1[/============================================================================== 2 Copyright (C) 2001-2008 Joel de Guzman 3 Copyright (C) 2001-2008 Hartmut Kaiser 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8[section:basics Parser Basics] 9 10[heading Lazy Argument] 11 12Some parsers (e.g. primitives and non-terminals) may take in additional 13attributes. Such parsers take the form: 14 15 p(a1, a2,..., aN) 16 17where `p` is a parser. Each of the arguments (a1 ... aN) can either be an 18immediate value, or a function, `f`, with signature: 19 20 T f(Unused, Context) 21 22where `T`, the function's return value, is compatible with the argument 23type expected and `Context` is the parser's __context__ type (The first 24argument is __unused__ to make the `Context` the second argument. This 25is done for uniformity with __actions__). 26 27[heading Character Encoding Namespace] 28 29Some parsers need to know which character set a `char` or `wchar_t` is 30operating on. For example, the `alnum` parser works differently with 31ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags) 32the parser with the character set. 33 34We have a namespace for each character set Spirit will be supporting. 35That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and 36in the future, `unicode`). In each of the character encoding namespaces, 37we place tagged versions of parsers such as `alnum`, `space` etc. 38 39Example: 40 41 using boost::spirit::ascii::space; // use the ASCII space parser 42 43Namespaces: 44 45* boost::spirit::ascii 46* boost::spirit::iso8859_1 47* boost::spirit::standard 48* boost::spirit::standard_wide 49 50For ease of use, the components in this namespaces are also brought into 51the qi sub-namespaces with the same names: 52 53* boost::spirit::qi::ascii 54* boost::spirit::qi::iso8859_1 55* boost::spirit::qi::standard 56* boost::spirit::qi::standard_wide 57 58[heading Examples] 59 60All sections in the reference present some real world examples. The 61examples use a common test harness to keep the example code as minimal 62and direct to the point as possible. The test harness is presented 63below. 64 65Some includes: 66 67[reference_includes] 68 69Our test functions: 70 71These functions test the parsers without attributes. 72 73[reference_test] 74 75These functions test the parsers with user supplied attributes. 76 77[reference_test_attr] 78 79The `print_info` utility function prints information contained in the 80__info__ class. 81 82[reference_print_info] 83 84[heading String] 85 86[heading Header] 87 88 // forwards to <boost/spirit/home/support/string_traits.hpp> 89 #include <boost/spirit/support_string_traits.hpp> 90 91A string can be any object `s`, of type, `S`, that satisfies the 92following expression traits: 93 94[table 95 [[Expression] [Semantics]] 96 [[`boost::spirit::traits::is_string<S>`] [Metafunction that evaluates to `mpl::true_` if 97 a certain type, `S` is a string, `mpl::false_` 98 otherwise (See __mpl_boolean_constant__).]] 99 [[`boost::spirit::traits::char_type_of<S>`] [Metafunction that returns the underlying 100 char type of a string type, `S`.]] 101 [[`boost::spirit::traits::get_c_string(s)`] [Function that returns the underlying 102 raw C-string from `s`.]] 103 [[`boost::spirit::traits::get_begin(s)`] [Function that returns an __stl__ iterator from `s` 104 that points to the beginning the string.]] 105 [[`boost::spirit::traits::get_end(s)`] [Function that returns an __stl__ iterator from `s` 106 that points to the end of the string.]] 107 108] 109 110[heading Models] 111 112Predefined models include: 113 114* any literal string, e.g. "Hello, World", 115* a pointer/reference to a null-terminated array of characters 116* a `std::basic_string<Char>` 117 118The namespace `boost::spirit::traits` is open for users to provide their 119own specializations. The customization points implemented by __qi__ usable 120to customize the behavior of parsers are described in the section 121__sec_customization_points__. 122 123[endsect] 124 125