=pod

=encoding utf8

=head1 NAME

Language::MuldisD::PerlHosted -
How to format Perl Hosted Abstract Muldis D

=head1 VERSION

This document is Language::MuldisD::PerlHosted version 0.7.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Language::MuldisD>; you should read that root document
before you read this one, which provides subservient details.

=head1 DESCRIPTION

This document outlines the specification of I<Abstract Muldis D> as hosted
in either Perl 5 or Perl 6, and as composed of just|mainly core Perl types;
for brevity, the term I<PHMD> will be used to refer to this spec.

Where Perl 5 and 6 differ, the terminology and examples in this
documentation specifically uses Perl 6 terminology and examples by default,
and adds analogous Perl 5 terminology as necessary.

Fundamentally, the various Muldis D scalar and collection types are
represented by their equivalent Perl 5 or 6 native scalar and collection
types.  But since Muldis D is more strongly typed, or at least differently
typed, than Perl, each Muldis D literal is represented by a Perl Array,
whose elements include both the payload Perl literal plus explicit
meta-data for how to interpret that Perl literal for mapping to Muldis D.

This document mainly just specifies a way to represent Muldis D values as
Perl values.  Since the fundamental way to do data definition in Muldis D
is to update catalog (information schema) variables, aka the Muldis D
meta-model, which are themselves just data, then this document only needs
to tell you how to define values to put in the catalog variables.  Defining
data types or routines are done by defining catalog values describing them.

See instead L<Language::MuldisD::Core> for how to actually define the
tuples and relations that define your data types and routines and queries
and so forth.

Note that this document (along with the aforementioned) is also intended to
serve as a proposal for a generic portable AST that various Perl
applications and components can use to represent their database schemas and
queries, regardless of whether a native Muldis D implementation is in use;
or this document can be used as a point of departure for documenting some
alternative AST for that purpose.

I<This documentation is pending.>

=head1 GENERAL STRUCTURE

A PHMD value is composed mainly of a tree of Perl Array, such that each
Array is a tree node.  The elements of each node/Array include typically a
native Perl payload value, which may be a PHMD value itself, plus meta-data
for that payload, that meta-data typically including the analogy of a class
name, were PHMD nodes instead represented by a tree of PHMD-specific
objects.

It should be emphasized that no Perl undefined values are allowed anywhere
in a PHMD value; you must use only defined values instead.  This
documentation also assumes that only defined values are used, and that
supplying a Perl undef will result in an error.  If you genuinely want to
represent that a value is unknown or inapplicable, then the C<Nothing> node
type is provided as one way you can explicitly say so.  I<This policy may
be reconsidered.>

The root Perl C<Array> of a PHMD value has 4 elements, which are:

=over

=item *

The AST language/schema base name, specifically the Perl C<Str> value
C<MuldisD> for this spec.

=item *

The AST language/schema authority, encoded as a Perl C<Str> value.  The
authority string is interpreted within the context of the language/schema
name, which for the C<MuldisD> spec is the range of authority string
formats permitted for the long names of Perl 6 packages, such as a CPAN
identifier or an http url, although what's allowed may be open-ended.  For
the official/original Muldis D language spec by Darren Duncan, that string
is always C<cpan:DUNCAND> during the foreseeable future.  If someone else
wants to I<embrace and extend> Muldis D, such as to include proprietary
extensions, or incompatible changes, then they must use something other
than C<cpan:DUNCAND> for the authority, (and optionally, change the name
from C<MuldisD> as well if that seems appropriate), to prevent ambiguity.

=item *

The AST language/schema version number, encoded as a Perl C<Str> value.
The version number string is interpreted within the context of both the
language/schema name and language/schema authority, which for the
C<MuldisD> plus C<cpan:DUNCAND> spec is the normal 3-integer-parts
(C<X.Y.Z>) version format normal for the long names of Perl 6 packages and
many other versioned projects in general.  At the present time, the
official spec version number to use is shown in the VERSION and DESCRIPTION
of the C<MuldisD.pm> file, when corresponding to the spec containing that
file.

