From 6cc39ef5d59bbca7abc7053ce46e06c6d0eeb8bb Mon Sep 17 00:00:00 2001
From: Manuel Weberndorfer <manuel.weberndorfer@id.ethz.ch>
Date: Mon, 9 Nov 2020 12:25:26 +0000
Subject: [PATCH] add cmdline documentation
---
cmdline/README.rst | 156 +++++++++++++++++++++++++++++++++++++++
docs/build_documentation | 2 +
docs/index.rst | 1 +
3 files changed, 159 insertions(+)
create mode 100644 cmdline/README.rst
diff --git a/cmdline/README.rst b/cmdline/README.rst
new file mode 100644
index 00000000..84e099b6
--- /dev/null
+++ b/cmdline/README.rst
@@ -0,0 +1,156 @@
+..
+ © 2020 ETH Zurich, Mechanics and Materials Lab
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+The CmdLine Library
+===================
+
+Introduction
+------------
+
+This library assists with reading parameters from the command line.
+It supports different types of arguments, including floating point numbers, integers, and booleans.
+Moreover, it automatically generates a ``--help`` flag that provides custom information about the available flags.
+
+Tutorial
+--------
+
+To use this library, you only need to familiarize yourself with a single class.
+This class is called ``CommandLineOptionParser``.
+It's in the namespace ``ae108::cmdline``.
+
+.. doxygenclass:: ae108::cmdline::CommandLineOptionParser
+
+Example Setup
+^^^^^^^^^^^^^
+
+Let's try using this class in a simple example.
+
+.. code-block:: cpp
+
+ #include <ae108/cmdline/CommandLineOptionParser.h>
+ #include <iostream>
+
+ int main(const int argc, const char *const *const argv) {
+ /**
+ * @todo use command line options
+ */
+ }
+
+Construction
+^^^^^^^^^^^^
+
+To parse the command line parameters, we'll construct a ``CommandLineOptionParser`` by providing a stream.
+
+.. doxygenfunction:: ae108::cmdline::CommandLineOptionParser::CommandLineOptionParser
+
+Let's say we want to print error messages and warnings to ``stderr``.
+
+.. code-block:: cpp
+
+ namespace cmdline = ae108::cmdline;
+ cmdline::CommandLineOptionParser(std::cerr)
+ /**
+ * @todo define available options
+ */
+ ;
+
+Adding Options
+^^^^^^^^^^^^^^
+
+The only thing that is missing are the options that we would like to parse.
+In this example, we are going greet the world if greetings are enabled via a command line flag.
+The ``CommandLineOptionParser`` class provides a ``withOption`` method to add flags.
+
+In this example we'll add a flag ``--greet`` (with a short form ``-g``) together with a help text describing the flag.
+
+.. code-block:: cpp
+
+ auto enable_greeting = bool{false};
+ cmdline::CommandLineOptionParser(std::cerr)
+ .withOption("enable_greeting,g", "Print a greeting.", &enable_greeting)
+ .parse(argc, argv);
+
+ if (enable_greeting) {
+ std::cout << "Hello world!" << std::endl;
+ }
+
+Let's see it in action.
+
+.. code-block:: shell-session
+
+ $ cmdline/examples/ae108-CmdLineExample
+ $ cmdline/examples/ae108-CmdLineExample --enable_greeting=yes
+ Hello world!
+ $ cmdline/examples/ae108-CmdLineExample --enable_greeting=no
+ $ cmdline/examples/ae108-CmdLineExample -g yes
+ Hello world!
+
+As promised, there's also a ``--help`` flag:
+
+.. code-block:: shell-session
+
+ $ cmdline/examples/ae108-CmdLineExample --help
+ Command line options:
+ -h [ --help ] Show this help.
+ -g [ --enable_greeting ] arg Print a greeting.
+
+Moreover, a warning message is printed out to ``stderr`` if an unknown flag is used.
+
+.. code-block:: shell-session
+
+ $ cmdline/examples/ae108-CmdLineExample --unknown_flag=123
+ Warning: The following options were not recognized by cmdline: '--unknown_flag=123'.
+
+Most importantly, invalid command line parameters are rejected with a suitable error message.
+
+.. code-block:: shell-session
+
+ $ cmdline/examples/ae108-CmdLineExample --enable_greeting=123
+ the argument ('123') for option '--enable_greeting' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'
+
+Example Source Code
+^^^^^^^^^^^^^^^^^^^
+
+The full source code of the example is available in ``cmdline/examples/Example.cc``.
+If you want to build it and try it out, the executable target is called ``ae108-CmdLineExample``.
+
+Outlook
+-------
+
+We've seen many of the features in action, but there's a bit more to explore.
+For instance, it's possible to chain more than one call to ``withOption``:
+
+.. code-block:: cpp
+
+ cmdline::CommandLineOptionParser(std::cerr)
+ .withOption(/* ... */)
+ .withOption(/* ... */)
+ .parse(argc, argv);
+
+Also, there is another overload of ``withOption`` that permits to add flags without a help text.
+
+Interface Documentation
+^^^^^^^^^^^^^^^^^^^^^^^
+
+For reference, here's the documentation of the full interface of the ``CommandLineOptionParser`` class.
+
+.. doxygenclass:: ae108::cmdline::CommandLineOptionParser
+ :members:
+
+Tests
+^^^^^
+
+Finally, feel free to check out the tests in ``cmdline/test/CommandLineOptionParser_Test.cc``.
+They showcase the features of the library in many common use cases.
diff --git a/docs/build_documentation b/docs/build_documentation
index 4d097d33..d2ebff73 100755
--- a/docs/build_documentation
+++ b/docs/build_documentation
@@ -23,6 +23,7 @@ ROOT_DIRECTORY=$(readlink -e $(dirname "$0"))/..
echo GENERATE_LATEX=NO; \
echo GENERATE_XML=YES; \
echo INPUT="$ROOT_DIRECTORY/cmdline/src/include" \
+ "$ROOT_DIRECTORY/cmdline/examples" \
"$ROOT_DIRECTORY/cpppetsc/src/include" \
"$ROOT_DIRECTORY/assembly/src/include" \
"$ROOT_DIRECTORY/solve/src/include"; \
@@ -52,6 +53,7 @@ pandoc \
-t rst \
"$ROOT_DIRECTORY/README.md"
cp "$ROOT_DIRECTORY/docs/index.rst" source/index.rst
+cp "$ROOT_DIRECTORY/cmdline/README.rst" source/Cmdline.rst
make -j$(nproc) html
make -j$(nproc) latexpdf
diff --git a/docs/index.rst b/docs/index.rst
index a2966120..bb2df9f1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,3 +18,4 @@ Welcome to AE108!
.. toctree::
Getting Started <README.rst>
+ Cmdline.rst
--
GitLab