Quick Start

The actual preprocessing itself is highly configurable, so obviously you have to define a couple of parameters to control this process, such as:

 include search pathes, which define, where to search for files to be included with #include <...> and #include "..." directives
 which macros to predefine and which of the predefined macros to undefine
 several other options as for instance to control, whether to enable several extensions to the C++ Standard (as for instance variadics and placemarkers) or not.

You can access all these processing parameters through the boost::wave::context object. So you have to instantiate one object of this type to use the Wave library. For more information about the context template class please refer to the class reference here. To instantiate the boost::wave::context object you have to supply at least two template parameters: the iterator type of the underlying input stream to use and the type of the lexer iterator to be used as the token source for the preprocessing engine.

The main preprocessing iterators are not to be instantiated directly, but should be generated through this context object too. The following code snippet is taken from the quick_start sample, which shows a minimal usage scenario for Wave.

    // The following preprocesses a given input file.
    // Open the file and read it into a string variable
    std::ifstream instream("input.cpp");
    std::string input(
        std::istreambuf_iterator<char>(instream.rdbuf());
        std::istreambuf_iterator<char>());

    // The template boost::wave::cpplexer::lex_token<> is the  
    // token type to be used by the Wave library.
    // This token type is one of the central types throughout 
    // the library, because it is a template parameter to some 
    // of the public classes and templates and it is returned 
    // from the iterators itself.
    // The template boost::wave::cpplexer::lex_iterator<> is
    // the lexer iterator to use as the token source for the
    // preprocessing engine. In this case this is parametrized
    // with the token type.
    typedef boost::wave::cpplexer::lex_iterator<
            boost::wave::cpplexer::lex_token<> >
        lex_iterator_t;
    typedef boost::wave::context<
            std::string::iterator, lex_iterator_t>
        context_t;

    // The C++ preprocessor iterators shouldn't be constructed 
    // directly. These are to be generated through a 
    // boost::wave::context<> object. Additionally this  
    // boost::wave::context<> object is to be used to initialize 
    // and define different parameters of the actual preprocessing.
    context_t ctx(input.begin(), input.end(), "input.cpp");

    // At this point you may want to set the parameters of the
    // preprocessing as include pathes and/or predefined macros.
        ctx.add_include_path("...");
        ctx.add_macro_definition(...);

    // Get the preprocessor iterators and use them to generate 
    // the token sequence.
    context_t::iterator_t first = ctx.begin();
    context_t::iterator_t last = ctx.end();

    // The preprocessing of the input stream is done on the fly 
    // behind the scenes during the iteration over the 
    // context_t::iterator_t based stream. 
       while (first != last) {
           std::cout << (*first).get_value();
           ++first;
       }

The constructor of the boost::wave::context object can take a pair of arbitrary iterator types (at least input_iterator type iterators) to the input stream, from where should be read the data to be preprocessed. The third parameter supplies a filename, which is used subsequently inside the preprocessed tokens returned from the preprocessing to indicate the token position inside the underlying input stream. Note though, that this filename is used only as long as no #include or #line directives are encountered, which in turn will alter the current filename reported.

The iteration over the preprocessed tokens is relativly straight forward. Just get the starting and the ending iterators from the context object (maybe after initializing some include search paths) and you are done! The dereferencing of the iterator will return the preprocessed tokens, which are generated on the fly from the input stream. To get further information about the token type, you may want to look here.

Copyright © 2003-2004 Hartmut Kaiser

Use, modification and distribution is subject to 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)