=pod

=encoding utf8

=head1 NAME

Muldis::D::Dialect::HDMD_Perl6_STD -
How to format Perl 6 Hosted Data Muldis D

=head1 VERSION

This document is Muldis::D::Dialect::HDMD_Perl6_STD version 0.73.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_Perl6_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_Perl6_STD' ]> (when
the bundled base language version is substituted for the C<N.N.N>).

The C<HDMD_Perl6_STD> dialect is defined to be hosted in Perl 6, and is
composed of just|mainly core Perl 6 types.  This dialect is optimized for
Perl 6 specifically, and doesn't try to match the version for Perl 5; 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 6 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 6.  This dialect
exists as a convenience to Perl 6 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 6 will natively accept input in both the
C<PTMD_STD> and C<HDMD_Perl6_STD> dialects.  Furthermore, the
C<HDMD_Perl6_STD> dialect provides additional Muldis D syntax options to
Perl 6 programmers besides what C<PTMD_STD> would canonically parse into,
such as the direct use of some Perl 6-only features.  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_Perl6_STD> Muldis D code file is actually a Perl 6 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 Seq|Array, but could alternately be a Perl
scalar or something else, and so C<HDMD_Perl6_STD> Muldis D code is
typically a tree of Perl structures, called I<node trees>, with Perl
Seq|Array as the central nodes and Perl scalars as the leaf nodes.  Often
C<HDMD_Perl6_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 Seq|Array unless otherwise stated, and every grammar element
is a Seq|Array element; the first node element is the Seq|Array element at
index zero, and so on.

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

=head1 BOOTLOADER

A C<bootloader> node has 1..N ordered elements where the first element is a
C<language_name> node and then either: 1. there is exactly one (second)
element that is a C<value> node or a C<depot> node; 2. there are 1..N
ordered elements where each is a C<boot_stmt> node; 3. there are no other
elements, making the bootloader a no-op.

See the pod sections in this file named L</LANGUAGE NAME>, L</VALUE
LITERALS AND SELECTORS>, L</DEPOT DECLARATION>, and L</BOOTLOADER
STATEMENT> 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, the conceptual
C<bootloader> is usually split up, and so not every Muldis D code fragment
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_Perl6_STD> dialect formats this name as a
C<language_name> node having 4-5 ordered elements:

=over

=item C<ln_base_name>

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

=item C<ln_base_authority>

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

=item C<ln_base_version_number>

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

=item C<ln_dialect>

This is the dialect name; it is simply the Perl C<Str> value
C<HDMD_Perl6_STD>.

=item C<ln_extensions>

Optional; this is a set of chosen pragma/parser-config options as per a
C<Tuple> SCVL; see the L</MULDIS D TINY DIALECT PRAGMAS> pod section for
more details.

=back

