=pod

=encoding utf8

=head1 NAME

Muldis::D::Dialect::PTMD_STD -
How to format Plain Text Muldis D

=head1 VERSION

This document is Muldis::D::Dialect::PTMD_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<Plain Text Muldis D> dialect
named C<PTMD_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":PTMD_STD> (when the bundled base
language version is substituted for the C<N.N.N>).

This dialect is designed to exactly match the Muldis D system catalog (the
possible representation of Muldis D code that is visible to or updateable
by Muldis D programs at runtime) as to what non-critical meta-data it
explicitly stores; so code in the C<PTMD_STD> dialect should be
round-trippable with the system catalog with the result maintaining all the
details that were started with.  Since it matches the system catalog, this
dialect should be able to exactly represent all possible Muldis D base
language code (and probably all extensions too), rather than a subset of
it.  That said, the C<PTMD_STD> dialect does provide a choice of multiple
syntax options for writing Muldis D value literals and DBMS entity (eg type
and routine) declarations, so several very distinct C<PTMD_STD> code
artifacts may parse into the same system catalog entries.  There is even a
considerable level of abstraction in some cases, so that it is easier for
programmers to write and understand typical C<PTMD_STD> code, and so that
this code isn't absurdly verbose.

This dialect is designed to be as small as possible while meeting the above
criteria, and is designed such that a parser that handles all of this
dialect can be fairly small and simple.  Likewise, a code generator for
this dialect from the system catalog can be fairly small and simple.

A significant quality of the C<PTMD_STD> dialect is that it is designed to
work easily for a single-pass parser, or at least a single-pass lexer; all
the context that one needs to know for how to parse or lex any arbitrary
substring of code is provided by prior code, or any required lookahead is
just by a few characters in general.  Therefore, a C<PTMD_STD> parser can
easily work on a streaming input like a file-handle where you can't go back
earlier in the stream.  Often this means a parser can work with little RAM.

Also the dialect is designed that any amount of whitespace can be added or
omitted next to most non-alphanumeric characters (which happen to be next
to alphanumeric tokens) without that affecting the meaning of the code at
all, except obviously for within character string literals.  And long
binary or character or numeric or identifier strings can be split into
arbitrary-size substrings, without affecting the meaning.  And many
elements are identified by name rather than ordinal position, so to some
degree the order they appear has no effect on the meaning.  So programmers
can easily format (separate, indent, linewrap, order) code how they like,
and making an automated code reformatter shouldn't be difficult.  Often,
named elements can also be omitted entirely for brevity, in which case the
parser would use context to supply default values for those elements.

Given that plain text is (more or less) universally unambiguously portable
between all general purpose languages that could be used to implement a
DBMS, it is expected that every single Muldis D implementation will
natively accept input in the C<PTMD_STD> dialect, which isn't dependent on
any specific host language and should be easy enough to process, so it
should be considered the safest official Muldis D dialect to write in by
default, when you don't have a specific reason to use some other dialect.

See also the dialects
L<HDMD_Perl6_STD|Muldis::D::Dialect::HDMD_Perl6_STD> and
L<HDMD_Perl5_STD|Muldis::D::Dialect::HDMD_Perl5_STD>, which are derived
directly from C<PTMD_STD>, and represent possible Perl 6 and 5 concrete
syntax trees for it; in fact, most of the details in common with those
other dialects are described just in the current file, for all 3 dialects.

=head1 GENERAL STRUCTURE

A C<PTMD_STD> Muldis D code file consists just of a full or partial Muldis
D C<bootloader> routine definition, which begins with a language name
declaration, and otherwise is simply an ordered sequence of imperative
routine calls, where earlier routine calls are to system-defined
data-definition routines (their arguments are values to put in the system
catalog), and later ones are then to user-defined routines that the earlier
statements either loaded or defined.  This is conceptually what a
C<PTMD_STD> file is, and it can even be that literally, but C<PTMD_STD>
provides a canonical further abstraction which should be used when doing
data-definition.  And so you typically use syntax resembling routine and
type declarations in a general purpose programming language, where simply
declaring such an entity will cause it to be written into the system
catalog for subsequent use.

The grammar in this file is formatted as a hybrid between various EBNF
flavors and Perl 6 rules (see L<http://perlcabal.org/syn/S05.html> for
details on the latter) with further changes.  It is only meant to be
illustrative and human readable, and would need significant changes to
actually be a functional parser, which are different for each parser
toolkit.

The grammar consists mainly of named I<tokens> which define matching rules.
Loosely speaking, each parser match of a token corresponds to a capture
I<node> or node element in the concrete syntax tree resulting from the
parse; in practice, the parser may make various alterations to the match
when generating a node, such as adding guide keywords corresponding to the
token name, or by merging series of trivial tokens or doing escaped
character substitutions.  No explicit capture syntax such as parenthesis is
used in the grammar.

To help understand the grammar in this file, here are a few guidelines:  1.
The grammar is exactly the same as that of a Perl 6 rule except where these
guidelines state otherwise; this includes that square brackets mean
grouping not optionality, and that when multiple sub-pattern alternatives
match, the one that is the longest wins.  2. The grammar portion that
actually declares a token, that is what associates a token name with its
definition body, is formatted like EBNF, as C<< <footok> ::= ... >> rather
than the Perl 6 way like C<token footok { ... }> or C<rule footok { ... }>.
3. All non-quoted whitespace is not significant and just is formatting the
grammar itself; rather, whitespace rules in the grammar are spelled out
explicitly such as with C<\s*> (optional whitespace) and C<\s+> (mandatory
whitespace.

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

=head1 BOOTLOADER

Grammar:

    <bootloader> ::=
        <language_name>
        [\s+ [
              <value>
            | <depot>
            | <boot_stmt> ** \s+
        ]]?

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

Grammar:

    <language_name> ::=
        <ln_base_name>
        \s* ':' \s* <ln_base_authority>
        \s* ':' \s* <ln_base_version_number>
        \s* ':' \s* <ln_dialect>
        [\s* ':' \s* <ln_extensions>]?

    <ln_base_name> ::=
        Muldis_D

    <ln_base_authority> ::=
        <Name_payload>

    <ln_base_version_number> ::=
        <Name_payload>

    <ln_dialect> ::=
        PTMD_STD

    <ln_extensions> ::=
        <QTuple_payload>

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<PTMD_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 bareword
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 delimited
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 bareword character string
C<PTMD_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":PTMD_STD

    Muldis_D:"http://muldis.com":"1.2.3":PTMD_STD:{
        ...
    }

=head1 VALUE LITERALS AND SELECTORS

Grammar:

    <value> ::=
          <opaque_value_literal>
        | <coll_value_selector>

    <opaque_value_literal> ::=
          <Bool>
        | <Order>
        | <RatRoundMeth>
        | <Int>
        | <Rat>
        | <Blob>
        | <Text>
        | <Name>
        | <NameChain>
        | <DeclNameChain>
        | <Comment>
        | <Instant>
        | <Duration>
        | <UTCInstant>
        | <FloatInstant>
        | <UTCDuration>
        | <String>

    <coll_value_selector> ::=
          <QScalar>
        | <QTuple>
        | <Database>
        | <QRelation>
        | <QSet>
        | <QMaybe>
        | <QArray>
        | <QBag>
        | <RatRoundRule>

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

Unlike value selectors in general, which must be composed beneath a
C<depot> or C<boot_stmt> because they actually represent a Muldis D value
expression tree of a function or updater or type definition, a C<value>
node does I<not> represent an expression tree, but rather a value constant;
by definition, a C<value> can be completely evaluated at compile time.  A
C<bootloader> consisting directly of a C<value> is hence just a serialized
Muldis D value.

The PTMD_STD grammar subsection for value literals (having the root
grammar token C<value>) is completely self-defined and can be used in
isolation from the wider grammar as a Muldis D sub-language; for example, a
hosted-data Muldis D implementation may have an object representing a
Muldis D value, which is initialized using code written in that
sub-language.

Every grammar token, and corresponding capture node, representing a Muldis
D value literal is similarly formatted and has 1-3 elements; the following
pod section L</Value Literal Common Elements> describes the similarities
once for all of them, in terms of an alternate C<value> token definition
which is called C<x_value>.  And then the other pod sections specific to
each kind of value literal then just focus on describing their unique
aspects, namely their I<payloads>.

An C<opaque_value_literal> node represents a conceptually opaque Muldis D
value, such that every one of these values is defined with its own literal
syntax that is compact and doesn't look like a collection of other nodes;
this includes the basic numeric and string literals.

A C<coll_value_selector> node represents a conceptually transparent Muldis
D value, such that every one of these values is defined visibly in terms of
a collection of other nodes; this includes the basic tuple and relation
selectors.

=head2 Value Literal Common Elements

A I<generic context value literal> (or I<GCVL>) is a value literal that can
be properly interpreted in a context that is expecting I<a> value but has
no expectation that said value belongs to a specific data type; in the
general case, a GCVL includes explicit I<value kind> meta-data (such as,
"this is an C<Int>" or "this is a C<Name>"); but with a few specific data
types (see the C<value_kind> node description for details) that meta-data
may be omitted for brevity because the main literal has mutually uniquely
identifying characteristics.  For example, each element of a generic Muldis
D collection value, such as a member of an array or tuple, could
potentially have any type at all.  In contrast, a I<specific context value
literal> (or I<SCVL>) is a value literal that does not include explicit
value kind meta-data, even when the main literal doesn't have uniquely
identifying characteristics, because the context of its use supplies said
meta-data.  For example, in a tuple value literal it is assumed that a
value literal in an attribute name position must denote a C<Name>.  The
grammar token C<value>|C<x_value> denotes a GCVL, as do most short-named
grammar tokens, like C<Int> or C<Name>; in contrast, a grammar token
containing C<payload> denotes a SCVL, like C<Int_payload> or
C<Name_payload>.

Every GCVL has 1-3 elements, illustrated by this grammar:

    <x_value> ::=
        [
            <value_kind> \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <payload>

    <value_kind> ::=
          Bool
        | Order
        | RatRoundMeth
        | Int | NNInt | PInt
        | Rat | NNRat | PRat
        | Blob | OctetBlob
        | Text
        | Name
        | NameChain
        | DeclNameChain
        | Comment
        | Instant
        | Duration
        | UTC [Instant | DateTime | Date | Time]
        | Float [Instant | DateTime | Date | Time]
        | UTCDuration
        | String | BString | OString | UCPString
        | Q? Scalar
        | Q? Tuple
        | Database
        | Q? Relation
        | Q? Set
        | Q? [Maybe | Single]
        | Q? Array
        | Q? Bag
        | RatRoundRule

    <type_name> ::=
        <NameChain_payload>

    <payload> ::=
          <Bool_payload>
        | <Order_payload>
        | <RatRoundMeth_payload>
        | <Int_payload>
        | <Rat_payload>
        | <Blob_payload>
        | <Text_payload>
        | <Name_payload>
        | <NameChain_payload>
        | <DeclNameChain_payload>
        | <Comment_payload>
        | <Instant_payload>
        | <Duration_payload>
        | <UTCInstant_payload>
        | <FloatInstant_payload>
        | <UTCDuration_payload>
        | <String_payload>
        | <QScalar_payload>
        | <QTuple_payload>
        | <Database_payload>
        | <QRelation_payload>
        | <QSet_payload>
        | <QMaybe_payload>
        | <QArray_payload>
        | <QBag_payload>
        | <RatRoundRule_payload>

So a C<x_value>|C<value> node has 1-3 elements in general:

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

For all values of just the 8 data types [C<Bool>, C<Order>,
C<RatRoundMeth>, C<Int>, C<Rat>, C<Blob>, C<Text>, C<Comment>], the
C<value_kind> portion of a GCVL may be omitted for brevity, but the code
parser should still be able to infer it easily by examining the first few
characters of the C<payload>, which for each of said 8 data types has a
mutually uniquely identifying format, which is also distinct from all
possible C<value_kind>.  Note that omission of C<value_kind> is only
allowed when the GCVL doesn't include a C<type_name> element.

For just these certain special values of other data types, the same option
of omitting the C<value_kind> (and C<type_name>) applies: C<Maybe:nothing>.

=item C<type_name>

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

How a Muldis D parser treats a C<value> node with a C<type_name> element
depends on the wider context.  In the general case where the C<value> is an
C<expr> beneath the context of a C<depot> or C<boot_stmt> node, the
C<value> is treated as if it had an extra parent C<func_invo> node
that invokes the C<treated> function and whose 2 argument nodes are as
follows: C<topic> gets the C<value> without the C<type_name> element, and
C<as> gets the C<type_name> element.  This means that in general the
C<type_name> assertion is done at runtime.  In the common special case
where both C<value> is an C<opaque_value_literal> and C<type_name> refers
to a system-defined type, then the C<type_name> assertion is done at
compile time, and then the C<type_name> element is simply eliminated, so
the C<value> ends up simply as itself with no new C<func_invo> parent.

=item C<payload>

This is mandatory for all C<value>.

=back

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

=head1 OPAQUE VALUE LITERALS

=head2 Boolean Literals

Grammar:

    <Bool> ::=
        [Bool \s* ':' \s*]?
        <Bool_payload>

    <Bool_payload> ::=
        false | true

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 C<Bool_payload>
is a bareword character string formatted as per a C<Name> SCVL, and it maps
directly to the C<name> possrep of the C<Bool> type.

Examples:

    Bool:true

    false

=head2 Order-Determination Literals

Grammar:

    <Order> ::=
        [Order \s* ':' \s*]?
        <Order_payload>

    <Order_payload> ::=
        increase | same | decrease

An 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
C<Order_payload> is a bareword character string formatted as per a C<Name>
SCVL, and it maps directly to the C<name> possrep of the C<Order> type.

Examples:

    Order:same

    decrease

=head2 Rational Rounding Method Literals

Grammar:

    <RatRoundMeth> ::=
        [
            RatRoundMeth \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <RatRoundMeth_payload>

    <RatRoundMeth_payload> ::=
          half_down | half_up
        | half_even
        | to_floor | to_ceiling
        | to_zero | to_inf

A C<RatRoundMeth> node represents a rational rounding method.  It is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.RatRoundMeth> value as
follows:  The C<RatRoundMeth_payload> is a bareword character string
formatted as per a C<Name> SCVL, and it maps directly to the only possrep
of the C<RatRoundMeth> type.

Examples:

    RatRoundMeth:half_up

    to_zero

=head2 General Purpose Integer Numeric Literals

Grammar:

    <Int> ::=
        [
            [Int | NNInt | PInt] \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <Int_payload>

    <Int_payload> ::=
          <num_max_col_val> \s* ';' \s* <int_body>
        | <d_int_body>

    <num_max_col_val> ::=
        <pint_head>

    <int_body> ::=
        [0 | \-?<pint_body>]

    <pint_body> ::=
        <pint_head> <pint_tail>?

    <pint_head> ::=
        <[ 1..9 A..Z ]>

    <pint_tail> ::=
        [[_?<[ 0..9 A..Z ]>+]+] ** [\s* '~' \s*]

    <d_int_body> ::=
        [0 | \-?<d_pint_body>]

    <d_pint_body> ::=
        <d_pint_head> <d_pint_tail>?

    <d_pint_head> ::=
        <[ 1..9 ]>

    <d_pint_tail> ::=
        [[_?<[ 0..9 ]>+]+] ** [\s* '~' \s*]

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:

If the C<Int_payload> is composed of a C<num_max_col_val> plus C<int_body>,
then the C<int_body> is interpreted as a base-I<N> integer where I<N> might
be between 2 and 36, and the C<num_max_col_val> says which possible value
of I<N> to use.  Assuming all C<int_body> column values are between zero
and I<N>-minus-one, the C<num_max_col_val> contains that I<N>-minus-one.
So to specify, eg, bases [2,8,10,16], use C<num_max_col_val> of [1,7,9,F].

If the C<Int_payload> is a C<d_int_body>, then it is interpreted as a base
10 integer.

Fundamentally the I<body> part of an C<Int> node consists of a string of
digits and uppercased (but not lowercased) letters, where each digit
(C<0..9>) represents its own number and each letter (C<A..Z>) represents a
number in [10..35].  A I<body> may optionally contain underscore characters
(C<_>), which exist just to help with visual formatting, such as for
C<10_000_000>, and these are ignored/stripped by the parser.  A I<body> may
optionally be split into 1..N segments where each segment is separated by a
tilde token (C<~>); this segmenting ability is provided to support code
that contains very long numeric literals while still being well formatted
(no extra long lines); the tilde tokens are also ignored/stripped by the
parser, and the I<body> is interpreted as if all its alphanumeric
characters were contiguous.

If the C<value_kind> of a C<value> node is C<NNInt> or C<PInt> rather than
C<Int>, then the C<value> node is interpreted simply as an C<Int> node
whose C<type_name> is C<NNInt> or C<PInt>, and the allowed I<body> is
appropriately further restricted.

Examples:

    Int:1;11001001 # binary #

    7;0 # octal #

    7;644 # octal #

    -34 # decimal #

    42 # decimal #

    F;DEADBEEF # hexadecimal #

    Z;-HELLOWORLD # base-36 #

    3;301 # base-4 #

    B;A09B # base-12 #

=head2 General Purpose Rational Numeric Literals

Grammar:

    <Rat> ::=
        [
            [Rat | NNRat | PRat] \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <Rat_payload>

    <Rat_payload> ::=
          <num_max_col_val> \s* ';' \s* <rat_body>
        | <d_rat_body>

    <rat_body> ::=
          <int_body>\.<pint_tail>
        | <int_body> \s* \/ \s* <pint_body>
        | <int_body> \s* \* \s* <pint_body> \s* \^ \s* <int_body>

    <d_rat_body> ::=
          <d_int_body>\.<d_pint_tail>
        | <d_int_body> \s* \/ \s* <d_pint_body>
        | <d_int_body> \s* \* \s* <d_pint_body> \s* \^ \s* <d_int_body>

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:

Fundamentally a C<Rat> node is formatted and interpreted like an C<Int>
node, and any similarities won't be repeated here.  The differences of
interpreting a C<Rat_payload> being composed of a C<num_max_col_val> plus
C<rat_body> versus the C<Rat_payload> being a C<d_rat_body> are as per the
corresponding differences of interpreting an C<Int_payload>.  Also
interpreting a C<NNRat> or C<PRat> is as per a C<NNInt> or C<PInt>.

If the I<body> part of a C<Rat> node contains a radix point (C<.>), then it
is interpreted as is usual for a programming language with such a literal.

If the I<body> part of a C<Rat> node contains a solidus (C</>), then the
rational's value is interpreted as the leading integer (a numerator)
divided by the trailing positive integer (a denominator); that is, the two
integers collectively map to the C<ratio> possrep of the C<Rat> type.

If the I<body> part of a C<Rat> node contains a asterisk (C<*>) plus a
circumflex accent (C<^>), then the rational's value is interpreted as the
leading integer (a mantissa) multiplied by the result of the middle
positive integer (a radix) taken to the power of the trailing integer (an
exponent); that is, the three integers collectively map to the C<float>
possrep of the C<Rat> type.

Examples:

    Rat:1;-1.1

    -1.5 # same val as prev #

    3.14159

    A;0.0

    F;DEADBEEF.FACE

    Z;0.000AZE

    Rat:6;500001/1000

    B;A09B/A

    Rat:1;1011101101*10^-11011

    45207196*10^37

    1/43

    314159*10^-5

=head2 General Purpose Binary String Literals

Grammar:

    <Blob> ::=
        [
            [Blob | OctetBlob] \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <Blob_payload>

    <Blob_payload> ::=
        <blob_max_col_val> \s* ';' \s* <blob_body>

    <blob_max_col_val> ::=
        <[137F]>

    <blob_body> ::=
        [
            <[']>
                <[ 0..9 A..F ]>*
            <[']>
        ] ** [\s* '~' \s*]

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:  Fundamentally
the I<body> part of a C<Blob> node consists of a delimited string of digits
and uppercased (but not lowercased) letters, where each digit (C<0..9>)
represents its own number and each letter (C<A..F>) represents a number in
[10..15]; this string is qualified with a C<blob_max_col_val> character
(C<[137F]>), similarly to how an C<int_body> is qualified by a
C<num_max_col_val>.  Each character of the delimited string specifies a
sequence of one of [1,2,3,4] bits, depending on whether C<blob_max_col_val>
is [1,3,7,F].  If the C<value_kind> of a C<value> node is C<OctetBlob>
rather than C<Blob>, then the C<value> node is interpreted simply as an
C<Blob> node whose C<type_name> is C<OctetBlob>, and the delimited string
is appropriately further restricted.

Examples:

    Blob:1;'00101110100010' # binary #

    3;''

    F;'A705E' # hexadecimal #

    7;'523504376'

=head2 General Purpose Character String Literals

Grammar:

    <Text> ::=
        [
            Text \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <Text_payload>

    <Text_payload> ::=
        [
            <[']>
                [<-[\\\'\t\n\f\r]> | <escaped_char>]*
            <[']>
        ] ** [\s* '~' \s*]

    <escaped_char> ::=
          '\b' | '\a' | '\q' | '\h'
        | '\s'
        | '\t' | '\n' | '\f' | '\r'
        | '\c<' [
              [<[ A..Z ]>+] ** ' '
            | [0 | <[ 1..9 ]> <[ 0..9 ]>*]
            | <[ 1..9 A..Z ]> ';' [0 | <[ 1..9 A..Z ]> <[ 0..9 A..Z ]>*]
          ] '>'

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

The C<Text_payload> is interpreted generally as is usual for a programming
language with such a delimited character string literal.

A C<Text_payload> may optionally be split into 1..N segments where each
segment is delimited by apostrophes/single-quotes (C<'>) and separated by a
tilde token (C<~>); this segmenting ability is provided to support code
that contains long string literals while still being well formatted (no
extra long lines); the tilde tokens and adjoining string delimiters are
ignored/stripped by the parser, and the C<Text_payload> is interpreted as
if it just consisted of a single delimited string.

All Muldis D delimited character string literals (generally the 3 C<Text>,
C<Name>, C<Comment>) may contain some characters denoted with escape
sequences rather than literally.  The Muldis D parser would substitute the
escape sequences with the characters they represent, so the resulting
character string values don't contain those escape sequences.  Currently
there are 2 classes of escape sequences, called I<simple> and I<complex>.

The meanings of the simple escape sequences are:

    Esc | Unicode   | Unicode         | Chr | Literal character used
    Seq | Codepoint | Character Name  | Lit | for when not escaped
    ----+-----------+-----------------+-----+------------------------------
    \b  | F;5C      | REVERSE SOLIDUS | \   | esc seq lead (aka backslash)
    \a  | F;27      | APOSTROPHE      | '   | delim Text literals
    \q  | F;22      | QUOTATION MARK  | "   | delim quoted Name literals
    \h  | F;23      | NUMBER SIGN     | #   | delim Comment lit (aka hash)
    \s  | F;20      | SPACE           |     | space char
    \t  | F;9       | CHAR... TAB...  |     | control char horizontal tab
    \n  | F;A       | LINE FEED (LF)  |     | ctrl char line feed / newline
    \f  | F;C       | FORM FEED (FF)  |     | control char form feed
    \r  | F;D       | CARR. RET. (CR) |     | control char carriage return

One design decision of PTMD_STD that is distinct from typical other
languages is that an escape sequence for any character used as a delimiter
I<never> contains that literal character.  For example, while in SQL or
Perl character strings delimited by C<'>, they typically escape literal
apostrophes/single-quotes as C<''> or C<\'>; while this is unambiguous, the
task of parsing such code is considerably more difficult than it could be.
In contrast, while in PTMD_STD character strings delimited by C<'>, a
literal of the same is escaped with C<\a>; so parsing such code is an order
of magnitude easier because the parser doesn't have to understand the
internals of any character string literal in order to separate out the
character string from its surrounding code.

Another design decision of PTMD_STD that is distinct at least from Perl is
that non-"space" whitespace characters in character string literals must
never appear literally, but must instead be denoted with escape sequences.
The main reason for this is to ensure that the actual values being selected
by the string literals were not variable per the kind of linebreaks used to
format the Muldis D source code itself.

There is currently just one complex escape sequence, of the format C<<
\c<...> >>, that supports specifying characters in terms of their Unicode
abstract codepoint name or number.  If the C<...> consists of just
uppercased (not lowercased) letters and the space character, then the
C<...> is interpreted as a Unicode character name.  If the C<...> looks
like an C<Int_payload>, sans that underscores and tilde segmentation aren't
allowed here, then the C<...> is interpreted as a Unicode abstract
codepoint number.  One reason for this feature is to empower more elegant
passing of Unicode-savvy PTMD_STD source code through a communications
channel that is more limited, such as to 7-bit ASCII.

Examples:

    Text:'Ceres'

    'サンプル'

    ''

    'Perl'

    '\c<LATIN SMALL LETTER OU>\c<F;263A>\c<65>'

=head2 DBMS Entity Name Literals

Grammar:

    <Name> ::=
        Name \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <Name_payload>

    <Name_payload> ::=
        <nonquoted_name_str> | <quoted_name_str>

    <nonquoted_name_str> ::=
        <[ a..z A..Z _ ]><[ a..z A..Z 0..9 _ - ]>*

    <quoted_name_str> ::=
        [
            <["]>
                [<-[\\\"\t\n\f\r]> | <escaped_char>]*
            <["]>
        ] ** [\s* '~' \s*]

    <NameChain> ::=
        NameChain \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <NameChain_payload>

    <NameChain_payload> ::=
        <Name_payload> ** [\s* '.' \s*]

    <DeclNameChain> ::=
        DeclNameChain \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <DeclNameChain_payload>

    <DeclNameChain_payload> ::=
        <NameChain_payload> | '[]'

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 as follows:

Fundamentally a C<Name> node is formatted and interpreted like a C<Text>
node, and any similarities won't be repeated here.  Unlike a
C<Text_payload> literal which must always be delimited, a C<Name_payload>
has 2 variants, one delimited (C<quoted_name_str>) and one not
(C<nonquoted_name_str>).  The delimited C<Name_payload> form differs from
C<Text_payload> only in that each string segment is delimited by
double-quotes rather than apostrophes/single-quotes.

A C<nonquoted_name_str> is composed of a single alphabetic or underscore
character followed by zero or more characters that are each alphanumeric or
underscore or hyphen.  It can not be segmented, so you will have to use the
C<quoted_name_str> equivalent if you want a segmented string.  I<The
definitions of alphabetic and numeric should include appropriate Unicode
characters, but at the moment this isn't reflected in the grammar; TODO:
fix this.>

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.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Cat.NameChain> value as follows:  A
C<NameChain_payload> consists of a sequence of 1 or more C<Name_payload>
where the elements of the sequence are separated by period (C<.>) tokens;
each element of the sequence, in order, defines an element of the C<array>
possrep's attribute of the result C<NameChain> value.

Now, strictly speaking, a Muldis D C<NameChain> value is supposed to have
at least 2 elements in its sequence, and the first element of any sequence
must be one of these 9 C<Name> values, which is a top-level namespace:
C<sys>, C<mnt>, C<tpc>, C<fed>, C<dep>, C<sdp>, C<pkg>, C<inn>, C<lex>.
(Actually, C<type> is a 10th option, but that will be treated separately in
this discussion.)  In the general case, a C<NameChain_payload> must be
written out in full, so it is completely unambiguous (and is clearly
self-documenting), and it is always the case that a C<NameChain> value in
the system catalog is written out in full.  But the PTMD_STD grammar also
has a few commonly used special cases where a C<NameChain_payload> may be a
much shorter substring of its complete version, such that a simple parser,
with no knowledge of any user-defined entities besides said shorter
C<NameChain_payload> in isolation, can still unambiguously resolve it to
its complete version; exploiting these typically makes for code that is a
lot less verbose, and much easier to write or read.

The first special case involves any context where a type or routine is
being referenced by name.  In such a context, when the referenced entity is
a standard system-defined type or routine, programmers may omit any number
of consecutive leading chain elements from such a C<NameChain_payload>, so
long as the remaining unqualified chain is distinct among all standard
system-defined (C<sys.std>-prefix) DBMS entities (but that as an exception,
a non-distinct abbreviation is allowed iff exactly 1 of the candidate
entities is in the language core, C<sys.std.Core>-prefix, in which case
that 1 is unambiguously the entity that is resolved to).  This feature has
no effect on the namespace prefixes like C<type> or C<tuple_from> or
C<array_of>; one still writes those as normal prepended to the otherwise
shortened chains.  When a C<NameChain_payload>, whose context indicates it
is a type or routine invocation, is encountered by the parser, and its
existing first chain element isn't one of the other 8 top-level namespaces,
then the parser will assume it is an unqualified chain in the C<sys>
namespace and lookup the best / only match from the known C<sys.std> DBMS
entities, to resolve to.  So for example, one can just write C<Int> rather
than C<sys.std.Core.Type.Int>, C<is_identical> rather than
C<sys.std.Core.Universal.is_identical>, C<QTuple.attr> rather than
C<sys.std.Core.QTuple.attr>, C<min> rather than C<sys.std.Ordered.min>,
C<array_of.Rat> rather than C<array_of.sys.std.Core.Type.Rat>, and so on.
In fact, the Muldis D spec itself uses such abbreviations frequently.

The second special case involves any context where a value expression
(including a parameter) or a variable is being referenced by name, such as
with an C<expr_name> node.  In such a context, any leading C<lex> element
may be omitted; when a C<NameChain_payload>, whose context indicates it is
a type or routine invocation, is encountered by the parser, and its
existing first chain element isn't one of the other 8 top-level namespaces,
then the parser will assume it is an unqualified chain in the C<lex>
namespace and will prepend a C<lex> element to it.  So for example a
C<$foo> is treated as being C<$lex.foo> while a C<$dep.data.foo> is treated
as itself.

The third special case involves any context where a type is being
referenced using the C<type> namespace prefix feature described in
L<Muldis::D::Basics/Referencing Data Types>.  In such a context, when the
namespace prefix contains either of the optional chain elements
C<[|quasi_][tuple|relation]_from> or
C<[|quasi_][set|maybe|single|array|bag]_of>, programmers may omit the
single prefix-leading C<type> chain element.  So for example, one can just
write C<array_of.Rat> rather than C<type.array_of.Rat>, or
C<tuple_from.var.lex.myrelvar> rather than
C<type.tuple_from.var.lex.myrelvar>.  This third special case is completely
orthogonal to which of the 9 normal top-level namespaces is in use
(implicitly or explicitly) by the chain being prefixed, and works for all 9
of them.

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, and a zero-element chain is
represented by the special C<DeclNameChain_payload> syntax of C<[]>.

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

Grammar:

    <Comment> ::=
        [
            Comment \s* ':' \s*
            [<type_name> \s* ':' \s*]?
        ]?
        <Comment_payload>

    <Comment_payload> ::=
        [
            '#' ' '*
                [<-[\\\#\t\n\f\r]> | <escaped_char>]*
            ' '* '#'
        ] ** \s*

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 as
follows:

Fundamentally a C<Name> node is formatted and interpreted like a C<Text>
node, and any similarities won't be repeated here.  The C<Comment_payload>
differs from C<Text_payload> only in that each string segment is delimited
by number-signs/hash-marks rather than apostrophes/single-quotes, and also
that:

Note that any leading or trailing space (F;20) characters inside the C<#>
delimiters of a C<Comment_payload> are also part of the delimiters, and are
not part of the selected C<Comment> value; if you want to denote a
C<Comment> value with leading or trailing space chars, you must write those
space chars in an escaped form such as with C<\s>.

Examples:

    Comment:# This does something. #

    # So does this. #

=head2 TAI Temporal Literals

Grammar:

    <Instant> ::=
        Instant \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <Instant_payload>

    <Instant_payload> ::=
        <Rat_payload>

    <Duration> ::=
        Duration \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <Duration_payload>

    <Duration_payload> ::=
        <Rat_payload>

An C<Instant> node represents a single point in time which is specified in
terms of 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 as follows:  An C<Instant_payload> is
formatted and interpreted in the same way as a C<Rat_payload>.

A C<Duration> node represents a single amount of time (the difference
between two instants) which is specified in terms of 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 as follows:  A C<Duration_payload> is
formatted and interpreted in the same way as a C<Rat_payload>.

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

Grammar:

    <UTCInstant> ::=
        UTC [Instant | DateTime | Date | Time] \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <UTCInstant_payload>

    <UTCInstant_payload> ::=
        <UTCDuration_payload>

    <FloatInstant> ::=
        Float [Instant | DateTime | Date | Time] \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <FloatInstant_payload>

    <FloatInstant_payload> ::=
        <UTCDuration_payload>

    <UTCDuration> ::=
        UTCDuration \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <UTCDuration_payload>

    <UTCDuration_payload> ::=
          <num_max_col_val> \s* ';' \s* <utc_duration_body>
        | <d_utc_duration_body>

    <utc_duration_body> ::=
        '[' \s*
            [<int_body>? [\s* ',' \s*]] ** 5
            \s* ',' \s* <rat_body>?
        \s* ']'

    <d_utc_duration_body> ::=
        '[' \s*
            [<d_int_body>? [\s* ',' \s*]] ** 5
            \s* ',' \s* <d_rat_body>?
        \s* ']'

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:

A C<UTCInstant_payload> consists mainly of a bracket-delimited sequence of
6 comma-separated elements, where each element is either a valid numeric
literal or is completely absent.  The 6 elements correspond in order to
the 6 attributes: C<year>, C<month> C<day>, C<hour>, C<minute>, C<second>.
For each element that is absent 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 I<body> part of an
C<Int> node; for the 6th element, when it is defined, it must qualify as a
valid I<body> part of a C<Rat> node.

Fundamentally each C<UTCInstant> node element is formatted and interpreted
like an C<Int> or C<Rat> node, and any similarities won't be repeated here.

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.

If the C<value_kind> of a C<value> node is C<UTCDateTime> or C<UTCDate> or
C<UTCTime> rather than C<UTCInstant>, then the C<value> node is interpreted
simply as a C<UTCInstant> node whose C<type_name> is C<UTCDateTime> or
C<UTCDate> or C<UTCTime>, and the allowed I<body> is appropriately further
restricted.

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:

A C<UTCDuration_payload> consists mainly of a bracket-delimited sequence of
6 comma-separated elements, where each element is either a valid numeric
literal or is completely absent.  The 6 elements correspond in order to the
6 attributes: C<years>, C<months> C<days>, C<hours>, C<minutes>,
C<seconds>.  For each element that is absent 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
I<body> part of an C<Int> node; for the 6th element, when it is defined, it
must qualify as a valid I<body> part of a C<Rat> node.

Mostly a C<UTCDuration> is formatted and interpreted like a C<UTCInstant>
node, and any similarities won't be repeated here.

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,16,,,] # a UTCDate #

    UTCInstant:[,,,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

Grammar:

    <String> ::=
        [String | BString | OString | UCPString] \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <String_payload>

    <String_payload> ::=
          <num_max_col_val> \s* ';' \s* <string_body>
        | <d_string_body>

    <string_body> ::=
        '[' \s*
            [<int_body> ** [\s* ',' \s*]]?
        \s* ']'

    <d_string_body> ::=
        '[' \s*
            [<d_int_body> ** [\s* ',' \s*]]?
        \s* ']'

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:  A
C<String_payload> consists mainly of a bracket-delimited sequence of 0..N
elements, where each element must qualify as a valid I<body> part of a
C<Int> node, and the new C<String> is conceptually that sequence of
integers.  Fundamentally each C<String> node element is formatted and
interpreted like an C<Int> node, and any similarities won't be repeated
here.

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 (members of C<coll_value_selector> etc), 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

Grammar:

    <QScalar> ::=
        Q? Scalar \s* ':' \s*
        <type_name> \s* ':' \s*
        <QScalar_payload>

    <QScalar_payload> ::=
        <possrep_name> \s* ';' \s* <possrep_attrs>

    <possrep_name> ::=
        <Name_payload>

    <possrep_attrs> ::=
        <QTuple_payload>

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> and whose attributes
are defined by the C<QScalar_payload>.  The C<possrep_attrs> is interpreted
specifically as attributes of the declared type's possrep which is
specified by the C<possrep_name>.  Each name+expr pair of the
C<possrep_attrs> defines a named possrep attribute of the new quasi-scalar;
the pair's name and expr specify, respectively, the possrep attribute name,
and the possrep attribute value.  If the C<value_kind> of a C<value> node
is C<Scalar> rather than C<QScalar>, then the C<value> node is interpreted
simply as an C<QScalar> node that is appropriately further restricted; the
C<type_name> must name a C<Scalar> subtype, and the C<possrep_attrs> must
not specify any quasi- typed attribute values.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.ScaPRSelExprNodeSet>, a tuple of which is what in
general a C<QScalar> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

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

Grammar:

    <QTuple> ::=
        Q? Tuple \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QTuple_payload>

    <QTuple_payload> ::=
        '{' \s*
            [[<Name_payload> \s* '=>' \s* <expr>] ** [\s* ',' \s*]]?
        \s* '}'

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
C<QTuple_payload>.  Each name+expr pair of the C<QTuple_payload> defines a
named attribute of the new quasi-tuple; the pair's name and expr specify,
respectively, the attribute name, and the attribute value.  If the
C<value_kind> of a C<value> node is C<Tuple> rather than C<QTuple>, then
the C<value> node is interpreted simply as an C<QTuple> node that is
appropriately further restricted; the C<QTuple_payload> must not specify
any quasi- typed attribute values.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.TupSelExprNodeSet>, a tuple of which is what in
general a C<QTuple> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

Examples:

    Tuple:{}

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

    Tuple:{
        name => 'Michelle',
        age  => 17
    }

=head2 Database Selectors

Grammar:

    <Database> ::=
        Database \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <Database_payload>

    <Database_payload> ::=
        <QTuple_payload>

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
C<Database_payload>.  Each name+relation pair of the C<Database_payload>
defines a named attribute of the new 'database'; the pair's name and
relation specify, respectively, the attribute name, and the attribute
value.  While this grammar mentions that C<Database_payload> is a
C<QTuple_payload>, it is in fact significantly further restricted, such
that every attribute value of the C<Database> can only be a relation.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.TupSelExprNodeSet>, a tuple of which is what in
general a C<Database> node distills to same as when C<QTuple> does.

=head2 Relation Selectors

Grammar:

    <QRelation> ::=
        Q? Relation \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QRelation_payload>

    <QRelation_payload> ::=
          <r_empty_qbody_payload>
        | <r_nonordered_qattr_payload>
        | <r_ordered_qattr_payload>

    <r_empty_qbody_payload> ::=
        '{' \s*
            [<Name_payload> ** [\s* ',' \s*]]?
        \s* '}'

    <r_nonordered_qattr_payload> ::=
        '{' \s*
            [<QTuple_payload> ** [\s* ',' \s*]]?
        \s* '}'

    <r_ordered_qattr_payload> ::=
        '[' \s*
            [<Name_payload> ** [\s* ',' \s*]]?
        \s* ']'
        \s* ';' \s*
        '{' \s*
            [<ordered_qtuple_qattrs> ** [\s* ',' \s*]]?
        \s* '}'

    <ordered_qtuple_qattrs> ::=
        '[' \s*
            [<expr> ** [\s* ',' \s*]]?
        \s* ']'

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 C<QRelation_payload>, which is interpreted as follows:

Iff the C<QRelation_payload> is composed of just a
C<nonord_list_[open|close]> pair with zero elements between them, then it
defines the only relation value having zero attributes and zero tuples.

Iff the C<QRelation_payload> is a C<r_empty_qbody_payload> with at least
one C<Name_payload> element, then it defines the attribute names of a
relation having zero tuples.

Iff the C<QRelation_payload> is a C<r_nonordered_qattr_payload> with at
least one <QTuple_payload> element, then each element defines a quasi-tuple
of the new quasi-relation; every <QTuple_payload> must define a quasi-tuple
of the same degree and have the same attribute names as its sibling
<QTuple_payload>; these are the degree and attribute names of the
quasi-relation as a whole, which is its heading for the current purposes.

Iff the C<QRelation_payload> is a C<r_ordered_qattr_payload>, then:  The
new quasi-relation value's attribute names are defined by the
C<Name_payload> elements, and the relation body's tuples' attribute values
are defined by the C<ordered_qtuple_qattrs> elements.  This format is meant
to be the most compact of the generic relation selector 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 all of the
C<ordered_qtuple_attrs> elements must appear in the same order as their
corresponding attribute names appear in the collection of C<Name_payload>
elements, as the names and values in the relation literal are matched up by
ordinal position here.

If the C<value_kind> of a C<value> node is C<Relation> rather than
C<QRelation>, then the C<value> node is interpreted simply as an
C<QRelation> node that is appropriately further restricted; the
C<QRelation_payload> must not specify any quasi- typed attribute values.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.RelSelExprNodeSet>, a tuple of which is what in
general a C<QRelation> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

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 => true
        }
    }  # 3 attrs + 1 tuple #

    Relation:fed.lib.the_db.gene.Person:[ name, age ];{
        [ 'Michelle', 17 ]
    }  # 2 attrs + 1 tuple #

=head2 Set Selectors

Grammar:

    <QSet> ::=
        Q? Set \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QSet_payload>

    <QSet_payload> ::=
        '{' \s*
            [<expr> ** [\s* ',' \s*]]?
        \s* '}'

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 C<QSet_payload>.  Each C<expr> of the
C<QSet_payload> defines a unary quasi-tuple of the new quasi-set; each
C<expr> defines the C<value> attribute of the quasi-tuple.  If the
C<value_kind> of a C<value> node is C<Set> rather than C<QSet>, then the
C<value> node is further restricted.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.SetSelExprNodeSet>, a tuple of which is what in
general a C<QSet> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

Examples:

    Set:fed.lib.the_db.account.Country_Names:{
        'Canada',
        'Spain',
        'Jordan',
        'Thailand'
    }

    Set:{
        3,
        16,
        85
    }

=head2 Maybe Selectors

Grammar:

    <QMaybe> ::=
        Q? [Maybe | Single] \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QMaybe_payload>

    <QMaybe_payload> ::=
        <maybe_list> | <maybe_nothing>

    <maybe_list> ::=
        '{' \s* <expr> \s* '}'

    <maybe_nothing> ::=
        nothing

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 whose elements are defined by the
C<QMaybe_payload>.

Iff the C<QMaybe_payload> is a C<maybe_list> then it defines either zero or
one C<expr>; in the case of one, the C<expr> defines the unary quasi-tuple
of the new quasi-maybe, which is a quasi-'single'; the C<expr> defines the
C<value> attribute of the quasi-tuple.  If the C<value_kind> of a C<value>
node is C<Maybe> or C<[Q|]Single> rather than C<QMaybe>, then the C<value>
node is further restricted, either to not having any quasi- resulting
C<expr> or to having exactly one C<expr>, as appropriate.

Iff the C<QMaybe_payload> is a C<maybe_nothing> then the C<QMaybe> node is
interpreted as the special value C<Maybe:nothing>, aka C<nothing>, which is
the only C<QMaybe> value with zero elements.  Note that this is just an
alternative syntax, as C<set_expr_list> can select that value too.  As a
further restriction, the C<value_kind> must be just one of C<[Q|]Maybe>
when the C<QMaybe_payload> is a C<maybe_nothing>.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.SetSelExprNodeSet>, a tuple of which is what in
general a C<QMaybe> node distills to same as when C<QSet> does.

Examples:

    Maybe:{ 'I know this one!' }

    Maybe:nothing

    nothing

=head2 Array Selectors

Grammar:

    <QArray> ::=
        Q? Array \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QArray_payload>

    <QArray_payload> ::=
        '[' \s*
            [<expr> ** [\s* ',' \s*]]?
        \s* ']'

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
C<QArray_payload>.  Each C<expr> of the C<QArray_payload> defines a binary
quasi-tuple of the new sequence; the C<expr> defines the C<value> attribute
of the quasi-tuple, and the C<index> attribute of the quasi-tuple is
generated such that the first C<expr> gets an C<index> of zero and
subsequent ones get consecutive higher integer values.  If the
C<value_kind> of a C<value> node is C<Array> rather than C<QArray>, then
the C<value> node is further restricted.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.ArySelExprNodeSet>, a tuple of which is what in
general a C<QArray> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

Examples:

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

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

=head2 Bag Selectors

Grammar:

    <QBag> ::=
        Q? Bag \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <QBag_payload>

    <QBag_payload> ::=
          <qbag_payload_counted_values>
        | <qbag_payload_repeated_values>

    <qbag_payload_counted_values> ::=
        '{' \s*
            [[<expr> \s* '=>' \s* <count>] ** [\s* ',' \s*]]?
        \s* '}'

    <count> ::=
          <num_max_col_val> \s* ';' \s* <pint_body>
        | <d_pint_body>

    <qbag_payload_repeated_values> ::=
        '{' \s*
            [<expr> ** [\s* ',' \s*]]?
        \s* '}'

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 C<QBag_payload>, which is interpreted as
follows:

Iff the C<QBag_payload> is composed of just a C<nonord_list_[open|close]>
pair with zero elements between them, then it defines the only bag value
having zero elements.

Iff the C<QBag_payload> is a C<qbag_payload_counted_values> with at least
one C<expr>/C<count>-pair element, then each pair defines a binary
quasi-tuple of the new quasi-bag; the C<expr> defines the C<value>
attribute of the quasi-tuple, and the C<count> defines the C<count>
attribute.

Iff the C<QBag_payload> is a C<qbag_payload_repeated_values> with at least
one <expr> element, then each C<expr> contributes to a binary quasi-tuple
of the new quasi-bag; the C<expr> defines the C<value> attribute of the
quasi-tuple.  The quasi-bag has 1 quasi-tuple for every distinct (after
normalization or evaluation) C<expr> and C<expr>-derived value in the
C<QBag_payload>, and the C<count> attribute of that quasi-tuple says how
many instances of said C<value> there were.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.BagSelExprNodeSet>, a tuple of which is what in
general a C<QBag> node distills to when it is beneath the context of a
C<depot> or C<boot_stmt> node, as it describes some semantics.

Further concerning C<qbag_payload_counted_values>, because of how
C<BagSelExprNodeSet> is defined, a C<count> has to be a compile time
constant, since an integer is stored in the system catalog rather than the
name of an expression node like with C<value>; if you actually want the
q/bag value being selected at runtime to have runtime-determined C<count>
values, then you must use a C<Relation> node rather than a C<Bag> node.

Examples:

    Bag:fed.lib.the_db.inventory.Fruit:{
        'Apple'  => 500,
        'Orange' => 300,
        'Banana' => 400
    }

    Bag:{
        'Foo',
        'Quux',
        'Foo',
        'Bar',
        'Baz',
        'Baz'
    }

=head2 Rational Rounding Rule Selectors

Grammar:

    <RatRoundRule> ::=
        RatRoundRule \s* ':' \s*
        [<type_name> \s* ':' \s*]?
        <RatRoundRule_payload>

    <RatRoundRule_payload> ::=
        '[' \s*
            <radix> \s* ',' \s* <min_exp> \s* ',' \s* <round_meth>
        \s* ']'

    <radix> ::=
        <expr>

    <min_exp> ::=
        <expr>

    <round_meth> ::=
        <expr>

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> consists mainly of
a bracket-delimited sequence of 3 comma-separated 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.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.TupSelExprNodeSet>, a tuple of which is what in
general a C<RatRoundRule> node distills to same as when C<QTuple> does.

Examples:

    RatRoundRule:[10,-2,half_even]

    RatRoundRule:[2,-7,to_zero]

=head1 GENERIC VALUE EXPRESSIONS

Grammar:

    <expr> ::=
          <expr_name>
        | <named_expr>
        | <opaque_value_literal>
        | <coll_value_selector>
        | <func_invo>
        | <if_else_expr>
        | <given_when_def_expr>
        | <lib_entity_ref_selector>
        | <func_invo_alt_syntax>

    <expr_name> ::=
        <data_sigil> <NameChain_payload>

    <data_sigil> ::=
        '$'

    <named_expr> ::=
        <decl_expr_name> \s* <infix_bind_op> \s* <expr>

    <decl_expr_name> ::=
        <data_sigil> <Name_payload>

    <infix_bind_op> ::=
        '='

An C<expr> node is the general case of a Muldis D value expression tree
(which normally denotes a Muldis D value selector), which must be composed
beneath a C<depot> or C<boot_stmt>, or specifically into a function or
updater or type or constraint (etc) definition, because in the general case
an C<expr> can I<not> be completely evaluated at compile time.

An C<expr> node is a proper superset of a C<value> node, and any
occurrences of C<expr> nodes in this document may optionally be substituted
with C<value> nodes on a per-instance basis.

An C<expr> node in the PTMD_STD grammar corresponds directly to a tuple of
an attribute of a value of the catalog data type
C<sys.std.Core.Type.Cat.ExprNodeSet>, which is how a value expression node
is actually represented in Muldis D's nonsugared form, which is as a
component of the system catalog.  Or more specifically, an entire tree of
PTMD_STD C<expr> nodes corresponds to a set of said attribute values, one
attribute value per C<expr> node.  In the nonsugared form, every C<expr>
node has an explicitly designated name, as per a PTMD_STD C<named_expr>
node, and all child nodes are not declared inline with their parent nodes
but rather are declared in parallel with them, and the parents refer to
their children by their names.  A feature of the PTMD_STD grammar is that
expression nodes may be declared without explicit names, such that the
parser would generate names for them when deriving system catalog entries,
and that is why PTMD_STD supports, and encourages the use of for code
brevity/readability, the use of inline-declared expression nodes,
especially so when the C<expr> in question is an C<opaque_value_literal>.

Iff an C<expr> is an C<expr_name>, then this typically means that the
parent C<expr> is having at least one of its children declared with an
explicit name rather than inline, same as the corresponding system catalog
entry would do, and then the C<expr_name> is the invocation name of that
child.  Alternately, the C<expr_name> may be the invocation name of one of
the expression-containing routine's parameters, in which case the C<expr>
in question represents the current argument to that parameter; this also is
exactly the same as a corresponding catalog entry for using an argument.

Iff an C<expr> is a C<named_expr>, then then the C<expr> element of the
C<named_expr> is being declared with an explicit name, and the
C<decl_expr_name> element of the C<named_expr> is that name.  Note that a
C<named_expr> node may not have a C<named_expr> node as its direct C<expr>
child element.  I<TODO: nor a C<param> node.>

Examples:

    # an expr_name node #
    $foo_expr

    # a named_expr node #
    $bar_expr = factorial( $foo_expr )

=head2 Generic Function Invocation Expressions

Grammar:

    <func_invo> ::=
        <routine_name> \s* <func_arg_list>

    <routine_name> ::=
        <NameChain_payload>

    <func_arg_list> ::=
        '(' \s*
            [[<named_ro_arg> | <anon_ro_arg>] ** [\s* ',' \s*]]?
        \s* ')'

    <named_ro_arg> ::=
        <param_name> \s* '=>' \s* <expr>

    <param_name> ::=
        C<Name_payload>

    <anon_ro_arg> ::=
        <expr>

A C<func_invo> node represents the result of invoking a named
inner/function with specific arguments.  It is interpreted as a tuple of a
Muldis D C<sys.std.Core.Type.Cat.FuncInvoExprNodeSet> value.  The
C<routine_name> element specifies the C<function> attribute of the new
C<FuncInvoExprNodeSet>, which is the name of the function being invoked,
and the C<func_arg_list> element specifies the C<args> attribute.

In the general case of a function invocation, all of the arguments are
named, as per C<named_ro_arg>, and formatting a C<func_invo> node that
way is always allowed.  In some (common) special cases, some (which might
be all) arguments may be anonymous, as per C<anon_ro_arg>.

With just functions in the top-level namespaces C<sys.std> and C<inn>,
these 4 special cases apply:  If a function has exactly one parameter, then
it may be invoked with a single anonymous argument and the latter will bind
to that parameter.  Or, if a function has multiple parameters but exactly
one of those is mandatory, then it may be invoked with just one anonymous
argument, which is assumed to bind to the single mandatory parameter, and
all optional arguments must be named.  Or, if a function has multiple
mandatory parameters and one of them is named C<topic>, then it may be
invoked with a single anonymous argument and the latter will bind to that
parameter.  Or, if a function has multiple mandatory parameters and two of
them are named C<topic> and C<other>, then it may be invoked with two
anonymous arguments and the latter will bind to those parameters in
sequential order, the first one to C<topic> and the second one to C<other>.

With just functions in all top-level namespaces I<except> C<sys.std> and
C<inn>, these 2 special cases apply (similar to the prior-mentioned second
2):  If a function invocation has either 1 or 2 anonymous arguments, then
they will be treated as if they were named arguments for the C<topic> and
C<other> parameters; the only or sequentially first argument will bind to
C<topic>, and any sequentially second argument will bind to C<other>.

One reason for this difference between treatment of top-level namespaces is
it allows the Muldis D parser to convert all the anonymous arguments to
named ones (all arguments in the system catalog are named) when parsing the
expression-containing outer routine/etc in isolation from any other
user-defined entities.  The other reason for this limitation is that it
helps with self-documentation; programmers wanting to know an anonymous
argument's parameter name won't have to look outside the current outer
routine/etc or the language spec to find the answer.

I<Maybe TODO:  Consider adding a language pragma to enable use of the first
4 special cases with functions in all top-level namespaces, where the cost
of enabling is added implementation complexity and a reduction of the
ability to parse exploiting Muldis D code piecemeal.>

Examples:

    # zero params #
    nothing()

    # single mandatory param #
    Integer.median( Bag:{ 22, 20, 21, 20, 21, 21, 23 } )

    # single mandatory param #
    factorial( topic => 5 )

    # two mandatory params #
    Rational.quotient( dividend => 43.7, divisor => 16.9 )

    # same as previous #
    Rational.quotient( divisor => 16.9, dividend => 43.7 )

    # one mandatory param, two optional #
    inn.barfunc( $mand_arg, oa1 => $opt_arg1, oa2 => $opt_arg2 )

    # same as previous #
    inn.barfunc( oa2 => $opt_arg2, $mand_arg, oa1 => $opt_arg1 )

    # a user-defined non-inner function #
    dep.lib.foodb.bazfunc( a1 => 52, a2 => 'hello world' )

    # two params named 'topic' and 'other' #
    is_identical( $foo, $bar )

=head2 Generic If-Else Expressions

Grammar:

    <if_else_expr> ::=
        '(' \s*
            [if \s+ <if_expr> \s+ then \s+ <then_expr> \s+ else \s+]*
            <else_expr>
        \s* ')'

    <if_expr> ::=
        <expr>

    <then_expr> ::=
        <expr>

    <else_expr> ::=
        <expr>

An C<if_else_expr> node represents an N-way if-else control flow
expression.  It is interpreted as a tuple of a Muldis D
C<sys.std.Core.Type.Cat.IfElseExprNodeSet> value.  The whole collection of
sequential 0..N C<if_expr> + C<then_expr> elements specifies the C<if_then>
attribute of the new C<IfElseExprNodeSet>, which is a sequence of arbitrary
but C<Bool>-resulting I<if> expressions, and for just the first one of
those in the sequence that at runtime evaluates to C<Bool:true>, its
associated I<then> result value is the result of the C<if_else_expr>.  The
C<else_expr> element specifies the C<else> attribute, which determines the
result value of the C<if_else_expr> at runtime if either <if_then> is an
empty sequence or all of its conditionals evaluate to C<Bool:false>.

Examples:

    (if ($foo > 5) then $bar else $baz)

    (if ($ary is empty) then $empty_result else ($ary[0]))

    (if (($x === nothing) or ($y === nothing)) then nothing
        else Maybe:{ ($x{M:}) I+ (($y{M:}) I^ 3) }

    (if ($val isa T->Int) then ($val I^ 3)
        else if ($val isa T->Text) then ($val Tx 5)
        else true)

=head2 Generic Given-When-Default Expressions

Grammar:

    <given_when_def_expr> ::=
        '(' \s*
            given \s+ <given_expr> \s+
            [when \s+ <when_expr> \s+ then \s+ <then_expr> \s+]*
            default \s+ <default_expr>
        \s* ')'

    <given_expr> ::=
        <expr>

    <when_expr> ::=
        <expr>

    <then_expr> ::=
        <expr>

    <default_expr> ::=
        <expr>

A C<given_when_def_expr> node represents an N-way given-when-default
switch control flow expression that dispatches based on matching a single
value with several options.  It is interpreted as a tuple of a Muldis D
C<sys.std.Core.Type.Cat.GivenWhenDefExprNodeSet> value.  The C<given_expr>
element specifies the C<given> attribute of the new
C<GivenWhenDefExprNodeSet>, which is the control value for the expression.
The whole collection of nonordered 0..N C<when_expr> + C<then_expr>
elements specifies the C<when_then> attribute, which is a set of I<when>
comparands; if any of these I<when> values matches the value of C<given>,
its associated I<then> result value is the result of the
C<given_when_def_expr>.  The C<default_expr> element specifies the
C<default> attribute, which determines the result value of the
C<given_when_def_expr> at runtime if either <when_then> is an empty set or
none of its comparands match C<given>.

Examples:

    (given $digit
        when 'T' then 10
        when 'E' then 11
        default $digit
    )

=head2 Library Entity Reference Selector

Grammar:

    <lib_entity_ref_selector> ::=
          <func_ref>
        | <proc_ref>
        | <type_ref>
        | <ord_det_func_ref>

    <func_ref> ::=
        'F->' <routine_name>

    <proc_ref> ::=
        'P->' <routine_name>

    <type_ref> ::=
        'T->' <type_name>

    <ord_det_func_ref> ::=
        'ODF->' <routine_name>

A C<[func|proc|type|ord_det_func]_ref> node represents a literal or
selector invocation for a DBMS routine or type reference value.  It is
interpreted as a tuple of a Muldis D
C<sys.std.Core.Type.Cat.[Func|Proc|Type|OrdDetFunc]RefSelExprNodeSet>
value, which when evaluated at runtime would result in a
C<sys.std.Core.Type.Cat.[Func|Proc|Type|OrdDetFunc]Ref> value.  The
C<[routine|type]_name> element specifies the C<referencing> attribute of
the new
C<sys.std.Core.Type.Cat.[Func|Proc|Type|OrdDetFunc]RefSelExprNodeSet>,
which is the name of the routine or type being invoked by way of the new
reference value.

Examples:

    F->inn.filter

    P->inn.try_block

    T->inn.foo_type

    ODF->inn.order_bars

=head1 FUNCTION INVOCATION ALTERNATE SYNTAX EXPRESSIONS

Grammar:

    <func_invo_alt_syntax> ::=
          <comm_infix_reduce_op_invo>
        | <noncomm_infix_reduce_op_invo>
        | <comm_dyadic_infix_op_invo>
        | <noncomm_dyadic_infix_op_invo>
        | <monadic_prefix_op_invo>
        | <monadic_postfix_op_invo>
        | <rat_op_invo_with_round>
        | ...

A C<func_invo_alt_syntax> node represents the result of invoking a named
system-defined function with specific arguments.  It is interpreted as a
tuple of a Muldis D C<sys.std.Core.Type.Cat.FuncInvoExprNodeSet> value.  A
C<func_invo_alt_syntax> node is a lot like a C<func_invo> node in purpose
and interpretation but it differs in several significant ways.

While a C<func_invo> node can be used to invoke any inner/function at all,
a C<func_invo_alt_syntax> node can only invoke a fraction of them, and only
standard system-defined functions.  While a C<func_invo> node uses a simple
common format with all functions, written in prefix notation with generally
named arguments, a C<func_invo_alt_syntax> node uses potentially unique
syntax for each function, often written in infix notation, although
inter-function format consistency is still applied as much as is reasonably
possible.

One basic format commonality with all C<func_invo_alt_syntax> tokens is
that the entire token is delimited by a pair of parenthesis, whose
conceptual purpose is to group together all the parts of the token, so
there are no precedence issues to make difficulty in telling the token from
its parent, no matter how complicated it is; this is like with the common
grouping parenthesis in mathematical expressions.  A practical purpose of
this is that the delimiting parenthesis is a feature mostly unique to a
C<func_invo_alt_syntax> token, which almost all other grammar tokens don't
have, C<if_else_expr> and C<given_when_def_expr> being the main exceptions,
and so a parser encountering an opening parenthesis at the start of a
context where a generic C<expr> is expected can be reasonably sure it is
dealing with a C<func_invo_alt_syntax> (or if-else or given-when) and not
something else.

Broadly speaking, a C<func_invo_alt_syntax> node has 2-3 kinds of payload
elements:  The first is the determinant of what function to invoke,
hereafter referred to as a I<op> or I<keyword>.  The second is an ordered
list of 1-N mandatory function inputs, hereafter referred to as I<main op
args>, whose elements typically have generic names like C<expr> or C<lhs>
or C<rhs>.  The (optional) third is a named list of optional function
inputs, hereafter referred to as I<extra op args>, whose elements tend to
have more purpose-specific names such as C<using_clause>, though note that
things like C<using_clause> can be either mandatory or optional depending
on the op they are being used with.

The decision of I<which> system-defined functions get the special alternate
syntax treatment partly comes down to respecting common good practices in
programming languages, letting people write code more like how they're
comfortable with.  Most programming languages only have special syntax for
a handful of their operators, such as common comparison and boolean and
mathematical and string and element extraction operators, and so Muldis D
mainly does likewise.  Functions get special alternate syntax if they would
be frequently used and the syntax would significantly aid programmers in
quickly writing understandeable code.

=head2 Simple Commutative N-adic Infix Reduction Operators

Grammar:

    <comm_infix_reduce_op_invo> ::=
        '(' \s*
            <expr> ** [\s+ <comm_infix_reduce_op> \s+]
        \s* ')'

    <comm_infix_reduce_op ::=
          and | or | xor
        | 'I+' | 'I*'
        | 'N+' | 'N*'
        | 'R+' | 'R*'

A C<comm_infix_reduce_op_invo> node is for using infix notation to invoke a
(homogenous) commutative N-adic reduction operator function.  Such a
function takes exactly 1 actual argument, which is unordered-collection
typed (q/set or q/bag), and the elements of that collection are the inputs
of the operation; the inputs are all of the same type as each other and of
the result.  A single C<comm_infix_reduce_op_invo> node is equivalent to a
single C<func_invo> node whose C<func_arg_list> element defines a single
argument, whose value is a C<QSet> or C<QBag> node, which has a payload
C<expr> element for each C<expr> element of the
C<comm_infix_reduce_op_invo>, and the relative sequence of the C<expr>
elements isn't significant.  A C<comm_infix_reduce_op_invo> node requires
at least 2 input value providing child nodes (C<expr> must match at least
twice), which are its 2-N main op args; if you already have your inputs in
a single collection-valued node then use C<func_invo> to invoke the
function instead.  If C<comm_infix_reduce_op> matches more than once in the
same C<comm_infix_reduce_op_invo>, then all of the C<comm_infix_reduce_op>
matches must be identical / the same operator.

This table indicates which function is invoked by each keyword:

    and -> Core.Bool.and( Set:{ $expr[0], ..., $expr[n] } )
    or  -> Core.Bool.or( Set:{ $expr[0], ..., $expr[n] } )
    xor -> Core.Bool.xor( Bag:{ $expr[0], ..., $expr[n] } )
    I+  -> Integer.sum( Bag:{ $expr[0], ..., $expr[n] } )
    I*  -> Integer.product( Bag:{ $expr[0], ..., $expr[n] } )
    N+  -> Rational.sum( Bag:{ $expr[0], ..., $expr[n] } )
    N*  -> Rational.product( Bag:{ $expr[0], ..., $expr[n] } )
    R+  -> Core.QRelation.union( QSet:{ $expr[0], ..., $expr[n] } )
    R*  -> Core.QRelation.join( QSet:{ $expr[0], ..., $expr[n] } )

Examples:

    (true and false and true)

    (true or false or true)

    (true xor false xor true)

    (14 I+ 3 I+ -5)

    (-6 I* 2 I* 25)

    (4.25 N+ -0.002 N+ 1.0)

    (69.3 N* 15*2^6 N* 49/23)

    (Set:{ 1, 3, 5 } R+ Set:{ 4, 5, 6 } R+ Set:{ 0, 9 })

    (Set:{ 1, 3, 5, 7, 9 } R* Set:{ 3, 4, 5, 6, 7, 8 } R* Set:{ 2, 5, 9 })

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

Grammar:

    <noncomm_infix_reduce_op_invo> ::=
        '(' \s*
            <expr> ** [\s+ <noncomm_infix_reduce_op> \s+]
        \s* ')'

    <noncomm_infix_reduce_op ::=
        '[<=>]' | 'B~' | 'T~' | 'A~'

A C<noncomm_infix_reduce_op_invo> node is for using infix notation to
invoke a (homogenous) non-commutative N-adic reduction operator function.
Such a function takes exactly 1 actual argument, which is
ordered-collection typed (q/array), and the elements of that collection are
the inputs of the operation; the inputs are all of the same type as each
other and of the result.  A single C<noncomm_infix_reduce_op_invo> node is
equivalent to a single C<func_invo> node whose C<func_arg_list> element
defines a single argument, whose value is a C<QArray> node, which has a
payload C<expr> element for each C<expr> element of the
C<noncomm_infix_reduce_op_invo>, and the C<expr> elements have the same
relative sequence.  A C<noncomm_infix_reduce_op_invo> node requires at
least 2 input value providing child nodes (C<expr> must match at least
twice), which are its 2-N main op args; if you already have your inputs in
a single collection-valued node then use C<func_invo> to invoke the
function instead.  If C<noncomm_infix_reduce_op> matches more than once in
the same C<noncomm_infix_reduce_op_invo>, then all of the
C<noncomm_infix_reduce_op> matches must be identical / the same operator.

This table indicates which function is invoked by each keyword:

    [<=>] -> Core.Cat.Order.reduction( Array:{ $expr[0], ..., $expr[n] } )
    B~    -> Blob.catenation( Array:{ $expr[0], ..., $expr[n] } )
    T~    -> Text.catenation( Array:{ $expr[0], ..., $expr[n] } )
    A~    -> QArray.catenation( QArray:{ $expr[0], ..., $expr[n] } )

Examples:

    (same [<=>] increase [<=>] decrease)

    (F;'DEAD' B~ 1;'10001101' B~ F;'BEEF')

    ('hello' T~ ' ' T~ 'world')

    (Array:[ 24, 52 ] A~ Array:[ -9 ] A~ Array:[ 0, 11, 24, 7 ])

=head2 Simple Commutative Dyadic Infix Operators

Grammar:

    <comm_dyadic_infix_op_invo> ::=
        '(' \s*
            <expr> \s+ <comm_dyadic_infix_op> \s+ <expr>
        \s* ')'

    <comm_dyadic_infix_op> ::=
          '===' | '!==='
        | 'I|-|' | 'N|-|'

A C<comm_dyadic_infix_op_invo> node is for using infix notation to invoke a
commutative dyadic operator function.  Such a function takes exactly 2
arguments, which are the inputs of the operation; the inputs are all of the
same type as each other but the result might be of either that type or a
different type.  A single C<comm_dyadic_infix_op_invo> node is equivalent
to a single C<func_invo> node whose C<func_arg_list> element defines 2
arguments, and the 2 C<expr> elements of the C<comm_dyadic_infix_op_invo>
supply the values of those arguments, and which arguments get which C<expr>
isn't significant.

This table indicates which function is invoked by each keyword:

    ===  -> Core.Universal.is_identical( $expr[0], $expr[1] )
    !=== -> Core.Universal.is_not_identical( $expr[0], $expr[1] )
    I|-| -> Integer.abs_difference( $expr[0], $expr[1] )
    N|-| -> Rational.abs_difference( $expr[0], $expr[1] )

Examples:

    ($foo === $bar)

    ($foo !=== $bar)

    (15 I|-| 17)

    (7.5 N|-| 9.0)

=head2 Simple Non-commutative Dyadic Infix Operators

Grammar:

    <noncomm_dyadic_infix_op_invo> ::=
        '(' \s*
            <lhs> \s+ <noncomm_dyadic_infix_op> \s+ <rhs>
        \s* ')'

    <lhs> ::=
        <expr>

    <rhs> ::=
        <expr>

    <noncomm_dyadic_infix_op> ::=
        | 'I-' | 'I/' | '%' | 'I^'
        | 'N-' | 'N/'
        | 'R-' | 'R/'

A C<noncomm_dyadic_infix_op_invo> node is for using infix notation to
invoke a non-commutative dyadic operator function.  Such a function takes
exactly 2 arguments, which are the inputs of the operation; the inputs are
all of the same type as each other but the result might be of either that
type or a different type.  A single C<noncomm_dyadic_infix_op_invo> node is
equivalent to a single C<func_invo> node whose C<func_arg_list> element
defines 2 arguments, and the 2 C<expr> elements of the
C<noncomm_dyadic_infix_op_invo> supply the values of those arguments, which
are associated in the appropriate sequence.

This table indicates which function is invoked by each keyword:

    I- -> Integer.difference( minuend => $lhs, subtrahend => $rhs )
    I/ -> Integer.quotient( dividend => $lhs, divisor => $rhs )
    %  -> Integer.remainder( dividend => $lhs, divisor => $rhs )
    I^ -> Integer.power( radix => $lhs, exponent => $rhs )
    N- -> Rational.difference( minuend => $lhs, subtrahend => $rhs )
    N/ -> Rational.quotient( dividend => $lhs, divisor => $rhs )
    R- -> Core.QRelation.difference( source => $lhs, filter => $rhs )
    R/ -> Core.QRelation.quotient( dividend => $lhs, divisor => $rhs )

Examples:

    (34 I- 21)

    (5 I/ 3)

    (5 % 3)

    (2 I^ 63)

    (9.2 N- 0.1)

    (1;101.01 N/ 1;11.0)

    (Set:{ 8, 4, 6, 7 } R- Set:{ 9, 0, 7 })

    (Relation:[ x, y ];{ [ 5, 6 ], [ 3, 6 ] } R/ Relation:{ { y => 6 } })

=head2 Simple Monadic Prefix Operators

Grammar:

    <monadic_prefix_op_invo> ::=
        '(' \s*
            <monadic_prefix_op> \s+ <expr>
        \s* ')'

    <monadic_prefix_op> ::=
        not | 'I||' | 'N||'

A C<monadic_prefix_op_invo> node is for using prefix notation to invoke a
monadic operator function.  Such a function takes exactly 1 argument, which
is the input of the operation.  A single C<monadic_prefix_op_invo> node is
equivalent to a single C<func_invo> node whose C<func_arg_list> element
defines 1 argument, and the 1 C<expr> element of the
C<monadic_prefix_op_invo> supplies the value of that argument.

This table indicates which function is invoked by each keyword:

    not -> Core.Bool.not( $expr )
    I|| -> Integer.abs( $expr )
    N|| -> Rational.abs( $expr )

Examples:

    (not true)

    (I|| -23)

    (N|| -4.59)

=head2 Simple Monadic Postfix Operators

Grammar:

    <monadic_postfix_op_invo> ::=
        '(' \s*
            <expr> \s+ <monadic_postfix_op>
        \s* ')'

    <monadic_postfix_op> ::=
        '++' | '--' | '!'

A C<monadic_postfix_op_invo> node is for using prefix notation to invoke a
monadic operator function.  Such a function takes exactly 1 argument, which
is the input of the operation.  A single C<monadic_postfix_op_invo> node is
equivalent to a single C<func_invo> node whose C<func_arg_list> element
defines 1 argument, and the 1 C<expr> element of the
C<monadic_postfix_op_invo> supplies the value of that argument.

This table indicates which function is invoked by each keyword:

    ++ -> Integer.increment( $expr )
    -- -> Integer.decrement( $expr )
    !  -> Integer.factorial( $expr )

Examples:

    (13 ++)

    (4 --)

    (5 !)

=head2 Rational Operators That Do Rounding

Grammar:

    <rat_op_invo_with_round> ::=
        '(' \s*
            <rat_op_invo> \s+ <rounded_with_rule_clause>
        \s* ')'

    <rat_op_invo> ::=
          <expr>
        | <infix_rat_op_invo>
        | <prefix_rat_op_invo>
        | <postfix_rat_op_invo>

    <infix_rat_op_invo> ::=
        <lhs> \s+ <infix_rat_op> \s+ <rhs>

    <infix_rat_op> ::=
        'N^' | log

    <prefix_rat_op_invo> ::=
        <expr> \s+ <prefix_rat_op>

    <prefix_rat_op>
        'e^'

    <postfix_rat_op_invo> ::=
        <expr> \s+ <postfix_rat_op>

    <postfix_rat_op>
        loge

    <rounded_with_rule_clause> ::=
        round \s+ <round_rule>

    <round_rule> ::=
        <expr>

A C<rat_op_invo_with_round> node is for using infix or prefix or postfix
notation to invoke a rational numeric operator function whose operation
involve rounding a number to one with less precision.  Such a function
takes exactly 1 (C<$expr>) or 2 (C<$lhs> and C<$rhs>) primary arguments,
which are the inputs of the operation, plus a special C<$round_rule>
argument which specifies explicitly the semantics of the numeric rounding
in a declarative way (all 3 of these are I<main op args>).  A single
C<rat_op_invo_with_round> node is equivalent to a single C<func_invo> node
whose C<func_arg_list> element defines 2-3 arguments, and the
C<expr|lhs|rhs|round_rule> elements of the C<rat_op_invo_with_round> supply
the values of those arguments, which are associated in the appropriate
sequence.

This table indicates which function is invoked by each keyword:

         -> Rational.round( $expr, round_rule => $round_rule )
    N^   -> Rational.power( radix => $lhs, exponent => $rhs,
                round_rule => $round_rule )
    log  -> Rational.log( $lhs, $radix => $rhs, round_rule => $round_rule )
    e^   -> Rational.natural_power( $expr, round_rule => $round_rule )
    loge -> Rational.natural_log( $expr, round_rule => $round_rule )

Examples:

    ($foo round RatRoundRule:[10,-2,half_even])

    (2.0 N^ 0.5 round RatRoundRule:[2,-7,to_zero])

    (309.1 log 5.4 round RatRoundRule:[10,-4,half_up])

    (e^ 6.3 round RatRoundRule:[10,-6,to_ceiling])

    (17.0 loge round RatRoundRule:[3,-5,to_floor])

=head1 DEPOT DECLARATION

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

Grammar:

    <depot> ::=
        depot \s+
        '{' \s*
            <depot_catalog>
            <depot_data>?
        \s* '}'

=head1 BOOTLOADER STATEMENT

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

Grammar:

    <boot_stmt> ::=
          <generic_boot_stmt>
        | ...

    <generic_boot_stmt> ::=
        boot_stmt
        \s* ':' \s* <imperative_routine_name>
        \s* ':' \s* <imperative_routine_upd_args>
        \s* ':' \s* <imperative_routine_ro_args>

    <imperative_routine_name> ::=
        <NameChain_payload>

    <imperative_routine_upd_args> ::=
        '{' \s*
            [[<Name_payload> \s* '=>' \s* <NameChain_payload>]
                ** [\s* ',' \s*]]?
        \s* '}'

    <imperative_routine_ro_args> ::=
        <QTuple_payload>

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
