-help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
+.. _grouping options into categories:
+
Grouping options into categories
--------------------------------
.. code-block:: c++
- cl::opt<**bool**> Quiet("quiet");
+ cl::opt<bool> Quiet("quiet");
.. _cl::desc(...):
* The **cl::desc** attribute specifies a description for the option to be
- shown in the ``-help`` output for the program.
+ shown in the ``-help`` output for the program. This attribute supports
+ multi-line descriptions with lines separated by '\n'.
.. _cl::value_desc:
classes: `cl::opt`_, `cl::list`_, and `cl::alias`_. This section describes
these three classes in detail.
+.. _cl::getRegisteredOptions:
+
+The ``cl::getRegisteredOptions`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::getRegisteredOptions`` function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in ``-help`` can be modified prior to calling `cl::ParseCommandLineOptions`_.
+Note this method should not be called during any static initialisation because
+it cannot be guaranteed that all options will have been initialised. Hence it
+should be called from ``main``.
+
+This function can be used to gain access to options declared in libraries that
+the tool writter may not have direct access to.
+
+The function retrieves a :ref:`StringMap <dss_stringmap>` that maps the option
+string (e.g. ``-help``) to an ``Option*``.
+
+Here is an example of how the function could be used:
+
+.. code-block:: c++
+
+ using namespace llvm;
+ int main(int argc, char **argv) {
+ cl::OptionCategory AnotherCategory("Some options");
+
+ StringMap<cl::Option*> Map;
+ cl::getRegisteredOptions(Map);
+
+ //Unhide useful option and put it in a different category
+ assert(Map.count("print-all-options") > 0);
+ Map["print-all-options"]->setHiddenFlag(cl::NotHidden);
+ Map["print-all-options"]->setCategory(AnotherCategory);
+
+ //Hide an option we don't want to see
+ assert(Map.count("enable-no-infs-fp-math") > 0);
+ Map["enable-no-infs-fp-math"]->setHiddenFlag(cl::Hidden);
+
+ //Change --version to --show-version
+ assert(Map.count("version") > 0);
+ Map["version"]->setArgStr("show-version");
+
+ //Change --help description
+ assert(Map.count("help") > 0);
+ Map["help"]->setDescription("Shows help");
+
+ cl::ParseCommandLineOptions(argc, argv, "This is a small program to demo the LLVM CommandLine API");
+ ...
+ }
+
+
.. _cl::ParseCommandLineOptions:
The ``cl::ParseCommandLineOptions`` function
.. code-block:: c++
- struct FileSizeParser : public cl::basic_parser<unsigned> {
+ struct FileSizeParser : public cl::parser<unsigned> {
// parse - Return true on error.
- bool parse(cl::Option &O, const char *ArgName, const std::string &ArgValue,
+ bool parse(cl::Option &O, StringRef ArgName, const std::string &ArgValue,
unsigned &Val);
};
-Our new class inherits from the ``cl::basic_parser`` template class to fill in
+Our new class inherits from the ``cl::parser`` template class to fill in
the default, boiler plate code for us. We give it the data type that we parse
into, the last argument to the ``parse`` method, so that clients of our custom
parser know what object type to pass in to the parse method. (Here we declare
.. code-block:: c++
- bool FileSizeParser::parse(cl::Option &O, const char *ArgName,
+ bool FileSizeParser::parse(cl::Option &O, StringRef ArgName,
const std::string &Arg, unsigned &Val) {
const char *ArgStart = Arg.c_str();
char *End;
OPTIONS:
-help - display available options (-help-hidden for more)
...
- -max-file-size=<size> - Maximum file size to accept
+ -max-file-size=<size> - Maximum file size to accept
And we can test that our parse works correctly now (the test program just prints
out the max-file-size argument value):
.. _dynamically loaded options:
Dynamically adding command line options
+---------------------------------------
.. todo::