Examples:

    [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl6_STD' ]

    [ 'Muldis_D', 'http://muldis.com', '1.2.3', 'HDMD_Perl6_STD', {
        ...
    } ]

=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 26 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<String>, C<QScalar>, C<QTuple>, C<Database>, C<QRelation>, C<QSet>,
C<QMaybe>, C<QArray>, C<QBag>, C<RatRoundRule>.

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

=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 Perl C<Str> value 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<payload> generally necessary to interpret the
latter; what grammars are valid for C<payload> depend just on
C<value_kind>.

Between the various kinds of C<value> node, these 49 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<[|B|O|UCP]String>, C<[Q|]Scalar>, C<[Q|]Tuple>,
C<Database>, C<[Q|]Relation>, C<[Q|]Set>, C<[Q|][Maybe|Single]>,
C<[Q|]Array>, C<[Q|]Bag>, C<RatRoundRule>.

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<payload> is a member of the
named subtype.  Its format is a C<NameChain_payload> node.  Iff
C<value_kind> is C<[Q|]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<payload>

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

=back

A Perl Pair may alternately be used to represent a GCVL iff that node has
exactly 2 elements (C<value_kind> and C<payload>); in that case, the
C<value_kind> is stored in that Pair's key, and the C<payload> is stored in
the Pair's value.

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 6
    --------------------
    Bool     <- Bool
    Order    <- Order
    Int      <- Int
    Rat      <- Rat|Num
    Blob     <- Blob
    Text     <- Str
    Instant  <- Instant
    Duration <- Duration

The above details are subject to revision regarding when a Perl object
might claim to do multiple type interfaces.

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:  The payload must be a
Perl C<Bool>, and so C<Bool::False> and C<Bool::True> are mapped directly.

Examples:

    :Bool(Bool::True)

    Bool::False

=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:  The payload must
be a Perl C<Order>, and so C<Order::Increase> and C<Order::Same> and
C<Order::Decrease> are mapped directly.

Examples:

    :Order(Order::Same)

    Order::Decrease

=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 C<Str> 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:  The payload must be a
Perl C<Int>, which is mapped directly.

Examples:

    :Int(:2<11001001>) # binary #

    :8<0> # octal #

    :8<644> # octal #

    -34 # decimal #

    42 # decimal #

    :16<DEADBEEF> # hexadecimal #

    :36<-HELLOWORLD> # base-36 #

    :4<301> # base-4 #

    :12<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:  The payload must
be a Perl C<Rat|Num|Int>, which is mapped directly.

Examples:

    :Rat(:2<-1.1>)

    -1.5 # same val as prev #

    3.14159

    :11<0.0>

    :16<DEADBEEF.FACE>

    :36<0.000AZE>

    :Rat(:7<500001> div :7<1000>)

    :12<A09B> div :12<A>

    :Rat(:2<1011101101> * :2<10> ** :2<-11011>)

    45207196 * 10 ** 37

    1 div 43

    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:  The payload must
be a Perl C<Blob>, which is mapped directly.

Examples I<TODO: What is the actual syntax for the P6 Blob type?>:

    :Blob( Blob.new(  2 => '00101110100010' ) ) # binary #

     Blob.new(  4 => '' )

     Blob.new( 16 => 'A705E' ) # hexadecimal #

     Blob.new(  8 => '523504376' )

=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 a Perl C<Str>.

Examples:

    :Text<Ceres>

    'サンプル'

    ''

    'Perl'

    "\c[LATIN SMALL LETTER OU]\x[263A]\c[65]"

=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 a Perl C<Str>.

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 C<Seq|Array> value or C<Str> value.  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 C<Seq|Array>, 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 C<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 C<Seq|Array> payload format to express it).  The
C<Str> format of payload is interpreted by splitting it on the separators
into the C<Seq|Array> format, then processed as per the latter.

=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 C<Seq|Array> payload format; an empty string
C<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')

    :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 a Perl C<Str>.

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 of atomic seconds.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Instant> value as follows:  The payload must be a Perl
C<Instant>, which is mapped directly.

A C<Duration> node represents a single amount of time (the difference
between two instants) which is specified in terms of of atomic seconds.
This node is interpreted as a Muldis D C<sys.std.Core.Type.Duration> value
as follows:  The payload must be a Perl C<Duration>, which is mapped
directly.

