=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Types_Catalog -
Muldis D catalog-defining data types

=head1 VERSION

This document is Muldis::D::Core::Types_Catalog version 0.21.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document before
you read this one, which provides subservient details.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

This document contains one or more sections that were moved here from
L<Muldis::D::Core> so that that other document would not be too
large.

=head1 TYPE SUMMARY

These system-defined subtypes are specific to defining the system catalog,
more or less:

    sys.Core.Universal.Universal

        sys.Core.Universal.Empty

        sys.Core.Scalar.Scalar

            # The following are all regular ordered scalar types.

            sys.Core.Cat.Name
            sys.Core.Cat.NameChain
            sys.Core.Cat.FlattenedNameChain
            sys.Core.Cat.Comment

            sys.Core.Scalar.Int
                sys.Core.Scalar.UInt
                    sys.Core.Scalar.PInt

                        # These are all finite integer types.

                        sys.Core.Cat.PInt2_36

            # The following are all regular non-ordered scalar types.

            sys.Core.Cat.E_TK
            sys.Core.Cat.E_TDM
            sys.Core.Cat.E_ENK
            sys.Core.Cat.E_PSAK

        sys.Core.Tuple.Tuple

            # The following are all regular tuple types.

            sys.Core.Cat.Type
            sys.Core.Cat.ExprNode
            sys.Core.Cat.InnerFunc
            sys.Core.Cat.Func
            sys.Core.Cat.UpdStmt
            sys.Core.Cat.InnerUpdater
            sys.Core.Cat.Updater
            sys.Core.Cat.ProcStmtArg
            sys.Core.Cat.ProcStmt
            sys.Core.Cat.InnerProc
            sys.Core.Cat.Proc
            sys.Core.Cat.Exception

        sys.Core.Relation.Relation

            # The following are all regular relation types.

            sys.Core.Cat.NameTypeMap
            sys.Core.Cat.NameExprMap
            sys.Core.Cat.AttrRenameMap
            sys.Core.Cat.ExprSet
                sys.Core.Cat.ExprTree
            sys.Core.Cat.InnerFuncSet
                sys.Core.Cat.InnerFuncTree
            sys.Core.Cat.MultiUpdStmt
            sys.Core.Cat.InnerUpdaterSet
                sys.Core.Cat.InnerUpdaterTree
            sys.Core.Cat.ProcStmtArgSet
            sys.Core.Cat.InnerProcTree

            sys.Core.Relation.Set

                # The following are all regular set types.

                sys.Core.Cat.SetOfName
                sys.Core.Cat.SetOfSetOfName
                sys.Core.Cat.SetOfNameExprMap
                sys.Core.Cat.SetOfNameChain

            sys.Core.Relation.Seq

                # The following are all regular sequence types.

                sys.Core.Cat.NESeqOfName
                sys.Core.Cat.SeqOfProcStmt

These system-defined subtypes are used as the declared types of some
parameters of some system-defined N-ary routines, but they are not used in
defining the system catalog itself; it is not anticipated that they would
be used for user data:

    sys.Core.Universal.Universal

        sys.Core.Universal.Empty

        sys.Core.Relation.Relation
            sys.Core.Relation.Set

                # The following are all nonscalar type factories.

                sys.Core.QuasiCat.SetOfTuple
                sys.Core.QuasiCat.SetOfRelation
                    sys.Core.QuasiCat.SetOfBag

                sys.Core.Relation.Maybe

                    # The following are all nonscalar type factories.

                    sys.Core.QuasiCat.MaybeOfTuple

            sys.Core.Relation.Seq

                # The following are all nonscalar type factories.

                sys.Core.QuasiCat.SeqOfSeq

            sys.Core.Relation.Bag

                # The following are all nonscalar type factories.

                sys.Core.QuasiCat.BagOfTuple
                sys.Core.QuasiCat.BagOfRelation

        sys.Core.QuasiRelation.QuasiRelation
            sys.Core.QuasiRelation.QuasiSet

                # The following are all quasi-nonscalar type factories.

                sys.Core.QuasiCat.QuasiSetOfTuple
                sys.Core.QuasiCat.QuasiSetOfRelation

=head1 SYSTEM-DEFINED CORE CATALOG SCALAR DATA TYPES

These core scalar data types are more special-purpose in nature and are
intended for use in defining or working with the system catalog, which is
mainly composed of nonscalar types built using these.

=head2 sys.Core.Cat.Name

A C<Cat.Name> (scalar) is a canonical short name for any kind of DBMS
entity (or named component) when declaring it; this short name is
sufficient to identify the entity within its immediate namespace.
Similarly, a DBMS entity can often be invoked or referred to using just its
C<Cat.Name>, depending on the context; other times, a C<Cat.NameChain> must
be used instead to also qualify the reference with a namespace.
C<Cat.Name> is the same as C<Text> in all ways but that it is specifically
intended for use in naming DBMS entities rather than being normal data.

=head2 sys.Core.Cat.NameChain

