HELP FILESEQUENCE                           David Young
                                            Nov 1993, revised Oct 1998

LIB * FILESEQUENCE (available when LIB * POPVISION is loaded) makes it
easy to write and read sequences of files whose names incorporate an
integer index.

         CONTENTS - (Use <ENTER> g to access required sections)

 -- Introduction
 -- File name sequences - filesequence
 -- Writing sequences - filesout
 -- . . . Example
 -- Reading sequences - filesin

-- Introduction -------------------------------------------------------

The library was designed for image sequences, but may be useful in other
contexts too. For example, you may want to write files in sequences with
names like

    image001.ras    image002.ras    image003.ras

or like

    file8       file9       file10      file11

or perhaps

    /home/fred/data/images/picture0015.pic
    /home/fred/data/images/picture0020.pic
    /home/fred/data/images/picture0025.pic

and read them back later.

Note that *DATAINOUT provides a way of writing successive pieces of data
to a single file and may be a more efficient alternative.

-- File name sequences - filesequence ---------------------------------

filesequence(base_name, nwid, suffix, list) -> repeater;
filesequence(base_name, nwid, suffix) -> repeater;
filesequence(base_name, nwid, suffix, n0) -> repeater;
filesequence(base_name, nwid, suffix, n0, ninc) -> repeater;
filesequence(base_name, nwid, suffix, n0, ninc, n1) -> repeater;
        This returns a repeater procedure which when called successively
        returns file names from a sequence like those above.

        base_name is a string giving the part of the path name before
        the numerical index.

        nwid is an integer, giving the number of characters in the file
        names to devote to the numerical index, or <false> for a
        variable-width number using only the characters necessary.

        suffix is a string giving the part of the file name after the
        numerical index.

        list is a list of integers, each to be plugged into the filename
        in turn. Alternatively, the integers can be specified in a way
        analogous to a for loop, as follows.

        n0 is an integer giving the index of the first file to write. If
        this is omitted, and list is not given, n0 defaults to 1.

        ninc is an integer giving the increment to add to the index
        between naming each file. It may be negative. If omitted it
        defaults to 1.

        n1 is optional. If given, it is an integer specifying the index
        of the last file in the sequence.

        The procedure repeater is returned. The first time this is
        called -

                repeater() -> filename

        - it returns a string giving the first file name in the
        sequence. Each time it is called thereafter it returns a string
        with the next file name in the sequence.

            Note that successive strings returned by repeater may use
            the same memory, so the contents of the string must not be
            changed by the caller, and the string must be copied if it
            is to be accessed after a subsequent call to repeater.

            If n1 is given then termin is returned once the index has
            gone past n1 (in either direction, depending on the sign of
            ninc).

            repeater also has an updater, which when called with no
            arguments -

                -> repeater()

            - resets the position in the sequence back to the start, so
            that the next ordinary call to the repeater reads the first
            file in the sequence.

-- Writing sequences - filesout ---------------------------------------

filesout(writer, base_name, ...) -> consumer;
        writer must be a procedure whose updater writes data to a file,
        for example

                image -> sunrasterfile('image88.ras')

        See *sunrasterfile and *arrayfile for suitable procedures to
        use for writing arrays.

        The remaining arguments are as for filesequence.

        The procedure consumer is returned. This takes one argument, the
        data structure to write, or false. If n1 is not given,
        consumer returns no result so is called thus:

                consumer(data)

        If n1 is specified, consumer returns a boolean result:

                consumer(data) -> finished

            In both cases, if data is false, the index is incremented,
            but nothing is written to disc. Otherwise, writer is called
            to write data to a file with the next name in the sequence.

            If n1 was specified, the result finished will be false until
            the last file has been written, and then will be true. Once
            consumer has returned true, no more files are written.

-- . . . Example ------------------------------------------------------

For example, the sequences above would be generated with:

    filesout(sunrasterfile, 'image', 3, '.ras') -> consumer;

    filesout(mywriter, 'file', false, '', 8) -> consumer;

    filesout(arrayfile, '/home/fred/data/image/picture', 4, '.pic',
                15, 5) -> consumer;

respectively, followed in each case by 3 calls to consumer. (That is,
assuming that mywriter was a procedure with an appropriate updater.)

To generate the first sequence using the n1 argument to specify that
only 3 files were to be written, something like this is used:

    filesout(sunrasterfile, 'image', 3, '.ras', 1, 1, 3) -> consumer;
    repeat
        < Code to generate data >
    quitif(consumer(data)) endrepeat;

-- Reading sequences - filesin ----------------------------------------

filesin(reader, base_name, ...) -> repeater;
        This reverses filesout in effect. reader is a procedure like
        sunrasterfile or arrayfile that takes a filename as argument and
        returns a data structure.  The other arguments are as for
        filesequence.

        filesin with a first argument of identfn is the same as
        filesequence.

        repeater is a procedure of no arguments, which when called -

                repeater() -> data

        - returns a data structure read from the next file in the
        sequence, using reader.  If the file does not exist, repeater
        returns false (except when reader is identfn, in which case the
        file name is still returned). If n1 was given, and the index
        goes past n1, then termin is returned.

            repeater also has an updater, which when called with no
            arguments -

                -> repeater()

            - resets the position in the sequence back to the start, so
            that the next ordinary call to the repeater reads the first
            file in the sequence.

--- $popvision/help/filesequence
--- Copyright University of Sussex 1993. All rights reserved.
