Boolean Parser (bool_)

| Home | Libraries | People | FAQ | More

##### Boolean Parser (`bool_`)

###### Description

The `bool_parser` can parse booleans of arbitrary type, `B`. The boolean base type `T` can be a user defined boolean type as long as the type follows certain expression requirements (documented below).

###### Header

    // forwards to <boost/spirit/home/qi/numeric/bool.hpp>
    #include <boost/spirit/include/qi_bool.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::bool_ // alias: boost::spirit::qi::bool_`
`boost::spirit::true_ // alias: boost::spirit::qi::true_`
`boost::spirit::false_ // alias: boost::spirit::qi::false_`

###### Synopsis

    template <typename T, typename BooleanPolicies>
    struct bool_parser;

###### Template parameters

Parameter | Description | Default
--- | --- | ---
`B` | The boolean type of the boolean parser. | `bool`
`BooleanPolicies` | Policies control the parser's behavior. | `bool_policies<B>`

###### Model of

> `PrimitiveParser`

Notation

`BP`

  A boolean `Policies` (type).

`b`

  An object of `B`, the numeric base type.

`boolean`

  Numeric literal, any boolean value, or a Lazy Argument that evaluates to a boolean value.

`f`, `l`

  `ForwardIterator`. first/last iterator pair.

`attr`

  An attribute value.

`Context`

  The type of the parse context of the current invocation of the `bool_` parser.

`ctx`

  An instance of the parse context, `Context`.

###### Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in `PrimitiveParser`.

Expression | Semantics
--- | ---
    bool_
| Parse a boolean using the default policies (`bool_policies<T>`).
    lit(boolean)
    bool_(boolean)
| Match the literal `boolean` using the default policies (`bool_policies<T>`). The parser will fail if the parsed value is not equal to the specified value.
    true_
    false_
| Match `"true"` and `"false"`, respectively.
    bool_parser<
        T, BoolPolicies
    >()
| Parse a real of type `T` using `BoolPolicies`.
    bool_parser<
        T, BoolPolicies
    >()(boolean)
| Match the literal `boolean` of type `T` using `BoolPolicies`. The parser will fail if the parsed value is not equal to the specified value.

| Note
All boolean parsers properly respect the `no_case``[]` directive.

###### Attributes

Expression | Attribute
--- | ---
    lit(boolean)
| `unused`
    true_
    false_
    bool_
    bool_(boolean)
| `bool`
    bool_parser<
        T, BoolPolicies
    >()
    bool_parser<
        T, BoolPolicies
    >()(num)
| `T`

###### Complexity

> O(N), where N is the number of characters being parsed.

###### Minimum Expression Requirements for `B`

The boolean type, `B`, the minimum expression requirements listed below must be valid. Take note that additional requirements may be imposed by custom policies.

Expression | Semantics
--- | ---
`B(bool)` | Constructible from a `bool`.

###### Boolean `Policies`

The boolean `Policies` template parameter is a class that groups all the policies that control the parser's behavior. Policies control the boolean parsers' behavior.

The default is `bool_policies<bool>`. The default is provided to take care of the most common case (there are many ways to represent, and hence parse, boolean numbers). In most cases, the default policies are sufficient and can be used straight out of the box. They are designed to parse boolean value of the form `"true"` and `"false"`.

###### Boolean `Policies` Expression Requirements

For models of boolean `Policies` the following expressions must be valid:

Expression | Semantics
--- | ---
`BP::parse_true(f, l, attr, ctx)` | Parse a `true` value.
`BP::parse_false(f, l, attr, ctx)` | Parse a `false` value.

The functions should return true if the required representations of `true` or `false` have been found. In this case the attribute `n` should be set to the matched value (`true` or `false`).

###### Boolean `Policies` Specializations

The easiest way to implement a proper boolean parsing policy is to derive a new type from the the type `bool_policies` while overriding the aspects of the parsing which need to be changed. For example, here's the implementation of a boolean parsing policy interpreting the string `"eurt"` (i.e. "true" spelled backwards) as `false`:

    struct backwards_bool_policies : qi::bool_policies<>
    {
        // we want to interpret a 'true' spelled backwards as 'false'
        template <typename Iterator, typename Attribute, typename Context>
        static bool
        parse_false(Iterator& first, Iterator const& last, Attribute& attr, Context& ctx)
        {
            namespace qi = boost::spirit::qi;
            if (qi::detail::string_parse("eurt", first, last, qi::unused, qi::unused))
            {
                spirit::traits::assign_to(false, attr, ctx);    // result is false
                return true;
            }
            return false;
        }
    };

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some using declarations:

    using boost::phoenix::val;
    using boost::spirit::qi::bool_;
    using boost::spirit::qi::bool_parser;
    using boost::spirit::qi::lit;

Basic real number parsing:

    // bool
    test_parser("true", bool_);
    test_parser("false", bool_);
    test_parser("true", bool_(true));
    test_parser("false", bool_(false));
    test_parser("true", bool_(val(true)));
    test_parser("false", bool_(val(false)));

    // literals
    test_parser("true", lit(true));
    test_parser("false", lit(false));
    test_parser("true", lit(val(true)));
    test_parser("false", lit(val(false)));

A custom real number policy:

    ///////////////////////////////////////////////////////////////////////////////
    //  These policies can be used to parse "eurt" (i.e. "true" spelled backwards)
    //  as `false`
    ///////////////////////////////////////////////////////////////////////////////
    struct backwards_bool_policies : boost::spirit::qi::bool_policies<>
    {
        // we want to interpret a 'true' spelled backwards as 'false'
        template <typename Iterator, typename Attribute>
        static bool
        parse_false(Iterator& first, Iterator const& last, Attribute& attr)
        {
            namespace qi = boost::spirit::qi;
            if (qi::detail::string_parse("eurt", first, last, qi::unused))
            {
                namespace traits = boost::spirit::traits;
                traits::assign_to(false, attr);    // result is false
                return true;
            }
            return false;
        }
    };

And its use:

    bool_parser<bool, backwards_bool_policies> backwards_bool;
    test_parser("true", backwards_bool);
    test_parser("eurt", backwards_bool);
    test_parser("true", backwards_bool(true));
    test_parser("eurt", backwards_bool(false));