]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Joel de Guzman | |
3 | Copyright (C) 2001-2011 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 | ||
9 | [section:faq Spirit FAQ] | |
10 | ||
11 | [heading I'm getting multiple symbol definition errors while using Visual C++. Anything I could do about that?] | |
12 | ||
13 | Do you see strange multiple symbol definition linker errors mentioning | |
14 | `boost::mpl::failed` and `boost::spirit::qi::rule`? Then this FAQ entry might | |
15 | be for you. | |
16 | ||
17 | __mpl__ implements a macro `BOOST_MPL_ASSERT_MSG()` which essentially is a | |
18 | more powerful version of static_assert. Unfortunately under certain | |
19 | circumstances using this macro may lead to the aforementioned linker errors. | |
20 | ||
21 | __spirit__ allows you to define a preprocessor constant disabling the usage | |
22 | of `BOOST_MPL_ASSERT_MSG()`, while switching to `BOOST_STATIC_ASSERT()` instead. | |
23 | For that you need define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1. Do this by | |
24 | adding | |
25 | ||
26 | -DBOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1 | |
27 | ||
28 | on the compiler command line or by inserting a | |
29 | ||
30 | #define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG 1 | |
31 | ||
32 | into your code before any Spirit headers get included. | |
33 | ||
34 | Using this trick has no adverse effects on any of the functionality of | |
35 | __spirit__. The only change you might see while using this workaround is less | |
36 | verbose error messages generated from static_assert. | |
37 | ||
38 | ||
39 | [heading I'm very confused about the header hell in my boost/spirit directory. What's all this about?] | |
40 | ||
41 | The boost/spirit directory currently holds two versions of the Spirit library: | |
42 | __classic__ (former V1.8.x) and SpiritV2. Both are completely independent | |
43 | and usually not used at the same time. Do not mix these two in the same grammar. | |
44 | ||
45 | __classic__ evolved over years in a fairly complex directory structure: | |
46 | ||
47 | boost/spirit/actor | |
48 | boost/spirit/attribute | |
49 | boost/spirit/core | |
50 | boost/spirit/debug | |
51 | boost/spirit/dynamic | |
52 | boost/spirit/error_handling | |
53 | boost/spirit/iterator | |
54 | boost/spirit/meta | |
55 | boost/spirit/symbols | |
56 | boost/spirit/tree | |
57 | boost/spirit/utility | |
58 | ||
59 | While introducing Spirit V2 we restructured the directory structure in order to | |
60 | accommodate two versions at the same time. All of __classic__ now lives in | |
61 | the directory | |
62 | ||
63 | boost/spirit/home/classic | |
64 | ||
65 | where the directories above contain forwarding headers to the new location | |
66 | allowing to maintain application compatibility. The forwarding headers issue a | |
67 | warning (starting with Boost V1.38) telling the user to change their include | |
68 | paths. Please expect the above directories/forwarding headers to go away soon. | |
69 | ||
70 | This explains the need for the directory | |
71 | ||
72 | boost/spirit/include | |
73 | ||
74 | which contains forwarding headers as well. But this time the headers won't go | |
75 | away. We encourage application writers to use only the includes contained in | |
76 | this directory. This allows us to restructure the directories underneath if | |
77 | needed without worrying application compatibility. Please use those files in | |
78 | your application only. If it turns out that some forwarding file is missing, | |
79 | please report this as a bug. | |
80 | ||
81 | Spirit V2 is not about parsing only anymore (as __classic__). It now consists | |
82 | out of 3 parts (sub-libraries): __qi__, __karma__, and __lex__. The header | |
83 | files for those live in | |
84 | ||
85 | boost/spirit/home/qi | |
86 | boost/spirit/home/karma | |
87 | boost/spirit/home/lex | |
88 | ||
89 | and have forwarding headers in | |
90 | ||
91 | boost/spirit/include | |
92 | ||
93 | __qi__ is the direct successor to __classic__ as it implements a DSEL (domain | |
94 | specific embedded language) allowing to write parsers using the syntax of C++ | |
95 | itself (parsers in the sense turning a sequence of bytes into an internal data | |
96 | structure). It is not compatible with __classic__, the main concepts are | |
97 | similar, though. | |
98 | ||
99 | __karma__ is the counterpart to __qi__. It implements a similar DSEL but for | |
100 | writing generators (i.e. the things turning internal data structures into a | |
101 | sequence of bytes, most of the time - strings). __karma__ is the Yang to | |
102 | __qi__'s Yin, it's almost like a mirrored picture. | |
103 | ||
104 | __lex__ is (as the name implies) a library allowing to write lexical analyzers. | |
105 | These are either usable stand alone or can be used as a front end for __qi__ | |
106 | parsers. If you know flex you shouldn't have problems understanding __lex__. | |
107 | This library actually doesn't implement the lexer itself. All it does is to | |
108 | provide an interface to pre-existing lexical analyzers. Currently it's using | |
109 | Ben Hansons excellent __lexertl__ library (proposed for a Boost review, BTW) as | |
110 | its underlying workhorse. | |
111 | ||
112 | Again, don't use any of the header files underneath the boost/spirit/home | |
113 | directory directly, always include files from the boost/spirit/include | |
114 | directory. | |
115 | ||
116 | The last bit missing is __boost_phoenix__ (which currently still lives under the | |
117 | Spirit umbrella, but already has been accepted as a Boost library, so it will | |
118 | move away). __boost_phoenix__ is a library allowing to write functional style C++, | |
119 | which is interesting in itself, but as it initially has been developed for | |
120 | Spirit, it is nicely integrated and very useful when it comes to writing | |
121 | semantic actions. I think using the boost/spirit/include/phoenix_... headers | |
122 | will be safe in the future as well, as we will probably redirect to the | |
123 | Boost.Phoenix headers as soon as these are available. | |
124 | ||
125 | ||
126 | [heading Why doesn't my symbol table work in a `no_case` directive?] | |
127 | ||
128 | In order to perform case-insensitive parsing (using __qi_no_case__) with a | |
129 | symbol table (i.e. use a __qi_symbols__ | |
130 | parser in a `no_case` directive), that symbol table needs to be filled with | |
131 | all-lowercase contents. Entries containing one or more uppercase characters | |
132 | will not match any input. | |
133 | ||
134 | ||
135 | [heading I'm getting a compilation error mentioning `boost::function` and/or | |
136 | `boost::function4`. What does this mean?] | |
137 | ||
138 | If you are using Visual C++ and have an error like: | |
139 | ||
140 | [pre | |
141 | error C2664: \'bool boost::function4<R,T0,T1,T2,T3>::operator ()(T0,T1,T2,T3) const\' : | |
142 | cannot convert parameter 4 from '...' to '...' | |
143 | ] | |
144 | ||
145 | or you are using GCC and have an error like: | |
146 | ||
147 | [pre | |
148 | error: no match for call to '(const boost::function<bool ()(...)>) (...)' | |
149 | note: candidates are: ... boost::function4<R,T1,T2,T3,T4>::operator()(T0,T1,T2,T3) const [with ...\] | |
150 | ] | |
151 | ||
152 | then this FAQ entry may help you. | |
153 | ||
154 | The definition of a __rule__ or __grammar__ may contain a skip parser type. If | |
155 | it does, it means that non-terminal can only be used with a skip parser of a | |
156 | compatible type. The error above arises when this is not the case, i.e.: | |
157 | ||
158 | * a non-terminal defined with a skip parser type is used without a skip parser; | |
159 | for example, a rule with a skip parser type is used inside a `lexeme` | |
160 | directive, or a grammar with a skip parser type is used in `parse` instead of | |
161 | `phrase_parse`, | |
162 | * or a non-terminal is used with a skip parser of an incompatible type; | |
163 | for example, a rule defined with one skip parser type calls a second rule | |
164 | defined with another, incompatible skip parser type. | |
165 | ||
166 | [note The same applies to __karma__, replacing 'skip parser' and `lexeme` | |
167 | by 'delimit generator' and `verbatim`. Similarily, corresponding error | |
168 | messages in __karma__ reference `boost::function3` and the 3rd | |
169 | parameter (instead of the 4th).] | |
170 | ||
171 | [endsect] |