=item *

The payload is any other PHMD node.

=back

Examples of a root node:

    [ 'MuldisD', 'cpan:DUNCAND', '1.2.3', [ 'Bool', 'md_enum', 'false' ] ]

Both the payload node under the root node and every other node is a Perl
C<Array> with usually 2+ elements, where the first element is a Perl C<Str>
saying what kind of node it is, and the last element is the
typically-single payload, and any sometimes-optional intermediate elements
give extra meta-data to specify which of possibly several representation
formats the payload is, so that it is correctly interpreted.  Typically
speaking, only the payload element might be a Perl collection type, and
typically all the other elements are Perl scalars.

Note that a Hosted Abstract Muldis D implementation may eschew the above
4-element Array as the root PHMD node for all PHMD trees, and instead have
a separate virtual machine configuration step taking just the first 3
elements (base name, authority, version number), to provide a context for
subsequent use of PHMD trees that consist of just what would otherwise be
the 4th (payload) element.

Examples; at VM config time:

    [ 'MuldisD', 'cpan:DUNCAND', '1.2.3' ]

Then later, just:

    [ 'Bool', 'md_enum', 'false' ]

=head1 SCALAR VALUES

=head2 sys.Core.Bool.Bool

This node type represents a logical boolean value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Bool>.

=item *

Format; one of: C<md_enum>, C<perl_bool>, C<any_perl>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Bool.Bool> value as
follows:

=over

=item *

If the format is C<md_enum>, then the payload must be a Perl C<Str>
having one of the values C<false>, C<true>.  This format specifically is
what the Concrete Muldis D grammar uses, and is the result of parsing it.

=item *

If the format is C<perl_bool>, then:  Under Perl 6, the payload must
be a Perl C<Bool>, and so C<Bool::False> and C<Bool::True> are mapped
directly.  Under Perl 5, the payload must be just the specific result of a
Perl 5 logical expression, such as C<(1 == 0)> or C<(1 == 1)>, and nothing
else; said values are probably the empty string and number 1, respectively.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into a boolean context as per Perl's own
semantics; typically for built-in scalars, the empty string and number zero
are considered false, and everything else true.

=back

Examples:

    [ 'Bool', 'md_enum', 'true' ]

    [ 'Bool', 'perl_bool', Bool::False ] # Perl 6 only

    [ 'Bool', 'perl_bool', (1 == 0) ]

    [ 'Bool', 'perl_any', 42 ]

=head2 sys.Core.Int.Int

This node type represents an integer value.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Int>.

=item *

Format; one of: C<md_int>, C<perl_int>, C<any_perl>.

=item *

Only when format is C<md_int>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Int.Int> value as
follows:

=over

=item *

If the format is C<md_int>, then the max-col-val must be a Perl
C<Str> composed of a single C<[1-9A-Z]> character, and the payload must be
a Perl C<Str> of the format C<0> or C<< \-?<[1-9A-Z]><[0-9A-Z]>* >>.  This
format specifically is what the Concrete Muldis D grammar uses, and is the
result of parsing it.  The payload is interpreted as a base-I<N> integer
where I<N> might be between 2 and 36, and the given max-col-val says which
possible value of I<N> to use.  Assuming all column values are between zero
and I<N>-minus-one, the max-col-val contains that I<N>-minus-one.  So to
specify, eg, bases [2,8,10,16], use max-col-val of [1,7,9,F].

=item *

If the format is C<perl_int>, then:  Under Perl 6, the payload must
be a Perl C<Int>, which is mapped directly.  Under Perl 5, the payload must
be just a canonical integer value according to Perl.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into an integer context as per Perl's own
semantics, meaning base-10 where applicable.  If something doesn't look
numeric, it becomes zero; if something looks like a fractional number, it
is truncated.

=back

Examples:

    [ 'Int', 'md_int', '1', '11001001' ] # binary

    [ 'Int', 'md_int', '7', '0' ] # octal

    [ 'Int', 'md_int', '7', '644' ] # octal

    [ 'Int', 'md_int', '9', '-34' ] # decimal

    [ 'Int', 'md_int', '9', '42' ] # decimal

    [ 'Int', 'md_int', 'F', 'DEADBEEF' ] # hexadecimal

    [ 'Int', 'md_int', 'Z', '-HELLOWORLD' ] # base-36

    [ 'Int', 'perl_int', 21 ]

    [ 'Int', 'any_perl', ' 171 ' ]

    [ 'Int', 'md_int', '3', '301' ] # base-4

    [ 'Int', 'perl_int', 0 ]

    [ 'Int', 'md_int', 'B', 'A09B' ] # base-12

    [ 'Int', 'perl_int', 101 ]

=head2 sys.Core.Rat.Rat

This node type represents a rational value.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Rat>.

=item *

Format; one of: C<md_radix>, C<md_pair>, C<perl_rat>, C<perl_int_pair>,
C<any_perl>, C<any_perl_pair>.

=item *

Only when format is C<md_radix>|C<md_pair>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Rat.Rat> value as
follows:

=over

=item *

If the format is C<md_radix>, then the max-col-val must be a Perl C<Str>
composed of a single C<[1-9A-Z]> character, and the payload must be a Perl
C<Str> of the format C<0> or C<< \-?<[1-9A-Z]><[0-9A-Z]>*\.?<[0-9A-Z]>* >>.
This format specifically is what the Concrete Muldis D grammar uses
('radix' option), and is the result of parsing it.  The payload is
interpreted as a base-I<N> rational where I<N> might be between 2 and 36,
and the given max-col-val says which possible value of I<N> to use.
Assuming all column values are between zero and I<N>-minus-one, the
max-col-val contains that I<N>-minus-one.  So to specify, eg, bases
[2,8,10,16], use max-col-val of [1,7,9,F].

=item *

If the format is C<md_pair>, then the max-col-val must be as per
C<md_radix>, and the payload must be a 2-element C<Array|Seq> where the
first element is a Perl C<Str> of the format C<0> or C<<
\-?<[1-9A-Z]><[0-9A-Z]>* >> (an integer) and the second element is a Perl
C<Str> of the format C<< <[1-9A-Z]><[0-9A-Z]>* >> (a positive integer).
The payload is interpreted as per C<md_radix> but that its value comes from
the first element divided by the second.  Note that while the C<md_radix>
format is limited to representing rationals whose denominator is a power of
some I<N> between 2 and 36, the C<md_pair> format can represent those with
any I<N> that is greater than or equal to 2, such as 1/43.

=item *

If the format is C<perl_rat>, then:  Under Perl 6, the payload must be a
Perl C<Rat> (or C<Num>), which is mapped directly.  Under Perl 5, the
payload must be just a canonical rational or numeric value according to
Perl.

=item *

If the format is C<perl_int_pair>, then the payload must a 2-element
C<Array|Seq> where each element must be a canonical integer (or positive
integer, respectively) to Perl as per defining a C<perl_int>; the
rational's value is interpreted as the first element divided by the second.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into a numeric context as per Perl's own
semantics, meaning base-10 where applicable.  If something doesn't look
numeric, it becomes zero.

=item *

If the format is C<any_perl_pair>, then the payload is as per
C<perl_int_pair> but that each array element is simply coerced into an
integer context.  If Perl's coercion of the denominator produces an integer
less than 1, it becomes a 1.  I<This may be revised to fail instead.>

=back

