REF RECORDS                                         John Gibson Jan 1996

       COPYRIGHT University of Sussex 1996. All Rights Reserved.

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
>>>>>>>>>>>>>>>>>>>>>>>                       >>>>>>>>>>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>>>>>>>>     MISCELLANEOUS     >>>>>>>>>>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>>>>>>>>   RECORD PROCEDURES   >>>>>>>>>>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>>>>>>>>                       >>>>>>>>>>>>>>>>>>>>>>>>>>
>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

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

  1   Overview

  2   References

  3   Booleans

  4   Matchvars
      4.1   Implementing Other Matching Operations



-----------
1  Overview
-----------

This file describes standard  record types not  documented in other  REF
files, namely references, booleans and matchvars.



-------------
2  References
-------------

A reference (dataword "ref") is a record containing a single field,  its
cont (contents), which may be any Poplog item.

isref(item) -> bool                                          [procedure]
        Returns true if item is a reference, false if not.


consref(item) -> ref                                         [procedure]
        Constructs and returns a reference with a cont of item.


cont(ref) -> item                                            [procedure]
item -> cont(ref)
        Returns or updates the contents of the reference ref.


ref_key -> key                                                [constant]
        This constant  holds  the  key  structure  for  references  (for
        details see REF * KEYS).




-----------
3  Booleans
-----------

There are just two of these  objects, true and false. Their dataword  is
"boolean". Note that  as regards the  representation of truth-values  in
condition-testing generally, only false is significant in that any value
other than false is considered to be true.

true -> bool                                                  [constant]
        The value of this constant is the boolean <true>.


false -> bool                                                 [constant]
        The value  of this  constant is  the boolean  <false>. false  is
        returned by  all  procedures  with * BOOLEAN  results  when  the
        condition does not hold.


isboolean(item) -> bool                                      [procedure]
        Returns  true  if  item  is  one  of  the  two  booleans,  false
        otherwise.


not(item) -> bool                                            [procedure]
        Negates the truth-value of item (which may be anything). If item
        is false then not returns true.  If item is anything else  false
        is returned. Also see and and or.


boolean_key -> key                                            [constant]
        This constant holds the key structure for booleans (for  details
        see REF * KEYS).




------------
4  Matchvars
------------

Matchvars (dataword "matchvar") are  records that may  be used alone  or
embedded in other structures to match against arbitrary values during an
= (or equals) operation (see Pattern Matching With = in HELP * EQUAL).

This behaviour is effected by the * class_= procedure of matchvars,  and
only happens when the matchvar is  part of the second (i.e.  right-hand)
argument to =.

There are two  distinct types  of matchvar (indicated  by bit  0 in  the
flags field): single item,  and list segment.  The first matches  just a
single item, whereas  the second  matches any  sequence of  (0 or  more)
items in a list  (and must itself be  an element of a  list in order  to
match).

Matchvar records contain the following four fields:

    name
        Matchvar records are printed to look like the Pop-11 syntax  for
        constructing them (see  HELP * EQUAL), i.e.  as =?(?)name  (etc)
        when wident is  an identifier, as  =?(?)"name" when wident  is a
        word, and as =*(*) when wident is false.

        Thus name should be wident if wident is a word, the name of  the
        identifier if wident  is an  identifier, or false  if wident  is
        false.

    wident
        A word, an identifier, or false.

        When a matchvar is matched against  a value value, the valof  or
        idval of wident is set to value, and wident is added to the list
        pop_matchvars_bound (the contents of this list are always  local
        to the current call of =).

        If however wident  is already in  pop_matchvars_bound (that  is,
        has already been  matched in the  current call of  =), then  the
        existing valof or idval of wident must equal value in order  for
        the match to succeed.

        wident  being  false  means  match  a  value  without  setting a
        variable.

    restriction
        An item which restricts what the matchvar may match. false means
        no restriction; an integer I means that length(value) must equal
        I; a procedure P  means that P(value) must  return a true  (i.e.
        non-false) result.

        restriction may also be an identifier whose idval is an  integer
        or procedure (this is dereferenced each time a match is tried).

    flags
        An integer  containing flag  bits. Currently,  only 2  bits  are
        defined:

            Bit     Meaning
            ---     -------
             0      If set this is a list segment matchvar,  otherwise a
                    single item matchvar.

             1      If  set,  a  restriction   procedure  P  is   also a
                    'conversion' procedure. This means that if P accepts
                    the match by  returning a non-false  item, then  the
                    valof/idval of wident will be replaced with item  at
                    the end of  the call  to = (providing  the call  was
                    successful). Thus  on  return from  =,  wident  will
                    contain item rather than value.


