HELP LISTS                                           Andrew Law Apr 1987

This help file describes some of the on-line help files relating to
list processing in Pop-11.

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

  1   Overviews of List Processing
  2   List Syntax
  3   Pattern Matching
  4   Accessing Lists
  5   Examining Characteristics of Lists (e.g, membership,length)
  6   Processing Elements of Lists (e.g, sorting, deleting, reversing)
  7   Iteration over Lists
  8   Copying Lists
  9   Dynamic Lists
 10   List Input and Output (e.g, reading in printing out)
 11   Lists and Pair Manipulation
 12   Efficiency and Fast Procedures


-----------------------------------------------------------------------
1  Overviews of List Processing
-----------------------------------------------------------------------

TEACH * LISTS
    Introduction to lists and matching (for beginners)
TEACH * LISTSUMMARY
    Summary of list processing facilities with examples
REF * LISTS
    Built-in list and pair processing facilities (advanced)
HELP * PAIR
    Short menu of help files relating to lists pairs
HELP * MORELISTS
    Longer menu of help files relating to lists
HELP * LISTQUESTIONS, * LISTANSWERS
    Exercises and answers


-----------------------------------------------------------------------
2  List Syntax
-----------------------------------------------------------------------

There is a special syntax for lists in Pop-11, which involves writing
the contents of the list between square brackets.

HELP * SQUAREBRA
    Constructing lists using square brackets

Constructing a list using the value of a variable or an expression:

TEACH * PERCENT, HELP * PERCENT
    Using the percent sign
TEACH * ARROW
    Using uparrows (the "^" symbol)
HELP * INSTANCE
    Creating a "filled in" instance of a pattern

Other means of creating lists:

HELP * CONSPAIR
    Constructing lists from pairs


-----------------------------------------------------------------------
3  Pattern Matching
-----------------------------------------------------------------------

HELP * MATCHES
    Basic Pop-11 matching operation
TEACH * MATCHES
    Tutorial introduction to matching in pop-11
HELP * SYSMATCH
    Some more facilities in the matcher
TEACH * MATCHES2, * MOREMATCH
    More material for beginners
HELP * MATCHESALLOF
    Checking for multiple matches
HELP * MATCHESONEOF
    Checking for alternative matches
HELP * ISIN
    Looking for a match in a list of lists
HELP * FOREACH, * IT
    Iterating over matches in a list of lists
HELP * AREIN
    Looking for multiple matches in a list of lists
HELP * FOREVERY
    Iterating over multiple matches in a list of lists


-----------------------------------------------------------------------
4  Accessing Lists
-----------------------------------------------------------------------

Various ways of accessing parts of lists by position or number, rather
than matching against particular items

HELP * HD
    Getting the head (the first first element)
HELP * TL
    Getting the tail (the rest)
HELP * DEST
    Getting both
HELP * LASTPAIR
    Examining or changing the last pair of a list
HELP * FRONT
    Getting the first component of a pair
HELP * BACK
    Getting the second component of a pair
HELP * DESTPAIR
    Getting the first and second components
HELP * SUBSCRL
    Examining or changing the Nth element of a list
HELP * LAST
    Examining or changing the last element of a list
HELP * ALLBUTLAST
    Examining the initial segment of a list
HELP * ALLBUTFIRST
    Examining the final segment of a list
HELP * ONEOF
    Selecting a random element from a list
TEACH * ONEOF
    Tutorial introduction to oneof (for beginners)
REF * DL, * EXPLODE
    Putting all the elements of a list onto the stack
REF * FILL
    Putting items on the stack into a list or structure. (Also the
    updater of dl or explode)

These procedures (e.g, * hd, * tl, * dest, * front, * back, * destpair)
differ according to whether they deal with "dynamic lists" or not - see
section on dynamic lists.


-----------------------------------------------------------------------
5  Examining Characteristics of Lists (e.g, membership,length)
-----------------------------------------------------------------------

HELP * EQUAL
    Checking for list equality

Membership of an object in a list

HELP * MEMBER
    Using '=' to compare elements
HELP * LMEMBER
    Using '==' to compare elements
HELP * ISLIST
    Checking that an object is a list
HELP * ATOM
    Checking that an object is NOT a list
HELP * ISPAIR
    Checking that an object is a pair
HELP * NULL
    Checking that something is an empty list
