|
@@ -15,49 +15,53 @@
|
|
|
/**
|
|
|
@page dhcpEval libeval - Expression evaluation and client classification
|
|
|
|
|
|
+ @section dhcpEvalIntroduction Introduction
|
|
|
+
|
|
|
The core of the libeval library is a parser that is able to parse an
|
|
|
expression (e.g. option[123] == 'APC'). This is currently used for client
|
|
|
classification, but in the future may be also used for other applications.
|
|
|
- The external interface to the library is @ref isc::eval::EvalContext class.
|
|
|
- Once instantiated, it offers two major methods:
|
|
|
- @ref isc::eval::EvalContext::parseFile that parses content of the file
|
|
|
- and @ref isc::eval::EvalContext::parseString, which parses specified string.
|
|
|
- Once expression is parsed, it is converted to a collection of tokens
|
|
|
- that are stored in Reverse Polish Notation in EvalContext::expression.
|
|
|
-
|
|
|
- Internally, the parser code is generated by flex and bison. Those two
|
|
|
+
|
|
|
+ The external interface to the library is the @ref isc::eval::EvalContext
|
|
|
+ class. Once instantiated, it offers two major methods:
|
|
|
+ @ref isc::eval::EvalContext::parseFile whch parses the content of a file
|
|
|
+ and @ref isc::eval::EvalContext::parseString, which parses the specified
|
|
|
+ string. Once the expression is parsed, it is converted to a collection of
|
|
|
+ tokens that are stored in Reverse Polish Notation in
|
|
|
+ EvalContext::expression.
|
|
|
+
|
|
|
+ Internally, the parser code is generated by flex and bison. These two
|
|
|
tools convert lexer.ll and parser.yy files into a number of .cc and .hh files.
|
|
|
- To avoid adding flex and bison as dependencies, the result of the
|
|
|
- generation is checked into the github repository and is distributed in the
|
|
|
- tarballs.
|
|
|
+ To avoid a build of Kea depending on the presence of flex and bison, the
|
|
|
+ result of the generation is checked into the github repository and is
|
|
|
+ distributed in the tarballs.
|
|
|
|
|
|
@section dhcpEvalLexer Lexer generation using flex
|
|
|
|
|
|
- Flex is used to generate lexer, a piece of code that converts input
|
|
|
+ Flex is used to generate the lexer, a piece of code that converts input
|
|
|
data into a series of tokens. It contains a small number of directives,
|
|
|
- but the majority of the code consists of a definition of tokens. These
|
|
|
- are regular expressions that define various tokens, e.g. strings,
|
|
|
+ but the majority of the code consists of the definitions of tokens. These
|
|
|
+ definitions are regular expressions that define various tokens, e.g. strings,
|
|
|
numbers, parentheses, etc. Once the expression is matched, the associated
|
|
|
- action is executed. In majority of the cases a generator method from
|
|
|
- @ref isc::eval::EvalParser is called. It returns newly created
|
|
|
- bison tokens. The purpose of the lexer is to generate a stream
|
|
|
+ action is executed. In the majority of the cases a generator method from
|
|
|
+ @ref isc::eval::EvalParser is called, which returns returns a newly created
|
|
|
+ bison token. The purpose of the lexer is to generate a stream
|
|
|
of tokens that are consumed by the parser.
|
|
|
|
|
|
- lexer.cc and lexer.hh files must not be edited. In case there is a need
|
|
|
+ lexer.cc and lexer.hh must not be edited. If there is a need
|
|
|
to introduce changes, lexer.ll must be updated and the .cc and .hh files
|
|
|
regenerated.
|
|
|
|
|
|
@section dhcpEvalParser Parser generation using bison
|
|
|
|
|
|
- Bison is used to generate parser, a piece of code that consumes a
|
|
|
- stream of tokens and attempts to match it against defined grammar.
|
|
|
- Bison parser is created from the parser.yy file. It contains
|
|
|
+ Bison is used to generate the parser, a piece of code that consumes a
|
|
|
+ stream of tokens and attempts to match it against a defined grammar.
|
|
|
+ The bison parser is created from parser.yy. It contains
|
|
|
a number of directives, but the two most important sections are:
|
|
|
- a list of tokens (for each token defined here, bison will generate
|
|
|
- make_NAMEOFTOKEN method in @ref isc::eval::EvalParser class) and
|
|
|
- the grammar. Grammar is a tree like structure with possible loops.
|
|
|
+ a list of tokens (for each token defined here, bison will generate the
|
|
|
+ make_NAMEOFTOKEN method in the @ref isc::eval::EvalParser class) and
|
|
|
+ the grammar. The Grammar is a tree like structure with possible loops.
|
|
|
|
|
|
- Here's an over simplified version of the grammar:
|
|
|
+ Here is an over-simplified version of the grammar:
|
|
|
|
|
|
@code
|
|
|
01. %start expression;
|
|
@@ -79,22 +83,23 @@
|
|
|
|
|
|
This code determines that the grammar starts from expression (line 1).
|
|
|
The actual definition of expression (lines 3-5) may either be a
|
|
|
-single token or an expression token equals token. Token is further
|
|
|
+single token or an expression "token == token" (EQUAL has been defined as
|
|
|
+"==" elsewhere). Token is further
|
|
|
defined in lines 7-15: it may either be a string (lines 8-11) or option
|
|
|
-(lines 12-15). When the actual case is defined, respective C++ action
|
|
|
-is executed. For example, TokenString class is instantiated with
|
|
|
-appropriate values and put onto the expression vector.
|
|
|
+(lines 12-15). When the actual case is determined, the respective C++ action
|
|
|
+is executed. For example, if the token is a string, the TokenString class is
|
|
|
+instantiated with the appropriate value and put onto the expression vector.
|
|
|
|
|
|
@section dhcpEvalMakefile Generating parser files
|
|
|
|
|
|
- In general case, we do want to avoid generating parser files, so an
|
|
|
+ In the general case, we want to avoid generating parser files, so an
|
|
|
average user interested in just compiling Kea would not need flex or
|
|
|
bison. Therefore the generated files are already included in the
|
|
|
git repository and will be included in the tarball releases.
|
|
|
|
|
|
However, there will be cases when one of the developers would want
|
|
|
to tweak the lexer.ll and parser.yy files and then regenerate
|
|
|
- the code. For this purpose, two makefile targets were defined:
|
|
|
+ the code. For this purpose, two makefile targets are defined:
|
|
|
@code
|
|
|
make parser
|
|
|
@endcode
|
|
@@ -103,16 +108,16 @@ appropriate values and put onto the expression vector.
|
|
|
make parser-clean
|
|
|
@endcode
|
|
|
will remove the files. Generated files removal was also hooked
|
|
|
- into maintainer-clean target.
|
|
|
+ into the maintainer-clean target.
|
|
|
|
|
|
@section dhcpEvalConfigure Configure options
|
|
|
|
|
|
Since the flex/bison tools are not necessary for a regular compilation,
|
|
|
- there are checks conducted during configure, but lack of flex or
|
|
|
+ checks conducted during configure, but the lack of flex or
|
|
|
bison tools does not stop the configure process. There is a flag
|
|
|
- \--enable-generate-parser that tells configure script that the
|
|
|
+ (--enable-generate-parser) that tells configure script that the
|
|
|
parser will be generated. With this flag, the checks for flex/bison
|
|
|
- are mandatory. Any missing or too old flex/bison will cause an
|
|
|
- error.
|
|
|
+ are mandatory. If either tool is missing or at too early a version, the
|
|
|
+ configure process will terminate with an error.
|
|
|
|
|
|
-*/
|
|
|
+*/
|