[/==============================================================================
    Copyright (C) 2001-2008 Joel de Guzman
    Copyright (C) 2001-2008 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:basics Parser Basics]

[heading Lazy Argument]

Some parsers (e.g. primitives and non-terminals) may take in additional
attributes. Such parsers take the form:

    p(a1, a2,..., aN)

where `p` is a parser. Each of the arguments (a1 ... aN) can either be an
immediate value, or a function, `f`, with signature:

    T f(Unused, Context)

where `T`, the function's return value, is compatible with the argument
type expected and `Context` is the parser's __context__ type (The first
argument is __unused__ to make the `Context` the second argument. This
is done for uniformity with __actions__).

[heading Character Encoding Namespace]

Some parsers need to know which character set a `char` or `wchar_t` is
operating on. For example, the `alnum` parser works differently with
ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
the parser with the character set. 

We have a namespace for each character set Spirit will be supporting.
That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
in the future, `unicode`). In each of the character encoding namespaces,
we place tagged versions of parsers such as `alnum`, `space` etc. 

Example:

    using boost::spirit::ascii::space; // use the ASCII space parser
    
Namespaces:

* boost::spirit::ascii
* boost::spirit::iso8859_1
* boost::spirit::standard
* boost::spirit::standard_wide

For ease of use, the components in this namespaces are also brought into
the qi sub-namespaces with the same names:

* boost::spirit::qi::ascii
* boost::spirit::qi::iso8859_1
* boost::spirit::qi::standard
* boost::spirit::qi::standard_wide

[heading Examples]

All sections in the reference present some real world examples. The
examples use a common test harness to keep the example code as minimal
and direct to the point as possible. The test harness is presented
below.

Some includes:

[reference_includes]

Our test functions:

These functions test the parsers without attributes.

[reference_test]

These functions test the parsers with user supplied attributes.

[reference_test_attr]

The `print_info` utility function prints information contained in the
__info__ class.

[reference_print_info]

[heading String]

[heading Header]

    // forwards to <boost/spirit/home/support/string_traits.hpp>
    #include <boost/spirit/support_string_traits.hpp>

A string can be any object `s`, of type, `S`, that satisfies the
following expression traits:

[table
    [[Expression]                               [Semantics]]
    [[`boost::spirit::traits::is_string<S>`]    [Metafunction that evaluates to `mpl::true_` if 
                                                a certain type, `S` is a string, `mpl::false_`  
                                                otherwise (See __mpl_boolean_constant__).]]
    [[`boost::spirit::traits::char_type_of<S>`] [Metafunction that returns the underlying 
                                                char type of a string type, `S`.]]
    [[`boost::spirit::traits::get_c_string(s)`] [Function that returns the underlying 
                                                raw C-string from `s`.]]
    [[`boost::spirit::traits::get_begin(s)`]    [Function that returns an __stl__ iterator from `s`
                                                that points to the beginning the string.]]                                                
    [[`boost::spirit::traits::get_end(s)`]      [Function that returns an __stl__ iterator from `s`
                                                that points to the end of the string.]]
                                                
]

[heading Models]

Predefined models include:

* any literal string, e.g. "Hello, World", 
* a pointer/reference to a null-terminated array of characters
* a `std::basic_string<Char>`

The namespace `boost::spirit::traits` is open for users to provide their
own specializations. The customization points implemented by __qi__ usable
to customize the behavior of parsers are described in the section 
__sec_customization_points__.

[endsect]