=pod

=encoding utf8

=head1 NAME

Muldis::D::Dialect::HDMD_Perl5_STD -
How to format Perl 5 Hosted Data Muldis D

=head1 VERSION

This document is Muldis::D::Dialect::HDMD_Perl5_STD version 0.99.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.

=head1 DESCRIPTION

This document outlines the grammar of the I<Hosted Data Muldis D> dialect
named C<HDMD_Perl5_STD>.  The fully-qualified name of this Muldis D
dialect, in combination with the base language spec it is bundled with, is
C<[ 'Muldis_D', 'http://muldis.com', 'N.N.N', 'HDMD_Perl5_STD' ]> (when
the bundled base language version is substituted for the C<N.N.N>).

The C<HDMD_Perl5_STD> dialect is defined to be hosted in Perl 5, and is
composed of just|mainly core Perl 5 types.  This dialect is optimized for
Perl 5 specifically, and doesn't try to match the version for Perl 6; you
*will* have to reformat any Perl Hosted Data Muldis D when migrating
between Perl 5 and Perl 6, same as with your ordinary Perl code.

This dialect is designed to exactly match the structure of a possible
concrete syntax tree, comprised of native Perl 5 scalar and collection
typed values, resulting from parsing code written in the Muldis D dialect
L<PTMD_STD|Muldis::D::Dialect::PTMD_STD> using Perl 5.  This dialect
exists as a convenience to Perl 5 programmers that want to generate or
introspect Muldis D code by saving them the difficulty and overhead of
escaping and stitching plain text code; it is expected that a Muldis D
implementation written in Perl 5 will natively accept input in both the
C<PTMD_STD> and C<HDMD_Perl5_STD> dialects.  Furthermore, the
C<HDMD_Perl5_STD> dialect provides additional Muldis D syntax options to
Perl 5 programmers besides what C<PTMD_STD> would canonically parse into,
such as the direct use of some Perl 5-only features.

B<Note that most of the details that the 2 dialects have in common are
described just in the C<PTMD_STD> file, for both dialects; this current
file will mainly focus on the differences; you should read the
L<Muldis::D::Dialect::PTMD_STD> file before the current one, so to provide
a context for better understanding it.>

=head1 GENERAL STRUCTURE

A C<HDMD_Perl5_STD> Muldis D code file is actually a Perl 5 code file that
defines particular multi-dimensional Perl data structures which resemble
possible concrete syntax trees (CSTs) from parsing C<PTMD_STD> Muldis D
code.  Each component of a CST is called a I<node> or node element, and
roughly corresponds to a capture by the C<PTMD_STD> parser.  A node is
typically represened as a Perl array ref, but could alternately be a Perl
scalar or something else, and so C<HDMD_Perl5_STD> Muldis D code is
typically a tree of Perl structures, called I<node trees>, with Perl array
refs as the central nodes and Perl scalars as the leaf nodes.  Often
C<HDMD_Perl5_STD> code is embedded or constructed in one or more files of
a larger Perl 5 program that does more than define this code, such as
various non-database-related tasks.  A node tree is just composed using
basic Perl data types, and there are no Muldis D node-specific Perl classes
or objects required for doing this.

Note that Perl undefined values are not allowed anywhere in a node in the
general case; 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.  The few exceptions to this rule are
explicitly stated.

The grammar in this file is informal and consists just of written
descriptions of how each kind of I<node> must be composed and how to
interpret such Perl data structures as Muldis D code.  Every named grammar
node is a Perl array ref unless otherwise stated, and every grammar element
is an array element; the first node element is the array element at index
zero, and so on.

The root grammar node for the entire dialect is C<Muldis_D>.

=head1 START

A C<Muldis_D> node has 2 ordered elements where the first element is a
C<language_name> node and the second element is either a C<value> node or a
C<depot> node.

See the pod sections in this file named L</LANGUAGE NAME>, L</VALUE
LITERALS AND SELECTORS>, and L</DEPOT SPECIFICATION>, for more details
about the aforementioned tokens/nodes.

When Muldis D is being compiled and invoked piecemeal, such as because the
Muldis D implementing virtual machine (VM) is attached to an interactive
user terminal, or the VM is embedded in a host language where code in the
host language invokes Muldis D code at various times, many C<value> may be
fed to the VM directly for inter-language exchange, and not every one
would then have its own C<language_name>.  Usually a C<language_name> would
be supplied to the Muldis D VM just once as a VM configuration step, which
provides a context for further interaction with the VM that just involves
Muldis D code that isn't itself qualified with a C<language_name>.

=head1 LANGUAGE NAME

As per the VERSIONING pod section of L<Muldis::D>, code written in Muldis D
must start by declaring the fully-qualified Muldis D language name it is
written in.  The C<HDMD_Perl5_STD> dialect formats this name as a
C<language_name> node having 5 ordered elements:

=over

=item C<ln_base_name>

This is the Muldis D language base name; it is simply the Perl character
string C<Muldis_D>.

=item C<ln_base_authority>

This is the base authority; it is a character string formatted as per a
specific-context C<Name> value literal; it is typically the Perl character
string C<http://muldis.com>.

=item C<ln_base_version_number>

This is the base version number; it is a character string formatted as per
C<ln_base_authority>; it is typically a character string like C<1.2.3>.

=item C<ln_dialect>

This is the dialect name; it is simply the Perl character string
C<HDMD_Perl5_STD>.

=item C<ln_extensions>

This is a set of chosen pragma/parser-config options, which is formatted
similarly to a C<Tuple> SCVL.  The only currently defined pragma,
C<catalog_abstraction_level> (see the L</CATALOG ABSTRACTION LEVELS> pod
section), is mandatory; others may be added later which would likely be
optional.

The value associated with the C<ln_extensions> attribute named
C<catalog_abstraction_level> must be one of these 4 Perl character strings:
C<the_floor>, C<code_as_data>, C<plain_rtn_inv>, C<rtn_inv_alt_syn>.

=back

Examples:

    [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
        catalog_abstraction_level => 'rtn_inv_alt_syn'
    } ]

=head1 CATALOG ABSTRACTION LEVELS

The C<catalog_abstraction_level> pragma determines with a broad granularity
how large the effective Muldis D grammar is that a programmer may employ
with their Muldis D code.

The catalog abstraction level of some Muldis D code is a measure of how
much or how little that code would resemble the system catalog data that
the code would parse into.  The lower the abstraction level, the smaller
and simpler the used Muldis D grammar is and the more like data structure
literals it is; the higher the abstraction level, the larger and more
complicated the Muldis D grammar is and the more like
general-purpose-language typical code it is.

There are currently 4 specified catalog abstraction levels, which when
arranged from lowest to highest amount of abstraction, are: C<the_floor>,
C<code_as_data>, C<plain_rtn_inv>, C<rtn_inv_alt_syn>.  Every abstraction
level has a proper superset of the grammar of every other abstraction level
that is lower than itself, so for example any code that is valid
C<code_as_data> is also valid C<plain_rtn_inv>, and so on.

=head2 the_floor

This abstraction level exists more as an academic exercise and is not
intended to actually be used.

Examples:

    [
        [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
            catalog_abstraction_level => 'the_floor'
        } ],
        [ 'Relation', [
            {
                food => [ 'Scalar', 'Text', [ nfd_codes => {
                    '' => ['Scalar',
                        'String.<67><97><114><114><111><116><115>',{}]
                } ] ],
                qty => [ 'Scalar', 'Int', {
                    '' => ['Scalar','String.<100>',{}]
                } ]
            },
            {
                food => [ 'Scalar', 'Text', [ nfd_codes => {
                    '' => ['Scalar','String.<75><105><119><105><115>',{}]
                } ] ],
                qty => [ 'Scalar', 'Int', {
                    '' => ['Scalar','String.<30>',{}]
                } ]
            }
        ] ]
    ]

=head2 code_as_data

This abstraction level is the best one for when you want to write code in
exactly the same form as it would take in the system catalog.

Code written to the C<code_as_data> level can employ all of the language
grammar constructs described in these main pod sections: L</VALUE LITERALS
AND SELECTORS>, L</OPAQUE VALUE LITERALS>, L</COLLECTION VALUE SELECTORS>.

Examples:

    [
        [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
            catalog_abstraction_level => 'code_as_data'
        } ],
        [ 'Relation', [
            { food => 'Carrots', qty => 100 },
            { food => 'Kiwis', qty => 30 }
        ] ]
    ]

    [
       [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
          catalog_abstraction_level => 'code_as_data'
       } ],
       [ 'depot', { 'depot-catalog' => [ 'Database', 'Depot', {
          functions => [ 'Relation', [
             {
                name => ['Name','cube'],
                is_public => ['Bool','true'],
                material => [ 'Tuple', 'Function', {
                   result_type => ['NameChain','Int'],
                   params => [ 'Relation', 'NameTypeMap', [
                      {name=>['Name','topic'], type=>['NameChain','Int']}
                   ] ],
                   expr => [ 'Database', 'ExprNodeSet', {
                      sca_val_exprs => [ 'Relation', [
                         { name => ['Name','INT_3'], value => 3 }
                      ] ],
                      func_invo_exprs => [ 'Relation', [
                         {
                            name => ['Name',''],
                            function => ['NameChain','Integer.power'],
                            args => [ 'Relation', 'NameExprMap', [
                               { name => ['Name','radix'],
                                  expr => ['Name','topic'] },
                               { name => ['Name','exponent'],
                                  expr => ['Name','INT_3'] }
                            ] ]
                         }
                      ] ]
                   } ]
                } ]
             }
          ] ]
       } ] } ]
    ]

=head2 plain_rtn_inv

This abstraction level is the lowest one that can be recommended for
general use.

Code written to the C<plain_rtn_inv> level can employ all of the language
grammar constructs that C<code_as_data> can, plus all of those
described in these main pod sections: L</GENERIC VALUE EXPRESSIONS>.

Examples:

    [
        [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
            catalog_abstraction_level => 'plain_rtn_inv'
        } ],
        [ 'depot', { 'depot-catalog' => [
            [ 'function', 'public', 'cube', [ 'Int', { topic => 'Int' }, [
                [ 'func-invo', 'Integer.power',
                    { radix => ['$','topic'], exponent => 3 } ]
            ] ] ]
        ] } ]
    ]

=head2 rtn_inv_alt_syn

This abstraction level is the highest one and is the most recommended one
for general use.

Code written to the C<rtn_inv_alt_syn> level can employ all of the language
grammar constructs that C<plain_rtn_inv> can, plus all of those described
in these main pod sections: L</FUNCTION INVOCATION ALTERNATE SYNTAX
EXPRESSIONS>.

Examples:

    [
        [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl5_STD', {
            catalog_abstraction_level => 'rtn_inv_alt_syn'
        } ],
        [ 'depot', { 'depot-catalog' => [
            [ 'function', 'public', 'cube', [ 'Int', { topic => 'Int' }, [
                [ 'op', 'I^', [ ['$','topic'], 3 ] ]
            ] ] ]
        ] } ]
    ]

=head1 VALUE LITERALS AND SELECTORS

A C<value> node is a Muldis D value literal, which is a common special case
of a Muldis D value selector.

There are 27 main varieties of C<value> node, each of which is a named node
kind of its own:  C<Bool>, C<Order>, C<RatRoundMeth>, C<Int>, C<Rat>,
C<Blob>, C<Text>, C<Name>, C<NameChain>, C<DeclNameChain>, C<Comment>,
C<Instant>, C<Duration>, C<UTCInstant>, C<FloatInstant>, C<UTCDuration>,
C<RatRoundRule>, C<String>, C<Scalar>, C<Tuple>, C<Database>,
C<Relation>, C<Set>, C<Maybe>, C<Array>, C<Bag>, C<Interval>.

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

=head2 Value Literal Common Elements

Every C<value> node is either a GCVL (generic context value literal) or a
SCVL (specific context value literal).

Every GCVL has 1-3 ordered elements:

=over

=item C<value_kind>

This is a character string of the format C<< <[A..Z]> <[ a..z A..Z ]>+ >>;
it identifies the data type of the value literal in broad terms and is the
only external meta-data of C<value_payload> generally necessary to
interpret the latter; what grammars are valid for C<value_payload> depend
just on C<value_kind>.

Between the various kinds of C<value> node, these 51 values are allowed for
C<value_kind>:  C<Bool>, C<Order>, C<RatRoundMeth>, C<[|NN|P]Int>,
C<[|NN|P]Rat>, C<[|Octet]Blob>, C<Text>, C<Name>, C<NameChain>,
C<DeclNameChain>, C<Comment>, C<Instant>, C<Duration>,
C<UTC[Instant|DateTime|Date|Time]>, C<Float[Instant|DateTime|Date|Time]>,
C<UTCDuration>, C<RatRoundRule>, C<[|B|O|UCP]String>, C<[|DH]Scalar>,
C<[|DH]Tuple>, C<Database>, C<[|DH]Relation>, C<[|DH]Set>,
C<[|DH][Maybe|Single]>, C<[|DH]Array>, C<[|DH]Bag>, C<[|DH]Interval>.

For just some data types, the C<value_kind> may be omitted; see below.

=item C<type_name>

Only when the C<value> node has 3 elements:  This is a Muldis D data type
name, for example C<sys.std.Core.Type.Int>; it identifies a specific
subtype of the generic type denoted by C<value_kind>, and serves as an
assertion that the Muldis D value denoted by C<value_payload> is a member
of the named subtype.  Its format is a C<NameChain_payload> node.  Iff
C<value_kind> is C<[|DH]Scalar> then C<type_name> is mandatory; otherwise,
C<type_name> is optional for all C<value>, except that C<type_name> must be
omitted when C<value_kind> is one of the 2 [C<Bool>, C<Order>]; this isn't
because those 2 types can't be subtyped, but because in practice doing so
isn't useful.

=item C<value_payload>

This is mandatory for all C<value>.  Format varies with C<value_kind>.

=back

For some data types, a GCVL may alternately be just its payload for the
sake of brevity.  If any Perl value of one of the following types is
encountered where a GCVL node is expected, then it is interpreted as a full
C<value> node as follows:

    Muldis D <- Perl 5
    --------------------
    Int  <- BigInt object or Perl scalar that looks like an integer
    Rat  <- BigRat|BigNum obj or Perl scal that looks like num but not int
    Text <- Perl scalar that doesn't look like a number

Or specifically, Int or Rat is assumed if the Perl value agrees with a
canonical payload format according to the Int|Rat node definitions, or the
value is otherwise interpreted as Text by default.  If your data is such
that the assumption might be wrong, then just use a full node to force the
desired behaviour.

For GCVL and SCVL examples, see the subsequent documentation sections.

=head1 OPAQUE VALUE LITERALS

=head2 Boolean Literals

A C<Bool> node represents a logical boolean value.  It is interpreted as a
Muldis D C<sys.std.Core.Type.Bool> value as follows:

=over

=item *

The canonical payload is the specific result of a Perl logical expression,
such as C<(1 == 0)> for C<Bool:false> or C<(1 == 1)> for C<Bool:true>; said
values are probably the empty string and number 1, respectively.

=item *

A few alternative payload formats are supported:  The Perl value literals
[C<'false'>, C<'0'>, C<0>, C<''>, C<'⊥'>] all map to C<Bool:false>,
and the Perl value literals [C<'true'>, C<'1'>, C<1>, C<'⊤'>] all
map to C<Bool:true>.

=back

Examples:

    ['Bool','true']

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

    ['Bool','⊤']

=head2 Order-Determination Literals

A C<Order> node represents an order-determination.  It is interpreted as a
Muldis D C<sys.std.Core.Type.Cat.Order> value as follows:

=over

=item *

The canonical payload is the specific result of a Perl order-determining
expression, such as C<< (1 <=> 2) >> for C<Order:increase> or C<< (1 <=> 1)
>> for C<Order:same> or C<< (2 <=> 1) >> for C<Order:decrease>; said values
are probably the numbers [-1,0,1], respectively.

=item *

A few alternative payload formats are supported:  The Perl value literals
[C<'increase'>, C<'-1'>, C<-1>] all map to C<Order:increase>, the Perl
value literals [C<'same'>, C<'0'>, C<0>] all map to C<Order:same>, and the
Perl value literals [C<'decrease'>, C<'1'>, C<1>] all map to
C<Order:decrease>.

=back

Examples:

    ['Order','same']

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

=head2 Rational Rounding Method Literals

A C<RatRoundMeth> node represents a rational rounding method.  It is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.RatRoundMeth> value by
directly mapping the payload.  The payload must be a Perl character string
having one of the 7 values C<half_down>, C<half_up>, C<half_even>,
C<to_floor>, C<to_ceiling>, C<to_zero>, C<to_inf>.

Examples:

    ['RatRoundMeth','half_up']

    ['RatRoundMeth','to_zero']

=head2 General Purpose Integer Numeric Literals

An C<Int> node represents an integer numeric value.  It is interpreted as a
Muldis D C<sys.std.Core.Type.Int> value as follows:

=over

=item *

If the payload is a Perl scalar, then it must be just a canonical integer
value according to Perl, and it is mapped directly; since native Perl
integers are limited precision, larger integers can be represented by a
Perl character string of the format C<0> or C<< \-?<[1..9]>['_'?<[0..9]>+]*
>> that is interpreted as base 10.

=item *

An alternative payload format is a C<bigint> object, which is conceptually
the closest thing Perl 5 has in core to a "big integer".

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string composed of a single C<[ 1..9 A..Z ]>
character, and the main payload must be a Perl character string of the
format C<0> or C<< \-?<[ 1..9 A..Z ]>['_'?<[ 0..9 A..Z ]>+]* >>.  The
main 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].

=back

Examples:

    [ 'Int', { 1 => '11001001' } ] # binary #

    [ 'Int', { 7 => '0' } ] # octal #

    [ 'Int', { 7 => '644' } ] # octal #

    -34 # decimal #

    42 # decimal #

    [ 'Int', { F => 'DEADBEEF' } ] # hexadecimal #

    [ 'Int', { Z => '-HELLOWORLD' } ] # base-36 #

    [ 'Int', { 3 => '301' } ] # base-4 #

    [ 'Int', { B => 'A09B' } ] # base-12 #

=head2 General Purpose Rational Numeric Literals

A C<Rat> node represents a rational numeric value.  It is interpreted as a
Muldis D C<sys.std.Core.Type.Rat> value as follows:

=over

=item *

If the payload is a Perl scalar, then it must be just a canonical numeric
value according to Perl, and it is mapped directly; since native Perl
numerics are limited precision or are inexact (IEEE float), larger numerics
can be represented by a Perl character string of the format C<<
0\.['_'?<[0..9]>+]+ >> or C<< \-?<[1..9]>['_'?<[0..9]>+]*\.['_'?<[0..9]>+]+
>> that is interpreted as base 10.

=item *

An alternative payload format is a C<bigrat|bignum|bigint> object, which is
conceptually the closest thing Perl 5 has in core to a "big rational".

=item *

If the payload is a Perl array ref, then the payload must have exactly 2 or
3 elements, each of which constitutes a valid payload of an C<Int>
node.  If the payload has 2 elements, then the rational's value is
interpreted as the first element (a numerator) divided by the second (a
denominator).  If the payload has 3 elements, then the rational's value is
interpreted as the first element (a mantissa) multiplied by the result of
the second element (a radix) taken to the power of the third (an exponent).

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string composed of a single C<[ 1..9 A..Z ]>
character.  If the main payload is a Perl scalar, then the main payload
must be a Perl character string of the format C<< 0\.['_'?<[ 0..9 A..Z
]>+]+ >> or C<< \-?<[ 1..9 A..Z ]>['_'?<[ 0..9 A..Z ]>+]*\.['_'?<[ 0..9
A..Z ]>+]+ >>.  The main 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].  If the main
payload is a Perl array ref, then the main payload must have exactly 2 or 3
elements, and every pairwise combination of the max-col-val with the
elements of the main payload must, when appropriately wrapped in a Perl
hash ref, must constitute a valid hash ref payload for an C<Int>  node;
the meaning of the 2 or 3 main payload elements is the same as the 2 or 3
payload elements mentioned in the previous bullet point.

=back

Examples:

    [ 'Rat', { 1 => '-1.1' } ]

    -1.5 # same val as prev #

    3.14159

    [ 'Rat', { A => '0.0' } ]

    [ 'Rat', { F => 'DEADBEEF.FACE' } ]

    [ 'Rat', { Z => '0.000AZE' } ]

    [ 'Rat', { 6 => ['500001','1000'] } ]

    [ 'Rat', { B => ['A09B','A'] } ]

    [ 'Rat', { 1 => ['1011101101','10','-11011'] } ]

    [ 'Rat', [45207196,10,37] ]

    [ 'Rat', [1,43] ]

    [ 'Rat', [314159,10,-5] ]

=head2 General Purpose Binary String Literals

A C<Blob> node represents a general purpose bit string.  It is interpreted
as a Muldis D C<sys.std.Core.Type.Blob> value as follows:

=over

=item *

If the payload is a Perl scalar, then it must be a canonical Perl bit
string, which is a scalar whose utf-8 flag is false, and it is mapped
directly.

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string composed of a single C<[137F]> character,
and the main payload must be a Perl character string of the format C<< <[
0..9 A..F ]>* >>.  Each column of the main payload specifies a sequence of
one of [1,2,3,4] bits, depending on whether max-col-val is [1,3,7,F].

=back

Examples:

    [ 'Blob', { 1 => '00101110100010' } ] # binary #

    [ 'Blob', { 3 => '' } ]

    [ 'Blob', { F => 'A705E' } ] # hexadecimal #

    [ 'Blob', { 7 => '523504376' } ]

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

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

=head2 General Purpose Character String Literals

A C<Text> node represents a general purpose character string.  It is
interpreted as a Muldis D C<sys.std.Core.Type.Text> value by directly
mapping the payload.  The payload must be just a canonical Perl character
string, which is any Perl scalar value (a Muldis D implementation in Perl
can ignore the utf-8 flag as Perl itself knows how to treat its strings
consistently).

Examples:

    [ 'Text', 'Ceres' ]

    'サンプル' # note: needs "use utf8;" pragma to work #

    ''

    'Perl'

    "\N{LATIN SMALL LETTER OU}\x{263A}".chr(65)
        # note: \N{} needs "use charnames ':full';" pragma to work #

=head2 DBMS Entity Name Literals

A C<Name> node represents a canonical short name for any kind of DBMS
entity when declaring it; it is a character string type, that is disjoint
from C<Text>.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Cat.Name> value by directly mapping the payload.  The
payload must be as per the payload of a C<Text> node.

A C<NameChain> node represents a canonical long name for invoking a DBMS
entity in some contexts; it is conceptually a sequence of entity short
names.  Its payload is a Perl array ref or character string.  This node is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.NameChain> value as
follows:

=over

=item *

If the payload is an array ref, then it must have at least 1 element,
and every element must be a valid payload for a C<Name> node (that
is, any Perl character string).  Each element of the payload, in order,
defines an element of the C<array> possrep's attribute of a C<NameChain>.

=item *

If the payload is a char str, then it must be formatted as a catenation
(using period (C<.>) separators) of at least 1 part, where each part can
not have any literal period (C<.>) characters (if you want literal periods
then you can only use the array ref payload format to express it).  The
char str format of payload is interpreted by splitting it on the separators
into the array ref format, then processed as per the latter.  As a special
case, if the C<NameChain> payload begins with a period separator, then the
first element of the post-split result is treated not as the empty string
C<Name>, but rather as the C<Name> value C<topic>; that is, C<.foo> means
the same thing as C<topic.foo> (if you want a literal empty string first
element, then you can only use the array ref payload format to express it).

=back

A C<DeclNameChain> node represents a canonical long name for declaring a
DBMS entity in N-depth contexts; the format and interpretation of a
C<DeclNameChain_payload> (but as a C<sys.std.Core.Type.Cat.DeclNameChain>
value) is the same as a C<NameChain_payload> but that the chain may have as
few as zero parts rather than as few as 1 or 2; however, a zero part chain
can only be expressed with the array ref payload format; an empty string
char str format will be interpreted as having a single element that is the
empty string.

Examples:

    [ 'Name', 'login_pass' ]

    [ 'Name', 'First Name' ]

    [ 'NameChain', ['fed','data','the_db','gene','sorted_person_names'] ]

    [ 'NameChain', 'fed.data.the_db.stats.samples by order' ]

    [ 'NameChain', '.attr' ]  # same as [ 'NameChain', 'lex.topic.attr' ] #

    [ 'DeclNameChain', ['gene','sorted_person_name'] ]

    [ 'DeclNameChain', 'stats.samples by order' ]

    [ 'DeclNameChain', [] ]

=head2 Code Comment Literals

A C<Comment> node represents the text of a Muldis D code comment; it is a
character string type, that is disjoint from both C<Text> and C<Name>.  It
is interpreted as a Muldis D C<sys.std.Core.Type.Cat.Comment> value by
directly mapping the payload.  The payload must be as per the payload of a
C<Text> node.

Examples:

    [ 'Comment', 'This does something.' ]

    [ 'Comment', 'So does this.' ]

=head2 TAI Temporal Literals

An C<Instant> node represents a single point in time which is specified in
terms of atomic seconds; it is a rational numeric type, that is disjoint
from both C<Rat> and C<Duration>.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Instant> value by directly mapping the payload, which
must be as per the payload of a C<Rat> node.

A C<Duration> node represents a single amount of time (the difference
between two instants) which is specified in terms of atomic seconds; it
is a rational numeric type, that is disjoint from both C<Rat> and
C<Instant>.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Duration> value by directly mapping the payload, which
must be as per the payload of a C<Rat> node.

Examples:

    [ 'Instant', 1235556432.0 ]

    [ 'Instant', 854309115.0 ]

    [ 'Duration', 3600.0 ]

    [ 'Duration', -50.0 ]

    [ 'Duration', 3.14159 ]

    [ 'Duration', { 1 => ['1011101101','10','-11011'] } ]

    [ 'Duration', [1,43] ]

=head2 UTC and Float Temporal Literals

A C<UTCInstant> node represents an "instant"/"datetime" value that is
affiliated with the UTC time-zone.  This node is interpreted as a Muldis D
C<sys.std.Temporal.Type.UTCInstant> value whose C<instant> possrep
attribute values are defined as follows:

=over

=item *

If the payload is a Perl array ref, then it must have 6 elements, where
each element may be either undefined or defined; or if fewer than 6
elements are provided, the array ref will be implicitly extended to 6,
filling with undefs.  The 6 payload elements correspond in order, from the
lowest to the highest indexed, to the 6 attributes: C<year>, C<month>,
C<day>, C<hour>, C<minute>, C<second>.  For each payload element that Perl
considers undefined or defined, the corresponding attribute has the
C<nothing> or a C<Single> value, respectively.  For each of the first 5
elements, when it is defined, it must qualify as a valid payload for an
C<Int> node; for the 6th element, when it is defined, it must qualify
as a valid payload for a C<Rat> node.

A defined C<year> may be any integer, each of [C<month>, C<day>] must be a
positive integer, each of [C<hour>, C<minute>] must be a non-negative
integer, and C<second> must be a non-negative rational number.  If all 6
attributes are defined, then the new C<UTCInstant> value is also a
C<UTCDateTime>; if just the first 3 or last 3 are defined, then the value
is not a C<UTCDateTime> but rather a C<UTCDate> or C<UTCTime>,
respectively; if any other combination of attributes are defined, then the
value is just a C<UTCInstant> and not of any of the other 3 subtypes.

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string and the main payload must be a Perl array
ref as per the payload of the previous bullet point but that none of the 6
elements is a Perl hash ref.  Each of the 6 main payload elements, when
defined, is further interpreted according to the max-col-val, in the same
manner as how an C<Int> or C<Rat> node's hash ref payload's element's value
is interpreted.  The interpretation of this payload is the same as for the
Perl array ref payload.

=back

A C<FloatInstant> node represents an "instant"/"datetime" value that is
"floating" / not affiliated with any time-zone.  This node is interpreted
as a Muldis D C<sys.std.Temporal.Type.FloatInstant> value in an identical
fashion to how a C<UTCInstant> node is interpreted, whose format it
completely shares.  Likewise regarding C<Float[DateTime|Date|Time]>.

A C<UTCDuration> node represents a duration value, an amount of time, which
is not fixed to any instant in time.  This node is interpreted as a Muldis
D C<sys.std.Temporal.Type.UTCDuration> value whose C<duration> possrep
attribute values are defined as follows:

=over

=item *

If the payload is a Perl array ref, then it must have 6 elements, where
each element may be either undefined or defined; or if fewer than 6
elements are provided, the array ref will be implicitly extended to 6,
filling with undefs.  The 6 payload elements correspond in order, from the
lowest to the highest indexed, to the 6 attributes: C<years>, C<months>,
C<days>, C<hours>, C<minutes>, C<seconds>.  For each payload element that
Perl considers undefined or defined, the corresponding attribute has the
C<nothing> or a C<Single> value, respectively.  For each of the first 5
elements, when it is defined, it must qualify as a valid payload for an
C<Int>  node; for the 6th element, when it is defined, it must qualify
as a valid payload for a C<Rat>  node.

A defined [C<years>, C<months>, C<days>, C<hours>, C<minutes>] may be any
integer, and C<seconds> may be any rational number.  I<Currently,
C<UTCDuration> has no system-defined subtypes, but that may change later.>

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string and the main payload must be a Perl array
ref as per the payload of the previous bullet point but that none of the 6
elements is a Perl hash ref.  Each of the 6 main payload elements, when
defined, is further interpreted according to the max-col-val, in the same
manner as how an C<Int> or C<Rat> node's hash ref payload's element's value
is interpreted.  The interpretation of this payload is the same as for the
Perl array ref payload.

=back

Examples:

    [ 'UTCInstant', [1964,10,16,16,12,47.5] ] # a UTCDateTime #

    [ 'UTCInstant', [2002,12,6] ] # a UTCDate #

    [ 'UTCInstant', [undef,undef,undef,14,2,29.0] ] # a UTCTime #

    [ 'FloatInstant', [2003,4,5,2] ] # min,sec unknown or N/A #

    [ 'FloatInstant', [1407] ] # just know its sometime in 1407 #

    [ 'UTCDuration', [3,5,1,6,15,45.000012] ]

=head2 Rational Rounding Rule Literals

A C<RatRoundRule> node represents a rational rounding rule.  It is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.RatRoundRule> value whose
attributes are defined by the C<RatRoundRule_payload>.  A
C<RatRoundRule_payload> must be a Perl array ref with 3 elements, which
correspond in order to the 3 attributes: C<radix> (a C<PInt2_N>),
C<min_exp> (an C<Int>), and C<round_meth> (a C<RatRoundMeth>).  Each of
C<radix> and C<min_exp> must qualify as a valid C<Int_payload>, and
C<round_meth> must qualify as a valid C<RatRoundMeth_payload>.

Examples:

    [ 'RatRoundRule', [10,-2,'half_even'] ]

    [ 'RatRoundRule', [2,-7,'to_zero'] ]

=head2 Low Level Integer String Literals

A C<String> node represents an integer string value.  This node is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.String> value as follows:

=over

=item *

If the payload is a Perl array ref, then every one of its elements must
constitute a valid payload for an C<Int> node.

=item *

If the payload is a Perl hash ref, then it must have 1 element, whose key
and value are designated, in order, I<max-col-val> and I<main payload>; the
max-col-val must be a Perl string and the main payload must be a Perl array
ref; every pairwise combination of the max-col-val with the elements of the
main payload must, when appropriately wrapped in a Perl hash ref, must
constitute a valid hash ref payload for an C<Int> node.

=back

Examples:

    [ 'String', [80,101,114,109] ] # Unicode abstract codepoints = 'Perl' #

    [ 'String', { F => ['50','65','72','6C'] } ] # same thing #

=head1 COLLECTION VALUE SELECTORS

Note that, with each of the main value selector nodes documented in this
main POD section, any occurrences
of child C<expr> nodes should be read as being C<value> nodes instead in
contexts where instances of the main nodes are being composed beneath
C<value> nodes.  That is, any C<expr> node options beyond what C<value>
options exist are only valid within a C<depot> node.

=head2 Scalar Selectors

A C<Scalar> node represents a literal or selector invocation for a
scalar subtype value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Scalar> subtype value whose declared type is specified
by the  node's (mandatory for C<Scalar>) C<type_name> element and whose
attributes are defined by the payload.  If the payload is a Perl array ref,
then it must have exactly 2 elements, that are designated I<possrep name>
and I<possrep attrs>; if the payload is not a Perl array ref, then it is
interpreted as if it was just the I<possrep attrs>, and the I<possrep name>
was the empty string.  The possrep name and possrep attrs must be as per
the payload of a C<Name> and C<Tuple> node, respectively.  The I<possrep
attrs> is interpreted specifically as attributes of the declared type's
possrep which is specified by the I<possrep name>.  Each key+value pair of
the I<possrep attrs> defines a named possrep attribute of the new scalar;
the pair's key and value are, respectively, a Perl character string that
specifies the possrep attribute name, and a C<expr> node that specifies the
possrep attribute value.

Examples:

    [ 'Scalar', 'sys.std.Core.Type.Cat.Name', { '' => 'the_thing' } ]

    [ 'Scalar', 'sys.std.Core.Type.Rat', [ float => {
        mantissa => 45207196,
        radix    => 10,
        exponent => 37,
    } ] ]

    [ 'Scalar', 'sys.std.Temporal.Type.UTCDateTime', [ datetime => {
        year   => 2003,
        month  => 10,
        day    => 26,
        hour   => 1,
        minute => 30,
        second => 0.0,
    } ] ]

    [ 'Scalar', 'fed.lib.the_db.WeekDay', [ name => {
        '' => 'monday',
    } ] ]

    [ 'Scalar', 'fed.lib.the_db.WeekDay', [ number => {
        '' => 5,
    } ] ]

    [ 'Scalar', 'Int', { '' => ['Scalar','String.<42>',{}] } ]

    [ 'Scalar', 'Text', [ nfd_codes => {
        '' => ['Scalar','String.<80><101><114><109>',{}]
    } ] ]

=head2 Tuple Selectors

A C<Tuple> node represents a literal or selector invocation for a
tuple value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Tuple> value whose attributes are defined by the
payload.  The payload must be just a Perl hash ref.  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 character string that specifies the
attribute name, and a C<expr> node that specifies the attribute value.

Examples:

    [ 'Tuple', {} ]

    [ 'Tuple', 'type.tuple_from.var.fed.data.the_db.account.users', {
        login_name => 'hartmark',
        login_pass => 'letmein',
        is_special => ['Bool','true'],
    } ]

    [ 'Tuple', {
        name => 'Michelle',
        age  => 17,
    } ]

=head2 Database Selectors

A C<Database> node represents a literal or selector invocation for a
'database' value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Database> value whose attributes are defined by the
payload.  The payload must be a just a Perl hash ref.  Each key+value pair
of the payload defines a named attribute of the new 'database'; the pair's
key and value are, respectively, a Perl character string that specifies the
attribute name, and a C<expr> node that specifies the attribute value,
which must be represent a relation value.

=head2 Relation Selectors

A C<Relation> node represents a literal or selector invocation for a
relation value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Relation> value whose attributes and tuples are
defined by the payload, which is interpreted as follows:

=over

=item *

Iff the payload is a Perl array ref with zero elements, then it defines the
only relation value having zero attributes and zero tuples.

=item *

Iff the payload is a Perl array ref with at least one element, and every
element is a Perl character string (as per a valid payload for a C<Name>
node), then it defines the attribute names of a relation having zero
tuples.

=item *

Iff the payload is a Perl array ref with at least one element, and every
element is a Perl hash ref (as per a valid payload for a C<Tuple>
node), then each element of the payload defines a tuple of the new
relation; every tuple-defining element of the payload must be of the same
degree and have the same attribute names as its sibling elements; these are
the degree and attribute names of the relation as a whole, which is its
heading for the current purposes.

=item *

Iff the payload is a Perl array ref with exactly 2 elements, each of which
is a Perl array ref, then:  The new relation value's attribute names are
defined by the payload's first element, which is a Perl array ref of
character string (each as per a C<Name> node payload), and the relation
body's tuples' attribute values are defined by the payload's second
element, which is a Perl array ref of Perl array ref of tuple attribute
value defining  nodes.  This format is meant to be the most compact of
the generic relation payload formats, as the attribute names only appear
once for the relation rather than repeating for each tuple.  As a
trade-off, the attribute values per tuple from the payload second element
must appear in the same order as their corresponding attribute names appear
in the payload first element, as the names and values in the relation
literal are matched up by ordinal position here.

=back

Examples:

    [ 'Relation', [] ]  # zero attrs + zero tuples #

    [ 'Relation', [ 'x', 'y', 'z' ] ]  # 3 attrs + zero tuples #

    [ 'Relation', [ {} ] ]  # zero attrs + 1 tuple #

    [ 'Relation', [
        {
            login_name => 'hartmark',
            login_pass => 'letmein',
            is_special => ['Bool','true'],
        },
    ] ]  # 3 attrs + 1 tuple #

    [ 'Relation', 'fed.lib.the_db.gene.Person', [ [ 'name', 'age' ] => [
        [ 'Michelle', 17 ],
    ] ] ]  # 2 attrs + 1 tuple #

=head2 Set Selectors

A C<Set> node represents a literal or selector invocation for a set
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.Set> value
whose elements are defined by the payload.  The payload must be just a Perl
array ref.  Each element of the payload defines a unary tuple of the
new set; each element is a C<expr> node that defines the C<value>
attribute of the tuple.

Examples:

    [ 'Set', 'fed.lib.the_db.account.Country_Names', [
        'Canada',
        'Spain',
        'Jordan',
        'Thailand',
    ] ]

    [ 'Set', [
        3,
        16,
        85,
    ] ]

=head2 Maybe Selectors

A C<Maybe> node represents a literal or selector invocation for a
maybe value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Maybe> value.  If the node payload is missing or
undefined, then the node is interpreted as the special value
C<Maybe:nothing>, aka C<nothing>, which is the only C<Maybe> value with
zero elements.  If the node payload is defined then the node is interpreted
as a C<Single> whose element is defined by the payload.  The payload is a
C<expr> node that defines the C<value> attribute of the single tuple
of the new 'single'.

Examples:

    [ 'Maybe', 'I know this one!' ]

    [ 'Maybe', undef ]

=head2 Array Selectors

A C<Array> node represents a literal or selector invocation for a
array value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Array> value whose elements are defined by the
payload.  The payload must be just a Perl array ref.  Each element of the
payload defines a binary tuple of the new sequence; the element value
is a C<expr> 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:

    [ 'Array', [
        'Alphonse',
        'Edward',
        'Winry',
    ] ]

    [ 'Array', 'fed.lib.the_db.stats.Samples_By_Order', [
        57,
        45,
        63,
        61,
    ] ]

=head2 Bag Selectors

A C<Bag> node represents a literal or selector invocation for a bag
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.Bag> value
whose elements are defined by the payload.  The payload is interpreted as
follows:

=over

=item *

Iff the payload is a Perl array ref with zero elements, then it defines the
only bag value having zero elements.  Iff the payload is an array ref with
at least one element, then every one of the payload elements must be itself
a Perl array ref.

=item *

Iff the payload is an array ref with at least one (array ref) element, and
the first element of that element I<is> itself an array ref, then the
payload is interpreted as being of the I<array counted values> bag format.
Each element of the payload defines a binary tuple of the new
bag; the element is a 2-element array ref, and those 2 elements, by
index order, are a C<expr> node that defines the C<value> attribute of the
tuple, and a valid C<Int> node payload that defines the C<count>
attribute of the tuple; the count must be a positive integer.

=item *

Iff the payload is an array ref with at least one (array ref) element, and
the first element of that element I<is not> itself an array ref, then the
payload is interpreted as being of the I<array repeated values> bag format.
Each element of the payload contributes to a binary tuple of the new
bag; the element value is a C<expr> 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.

=back

Examples:

    [ 'Bag', 'fed.lib.the_db.inventory.Fruit', [
        [ 'Apple'  => 500 ],
        [ 'Orange' => 300 ],
        [ 'Banana' => 400 ],
    ] ]

    [ 'Bag', [
        'Foo',
        'Quux',
        'Foo',
        'Bar',
        'Baz',
        'Baz',
    ] ]

=head2 Interval Selectors

An C<Interval> node represents a literal or selector invocation for an
interval value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Interval> value whose attributes are defined by the
payload.  The node payload must be a Perl array ref with 3 elements, which
are designated in order: I<min>, I<interval boundary kind>, I<max>.  Each
of I<min> and I<max> is an C<expr> node that defines the C<min> and C<max>
attribute value, respectively, of the new interval.  The I<interval
boundary kind> is one of these 4 Perl character strings: C<..>, C<..^>,
C<^..>, C<^..^>; each of those strings corresponds to one of the 4 possible
combinations of C<excludes_min> and C<excludes_max> values that the new
interval can have, which in order are: C<[false,false]>, C<[false,true]>,
C<[true,false]>, C<[true,true]>.

Examples:

    [ 'Interval', [1,'..',10] ]

    [ 'Interval', [2.7,'..^',9.3] ]

    [ 'Interval', ['a','^..','z'] ]

    [ 'Interval', [[ 'UTCInstant', [2002,12,6] ], '^..^',
        [ 'UTCInstant', [2002,12,20] ]] ]

=head1 DEPOT SPECIFICATION

A C<depot> node has 2-3 ordered elements such that 3 elements means the
depot has a normal-user-data database and 2 elements means it has just a
(possibly empty) system catalog database:  The first element is the Perl
character string C<depot>.  Iff the C<depot> has 3 elements then the third
element specifies the normal-user-data database; it is a single-element
Perl hash ref whose element's key is the Perl character string
C<depot-data> and whose element's value is a C<Database> node.  The second
element specifies the system catalog database; it is a single-element Perl
hash ref whose element's key is the Perl character string C<depot-catalog>
and whose element's value is either a C<Database> node or a Perl array ref
which is hereafter referred to as C<depot_catalog_payload>.  A
C<depot_catalog_payload> either has zero elements, designating an empty
catalog, or all of its elements are Perl array refs (in particular, none of
its elements is the Perl character string 'Database'), each of which is one
of the following kinds of nodes: C<subdepot>, C<material>,
C<self_local_dbvar_type>.

A C<subdepot> node has 3 ordered elements:  The first element is the Perl
character string C<subdepot>.  The second element is a C<Name_payload>,
which is the declared name of the subdepot within the namespace defined by
its parent subdepot (or depot).  The third element is a
C<depot_catalog_payload>.

A C<self_local_dbvar_type> node has 2 ordered elements:  The first element
is the Perl character string C<self-local-dbvar-type>.  The second element
is a C<NameChain_payload>, which specifies what the normal-user-data
database has as its declared data type.

Examples:

    # A completely empty depot that doesn't have a self-local dbvar. #
    [ 'depot', { 'depot-catalog' => [] } ]

    # Empty depot with self-local dbvar with unrestricted allowed values. #
    [ 'depot',
        { 'depot-catalog' => [
            [ 'self-local-dbvar-type', 'Database' ]
        ] },
        { 'depot-data' => [ 'Database', {} ] }
    ]

    # A depot having just one function and no dbvar. #
    [ 'depot', { 'depot-catalog' => [
        [ 'function', 'public', 'cube', [ 'Int', { topic => 'Int' }, [
            [ 'op', 'I^', [ ['$','topic'], 3 ] ]
        ] ] ]
    ] } ]

=head1 MATERIAL SPECIFICATION

A C<material> node specifies a new material (routine or type) that lives in
a depot or subdepot.

There are 7 main varieties of C<material> node, each of which is a named
node kind of its own:  C<function>, C<updater>, C<procedure>,
C<scalar_type>, C<nonscalar_type>, C<union_type>, C<subset_type>.

=head2 Material Specification Common Elements

A C<material> node has 2-4 ordered elements, such that a material that has
2 elements is an C<anon_material> and a material with 3-4 elements is a
C<named_material>:  The first element is C<material_kind>.  The last
element is C<material_payload>.  Iff there are 3-4 elements then the
second-to-last element is C<material_declared_name>.  Iff there are 4
elements then the second element is C<priv_or_pub>.

=over

=item C<material_kind>

This is a character string of the format C<< [<[ a..z ]>+] ** '-' >>; it
identifies the kind of the material and is the only external meta-data of
C<material_payload> generally necessary to interpret the latter; what
grammars are valid for C<material_payload> depend just on C<material_kind>.

=item C<priv_or_pub>

This is one of the 2 character strings [C<private>, C<public>]; it is
C<public> if the material is part of its containing subdepot's own public
interface and may be invoked from outside the subdepot; it is C<private> if
it is just part of the subdepot's internals.  This is optional iff
C<material> is a C<named_material>; this must be omitted iff C<material> is
an C<anon_material>.  If C<priv_or_pub> is not explicitly specified then
the C<material> is interpreted as if it were explicitly C<private> (so all
C<anon_material> are private).

=item C<material_declared_name>

This is the declared name of the material within the namespace defined by
its subdepot (or depot).  It is explicitly specified iff the C<material> is
a C<named_material>

=item C<material_payload>

This is mandatory for all C<material>.  It specifies the entire material
sans its name.  Format varies with C<material_kind>.

=back

For material examples, see the subsequent documentation sections.

=head2 Function Specification

I<TODO.>

=head2 Updater Specification

I<TODO.>

=head2 Procedure Specification

I<TODO.>

=head2 Scalar Type Specification

I<TODO.>

=head2 Nonscalar Type Specification

I<TODO.>

=head2 Union Type Specification

I<TODO.>

=head2 Subset Type Specification

I<TODO.>

=head1 GENERIC VALUE EXPRESSIONS

An C<expr_name> node has 2 ordered elements:  The first element is the Perl
character string C<$>.  The second element is a C<Name_payload>.

A C<named_expr> node has 3 ordered elements:  The first element is the Perl
character string C<::=>.  The second element is a C<Name_payload> and the
third element is an C<expr> node; the second element declares an explicit
expression node name for the third element.

Examples:

    # an expr_name node #
    ['$','foo_expr']

    # a named_expr node #
    [ '::=', 'bar_expr', [ 'func-invo', 'factorial', [['$','foo_expr']] ] ]

=head2 Generic Expression Attribute Accessors

An C<accessor> node has 2-3 ordered elements, such that 2 elements makes it
an C<acc_via_named> and 3 elements makes it an C<acc_via_anon>:  The first
element is the Perl character string C<$.>.  The last element of an
C<acc_via_named> is a C<NameChain_payload>, which is by itself the
C<target> of the accessor (naming both the other node plus its attribute to
alias).  The second element of an C<acc_via_anon> is an C<expr> node which
is the other node whose attribute is being aliased.  The last element of an
C<acc_via_anon> is a C<DeclNameChain_payload> and names the attribute.

Examples:

    # an accessor node of a named tuple-valued node #
    ['$.','foo_t.bar_attr']

    # an accessor node of an anonymous tuple-valued node #
    ['$.',['func-invo','sdp.lib.tuple_res_func',[['$','arg']]],'quux_attr']

=head2 Generic Function Invocation Expressions

An C<func_invo> node has 2-4 ordered elements:  The first element is the
Perl character string C<func-invo>.  The second element is a
C<NameChain_payload>, which names the function to invoke.  The last 1-2
elements provide arguments to the function invocation; either or both or
none of a C<Array_payload> element and a C<Tuple_payload> element may be
given.  The C<Array_payload> 3rd/4th element is for any anonymous (and
ordered if multiple exist) arguments, and the C<Tuple_payload> 3rd/4th
element is for any named arguments; each C<Array_payload> element or
C<Tuple_payload> element value is an C<expr> node which is the argument
value.

Examples:

    # zero params #
    [ 'func-invo', 'nothing' ]

    # single mandatory param #
    [ 'func-invo', 'Integer.median',
        [ [ 'Bag', [ 22, 20, 21, 20, 21, 21, 23 ] ] ] ]

    # single mandatory param #
    [ 'func-invo', 'factorial', { topic => 5 } ]

    # two mandatory params #
    [ 'func-invo', 'Rational.quotient',
        { dividend => 43.7, divisor => 16.9 } ]

    # one mandatory 'topic' param, two optional #
    [ 'func-invo', 'sdp.lib.barfunc', [ ['$','mand_arg'] ],
        { oa1 => ['$','opt_arg1'], oa2 => ['$','opt_arg2'] } ]

    # a user-defined function #
    [ 'func-invo', 'dep.lib.foodb.bazfunc',
        { a1 => 52, a2 => 'hello world' } ]

    # two params named 'topic' and 'other' #
    [ 'func-invo', 'is_identical', [ ['$','foo'], ['$','bar'] ] ]

=head2 Generic If-Else Expressions

An C<if_else_expr> node has 2-3 ordered elements:  The first element is
either of the 2 Perl character strings C<if-else-expr> and C<??!!>.  The
optional second element is I<if_then>, a Perl array ref with 0..N elements,
each of those being a 2-element Perl array ref, where each element is an
C<expr> node; the first element is an I<if> condition expression, and the
second element is the associated I<then> result expression.  The 3rd/last
element of an C<if_else_expr> node is I<else> result expression, which is
an C<expr> node.

Examples:

    [ 'if-else-expr',
        [
            [[ 'op', '>', [['$','foo'], 5] ] => ['$','bar']],
        ],
        ['$','baz']
    ]

    [ 'if-else-expr',
        [
            [[ 'op', 'is-empty', [['$','ary']] ] => ['$','empty_result']],
        ],
        [ 'op', '.[]', [['$','ary'], 0] ]
    ]

    [ 'op', 'T~', ['My answer is: ',
        [ '??!!', [ [['$','maybe'] => 'yes'] ], 'no' ]] ]

=head2 Generic Given-When-Default Expressions

A C<given_when_def_expr> node has 3-4 ordered elements:  The first element
is the Perl character string C<given-when-def-expr>.  The second element is
an C<expr> node which is the I<given> common comparand.  The optional third
element is I<when_then>, a Perl array ref with 0..N elements, each of those
being a 2-element Perl array ref, where each element is an C<expr> node;
the first element is a I<when> comparand, and the second element is the
associated I<then> result expression.  The 4th/last element of an
C<given_when_def_expr> node is I<default> result expression, which is an
C<expr> node.

Examples:

    [ 'given-when-def-expr',
        ['$','digit'],
        [
            [ 'T' => 10 ],
            [ 'E' => 11 ],
        ],
        ['$','digit'],
    ]

=head2 Library Entity Reference Selector

A C<[func|upd|proc|type|ord_det_func]_ref> node has 2 ordered elements:
The first element is the Perl character string value
C<[func|upd|proc|type|ord-det-func]-ref>.  The second element is a
C<NameChain_payload>, which names the routine|type to invoke.

Examples:

    ['func-ref','sdp.lib.filter']

    ['upd-ref','sdp.lib.swap']

    ['proc-ref','sdp.lib.try_block']

    ['type-ref','sdp.lib.foo_type']

    ['ord-det-func-ref','sdp.lib.order_bars']

=head1 FUNCTION INVOCATION ALTERNATE SYNTAX EXPRESSIONS

A C<func_invo_alt_syntax> node has 3-4 ordered elements:  The first element
is the Perl character string C<op>.  The second element is a Perl character
string, hereafter referred to as I<op> or I<keyword>, which determines the
function to invoke.  The third element is (usually) a Perl array ref,
hereafter referred to as I<main op args>, which is an ordered list of 1-N
mandatory inputs to the function invocation.  The (optional) fourth element
is a Perl hash ref, hereafter referred to as I<extra op args>, which is a
named list of optional function inputs.  The number and format of elements
of either I<main op args> or I<extra op args> varies depending on I<op>.
Note that, when a I<main op args> would just contain a single element, such
as when it is for a monadic operator, it may alternately be formatted as
what is otherwise just its sole (node) element iff that node is not
formatted as a Perl array ref.

=head2 Simple Commutative N-adic Infix Reduction Operators

A C<comm_infix_reduce_op_invo> node has 2-N main op args, each of which
is an C<expr> node.

Examples:

    [ 'op', 'and', [ ['Bool','true'], ['Bool','false'], ['Bool','true'] ] ]

    [ 'op', 'or', [ ['Bool','true'], ['Bool','false'], ['Bool','true'] ] ]

    [ 'op', 'xor', [ ['Bool','true'], ['Bool','false'], ['Bool','true'] ] ]

    [ 'op', 'I+', [ 14, 3, -5 ] ]

    [ 'op', 'I*', [ -6, 2, 25 ] ]

    [ 'op', 'N+', [ 4.25, -0.002, 1.0 ] ]

    [ 'op', 'N*', [ 69.3, [ 'Rat', [15,2,6] ], [ 'Rat', [49,23] ] ] ]

    [ 'op', '∪', [ [ 'Set', [ 1, 3, 5 ] ],
        [ 'Set', [ 4, 5, 6 ] ], [ 'Set', [ 0, 9 ] ] ] ]

    [ 'op', '∩', [ [ 'Set', [ 1, 3, 5, 7, 9 ] ],
        [ 'Set', [ 3, 4, 5, 6, 7, 8 ] ], [ 'Set', [ 2, 5, 9 ] ] ] ]

=head2 Simple Non-commutative N-adic Infix Reduction Operators

A C<noncomm_infix_reduce_op_invo> node has 2-N main op args, each of which
is an C<expr> node.

Examples:

    [ 'op', '[<=>]', [ ['Order','same'],
        ['Order','increase'], ['Order','decrease'] ] ]

    [ 'op', 'B~', [ [ 'Blob', { F => 'DEAD' } ],
        [ 'Blob', { 1 => '10001101' } ], [ 'Blob', { F => 'BEEF' } ] ] ]

    [ 'op', 'T~', [ 'hello', ' ', 'world' ] ]

    [ 'op', 'A~', [ [ 'Array', [ 24, 52 ] ],
        [ 'Array', [ -9 ] ], [ 'Array', [ 0, 11, 24, 7 ] ] ] ]

    [ 'op', '//', [ ['$','a'], ['$','b'], 42 ] ]

    [ 'op', '//d', [['$','a'],['$','b'],['type-ref','sdp.lib.foo_type']] ]

=head2 Simple Symmetric Dyadic Infix Operators

A C<sym_dyadic_infix_op_invo> node has exactly 2 main op args, each of
which is an C<expr> node; which function arguments get which main op args
isn't significant.

Examples:

    [ 'op', '=', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', '≠', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', 'nand', [ ['Bool','false'], ['Bool','true'] ] ]

    [ 'op', 'I|-|', [ 15, 17 ] ]

    [ 'op', 'N|-|', [ 7.5, 9.0 ] ]

