=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.25.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.

These core data types are more special-purpose in nature and are intended
for use in defining or working with the system catalog.  Those types that
are nonscalar are completely defined types.

Note that whenever an attribute of one of the tuple 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.

Note that many of the tuple 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.

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

=head1 TYPE SUMMARY

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

    sys.std.Core.Type.Universal

        sys.std.Core.Type.Empty

        sys.std.Core.Type.Scalar

            # The following are all regular ordered scalar types.

            sys.std.Core.Type.Cat.Name
            sys.std.Core.Type.Cat.NameChain
            sys.std.Core.Type.Cat.DeclNameChain
            sys.std.Core.Type.Cat.Comment

        sys.std.Core.Type.Tuple

            # The following are all regular tuple types.

            sys.std.Core.Type.Cat.FuncHead
            sys.std.Core.Type.Cat.UpdHead
            sys.std.Core.Type.Cat.ProcHead
            sys.std.Core.Type.Cat.FuncBody
            sys.std.Core.Type.Cat.UpdBody
            sys.std.Core.Type.Cat.ProcBody
            sys.std.Core.Type.Cat.InnerFuncBody
            sys.std.Core.Type.Cat.InnerUpdBody
            sys.std.Core.Type.Cat.InnerProcBody
            sys.std.Core.Type.Cat.ProcStmt
            sys.std.Core.Type.Cat.Type
            sys.std.Core.Type.Cat.Exception

            sys.std.Core.Type.Database

                # The following are all regular database types.

                sys.std.Core.Type.Cat.System
                sys.std.Core.Type.Cat.Federation
                sys.std.Core.Type.Cat.Depot
                sys.std.Core.Type.Cat.Package
                sys.std.Core.Type.Cat.ExprNodeSet

        sys.std.Core.Type.Relation

            # The following are all regular relation types.

            sys.std.Core.Type.Cat.SysNspSet
            sys.std.Core.Type.Cat.Sys(Func|Upd|Proc)Set
            sys.std.Core.Type.Cat.DepotMountSet
            sys.std.Core.Type.Cat.SubdepotSet
            sys.std.Core.Type.Cat.PackageSet
            sys.std.Core.Type.Cat.Dep(Func|Upd|Proc)Set
            sys.std.Core.Type.Cat.Pkg(Func|Upd|Proc)Set
            sys.std.Core.Type.Cat.Inner(Func|Upd|Proc)Set
            sys.std.Core.Type.Cat.ScaLitExprNodeSet
            sys.std.Core.Type.Cat.ScaPRLitExprNodeSet
            sys.std.Core.Type.Cat.TupLitExprNodeSet
            sys.std.Core.Type.Cat.RelLitExprNodeSet
            sys.std.Core.Type.Cat.FuncInvoExprNodeSet
            sys.std.Core.Type.Cat.MultiUpdStmt
            sys.std.Core.Type.Cat.NameTypeMap
            sys.std.Core.Type.Cat.NameExprMap
            sys.std.Core.Type.Cat.AttrRenameMap

=head1 TYPES FOR DEFINING ENTITY NAMES AND COMMENTS

=head2 sys.std.Core.Type.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 representation (each value as a
string of characters) and cardinality though its values are distinct; it is
specifically intended for use in naming DBMS entities rather than being for
general-purpose user data.  The default value et al is as for C<Text>.

=head2 sys.std.Core.Type.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> is conceptually a sequence of 2..N
C<Cat.Name>, the 2..N elements being ordered from parent-most to child-most
component name.  A C<Cat.NameChain> has 2 system-defined possreps, named
C<seq> and C<flat>, both of which are defined over C<Cat.Name>.

The C<seq> possrep directly matches the conception of the type; it consists
of 1 attribute whose name is the empty string; the attribute is a C<Seq>
whose C<value> attribute has a declared type of C<Cat.Name> and that must
have at least 2 elements.

The C<flat> possrep consists of 1 attribute whose name is the empty string;
the attribute is a C<Cat.Name>, its value being identical to 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.

The default and minimum value of C<Cat.NameChain> is a 2 element sequence
where each element is the default value of C<Cat.Name> (the empty string);
its maximum value is an infinite sequence where each element is the maximum
value of C<Cat.Name> (an infinite-length string) and practically
impossible.  The cardinality of this type is infinity; to define a
most-generalized finite C<Cat.NameChain> subtype, you must specify a
maximum number of sequence elements of its values, and each element must be
of a finite C<Cat.Name> subtype.

=head2 sys.std.Core.Type.Cat.DeclNameChain

A C<Cat.DeclNameChain> (scalar) is mostly the same as a C<Cat.NameChain>
but that it is a sequence of 0..N rather than 2..N, and that its C<flat>
possrep has N+1 periods rather than N-1; the possrep starts with a period,
and also has a period just following each sequence element, and so an empty
sequence means a C<flat> possrep consisting of just a period.  A
C<Cat.DeclNameChain> is used in declaring system catalogs where DBMS
entities live under a potentially N-depth namespace, such as depot entities
grouped in a subdepot hierarchy.  The default and minimum value of
C<Cat.DeclNameChain> is a zero element sequence.

=head2 sys.std.Core.Type.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 exactly the same as C<Cat.Name> in representation and cardinality though
its values are distinct; it is intended just for commenting Muldis D code.
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.  The
default value et al is as for C<Cat.Name>.

=head1 TYPES FOR DEFINING SYSTEM-DEFINED ENTITIES

=head2 sys.std.Core.Type.Cat.System

A C<Cat.System> is a C<Database>.  It specifies the public interfaces of
system-defined entities, specifically all the system-defined types,
routines, and catalogs.  Both standard system-defined entities and
implementation-specific system-defined entities are specified here,
specifically all the relcons and relvars with the names
C<(sys|mnt|fed|dep|sdp|pkg).cat>.  The system catalog constant named
C<sys.cat> is of the C<Cat.System> type.

A C<Cat.System> has these 11 attributes:

=over

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

This is an optional programmer comment about the collection of
system-defined entities as a whole.

=item C<namespaces> - C<Cat.SysNspSet>

