| In-depth: The Parser Context |

The parser's context is yet another concept. An instance (object) of the `context` class is created before a non-terminal starts parsing and is destructed after parsing has concluded. A non-terminal is either a `rule`, a `subrule`, or a `grammar`. Non-terminals have a `ContextT` template parameter. The following pseudo code depicts what's happening when a non-terminal is invoked:

        return_type
        a_non_terminal::parse(ScannerT const& scan)
        {
            context_t ctx(/**/);
            ctx.pre_parse(/**/);

            //  main parse code of the non-terminal here...

            return ctx.post_parse(/**/);
        }

The context is provided for extensibility. Its main purpose is to expose the start and end of the non-terminal's parse member function to accomodate external hooks. We can extend the non-terminal in a multitude of ways by writing specialized context classes, without modifying the class itself. For example, we can make the non-terminal emit debug diagnostics information by writing a context class that prints out the current state of the scanner at each point in the parse traversal where the non-terminal is invoked.

Example of a parser context that prints out debug information:

        pre_parse:      non-terminal XXX is entered. The current state of the input
                        is "hello world, this is a test"

        post_parse:     non-terminal XXX has concluded, the non-terminal matched "hello world".
                        The current state of the input is ", this is a test"

Most of the time, the context will be invisible from the user's view. In general, clients of the framework need not deal directly nor even know about contexts. Power users might find some use of contexts though, thus, this is part of the public API. Other parts of the framework in other layers above the core take advantage of the context to extend non-terminals.

The `parser_context` class is the default context class that the non-terminal uses.

        struct parser_context
        {
            typedef implementation_defined attr_t;
            typedef implementation_defined base_t;
            typedef parser_context_linker<parser_context> context_linker_t;

            template <typename ParserT>
            parser_context(ParserT const& p) {}

            template <typename ParserT, typename ScannerT>
            void
            pre_parse(ParserT const& p, ScannerT const& scan) {}

            template <typename ResultT, typename ParserT, typename ScannerT>
            ResultT&
            post_parse(ResultT& hit, ParserT const& p, ScannerT const& scan)
            { return hit; }
        };

The non-terminal's `ContextT` template parameter is a concept. The `parser_context` class above is the simplest model of this concept. The default `parser_context`'s`pre_parse` and `post_parse` member functions are simply no-ops. You can think of the non-terminal's `ContextT` template parameter as the policy that governs how the non-terminal will behave before and after parsing. The client can supply her own context policy by passing a user defined context template parameter to a particular non-terminal.

Parser Context Policies
attr_t | typedef: the attribute type of the non-terminal. See the match.
| base_t | typedef: the base class of the non-terminal. The non-terminal inherits from this class.
context_linker_t | typedef: this class type opens up the possibility for Spirit to plug in additional functionality into the non-terminal parse function or even bypass the given context. This should simply be typedefed to `parser_context_linker<T>` where T is the type of the user defined context class.
| constructor | Construct the context. The non-terminal is passed as an argument to the constructor.
pre_parse | Do something prior to parsing. The non-terminal and the current scanner are passed as arguments.
post_parse | Do something after parsing. This is called regardless of the parse result. A reference to the parser's result is passed in. The context has the power to modify this. The non-terminal and the current scanner are also passed as arguments.

The `base_t` deserves further explanation. Here goes... The context is strictly a stack based class. It is created before parsing and destructed after the non-terminal's parse member function exits. Sometimes, we need auxilliary data that that exists throughout the full lifetime of the non-terminal host. Since the non-terminal inherits from the context's `base_t`, the context itself, when created, gets access to this upon construction when the non-terminal is passed as an argument to the constructor. Ditto on `pre_parse` and `post_parse`.

The non-terminal inherits from the context's `base_t` typedef. The sole requirement is that it is a class that is default constructible. The copy-construction and assignment requirements depends on the host. If the host requires it, so does the context's `base_t`. In general, it wouldn't hurt to provide these basic requirements.

Copyright © 1998-2003 Joel de Guzman
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)