Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext
Iterator Based Parser 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.

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.

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
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);
}}}
[Note] Note

Starting with Spirit V2.5 (distributed with Boost V1.47) the placeholder _val can be used in semantic actions attached to top level parser components. In this case _val refers to the supplied attribute as a whole. For API functions taking more than one attribute argument _val will refer to a Fusion vector or references to the attributes.

Spirit.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] 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.

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.

Attr

An attribute type utilized to create the corresponding parser type from.

Attr1, Attr2, ..., AttrN

One or more attributes.


PrevUpHomeNext