(See also  the  procedure * matchvar_instantiate  in  REF * DATA,  which
returns a partial  copy of a  structure with any  matchvars replaced  by
their identifier values.)


consmatchvar(name, wident, restriction, flags) -> matchvar   [procedure]
        Returns a new  matchvar record matchvar.  The four fields  name,
        wident, restriction and flags are as described above.


destmatchvar(matchvar) -> (name, wident, restriction, flags) [procedure]
        Returns all four fields of the matchvar matchvar.


pop_matchvars_bound -> list                                   [variable]
        This list is dynamically  localised and initially  set to []  by
        the =, /=  and equals  operators (and the  procedure sys_=).  It
        records matchvar variables that  have been bound  to a value  in
        the current call of =, etc.

        If empty (i.e. []), then no variables have been bound.

        If non-empty,  its tl  is  the list  of  all widents  (words  or
        identifiers) that have been assigned  a value. In addition,  its
        hd is a (possibly empty) list

                [% item1, wident1, ..., itemN, widentN %]

        which records  any  results  from  matchvars  with  'conversion'
        restriction procedures. That is, if the current call succeeds (=
        returns true, or /= returns false), then each widentI will  have
        its valof/idval replaced by itemI.


matchvar_key -> key                                           [constant]
        This constant holds the key structure for matchvars.



4.1  Implementing Other Matching Operations
-------------------------------------------
A   matching   operation   that   requires   a   non-local   value   for
pop_matchvars_bound can  be  effected  by calling  a  class_=  procedure
directly instead of =. That is, instead of

        item1 = item2

use

        class_=(datakey(item2))(item1, item2)

Similarily, the procedure * sys_nonlocal_equals  can be used instead  of
equals.

The following two procedures may be  used in conjunction with the  above
to implement self-contained matching operations other than the  standard
= and equals. Such an  operation should start by dynamically  localising
pop_matchvars_bound and initialising it to [], i.e.

        dlocal pop_matchvars_bound = [];


sys_restore_matchvars(save_conv, save_matchvars)             [procedure]
        Restores pop_matchvars_bound to the state given by the arguments
        save_conv and save_matchvars: these should previously have  been
        saved as two separate lists with

            fast_destpair(pop_matchvars_bound)
                            -> (save_conv, save_matchvars);

        (note that fast_destpair([]) is  guaranteed to produce [],  []).
        sys_restore_matchvars simply calls sys_grbg_destpair to  reclaim
        any pairs that have been added to pop_matchvars_bound since  the
        save operation was done.


sys_finish_matchvars(bool) -> bool                           [procedure]
        Uses sys_grbg_destpair to reclaim all pairs that have been added
        to pop_matchvars_bound,  after  performing  any  assignments  to
        variables resulting from 'conversion' restriction procedures.

        It should be called  at the end of  the matching operation,  but
        only if pop_matchvars_bound is non-empty, i.e.

            bool;
            if pop_matchvars_bound /== [] then
                sys_finish_matchvars()
            endif;

        The bool  argument is  true if  the match  succeeded, and  false
        otherwise (this argument is  left unchanged on  the stack so  it
        can be the result of the match operation). If bool is true,  and
        the first element of pop_matchvars_bound is a non-empty list

                [% item1, wident1, ..., itemN, widentN %]

        then each itemI is assigned to the valof/idval of widentI.




--- C.all/ref/records
--- Copyright University of Sussex 1996. All rights reserved.
