HELP SECTIONS                                  A. Sloman, Nov 1986

SECTION ... ENDSECTION

section <pathname> <imports> => <exports> ;
            <expression sequence>
endsection;

-- Introduction -------------------------------------------------------
The brackets SECTION ... ENDSECTION are be used to define a portion of
program in which some of the the identifiers used (those which are not
exported) can be guaranteed not to clash with those used elsewhere.
Identifiers used within a section, unless explicitly declared otherwise,
are local to that section; therefore even if they are not declared as
local, their values will not be confused with those of identifiers with
the same names used outside that section.

Sections have names, and imported and exported identifiers. They have
path-names, like directories, and can be re-entered after leaving.

-- Top-level section --------------------------------------------------
The top level section is named by the identifier *POP_SECTION. It can be
restored by section brackets giving no path name, no imports and no
exports, e.g.

    section;
        <expression sequence>
    endsection;

-- Nested sections ----------------------------------------------------
A section may be nested within another section. If it uses only a simple
name as its path-name then it will be a sub-section of the outer
section. If the nested section heading uses a full path name then that
will be equivalent to temporarily leaving the enclosing section to go to
the section with that path name.

If fred is defined as a section within the top level section, and joe
is defined as a section in fred, then at any time the following syntax
will re-enter the context to the sub-section joe of fred,
    section $-fred$-joe;
        <expression sequence>
    endsection;

New imports and exports can be specified when this happens.

-- Imports and exports ------------------------------------------------
Importing an identifier named X into a sub-section B of a section A
means that references to X in B refer to the identifier associated with
X in A; similarily, exporting an identifier Y from B up to A means that
references to Y in A refer to the identifier as declared in B. Thus the
former allows references to identifiers already declared in sections
above the current one, while the latter allows new identifiers to be
declared in higher-level sections from within the current section.

-- Reference to an identifier in another section ----------------------
A 'pathname' syntax is provided to enable reference to identifiers
within sections. The word "$-" is used to separate parts of the
pathname,  so that for example

                $-tom$-dick$-harry

refers to the identifier HARRY in sub-section DICK of section TOM (TOM
being a sub-section of *POP_SECTION, the default top-level section in
POP-11.

-- CURRENT_SECTION ----------------------------------------------------
The active variable *CURRENT_SECTION has as its value the section
currently used by the compiler to specify the mapping from words read in
to identifiers. Its value can be saved and then later re-assigned.
See HELP * CURRENT_SECTION.

-- Further information ------------------------------------------------
On leaving a section (via ENDSECTION) the information about the section
is retained in a section record. If it is certain that there will never
be any further need to re-enter the section or to refer to identifiers
within it, the section may be cancelled, using SECTION_CANCEL. For
details see HELP *SECTION_CANCEL.

The section $-library is used as a default section in which to define
library files, and $-ved for VED library files.

WARNING: A file is always compiled in the current section, and
identifiers declared therein will not necessarily be accessible in other
sections. Exporting an identifier makes it available in higher level
sections. Making it *GLOBAL will ensure that it is available in lower
level sections.

For an example of the use of sections and SECTION_CANCEL see
LIB *ARRAYSCAN

In many cases lexical identifiers can make the use of a section
unnecessary. See HELP *LEXICAL

See HELP *STANDARDS for recommendations on the use of sections and
lexical identifiers in writing library programs.

See also HELP files
*POP_SECTION     - on the value and use of POP_SECTION
*CURRENT_SECTION - on accessing and changing current section
*SECTION_CANCEL  - how to cancel a section
*SMATCH          - on using MATCHES within sections
*GLOBAL          - on the use of global identifiers in POP-11
*VARS, *DEFINE   - on declarations in POP-11
*SYSCANCEL       - breaks the link between a word and its
                    current identifier
*SYSCANCELWORD   - removes a word completely from the dictionary

REF *SECTIONS, REF *IDENT, REF *WORDS - give more technical details.

-----<Copyright University of Sussex 1986.  All rights reserved.>-------
