File Iterator

Since Spirit is a back-tracking parser, it requires at least a forward iterator. In particular, an input iterator is not sufficient. Many times it is convenient to read the input to a parser from a file, but the STL file iterators are input iterators. To get around this limitation, Spirit has a utility class file_iterator, which is a read-only random-access iterator for files.

To use the Spirit file iterator, simply create a file iterator with the path to the file you wish to parse, and then create an EOF iterator for the file:

    #include <boost/spirit/iterator/file_iterator.hpp> // the header file

    file_iterator<> first("input.dat");

    if (!first)
    {
       std::cout << "Unable to open file!\n";

       // Clean up, throw an exception, whatever
       return -1;
    }

    file_iterator<> last = first.make_end();

You now have a pair of iterators to use with Spirit . If your parser is fully parametrized (no hard-coded <char const *>), it is a simple matter of redefining the iterator type to file_iterator:

    typedef char                    char_t;
    typedef file_iterator <char_t>  iterator_t;
    typedef scanner<iterator_t>     scanner_t;
    typedef rule <scanner_t>        rule_t;

    rule_t my_rule;

    // Define your rule

    parse_info<iterator_t> info = parse(first, last, my_rule);

Of course, you don't have to deal with the scanner-business at all if you use grammars rather than rules as arguments to the parse functions. You simply pass the iterator pairs and the grammar as is:

    my_grammar g;
    parse_info<iterator_t> info = parse(first, last, g);

Generic iterator The Spirit file iterator can be parameterized with any type that is default constructible and assignable. It transparently supports large files (greater than 2GB) on systems that provide an appropriate interface. The file iterator can be useful outside of Spirit as well. For instance, the Boost.Tokenizer package requires a bidirectional iterator, which is provided by file_iterator.

See file_parser.cpp for a compilable example. This is part of the Spirit distribution.

Copyright © 2002 Jeff Westfahl

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)