Examples:

    [ 'Rat', 'md_radix', '1', '-1.1' ]

    [ 'Rat', 'md_radix', '9', '-1.5' ] # same val as prev

    [ 'Rat', 'md_radix', '9', '3.14159' ]

    [ 'Rat', 'md_radix', 'A', '0.0' ]

    [ 'Rat', 'md_radix', 'F', 'DEADBEEF.FACE' ]

    [ 'Rat', 'md_radix', 'Z', '0.000AZE' ]

    [ 'Rat', 'perl_rat', 21.003 ]

    [ 'Rat', 'any_perl', ' 54.67 ' ]

    [ 'Rat', 'md_pair', '6', [ '500001', '1000' ] ]

    [ 'Rat', 'md_pair', 'B', [ 'A09B', '10' ] ]

    [ 'Rat', 'perl_int_pair', [ 1, 43 ] ]

    [ 'Rat', 'any_perl_pair', [ ' 57 ', ' 71 ' ] ]

=head2 sys.Core.Blob.Blob

This node type represents a bit string.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Blob>.

=item *

Format; one of: C<md_blob>, C<perl_blob>.

=item *

Only when format is C<md_blob>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Blob.Blob> value as
follows:

=over

=item *

If the format is C<md_blob>, then the max-col-val must be a Perl
C<Str> composed of a single C<[137F]> character, and the payload must be a
Perl C<Str> of the format C<< <[0-9A-F]>* >>.  This format specifically is
what the Concrete Muldis D grammar uses, and is the result of parsing it.
Each column of the payload specifies a sequence of one of [1,2,3,4] bits,
depending on whether max-col-val is [1,3,7,F].

=item *

If the format is C<perl_blob>, then:  Under Perl 6, the payload must
be a Perl C<Blob>, which is mapped directly.  Under Perl 5, the payload
must be just a canonical Perl bit string, which is a scalar whose utf-8
flag is false.

=back

Examples:

    [ 'Blob', 'md_blob', '1', '00101110100010' ] # binary

    [ 'Blob', 'md_blob', '3', ''

    [ 'Blob', 'md_blob', 'F', 'A705E' # hexadecimal

    [ 'Blob', 'perl_blob', (pack 'H2', 'P') ]

    [ 'Blob', 'md_blob', '7', '523504376' ]

    [ 'Blob', 'perl_blob', (pack 'H2', 'Z') ]

=head2 sys.Core.Text.Text

This node type represents a character string.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Text>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Text.Text> value by
directly mapping the payload.  Note that, while Concrete Muldis D may
contain a few escape sequences, those would be replaced with what they
represent prior to making a PHMD node.  Under Perl 6, the payload must be a
Perl C<Str>, which is mapped directly.  Under Perl 5, the payload must be
just a canonical Perl character string, which is a scalar whose utf-8 flag
is true, or that doesn't contain any octets with a C<1>-valued highest bit.

Examples:

    [ 'Text', 'Ceres' ]

    [ 'Text', 'サンプル' ] # note: Perl 5 needs "use utf8;" pragma to work

    [ 'Text', '' ]

    [ 'Text', 'Perl' ]

=head1 NONSCALAR VALUES

=head2 sys.Core.Tuple.Tuple

This node type represents a tuple value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Tuple>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

The payload; a Perl C<Hash|Mapping> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Tuple.Tuple> value whose
heading was predefined, as a tuple data type, for referencing now by the
type name, and whose body is defined now by the payload.  Each key+value
pair of the payload defines a named attribute of the new tuple; the pair's
key and value are, respectively, a Perl C<Str> that specifies the attribute
name, and a PHMD node that specifies the attribute value.  The tuple body
defined by the payload must correspond to the tuple heading named by the
type name; that is, they must have the same degree, same attribute names,
and compatible types.

Examples:

    [ 'Tuple', 'sys.Core.Tuple.D0', {} ]

    [ 'Tuple', 'fed.the_db.account.user_t', {
        'login_name' => [ 'Text', 'hartmark' ],
        'login_pass' => [ 'Text', 'letmein' ],
        'is_special' => [ 'Bool', 'md_enum', 'true' ],
    } ]

    [ 'Tuple', 'fed.the_db.gene.person_t', {
        'name' => [ 'Text', 'Michelle' ],
        'age'  => [ 'Int', 'perl_int', 17 ],
    } ]

    [ 'Tuple', 'fed.the_db.account', {
        'user' => [ 'Relation', 'fed.the_db.account.user_r', ... ],
    } ]

    [ 'Tuple', 'fed.the_db.gene', {
        'person' => [ 'Relation', 'fed.the_db.gene.person_r', ... ],
    } ]

=head2 sys.Core.Relation.Relation

This node type represents a relation value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Relation>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

The payload; a Perl C<Array|Seq|Set|KeySet> of C<Hash|Mapping> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Relation> value
whose heading was predefined, as a relation data type, for referencing now
by the type name, and whose body is defined now by the payload.  Each
element of the payload defines a tuple of the new relation; each element is
as per the payload of a tuple-defining PHMD node, including the need to
correspond to the relation heading, which is common to all tuples in it.

Examples:

    [ 'Relation', 'sys.Core.Relation.D0', [] ]

    [ 'Relation', 'sys.Core.Relation.D0', [ {} ] ]

    [ 'Relation', 'fed.the_db.account.user_r', [
        {
            'login_name' => [ 'Text', 'hartmark' ],
            'login_pass' => [ 'Text', 'letmein' ],
            'is_special' => [ 'Bool', 'md_enum', 'true' ],
        },
    ] ]

    [ 'Relation', 'fed.the_db.gene.person_r', [
        {
            'name' => [ 'Text', 'Michelle' ],
            'age'  => [ 'Int', 'perl_int', 17 ],
        },
    ] ]

=head2 sys.Core.Relation.Set

This node type represents a set value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Set>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

The payload; a Perl C<Array|Seq|Set|KeySet> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Set> value whose
heading was predefined, as a set data type, for referencing now by the type
name, and whose body is defined now by the payload.  Each element of the
payload defines a unary tuple of the new set; each element is a PHMD node
that defines the C<value> attribute of the tuple.

Examples:

    [ 'Set', 'fed.the_db.account.country_name', [
        [ 'Text', 'Canada' ],
        [ 'Text', 'Spain' ],
        [ 'Text', 'Jordan' ],
        [ 'Text', 'Thailand' ],
    ] ]

    [ 'Set', 'fed.the_db.stats.some_ages', [
        [ 'Int', 'perl_int', 3 ],
        [ 'Int', 'perl_int', 16 ],
        [ 'Int', 'perl_int', 85 ],
    ] ]

=head2 sys.Core.Relation.Nothing

This node type represents a 'nothing' value; it is interpreted as a Muldis D
C<sys.Core.Relation.Nothing>.  It has 1 element, which is the Perl C<Str>
value C<Nothing>.

Examples:

    [ 'Nothing' ]

=head2 sys.Core.Relation.Just

This node type represents a 'just' value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Just>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

The payload; a PHMD node that defines a single scalar or nonscalar value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Just> value
whose heading was predefined, as a 'maybe' data type, for referencing now
by the type name, and whose body is defined now by the payload.  The
payload is a PHMD node that defines the C<value> attribute of the single
tuple of the new 'just'.

Examples:

    [ 'Just', 'fed.the_db.gene.person_death_date',
        [ 'Text', '2003.07.24' ] ]

=head2 sys.Core.Relation.Seq

This node type represents a sequence value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Seq>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

The payload; a Perl C<Array|Seq> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Seq> value whose
heading was predefined, as a sequence data type, for referencing now by the
type name, and whose body is defined now by the payload.  Each element of
the payload defines a binary tuple of the new sequence; the element value
is a PHMD node that defines the C<value> attribute of the tuple, and the
element index is used as the C<index> attribute of the tuple.

Examples:

    [ 'Seq', 'fed.the_db.gene.sorted_person_name', [
        [ 'Text', 'Alphonse' ],
        [ 'Text', 'Edward' ],
        [ 'Text', 'Winry' ],
    ] ]

    [ 'Seq', 'fed.the_db.stats.samples_by_order', [
        [ 'Int', 'perl_int', 57 ],
        [ 'Int', 'perl_int', 45 ],
        [ 'Int', 'perl_int', 63 ],
        [ 'Int', 'perl_int', 61 ],
    ] ]

=head2 sys.Core.Relation.Bag

This node type represents a bag value.  It has 4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Bag>.

=item *

Type name; any C<Array|Str> that is a valid payload for a C<Cat.NameChain>.

=item *

Format; one of: C<aoa_counted>, C<array_repeated>, C<perl_bag> (p6).

=item *

The payload; a Perl C<Bag|KeyBag> value or C<Array|Seq> or
C<Array|Seq> of C<Array|Seq>.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Bag> value whose
heading was predefined, as a bag data type, for referencing now by the type
name, and whose body is defined now by the payload.  The payload is
interpreted as follows:

=over

=item *

If the format is C<aoa_counted>, then the payload must be a Perl
C<Array|Seq>, and each element of the payload defines a binary tuple of the
new bag; the element is a 2-element C<Array|Seq>, and those 2 elements, by
index order, are a PHMD node that defines the C<value> attribute of the
tuple, and a 2-3-element C<Array|Seq> (which is the same as an 'Int' PHMD
node minus the first constant element) that defines the C<count> attribute
of the tuple; the count must be a positive integer.

=item *

If the format is C<array_repeated>, then the payload must be a Perl
C<Array|Seq>, and each element of the payload contributes to a binary tuple
of the new bag; the element value is a PHMD node that defines the C<value>
attribute of the tuple.  The bag has 1 tuple for every distinct (after
format normalization) element value in the payload, and the C<count>
attribute of that tuple says how many instances of said element were in the
payload.

=item *

If the format is C<perl_bag>, then the payload must be a Perl 6
(there is no Perl 5 analogy) C<Bag|KeyBag> value; the payload elements are
PHMD nodes corresponding to the C<value> attribute of the new bag's tuples,
and the mapping is as you should expect.

=back

Examples:

    [ 'Bag', 'fed.the_db.inventory.fruit', 'aoa_counted', [
        [
            [ 'Text', 'Apple' ],
            [ 'md_int', '9', '500' ],
        ],
        [
            [ 'Text', 'Orange' ],
            [ 'perl_int', 300 ],
        ],
        [
            [ 'Text', 'Banana' ],
            [ 'perl_int', 400 ],
        ],
    ] ]

    [ 'Bag', 'fed.the_db.inventory.whatsits', 'array_repeated', [
        [ 'Text', 'Foo' ],
        [ 'Text', 'Quux' ],
        [ 'Text', 'Foo' ],
        [ 'Text', 'Bar' ],
        [ 'Text', 'Baz' ],
        [ 'Text', 'Baz' ],
    ] ]

=head1 CATALOG SCALAR VALUES

=head2 sys.Core.Cat.Name

This node type represents a canonical short name for any kind of DBMS
entity when declaring it; it is a non-empty character string type, that is
disjoint from C<Text>.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.Name>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.Name> value by
directly mapping the payload.  Note that, while Concrete Muldis D may
contain a few escape sequences, those would be replaced with what they
represent prior to making a PHMD node.  They payload must be as per a
C<Text> PHMD node.

Examples:

    [ 'Cat.Name', 'login_pass' ]

    [ 'Cat.Name', 'First Name' ]

=head2 sys.Core.Cat.NameChain

This node type represents a canonical long name for invoking some a DBMS
entity in some contexts; it is conceptually a sequence of entity short
names.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.NameChain>.

=item *

The payload; a Perl C<Array|Seq> value or C<Str> (char-mode scalar) value.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.NameChain> value as
follows:

=over

=item *

If the payload is an C<Array|Seq>, then it must have at least 1 element,
and every element must be a valid payload for a C<Cat.Name> PHMD node (that
is, any non-empty Perl character string).  Each element of the payload, in
order, defines an element of the sequence possrep of a C<Cat.NameChain>.

=item *

If the payload is a C<Str>, then it must be formatted as a catenation
(using period (C<.>) separators) of at least 1 part, where each part is
escaped such that backslashes, single-quotes, and periods are escaped as
C<\b>, C<\q> and C<\p> respectively.

=back

Examples:

    [ 'Cat.NameChain', ['fed','the_db','gene','sorted_person_name'] ]

    [ 'Cat.NameChain', 'fed.the_db.stats.samples_by_order' ]

=head2 sys.Core.Cat.Order

This node type represents an order-determination.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.Order>.

=item *

Format; one of: C<md_enum>, C<perl_order>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.Order> value as
follows:

=over

=item *

If the format is C<md_enum>, then the payload must be a Perl C<Str>
having one of the values C<increase>, C<same>, C<decrease>.  This format
specifically is what the Concrete Muldis D grammar uses, and is the result
of parsing it.

=item *

If the format is C<perl_order>, then:  Under Perl 6, the payload must be a
Perl C<Order>, and so C<Order::Increase> and C<Order::Same> and
C<Order::Decrease> are mapped directly.  Under Perl 5, the payload must be
just the specific result of a Perl 5 order-determining expression, such as
C<< (1 <=> 2) >> or C<< (1 <=> 1) >> or C<< (2 <=> 1) >>, and nothing else;
said values are probably the numbers [C<-1>, C<0>, C<1>], respectively.

=back

Examples:

    [ 'Cat.Order', 'md_enum', 'same' ]

    [ 'Cat.Order', 'perl_order', Order::Increase ] # Perl 6 only

    [ 'Cat.Order', 'perl_order', (2 <=> 1) ]

=head2 sys.Core.Cat.E_RM

This node type represents a rounding method.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_RM>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_RM> value by
directly mapping the payload.  The payload must be a Perl C<Str>
having one of the 5 values C<half_up>, C<to_even>, C<to_floor>,
C<to_ceiling>, C<to_zero>.

Examples:

    [ 'Cat.E_RM', 'half_up' ]

=head2 sys.Core.Cat.E_TK

This node type represents a type kind.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_TK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_TK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 8 values C<special>, C<scalar>, C<tuple>, C<relation>,
C<quasi_scalar>, C<quasi_tuple>, C<quasi_relation>, C<remnant>.

Examples:

    [ 'Cat.E_TK', 'scalar' ]

=head2 sys.Core.Cat.E_TDM

This node type represents a type definition method.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_TDM>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_TDM> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 9 values C<special>, C<root>, C<restriction>, C<alias>, C<union>,
C<intersection>, C<exclusion>, C<difference>, C<negation>.

Examples:

    [ 'Cat.E_TDM', 'alias' ]

=head2 sys.Core.Cat.E_ENK

This node type represents an expression node kind.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_ENK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_ENK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 11 values C<default>, C<scalar>, C<tuple>, C<relation>,
C<quasi_scalar>, C<quasi_tuple>, C<quasi_relation>, C<param>, C<upd_param>,
C<ro_param>, C<func>.

Examples:

    [ 'Cat.E_ENK', 'default' ]

=head2 sys.Core.Cat.E_PSAK

This node type represents a procedural statement argument kind.  It has 2
elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_PSAK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_PSAK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 5 values C<default>, C<upd_param>, C<ro_param>, C<inner_var>,
C<outer_var>.

Examples:

    [ 'Cat.E_PSAK', 'ro_param' ]

=head1 SEE ALSO

Go to L<Language::MuldisD> for the majority of distribution-internal
references, and L<Language::MuldisD::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<Language::MuldisD> for details.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Language::MuldisD> apply to this file too.

=cut