[/==============================================================================
    Copyright (C) 2001-2008 Joel de Guzman
    Copyright (C) 2001-2009 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 Parsing]

Central to the library is the parser. The parser does the actual
work of recognizing a linear input stream of data read sequentially
from start to end by the supplied iterators. The parser attempts to
match the input following a well-defined set of specifications known
as grammar rules. The parser returns a `bool` to report the success or
failure. When successful, the parser calls a client-supplied semantic
action, if there is one. The semantic action extracts structural
information depending on the data passed by the parser and the
hierarchical context of the parser it is attached to.

Parsers come in different flavors. The Spirit library comes bundled with an 
extensive set of pre-defined parsers that perform various parsing tasks from 
the trivial to the complex. The parser, as a concept, has a public conceptual 
interface contract. Following the contract, anyone can write a conforming 
parser that will play along well with the library's predefined components. We 
shall provide a blueprint detailing the conceptual interface of the parser 
later.

Clients of the library generally do not need to write their own hand-coded 
parsers at all. Spirit has an immense repertoire of pre-defined parsers 
covering all aspects of syntax and semantic analysis. We shall examine this 
repertoire of parsers in the following sections. In the rare case where a 
specific functionality is not available, it is extremely easy to write a 
user-defined parser. The ease in writing a parser entity is the main reason 
for Spirit's extensibility.

[heading The API functions exposed by __qi__ ]

[heading The parse() function]

[heading The phrase_parse() function]

[heading The tokenize_and_parse() function]

[heading The tokenize_and_phrase_parse() function]

[endsect]