Quick Start

The actual preprocessing itself is a highly configurable process, 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 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 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 token to be returned from the preprocessing engine.

The main preprocessing iterators are not to be instantiated directly, but should be generated through this context object too.

    // 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 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 many 
    // of the public classes and templates and it is returned 
    // from the iterators itself.
    typedef wave::context<std::string::iterator, 
                wave::cpplexer::lex_token<> >
            context_t;

    // The C++ preprocessor iterators shouldn't be constructed 
    // directly. These are to be generated through a 
    // wave::context<> object. Additionally this 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");
    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 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 no #include or #line directives are encountered, which in turn will alter the current filename.

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 Hartmut Kaiser

Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.