These are all the system-defined namespaces where DBMS entities may live,
or that otherwise always exist due to being system-defined.  Specifically,
it declares these 27 standard language namespaces:
C<.(sys|mnt|fed|dep|sdp|pkg|inn|lex).> (which have the nameless global root
namespace as their parent, spelled C<.>, that isn't also declared here),
C<.sys.(cat|std|imp).>, C<.mnt.cat.>,
C<.(fed|dep|sdp|pkg).(cat|lib|data).>, C<.sys.std.Core.>,
C<.sys.std.Core.Type.>, C<.sys.std.Core.Type.Cat.>; it also declares other
C<Core> namespaces, and where applicable, standard extensions or
implementation-specific extensions.

=item C<functions|updaters|procedures> - C<Cat.Sys(Func|Upd|Proc)Set>

These are the interfaces of all the system-defined
functions|updaters|procedures.

=item C<special_types> - C<Cat.SysSpecTypeSet>

These are the few central system-defined data types that have special
hard-coded meanings and are not defined like any other types.
Specifically, it declares these 9 standard types (all in the
C<sys.std.Core.Type> namespace): C<Universal>, C<Empty>, C<Scalar>,
C<Tuple>, C<Relation>, C<QuasiScalar>, C<QuasiTuple>, C<QuasiRelation>,
C<Remnant>.

=item C<sca_npr_types> - C<Cat.SysScaNPRTypeSet>

These are all the system-defined (|quasi-)scalar root (not union etc) types
that have no possreps, the likes of which users can not define, and values
of which can only be selected using either system-defined literal syntax or
mapping functions.  Specifically, it declares these 7 standard types: in
the C<sys.std.Core.Type> namespace, C<Bool>, C<Int>, C<Blob>, C<Text>,
C<QuasiScalarDVPT>; in the C<sys.std.Core.Type.Cat> namespace, C<Name>,
C<Comment>.

=item C<(sca|non_sca|dom)_types> - C<Cat.Sys(Sca|NonSca|Dom)TypeSet>

These are all the system-defined (|quasi-)scalar types with possreps, and
complete (|quasi-)nonscalar types, and domain types.

=item C<catalogs> - C<Cat.SysCatSet>

These are the interfaces of all the catalog relcons and relvars.
Specifically, it declares these 6 standard catalogs:
C<(sys|mnt|fed|dep|sdp|pkg).cat>; the first is a relcon, the others not.

=back

The default value of C<Cat.System> defines a system with zero builtins.

=head2 sys.std.Core.Type.Cat.SysNspSet

A C<Cat.SysNspSet> is a C<Relation> that specifies the set of system
namespaces that exist for organizing DBMS public entities, mostly the
system-defined ones; these system namespaces are organized into a tree
whose root has no name.  A C<Cat.SysNspSet> only specifies that a system
namespace exists, not which public entities it contains; see the
C<Cat.System> which contains it for that.

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

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the nameless global root namespace, of
the system namespace's parent system namespace.

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

This is the declared name of the system namespace within the namespace
defined by C<parent>; other Muldis D code would reference it with the
combination of C<parent> and C<name>.

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

This is an optional programmer comment about this specific system
namespace.

=back

A C<Cat.SysNspSet> has a binary (unique) key on the C<parent> plus
C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.Sys(Func|Upd|Proc)Set

A C<Cat.Sys(Func|Upd|Proc)Set> is a C<Relation> that specifies a set of
system-defined functions|updaters|procedures.

A C<Cat.Sys(Func|Upd|Proc)Set> has these 4 attributes:

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the nameless global root namespace, of
the function|updater|procedure's parent system namespace.

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

This is the declared name of the function|updater|procedure within the
namespace defined by C<parent>; other Muldis D code would reference it with
the combination of C<parent> and C<name>.

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

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

=item C<head> - C<Cat.(Func|Upd|Proc)Head>

This defines the entire function|updater|procedure heading, that is its
public interface sans the name, which is all the details of how to use it
and no more detail than necessary about how it is implemented.

=back

A C<Cat.Sys(Func|Upd|Proc)Set> has a binary (unique) key on the C<parent>
plus C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.SysSpecTypeSet

A C<Cat.SysSpecTypeSet> is a C<Relation> that specifies a set of
system-defined types which are particularly special and unlike other types.

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

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the nameless global root namespace, of
the type's parent system namespace.

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

This is the declared name of the type within the namespace defined by
C<parent>; other Muldis D code would reference it with the combination of
C<parent> and C<name>.

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

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

=back

A C<Cat.SysSpecTypeSet> has a binary (unique) key on the C<parent> plus
C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.SysScaNPRTypeSet

A C<Cat.SysSpecTypeSet> is a C<Relation> that specifies a set of
system-defined (|quasi-)scalar root (not union etc) types that have no
possreps.

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

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the nameless global root namespace, of
the type's parent system namespace.

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

This is the declared name of the type within the namespace defined by
C<parent>; other Muldis D code would reference it with the combination of
C<parent> and C<name>.

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

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

=item C<is_quasi> - C<Bool>

This is C<Bool:true> if the type is a quasi-scalar type; it is
C<Bool:false> if the type is a scalar type.

=back

A C<Cat.SysScaNPRTypeSet> has a binary (unique) key on the C<parent> plus
C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.Sys(Sca|NonSca|Dom)TypeSet

A C<Cat.Sys(Sca|NonSca|Dom)TypeSet> is a C<Relation> that specifies a set
of system-defined scalar|nonscalar|domain types.

A C<Cat.Sys(Sca|NonSca|Dom)TypeSet> has these 4 attributes:

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the nameless global root namespace, of
the scalar|nonscalar|domain type's parent system namespace.

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

This is the declared name of the scalar|nonscalar|domain type within the
namespace defined by C<parent>; other Muldis D code would reference it with
the combination of C<parent> and C<name>.

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

This is an optional programmer comment about the scalar|nonscalar|domain
type as a whole.

=item C<type> - C<Cat.(Scalar|Nonscalar|Domain)Type>

This defines the entire scalar|nonscalar|domain type sans the name.

=back

A C<Cat.Sys(Sca|NonSca|Dom)TypeSet> has a binary (unique) key on the
C<parent> plus C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.SysCatSet

A C<Cat.SysCatSet> is a C<Relation> that specifies a set of system-defined
catalog dbvars; each tuple specifies one catalog dbvar.

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

=over

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

This is the fully-qualified name of the catalog dbvar.

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

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

=item C<is_readonly> - C<Bool>

This is C<Bool:true> if a catalog relcon is being described; it is
C<Bool:false> if a catalog relvar is being described.

=item C<catalog> - C<Cat.DbVar>

This is the definition of the catalog dbvar.

=back

A C<Cat.SysCatSet> has a unary (unique) key on the C<name> attribute.  Its
default value is empty.

=head1 TYPES FOR DEFINING FEDERATIONS

=head2 sys.std.Core.Type.Cat.Federation

A C<Cat.Federation> is a C<Database>.  It specifies a federation of depot
mounts, that is, all the depot mounts that an in-DBMS process can see or
update, and that defines the scope of an active transaction.  There is
exactly one of these per process and it doesn't have a name.  The system
catalog variable named C<fed.cat> is of the C<Cat.Federation> type.

A C<Cat.Federation> has these 2 attributes:

=over

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

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

=item C<mounts> - C<Cat.DepotMountSet>

These are the depot mounts that comprise the federation.

=back

The default value of C<Cat.Federation> has zero depot mounts.

=head2 sys.std.Core.Type.Cat.DepotMountSet

A C<Cat.DepotMountSet> is a C<Relation> that specifies a set of depot
mounts, such that each tuple is a single depot mount.  A depot mount is a
named in-DBMS context by which a depot is referenced from either other
depots or by the main application, and it also specifies the catalog
content of the depot itself.

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

=over

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

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

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

This is an optional programmer comment about this specific mount of the
depot.

=item C<depot> - C<Cat.Depot>

This defines the entire system catalog of the depot that this mount has
made visible to the DBMS.

=back

A C<Cat.DepotMountSet> has a unary (unique) key on the C<name> attribute.
Its default value is empty.

=head1 TYPES FOR DEFINING DEPOTS AND SUBDEPOTS

=head2 sys.std.Core.Type.Cat.Depot

A C<Cat.Depot> is a C<Database>.  It specifies the entire system catalog of
a single depot, that is, the widest scope within which all entities must be
fully defined in terms of just user-defined entities within the same scope
or of system-defined entities.  It also doubles to specify the system
catalog of a subdepot, which is an arbitrary subset of a depot's entities
that internally looks like a depot; a depot can have 0..N subdepots, and
any that exist are arranged in a hierarchy with the depot as the root.  The
system catalog variables named C<dep.cat> and C<sdp.cat> are both of the
C<Cat.Depot> type.

A C<Cat.Depot> has these 10 attributes:

=over

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

This is an optional programmer comment about the (|sub)depot as a whole.

=item C<subdepots> - C<Cat.SubdepotSet>

These are all the subdepots that this (|sub)depot contains.

=item C<packages> - C<Cat.PackageSet>

These are all the packages that this (|sub)depot contains.

=item C<functions|updaters|procedures> - C<Cat.Dep(Func|Upd|Proc)Set>

These are all the function|updater|procedure definitions that this
(|sub)depot contains.

=item C<(sca|non_sca|dom)_types> - C<Cat.Dep(Sca|NonSca|Dom)TypeSet>

These are all the definitions that this (|sub)depot contains of
(|quasi-)scalar types with possreps, and complete (|quasi-)nonscalar types,
and domain types.

=item C<data> - C<single_of.Cat.DbVar>

This is the definition of the dbvar that this (|sub)depot contains.

=back

The default value of C<Cat.Depot> defines an empty (|sub)depot.

=head2 sys.std.Core.Type.Cat.SubdepotSet

A C<Cat.SubdepotSet> is a C<Relation> that specifies the set of subdepots
that a depot might optionally have for organizing its public entities;
these subdepots are organized into a tree whose root is the depot.  A
C<Cat.SubdepotSet> only specifies that a subdepot exists, not which depot
entities it contains; see the C<Cat.Depot> which contains it for that.

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

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the C<dep.(cat|lib|data)> namespace,
of the subdepot's parent subdepot, which is often just the depot itself.

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

This is the declared name of the subdepot within the namespace defined by
C<parent>; other Muldis D code would reference it with the combination of
C<parent> and C<name>.

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

This is an optional programmer comment about this specific subdepot.

=back

A C<Cat.SubdepotSet> has a binary (unique) key on the C<parent> plus
C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.PackageSet

A C<Cat.PackageSet> is a C<Relation> that specifies the set of packages
that a depot might optionally have for organizing its possibly private
entities.

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

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the C<dep.(cat|lib|data)> namespace,
of the packages's parent (|sub)depot.

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

This is the declared name of the package within the namespace defined by
C<parent>; other Muldis D code would reference it with the combination of
C<parent> and C<name>.

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

This is an optional programmer comment about the package definition as
associated with this package name.

=item C<package> - C<Cat.Depot>

This defines the entire system catalog of the package.

=back

A C<Cat.PackageSet> has a binary (unique) key on the C<parent> plus
C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.Dep(Func|Upd|Proc)Set

A C<Cat.Dep(Func|Upd|Proc)Set> is a C<Relation> that specifies a set of
functions|updaters|procedures that a (|sub)depot might directly contain.

A C<Cat.Dep(Func|Upd|Proc)Set> has these 5 attributes:

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the C<dep.(cat|lib|data)> namespace,
of the function|updater|procedure's parent (|sub)depot.

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

This is the declared name of the function|updater|procedure within the
namespace defined by C<parent>; other Muldis D code would reference it with
the combination of C<parent> and C<name>.

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

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

=item C<head> - C<Cat.(Func|Upd|Proc)Head>

This defines the entire function|updater|procedure heading, that is its
public interface sans the name, which is all the details of how to use it
and no more detail than necessary about how it is implemented.

=item C<body> - C<Cat.(Func|Upd|Proc)Body>

This defines the entire function|updater|procedure body, that is its
implementation, besides what C<interface> defines.

=back

A C<Cat.Dep(Func|Upd|Proc)Set> has a binary (unique) key on the C<parent>
plus C<name> attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.Dep(Sca|NonSca|Dom)TypeSet

A C<Cat.Dep(Sca|NonSca|Dom)TypeSet> is a C<Relation> that specifies a set
of scalar|nonscalar|domain types that a (|sub)depot might directly contain.

A C<Cat.Dep(Sca|NonSca|Dom)TypeSet> has these 4 attributes:

=over

=item C<parent> - C<Cat.DeclNameChain>

This is the fully-qualified name, in the C<dep.(cat|lib|data)> namespace,
of the scalar|nonscalar|domain type's parent (|sub)depot.

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

This is the declared name of the scalar|nonscalar|domain type within the
namespace defined by C<parent>; other Muldis D code would reference it with
the combination of C<parent> and C<name>.

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

This is an optional programmer comment about the scalar|nonscalar|domain
type as a whole.

=item C<type> - C<Cat.(Scalar|Nonscalar|Domain)Type>

This defines the entire scalar|nonscalar|domain type sans the name.

=back

A C<Cat.Dep(Sca|NonSca|Dom)TypeSet> has a binary (unique) key on the
C<parent> plus C<name> attributes.  Its default value is empty.

=head1 TYPES FOR DEFINING PACKAGES

=head2 sys.std.Core.Type.Cat.Package

A C<Cat.Package> is a C<Database>.  It specifies the entire system catalog
of a single package, which provides a privatizing namespace for a subset of
a depot's entities; entities outside a package can only invoke that
package's entities which have been declared part of its public interface.
A package internally looks like a depot but that it doesn't contain
subdepots or other packages.  The system catalog variable named C<pkg.cat>
is of the C<Cat.Package> type.

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

=over

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

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

=item C<functions|updaters|procedures> - C<Cat.Pkg(Func|Upd|Proc)Set>

These are all the function|updater|procedure definitions that this package
contains.

=item C<(sca|non_sca|dom)_types> - C<Cat.Pkg(Sca|NonSca|Dom)TypeSet>

These are all the definitions that this package contains of (|quasi-)scalar
types with possreps, and complete (|quasi-)nonscalar types, and domain
types.

=item C<data> - C<single_of.Cat.DbVar>

This is the definition of the dbvar that this package contains.

=back

The default value of C<Cat.Package> defines an empty package.

=head2 sys.std.Core.Type.Cat.Pkg(Func|Upd|Proc)Set

A C<Cat.Pkg(Func|Upd|Proc)Set> is a C<Relation> that specifies a set of
functions|updaters|procedures that a package might contain, where each
function|updater|procedure may be either public for the DBMS as a whole or
private to the package.

A C<Cat.Pkg(Func|Upd|Proc)Set> has these 5 attributes:

=over

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

This is the declared name of the function|updater|procedure.

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

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

=item C<is_public> - C<Bool>

This is C<Bool:true> if the function|updater|procedure is part of the
package's own public interface and may be invoked from outside the package;
it is C<Bool:false> if it is just part of the package's internals.

=item C<head> - C<Cat.(Func|Upd|Proc)Head>

This defines the entire function|updater|procedure heading, that is its
public interface sans the name, which is all the details of how to use it
and no more detail than necessary about how it is implemented.

=item C<body> - C<Cat.(Func|Upd|Proc)Body>

This defines the entire function|updater|procedure body, that is its
implementation, besides what C<interface> defines.

=back

A C<Cat.Pkg(Func|Upd|Proc)Set> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.Pkg(Sca|NonSca|Dom)TypeSet

A C<Cat.Pkg(Sca|NonSca|Dom)TypeSet> is a C<Relation> that specifies a set
of scalar|nonscalar|domain types that a package might contain, where each
scalar|nonscalar|domain type may be either public for the DBMS as a whole
or private to the package.

A C<Cat.Pkg(Sca|NonSca|Dom)TypeSet> has these 4 attributes:

=over

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

This is the declared name of the scalar|nonscalar|domain type.

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

This is an optional programmer comment about the scalar|nonscalar|domain
type as a whole.

=item C<is_public> - C<Bool>

This is C<Bool:true> if the scalar|nonscalar|domain type is part of the
package's own public interface and may be directly invoked from outside the
package; it is C<Bool:false> if it is just part of the package's internals.

=item C<type> - C<Cat.(Scalar|Nonscalar|Domain)Type>

This defines the entire scalar|nonscalar|domain type sans the name.

=back

A C<Cat.Pkg(Sca|NonSca|Dom)TypeSet> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head1 TYPES FOR DEFINING ROUTINE HEADINGS

=head2 sys.std.Core.Type.Cat.FuncHead

A C<Cat.FuncHead> is a C<Tuple>.  It specifies the entire heading or public
interface of a function or inner function, except for its name and
public/private status; the latter are provided by any type embedding this
one when applicable.

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

=over

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

This is an optional programmer comment about the function heading.

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

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

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

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

=back

The default value of C<Cat.FuncHead> has zero parameters and a result type
of C<Bool>.

=head2 sys.std.Core.Type.Cat.UpdHead

A C<Cat.UpdHead> is a C<Tuple>.  It specifies the entire heading or public
interface of an updater or inner updater, except for its name and
public/private status; the latter are provided by any type embedding this
one when applicable.

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

=over

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

This is an optional programmer comment about the updater heading.

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

This is the declared subject-to-update parameter list of the updater, 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 updater, which has
0..N named and typed such parameters.

=back

There is a distributed (unique) key over the C<name> attributes of
C<upd_params> and C<ro_params>.

The default value of C<Cat.UpdHead> has 1 subject-to-update parameter whose
name is C<topic> and whose declared type is C<Bool>; it has zero read-only
parameters.

=head2 sys.std.Core.Type.Cat.ProcHead

A C<Cat.ProcHead> is a C<Tuple>.  It specifies the entire heading or public
interface of a procedure or inner procedure, except for its name and
public/private status; the latter are provided by any type embedding this
one when applicable.

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

=over

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

This is an optional programmer comment about the procedure heading.

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

This is the declared subject-to-update parameter list of the 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 procedure, which has
0..N named and typed such parameters.

=back

There is a distributed (unique) key over the C<name> attributes of
C<upd_params> and C<ro_params>.

The default value of C<Cat.ProcHead> has zero parameters.

=head1 TYPES FOR DEFINING ROUTINE BODIES

=head2 sys.std.Core.Type.Cat.FuncBody

A C<Cat.FuncBody> is a C<Tuple>.  It specifies the entire body or
implementation of a function, besides the details that a C<Cat.FuncHead>
has, one of which each C<Cat.FuncBody> typically must be paired with.

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

=over

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

This is an optional programmer comment about the function body.

=item C<main_body> - C<Cat.InnerFuncBody>

This defines the entire main body of the function, namely what's left of
the function body after parts of it are optionally factored out into inner
routines or inner types.  It must consist of a value expression whose
result type is of the result type of the function, and which invokes all of
the function's parameters.

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

These are all the inner function definitions that this function contains.

=item C<inner_(sca|non_sca|dom)_types> -
C<Cat.Inner(Sca|NonSca|Dom)TypeSet>

These are all the inner scalar|nonscalar|domain type definitions that this
function contains.

=back

There is a distributed (unique) key over the C<name> attributes of
C<inner_(funcs|(sca|non_sca|dom)_types)>.

The default value of C<Cat.FuncBody> directly corresponds to the default
value of C<Cat.FuncHead> and unconditionally results in the value
C<Bool:false>.

=head2 sys.std.Core.Type.Cat.UpdBody

A C<Cat.UpdBody> is a C<Tuple>.  It specifies the entire body or
implementation of an updater, besides the details that a C<Cat.UpdHead>
has, one of which each C<Cat.UpdBody> typically must be paired with.

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

=over

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

This is an optional programmer comment about the updater body.

=item C<main_body> - C<Cat.InnerUpdBody>

This defines the entire main body of the updater, namely what's left of the
updater body after parts of it are optionally factored out into inner
routines or inner types.  It must consist of a multi-update statement which
invokes all of the updater's parameters.

=item C<inner_upds> - C<Cat.InnerUpdSet>

These are all the inner updater definitions that this updater contains.

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

These are all the inner function definitions that this updater contains.

=item C<inner_(sca|non_sca|dom)_types> -
C<Cat.Inner(Sca|NonSca|Dom)TypeSet>

These are all the inner scalar|nonscalar|domain type definitions that this
updater contains.

=back

There is a distributed (unique) key over the C<name> attributes of
C<inner_(upds|funcs|(sca|non_sca|dom)_types)>.

The default value of C<Cat.UpdBody> directly corresponds to the default
value of C<Cat.UpdHead> and unconditionally updates its C<topic> argument
to the value C<Bool:false>.

=head2 sys.std.Core.Type.Cat.ProcBody

A C<Cat.ProcBody> is a C<Tuple>.  It specifies the entire body or
implementation of a procedure, besides the details that a C<Cat.ProcHead>
has, one of which each C<Cat.ProcBody> typically must be paired with.

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

=over

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

This is an optional programmer comment about the procedure body.

=item C<main_body> - C<Cat.InnerProcBody>

This defines the entire main body of the procedure, namely what's left of
the procedure body after parts of it are optionally factored out into inner
routines or inner types.

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

These are all the inner procedure definitions that this procedure contains.

=item C<inner_upds> - C<Cat.InnerUpdSet>

These are all the inner updater definitions that this procedure contains.

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

These are all the inner function definitions that this procedure contains.

=item C<inner_(sca|non_sca|dom)_types> -
C<Cat.Inner(Sca|NonSca|Dom)TypeSet>

These are all the inner scalar|nonscalar|domain type definitions that this
procedure contains.

=back

There is a distributed (unique) key over the C<name> attributes of
C<inner_(procs|upds|funcs|(sca|non_sca|dom)_types)>.

The default value of C<Cat.ProcBody> directly corresponds to the default
value of C<Cat.ProcHead> and is a no-op, having zero statements.

=head2 sys.std.Core.Type.Cat.Inner(Func|Upd|Proc)Set

A C<Cat.Inner(Func|Upd|Proc)Set> is a C<Relation> that specifies a set of
inner functions|updaters|procedures that a function|updater|procedure might
contain.

A C<Cat.Inner(Func|Upd|Proc)Set> has these 4 attributes:

=over

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

This is the declared name of the inner function|updater|procedure.

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

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

=item C<head> - C<Cat.(Func|Upd|Proc)Head>

This defines the entire inner function|updater|procedure heading, that is
its public interface sans the name, which is all the details of how to use
it and no more detail than necessary about how it is implemented.

=item C<body> - C<Cat.Inner(Func|Upd|Proc)Body>

This defines the entire inner function|updater|procedure body, that is its
implementation, besides what C<interface> defines.

=back

A C<Cat.Inner(Func|Upd|Proc)Set> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head1 TYPES FOR DEFINING INNER ROUTINE BODIES

=head2 sys.std.Core.Type.Cat.InnerFuncBody

A C<Cat.InnerFuncBody> is a C<Tuple>.  It specifies the entire body or
implementation of an inner function (or the main body of a function),
besides the details that a C<Cat.FuncHead> has, one of which each
C<Cat.InnerFuncBody> typically must be paired with.

A C<Cat.InnerFuncBody> has these 2 attributes:

=over

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

This is an optional programmer comment about the (|inner )function body.

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

This defines the value expression tree that comprises the entire (|inner
)function body.

=back

There is a distributed (unique) key over the C<name> attributes of all the
attributes of C<expr>; and if this C<Cat.InnerFuncBody> is paired with a
C<Cat.FuncHead>, then the distributed key also extends over the head's
parameter names.

A C<Cat.InnerFuncBody> specifies a simple value expression tree of named
expression nodes, each of which is a tuple of one of its C<expr.\w+_exprs>
attributes.  It must have at least 1 member node, except that it may have
zero member nodes iff the (|inner )function it is composed into has exactly
1 parameter, in which case the value expression tree implicitly results in
the argument to said parameter.  Otherwise:  All member nodes 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 (|inner
)function invocations are allowed); the name of the root node must be the
empty string.  Note that the composed-into (|inner )function's parameters
are also implicitly tree nodes, and are referenced by name into the
expression the same way as any other named expression node is.  Regardless
of whether the node count is zero or 1+, the tree must denote a value
expression whose result type is of the result type of the (|inner )function
it is composed into, and which invokes all of the (|inner )function's
parameters.

The default value of C<Cat.InnerFuncBody> directly corresponds to the
default value of C<Cat.FuncHead> and unconditionally results in the value
C<Bool:false>.

=head2 sys.std.Core.Type.Cat.ExprNodeSet

A C<Cat.ExprNodeSet> is a C<Database> that specifies a set of named value
expression nodes.  It is typically composed into a (|inner
)(function|updater). Each tuple of a C<Cat.ExprNodeSet> attribute is 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 expression nodes, either directly,
or indirectly by way of (|inner )function invocations, as each (|inner
)function body is itself composed entirely of a single expression tree (of
at least 1 node).  Only functions and updaters may contain expression
nodes, so for any procedures that would conceptually include them, those
portions of the procedures need to be separated out and encapsulated by
named (|inner )functions or (|inner )updaters.  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 (|inner )updaters where the expression is used as an argument
for a subject-to-update parameter of an (|inner )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 (|inner )update operator.

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

=over

=item C<sca_lit_exprs> - C<Cat.ScaLitExprNodeSet>

These are expression nodes that define scalar literals of types such that
the Muldis D dialect provides special literal syntax specific to the type,
and the type may not have any possreps.

=item C<sca_pr_lit_exprs> - C<Cat.ScaPRLitExprNodeSet>

These are expression nodes that define (|quasi-)scalar literals of types
such that each type has at least 1 possrep, and each literal is specified
simply in terms of possrep attributes.

=item C<tup_lit_exprs> - C<Cat.TupLitExprNodeSet>

These are expression nodes that define (|quasi-)tuple literals.

=item C<rel_lit_exprs> - C<Cat.RelLitExprNodeSet>

These are expression nodes that define (|quasi-)relation literals.

=item C<func_invo_exprs> - C<Cat.FuncInvoExprNodeSet>

These are expression nodes that invoke (|inner )functions.

=back

There is a distributed (unique) key over the C<name> attributes of all of a
C<Cat.ExprNodeSet>'s attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.ScaLitExprNodeSet

A C<Cat.ScaLitExprNodeSet> is a C<Relation> that specifies a set of value
expression nodes where each node is a hard-coded scalar literal of one of a
certain collection of system-defined core scalar types (or subtype
thereof).

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

=over

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

This is the declared name of the expression node.

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

This is an optional programmer comment about the expression (leaf) node.

=item C<value> - C<Scalar>

This is the actual literal value that the expression node represents.
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.>

=back

A C<Cat.ScaLitExprNodeSet> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.ScaPRLitExprNodeSet

A C<Cat.ScaPRLitExprNodeSet> is a C<Relation> that specifies a set of value
expression nodes where each node represents a (|quasi-)scalar literal of a
type that has at least 1 possrep, and the literal is specified simply in
terms of possrep attributes.

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