A C<Cat.NameChain> (scalar) is a canonical long name for invoking or
referring to a DBMS entity, when its name needs to be qualified with a
namespace.  A C<Cat.NameChain> has 2 possreps; one possrep is a sequence of
1..N C<Cat.Name> (represented by a C<Cat.NESeqOfName>), the 1..N elements
being ordered from parent-most to child-most component name; the other
possrep is a character string (represented by a C<Cat.FlattenedNameChain>)
like when the elements of the first possrep are catenated (in order with
the first element at the start of the string), with a period (C<.>) between
the parts, and each part escaped such that backslashes, single-quotes, and
periods are escaped as C<\b>, C<\q> and C<\p> respectively.

=head2 sys.Core.Cat.FlattenedNameChain

The C<Cat.FlattenedNameChain> (scalar) type is used as the definition of
the character string possrep of a C<Cat.NameChain> (see that type for
details); while being a character string like C<Cat.Name>, the two are
disjoint.

=head2 sys.Core.Cat.Comment

A C<Cat.Comment> (scalar) is the text of a Muldis D code comment, which
programmers can populate as an attribute of several catalog data types,
such as whole routines or statements or expression nodes.  C<Cat.Comment>
is the same as C<Text>, and C<Name>, in all ways but that it is
specifically intended for use in commenting Muldis D code rather than being
normal data; they are disjoint.  One main intended use of this type is to
help preserve comments in code translated to or from other languages;
though only a subset of those (FoxPro?) keep comments in the AST rather
than discarding them.

=head2 sys.Core.Cat.PInt2_36

A C<Cat.PInt2_36> is a proper subtype of C<Cat.PInt2_N> where all member
values are between 2 and 36.  (The significance of the number 36 is 10
digits plus 26 letters.)  Its maximum value is 36.  The cardinality of this
type is 35.

=head2 sys.Core.Cat.E_TK

A C<Cat.E_TK> (type kind) is a scalar enumeration consisting of the 8
values C<Cat.E_TK:special> (mainly for system-defined implicit supertypes),
C<Cat.E_TK:scalar>, C<Cat.E_TK:tuple>, C<Cat.E_TK:relation>,
C<Cat.E_TK:quasi_scalar>, C<Cat.E_TK:quasi_tuple>,
C<Cat.E_TK:quasi_relation>, C<Cat.E_TK:remnant>.  Its default value is
C<Cat.E_TK:scalar>.

=head2 sys.Core.Cat.E_TDM

A C<Cat.E_TDM> (type definition method) is a scalar enumeration consisting
of the 9 values C<Cat.E_TDM:special> (for some system-defined types that
don't best fit in other categories, and all parameterized types; users can
not define the latter for now), C<Cat.E_TDM:root> (complete root type
defined in terms of explicit attribute collection; all are fully defined,
not parameterized), C<Cat.E_TDM:restriction> (defined as "explicit
other-type where condition"), C<Cat.E_TDM:alias> (so the same one type can
have multiple names), C<Cat.E_TDM:(union|intersection|exclusion)> (defined
as explicit union|intersection|exclusion of other types),
C<Cat.E_TDM:difference> (defined as explicit difference of 2 other types),
C<Cat.E_TDM:negation> (defined as explicit negation of another type).  Its
default value is C<Cat.E_TDM:alias>.

=head2 sys.Core.Cat.E_ENK

A C<Cat.E_ENK> (expression node kind) is a scalar enumeration consisting of
the 11 values C<Cat.E_ENK:default> (default value of expression's declared
type),
C<Cat.E_ENK:(scalar|tuple|relation|quasi_scalar|quasi_tuple|quasi_relation)
> (hard-coded literal
scalar|tuple|relation|quasi-scalar|quasi-tuple|quasi-relation value),
C<Cat.E_ENK:param> (value of expression-containing function parameter),
C<Cat.E_ENK:upd_param> (on-entry value of expression-containing update
operator subject-to-update parameter), C<Cat.E_ENK:ro_param> (value of
expression-containing update operator read-only parameter),
C<Cat.E_ENK:func> (result of function invocation, or inlining of function
body).  Note that only C<upd_param> and C<func> (over C<upd_param>) can be
used for a subject-to-update argument of an update operator, but all of
these can be used elsewhere.  Its default value is C<Cat.E_ENK:scalar>.

=head2 sys.Core.Cat.E_PSAK

A C<Cat.E_PSAK> (procedural statement argument kind) is a scalar
enumeration consisting of the 5 values C<Cat.E_PSAK:default> (default value
of argument's declared type), C<Cat.E_PSAK:upd_param> (current value of
statement-containing procedure subject-to-update parameter),
C<Cat.E_PSAK:ro_param> (value of statement-containing procedure read-only
parameter), C<Cat.E_PSAK:inner_var> (current value of statement-containing
procedure lexical variable, not param), C<Cat.E_PSAK:outer_var> (current
value of a non-lexical variable).  Note that only C<upd_param> and
C<(inner|outer)_var> can be used for a subject-to-update argument, but all
of these can be used with a read-only argument.  Its default value is
C<Cat.E_PSAK:ro_param>.

=head1 SYSTEM-DEFINED CORE CATALOG TUPLE DATA TYPES

These tuple data types, essentially all of the system-defined tuple types
are special-purpose in nature and are intended for use in defining or
working with the system catalog.  They are all completely defined types.

