Subject: [Boost-commit] svn:boost r54629 - in trunk/libs/spirit/doc: . qi
From: joel_at_[hidden]
Date: 2009-07-03 22:58:13
Author: djowel
Date: 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
New Revision: 54629
URL: http://svn.boost.org/trac/boost/changeset/54629
Log:
updates
Added:
trunk/libs/spirit/doc/qi/basics.qbk (contents, props changed)
Text files modified:
trunk/libs/spirit/doc/concepts_template.qbk | 34 ++--
trunk/libs/spirit/doc/qi.qbk | 9
trunk/libs/spirit/doc/qi/action.qbk | 4
trunk/libs/spirit/doc/qi/auxiliary.qbk | 4
trunk/libs/spirit/doc/qi/binary.qbk | 4
trunk/libs/spirit/doc/qi/char.qbk | 4
trunk/libs/spirit/doc/qi/concepts.qbk | 274 ++++++++++++++++++++++++++++++++++++++++
trunk/libs/spirit/doc/qi/directive.qbk | 4
trunk/libs/spirit/doc/qi/nonterminal.qbk | 4
trunk/libs/spirit/doc/qi/numeric.qbk | 4
trunk/libs/spirit/doc/qi/operator.qbk | 4
trunk/libs/spirit/doc/qi/quick_reference.qbk | 25 ---
trunk/libs/spirit/doc/qi/stream.qbk | 4
trunk/libs/spirit/doc/qi/string.qbk | 200 +++++++++++++++++++++++++++++
trunk/libs/spirit/doc/reference_template.qbk | 36 ++--
trunk/libs/spirit/doc/spirit2.qbk | 27 +++
16 files changed, 562 insertions(+), 79 deletions(-)
Modified: trunk/libs/spirit/doc/concepts_template.qbk
==============================================================================
--- trunk/libs/spirit/doc/concepts_template.qbk (original)
+++ trunk/libs/spirit/doc/concepts_template.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -1,46 +1,52 @@
-[/==============================================================================
- Copyright (C) 2001-2009 Joel de Guzman
- Copyright (C) 2001-2009 Hartmut Kaiser
-
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-===============================================================================/]
+[/------------------------------------------------------------------------------]
[section XXX]
[heading Description]
Description of XXX concept
+[heading Refinement of]
+
+[:Link to base concept]
+
[variablelist Notation
[[`xxx`] [An XXX]]
]
[heading Valid Expressions]
-(For any Forward Sequence the following expressions must be valid:)
+(For any XXX the following expressions must be valid:)
In addition to the requirements defined in _XXX-Basic_concept_, for any
XXX the following must be met:
[table
- [[Expression] [Semantics] [Return type] [Complexity]]
- [[`xxx`] [Semantics of `xxx`] [XXX] [Constant]]
+ [[Expression] [Semantics] [Return type]]
+ [[`xxx`] [Semantics of `xxx`] [XXX]]
]
-[heading Type Requirements]
+[heading Type Expressions]
[table
- [[Expression] [Requirements]]
- [[`xxx`] [Requirements for `xxx`]]
+ [[Expression] [Description]]
+ [[`XXX`] [Description of `XXX`]]
]
[heading Invariants]
For any XXX xxx the following invariants always hold:
+[heading Precondition]
+
+Prior to calling FOO the following preconditions should hold:
+
+[heading Precondition]
+
+Upon return from FOO the following postconditions should hold:
+
[heading Models]
Links to models of XXX concept
-[endsect]
+[endsect] [/ XXX Concept]
Modified: trunk/libs/spirit/doc/qi.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi.qbk (original)
+++ trunk/libs/spirit/doc/qi.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -1,5 +1,5 @@
[/==============================================================================
- Copyright (C) 2001-2009 Joel de Guzman
+ Copyright (C) 2001-2008 Joel de Guzman
Copyright (C) 2001-2009 Hartmut Kaiser
Distributed under the Boost Software License, Version 1.0. (See accompanying
@@ -27,12 +27,10 @@
[include qi/quick_reference.qbk]
[endsect]
-[/
[section Reference]
-[/section Concepts]
-[include qi/parser.qbk]
-[/endsect]
+[import ../example/qi/reference.cpp]
[include qi/concepts.qbk]
+[include qi/basics.qbk]
[include qi/action.qbk]
[include qi/auxiliary.qbk]
[include qi/binary.qbk]
@@ -44,7 +42,6 @@
[include qi/stream.qbk]
[include qi/string.qbk]
[endsect]
-]
[endsect]
Modified: trunk/libs/spirit/doc/qi/action.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/action.qbk (original)
+++ trunk/libs/spirit/doc/qi/action.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Action]
+[/ section Action]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/auxiliary.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/auxiliary.qbk (original)
+++ trunk/libs/spirit/doc/qi/auxiliary.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Auxiliary]
+[/ section Auxiliary]
-[endsect]
+[/ endsect]
Added: trunk/libs/spirit/doc/qi/basics.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/qi/basics.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -0,0 +1,45 @@
+[/==============================================================================
+ Copyright (C) 2001-2008 Joel de Guzman
+ Copyright (C) 2001-2008 Hartmut Kaiser
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+===============================================================================/]
+
+[section Basics]
+
+[heading Lazy Argument]
+
+Some parsers (e.g. primitives and non-terminals) may take in additional
+attributes. Such parsers take the form:
+
+ p(a1, a2,... aN)
+
+where `p` is a parser. Each of the arguments (a1...aN) can either be an
+immediate value, or a function, `f`, with signature:
+
+ T f(Unused, Context)
+
+where `T`, the function's return value, is compatible with the argument
+type expected and `Context` is the parser's __context__ type (The first
+argument is __unused__ to make the `Context` the second argument. This
+is done for uniformity with __actions__).
+
+[heading Character Encoding Namespace]
+
+Some parsers need to know which character set a `char` or `wchar_t` is
+operating on. For example, the `alnum` parser works differently with
+ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
+the parser with the character set.
+
+We have a namespace for each character set Spirit will be supporting.
+That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
+in the future, `unicode`). In each of the character encoding namespaces,
+we place tagged versions of parsers such as `alnum`, `space` etc.
+
+Example:
+
+ using boost::spirit::ascii::space; // use the ASCII space parser
+
+[endsect]
+
Modified: trunk/libs/spirit/doc/qi/binary.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/binary.qbk (original)
+++ trunk/libs/spirit/doc/qi/binary.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Binary]
+[/ section Binary]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/char.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/char.qbk (original)
+++ trunk/libs/spirit/doc/qi/char.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Char]
+[/ section Char]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/concepts.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/concepts.qbk (original)
+++ trunk/libs/spirit/doc/qi/concepts.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -8,6 +8,280 @@
[section Concepts]
+Spirit.Qi parsers fall into a couple of generalized concepts. The
+/Parser/ is the most fundamental concept. All Spirit.Qi parsers are
+models of the /Parser/ concept. /PrimitiveParser/, /UnaryParser/,
+/BinaryParser/ and /NaryParser/ are all refinements of the /Parser/
+concept.
+
+The following sections provide details on these concepts.
+
+[/------------------------------------------------------------------------------]
+[section Parser]
+
+[heading Description]
+
+The /Parser/ is the most fundamental concept. A Parser has a member
+function, `parse`, that accepts a first-last `ForwardIterator` pair and
+returns bool as its result. The iterators delimit the data being parsed.
+The Parser's `parse` member function returns `true` if the parse
+succeeds, in which case the first iterator is advanced accordingly. Each
+Parser can represent a specific pattern or algorithm, or it can be a
+more complex parser formed as a composition of other Parsers.
+
+[variablelist Notation
+ [[`p`] [A `Parser`.]]
+ [[`P`] [A `Parser` type.]]
+ [[`Iter`] [a `ForwardIterator` type.]]
+ [[`f`, `l`] [`ForwardIterator`. first/last iterator pair.]]
+ [[`Context`] [The parser's __context__ type.]]
+ [[`context`] [The parser's __context__, or __unused__.]]
+ [[`skip`] [A skip Parser, or __unused__.]]
+ [[`attr`] [A __compatible_atribute__, or __unused__.]]
+]
+
+[heading Valid Expressions]
+
+In the expressions below, the behavior of the parser, `p`, how `skip`
+and `attr` are handled by `p`, are left unspecified in the base `Parser`
+concept. These are specified in subsequent, more refined concepts and by
+the actual models therof.
+
+For any Parser the following expressions must be valid:
+
+[table
+ [[Expression] [Semantics] [Return type]]
+ [[
+``p.parse(f, l, context, skip, attr)``]
+ [Match the input sequence
+ starting from `f`. Return
+ `true` if successful, otherwise
+ return `false`.] [`bool`]]
+ [[`p.what(context)`] [Get information about a Parser.] [__info__]]
+]
+
+[heading Type Expressions]
+
+[table
+ [[Expression] [Description]]
+ [[`P::template attribute<Context, Iter>::type`] [The Parser's expected attribute.]]
+ [[`traits::is_parser<P>::type`] [Metafunction that evaluates to `mpl::true_` if
+ a certain type, `P` is a Parser, `mpl::false_`
+ otherwise (See __mpl_boolean_constant__).]]
+]
+
+[heading Postcondition]
+
+Upon return from `p.parse` the following post conditions should hold:
+
+* On a successful match, `f` is positioned one past the first
+ non-matching character/token.
+* On a failed match, if a `skip` parser is __unused__,
+ `f` is restored to its original position prior to entry.
+* On a failed match, if a `skip` parser is not __unused__,
+ `f` is positioned one past the first character/token not
+ matching `skip`.
+* On a failed match, `attr` is left untouched.
+* No post-skips: trailing `skip` characters/tokens will not be skipped.
+
+[heading Models]
+
+All parsers in Spirit.Qi are models of the /Parser/ concept.
+
+[endsect] [/ Parser Concept]
+
+[/------------------------------------------------------------------------------]
+[section PrimitiveParser]
+
+[heading Description]
+
+/PrimitiveParser/ is the most basic building block that the client uses
+to build more complex parsers.
+
+[heading Refinement of]
+
+[:__parser_concept__]
+
+[heading Pre-skip]
+
+Upon entry to the `parse` member function, a PrimitiveParser is required
+to do a pre-skip. Leading `skip` characters/tokens will be skipped prior
+to parsing. Only PrimitiveParsers are required to perform this pre-skip.
+This is typically carried out through a call to `qi::skip_over`:
+
+ qi::skip_over(f, l, skip);
+
+[heading Type Expressions]
+
+[table
+ [[Expression] [Description]]
+ [[`traits::is_primitive_parser<P>::type`] [Metafunction that evaluates to `mpl::true_` if
+ a certain type, `P`, is a PrimitiveParser, `mpl::false_`
+ otherwise (See __mpl_boolean_constant__).]]
+]
+
+[heading Models]
+
+Add links to /PrimitiveParser/ models here.
+
+[endsect] [/ PrimitiveParser Concept]
+
+[/------------------------------------------------------------------------------]
+[section UnaryParser]
+
+[heading Description]
+
+/UnaryParser/ is a composite parser that has a single subject. The
+UnaryParser may change the behavior of its subject following the
+__delegate_pattern__.
+
+[heading Refinement of]
+
+[:__parser_concept__]
+
+[variablelist Notation
+ [[`p`] [A UnaryParser.]]
+ [[`P`] [A UnaryParser type.]]
+]
+
+[heading Valid Expressions]
+
+In addition to the requirements defined in __parser_concept__, for any
+UnaryParser the following must be met:
+
+[table
+ [[Expression] [Semantics] [Return type]]
+ [[`p.subject`] [Subject parser.] [__parser_concept__]]
+]
+
+[heading Type Expressions]
+
+[table
+ [[Expression] [Description]]
+ [[`P::subject_type`] [The subject parser type.]]
+ [[`traits::is_unary_parser<P>::type`] [Metafunction that evaluates to `mpl::true_` if
+ a certain type, `P` is a UnaryParser, `mpl::false_`
+ otherwise (See __mpl_boolean_constant__).]]
+]
+
+[heading Invariants]
+
+For any UnaryParser, `P`, the following invariants always hold:
+
+* `traits::is_parser<P::subject_type>::type` evaluates to `mpl::true_`
+
+[heading Models]
+
+Links to models of UnaryParser concept
+
+[endsect] [/ UnaryParser Concept]
+
+[/------------------------------------------------------------------------------]
+[section BinaryParser]
+
+[heading Description]
+
+`BinaryParser` is a composite parser that has a two subjects, `left` and
+`right`. The BinaryParser allows its subjects to be treated in the same
+way as a single instance of a __parser_concept__ following the
+__composite_pattern__.
+
+[heading Refinement of]
+
+[:__parser_concept__]
+
+[variablelist Notation
+ [[`p`] [A BinaryParser.]]
+ [[`P`] [A BinaryParser type.]]
+]
+
+[heading Valid Expressions]
+
+In addition to the requirements defined in __parser_concept__, for any
+BinaryParser the following must be met:
+
+[table
+ [[Expression] [Semantics] [Return type]]
+ [[`p.left`] [Left parser.] [__parser_concept__]]
+ [[`p.right`] [Right parser.] [__parser_concept__]]
+]
+
+[heading Type Expressions]
+
+[table
+ [[Expression] [Description]]
+ [[`P::left_type`] [The left parser type.]]
+ [[`P::right_type`] [The right parser type.]]
+ [[`traits::is_binary_parser<P>::type`] [Metafunction that evaluates to `mpl::true_` if
+ a certain type, `P` is a BinaryParser, `mpl::false_`
+ otherwise (See __mpl_boolean_constant__).]]
+]
+
+[heading Invariants]
+
+For any BinaryParser, `P`, the following invariants always hold:
+
+* `traits::is_parser<P::left_type>::type` evaluates to `mpl::true_`
+* `traits::is_parser<P::right_type>::type` evaluates to `mpl::true_`
+
+[heading Models]
+
+Links to models of BinaryParser concept
+
+[endsect] [/ BinaryParser Concept]
+
+[/------------------------------------------------------------------------------]
+[section NaryParser]
+
+[heading Description]
+
+`NaryParser` is a composite parser that has one or more subjects. The
+NaryParser allows its subjects to be treated in the same way as a single
+instance of a __parser_concept__ following the __composite_pattern__.
+
+[heading Refinement of]
+
+[:__parser_concept__]
+
+[variablelist Notation
+ [[`p`] [A NaryParser.]]
+ [[`P`] [A NaryParser type.]]
+]
+
+[heading Valid Expressions]
+
+In addition to the requirements defined in __parser_concept__, for any
+NaryParser the following must be met:
+
+[table
+ [[Expression] [Semantics] [Return type]]
+ [[`p.elements`] [The tuple of elements.] [A __fusion__ Sequence of __parser_concept__ types.]]
+]
+
+[heading Type Expressions]
+
+[table
+ [[Expression] [Description]]
+ [[`p.elements_type`] [Elements tuple type.]]
+ [[`traits::is_nary_parser<P>::type`] [Metafunction that evaluates to `mpl::true_` if
+ a certain type, `P` is a NaryParser, `mpl::false_`
+ otherwise (See __mpl_boolean_constant__).]]
+]
+
+[heading Invariants]
+
+For any NaryParser, `P`, the following invariants always holds:
+
+* For each element, `E`, in NaryParser, `P`, the following invariant always hold:
+`` traits::is_parser<E>::type evaluates to `mpl::true_``
+
+[heading Models]
+
+Links to models of NaryParser concept
+
+[endsect] [/ NaryParser Concept]
+
+
[endsect]
Modified: trunk/libs/spirit/doc/qi/directive.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/directive.qbk (original)
+++ trunk/libs/spirit/doc/qi/directive.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Directive]
+[/ section Directive]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/nonterminal.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/nonterminal.qbk (original)
+++ trunk/libs/spirit/doc/qi/nonterminal.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Nonterminal]
+[/ section Nonterminal]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/numeric.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/numeric.qbk (original)
+++ trunk/libs/spirit/doc/qi/numeric.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Numeric]
+[/ section Numeric]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/operator.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/operator.qbk (original)
+++ trunk/libs/spirit/doc/qi/operator.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Operator]
+[/ section Operator]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/quick_reference.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/quick_reference.qbk (original)
+++ trunk/libs/spirit/doc/qi/quick_reference.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -226,31 +226,6 @@
[endsect]
-[section Lazy Arguments]
-
-For all expressions of the form:
-
- p(a1, a2,... aN)
-
-where `p` is a parser, each of the arguments (a1...aN) can either be an
-immediate value, or a lazy function with signature:
-
- T(Unused, Context)
-
-where `T`, the function's return value, is compatible with the argument
-type expected. For example, this is a valid expression:
-
- eps(false) // this will always fail
-
-And so is this:
-
- bool flag = true;
- eps(phoenix::var(flag)) // success or fail depending on the value
- // of flag at parse time
-
-since `phoenix::ref(f)` is a function that returns a `bool`.
-
-[endsect]
[section Non-terminals]
[variablelist Notation
Modified: trunk/libs/spirit/doc/qi/stream.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/stream.qbk (original)
+++ trunk/libs/spirit/doc/qi/stream.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -6,8 +6,8 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
-[section Stream]
+[/ section Stream]
-[endsect]
+[/ endsect]
Modified: trunk/libs/spirit/doc/qi/string.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/string.qbk (original)
+++ trunk/libs/spirit/doc/qi/string.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -9,5 +9,205 @@
[section String]
+[/------------------------------------------------------------------------------]
+[section lit/string]
+
+[heading Description]
+
+The lit/string parser matches a string of characters. The lit/string
+parser is an implicit lexeme: the `skip` parser is not applied in
+between characters of the string.
+
+[heading Header]
+
+ #include <boost/spirit/home/qi/string/lit.hpp> // main include
+ #include <boost/spirit/include/qi_lit.hpp> // or, forwarding header
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/qi/string.hpp> // string module
+ #include <boost/spirit/include/qi_string.hpp> // or, forwarding header
+ #include <boost/spirit/home/qi.hpp> // qi module
+ #include <boost/spirit/include/qi.hpp> // or, forwarding header
+
+Also, see __include_structure__.
+
+[heading Model of]
+
+[:__primitive_parser_concept__]
+
+[variablelist Notation
+ [[`s`] [A literal string, e.g. "Hello", or a pointer/reference to a
+ null-terminated array of characters or a a `std::basic_string`.]]
+ [[`fs`] [A __lazy_argument__ that evaluates to a `std::basic_string`
+ or a pointer/reference to a null-terminated array of characters.]]
+ [[`ns`] [A __char_encoding_namespace__.]]]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is
+not defined in __primitive_parser_concept__.
+
+[table
+ [[Expression] [Semantics]]
+ [[`s`] [Generate a string parser
+ from a string, `s`.]]
+ [[`lit(s)`] [Generate a string parser
+ from a string, `s`.]]
+ [[`ns::string(s)`] [Generate a string parser
+ from a string, `s`.]]
+ [[`fs`] [Generate a string parser
+ from a string, `s`, returned by
+ invoking `fs` at parse time.
+ See __lazy_argument__]]
+ [[`lit(fs)`] [Generate a string parser
+ from a string, `s`, returned by
+ invoking `fs` at parse time.
+ See __lazy_argument__]]
+ [[`ns::string(fs)`] [Generate a string parser
+ from a string, `s`, returned by
+ invoking `fs` at parse time.
+ See __lazy_argument__]]
+]
+
+[heading Attributes]
+
+[table
+ [[Expression] [Attribute]]
+ [[`s`]
+ [__unused__]]
+ [[`lit(s)`]
+ [__unused__]]
+ [[`ns::string(s)`] [`std::basic_string<T>` where `T`
+ is the underlying character type
+ of `s`]]
+ [[`fs`] [`std::basic_string<T>` where `T`
+ is the underlying character type
+ of `s`]]
+ [[`lit(fs)`] [`std::basic_string<T>` where `T`
+ is the underlying character type
+ of `s`]]
+ [[`ns::string(fs)`] [`std::basic_string<T>` where `T`
+ is the underlying character type
+ of `s`]]
+]
+
+
+[heading Complexity]
+
+[:O(N)]
+
+where `N` is the number of characters in the string to be parsed.
+
+[heading Example]
+
+All code snippets below use this common test function:
+
+[reference_test]
+
+Some using declarations:
+
+[reference_using_declarations]
+
+Basic literals:
+
+[reference_string1_literals]
+
+From a `std::string`
+
+[reference_string1_std_string]
+
+Lazy strings using __phoenix__
+
+[reference_string1_phoenix]
+
+[endsect] [/ lit/strin]
+
+
+[/------------------------------------------------------------------------------]
+[section symbols]
+
+[heading Description]
+
+This class `symbols` implements a symbol table: an associative container
+(or map) of key-value pairs where the keys are strings. The `symbols`
+class can work efficiently with 8, 16, 32 and even 64 bit characters.
+
+Traditionally, symbol table management is maintained seperately outside
+the grammar through semantic actions. Contrary to standard practice, the
+Spirit symbol table class symbols is-a parser. An instance of which may
+be used anywhere in the grammar specification. It is an example of a
+dynamic parser. A dynamic parser is characterized by its ability to
+modify its behavior at run time. Initially, an empty symbols object
+matches nothing. At any time, symbols may be added, thus, dynamically
+altering its behavior.
+
+[heading Header]
+
+ #include <boost/spirit/home/qi/string/symbols.hpp> // main include
+ #include <boost/spirit/include/qi_symbols.hpp> // or, forwarding header
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/qi/string.hpp> // string module
+ #include <boost/spirit/include/qi_string.hpp> // or, forwarding header
+ #include <boost/spirit/home/qi.hpp> // qi module
+ #include <boost/spirit/include/qi.hpp> // or, forwarding header
+
+Also, see __include_structure__.
+
+[heading Synopsis]
+
+ template <typename Char, typename T>
+ struct symbols;
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Char`] [The character type
+ of the symbol strings.] [`char`]]
+ [[`T`] [The data type associated
+ with each symbol.] [__unused_type__]]
+]
+
+[heading Model of]
+
+[:__primitive_parser_concept__]
+
+[variablelist Notation
+ [[`Sym`] [A `symbols` type.]]
+ [[`Char`] [A character type.]]
+ [[`T`] [A data type.]]
+ [[`sym`] [A `symbols` object.]]
+ [[`sym2`] [Another `symbols` object.]]
+ [[`sseq`] [An __stl__ container of strings.]]
+ [[`dseq`] [An __stl__ container of data with `value_type` `T`.]]
+]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is not
+defined in __primitive_parser_concept__.
+
+[table
+ [[Expression] [Semantics]]
+ [[`Sym()`] [Construct an empty symbols.]]
+ [[`Sym(sym)`] [Copy construct a symbols from `sym2`.]]
+ [[`Sym(sseq)`] [Construct symbols from `sseq`.]]
+ [[`Sym(sseq)`] [Construct symbols from `sseq` and `dseq`.]]
+ [[`sym = sym`] [Assign `sym2` to `sym`.]]
+]
+
+[heading Attributes]
+
+The attribute of `stymbol<Char, T>` is always `T`.
+
+[heading Example]
+
+Real example code. Use Quickbook import mechanism to link to actual
+working code snippets here.
+
+[endsect] [/ symbols]
[endsect]
Modified: trunk/libs/spirit/doc/reference_template.qbk
==============================================================================
--- trunk/libs/spirit/doc/reference_template.qbk (original)
+++ trunk/libs/spirit/doc/reference_template.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -1,11 +1,5 @@
-[/==============================================================================
- Copyright (C) 2001-2009 Joel de Guzman
- Copyright (C) 2001-2009 Hartmut Kaiser
-
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-===============================================================================/]
+[/------------------------------------------------------------------------------]
[section XXX]
[heading Description]
@@ -15,6 +9,13 @@
[heading Header]
#include <boost/spirit/xxx.hpp>
+
+[heading Module Headers]
+
+ #include <boost/spirit/xxx.hpp>
+ ...
+
+Also, see __include_structure__.
[heading Synopsis]
@@ -30,22 +31,25 @@
[heading Model of]
-Link to concept
-
-[heading Objects]
-
-Objects provided by the library
-
[variablelist Notation
[[`xxx`] [An XXX]]
]
+[heading Expression Semantics]
+
Semantics of an expression is defined only where it differs from, or is not
defined in _concept-of_XXX_.
[table
- [[Expression] [Semantics] [Return type] [Complexity]]
- [[`xxx`] [Semantics of `xxx`] [XXX] [Constant]]
+ [[Expression] [Semantics]]
+ [[`xxx`] [Semantics of `xxx`]]
+]
+
+[heading Attributes]
+
+[table
+ [[Expression] [Attribute]]
+ [[`xxx`] [Attribute of `xxx`]]
]
[heading Example]
@@ -53,4 +57,4 @@
Real example code. Use Quickbook import mechanism to link to actual
working code snippets here.
-[endsect]
+[endsect] [/ XXX]
Modified: trunk/libs/spirit/doc/spirit2.qbk
==============================================================================
--- trunk/libs/spirit/doc/spirit2.qbk (original)
+++ trunk/libs/spirit/doc/spirit2.qbk 2009-07-03 22:58:12 EDT (Fri, 03 Jul 2009)
@@ -64,6 +64,7 @@
[def __karma__ /Spirit.Karma/]
[def __lex__ /Spirit.Lex/]
+[def __mpl_boolean_constant__ [@http://www.boost.org/libs/mpl/doc/refmanual/integral-constant.html MPL Boolean Constant]]
[def __fixme__ *FIXME*]
@@ -103,6 +104,11 @@
[def __class_lexertl_lexer__ [link spirit.lex.reference.lexer_class.the_lexertl_lexer_class_implementing_the_dynamic_model `lexertl_lexer<>`]]
[def __class_lexertl_static_lexer__ [link spirit.lex.reference.lexer_class.the_lexertl_static_lexer_class_implementing_the_static_model `lexertl_static_lexer<>`]]
+[/ References to support ]
+
+[def __unused_type__ `unused_type`] [/$$$ TODO: link me $$$]
+[def __unused__ `unused`] [/$$$ TODO: link me $$$]
+[def __info__ `info`] [/$$$ TODO: link me $$$]
[/ References to abstracts ]
@@ -111,6 +117,27 @@
[def __peg__ [link spirit.abstracts.parsing_expression_grammar Parsing Expression Grammar]]
[def __ast__ [Abstract Syntax Tree] [/$$$ TODO: link me $$$]
+[def __include_structure__ [link spirit.structure.include Include Structure]]
+
+[/ References to reference ]
+
+[def __parser_concept__ [link spirit.qi.reference.concepts.parser `Parser`]]
+[def __primitive_parser_concept__ [link spirit.qi.reference.concepts.primitiveparser `PrimitiveParser`]]
+[def __lazy_argument__ [link spirit.qi.reference.basics.lazy_argument Lazy Argument]]
+[def __char_encoding_namespace__ [link spirit.qi.reference.basics.character_encoding_namespace Character Encoding Namespace]]
+
+Character Encoding Namespace
+
+[def __actions__ Semantic Actions] [/$$$ TODO: link me $$$]
+[def __context__ Context] [/$$$ TODO: link me $$$]
+[def __compatible__ Compatible] [/$$$ TODO: link me $$$]
+[def __atribute__ Attribute] [/$$$ TODO: link me $$$]
+[def __compatible_atribute__ Compatible Attribute] [/$$$ TODO: link me $$$]
+[def __rule__ Rule] [/$$$ TODO: link me $$$]
+[def __parser_conversion__ Parser Conversion] [/$$$ TODO: link me $$$]
+[def __delegate_pattern__ Delegate Design Pattern] [/$$$ TODO: link me $$$]
+[def __composite_pattern__ Composite Design Pattern] [/$$$ TODO: link me $$$]
+
[/ Some images ]
[def __note__ [$images/note.png]]