=over

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

This is the declared name of the expression node.

=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.

=item C<is_quasi> - C<Bool>

This is C<Bool:true> if the node denotes a quasi-scalar literal; it is
C<Bool:false> if the node just denotes a scalar literal.

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

This is the name of the type that the (|quasi-)scalar value belongs to.

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

This is the name of the possrep, of the type named by C<scalar_type_name>,
in terms of whose attributes the (|quasi-)scalar value is being selected.

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

These are the attributes (names and values) of the C<possrep_name> possrep
of the (|quasi-)scalar literal.

=back

A C<Cat.ScaPRLitExprNodeSet> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.TupLitExprNodeSet

A C<Cat.TupLitExprNodeSet> is a C<Relation> that specifies a set of value
expression nodes where each node represents a (|quasi-)tuple literal.

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

=over

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

This is the declared name of the expression node.

=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.

=item C<is_quasi> - C<Bool>

This is C<Bool:true> if the node denotes a quasi-tuple literal; it is
C<Bool:false> if the node just denotes a tuple literal.

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

These are the attributes (names and values) of the (|quasi-)tuple literal.

=back

A C<Cat.TupLitExprNodeSet> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.RelLitExprNodeSet

A C<Cat.RelLitExprNodeSet> is a C<Relation> that specifies a set of value
expression nodes where each node represents a (|quasi-)relation literal.

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

=over

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

This is the declared name of the expression node.

=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.

=item C<is_quasi> - C<Bool>

This is C<Bool:true> if the node denotes a quasi-relation literal; it is
C<Bool:false> if the node just denotes a relation literal.

=item C<head> - C<set_of.Cat.Name>

These are the names of all of this (|quasi-)relation literal's attributes.

=item C<body> - C<set_of.Cat.NameExprMap>

These are the (|quasi-)tuples of the (|quasi-)relation literal.

=back

A C<Cat.RelLitExprNodeSet> has a unary (unique) key on the C<name>
attribute.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.FuncInvoExprNodeSet

A C<Cat.FuncInvoExprNodeSet> is a C<Relation> that specifies a set of value
expression nodes where each node represents the result of invoking a named
(|inner )function with specific arguments.

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

=over

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

This is the declared name of the expression node.

=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.

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

This is the name of the (|inner )function being invoked.

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

These are the arguments for the (|inner )function invocation.  Each element
defines one argument value, with the element C<name> matching the invoked
(|inner )function's parameter name, and the element C<expr> naming another
local expression node which defines the value.

=back

A C<Cat.FuncInvoExprNodeSet> has a unary (unique) key on the C<name>
attribute. Its default value is empty.

=head2 sys.std.Core.Type.Cat.InnerUpdBody

A C<Cat.InnerUpdBody> is a C<Tuple>.  It specifies the entire body or
implementation of an inner updater (or the main body of a updater), besides
the details that a C<Cat.UpdHead> has, one of which each
C<Cat.InnerUpdBody> typically must be paired with.

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

