projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
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 |