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
13Do you see strange multiple symbol definition linker errors mentioning
14`boost::mpl::failed` and `boost::spirit::qi::rule`? Then this FAQ entry might
15be for you.
16
17__mpl__ implements a macro `BOOST_MPL_ASSERT_MSG()` which essentially is a
18more powerful version of static_assert. Unfortunately under certain
19circumstances using this macro may lead to the aforementioned linker errors.
20
21__spirit__ allows you to define a preprocessor constant disabling the usage
22of `BOOST_MPL_ASSERT_MSG()`, while switching to `BOOST_STATIC_ASSERT()` instead.
23For that you need define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1. Do this by
24adding
25
26    -DBOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1
27
28on the compiler command line or by inserting a
29
30    #define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG 1
31
32into your code before any Spirit headers get included.
33
34Using 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
36verbose 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
41The boost/spirit directory currently holds two versions of the Spirit library:
42__classic__ (former V1.8.x) and SpiritV2. Both are completely independent
43and 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
59While introducing Spirit V2 we restructured the directory structure in order to
60accommodate two versions at the same time. All of __classic__ now lives in
61the directory
62
63    boost/spirit/home/classic
64
65where the directories above contain forwarding headers to the new location
66allowing to maintain application compatibility. The forwarding headers issue a
67warning (starting with Boost V1.38) telling the user to change their include
68paths. Please expect the above directories/forwarding headers to go away soon.
69
70This explains the need for the directory
71
72    boost/spirit/include
73
74which contains forwarding headers as well. But this time the headers won't go
75away. We encourage application writers to use only the includes contained in
76this directory. This allows us to restructure the directories underneath if
77needed without worrying application compatibility. Please use those files in
78your application only. If it turns out that some forwarding file is missing,
79please report this as a bug.
80
81Spirit V2 is not about parsing only anymore (as __classic__). It now consists
82out of 3 parts (sub-libraries): __qi__, __karma__, and __lex__. The header
83files for those live in
84
85    boost/spirit/home/qi
86    boost/spirit/home/karma
87    boost/spirit/home/lex
88
89and have forwarding headers in
90
91    boost/spirit/include
92
93__qi__ is the direct successor to __classic__ as it implements a DSEL (domain
94specific embedded language) allowing to write parsers using the syntax of C++
95itself (parsers in the sense turning a sequence of bytes into an internal data
96structure). It is not compatible with __classic__, the main concepts are
97similar, though.
98
99__karma__ is the counterpart to __qi__. It implements a similar DSEL but for
100writing generators (i.e. the things turning internal data structures into a
101sequence 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.
105These are either usable stand alone or can be used as a front end for __qi__
106parsers. If you know flex you shouldn't have problems understanding __lex__.
107This library actually doesn't implement the lexer itself. All it does is to
108provide an interface to pre-existing lexical analyzers. Currently it's using
109Ben Hansons excellent __lexertl__ library (proposed for a Boost review, BTW) as
110its underlying workhorse.
111
112Again, don't use any of the header files underneath the boost/spirit/home
113directory directly, always include files from the boost/spirit/include
114directory.
115
116The last bit missing is __phoenix__ (which currently still lives under the
117Spirit umbrella, but already has been accepted as a Boost library, so it will
118move away). __phoenix__ is a library allowing to write functional style C++,
119which is interesting in itself, but as it initially has been developed for
120Spirit, it is nicely integrated and very useful when it comes to writing
121semantic actions. I think using the boost/spirit/include/phoenix_... headers
122will be safe in the future as well, as we will probably redirect to the
123Boost.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
128In order to perform case-insensitive parsing (using __qi_no_case__) with a
129symbol table (i.e. use a __qi_symbols__
130parser in a `no_case` directive), that symbol table needs to be filled with
131all-lowercase contents. Entries containing one or more uppercase characters
132will 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
138If you are using Visual C++ and have an error like:
139
140[pre
141error C2664: \'bool boost::function4<R,T0,T1,T2,T3>::operator ()(T0,T1,T2,T3) const\' :
142    cannot convert parameter 4 from '...' to '...'
143]
144
145or you are using GCC and have an error like:
146
147[pre
148error: no match for call to '(const boost::function<bool ()(...)>) (...)'
149note: candidates are: ... boost::function4<R,T1,T2,T3,T4>::operator()(T0,T1,T2,T3) const [with ...\]
150]
151
152then this FAQ entry may help you.
153
154The definition of a __rule__ or __grammar__ may contain a skip parser type. If
155it does, it means that non-terminal can only be used with a skip parser of a
156compatible 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`. Similarly, corresponding error
168      messages in __karma__ reference `boost::function3` and the 3rd
169      parameter (instead of the 4th).]
170
171[endsect]
172