HELP * LENGTH, * LISTLENGTH
    Finding the length of a list

The Pop-11 pattern matcher is often useful when the salient
characteristics concern the contents of the list - see section on list
matching


-----------------------------------------------------------------------
6  Processing Elements of Lists (e.g, sorting, deleting, reversing)
-----------------------------------------------------------------------

Processing (e.g., sorting, deleting elements etc.) and other
miscellaneous list processing procedures. Most of the facilities
described in the following help files create a copy of a list, with some
difference from the original.

HELP * REV
    Reversing the order of a list
HELP * SORT, * SYSSORT
    Sorting the elements of a list
HELP * SETFRONTLIST
    Moving an element to the front of a list

List operations that create a processed copy of a list can often have an
alternative "non-constructive" version that uses the same pairs.


-----------------------------------------------------------------------
7  Iteration over Lists
-----------------------------------------------------------------------

General introduction to iteration:

HELP * FOR
    Using a for loop

HELP * FOR_FORM
    How to extend the for loop syntax to deal with new cases.

Iteration over the elements in a list: the following facilities can be
used to perform some action to or for each element of a list:

REF * APPLIST
    Using a procedure for the action

HELP * MAPLIST
    Using a procedure for the action but creating a new list from the
    results

HELP * FOREACH
    Iterating over those elements of a list which match a given pattern

HELP * FOREVERY
    Iterating over combinations of elements which match a collection of
    patterns


-----------------------------------------------------------------------
8  Copying Lists
-----------------------------------------------------------------------

HELP * COPYLIST
    Copying the "top level" of a list

HELP * COPYTREE
    Copying every nested element of a list

Many list processing procedures create a copy of a list with some
alterations.


-----------------------------------------------------------------------
9  Dynamic Lists
-----------------------------------------------------------------------

A dynamic list is a list whose elements are determined by the results of
successive calls to a procedure. They provide a mechanism for lazy
evaluation, i.e. a list is created whose elements are not computed until
they are needed. So the list can even be infinite.

HELP * PDTOLIST
    Creating dynamic lists
HELP * ISDYNAMIC
    Checking for dynamic lists

Accessing dynamic lists

HELP * HD
    Getting the head
HELP * TL
    Getting the tail
HELP * DEST
    Getting both
HELP * NULL
    Finding the "last pair"

As with ordinary lists, dynamic lists are implemented in terms of pairs.


-----------------------------------------------------------------------
10  List Input and Output (e.g, reading in printing out)
-----------------------------------------------------------------------

Input:

HELP * LISTREAD
    Reading a list in standard list syntax
HELP * READLINE
    Reading a line of words into a list
TEACH * READLINE
    Turorial introduction to readline
HELP * GETLINE, * REQUESTLINE
    Reading a line of words into a list, using your own prompt
HELP * READEXPRESSION
    Reading a pop expression into a list

Output:

HELP * OUTPUT
    General Output procedures

Lists can generally be printed using standard Pop-11 output procedures.

HELP * PRINTARROW
    Output using the "printarrow"
TEACH * PRINTARROW
    Tutorial introduction to the printarrow
HELP * PPR
    Printing a list without the brackets
HELP * POPPRINT
    Printing a list when its contents are a program to be compiled

See also HELP * IO for an overview of help files relating to I/O in
Poplog.


-----------------------------------------------------------------------
11  Lists and Pair Manipulation
-----------------------------------------------------------------------

In Pop-11, lists are implemented in terms of a lower-level datastructure
called a pair.

TEACH * WAL, * BOXES, * PAIRS
    Tutorial introductions to lists and pairs (for beginners)
REF * LISTS
    Built-in list and pair processing facilities (advanced)


-----------------------------------------------------------------------
12  Efficiency and Fast Procedures
-----------------------------------------------------------------------

REF * FASTPROCS
HELP * FASTPROCS
    Many of the procedures mentioned in this file have "fast"
    equivalents.  These are often useful if you want your program to be
    more efficient. However debugging programs with fast procedures can
    sometimes be difficult, so LIB * SLOWPROCS is provided to transform
    the fast procedures to slower checking equivalents.

HELP * EFFICIENCY
    Gives more information about efficiency, including hints on
    minimising garbage collections.



--- C.all/help/lists
--- Copyright University of Sussex 1993. All rights reserved.
