[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2010 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:parse_api Parser API]

[//////////////////////////////////////////////////////////////////////////////]
[section:iterator_api Iterator Based Parser API]

[heading Description]

The library provides a couple of free functions to make parsing a snap.
These parser functions have two forms. The first form `parse` works on
the character level. The second `phrase_parse` works on the phrase level
and requires skip parser. Both versions can take in attributes by
reference that will hold the parsed values on a successful parse.

[heading Header]

    // forwards to <boost/spirit/home/qi/parse.hpp>
    #include <boost/spirit/include/qi_parse.hpp>

For variadic attributes:

    // forwards to <boost/spirit/home/qi/parse_attr.hpp>
    #include <boost/spirit/include/qi_parse_attr.hpp>

The variadic attributes version of the API allows one or more
attributes to be passed into the parse functions. The functions taking two 
or more are usable when the parser expression is a __qi_sequence__ only.
In this case each of the attributes passed have to match the corresponding 
part of the sequence.

For the API functions deducing the correct (matching) parser type from the 
supplied attribute type:

    // forwards to <boost/spirit/home/qi/detail/parse_auto.hpp>
    #include <boost/spirit/include/qi_parse_auto.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::qi::parse` ]]
    [[`boost::spirit::qi::phrase_parse` ]]
    [[`boost::spirit::qi::skip_flag::postskip` ]]
    [[`boost::spirit::qi::skip_flag::dont_postskip` ]]
]

[heading Synopsis]

    namespace boost { namespace spirit { namespace qi
    {
        template <typename Iterator, typename Expr>
        inline bool
        parse(
            Iterator& first
          , Iterator last
          , Expr const& expr);

        template <typename Iterator, typename Expr
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline bool
        parse(
            Iterator& first
          , Iterator last
          , Expr const& expr
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);

        template <typename Iterator, typename Expr, typename Skipper>
        inline bool
        phrase_parse(
            Iterator& first
          , Iterator last
          , Expr const& expr
          , Skipper const& skipper
          , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip);

        template <typename Iterator, typename Expr, typename Skipper
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline bool
        phrase_parse(
            Iterator& first
          , Iterator last
          , Expr const& expr
          , Skipper const& skipper
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);

        template <typename Iterator, typename Expr, typename Skipper
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline bool
        phrase_parse(
            Iterator& first
          , Iterator last
          , Expr const& expr
          , Skipper const& skipper
          , BOOST_SCOPED_ENUM(skip_flag) post_skip
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);
    }}}

__qi__ parser API functions based on the automatic creation of the matching 
parser type:

    namespace boost { namespace spirit { namespace qi
    {
        template <typename Iterator, typename Attr>
        inline bool
        parse(
            Iterator& first
          , Iterator last
          , Attr& attr);


        template <typename Iterator, typename Attr, typename Skipper>
        inline bool
        phrase_parse(
            Iterator& first
          , Iterator last
          , Attr& attr
          , Skipper const& skipper
          , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip);
    }}}

All functions above return `true` if none of the involved parser components
failed, and `false` otherwise. 

The maximum number of supported arguments is limited by the preprocessor 
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). 

[note The variadic functions with two or more attributes internally combine 
      references to all passed attributes into a `fusion::vector` and forward 
      this as a combined attribute to the corresponding one attribute function.]

The `phrase_parse` functions not taking an explicit `skip_flag` as one of their 
arguments invoke the passed skipper after a successful match of the parser 
expression. This can be inhibited by using the other versions of that function 
while passing `skip_flag::dont_postskip` to the corresponding argument.

[table
    [[Parameter]                    [Description]]
    [[`Iterator`]                   [__fwditer__ pointing to the source to parse.]]
    [[`Expr`]                       [An expression that can be converted to a Qi parser.]]
    [[`Skipper`]                    [Parser used to skip white spaces.]]
    [[`Attr`]                       [An attribute type utilized to create the corresponding 
                                     parser type from.]]
    [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]

[endsect] [/ Iterator Based Parser API]

[//////////////////////////////////////////////////////////////////////////////]
[section:stream_api Stream Based Parser API]

[heading Description]

The library provides a couple of Standard IO __iomanip__ allowing to integrate
__qi__ input parsing facilities with Standard input streams.
These parser manipulators have two forms. The first form, `match`, works on
the character level. The second `phrase_match` works on the phrase level
and requires a skip parser. Both versions can take in attributes by reference 
that will hold the parsed values on a successful parse.

[heading Header]

    // forwards to <boost/spirit/home/qi/stream/match_manip.hpp>
    #include <boost/spirit/include/qi_match.hpp>

For variadic attributes:

    // forwards to <boost/spirit/home/qi/stream/match_manip_attr.hpp>
    #include <boost/spirit/include/qi_match_attr.hpp>

The variadic attributes version of the API allows one or more
attributes to be passed into the parse manipulators. The manipulators taking 
two or more attributes are usable when the parser expression is a 
__qi_sequence__ only. In this case each of the attributes passed have to 
match the corresponding part of the sequence.

For the API functions deducing the correct (matching) parser type from the 
supplied attribute type:

    // forwards to <boost/spirit/home/qi/match_auto.hpp>
    #include <boost/spirit/include/qi_match_auto.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::qi::match` ]]
    [[`boost::spirit::qi::phrase_match` ]]
    [[`boost::spirit::qi::skip_flag::postskip` ]]
    [[`boost::spirit::qi::skip_flag::dont_postskip` ]]
]

[heading Synopsis]

    namespace boost { namespace spirit { namespace qi
    {
        template <typename Expr>
        inline <unspecified> 
        match(
            Expr const& xpr);

        template <typename Expr
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline <unspecified> 
        match(
            Expr const& xpr
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);

        template <typename Expr, typename Skipper>
        inline <unspecified> 
        phrase_match(
            Expr const& expr
          , Skipper const& s
          , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip);

        template <typename Expr, typename Skipper
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline <unspecified> 
        phrase_match(
            Expr const& expr
          , Skipper const& s
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);

        template <typename Expr, typename Skipper
          , typename Attr1, typename Attr2, ..., typename AttrN>
        inline <unspecified> 
        phrase_match(
            Expr const& expr
          , Skipper const& s
          , BOOST_SCOPED_ENUM(skip_flag) post_skip
          , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);
    }}}

__qi__ parser API functions based on the automatic creation of the matching 
parser type:

    namespace boost { namespace spirit { namespace qi
    {
        template <typename Attr>
        inline <unspecified> 
        match(
            Attr& attr);

        template <typename Attr, typename Skipper>
        inline <unspecified> 
        phrase_match(
            Attr& attr
          , Skipper const& s
          , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip);
    }}}

All functions above return a standard IO stream manipulator instance (see 
__iomanip__), which when streamed from an input stream will result in parsing
the input using the embedded __qi__ parser expression. Any error (or failed 
parse) occurring during the invocation of the __qi__ parsers will be reflected
in the streams status flag (`std::ios_base::failbit` will be set).

The maximum number of supported arguments is limited by the preprocessor 
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). 

