A library for iterating through the lines in a series of files. Very similar to the Python module of the same name.

It allows the programmer to automatically take filenames from the command line arguments (via input and input_state), as well as specify them as a vector directly (input_vec and input_vec_state). The files are opened as necessary, so any files that can't be opened only cause an error when reached in the iteration.

On the command line, stdin is represented by a filename of - (a single hyphen) and in the functions that take a vector directly (e.g. input_vec) it is represented by None. Note stdin is not reset once it has been finished, so attempting to iterate on [None, None] will only take input once unless io::stdin().seek(0, SeekSet) is called between.

The make_path_option_vec function handles converting a list of file paths as strings to the appropriate format, including the (optional) conversion of "-" to stdin.

Basic

In many cases, one can use the input_* functions without having to handle any FileInput structs. E.g. a simple cat program

for input |line| {
    io::println(line)
}

or a program that numbers lines after concatenating two files

for input_vec_state(make_path_option_vec([~"a.txt", ~"b.txt"])) |line, state| {
    io::println(fmt!("%u: %s", state.line_num,
                               line));
}

The two input_vec* functions take a vec of file names (where empty means read from stdin), the other two functions use the command line arguments.

Advanced

For more complicated uses (e.g. if one needs to pause iteration and resume it later), a FileInput instance can be constructed via the from_vec, from_vec_raw and from_args functions.

Once created, the each_line (from the std::io::ReaderUtil trait) and each_line_state methods allow one to iterate on the lines; the latter provides more information about the position within the iteration to the caller.

It is possible (and safe) to skip lines and files using the read_line and next_file methods. Also, FileInput implements std::io::Reader, and the state will be updated correctly while using any of those methods.

E.g. the following program reads until an empty line, pauses for user input, skips the current file and then numbers the remaining lines (where the numbers are from the start of each file, rather than the total line count).

let input = FileInput::from_vec(pathify([~"a.txt", ~"b.txt", ~"c.txt"],
                                         true));

for input.each_line |line| {
    if line.is_empty() {
        break
    }
    io::println(line);
}

io::println("Continue?");

if io::stdin().read_line() == ~"yes" {
    input.next_file(); // skip!

    for input.each_line_state |line, state| {
       io::println(fmt!("%u: %s", state.line_num_file,
                                  line))
    }
}