HELP READ_LISTS_IN_FILE                                     Aaron Sloman
                                                            October 2004


LIB READ_LISTS_IN_FILE

This is an autoloadable library that provides a procedure for reading
a list of text items from a file containing things like

    [ the cat sat ]
    [ on every mat]
    [ 1 2 3 4 ]
    [ 'fifty five' mice]
    [ ]

and returning a list of lists. E.g. if the file mydata.p contains
the above text, then the library can be used thus:

    ;;; make pop11 print string quotes
    true -> pop_pr_quotes;
    ;;; read the list of lists and print it out:
    read_lists_in_file('mydata.p') ==>
    ** [[the cat sat] [on every mat] [1 2 3 4] ['fifty five' mice] []]

HOW IT WORKS

The procedure read_lists_in_file uses discin to create a character repeater
for the file.

It uses incharitem to create an item repeater from the character
repeater.

It uses pdtolist to create a dynamic list from the item repeater.

It uses the following procedure defined in the same file:

    make_all_lists(items) -> lists;

to create a list of lists from a list of text items containing pairs
of matched square brackets.

Note that make_all_lists is defined so as NOT to cope with nested
lists.

This limitation can easily be removed by making it recursive, but
that will make it harder to check for errors in programs that create
files representing lists of non-nested lists but sometimes fail
to write the closing list bracket "]" for one or more lists.
This version is for novice-users doing simple things.


Procedures provided:
    define make_all_lists(items) -> lists;
        ;;; given a list of items including occurrences of
        ;;; matched pairs "[" ... "]" make a list of lists.
        ;;; the lists must not be nested. They can contain words,
        ;;; strings or numbers.


    define read_lists_in_file(filename) -> lists;
        ;;; given the name of a text file in approprpiate format
        ;;; return a list of lists read from the file.
        ;;; the lists must not be nested. They can contain words,
        ;;; strings or numbers.


I don't know if discin works on windows poplog. If not this will
not work on Windows.


TO TRY THIS OUT
Make a suitable file, E.G. containing list expressions such as

    [ the cat sat ]
    [ on every mat]
    [ 1 2 3 4 ]
    [ 'fifty five' mice]
    [ ]
    [ this is a list that
        extends over several
        lines ]


and test it thus:

    read_lists_in_file('mydata.p') ==>

It should print out something like:

    ** [[the cat sat]
        [on every mat]
        [1 2 3 4]
        ['fifty five' mice]
        []
        [this is a list that extends over several lines]]


--- $poplocal/local/help/read_lists_in_file
--- Copyright University of Birmingham 2004. All rights reserved.
