This allows for parsing of contextual keywords. For example:
```
some_command(
ARG_WITH_CONTEXT foo
CONTEXT bar
ARG_WITH_CONTEXT quux)
```
will be able to store that `foo` happened without context (or, rather,
its default value) and `quux` was provided in a `bar` context.
Tweak cmArgumentParser to ignore positional arguments once a keyword
argument has been seen. This prevents mingling of keyword arguments
being able to effectively skip positional arguments, with later
arguments being picked up again; this seems highly likely to lead to
user confusion. This is also consistent with how other languages (e.g.
Python) handle a mix of "named" and positional arguments.
Some clients have been explicitly checking whether the string specified
after a keyword is empty. Offer them a way to specify that the string
must be non-empty as part of the binding type.
The `keywordsMissingValue` argument to `Parse()` is now needed only for
the `cmake_parse_arguments` result `_KEYWORDS_MISSING_VALUES`. Offer
its implementation a private binding for this. Our internal clients can
use `ArgumentParser::NonEmpty<>` and friends to enforce the presence of
values.
Since commit f46b2e9142 (cmArgumentParser: Model maybe-missing string
with wrapper type, 2022-07-06) we know during parsing whether or not it
is an error for a keyword to be missing a value. Record such errors in
the parse results structure. Offer clients a helper method to report
them. This provides clients with an alternative to manually checking
`keywordsMissingValue` and generating their own error message.
Create a way for the parser to record errors or incidental information
about the argument parsing operation that clients can inspect afterward.
Offer clients a way to hold the structure as part of their arguments
structure.
Bindings to `std::string` require one value. Some clients have been
filtering `keywordsMissingValue` to support keywords that tolerate a
missing value. Offer them a type-safe way to achieve this instead.
Previously bindings to `std::vector<std::string>` required at least one
value. Some clients have been filtering `keywordsMissingValue` to
support keywords followed by empty lists. Instead, require clients to
specify whether a keyword's list can be empty as part of the binding
type.
Several clients have been using `keywordsMissingValue` or
`parsedKeywords` to check for the presence of keywords. Offer them a
type-encoded way to explicitly check whether a keyword is present.
#pragma once is a widely supported compiler pragma, even though it is
not part of the C++ standard. Many of the issues keeping #pragma once
from being standardized (distributed filesystems, build farms, hard
links, etc.) do not apply to CMake - it is easy to build CMake on a
single machine. CMake also does not install any header files which can
be consumed by other projects (though cmCPluginAPI.h has been
deliberately omitted from this conversion in case anyone is still using
it.) Finally, #pragma once has been required to build CMake since at
least August 2017 (7f29bbe6 enabled server mode unconditionally, which
had been using #pragma once since September 2016 (b13d3e0d)). The fact
that we now require C++11 filters out old compilers, and it is unlikely
that there is a compiler which supports C++11 but does not support
#pragma once.
Provide a standardized way to handle the C++ "standard" headers
customized to be used with current CMake C++ standard constraints.
Offer under directory `cm` headers which can be used as direct
replacements of the standard ones. For example:
#include <cm/string_view>
can be used safely for CMake development in place of the `<string_view>`
standard header.
Fixes: #19491