Note that many of these types might conceptually have C<name> attributes,
but those would actually be provided by any larger types in which they are
embedded, rather than by these types themselves.

Note that whenever an attribute of one of these types isn't significant,
given the context (determined by other attributes of the same type), and
should be ignored, its value is the default for its type.

I<To keep things simpler for now, most constraint definitions for these
types are missing, or just defined informally.>

=head2 sys.Core.Cat.Type

A C<Cat.Type> is a C<Tuple>.  It defines a data type, which can either be
(sometimes) invoked directly for values, or be invoked by or embedded into
other type definitions.  C<Cat.Type> is used in the catalogs for defining
both system and user types (just the interfaces in the former case).

I<TODO:  The catalog types for type definitions need an overhaul.>

A C<Cat.Type> has these 8 attributes:

=over

=item C<tk> - C<Cat.E_TK>

This broadly declares what kind of type this is (eg,
scalar|tuple|relation); it partially says how to interpret the rest of the
attributes and/or which of them have significant values.

=item C<tdm> - C<Cat.E_TDM>

This is the type definition method for the type; it partially says how to
interpret the rest of the attributes and/or which of them have significant
values.  If C<tk> is C<Cat.E_TK:special>, then C<tdm> must be
C<Cat.E_TDM:special>; C<tdm> can be special at other times too.

=item C<types> - C<Cat.SetOfNameChain>

For some values of C<tdm>, the data type is defined at least partially in
terms of other data types not by way of attribute definitions, and then
C<types> lists all/most of those types.  Iff C<tdm> is C<Cat.E_TDM:alias>,
then the data type is just a symbolic reference for some other data type
(as far as the type system is concerned, they are the same data type,
invokable by an extra name), and C<types> has one element that is the name
of that type.  Iff C<tdm> is C<Cat.E_TDM:restriction>, then the data type
is defined as an explicit subtype of another type by way of an explicit
further type constraint applied to it, and C<types> has one element that is
the name of that supertype.  Iff C<tdm> is
C<Cat.E_TDM:(union|intersection|exclusion)>, then the data type is defined
as an explicit union|intersection|exclusion of N other types, and C<types>
lists their names, one per element; 2+ elements is the norm; just 1 element
means that the data type is a simple alias for the named element; zero
elements means the data type is a simple alias for, respectively, the type
C<Empty>, C<Universal>, or C<Empty>.  Iff C<tdm> is
C<Cat.E_TDM.difference>, then the data type is defined as the difference of
2 other types, and C<types> has one element that is the name of the minuend
type.  Iff C<tdm> is C<Cat.E_TDM.negation>, then the data type is defined
as the negation of some other type, and C<types> has one element that is
the name of that type.

=item C<subtr_type> - C<Cat.NameChain>

Iff C<tdm> is C<Cat.E_TDM.difference>, then the data type is defined as the
difference of 2 other types, and C<subtr_type> is the name of the
subtrahend type.

=item C<attrs> - C<Cat.NameTypeMap>

Iff C<tdm> is C<Cat.E_TDM:root>, then the data type is defined
fundamentally in terms of an explicit attribute collection, and C<attrs>
defines the names and declared types of those attributes.  Iff additionally
C<tk> is C<Cat.E_TK:(scalar|quasi_scalar)>, then C<attrs> specifically
defines the attributes of just the core/initial/only possrep; otherwise,
C<attrs> defines the heading of the tuple or relation etc type.  It is
valid to have zero attributes; in this case, the type consists of exactly
one value.

=item C<keys> - C<Cat.SetOfSetOfName>

