From bb37d0e1a52636dd987bee6e28d88cf52be54722 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 31 Aug 2024 16:23:16 +1000 Subject: [PATCH] Help: Improve grammar and wording for cmake_parse_arguments --- Help/command/cmake_parse_arguments.rst | 57 +++++++++++++------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 70dbeeb37e..746e1f1619 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -20,48 +20,49 @@ It processes the arguments given to that macro or function, and defines a set of variables which hold the values of the respective options. -The first signature reads processes arguments passed in the ``...``. +The first signature reads arguments passed in the ``...``. This may be used in either a :command:`macro` or a :command:`function`. .. versionadded:: 3.7 The ``PARSE_ARGV`` signature is only for use in a :command:`function` - body. In this case the arguments that are parsed come from the + body. In this case, the arguments that are parsed come from the ``ARGV#`` variables of the calling function. The parsing starts with the ````-th argument, where ```` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. -The ```` argument contains all options for the respective macro, -i.e. keywords which can be used when calling the macro without any value -following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` -command. +The ```` argument contains all options for the respective function +or macro. These are keywords that have no value following them, like the +``OPTIONAL`` keyword of the :command:`install` command. -The ```` argument contains all keywords for this macro -which are followed by one value, like e.g. ``DESTINATION`` keyword of the -:command:`install` command. +The ```` argument contains all keywords for this function +or macro which are followed by one value, like the ``DESTINATION`` keyword of +the :command:`install` command. The ```` argument contains all keywords for this -macro which can be followed by more than one value, like e.g. the +function or macro which can be followed by more than one value, like the ``TARGETS`` or ``FILES`` keywords of the :command:`install` command. .. versionchanged:: 3.5 - All keywords shall be unique. I.e. every keyword shall only be specified - once in either ````, ```` or + All keywords must be unique. Each keyword can only be specified + once in any of the ````, ````, or ````. A warning will be emitted if uniqueness is violated. When done, ``cmake_parse_arguments`` will consider for each of the -keywords listed in ````, ```` and -```` a variable composed of the given ```` -followed by ``"_"`` and the name of the respective keyword. These -variables will then hold the respective value from the argument list -or be undefined if the associated option could not be found. -For the ```` keywords, these will always be defined, -to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. +keywords listed in ````, ````, and +````, a variable composed of the given ```` +followed by ``"_"`` and the name of the respective keyword. For +```` and ````, these variables +will then hold the respective value(s) from the argument list, or be undefined +if the associated keyword was not given (policy :policy:`CMP0174` can also +affect the behavior for ````). For the ```` +keywords, these variables will always be defined, and they will be set to +``TRUE`` if the keyword is present, or ``FALSE`` if it is not. All remaining arguments are collected in a variable ``_UNPARSED_ARGUMENTS`` that will be undefined if all arguments were recognized. This can be checked afterwards to see -whether your macro was called with unrecognized parameters. +whether your macro or function was called with unrecognized parameters. .. versionadded:: 3.15 ```` and ```` that were given no @@ -96,7 +97,7 @@ Assume ``my_install()`` has been called like this: my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) -After the ``cmake_parse_arguments`` call the macro will have set or undefined +After the ``cmake_parse_arguments`` call, the macro will have set or undefined the following variables:: MY_INSTALL_OPTIONAL = TRUE @@ -111,14 +112,14 @@ the following variables:: You can then continue and process these variables. -Keywords terminate lists of values, e.g. if directly after a -``one_value_keyword`` another recognized keyword follows, this is -interpreted as the beginning of the new option. E.g. +Keywords terminate lists of values. If a keyword is given directly after a +````, that preceding ```` receives no +value and the keyword is added to the ``_KEYWORDS_MISSING_VALUES`` +variable. For the above example, the call ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in -``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added -to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will -therefore be set to ``TRUE``. +``MY_INSTALL_OPTIONAL`` being set to ``TRUE`` and ``MY_INSTALL_DESTINATION`` +being unset. The ``MY_INSTALL_KEYWORDS_MISSING_VALUES`` variable would hold +the value ``DESTINATION``. See Also ^^^^^^^^