=over

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

This is an optional programmer comment about the (|inner )updater body.

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

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 )updater, which is composed of
a single multi-update statement.  This multi-update statement must
reference all of the parameters that the (|inner )updater has.

=back

There is a distributed (unique) key over the C<name> attributes of all the
attributes of C<exprs>; and if this C<Cat.InnerUpdBody> is paired with a
C<Cat.UpdHead>, then the distributed key also extends over the head's
parameter names.

The default value of C<Cat.InnerUpdBody> directly corresponds to the
default value of C<Cat.UpdHead> and unconditionally updates its C<topic>
argument to the value C<Bool:false>.

=head2 sys.std.Core.Type.Cat.MultiUpdStmt

A C<Cat.MultiUpdStmt> is a C<Relation> that specifies a multi-update
statement (of 1..N variables), which is the narrowest scope implicitly
atomic component of procedural Muldis D code.  It is the most fundamental
component of procedural Muldis D code.  The variables being updated are
accessed via the host (|inner )updater's subject-to-update parameters.  All
arbitrarily complex Muldis D value assignments, including relational
assignments, are composed of just C<Cat.MultiUpdStmt>, either directly, or
indirectly by way of (|inner )updater invocations, as each (|inner )updater
body is itself composed entirely of 1 multi-update statement (plus
supporting value expressions).  Only (|inner )updaters may contain
C<Cat.MultiUpdStmt>, so for any procedures that would conceptually include
them, those portions of the procedures need to be separated out and
encapsulated by named (|inner )updaters.  Each tuple of a multi-update
statement is a single update statement, which represents a single
invocation of an (|inner )updater, and at least 1 tuple is required.

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

=over

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

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

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

This is the name of the (|inner )updater being invoked.

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

These are the 1..N subject-to-update arguments to the (|inner )updater
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, the parameter is referenced directly.

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

These are the 0..N read-only arguments to the (|inner )updater invocation.
Each element defines one argument value, with the element C<name> matching
the invoked routine's parameter name, and the element C<expr> naming a
local expression node (or parameter) which defines the value.

=back

There is a distributed (unique) key over the C<name> attributes of
C<upd_args> and C<ro_args>.

The default value of C<Cat.MultiUpdStmt> directly corresponds to the
default value of C<Cat.InnerUpdBody> and unconditionally updates its
containing (|inner )updater's C<topic> argument to the value C<Bool:false>.

=head2 sys.std.Core.Type.Cat.InnerProcBody

A C<Cat.InnerProcBody> is a C<Tuple>.  It specifies the entire body or
implementation of an inner procedure (or the main body of a procedure),
besides the details that a C<Cat.ProcHead> has, one of which each
C<Cat.InnerProcBody> typically must be paired with.

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

=over

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

This is an optional programmer comment about the (|inner )procedure body.

=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<seq_of.Cat.ProcStmt>

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.

=back

There is a distributed (unique) key over the C<name> attributes of all the
attributes of C<vars>; and if this C<Cat.InnerProcBody> is paired with a
C<Cat.ProcHead>, then the distributed key also extends over the head's
parameter names.

The default value of C<Cat.InnerProcBody> directly corresponds to the
default value of C<Cat.ProcHead> and is a no-op, having zero statements.

=head2 sys.std.Core.Type.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
(|inner )procedure may contain C<Cat.ProcStmt>.

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

=over

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

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

=item C<procedure> - 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.NameExprMap>

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

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

These are the 0..N read-only arguments to the routine invocation.  Each
element defines one argument value, with the element C<name> matching the
invoked routine's parameter name, and the element C<expr> naming a local or
global variable or statement-containing routine parameter which defines the
value.

=back

There is a distributed (unique) key over the C<name> attributes of
C<upd_args> and C<ro_args>.

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

=head1 TYPES FOR DEFINING DATA TYPES

=head2 sys.std.Core.Type.Cat.(Scalar|Nonscalar|Domain)Type

A C<Cat.(Scalar|Nonscalar|Domain)Type> is a C<Tuple>.  Its purpose is as
per C<Cat.Inner(Scalar|Nonscalar|Domain)Type>, one of which it is a wrapper
for along with other inner types that are composed into it.

A C<Cat.(Scalar|Nonscalar|Domain)Type> has these 6 attributes:

=over

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

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

=item C<main_type> - C<Cat.Inner(Scalar|Nonscalar|Domain)Type>

This defines the actual main type, which a
C<Cat.(Scalar|Nonscalar|Domain)Type> is just a wrapper for, namely what's
left of the updater body after parts of it are optionally factored out into
inner routines or inner types.

=item C<inner_(sca|non_sca|dom)_types> -
C<Cat.Inner(Sca|NonSca|Dom)TypeSet>

These are all the inner scalar|nonscalar|domain type definitions that this
type contains.

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

These are all the inner function definitions that this type contains.

=back

There is a distributed (unique) key over the C<name> attributes of
C<inner_((sca|non_sca|dom)_types|funcs)>.

The default value of C<Cat.(Scalar|Nonscalar|Domain)Type> is as per
C<Cat.Inner(Scalar|Nonscalar|Domain)Type>.

=head2 sys.std.Core.Type.Cat.Inner(Sca|NonSca|Dom)TypeSet

A C<Cat.Inner(Sca|NonSca|Dom)TypeSet> is a C<Relation> that specifies a set
of inner scalar|nonscalar|domain types that a function|updater|procedure or
scalar|nonscalar|domain type might contain.

A C<Cat.Inner(Sca|NonSca|Dom)TypeSet> has these 3 attributes:

=over

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

This is the declared name of the inner scalar|nonscalar|domain type.

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

This is an optional programmer comment about the inner
scalar|nonscalar|domain type as a whole.

=item C<type> - C<Cat.Inner(Scalar|Nonscalar|Domain)Type>

This defines the entire inner scalar|nonscalar|domain type sans the name.

=back

A C<Cat.Inner(Sca|NonSca|Dom)TypeSet> has a unary (unique) key on the
C<name> attribute.  Its default value is empty.

=head1 TYPES FOR DEFINING INNER DATA TYPES

=head2 sys.std.Core.Type.Cat.InnerScalarType

A C<Cat.InnerScalarType> is a C<Tuple>.  It defines either a new
(|quasi-)scalar root type with at least 1 possrep, or it defines a subtype
of some other (|quasi-)scalar type which also adds at least one possrep to
the other type.  Either way, every possrep defines a candidate
representation that can handle every value of the (|sub)type it is defined
with, and the Muldis D implementation may choose for itself which of these,
or some other alternative, is the actual/physical representation.

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

=over

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

This is an optional programmer comment about the (|quasi-)scalar
(|sub-)type as a whole.

=item C<base_type> - C<maybe_of.Cat.NameChain>

Iff the type being defined is a (|quasi-)scalar root type, then
C<base_type> is not applicable and is a C<Nothing>.  Iff the type being
defined is a subtype of some other (|quasi-)scalar type, then C<base_type>
is a C<Single> whose sole element is the name of that other type.  Note
that any type named by C<base_type> must itself have at least 1 possrep.

=item C<is_quasi> - C<maybe_of.Bool>

Iff the type being defined is a (|quasi-)scalar root type, then C<is_quasi>
is a C<Single> whose sole element is C<Bool:true> if the type is a
quasi-scalar type; the element is C<Bool:false> if the type is a scalar
type.  Iff the type being defined is a subtype of some other type, then
C<is_quasi> is not applicable (would be redundant) and is a C<Nothing>.

=item C<possreps> - C<Cat.PossrepSet>

These are the 1..N possrep definitions that comprise this type such that
each one fully defines a set of attributes plus restrictions on their
collective values whereby it defines a representation of all values of this
type.  Note that if multiple (|quasi-)scalar types are related to each
other such that more than one declares possreps for at least one common
value, then the C<name> attribute of the C<possreps> attributes of all of
those types' definitions have a distributed (unique) key over them.
I<Details of this policy are subject to be revised, but it must still
ensure that diamond subtype/supertype relationships are taken properly into
account.>

=item C<possrep_maps> - C<Cat.PossrepMapSet>

When this type has more than one possrep applicable to all of its values,
these are the definitions of mapping functions for deriving the
representation of a value in one possrep directly from the representation
in another possrep, and also directly in the reverse.  Every one of this
type's possreps must be mapped bidirectionally to every other one of its
possreps, either directly or indirectly.  So for C<P> total possreps, the
total number of bidirectional maps C<M> is in C<< (P-1) <= M <= ((P-1)*P/2)
>>.  When a subtype is adding possreps to an other base type, all of the
mapping functions are defined with the subtype.

=item C<default> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a function that results in the
default (|quasi-)scalar value of the (|sub-)type; it has zero parameters
and its result type is the same as the (|quasi-)scalar type whose
declaration it is part of.

=back

The default value of C<Cat.InnerScalarType> defines a scalar root type with
a single possrep whose name is the empty string and that has no attributes;
it is a singleton type, whose default value is its only value.

=head2 sys.std.Core.Type.Cat.PossrepSet

A C<Cat.PossrepSet> is a C<Relation> that specifies a set of possreps that
a (|quasi-)scalar (|sub-)type might consist primarily of.

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

=over

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

This is the declared name of the possrep.

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

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

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

This defines the 0..N attributes of the possrep.

=item C<constraint> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a C<type_constraint> function that
determines what combinations of possrep attribute values denote values of
the (|sub-)type, besides the restrictions imposed by the declared types of
the attributes individually.  The implicit function heading that this goes
with has a single C<topic> parameter whose declared type is a tuple whose
attributes match those declared by C<attrs> and whose argument denotes the
value to test; the function's implicit result type is C<Bool>.  If the
function unconditionally results in C<Bool:true>, then all possible
combinations of attribute-allowable values are collectively allowed.

=back

A C<Cat.PossrepSet> has a unary (unique) key on the C<name> attribute.  Its
default value is empty.

=head2 sys.std.Core.Type.Cat.PossrepMapSet

A C<Cat.PossrepMapSet> is a C<Relation> such that each tuple in it
specifies a pair of mapping functions to bidirectionally derive a value of
a type between 2 of its possreps.

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

=over

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

This is an optional programmer comment about this bidirectional mapping.

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

This is the declared name of one possrep.

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

This is the declared name of a second possrep.  The value of C<p2> must be
distinct from that of C<p1>, and moreover, the 2 values must be mutually
ordered so that the value of C<p1> is before the value of C<p2>; the latter
constraint defines a C<Cat.PossrepMapSet>'s canonical form.

=item C<p2_from_p1> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a mapping function that derives the
representation of the possrep named by C<p2> from that of the possrep named
by C<p1>.  The implicit function heading that this goes with has a single
C<topic> parameter whose declared type is a tuple whose attributes match
those of C<p1>; the function's implicit result type is a tuple whose
attributes match those of C<p2>.  Note that every distinct argument
(domain) value of this function must have a distinct result (range) value.

=item C<p1_from_p2> - C<Cat.InnerFuncBody>

This defines the entire (main) body of the inverse mapping function to that
of C<p2_from_p1>.  I<Note that it would often be feasible for a Muldis D
implementation to automatically infer a reverse function, but for now we
still require it to be explicitly stated; the explicitly stated inverse
function could be generated though.  This design is subject to change.>

=back

A C<Cat.PossrepMapSet> has a binary (unique) key on the C<p1> plus C<p2>
attributes.  Its default value is empty.

=head2 sys.std.Core.Type.Cat.InnerNonscalarType

A C<Cat.InnerNonscalarType> is a C<Tuple>.  It defines either a new
(|quasi-)nonscalar heading (set of attributes) with associated constraints
for a tuple and relation type having that heading, or it defines a subtype
of some other (|quasi-)nonscalar type.  That is, it defines 2 new data
types, a tuple type and a relation type with matching headings.  Note that
you also declare a database type using C<Cat.InnerNonscalarType>, by
declaring a tuple type whose attributes are all relation or database typed.
Note that you can not use a C<Cat.InnerNonscalarType> to declare or
subtype an incomplete type, as it (or its supertype) must specify a
complete set of attributes.

A C<Cat.InnerNonscalarType> has these 10 attributes:

=over

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

This is an optional programmer comment about the (|quasi-)nonscalar
(|sub-)type as a whole.

=item C<base_type> - C<maybe_of.Cat.NameChain>

Iff the type being defined is a (|quasi-)nonscalar root type, then
C<base_type> is not applicable and is a C<Nothing>.  Iff the type being
defined is a subtype of some other (|quasi-)nonscalar type, then
C<base_type> is a C<Single> whose sole element is the name of that other
type.

=item C<is_quasi> - C<maybe_of.Bool>

Iff the type being defined is a (|quasi-)nonscalar root type, then
C<is_quasi> is a C<Single> whose sole element is C<Bool:true> if the type
is a quasi-nonscalar type; the element is C<Bool:false> if the type is a
nonscalar type.  Iff the type being defined is a subtype of some other
type, then C<is_quasi> is not applicable (would be redundant) and is a
C<Nothing>.

=item C<is_tuple_first> - C<Bool>

Iff this is C<Bool:true> then the type being defined is primarily
considered a tuple type; that is, when either the type name is referenced
normally (not using the C<type> namespace), or the type definition is
embedded (and nameless), then it is simply considered to be a tuple type;
iff this is C<Bool:false> then the type being defined is primarily
considered to be a relation type.  When a type is primarily considered a
tuple or relation type, the only way to reference it as the other kind of
type is by using the C<type.(tuple|relation)_from.\w+> referencing syntax.

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

Iff the type being defined is a (|quasi-)nonscalar root type, then C<attrs>
defines the 0..N attributes of the type.  Iff the type being defined is a
subtype of some other type, then the parent type's attribute list is used
by default, but C<attrs> of the current type may be used to apply
additional constraints by overriding the declared types of a subset of the
parent's attributes with types that are subtypes of the originals; an
override is done using matching C<name> attribute values of C<attrs>.  It
is indeed valid for a (|quasi-)nonscalar type to have zero attributes; in
this case, a tuple type consists of exactly one value, and a relation type
consists of exactly two values.

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