Iff C<tk> is C<Cat.E_TK:(relation|quasi_relation)> and C<tdm> is not
C<Cat.E_TDM:special>, then the data type is or resembles a relation type
and can have explicit keys (duality of unique key constraints and terser
unique identifiers for the q/relation's member q/tuples) defined over its
attributes, and C<keys> defines those keys in the canonical simplest form
(in contrast with using C<constraint> instead).  Each element of C<keys>
defines one key of the q/relation, and that element is a set of the
attribute names comprising that key.  For q/relation types, if no keys are
explicitly defined, then it implicitly has a single key comprising all of
its attributes.  If any explicit keys are defined, then every one must be
over a distinct proper subset of the type's attributes, and moreover no
key's attributes may be a proper subset of any other key's attributes; if 2
such candidates appear, just use the one that has the subset.  It is valid
for a key to consist of zero attributes; in this case, that key is the only
key of the q/relation type, and values of the type may each consist of no
more than one tuple.

=item C<constraint> - C<Cat.TypeConstraint> ... default one always res True

Iff C<tdm> is C<Cat.E_TDM:root>, then the data type is defined
fundamentally in terms of an explicit attribute collection, and
C<constraint> defines/names a generalized type constraint that validates
the collection as a whole.  Iff C<tdm> is C<Cat.E_TDM:restriction>, then
the data type is defined as an explicit subtype of another type by way of
an explicit further type constraint applied to it, and C<constraint>
defines/names that further constraint.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the data type.

=back

The default value of C<Cat.Type> is an alias of C<Empty>.

=head2 sys.Core.Cat.ExprNode

A C<Cat.ExprNode> is a C<Tuple>.  It specifies a named expression node,
which is the majority component of functional Muldis D code.  All
arbitrarily complex Muldis D expression trees, including relational
queries, are composed of just C<Cat.ExprNode>, either directly, or
indirectly by way of function invocations, as each function body is itself
composed entirely of a single expression tree (of at least 1 node).  Only
functions and update operators may contain C<Cat.ExprNode>, so for any
procedures that would conceptually include them, those portions of the
procedures need to be separated out and encapsulated by named functions or
inner-functions or update operators or inner-update-operators.  Note that,
while the general case has expression trees simply denoting a value, in
some cases they may instead define a pseudo-variable / virtual variable;
that only happens in update operators where the expression is used as an
argument for a subject-to-update parameter of an update operator call; in
that case the leaf nodes / only node of the expression must map to a
subject-to-update parameter of the containing update operator.

A C<Cat.ExprNode> has these 9 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the expression node; other Muldis D code that
is composing this expression node into their own definitions would
reference it with this name.

=item C<type> - C<Cat.NameChain>

This is the declared result data type of the expression node.  If the
expression node represents a literal value, this is often necessary for
properly interpreting the details of that literal, particularly for
literals that are not scalar.  Otherwise, although the result type of an
expression can sometimes be inferred from context, such as from the result
type of a function it is an invocation of, this redundancy helps make
static analysis of Muldis D code easier, so it is easier to validate and
optimize in isolation from the other routines it interacts with.  Moreover,
this type declaration provides a terse way to use the C<treated> function
frequently in code, so that the programmer and compiler knows that some
generic routines are actually supposed to be resulting in a subtype of
their normal result types.

=item C<kind> - C<Cat.E_ENK>

This is the declared kind of expression that this node is; it says how to
interpret the rest of the attributes and/or which of them have significant
values.

=item C<scal_lit> - C<Scalar>

Iff C<kind> is C<Cat.E_ENK:scalar>, then the expression represents a
hard-coded scalar literal of one of a certain collection of system-defined
core scalar types (or subtype thereof), and this is that literal value.
I<That is, any Scalar value could be used here, but in practice that is
either dialect-defined (what literals are supported), and possibly
implementation defined/limited.>

=item C<coll_lit> - C<Cat.SetOfNameExprMap>

Iff C<kind> is C<Cat.E_ENK:(|quasi_)(tuple|relation)>, then the expression
represents a collection literal, and these are the values of its
components.  Each element defines one tuple, and each sub-element of that
element defines one attribute value for one tuple, with the sub-element
C<name> matching the attribute name, and the sub-element C<expr> naming
another local C<Cat.ExprNode> which defines the value.  The value of
C<coll_lit> defines exactly one tuple when C<kind> specifies a tuple or
quasi-tuple, and it defines 0..N tuples when C<kind> specifies a relation
or quasi-relation.

=item C<param> - C<Cat.Name>

Iff C<kind> is C<Cat.E_ENK:param>, then the expression represents the value
of the containing function's parameter which this names.  Or, if C<kind> is
C<Cat.E_ENK:upd_param> or C<Cat.E_ENK:ro_param>, then the expression
represents the on-entry value or value of the containing update operator's
subject-to-update or read-only parameter, respectively.

=item C<func> - C<Cat.NameChain>

Iff C<kind> is C<Cat.E_ENK:func>, then the expression represents the result
of invoking a named function with specific arguments, and this the name of
that function.

=item C<func_args> - C<Cat.NameExprMap>

Iff C<func> is used, then these are the arguments for the function
invocation.  Each element defines one argument value, with the element
C<name> matching the parameter name, and the element C<expr> naming another
local C<ExprNode> which defines the value.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about either the expression node or
the expression node (sub-)tree it is the root of.

=back

The default value of C<Cat.ExprNode> has an empty name and represents the
literal scalar value C<Bool:false>.

=head2 sys.Core.Cat.InnerFunc

A C<Cat.InnerFunc> is a C<Tuple>.  It specifies a named C<inner_function>
routine, which is the main component type of a complete routine; a complete
function consists of at least one inner function, which is its main body,
plus more when it would conceptually be using anonymous inline function
definitions (to pass to function-valued function arguments), or when it
would conceptually have self-referencing/cyclic expressions.

A C<Cat.InnerFunc> has these 6 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the inner function within its parent complete
function; other Muldis D code within said complete function would reference
it with this name.

=item C<result_type> - C<Cat.NameChain>

This is the declared result data type of the inner function as a whole.

=item C<is_recursive> - C<Bool>

This is C<Bool:true> if the inner function might possibly invoke itself,
either directly or indirectly; it is C<Bool:false> if it promises to never
be recursive.  Note that the C<is_recursive> attribute does not make any
claims regarding the actions of any anonymous functions that it is passed
as function-valued arguments, which may cause this inner function to be
involved in a recursion even if C<is_recursive> is C<Bool:false>.  I<Note
that this may be changed later, or the attribute simply be eliminated.>

=item C<params> - C<Cat.NameTypeMap>

This is the declared parameter list of the inner function, which has 0..N
named and typed parameters.

=item C<expr> - C<Cat.ExprTree>

This defines the entire body of the inner function, which is composed of a
single expression tree, whose root node's name is the empty string.  This
expression tree must reference all of the parameters that the inner
function has.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the inner function as a whole.

=back

The default value of C<Cat.InnerFunc> has an empty name and unconditionally
results in the literal scalar value C<Bool:false>.

=head2 sys.Core.Cat.Func

A C<Cat.Func> is a C<Tuple>.  It specifies a named C<function> routine,
which is conceptually a non-anonymous function that is generally invokable
by the public (unless its parent package says otherwise).

A C<Cat.Func> has these 3 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the function; other Muldis D code would
reference it with this name.

=item C<inner_funcs> - C<Cat.InnerFuncTree>

This defines the entire body of the function (both its main body plus any
conceptually expression-inlined anonymous functions), which is composed of
one or more inner functions, plus its public interface / parameter list,
which is defined by one of those.  The inner function defining the outer
function's main body has the empty string as its name.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the function as a whole.

=back

The default value of C<Cat.Func> unconditionally results in the literal
scalar value C<Bool:false> as per the default of C<Cat.InnerFunc>.

=head2 sys.Core.Cat.UpdStmt

A C<Cat.UpdStmt> is a C<Tuple>.  It specifies a single update statement (of
1..N variables), which is the most fundamental component of procedural
Muldis D code, and is what the body of an update operator routine is
composed of.  The variables being updated are accessed via the host
routine's subject-to-update parameters.  All arbitrarily complex Muldis D
value assignments, including relational assignments, are composed of just
C<Cat.UpdStmt>, either directly, or indirectly by way of update operator
invocations, as each update operator body is itself composed entirely of 1
or more update statements (grouped as 1 multi-update).  Only update
operators may contain C<Cat.UpdStmt>, so for any procedures that would
conceptually include them, those portions of the procedures need to be
separated out and encapsulated by named update operators or
inner-update-operators.

A C<Cat.UpdStmt> has these 4 attributes:

=over

=item C<updater> - C<Cat.NameChain>

Every update statement is an invocation of some other update operator (or
inner-update-operator), either a user-defined or system-defined one (the
latter generally being the end of the call chain); this is the name of that
update operator.

=item C<upd_args> - C<Cat.NameExprMap>

These are the 1..N subject-to-update arguments to the update operator
invocation, as-per C<ro_args>.  But since each expression tree in
C<upd_args> is binding to a subject-to-update parameter, the expression
tree actually is defining a pseudo-variable / virtual-variable over 1..N
containing routine subject-to-update parameters; in the most trivial (and
common) case, such an expression tree is a single node that represents said
parameter without any indirection at all.

=item C<ro_args> - C<Cat.NameExprMap>

These are the 0..N read-only arguments to the update operator invocation.
Each element defines one argument value, with the element C<name> matching
the parameter name, and the element C<expr> naming a local C<ExprNode>
which defines the value.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the update statement as a
whole.

=back

The default value of C<Cat.UpdStmt> will unconditionally update 1
subject-to-update parameter of name C<topic> with the value C<Bool:false>.

=head2 sys.Core.Cat.InnerUpdater

A C<Cat.InnerUpdater> is a C<Tuple>.  It specifies a named C<updater>
routine, which is the main component type of a complete implicitly atomic
procedural routine; a complete update operator consists of at least one
inner update operator, which is its main body, likely plus more when it
would conceptually be code refactored.

A C<Cat.InnerUpdater> has these 7 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the inner update operator within its parent
complete update operator; other Muldis D code within said complete update
operator would reference it with this name.

=item C<is_recursive> - C<Bool>

This is C<Bool:true> if the inner update operator might possibly invoke
itself, either directly or indirectly; it is C<Bool:false> if it promises
to never be recursive.  I<Note that this attribute may be eliminated.>

=item C<upd_params> - C<Cat.NameTypeMap>

This is the declared subject-to-update parameter list of the inner update
operator, which has 1..N named and typed such parameters.  It must have at
least 1 element.

=item C<ro_params> - C<Cat.NameTypeMap>

This is the declared read-only parameter list of the inner update operator,
which has 0..N named and typed such parameters.  There is a distributed
(unique) key over the C<name> attributes of C<upd_params> and C<ro_params>.

=item C<exprs> - C<Cat.ExprSet>

This defines the expression trees that are arguments to the update
operators that C<stmt> invokes.  These expression trees must reference all
of the parameters that the inner update operator has.

=item C<stmt> - C<Cat.MultiUpdStmt>

This defines the entire body of the inner update operator, which is
composed of a single multi-update statement.  This multi-update statement
must reference all of the parameters that the inner update operator has.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the inner updater as a whole.

=back

The default value of C<Cat.InnerUpdater> has an empty name and has 1
subject-to-update parameter named C<topic> and declared type C<Bool> and
will unconditionally update it to the value C<Bool:false>; it has zero
read-only parameters.

=head2 sys.Core.Cat.Updater

A C<Cat.Updater> is a C<Tuple>.  It specifies a named C<update operator>
routine, which is conceptually a non-anonymous update operator that is
generally invokable by the public (unless its parent package says
otherwise).

A C<Cat.Updater> has these 4 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the update operator; other Muldis D code would
reference it with this name.

=item C<inner_updaters> - C<Cat.InnerUpdaterTree>

This (save for C<inner_funcs>) defines the entire body of the update
operator, which is composed of one or more inner update operators, plus its
public interface / parameter list, which is defined by one of those.  The
inner updater defining the outer updater's main body has the empty string
as its name.

=item C<inner_funcs> - C<Cat.InnerFuncSet>

This also contributes to the body of the update operator.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the updater as a whole.

=back

The default value of C<Cat.Updater> is as per the default of
C<Cat.InnerUpdater>.

=head2 sys.Core.Cat.ProcStmtArg

A C<Cat.ProcStmtArg> is a C<Tuple>.  It specifies a named argument for a
procedural routine invocation done as a procedure statement, and is
composed into the C<Cat.ProcStmt> definition of said statement.

A C<Cat.ProcStmtArg> has these 7 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the invoked procedural routine's parameter
(either subject-to-update or read-only) that this argument is binding to.

=item C<type> - C<Cat.NameChain>

This is as per the C<type> attribute of a C<Cat.ExprNode>, but applying to
the declared data type of the argument.

=item C<kind> - C<Cat.E_PSAK>

This is the declared kind of value that this argument is; it says how to
interpret the rest of the attributes and/or which of them have significant
values.

=item C<param> - C<Cat.Name>

Iff C<kind> is C<Cat.E_PSAK:upd_param> or C<Cat.E_PSAK:ro_param>, then the
argument is the current value or value of the containing procedure's
subject-to-update or read-only parameter, respectively.

=item C<inner_var> - C<Cat.Name>

Iff C<kind> is C<Cat.E_PSAK:inner_var>, then the argument is the current
value of a lexical variable that isn't a parameter.

=item C<outer_var> - C<Cat.NameChain>

Iff C<kind> is C<Cat.E_PSAK:outer_var>, then the argument is the current
value of a non-lexical variable.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the statement argument.

=back

The default value of C<Cat.ProcStmtArg> will bind to a read-only parameter
of name C<topic> with a value of the containing procedure's read-only
parameter named C<topic>.

=head2 sys.Core.Cat.ProcStmt

A C<Cat.ProcStmt> is a C<Tuple>.  It specifies a generic statement from
which non-implicitly-atomic procedural Muldis D code is composed.  Only
procedures (or inner procedures) may contain C<Cat.ProcStmt>.

A C<Cat.ProcStmt> has these 4 attributes:

=over

=item C<proc> - C<Cat.NameChain>

Every procedure statement is an invocation of some other procedural routine
(eg, procedure, update operator, system service), either user-defined or
system-defined; this is the name of that routine.

=item C<upd_args> - C<Cat.ProcStmtArgSet>

These are the 0..N subject-to-update arguments to the routine invocation,
as-per C<ro_args>.

=item C<ro_args> - C<Cat.ProcStmtArgSet>

These are the 0..N read-only arguments to the routine invocation.  There is
a distributed (unique) key over the C<name> attributes of C<upd_params> and
C<ro_params>.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the statement as a whole.

=back

The default value of C<Cat.ProcStmt> will invoke
C<sys.Core.Universal.assign>, giving it arguments from same-named and typed
parameters.

=head2 sys.Core.Cat.InnerProc

A C<Cat.InnerProc> is a C<Tuple>.  It specifies a named C<procedure>
routine, which is the main component type of a complete procedure; a
complete procedure consists of at least one inner procedure, which is its
main body, likely plus more when it would conceptually be code refactored.

A C<Cat.InnerProc> has these 7 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the inner procedure within its parent complete
procedure; other Muldis D code within said complete procedure would
reference it with this name.

=item C<is_recursive> - C<Bool>

This is C<Bool:true> if the inner procedure might possibly invoke
itself, either directly or indirectly; it is C<Bool:false> if it promises
to never be recursive.  I<Note that this attribute may be eliminated.>

=item C<upd_params> - C<Cat.NameTypeMap>

This is the declared subject-to-update parameter list of the inner
procedure, which has 0..N named and typed such parameters.

=item C<ro_params> - C<Cat.NameTypeMap>

This is the declared read-only parameter list of the inner procedure,
which has 0..N named and typed such parameters.  There is a distributed
(unique) key over the C<name> attributes of C<upd_params> and C<ro_params>.

=item C<vars> - C<Cat.NameTypeMap>

This defines the 0..N (non-parameter) lexical variables of the inner
procedure; they initialize to the default values of their declared types.

=item C<stmts> - C<Cat.SeqOfProcStmt>

This defines the entire main body of the inner procedure, which is composed
of 0..N procedure statements.  These statements must reference all of the
parameters and lexical variables that the inner procedure has.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the inner procedure as a
whole.

=back

The default value of C<Cat.InnerProc> has an empty name and is a no-op; its
C<name> has the default value of C<Cat.Name>, it has zero parameters, zero
variables, and zero statements.

=head2 sys.Core.Cat.Proc

A C<Cat.Proc> is a C<Tuple>.  It specifies a named C<procedure> routine,
which is conceptually a non-anonymous procedure that is generally invokable
by the public (unless its parent package says otherwise).

A C<Cat.Proc> has these 5 attributes:

=over

=item C<name> - C<Cat.Name>

This is the declared name of the procedure; other Muldis D code would
reference it with this name.

=item C<inner_procs> - C<Cat.InnerProcTree>

This (save for C<inner_updaters> and C<inner_funcs>) defines the entire
body of the procedure, which is composed of one or more inner procedures,
plus its public interface / parameter list, which is defined by one of
those.  The inner procedure defining the outer procedure's main body has
the empty string as its name.

=item C<inner_updaters> - C<Cat.InnerUpdaterSet>

This also contributes to the body of the procedure.

=item C<inner_funcs> - C<Cat.InnerFuncSet>

This also contributes to the body of the procedure.

=item C<comment> - C<Cat.Comment>

This is an optional programmer comment about the procedure as a whole.

=back

The default value of C<Cat.Proc> is as per the default of C<Cat.InnerProc>.

=head2 sys.Core.Cat.Exception

I<TODO.>

=head1 SYSTEM-DEFINED CORE CATALOG RELATION DATA TYPES

These relation data types, essentially all of the system-defined relation
types are special-purpose in nature and are intended for use in defining or
working with the system catalog.  They are all completely defined types.

I<To keep things simpler for now, most constraint definitions for these
types are missing, or just defined informally.>

=head2 sys.Core.Cat.NameTypeMap

A C<Cat.NameTypeMap> is a C<Relation>.  It defines a basic component list,
meaning a set of names, with a declared data type name for each.  It forms
the foundation for most componentized type definitions, including all tuple
and relation types (for which it is named I<heading>), and it is used also
for the components list of a scalar possrep.  It is also used to define
parameter lists for routines.  A C<Cat.NameTypeMap> has 2 attributes,
C<name> (a C<Cat.Name>) and C<type> (a C<Cat.NameChain>); the C<name> is
the declared name of the attribute or parameter, and comprises a unary key;
the C<type> is the declared data type of the attribute or parameter.  Its
default value has zero tuples.

=head2 sys.Core.Cat.NameExprMap

A C<Cat.NameExprMap> is a C<Relation>.  It defines a basic component-values
list, meaning a set of names, with a declared local expression node name
for each.  It is used to define collection literals; one C<Cat.NameExprMap>
defines a whole C<Tuple> value.  It is also used to define argument lists
for routine invocations.  A C<Cat.NameExprMap> has 2 attributes, C<name>
and C<expr>, each of those being a C<Cat.Name>; the C<name> is the name of
the tuple/etc attribute or routine argument, and comprises a unary key; the
C<expr> is the declared local name of the expression node which defines the
value for the attribute or argument.  Its default value has zero tuples.

=head2 sys.Core.Cat.AttrRenameMap

A C<Cat.AttrRenameMap> is a C<Relation>.  It is used as a specification for
how to rename attributes of some collection.  A C<Cat.AttrRenameMap> has 2
attributes, C<before> and C<after>, each of those being a C<Cat.Name>, and
each of those being a unary key.  Its default value has zero tuples.

=head2 sys.Core.Cat.ExprSet

A C<Cat.ExprSet> is the same as a C<Cat.ExprTree> except that it can
represent multiple trees rather than one, and there is no requirement for
any node to be named with the empty string; this is realized in that more
than one (rather than exactly one) member may have none of its peers as a
parent node.  It so happens then that C<Cat.ExprTree> is a proper subtype
of C<Cat.ExprSet>.

=head2 sys.Core.Cat.ExprTree

A C<Cat.ExprTree> is a C<Relation> with the same heading as
C<Cat.ExprNode>; it specifies a simple tree of named expression nodes,
which are its tuples.  It has a unary (unique) key on the C<name>
attribute, and it must have at least 1 member tuple.  All member tuples
must define a simple expression node tree, such that every member except
one (which is the root node) has one of its peers as a parent node, and no
direct cycles between members are permitted (only indirect cycles based on
function / inner-function invocations are allowed); the name of the root
node must be the empty string.  The default value of C<Cat.ExprTree> has
one tuple that is the default value of C<Cat.ExprNode>; the tree represents
the literal scalar value C<Bool:false>.

=head2 sys.Core.Cat.InnerFuncSet

A C<Cat.InnerFuncSet> is a C<Relation> with the same heading as
C<Cat.InnerFunc>; it specifies a set of inner functions (that comprise
parts of the same complete routine), which are its tuples.  It has a unary
(unique) key on the C<name> attribute.  Its default value is empty, which
may be applicable if the complete routine is not a function.

=head2 sys.Core.Cat.InnerFuncTree

A C<Cat.InnerFuncTree> is a proper subtype of C<Cat.InnerFuncSet> which is
likely to only be applicable if the complete routine is a function.  It
must have at least 1 member tuple.  All member tuples must define a single
invocation tree but that cycles are allowed, including any cycles that
invoke what is conceptually the tree root (main function if applicable);
the name of the root node must be the empty string.  The default value of
C<Cat.InnerFuncTree> has one tuple that is the default value of
C<Cat.InnerFunc>.

=head2 sys.Core.Cat.MultiUpdStmt

A C<Cat.MultiUpdStmt> is a C<Relation> with the same heading as
C<Cat.UpdStmt>; it is a multi-update statement, which is the narrowest
scope implicitly atomic component of procedural Muldis D code.  One value
of this type comprises the entire body of an update operator (or
inner-update-operator).  It must have at least 1 member tuple.  The default
value of C<Cat.MultiUpdStmt> has one tuple that is the default value of
C<Cat.UpdStmt>.

=head2 sys.Core.Cat.InnerUpdaterSet

A C<Cat.InnerUpdaterSet> is a C<Relation> with the same heading as
C<Cat.InnerUpdater>; it specifies a set of inner update operators (that
comprise parts of the same complete routine), which are its tuples.  It has
a unary (unique) key on the C<name> attribute.  Its default value is empty,
which may be applicable if the complete routine is not an update operator.

=head2 sys.Core.Cat.InnerUpdaterTree

A C<Cat.InnerUpdaterTree> is a proper subtype of C<Cat.InnerUpdaterSet>
which is likely to only be applicable if the complete routine is a update
operator.  It must have at least 1 member tuple.  All member tuples must
define a single invocation tree but that cycles are allowed, including any
cycles that invoke what is conceptually the tree root (main update operator
if applicable); the name of the root node must be the empty string.  The
default value of C<Cat.InnerUpdaterTree> has one tuple that is the default
value of C<Cat.InnerUpdater>.

=head2 sys.Core.Cat.ProcStmtArgSet

A C<Cat.ProcStmtArgSet> is a C<Relation> with the same heading as
C<Cat.ProcStmtArg>; it specifies a set of arguments to an invocation of a
procedural routine.  It has a unary (unique) key on the C<name> attribute.
Its default value is empty.

=head2 sys.Core.Cat.InnerProcTree

A C<Cat.InnerProcTree> is to C<Cat.InnerProc> what C<Cat.InnerUpdaterTree>
is to C<Cat.InnerUpdater>.

=head2 sys.Core.Cat.SetOfName

A C<Cat.SetOfName> is a C<Set> whose C<value> attribute has a declared type
of C<Cat.Name>.

=head2 sys.Core.Cat.SetOfSetOfName

A C<Cat.SetOfSetOfName> is a C<Set> whose C<value> attribute has a declared
type of C<Cat.SetOfName>.

=head2 sys.Core.Cat.SetOfNameExprMap

A C<Cat.SetOfNameExprMap> is a C<Set> whose C<value> attribute has a
declared type of C<Cat.NameExprMap>.

=head2 sys.Core.Cat.SetOfNameChain

A C<Cat.SetOfNameChain> is a C<Set> whose C<value> attribute has a declared
type of C<Cat.NameChain>.

=head2 sys.Core.Cat.NESeqOfName

A C<Cat.NESeqOfName> is a C<Seq> whose C<value> attribute has a declared
type of C<Cat.Name> and that must have at least 1 element; this type is
used as the definition of the sequence possrep of a C<Cat.NameChain> (see
that type for details).

=head2 sys.Core.Cat.SeqOfProcStmt

A C<Cat.SeqOfProcStmt> is a C<Seq> whose C<value> attribute has a declared
type of C<Cat.ProcStmt>.

=head1 SYSTEM-DEFINED CORE QUASI-CATALOG PARAMETERIZED TYPES

These types are incomplete proper subtypes of other core incomplete types,
and generally speaking their sole purpose is to be the declared data types
of several system-defined N-ary tuple|relation operator parameters which
are collections of generic nonscalar values.  They are called quasi-catalog
because they are not generally expected to be used for user data, but they
also are not used to compose the system catalog either.

=over

=item C<sys.Core.QuasiCat.(Set|Bag)Of(Tuple|Relation)>

A C<(Set|Bag)OfRelation> is an incompletely defined proper subtype of
C<Set|Bag> whose C<value> attribute has a declared type of a
C<Tuple|Relation> subtype; this is the parameter type of several N-ary
relational operators.

=item C<sys.Core.QuasiCat.SetOfBag>

A C<SetOfBag> is an incompletely defined proper subtype of C<Set> whose
C<value> attribute has a declared type of a C<Bag> subtype; this is the
parameter type of several N-ary relational operators that work with C<Bag>
values.

=item C<sys.Core.QuasiCat.MaybeOfTuple>

A C<MaybeOfTuple> is an incompletely defined proper subtype of C<Maybe>
whose C<value> attribute has a declared type of a C<Tuple> subtype; this is
the parameter type of the C<sys.Core.Relation.maybe_reduction> operator.

=item C<sys.Core.QuasiCat.SeqOfSeq>

A C<SeqOfSeq> is an incompletely defined proper subtype of C<Seq> whose
C<value> attribute has a declared type of a C<Seq> subtype; this is the
parameter type of the N-ary C<sys.Core.Seq.catenation> operator.

=item C<sys.Core.QuasiCat.QuasiSetOf(Tuple|Relation)>

A C<QuasiSetOfRelation> is an incompletely defined proper subtype of
C<QuasiSet> whose C<value> attribute has a declared type of
C<Tuple|Relation>; these are the parameter types of the N-ary
C<sys.Core.Tuple.product> and C<sys.Core.Relation.(join|product)>
operators.

=back

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut