REF STACK                                           John Gibson May 1995

       COPYRIGHT University of Sussex 1995. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    USER STACK PROCEDURES    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

In Poplog, arguments to procedures and  results from them are passed  on
the user stack, which is an  open stack of (nominally) infinite  length.
The procedures described in  this REF file enable  the user stack to  be
manipulated directly,  in  addition  to  its  implicit  use  in  passing
arguments and results.

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

  1   Manipulating the Top Item(s)

  2   Whole Stack Operations

  3   Accessing the Stack as a Vector

  4   Miscellaneous



-------------------------------
1  Manipulating the Top Item(s)
-------------------------------

identfn()                                                    [procedure]
        The identity  procedure -- does absolutely  nothing when  called
        (and so leaves the user stack untouched).


erase(item)                                                  [procedure]
        Removes the top item from the user stack.


erasenum(item1, item2, ..., itemN, N)                        [procedure]
        Removes the top N items from the user stack.


dup(item) -> (item, item)                                    [procedure]
        Duplicates the top item on the  user stack (i.e. pushes it  back
        onto the stack again).


dupnum(item, N) -> (item, item, ... item)                    [procedure]
        Leaves N  copies of  item  on the  stack.  (Hence dup  could  be
        defined as  dupnum(%2%)  and  erase as  dupnum(%0%).)  See  also
        * dup, * applynum.




-------------------------
2  Whole Stack Operations
-------------------------

stacklength() -> N                                           [procedure]
        Returns the number of items on the user stack.


setstacklength(N)                                            [procedure]
        Sets the user stack length to N. If the current stacklength L is
        greater than N, then  L-N items are  erased, otherwise N-L  nils
        ([]s) are  pushed on  (the  reason for  using  [] is  that  this
        procedure is principally used by  the Lisp compiler). Note  that
        for reasons of efficiency setstacklength does not check that the
        argument N is an integer.


clearstack()                                                 [procedure]
        Clears all items from the user stack.




----------------------------------
3  Accessing the Stack as a Vector
----------------------------------

subscr_stack(N) -> item                                      [procedure]
item -> subscr_stack(N)
        This procedure allows the user stack to be used as if it were an
        array: it  returns or  updates the  N-th element  on the  stack,
        where the element on top of the stack (the most recently pushed)
        has subscript 1.  There must be  at least N  items on the  stack
        (otherwise a mishap results).




----------------
4  Miscellaneous
----------------

popstackmark -> stackmark                                     [constant]
        The  value  of  this  constant  is  a  stackmark  record  (whose
        conventional use is  by the  Pop-11 list  constructor to  mark a
        position on the stack for * sysconslist). This item is the  only
        stackmark record available to the user (although others are used
        inside the system); it prints as <popstackmark>.


stackmark_key -> key                                          [constant]
        The key of stackmark objects.



+-+ C.all/ref/stack
+-+ Copyright University of Sussex 1995. All rights reserved.