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.