=head2 Simple Non-symmetric Dyadic Infix Operators

A C<nonsym_dyadic_infix_op_invo> node has exactly 2 main op args, each of
which is an C<expr> node; the first and second main op args are C<lhs> and
C<rhs>, respectively.

Examples:

    [ 'op', 'isa', [ ['$','bar'], ['type-ref','sdp.lib.foo_type'] ] ]

    [ 'op', '!isa', [ ['$','bar'], ['type-ref','sdp.lib.foo_type'] ] ]

    [ 'op', 'as', [ ['$','scalar'], ['type-ref','Int'] ] ]

    [ 'op', 'asserting', [['$','int'], [ 'op', '≠', [['$','int'], 0] ]] ]

    [ 'op', 'implies', [ ['Bool','true'], ['Bool','false'] ] ]

    [ 'op', 'I-', [ 34, 21 ] ]

    [ 'op', 'I/', [ 5, 3 ] ]

    [ 'op', '%', [ 5, 3 ] ]

    [ 'op', 'I^', [ 2, 63 ] ]

    [ 'op', 'N-', [ 9.2, 0.1 ] ]

    [ 'op', 'N/', [[ 'Rat', {1 => '101.01'} ], [ 'Rat', {1 => '11.0'} ]] ]

    [ 'op', 'Tx', [ '-', 80 ] ]

    [ 'op', '∖', [ [ 'Set', [ 8, 4, 6, 7 ] ], [ 'Set', [ 9, 0, 7 ] ] ] ]

    [ 'op', '÷', [ [ 'Relation', [ ['x', 'y'] => [ [5, 6], [3, 6] ] ] ],
        [ 'Relation', [ { y => 6 } ] ] ] ]

=head2 Simple Monadic Prefix Operators

A C<monadic_prefix_op_invo> node has exactly 1 main op arg, which is an
C<expr> node.

Examples:

    [ 'op', 'd', ['type-ref','sdp.lib.foo_type'] ]

    [ 'op', 'not', [['Bool','true']] ]

    [ 'op', 'I||', -23 ]

    [ 'op', 'N||', -4.59 ]

    [ 'op', 'R#', [[ 'Set', [ 5, -1, 2 ] ]] ]

    [ 'op', 't', [['$','relvar']] ]

    [ 'op', 'r', [['$','tupvar']] ]

    [ 'op', 's', [[ 'op', 'N+',
        [[ 'op', 'v', [['$','a']] ], [ 'op', 'v', [['$','b']] ]] ]] ]

=head2 Simple Monadic Postfix Operators

A C<monadic_postfix_op_invo> node has exactly 1 main op arg, which is an
C<expr> node.

Examples:

    [ 'op', '++', 13 ]

    [ 'op', '--', 4 ]

    [ 'op', 'I!', 5 ]

=head2 Simple Postcircumfix Operators

A C<postcircumfix_op_invo> node has exactly 2-3 main op args, where the
first is an C<expr> node that defines the primary input value for the
operator and the other 1-2 provide attribute names that customize the
operation.

Note that for the C<[]> op, the C<min_index>, C<interval_boundary_kind>,
C<max_index> are collectively the 2nd main op arg which is an C<Interval>
node payload that defines an C<interval_of.NNInt>.

Examples:

    [ 'op', '.${}', [['$','birthday'], 'date', 'day'] ]

    [ 'op', '.%{}', [['$','pt'], 'city'] ]

    [ 'op', '%{<-}', [['$','pt'], {pnum=>'pno', locale=>'city'}] ]

    [ 'op', '@{<-}', [['$','pr'], {pnum=>'pno', locale=>'city'}] ]

    [ 'op', '${}', [['$','birthday'], 'date', ['year','month']] ]

    [ 'op', '%{}', [['$','pt'], ['color','city']] ]

    [ 'op', '@{}', [['$','pr'], ['color','city']] ]

    [ 'op', '%{}', [['$','pt'], []] ]  # null projection #

    [ 'op', '@{}', [['$','pr'], []] ]  # null projection #

    [ 'op', '${!}', [['$','rnd_rule'], ['round_meth']] ]  # radix,min_exp #

    [ 'op', '%{!}', [['$','pt'], ['pno','pname','weight']] ]

    [ 'op', '@{!}', [['$','pr'], ['pno','pname','weight']] ]

    [ 'op', '%{%<-}', [['$','person'], 'name', ['fname','lname']] ]

    [ 'op', '@{%<-}', [['$','people'], 'name', ['fname','lname']] ]

    [ 'op', '%{%<-!}', [['$','person'],'all_but_name',['fname','lname']] ]

    [ 'op', '@{%<-!}', [['$','people'],'all_but_name',['fname','lname']] ]

    [ 'op', '%{<-%}', [['$','person'], ['fname','lname'], 'name'] ]

    [ 'op', '@{<-%}', [['$','people'], ['fname','lname'], 'name'] ]

    [ 'op', '@{@<-}', [['$','orders'], 'vendors', ['vendor']] ]

    [ 'op', '@{@<-!}', [['$','orders'], 'all_but_vendors', ['vendor']] ]

    [ 'op', '@{<-@}', [['$','orders'], ['vendor'], 'vendors'] ]

    [ 'op', '@{#@<-!}',
        [['$','people'], 'count_per_age_ctry', ['age','ctry']] ]

    [ 'op', '.[]', [['$','ary'], 3] ]

    [ 'op', '[]', [['$','ary'], [10,'..',14]] ]

=head2 Rational Operators That Do Rounding

A C<rat_op_invo_with_round> node has exactly 2-3 main op args, each of
which is an C<expr> node that defines an input value for the operator.
When there are 2 main op args, the first and second args are C<expr> and
C<round_rule>, respectively.  When there are 3 main op args, the first,
second and third args are C<lhs>, C<rhs> and C<round_rule>, respectively.

Examples:

    [ 'op', 'round', [ ['$','foo'],
        [ 'RatRoundRule', [10,-2,'half_even'] ] ] ]

    [ 'op', 'N^', [ 2.0, 0.5, [ 'RatRoundRule', [2,-7,'to_zero'] ] ] ]

    [ 'op', 'log', [ 309.1, 5.4, [ 'RatRoundRule', [10,-4,'half_up'] ] ] ]

    [ 'op', 'e^', [ 6.3, [ 'RatRoundRule', [10,-6,'to_ceiling'] ] ] ]

    [ 'op', 'log-e', [ 17.0, [ 'RatRoundRule', [3,-5,'to_floor'] ] ] ]

=head2 Order Comparison Operators

An C<ord_compare_op_invo> node has exactly 2 or 3 or 2-N main op args,
depending on the op, each of which is an C<expr> node.  When the op
requires exactly 2 main op args, the first and second args are C<lhs> and
C<rhs>, respectively.  When the op requires exactly 2 main op args, the
first, second and third args are C<min>, C<expr>, and C<max>, respectively.
When the op is N-adic, requiring 2-N main op args, then the order of the
main op args isn't significant.  Details on the extra op args are pending.

Examples (for now sans any use of extra op args, which are atypical):

    [ 'op', '<=>', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', 'min', [ ['$','a'], ['$','b'], ['$','c'] ] ]

    [ 'op', 'max', [ ['$','a'], ['$','b'], ['$','c'] ] ]

    [ 'op', '<', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', '>', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', '≤', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', '≥', [ ['$','foo'], ['$','bar'] ] ]

    [ 'op', 'I∈', [ ['$','a'], [ 'Interval', [1,'..',5] ] ] ]

    [ 'op', '≤≤', [ ['$','min'], ['$','foo'], ['$','max'] ] ]

    [ 'op', '≤<', [ ['$','min'], ['$','foo'], ['$','max'] ] ]

    [ 'op', '!<≤', [ ['$','min'], ['$','foo'], ['$','max'] ] ]

    [ 'op', '!<<', [ ['$','min'], ['$','foo'], ['$','max'] ] ]

=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<darren@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.

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