Examples I<TODO: What is t actual syntax for P6 [Instant|Duration] types?>:

    :Instant( Instant.new(1235556432.0) )

    Instant.new(854309115.0)

    :Duration( Duration.new(3600.0) )

    Duration.new(-50.0)

    Duration.new(3.14159)

    Duration.new(:2<1011101101> * :2<10> ** :2<-11011>)

    Duration.new(1 div 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:

The payload must be a Perl C<Seq|Array> with 6 elements, where each element
may be either undefined or defined; or if fewer than 6 elements are
provided, the C<Seq|Array> 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.

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:

The payload must be a Perl C<Seq|Array> with 6 elements, where each element
may be either undefined or defined; or if fewer than 6 elements are
provided, the C<Seq|Array> 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.>

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 Low Level Integer String Literals

A C<String> node represents an integer string value.  It is interpreted as
a Muldis D C<sys.std.Core.Type.Cat.String> value as follows:  The payload
must be a Perl C<Seq|Array>, whose elements are all Perl C<Int>, which is
mapped directly; each payload element is mapped directly as per the payload
of an C<Int> node.

Examples:

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

    :String[0x50,0x65,0x72,0x6C] # 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 or C<boot_stmt> node.

=head2 Scalar Selectors

A C<QScalar> node represents a literal or selector invocation for a
quasi-scalar subtype value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QScalar> subtype value whose declared type is specified
by the node's (mandatory for C<QScalar>) C<type_name> element and whose
attributes are defined by the payload.  The payload must be a Perl C<Pair>,
whose key and value, respectively, are designated I<possrep name> and
I<possrep attrs>.  The possrep name and possrep attrs must be as per the
payload of a C<Name> and C<QTuple> 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 C<Str> that specifies
the possrep attribute name, and a C<expr> node that specifies the possrep
attribute value.

Examples:

    [ '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,
    } ]

=head2 Tuple Selectors

A C<QTuple> node represents a literal or selector invocation for a
quasi-tuple value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QTuple> value whose attributes are defined by the
payload.  The payload must be a Perl C<Mapping|Hash>.  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 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 Perl C<Mapping|Hash>.  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 C<Str> 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<QRelation> node represents a literal or selector invocation for a
quasi-relation value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QRelation> value whose attributes and tuples are
defined by the payload, which is interpreted as follows:

=over

=item *

Iff the payload is a Perl C<Set|KeySet> with zero elements, then it
defines the only relation value having zero attributes and zero tuples.

=item *

