\autotoc
+
\section console_intro Introduction
There are three parts to the Config/console library:
commands which set their respective parameter, however the library allows commands to do much
more than just that.
+
\section console_example Example
The following example shows a \e very short summary on how to integrate the config/console
.name("someServer");
// Run the scheduler
- senf::Scheduler::instance().process();
+ senf::scheduler::process();
}
\endcode
\see \ref console_testserver for a complete example application
- \section intro_usage Access
+
+ \section intro_usage Using the Console: Configuration files, Network console, ...
There are several ways to access the node tree:
\li By parsing configuration files
\li By parsing command line parameters
- \li By providing interactive console access
+ \li By providing interactive or non-interactive network console access
\see console_access
+
\section intro_nodes The node tree
The basic idea is, that the console/config library manages a directory structure of parameters
\see \ref node_tree
- \section intro_commands Registering console/config commands
+ \section intro_commands Implementing console/config commands
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
\autotoc
+
\section console_access_config Configuration support
The configuration support of the Console/Config library revolves around the ConfigSource
node used during parsing and it is also possible to restrict parsing to a command subset. See
\ref console_access_partial.
+
\subsection console_access_file Configuration files
<table class="senf fixedwidth">
and a user specific configuration file) see \ref console_access_multiple and add one (or more)
senf::console::FileConfig() source to a senf::console::ConfigBundle.
+
\subsubsection console_access_file_syntax Configuration file syntax
Configuration files are written in a simple configuration language. This language is almost
\see \ref console_parser
+
\subsection console_access_options Command line options
<table class="senf fixedwidth">
See \ref senf::console::ProgramOptions for the source specific additional parameters. These
apply to senf::console::ProgramOptions and to the senf::console::OptionsConfig() source.
+
\subsubsection console_access_options_syntax Options syntax
Command line options are primarily parsed as long-options. Long options start with '--'. Further
(Beware, that the second argument to \c alias() is \e not shell quoted).
+
\subsection console_access_root Changing the root node
When used in it's default state, parsing will always interpret all commands relative to the
selectively choose commands from the node tree which are to be made accessible for
configuration. See \ref node_tree.
+
\subsection console_access_partial Partial / incremental configuration
Another feature provided by senf::console::ConfigBundle and all helper classes is partial
\code
// Create a console/config aware object and place it into the node tree
FooObject foo;
- senf::console::add("foo", foo.dir);
+ senf::console::root().add("foo", foo.dir);
// Open configuration file
senf::console::ConfigFile cf ("/etc/myserver.conf");
important: It allows a subsystem to parse it's configuration parameters irrespective of any
links pointing to nodes of that subsystem.
+
\subsection console_access_multiple Multiple sources
Most of the time, an application will utilize multiple configuration sources: A global
order they are specified, so in this case, the command line options will override any options
specified in one of the configuration files.
- \section console_access_console The interactive console
- To make the console accessible, it must be initialized when the program is started:
+ \section console_access_console The network console
+
+ To make the network console accessible, it must be initialized when the program is started:
\code
#include <senf/Console.hh>
.name("myserver");
// You need to enter the scheduler main-loop for the server to work
- senf::Scheduler::instance().process();
+ senf::scheduler::process();
// Alternatively enter the main-loop via the PPI
// senf::ppi::run();
</pre>
\endhtmlonly
+ It is possible to start multiple server consoles by calling \c start() multiple times with
+ different ports/addresses. Each server can be configured separately (e.g. root node, mode ...).q
+
+
\subsection console_serverclient Server and Client objects
The senf::console::Server and senf::console::Client objects offer further API calls. To access
members</a> for the Client API
- \subsection console_shell Features of the interactive console shell
+ \subsection console_shell The interactive console shell
The interactive shell will use the GNU readline library for the first connected
instance. Further users will not have access to this functionality since GNU readline is
- completely non-reentrant.
+ completely non-reentrant. GNU readline supports history and some command keys (like C-d for \c
+ exit or C-c to clear and restart the input).
The shell supports auto-cd and auto-completion: If you enter the name of a directory at the
prompt, the console will change to that directory. With auto-completion, any unique beginning of
- a path component will be completed automatically and transparently to th corresponding full
+ a path component will be completed automatically and transparently to the corresponding full
name.
+
+ \subsection console_noninteractive Non-interactive network console
+
+ After a new connection is established, the console server waits a short time for data to arrive.
+ arrive. Only if nothing happens in the first 500ms, readline is initialized (if available) and
+ the interactive prompt is displayed.
+
+ By sending data immediately after opening the connection, the console is switched into
+ non-interactive mode. In this mode, no prompt is displayed. In this mode, commands are \e not
+ terminated automatically by end-of-line (CR). This allows, to easily cat an arbitrary
+ configuration file into the network console using netcat:
+
+ <pre>
+ $ nc -q1 localhost 23232 < some.conf
+ </pre>
+
+ The argument <tt>-q1</tt> makes netcat close the sending end of the connection on EOF and wait
+ up to 1 second for the console to terminate. Even better, use \c netcat6, which has full TCP
+ half-close support.
+
+ <pre>
+ $ echo "ls" | nc6 --half-close localhost 23232 2>/dev/null
+ console/
+ server/
+ test/
+ $
+ </pre>
+
+ Commands are executed as soon as the terminating character (';', '{' or '}') is received or when
+ the sending end of the connection is closed.
*/
/** \defgroup console_commands Supported command types
\autotoc
+
\section console_cmdadd Adding commands and setting attributes
Basically, all commands are added using senf::console::DirectoryNode::add(). What exactly
To greatly simplify parsing complex commands, we turn to automatic argument parsing.
+
\subsection console_autoadd Adding
Automatically parsed commands are registered by just adding a callback which has the correct
</pre>
\endhtmlonly
+
\subsection command_overload Overloading
Automatically parsed commands can be overloaded: You can register multiple commands under the
\see senf::console::VariableAttributor for the complete attribute interface
+
\subsection console_varchange Change notification
A \e handler can be set to be called, whenever the variable is changed. It will be called with a
After this setup, \c varChanged will be called, whenever the value has changed.
- \section console_args Registering special argument types
+ \section console_args Special argument types
By default, argument types which can be read and written using \c iostreams are automatically
supported. Other types need to be registered explicitly
+ \subsection console_args_bool Boolean arguments and return values
+
+ The console library by default formats boolean values using the strings \c true and \c false for
+ their representation. When parsing a boolean value, most sensible representations will be
+ accepted:
+
+ <table class="senf">
+ <tr><td>\c true</td> <td>\c false</td> <td>\ref senf::console::formatTrueFalse</td></tr>
+ <tr><td>\c on</td> <td>\c off</td> <td>\ref senf::console::formatOnOff</td></tr>
+ <tr><td>\c enabled</td> <td>\c disabled</td> <td>\ref senf::console::formatEnabledDisabled</td></tr>
+ <tr><td>\c yes</td> <td>\c no</td> <td>\ref senf::console::formatYesNo</td></tr>
+ <tr><td><em>non-zero integer</em></td><td>\c 0</td><td>\ref senf::console::formatOneZero</td></tr>
+ </table>
+
+ The boolean parser will accept these values in any (mixed) case and accepts any unique initial
+ substring (e.g. \c Y / \c N).
+
+ The last column lists explicit formatters which can be set to customize the return value
+ formatting of a registered overload accordingly.
+
+
\subsection console_args_enum Registering enum types
Enum types are a special case, since it is not possible, to find a string representation for the
\endhtmlonly
- \subsection console_args_custom Customizing argument and return value parsing/formatting
+ \subsection console_args_custom Extending the library to support additional types
To support or customize parsing/formatting of other types, they need to be registered. In it's
simplest case, this works, by just providing an appropriate overload for
projects / senf.git / blobdiff