cmake_parse_arguments: Add option to read arguments from ARGC/ARGV#

The `ARGC`/`ARGV#` variables in function scope hold the original
arguments with no ;-list flattening.  Add a way for functions to
cleanly parse arguments that may contain `;`.  This also avoids
extra copying of the arguments.

Co-Author: Brad King <brad.king@kitware.com>

2 files changed, 17 insertions, 0 deletions

diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst
index 6206611..ec4ffed 100644
--- a/Help/command/cmake_parse_arguments.rst
+++ b/Help/command/cmake_parse_arguments.rst
@@ -11,6 +11,17 @@ respective options.
   cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                         <multi_value_keywords> args...)
 
+  cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
+                        <multi_value_keywords>)
+
+The first signature reads processes arguments passed in the ``args...``.
+This may be used in either a :command:`macro` or a :command:`function`.
+
+The ``PARSE_ARGV`` signature is only for use in a :command:`function`
+body.  In this case the arguments that are parsed come from the
+``ARGV#`` variables of the calling function.  The parsing starts with
+the Nth argument, where ``N`` is an unsigned integer.  This allows for
+the values to have special characters like ``;`` in them.
 
 The ``<options>`` argument contains all options for the respective macro,
 i.e.  keywords which can be used when calling the macro without any value
diff --git a/Help/release/dev/parse_arguments_argv_n.rst b/Help/release/dev/parse_arguments_argv_n.rst
new file mode 100644
index 0000000..758b72a
--- /dev/null
+++ b/Help/release/dev/parse_arguments_argv_n.rst
@@ -0,0 +1,6 @@
+parse_arguments_argv_n
+----------------------
+
+* The :command:`cmake_parse_arguments` command gained a new
+  mode to read arguments directly from ``ARGC`` and ``ARGV#``
+  variables inside a :command:`function` body.