172 lines
7.2 KiB
Plaintext
172 lines
7.2 KiB
Plaintext
[/==============================================================================
|
|
Copyright (C) 2001-2011 Joel de Guzman
|
|
Copyright (C) 2001-2011 Hartmut Kaiser
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
===============================================================================/]
|
|
|
|
[section:faq Spirit FAQ]
|
|
|
|
[heading I'm getting multiple symbol definition errors while using Visual C++. Anything I could do about that?]
|
|
|
|
Do you see strange multiple symbol definition linker errors mentioning
|
|
`boost::mpl::failed` and `boost::spirit::qi::rule`? Then this FAQ entry might
|
|
be for you.
|
|
|
|
__mpl__ implements a macro `BOOST_MPL_ASSERT_MSG()` which essentially is a
|
|
more powerful version of static_assert. Unfortunately under certain
|
|
circumstances using this macro may lead to the aforementioned linker errors.
|
|
|
|
__spirit__ allows you to define a preprocessor constant disabling the usage
|
|
of `BOOST_MPL_ASSERT_MSG()`, while switching to `BOOST_STATIC_ASSERT()` instead.
|
|
For that you need define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1. Do this by
|
|
adding
|
|
|
|
-DBOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1
|
|
|
|
on the compiler command line or by inserting a
|
|
|
|
#define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG 1
|
|
|
|
into your code before any Spirit headers get included.
|
|
|
|
Using this trick has no adverse effects on any of the functionality of
|
|
__spirit__. The only change you might see while using this workaround is less
|
|
verbose error messages generated from static_assert.
|
|
|
|
|
|
[heading I'm very confused about the header hell in my boost/spirit directory. What's all this about?]
|
|
|
|
The boost/spirit directory currently holds two versions of the Spirit library:
|
|
__classic__ (former V1.8.x) and SpiritV2. Both are completely independent
|
|
and usually not used at the same time. Do not mix these two in the same grammar.
|
|
|
|
__classic__ evolved over years in a fairly complex directory structure:
|
|
|
|
boost/spirit/actor
|
|
boost/spirit/attribute
|
|
boost/spirit/core
|
|
boost/spirit/debug
|
|
boost/spirit/dynamic
|
|
boost/spirit/error_handling
|
|
boost/spirit/iterator
|
|
boost/spirit/meta
|
|
boost/spirit/symbols
|
|
boost/spirit/tree
|
|
boost/spirit/utility
|
|
|
|
While introducing Spirit V2 we restructured the directory structure in order to
|
|
accommodate two versions at the same time. All of __classic__ now lives in
|
|
the directory
|
|
|
|
boost/spirit/home/classic
|
|
|
|
where the directories above contain forwarding headers to the new location
|
|
allowing to maintain application compatibility. The forwarding headers issue a
|
|
warning (starting with Boost V1.38) telling the user to change their include
|
|
paths. Please expect the above directories/forwarding headers to go away soon.
|
|
|
|
This explains the need for the directory
|
|
|
|
boost/spirit/include
|
|
|
|
which contains forwarding headers as well. But this time the headers won't go
|
|
away. We encourage application writers to use only the includes contained in
|
|
this directory. This allows us to restructure the directories underneath if
|
|
needed without worrying application compatibility. Please use those files in
|
|
your application only. If it turns out that some forwarding file is missing,
|
|
please report this as a bug.
|
|
|
|
Spirit V2 is not about parsing only anymore (as __classic__). It now consists
|
|
out of 3 parts (sub-libraries): __qi__, __karma__, and __lex__. The header
|
|
files for those live in
|
|
|
|
boost/spirit/home/qi
|
|
boost/spirit/home/karma
|
|
boost/spirit/home/lex
|
|
|
|
and have forwarding headers in
|
|
|
|
boost/spirit/include
|
|
|
|
__qi__ is the direct successor to __classic__ as it implements a DSEL (domain
|
|
specific embedded language) allowing to write parsers using the syntax of C++
|
|
itself (parsers in the sense turning a sequence of bytes into an internal data
|
|
structure). It is not compatible with __classic__, the main concepts are
|
|
similar, though.
|
|
|
|
__karma__ is the counterpart to __qi__. It implements a similar DSEL but for
|
|
writing generators (i.e. the things turning internal data structures into a
|
|
sequence of bytes, most of the time - strings). __karma__ is the Yang to
|
|
__qi__'s Yin, it's almost like a mirrored picture.
|
|
|
|
__lex__ is (as the name implies) a library allowing to write lexical analyzers.
|
|
These are either usable stand alone or can be used as a front end for __qi__
|
|
parsers. If you know flex you shouldn't have problems understanding __lex__.
|
|
This library actually doesn't implement the lexer itself. All it does is to
|
|
provide an interface to pre-existing lexical analyzers. Currently it's using
|
|
Ben Hansons excellent __lexertl__ library (proposed for a Boost review, BTW) as
|
|
its underlying workhorse.
|
|
|
|
Again, don't use any of the header files underneath the boost/spirit/home
|
|
directory directly, always include files from the boost/spirit/include
|
|
directory.
|
|
|
|
The last bit missing is __phoenix__ (which currently still lives under the
|
|
Spirit umbrella, but already has been accepted as a Boost library, so it will
|
|
move away). __phoenix__ is a library allowing to write functional style C++,
|
|
which is interesting in itself, but as it initially has been developed for
|
|
Spirit, it is nicely integrated and very useful when it comes to writing
|
|
semantic actions. I think using the boost/spirit/include/phoenix_... headers
|
|
will be safe in the future as well, as we will probably redirect to the
|
|
Boost.Phoenix headers as soon as these are available.
|
|
|
|
|
|
[heading Why doesn't my symbol table work in a `no_case` directive?]
|
|
|
|
In order to perform case-insensitive parsing (using __qi_no_case__) with a
|
|
symbol table (i.e. use a __qi_symbols__
|
|
parser in a `no_case` directive), that symbol table needs to be filled with
|
|
all-lowercase contents. Entries containing one or more uppercase characters
|
|
will not match any input.
|
|
|
|
|
|
[heading I'm getting a compilation error mentioning `boost::function` and/or
|
|
`boost::function4`. What does this mean?]
|
|
|
|
If you are using Visual C++ and have an error like:
|
|
|
|
[pre
|
|
error C2664: \'bool boost::function4<R,T0,T1,T2,T3>::operator ()(T0,T1,T2,T3) const\' :
|
|
cannot convert parameter 4 from '...' to '...'
|
|
]
|
|
|
|
or you are using GCC and have an error like:
|
|
|
|
[pre
|
|
error: no match for call to '(const boost::function<bool ()(...)>) (...)'
|
|
note: candidates are: ... boost::function4<R,T1,T2,T3,T4>::operator()(T0,T1,T2,T3) const [with ...\]
|
|
]
|
|
|
|
then this FAQ entry may help you.
|
|
|
|
The definition of a __rule__ or __grammar__ may contain a skip parser type. If
|
|
it does, it means that non-terminal can only be used with a skip parser of a
|
|
compatible type. The error above arises when this is not the case, i.e.:
|
|
|
|
* a non-terminal defined with a skip parser type is used without a skip parser;
|
|
for example, a rule with a skip parser type is used inside a `lexeme`
|
|
directive, or a grammar with a skip parser type is used in `parse` instead of
|
|
`phrase_parse`,
|
|
* or a non-terminal is used with a skip parser of an incompatible type;
|
|
for example, a rule defined with one skip parser type calls a second rule
|
|
defined with another, incompatible skip parser type.
|
|
|
|
[note The same applies to __karma__, replacing 'skip parser' and `lexeme`
|
|
by 'delimit generator' and `verbatim`. Similarily, corresponding error
|
|
messages in __karma__ reference `boost::function3` and the 3rd
|
|
parameter (instead of the 4th).]
|
|
|
|
[endsect]
|