]>
Commit | Line | Data |
---|---|---|
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 | ||
12 | Some parsers (e.g. primitives and non-terminals) may take in additional | |
13 | attributes. Such parsers take the form: | |
14 | ||
15 | p(a1, a2,..., aN) | |
16 | ||
17 | where `p` is a parser. Each of the arguments (a1 ... aN) can either be an | |
18 | immediate value, or a function, `f`, with signature: | |
19 | ||
20 | T f(Unused, Context) | |
21 | ||
22 | where `T`, the function's return value, is compatible with the argument | |
23 | type expected and `Context` is the parser's __context__ type (The first | |
24 | argument is __unused__ to make the `Context` the second argument. This | |
25 | is done for uniformity with __actions__). | |
26 | ||
27 | [heading Character Encoding Namespace] | |
28 | ||
29 | Some parsers need to know which character set a `char` or `wchar_t` is | |
30 | operating on. For example, the `alnum` parser works differently with | |
31 | ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags) | |
32 | the parser with the character set. | |
33 | ||
34 | We have a namespace for each character set Spirit will be supporting. | |
35 | That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and | |
36 | in the future, `unicode`). In each of the character encoding namespaces, | |
37 | we place tagged versions of parsers such as `alnum`, `space` etc. | |
38 | ||
39 | Example: | |
40 | ||
41 | using boost::spirit::ascii::space; // use the ASCII space parser | |
42 | ||
43 | Namespaces: | |
44 | ||
45 | * boost::spirit::ascii | |
46 | * boost::spirit::iso8859_1 | |
47 | * boost::spirit::standard | |
48 | * boost::spirit::standard_wide | |
49 | ||
50 | For ease of use, the components in this namespaces are also brought into | |
51 | the 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 | ||
60 | All sections in the reference present some real world examples. The | |
61 | examples use a common test harness to keep the example code as minimal | |
62 | and direct to the point as possible. The test harness is presented | |
63 | below. | |
64 | ||
65 | Some includes: | |
66 | ||
67 | [reference_includes] | |
68 | ||
69 | Our test functions: | |
70 | ||
71 | These functions test the parsers without attributes. | |
72 | ||
73 | [reference_test] | |
74 | ||
75 | These functions test the parsers with user supplied attributes. | |
76 | ||
77 | [reference_test_attr] | |
78 | ||
79 | The `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 | ||
91 | A string can be any object `s`, of type, `S`, that satisfies the | |
92 | following 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 | ||
112 | Predefined 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 | ||
118 | The namespace `boost::spirit::traits` is open for users to provide their | |
119 | own specializations. The customization points implemented by __qi__ usable | |
120 | to customize the behavior of parsers are described in the section | |
121 | __sec_customization_points__. | |
122 | ||
123 | [endsect] | |
124 |