Iterator Based Parse API

| Home | Libraries | People | FAQ | More

##### Iterator Based Parse API

###### 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.

###### 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 Sequence only. In this case each of the attributes passed have to match the corresponding part of the sequence.

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::qi::parse`
`boost::spirit::qi::phrase_parse`
`boost::spirit::qi::skip_flag::postskip`
`boost::spirit::qi::skip_flag::dont_postskip`

###### Synopsis

    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);

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 function 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 inhbited by using the other versions of that function while passing `skip_flag::dont_postskip` to the corresponding argument.

Parameter | Description
--- | ---
`Iterator` | `ForwardIterator` pointing to the source to parse.
`Expr` | An expression that can be converted to a Qi parser.
`Skipper` | Parser used to skip white spaces.
`Attr1`, `Attr2`, ..., `AttrN` | One or more attributes.