X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Console%2FParse.hh;h=1dc749819d51b047fba613102f9805d5b07f0869;hb=9a782796586d1f6708e1baab64f2140c3c7972e8;hp=8684f800e8a2898817f89e3a7199a97774a99c52;hpb=2d5a1fd2cef2d84e16226a7336948f524fbb71c6;p=senf.git diff --git a/Console/Parse.hh b/Console/Parse.hh index 8684f80..1dc7498 100644 --- a/Console/Parse.hh +++ b/Console/Parse.hh @@ -26,6 +26,168 @@ #ifndef HH_Parse_ #define HH_Parse_ 1 +/** \defgroup console_parser The console/config parser + + The console/config library defines a simple language used to interact with the console or to + configure the application. The parser is not concerned about interpreting commands or + arguments, checking that a command exists or managing directories. The parser just takes the + input and parses it. + + \autotoc + + \section console_language The Language + + The config/console language is used in configuration files and interactively at the + console. Some features of the language are more useful in config files, others at the + interactive console but the language is the same in both cases. + + Let's start with a sample of the config/console language. The following is written as a + configuration file + \code + # My someserver configuration file + + /server/port 1234; + + /logger/targets { + console { + accept senf::log::Debug IMPORTANT; + accept server::ServerLog CRITICAL; + } + + provide serverlog senf::log::FileTarget "/var/log/server.log"; + serverlog { + reject senf::log::Debug senf::Console::Server NOTICE; + accept senf::log::Debug NOTICE; + accept server::ServerLog; + } + } + + /server/stuffing (UDPPacket x"01 02 03 04"); + /server/allow_hosts 10.1.2.3 # our internal server + 10.2.3.4 10.4.3.5 # client workstations + ; + + /help/infoUrl "http://senf.j32.de/src/doc"; + \endcode + + The interactive syntax is the same with some notes: + \li All commands must be complete on a single line. This includes grouping constructs which must + be closed on the same line they are opened. + \li The last ';' is optional. However, multiple commands may be entered on a single line when + they are separated by ';'. + \li An empty line on the interactive console will repeat the last command. + + The language consists of a small number of syntactic entities: + + \subsection console_special_chars Special characters + + These are characters, which have a special meaning. Some are used internally, others are just + returned as punctuation tokens + + + + + + + +
/path component separator
( )argument grouping
{ }directory grouping
;command terminator
, =punctuation tokens
+ + \subsection console_basic Basic elements + + A word is \e any sequence of consecutive characters which does not include any special + character. Examples for words are thus + 
+    12.34
+    jens@fokus.fraunhofer.de
+    eth0
+    1>2
+
+ + The following are \e not valid words: + 
+    a/b/c
+    a,b
+
+ + A string literal is just that: A double-quoted string (C/C++ style) possibly with + embedded escape chars: + 
+    "\"foo\nbar\""
+    "\x04test"
+
+ + A hex-string literal is used to represent binary data. It looks like a string which has + only hexadecimal bytes or whitespace as contents (comments and newlines are Ok when not read + from the interactive console) + 
+    x"01 02 03 0405"
+    x"01 02   # ID header
+      0405    # payload
+      "
+
+ + A token is a \e word, \e string or \e hex-string, or a single special character (that's + true, any special character is allowed as a token). '(' and ')' must be properly nested. + + A path is a sequence of \e words separated by '/' (and optional whitespace). A path may + have an optional initial and/or a terminating '/'. + 
+    a/b/c
+    foo / bar /
+    /server
+
+ + \subsection console_statements Statements + + There are several types of statements: + \li The bulk of all statements are \e path statements + \li There are some \e built-in statements which are mostly useful at the interactive console + \li A special form of statement is the directory group + + A path statement consists of a (possibly relative) path followed by any number of + arguments and terminated with a ';' (or end-of-input) + 
+    /path/to/command arg1 "arg2" (complex=(1 2) another) ;
+
+ Every argument is either + \li A single word, string or hex-string + \li or a parenthesized list of tokens. + + So above command has three arguments: 'arg1', 'arg2' (a single token each) and one argument with + the 7 tokens 'complex', '=', '(', '1', '2', ')', 'another'. The interpretation of the arguments + is completely up to the command. + + A built-in statement is one of + + + + + + +
\c cd \e pathChange current directory
\c ls [ \e path ]List contents of \e path or current directory
\c exitExit interactive console
\c help [ \e path ]Show help for \e path or current directory
+ + A directory group statement is a block of statements all executed relatively to a fixed + directory. + 
+    /some/path {
+        statement ;
+        . . .
+    }
+
+ At the beginning of the block, the current directory is saved and the directory is changed to + the given directory. All commands are executed and at the end of the block, the saved directory + is restored. + + \section console_parse_api The parser API + + The senf::console::CommandParser is responsible for taking text input and turning it into a + sequence of senf::console::ParseCommandInfo structures. The structures are returned by passing + them successively to a callback function. + + Every statement is returned as a senf::console::ParseCommandInfo instance. Directory groups are + handled specially: They are divided into two special built-in commands called PUSHD and POPD. + */ + // Custom includes #include #include @@ -46,6 +208,8 @@ namespace console { All command arguments are split into tokens by the parser. Each token is returned as an ArgumentToken instance. + + \ingroup console_parser */ class ArgumentToken { @@ -69,10 +233,12 @@ namespace console { taken from the parser, no semantic information is attached at this point, the config/console is not involved in any why. ParseCommandInfo consist of - \li the type of command: builtin or normal command represented by a possibly relative path + \li the type of command: built-in or normal command represented by a possibly relative path into the command tree. \li the command \li the arguments. Every argument consists of a range of ArgumentToken instances. + + \ingroup console_parser */ class ParseCommandInfo { @@ -106,9 +272,9 @@ namespace console { BuiltinCommand builtin() const; ///< Command type /**< \returns \c NoBuiltin, if the command is an ordinary - command, otherwise the id of the builtin command */ + command, otherwise the id of the built-in command */ CommandPathRange commandPath() const; ///< Command path - /**< This is the path to the command if it is not a builtin + /**< This is the path to the command if it is not a built-in command. Every element of the returned range constitutes one path element. If the first element is empty, the path is an absolute path, otherwise it is @@ -116,7 +282,7 @@ namespace console { path ends in a '/' char. */ ArgumentsRange arguments() const; ///< Command arguments /**< The returned range contains one token range for each - agument. */ + argument. */ TokensRange tokens() const; ///< All argument tokens /**< The returned range contains \e all argument tokens in a single range not divided into separate arguments. */ @@ -165,6 +331,8 @@ namespace console { needs to be analyzed before this is viable. \todo Implement more detailed error reporting and error recovery. + + \ingroup console_parser */ class CommandParser : boost::noncopyable