\section intro_commands Implementing console/config commands
- \seechapter \ref console_commands
+ \seechapter \ref console_commands \n
+ \seechapter \ref senf::console::factory
The console/config language does not define, how arguments are passed to the commands, it just
tokenizes the input and passes the tokens to the commands which then handle the
Options can be abbreviated at each directory boundary: A command <tt>/foo/bar/do</tt> can be
called as <tt>--f-b-d</tt> as long as this name is unique.
- Everything after the first '=' character is parsed into argument tokens using the normal
- config/console parser. If the option has no '=' character, the list of argument tokens will be
- empty.
+ Everything after the first '=' character is passed as arguments to the command. The exact
+ interpretation depends on the command:
+ \li If the command only takes a single token as argument (e.g. a single string or numeric
+ value), everything after the '=' sign is parsed into a single token (e.g. see rows 2 and 3
+ of the following table).
+ \li In all other cases, the string after the '=' sign is parsed into argument tokens using the
+ config/console parser. In this case, quoted strings need to be quoted twice, once for the
+ shell and once for the config/console parser (e.g. see rows 4 and 5 of the following table).
+ \li If the option has no '=' character, the list of argument tokens will be empty (e.g. see row
+ 1 of the following table)
+
+ Without these rules, multi-word string arguments would \e always have to be quoted twice (for
+ the shell and the config/console parser).
<table style="font-size:80%" class="senf">
<tr><th>Command</th><th>File syntax</th><th>Option syntax</th></tr>
<tr>
<td><tt>void doo(std::string const &)</tt></td>
- <td><tt>/path/to/doo "some test";</tt></td>
- <td><tt>--path-to-doo='"some text"'</tt></td>
+ <td><tt>/path/to/doo "some text";</tt></td>
+ <td><tt>--path-to-doo="some text"</tt></td>
</tr>
<tr>
<td><tt>/path/to/doo take 1;</tt></td>
<td><tt>--path-to-doo="take 1"</tt></td>
</tr>
- </table>
- The last column is additionally quoted using standard \c sh quoting: quotes in arguments need to
- be additionally quoted for the shell.
+ <tr>
+ <td><tt>void doo(std::string const &, int)</tt></td>
+ <td><tt>/path/to/doo "take two" 1;</tt></td>
+ <td><tt>--path-to-doo='"take two" 1'</tt></td>
+ </tr>
+ </table>
Short options are registered as aliases for long options. They can be registered with or without
an implied parameter and can optionally take a parameter. so after
$ program --mycommand="2 3" --mycommand="4 5"
</pre>
- (Beware, that the second argument to \c alias() is \e not shell quoted).
+ (Beware, that the second argument to \c alias() must \e not be shell quoted).
\subsection console_access_root Changing the root node
Depending on the object added, you can also bind to a more specific node type
(e.g. senf::console::SimpleCommand) if you know the type of node returned.
- Depending on the type of object added, there are additional attributes which can be set. These
- attributes are always set by calling them on the factory return value. It is \e not guaranteed,
- you can call these members on the node reference returned by the \c add() call.
+ Nodes are always added using a factory from the senf::console::factory namespace. The factory
+ has additional (type specific) attributes. These attributes are set by calling member functions
+ called 'attributors' on the temporary factory instance. It is \e not guaranteed, you can call
+ these members on the node reference returned by the \c add() call.
\code
namespace fty = senf::console::factory;
- dir.add("name", fty::Command(callback)
- .doc("The documentation") );
+ dir.add("name", fty::Command(callback) .doc("The documentation") );
\endcode
sets the \e doc attribute (if that is available, otherwise this will fail to compile).
+ \see senf::console::factory for a list of all node factories.
\section console_manualparse Manually parsing command arguments
\endhtmlonly
As you can see above, the arguments and tokens are returned as <a
- href="http://www.boost.org/doc/libs/1_33_1/libs/range/doc/utility_class.html#iter_range">
+ href="http://www.boost.org/doc/libs/release/libs/range/doc/html/range/reference/utilities/iterator_range.html">
boost::iterator_range</a> instances. These behave much like containers: They have \c begin() and
\c end() and some other useful members.
// compile-command: "scons -u test"
// mode: auto-fill
// End:
-
projects / senf.git / blobdiff