Commit c0173ba7 authored by Stephen Morris's avatar Stephen Morris
Browse files

[4088] Miscellaneous edits to the developer documentation

parent d6178bcf
......@@ -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.
*/
\ No newline at end of file
*/
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment