HELP CONSPROCS                                       Andrew Law Jun 1987
                                         Updated: Adrian Howard May 1992

These are the procedures concerned with building "standard" POP-11
data-structures. Other libraries may provide additional data-structures
for internal use (for example, many of the X libraries.) These will be
detailed in the documentation for the individual libraries.

Also see REF *DEFSTRUCT for creating new POP-11 record and vector
classes.

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

 -- CONSTRUCTION PROCEDURES
 -- RELATED PROCEDURES
 -- ASSOCIATED DOCUMENTATION



-- CONSTRUCTION PROCEDURES --------------------------------------------

class_cons(KEY) -> PROCEDURE
    Returns the constructor procedure for the class KEY.
    -- *CLASS_CONS, REF *KEYS

conskey(WORD, SPEC) -> KEY
conskey(WORD, SPEC, ATTRIBUTE_VEC) -> KEY
    Creates a key for a new record or vector class according to the
    field specification SPEC. ATTRIBUTE_VEC can be used to supply
    any additional attributes of the new data-class.
    -- *CONSKEY, HELP *KEYS, REF *KEYS

cons_with PROCEDURE { ITEM_1 ITEM_2 ... ITEM_N } -> STRUCTURE
    Applies PROCEDURE to the specified ITEMs as follows:
        PROCEDURE(ITEM_1, ITEM2, ..., ITEM_N, N)
    PROCEDURE should be a vector class constructor procedure such as
    -consstring-
    -- *CONS_WITH, REF *SYNTAX, REF *POPSYNTAX

conslist(N) -> LIST
    Returns a LIST constructed from the top N items on the stack
    -- *CONSLIST, HELP *LISTS, REF *LISTS

cons(ITEM, LIST_1) -> LIST_2
ITEM :: LIST_1 -> LIST_2
    Constructs and returns a list whose head is ITEM and whose  tail is
    the list LIST_1
    -- *CONS, HELP *LISTS, REF *LISTS

conspair(ITEM_1, ITEM_2) -> PAIR
    Creates a PAIR whose -front- is ITEM_1 and whose -back- is ITEM_2.
    -- *CONSPAIR, TEACH *PAIRS, REF *LISTS

consvector(N) -> VECTOR
    Returns a VECTOR created from the top N items on the stack
    -- *CONSVECTOR, HELP *VECTORS, REF *VECTORS

consintvec(N) -> INTVEC
consshortvec(N) -> SHORTVEC
    Constructs and returns an integer/short vector with its elements
    taken from the next N items on the user stack,  where the first item
    on the stack  will be at  the highest  subscript value.
    -- *CONSINTVEC, *CONSSHORTVEC, REF *INTVEC

consword(STRING|INTEGER:N) -> WORD
    Returns a WORD with the same characters as STRING, or created from
    the top N characters on the stack.
    -- *CONSWORD, HELP *WORDS, REF *WORDS

consstring(N) -> STRING
    Returns a STRING created from the top N characters on the stack
    -- *CONSSTRING, HELP *STRINGS, REF *STRINGS

consdstring(N) -> DSTRING
consdstring(N, SOPT) -> DSTRING
consdstring(STRING) -> DSTRING
    Construct a "display" string DSTRING. The first two forms construct
    the display string from the top N characters on the stack. If SOPT
    is present and not -false- then the display string is optimised to
    an ordinary string if possible. The third form of -consdstring-
    constructs a display string from an ordinary string.
    --- *CONSDSTRING, HELP *STRINGS, REF *STRINGS

consref(ITEM) -> REFERENCE
    Returns a REFERENCE containing ITEM
    -- *CONSREF, HELP *REFERENCES, REF *RECORDS

consundef(WORD) -> UNDEF
    Creates a new undef record with -undefword- WORD.
    --- *CONSUNDEF, HELP *UNDEF, REF *IDENT

consclosure(P, ITEM_1, ITEM_2, ..., ITEM_N, N) -> CLOS
    Construct a closure based on procedure P with the N frozen arguments
    ITEM_1 to ITEM_N.
    --- *CONSCLOSURE, HELP *CLOSURES, REF *PROCEDURE

newarray(BOUNDS_LIST, ELEMENT_INIT) -> ARRAY
newanyarray(BOUNDS_LIST, ELEMENT_INIT, ARRAYVEC_SPEC, SUBSCR_P,
            ARRAYVEC_OFFSET, BY_ROW) -> ARRAY
    Generic array construction procedures
    --- *NEWARRAY, *NEWANYARRAY, HELP *ARRAYS, REF *ARRAYS

newsarray(BOUNDS_LIST, ELEMENT_INIT) -> CHAR_ARRAY
    Construct an array of strings
    --- *NEWSARRAY, HELP *ARRAYS, REF *ARRAYS

newsparse(DIMENSIONS) -> SPARSE_ARRAY
newanysparse(DIMENSIONS, DEFAULT_ITEM) -> SPARSE_ARRAY
newanysparse(DIMENSIONS, DEFAULT_P, APPLY) -> SPARSE_ARRAY
    Construct a "sparse" arrays.
    --- *NEWSPARSE, HELP *ARRAYS, REF *ARRAYS

newassoc(ASSOC_LIST) -> PROP
newmapping(ASSOC_LIST, TAB_SIZE, DEFAULT, EXPAND) -> PROP
newproperty(ASSOC_LIST, TAB_SIZE, DEFAULT, GC_TYPE) -> PROP
newanyproperty(ASSOC_LIST, TAB_SIZE, EXPAND_POW, THRESH, HASH_P,
               EQUAL_P, GC_TYPE, DEFAULT, ACTIVE_DEFAULT) -> PROP
    Construct properties.
    --- *NEWASSOC, *NEWMAPPING, *NEWPROPERTY, *NEWANYPROPERTY,
        HELP *PROPERTIES, REF *PROPS

consproc(ITEM_1, ..., ITEM_N, N, INIT_P) -> PROC
consproc(ITEM_1, ..., ITEM_N, N, INIT_P, VOLATILE) -> PROC
    Creates a process PROC from the procedure INIT_P transferring N
    items from the stack to PROC. VOLATILE is a boolean which specifies
    whether the process is "volatile" or not (the default is -true-.)
    -- *CONSPROC, HELP *PROCESS, REF *PROCESS

consproc_to(ITEM_1, ..., ITEM_N, N, TARGET_P) -> PROC        [procedure]
consproc_to(ITEM_1, ..., ITEM_N, N, TARGET_P, VOLATILE) -> PROC
    Creates a process record PROC of the current state of computation
    -- *CONSPROC_TO, HELP *PROCESS, REF *PROCESS

consident(IDPROPS, CONST_MODE, KIND) -> IDENT
    Construct an identifier record without the associated declaration of
    a word. IDENTPROPS specified the identprops. CONST_MODE specifies
    whether the ident refers to a constant or a variable, it also
    specifies whether the declaration is "weak" or not. KIND specifies
    the type of the identifier.
    -- *CONSIDENT, HELP *IDENTIFIERS, REF *IDENT

consdescriptor(STRING) -> DESC
    Construct a VMS simple string descriptor.
    --- *CONSDESCRIPTOR, REF *EXTERNAL

consprologterm(WORD, N) -> PROLOGTERM
    Construct a Prolog term with arity N and functor WORD.
    --- *CONSPROLOGTERM, REF *PROLOG

prolog_newvar() -> PROLOGVAR
    Constructs an uninstantiated Prolog variable.
    --- *PROLOG_NEWVAR, REF *PROLOG

prolog_maketerm(ITEM_1, N) -> ITEM_2
    Constructs a Prolog term with arity N and functor ITEM, with the
    arguments taken from the next N elements on the stack.
    --- *PROLOG_MAKETERM, REF *PROLOG

consdevice(PEN_NAME, FULL_NAME, USER_DATA, FLAGS,METHODS_VEC) -> UDEV
    Construct a user device.
    --- *CONSDEVICE, HELP *DEVICE, REF *SYSIO

consveddevice(FILENAME, ACCESS_MODE, INSERT_AT_EOF) -> DEV
    Constructs a VED-buffer device DEV for a file named FILENAME.
    --- *CONSVEDDEVICE, REF *VEDPROCS

consexternal_ptr() -> EXPTR
    Construct an external pointer.
    --- *CONSEXTERNAL_PTR, REF *EXTERNAL_DATA

consexptrvec(EXPTRCLASS_1,  ..., EXPTRCLASS_N, N) -> EXPTRVEC
    Construct an external pointer vector from the top N external
    pointers on the stack.
    --- *CONSEXPTRVEC, REF *EXTERNAL_DATA

cons_fixed(KEY) -> FIXED_STRUCT
cons_fixed(KEY, HOLD) -> FIXED_STRUCT
    Creating "fixed" structures not moved by garbage collection by
    calling the -class_cons- of KEY on any items on the stack. If HOLD
    is present and true, the returned structure is held on the fixed
    hold list to prevent it being garbage collected.
    --- *CONS_FIXED, REF *EXTERNAL_DATA

exptr_cons_fixed(KEY, HOLD) -> EXPTR
exptr_cons_fixed(KEY) -> EXPT
    Create an external pointer to a fixed POP-11 structure gained from
    applying the -class_cons- of KEY to any items on the stack. If HOLD
    is present and true, the returned structure is held on the fixed
    hold list to prevent it being garbage collected.
    --- *EXPTR_CONS_FIXED, REF *EXTERNAL_DATA

cons_access(WANT, SPEC, CHECK, MODE) -> P or P_VEC
    Constructs external access and application procedures for external
    data-structures and functions. WANT specifies what procedures are
    wanted. SPEC specifies the structure of the external object. CHECK
    specifies whether the returned procedure(s) do type checking of
    their arguments. MODE specifies the type of access.
    -- *CONS_ACCESS, REF *KEYS

make_exfunc_closure(F_EXPTRCLASS, ARG_ITEM, HOLD) -> EFC
exfunc_export(PROC, FLAGS, HOLD) -> EFC
    Create external function closures.
    --- *MAKE_EXFUNC_CLOSURE, *EXFUNC_EXPORT, REF *EXTERNAL_DATA

consshadowkey(NAME, SPEC, PROPS) -> SHKEY
    Construct a shadowkey. NAME is the name of the new data-class. SPEC
    is a description of its structure. PROPS specifies additional
    attributes.
    --- *CONSSHADOWKEY, REF *SHADOWCLASS

shadowclass_cons(SHKEY,FLAGS) -> PROC
    Returns the constructor procedure for the shadowclass with the
    shadow key SKKEY.
    --- *SHADOWCLASS_CONS, REF *SHADOWCLASS

sysvecons(N) -> FVEC
    Constructs a vector FVEC from items on the stack, leaving the stack
    N items deep.
    --- *SYSVECONS, REF *VECTORS

sysanyvecons(N, P) -> VEC
    Calculates the difference between the current stacklength and some
    previous stacklength N, which is given as an argument to P which
    should be some vector-type constructor procedure.
    --- *SYSANYVECONS, REF *DATA

sysconslist() -> LIST
    Constructs a list from the items on the stack up to -popstackmark-
    --- *SYSCONSLIST, REF *LISTS

sysconslist_onto(LIST_1) -> LIST_2
    Constructs a list from the items on the stack up to -popstackmark-
    followed by LIST_1.
    --- *SYSCONSLIST_ONTO, REF *LISTS



-- RELATED PROCEDURES -------------------------------------------------

class_init(KEY) -> PROCEDURE
    Returns the PROCEDURE which creates and initialises a structure of
    class KEY.
    --- *CLASS_INIT, REF *KEYS

initl(N) -> LIST
    Construct a list consisting of N copies of -nil-.
    --- *INITL, REF *LISTS

initv(INTEGER) -> VECTOR
    This procedure takes as argument an INTEGER and returns a data
    structure, of type VECTOR, with INTEGER components.  Initially all
    components hold "undef", though they can be set to any value using
    the procedure -subscrv-.
    --- *INITV, REF *VECTORS

initintvec(INTEGER) -> VECTOR
initshortvec(INTEGER) -> VECTOR
    Constructs and returns an integer/short VECTOR of length INTEGER
    whose elements are all initialised to the value 0 (zero).
    --- *INITINTVEC, *INITSHORTVEC, REF *INTVEC

inits(INTEGER) -> STRING
    Given an INTEGER, this procedure produces a STRING of the given
    size. The components of a STRING must be integers in the range 0 to
    255. The initial value of all components is 0.
    --- *INITS, REF *STRINGS

initdstring(INTEGER) -> STRING
    As for -inits-, but produces a display string rather than a normal
    string.
    --- *INITDSTRING, REF *STRINGS

initvectorclass(INTEGER, ITEM, KEY) -> VECTORCLASS
    This procedure is used to build instances of vector-type structures.
    Its arguments are an INTEGER specifying the size of vector-type
    object to construct, an ITEM to fill the new vector with, and a
    vector-type KEY which specifies what kind of vector to build.
    --- *INITVECTORCLASS, REF *DATA

initprologterm(N) -> PROLOGTERM
    Create a Prolog term with arity N and functor -undef-. All arguments
    are initialised to 0.
    --- *INITPROLOGTERM, REF *PROLOG

shadowclass_init(SHKEY) -> PROC
    Return the procedure PROC which creates and initialises a
    shadowclass structure with shadow key SHKEY.
    --- *SHADOWCLASS_INIT, REF *SHADOWCLASS

init_fixed(N, VEC_KEY) -> FIXED_VEC
init_fixed(N, VEC_KEY, HOLD) -> FIXED_VEC
    Created a fixed vector of length N using the -class_init- of the key
    VEC_KEY. If HOLD is present and non-false the vector is added to the
    fixed hold list to prevent it being garbage collected.
    --- *INIT_FIXED, REF *EXTERNAL_DATA

exptr_init_fixed(N, VEC_KEY, HOLD) -> EXPTR
exptr_init_fixed(N, VEC_KEY) -> EXPTR
    Return an external pointer to an N element fixed vector created by
    using the -class_init- of the key VEC_KEY. If HOLD is present and
    non-false the vector is added to the fixed hold list to prevent it
    being garbage collected.
    --- *EXPTR_INIT_FIXED, REF *EXTERNAL_DATA



-- ASSOCIATED DOCUMENTATION -------------------------------------------

    *FILL        - Filling in vectors from items on stack
    *STACK       - Procedures dealing with the stack
    *CLASSES     - Info. on POP-11 data classes
    *EXPLODE     - Puts all the elements of a structure on the stack.
    *DATA        - Info. on POP-11 datatypes
    *KEYS        - Info. on POP-11 keys
    *DESTPROCS   - POP-11 destructor procedures
    *DEFSTRUCT   - Constructing new POP-11 record and vector classes



--- C.all/help/consprocs -----------------------------------------------
--- Copyright University of Sussex 1992. All rights reserved. ----------
