```Search                        Top                                  Index
```
```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

-----------------------------------------------------------------------
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
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:

Reading a list in standard list syntax
Reading a line of words into a list
HELP * GETLINE, * REQUESTLINE
Reading a line of words into a list, using your own prompt
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