Iff the payload is a Perl C<Set|KeySet> with at least one element, and
every element is a Perl C<Str> (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 C<Set|KeySet> with at least one element, and
every element is a Perl C<Mapping|Hash> (as per a valid payload for a
C<QTuple> 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 C<Pair>, then:  The new relation value's
attribute names are defined by the payload's key, which is a Perl
C<Seq|Array> of C<Str> (each as per a C<Name> node payload), and the
relation body's tuples' attribute values are defined by the payload's
value, which is a Perl C<Set|KeySet> of C<Seq|Array> 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 value must
appear in the same order as their corresponding attribute names appear in
the payload key, as the names and values in the relation literal are
matched up by ordinal position here.

=back

Examples I<TODO: What is the actual syntax for the P6 Set type?>:

    :Relation( Set.new() )  # zero attrs + zero tuples #

    :Relation( Set.new(<x y z>) )  # 3 attrs + zero tuples #

    :Relation( Set.new( {} ) )  # zero attrs + 1 tuple #

    :Relation( Set.new(
        {
            login_name => 'hartmark',
            login_pass => 'letmein',
            is_special => Bool::True,
        },
    ) )  # 3 attrs + 1 tuple #

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

=head2 Set Selectors

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

Examples I<TODO: What is the actual syntax for the P6 Set type?>:

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

    :Set( Set.new(
        3,
        16,
        85,
    ) )

=head2 Maybe Selectors

A C<QMaybe> node represents a literal or selector invocation for a
quasi-maybe value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QMaybe> 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<QMaybe> value with
zero elements.  If the node payload is defined then the node is interpreted
as a C<QSingle> whose element is defined by the payload.  The payload is a
C<expr> node that defines the C<value> attribute of the single quasi-tuple
of the new quasi-'single'.

Examples:

    :Maybe( 'I know this one!' )

    :Maybe()  # or how does Perl 6 make a Pair with undef/default value? #

=head2 Array Selectors

A C<QArray> node represents a literal or selector invocation for a
quasi-array value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QArray> value whose elements are defined by the
payload.  The payload must be a Perl C<Seq|Array>.  Each element of the
payload defines a binary quasi-tuple of the new sequence; the element value
is a C<expr> node that defines the C<value> attribute of the quasi-tuple,
and the element index is used as the C<index> attribute of the quasi-tuple.

Examples:

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

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

=head2 Bag Selectors

A C<QBag> node represents a literal or selector invocation for a quasi-bag
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.QBag> value
whose elements are defined by the payload.  The payload must be a Perl
C<Bag|KeyBag|Set|KeySet> value; the payload element keys are C<expr> nodes
corresponding to the C<value> attribute of the new quasi-bag's
quasi-tuples, and the payload element values are positive integers (or
C<Bool::True>, which counts as the number 1) corresponding to the C<count>
attribute; the payload element mapping is as you should expect.

Examples I<TODO: What is the actual syntax for the P6 Bag type?>:

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

    :Bag( Bag.new( [
        'Foo',
        'Quux',
        'Foo',
        'Bar',
        'Baz',
        'Baz',
    ] ) )

=head2 Rational Rounding Rule Selectors

A C<RatRoundRule> node represents a literal or selector invocation for 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
C<Seq|Array> 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 the 3 C<RatRoundRule_payload>
elements is an C<expr> node.

Examples:

    :RatRoundRule[10,-2,half_even]

    :RatRoundRule[2,-7,to_zero]

=head1 GENERIC VALUE EXPRESSIONS

An C<expr_name> node has 2 ordered elements:  The first element is the Perl
C<Str> value C<expr_name>.  The second element is a C<NameChain_payload>.

An C<expr_name> node may alternately be formatted as a Perl Pair whose key
and value are what would otherwise be the first and second node elements,
respectively.

A C<named_expr> node has 3 ordered elements:  The first element is the Perl
C<Str> value C<named_expr>.  The second element is a C<Name_payload> and
the third element is an C<expr> node (that isn't a C<named_expr> node); the
second element declares an explicit expression node name for the third
element.

Examples:

    # an expr_name node #
    :expr_name<foo_expr>

    # a named_expr node #
    [ 'named_expr', 'bar_expr',
        [ 'func_invo', 'factorial', [ :expr_name<foo_expr> ] ] ]

=head2 Generic Function Invocation Expressions

An C<func_invo> node has 2-4 ordered elements:  The first element is the
Perl C<Str> value 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<QArray_payload> element and a C<QTuple_payload> element may be
given.  The C<QArray_payload> 3rd/4th element is for any anonymous (and
ordered if multiple exist) arguments, and the C<QTuple_payload> 3rd/4th
element is for any named arguments; each C<QArray_payload> element or
C<QTuple_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( Bag.new( [ 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 param, two optional #
    [ 'func_invo', 'inn.barfunc', [ :expr_name<mand_arg> ],
        { oa1 => :expr_name<opt_arg1>, oa2 => :expr_name<opt_arg2> } ]

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

    # two params named 'topic' and 'other' #
    [ 'func_invo', 'is_identical',
        [ :expr_name<foo>, :expr_name<bar> ] ]

=head2 Generic If-Else Expressions

An C<if_else_expr> node has 2-3 ordered elements:  The first element is the
Perl C<Str> value C<if_else_expr>.  The optional second element is
I<if_then>, a Perl C<Seq|Array> with 0..N elements, each of those being a
2-element Perl C<Seq|Array> or a Perl Pair, where each element is an
C<expr> node; the first element / key is an I<if> condition expression, and
the second element / value is the associated <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', '>', :expr_name<foo>, 5 ] => :expr_name<bar>,
        ],
        :expr_name<baz>
    ]

    [ 'if_else_expr',
        [
            [ 'op', 'is_empty', :expr_name<ary> ]
                => :expr_name<empty_result>,
        ],
        [ 'op', 'QArray.value', :expr_name<ary>, 0 ]
    ]

=head2 Generic Given-When-Default Expressions

A C<given_when_def_expr> node has 3-4 ordered elements:  The first element
is the Perl C<Str> value 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 C<Seq|Array> with 0..N elements, each of
those being a 2-element Perl C<Seq|Array> or a Perl Pair, where each
element is an C<expr> node; the first element / key is a I<when> comparand,
and the second element / value is the associated <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',
        :expr_name<digit>,
        [
            'T' => 10,
            'E' => 11,
        ],
        :expr_name<digit>,
    ]

=head2 Library Entity Reference Selector

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

A C<[func|proc|type|ord_det_func]_ref> node may alternately be formatted as
a Perl Pair whose key and value are what would otherwise be the first and
second node elements, respectively.

Examples:

    :func_ref<inn.filter>

    :proc_ref<inn.try_block>

    :type_ref<inn.foo_type>

    :ord_det_func_ref<inn.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 C<Str> value C<op>.  The second element is a Perl C<Str> value,
hereafter referred to as I<op> or I<keyword>, which determines the function
to invoke.  The third element is (usually) a Perl C<Seq|Array>, 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
C<Mapping|Hash>, 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 C<Seq|Array>.

=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.  Note that the I<main op args> may alternately be given as
a Perl C<Bag|KeyBag|Set|KeySet> rather than a Perl C<Seq|Array>.

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, 15 * 2 ** 6, 49 div 23 ] ]

    [ 'op', 'R+', [ :Set( Set.new( 1, 3, 5 ) ),
        :Set( Set.new( 4, 5, 6 ) ), :Set( Set.new( 0, 9 ) ) ] ]

    [ 'op', 'R*', [ :Set( Set.new( 1, 3, 5, 7, 9 ) ),
        :Set( Set.new( 3, 4, 5, 6, 7, 8 ) ), :Set( Set.new( 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.new( 16 => 'DEAD' ),
        Blob.new( 2 => '10001101' ), Blob.new( 16 => 'BEEF' ) ] ]

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

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

=head2 Simple Commutative Dyadic Infix Operators

A C<comm_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', '===', [ :expr_name<foo>, :expr_name<bar> ] ]

    [ 'op', '!===', [ :expr_name<foo>, :expr_name<bar> ] ]

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

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

=head2 Simple Non-commutative Dyadic Infix Operators

A C<noncomm_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', 'I-', [ 34, 21 ] ]

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

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

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

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

    [ 'op', 'N/', [ :2<101.01>, :2<11.0> ] ]

    [ 'op', 'R-', [:Set(Set.new( 8, 4, 6, 7 )), :Set(Set.new( 9, 0, 7 ))] ]

    [ 'op', 'R/', [ :Relation( <x y> => Set.new( [ 5, 6 ], [ 3, 6 ] ) ),
        :Relation( Set.new( { 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', 'not', Bool::True ]

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

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

=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', '!', 5 ]

=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', [ :expr_name<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', 'loge', [ 17.0, :RatRoundRule[3,-5,to_floor] ] ]

=head1 DEPOT DECLARATION

B<TODO: ALL OF THIS HERE MAIN POD SECTION!>

=head1 BOOTLOADER STATEMENT

B<TODO/REDO: ALL OF THIS HERE MAIN POD SECTION!>

This node specifies one statement of a Muldis D C<bootloader> routine
which invokes an imperative routine, such statements being what the entire
body of a C<bootloader> is composed of.  A bootloader imperative routine
call is formatted as a node having the following 4 elements:

=over

=item *

Node kind: the Perl C<Str> value C<boot_stmt>.

=item *

Imperative routine name: a Perl C<Seq|Array|Str> as per the payload of a
C<NameChain> node.

=item *

Imperative routine subject-to-update args: a Perl C<Mapping|Hash> as per
the payload of a C<QTuple> node except that every C<Mapping|Hash> value is
just a Perl C<Seq|Array|Str> as per the payload of a C<NameChain> node
(each value is the name of a global variable).

=item *

Imperative routine read-only args: a Perl C<Mapping|Hash> as per the
payload of a C<QTuple> node.

=back

Examples

    [ 'boot_stmt', 'sys.std.Core.Cat.create_depot_procedure', {}, { ... } ]

=head1 MULDIS D TINY DIALECT PRAGMAS

B<TODO/REDO: ALL OF THIS HERE MAIN POD SECTION!>

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-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