[note The variadic manipulators with two or more attributes internally combine 
      references to all passed attributes into a `fusion::vector` 
      and forward this as a combined attribute to the corresponding manipulator
      taking one attribute.]

The `phrase_match` manipulators not taking an explicit `skip_flag` as one of their 
arguments invoke the passed skipper after a successful match of the parser 
expression. This can be inhibited by using the other versions of that manipulator 
while passing `skip_flag::dont_postskip` to the corresponding argument.

[heading Template parameters]

[table
    [[Parameter]                    [Description]]
    [[`Expr`]                       [An expression that can be converted to a Qi parser.]]
    [[`Skipper`]                    [Parser used to skip white spaces.]]
    [[`Attr`]                       [An attribute type utilized to create the corresponding 
                                     parser type from.]]
    [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]

[endsect] [/ Stream Based Parser API]

[//////////////////////////////////////////////////////////////////////////////]
[section:create_parser API for Automatic Parser Creation]

[heading Description]

The library implements a special API returning a parser instance for a 
supplied attribute type. This function finds the best matching parser type 
for the attribute based on a set of simple matching rules (as outlined in the 
table below) applied recursively to the attribute type. The returned parser
can be utilized to match input for the provided attribute.

[heading Header]

    // forwards to <boost/spirit/home/qi/auto.hpp>
    #include <boost/spirit/include/qi_auto.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::qi::create_parser`]]
    [[`boost::spirit::traits::create_parser_exists`]]
]

[heading Synopsis]

    namespace boost { namespace spirit { namespace qi
    {
        template <typename Attr>
        inline <unspecified> 
        create_parser();
    }}}

The returned instance can be directly passed as the parser (or the skipping
parser) to any of the __qi__ API functions. Additionally it
can be assigned to a rule as the rules right hand side expression. This 
function will return a valid parser type only if the meta function 
`traits::create_parser_exists` returns `mpl::true_`. Otherwise it will fail
compiling.

    namespace boost { namespace spirit { namespace traits
    {
        template <typename Attr>
        struct create_parser_exists;
    }}}

The meta function evaluates to `mpl::true_` if `create_parser` would return 
a valid parser for the given type `Attr`.

The following table outlines the mapping rules from the attribute type to the
parser type. These rules are applied recursively to create the parser 
type which can be used to match input for the given attribute type.

[table 
    [[Attribute type]   [Generator type]]
    [[`char`, `wchar_t`]      [`standard::char_`, `standard_wide::char_`]]
    [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
    [[`unsigned short`, `unsigned int`, `unsigned long`] 
                              [`ushort_`, `uint_`, `ulong_`]]
    [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
    [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
    [[`long long`, `unsigned long long`]
                              [`long_long`, `ulong_long`]]
    [[`bool`]                 [`bool_`]]
    [[Any (STL) container]    [Kleene Star (unary `'*'`)]]
    [[Any Fusion sequence]    [Sequence operator (`'<<'`)]]
    [[`boost::optional<>`]    [Optional operator (unary `'-'`)]]
    [[`boost::variant<>`]     [Alternative operator (`'|'`)]]
]

[important The mapping for the parsers `long_long` and `ulong_long` are only 
        available on platforms where the preprocessor constant 
        `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native 
        support for `long long` and `unsigned long long` (64 bit) signed and 
        unsigned integer types).]

[heading Template parameters]

[table
    [[Parameter]                    [Description]]
    [[`Attr`]                       [An attribute type utilized to create the corresponding 
                                     parser type from.]]
]

[endsect] [/ API for Automatic Parser Creation]

[endsect]