These are the 0..N explicit (unique) keys that are applicable to relation
values of the type being defined; they apply either as candidate keys or as
unique key constraints, depending on context.  If there are no explicit
keys, then there is an implicit (unique) key over all attributes of the
relation type being defined, meaning that every possible tuple that may
individually be an element of a relation value of the type being defined,
may be in it at once.  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 type, and values of the type may each
consist of no more than one tuple.  Note that C<keys> is logically a
short-hand syntax (the canonical simplest form) for a particular kind of
C<relation_constraint> of the type being defined, one that compares the
cardinality of a projection of a relation on its key attributes with the
cardinality of the original relation; the attributes are a key if the
cardinalities are equal.

=item C<tuple_constraint> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a C<type_constraint> function that
determines what combinations of tuple attribute values denote values of the
(|sub-)type, besides the restrictions imposed by the declared types of the
attributes individually; it is a generalized type constraint that validates
a tuple as a whole.  The implicit function heading that this goes with has
a single C<topic> parameter whose declared type is a tuple whose attributes
match those declared by C<attrs> and whose argument denotes the value to
test; the function's implicit result type is C<Bool>.  If the function
unconditionally results in C<Bool:true>, then all possible combinations of
attribute-allowable values are collectively allowed.  This function is
invoked either once to test a tuple value, or multiple times to
individually test every tuple in a relation value.

=item C<relation_constraint> - C<Cat.InnerFuncBody>

This is like C<tuple_constraint> but that the function's parameter is
relation-typed rather than tuple-typed; it is a generalized type constraint
that validates a relation as a whole.

=item C<default_tuple> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a function that results in the
default (|quasi-)tuple value of the (|sub-)type; it has zero parameters and
its result type is the same as the (|quasi-)tuple type whose declaration it
is part of.

=item C<default_relation> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a function that results in the
default (|quasi-)relation value of the (|sub-)type; it has zero parameters
and its result type is the same as the (|quasi-)relation type whose
declaration it is part of.

=back

The default value of C<Cat.InnerNonscalarType> defines a relation type that
is the same as C<RelationD0>, having zero attributes, whose default value
is the one with zero tuples.

=head2 sys.std.Core.Type.Cat.KeySet

A C<Cat.KeySet> is a C<Relation> that specifies a set of candidate keys or
unique key constraints for a relation type; each tuple specifies one
candidate key.

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

=over

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

This is the declared name of the key.

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

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

=item C<attrs> - C<set_of.Cat.Name>

This defines the 0..N host relation attributes comprising the key.  If this
set is empty, then we have a nullary key which restricts the host relation
to have a maximum of 1 tuple.

=item C<is_primary> - C<Bool>

This is C<Bool:true> if all of the attributes comprising this key are
likely to be treated as immutable in practice for the relation's tuples,
and hence are the best candidates for identifying tuples within a relation
over an extended term, and are the best mapping values for automatic new
foreign keys and join conditions if the host relation type has to be
auto-split into several associated ones, for example because the physical
representation of this relation doesn't support RVAs.  This concept is a
generalization of the concept of "the primary key" of a relation.  A
relation type can have either none of its keys or more than one of its keys
with a true C<is_primary> attribute.  This is C<Bool:false> if any of the
attributes comprising this key are likely to mutate and so shouldn't be
used as the target of generated foreign keys.

=back

A C<Cat.KeySet> has a unary (unique) key on the C<name> attribute.  Its
default value is empty.

=head2 sys.std.Core.Type.Cat.InnerDomainType

A C<Cat.InnerDomainType> is a C<Tuple>.  It defines a new data type whose
values are all drawn from one or more specified other types (which can be
any types at all), and that generally speaking it is an arbitrary subset of
C<Universal> (and it has its own default value).  The value set of the new
data type is determined by taking a set of source types' values and
subtracting from it a set of filter types' values, then applying a type
constraint function to the values remaining.  The two likely most common
such type definition scenarios are defining a simple restriction/domain
type over a single scalar source type (no possreps added) using a filter
function, and defining a simple explicit union type of 2+ scalar source
types.  A domain type does not define any changes or supplements to the
interfaces available for working with its values, instead simply using
those of its declared parent types.  A data type defined in this way is
typically not considered to exist when the system wants to determine the
MST (most specific type) of one of its values.

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

=over

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

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

=item C<sources> - C<set_of.Cat.NameChain>

These are the names of the 0..N other types that all the values of the new
data type are drawn from; the complete set of source values is determined
by either unioning (the default) or intersecting the values of these types.

=item C<is_source_intersection> - C<Bool>

Iff this is C<Bool:true> then the set of source data types will be
intersected to determine the complete set of source values, and if
C<sources> has no elements then the source set is just C<Empty>; iff this
is C<Bool:false> then the set of source data types will be unioned to
determine the complete set of source values, and if C<sources> has no
elements then the source set is just C<Universal>.

=item C<filters> - C<set_of.Cat.NameChain>

These are the names of the 0..N other types (which are generally subtypes
of those of C<sources>) that determine values which the new data type will
I<not> contain; the complete set of filter values is determined by either
intersecting (the default) or unioning the values of these types.

=item C<is_filter_union> - C<Bool>

Iff this is C<Bool:true> then the set of filter data types will be unioned
to determine the complete set of filter values, and if C<filters> has no
elements then the filter set is just C<Universal>; iff this is
C<Bool:false> then the set of filter data types will be intersected to
determine the complete set of filter values, and if C<filters> has no
elements then the filter set is just C<Empty>.

=item C<constraint> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a C<type_constraint> function that
determines what filter-type-passing source-type values are part of the
domain type.  The implicit function heading that this goes with has a
single C<topic> parameter whose declared type is C<Universal>, unless there
is exactly 1 C<sources> element whereupon the declared type is the same as
the source type, and whose argument is the value to test; the function's
implicit result type is C<Bool>.  If the function unconditionally results
in C<Bool:true>, then all filter-type-passing values are allowed.

=item C<default> - C<Cat.InnerFuncBody>

This defines the entire (main) body of a function that results in the
default value of the subtype; it has zero parameters and its result type is
the same as the domain type whose declaration it is part of.

=back

The default value of C<Cat.InnerDomainType> defines an alias for
C<Universal>, with the same default value; the C<base_type> is that type,
C<constraint> is unconditionally C<Bool:true>.

=head1 TYPES FOR DEFINING DBVARS

=head2 sys.std.Core.Type.Cat.DbVar

A C<Cat.DbVar> is a C<Tuple>.  It specifies the data type and transition
constraints and so forth of a database-typed variable, such as the
C<(dep|sdp|pkg).data> variables.

A C<Cat.Package> has these 2 attributes:

=over

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

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

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

This defines the entire database type.

=back

I<Transition constraints et al are still TODO.>

The default value of C<Cat.DbVar> defines a variable that is "just a
database" and has no extra constraints.

=head1 SIMPLE GENERIC CATALOG COLLECTION TYPES

=head2 sys.std.Core.Type.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.std.Core.Type.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 (or
parameter or variable) 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> (a C<Cat.Name>) and C<expr> (a
C<Cat.NameChain>); 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 (or parameter or variable) which defines
the value for the attribute or argument.  Note that while the C<expr>
attribute could conceivably just be a C<Cat.Name> because most of its
allowed values would be in the C<lex> namespace, the C<Cat.NameChain> is
used instead so that value expressions can take advantage of terse syntax
for addressing value attributes.  Its default value has zero tuples.

=head2 sys.std.Core.Type.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.

=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