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

=head1 PREFACE

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

=head1 DESCRIPTION

This document outlines the grammar of the I<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 Muldis
D depot definition, which begins with a language name
declaration, and then has a C<Database> value literal defining the depot's
catalog, and finally has, optionally, a C<Database> value literal defining
the depot's data.  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 for defining the depot's catalog,
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 part of the system catalog.
Fundamentally every Muldis D depot is akin to a code library, and a Muldis
D "main program" is nothing more than a depot having a procedure that is
designated to execute automatically after a mount event of its host depot.

As a special extension feature, a C<PTMD_STD> Muldis D code file may
alternately consist just of a (language-qualified) Muldis D value literal,
which mainly is intended for use in mixed-language environments as an
interchange format for data values between Muldis D and other languages.

The grammar in this file is formatted as a hybrid between various BNF
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<Muldis_D>.

=head1 START

Grammar:

    <Muldis_D> ::=
        <language_name> \s+ [<value> | <depot>]

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

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

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

=head1 LANGUAGE NAME

Grammar:

    <language_name> ::=
        <ln_base_name>
        \s* ':' <ln_base_authority>
        \s* ':' <ln_base_version_number>
        \s* ':' <ln_dialect>
        \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> ::=
        '{' \s*
            catalog_abstraction_level \s* '=>' \s* <cat_abstr_level>
        \s* '}'

    <cat_abstr_level> ::=
          the_floor
        | code_as_data
        | plain_rtn_inv
        | rtn_inv_alt_syn

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

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

=back

Examples:

    Muldis_D:"http://muldis.com":"1.2.3":PTMD_STD:{
        catalog_abstraction_level => rtn_inv_alt_syn
    }

=head1 CATALOG ABSTRACTION LEVELS

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

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

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

Choosing an abstraction level to write Muldis D code against is all a
matter of trade-offs, perhaps mainly between advantages for Muldis D
implementors and advantages for Muldis D users.  Lower levels have benefits
such as that it takes less programmer effort to create a Muldis D code
parser or generator that just has to support that level, and such a
parser/generator could be made more quickly and occupy a smallar resource
footprint.  On the other side, higher levels have benefits such that any
Muldis D code itself can be immensely more terse and readable (and
writable), as well as have a much stronger resemblence to typical
general-purpose programming languages, which also caries the benefit that a
lot more of a programmer's preconceptions about what they should be able to
write in a language is more likely to just work in Muldis D, and users can
adopt it with less re-training.  Essentially, lower abstraction levels are
more like machine code while higher levels are more like human language.
It may not need to be said that while a lower level may be for a Muldis D
implementer an easier thing to make run, it would conversely tend to be
more difficult for them to write a test suite for, being more verbose.

B<It should be emphasized that all catalog abstration levels are completely
expressive, and everything a user can do with one, they can do with the
others, and code is round-trippable between all of them without loss of
behaviour.  The choice is simply about the syntax to accomplish something.>

Specifying this pragma in a C<language_name> node is mandatory, since there
is no obvious abstraction level to use implicitly when one isn't specified.

=head2 the_floor

When the C<catalog_abstraction_level> pragma is C<the_floor>, then the
following grammar definitions are in effect:

    <value> ::=
        <value__the_floor>

    <catalog> ::=
        <catalog__code_as_data>

    <expr> ::=
        <value__the_floor>

This abstraction level exists more as an academic exercise and is not
intended to actually be used.  It is meant to be analogous to those
academic programming languages whose main design goal, in addition to still
being programmatically complete, is to have the absolute smallest grammar
at all costs, also analogous to an extreme-RISC machine.  This level is
like C<code_as_data> except that it has the absolute minimum of value
literal syntaxes rather than all of them, essentially just having a single
node kind apiece to cover all scalars, tuples, relations.  This level is
also so minimal that many representation alternatives of the system catalog
itself are being ignored, such as the more concise alternatives the system
catalog itself provides to represent selectors of set/array/bag values or
any system-defined scalar types not in terms of possreps.

Examples:

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

=head2 code_as_data

When the C<catalog_abstraction_level> pragma is C<code_as_data>, then the
following grammar definitions are in effect:

    <value> ::=
        <value__code_as_data>

    <catalog> ::=
        <catalog__code_as_data>

    <expr> ::=
        <value__code_as_data>

This abstraction level is the best one for when you want to write code in
exactly the same form as it would take in the system catalog, and at the
same time use all the relatively consise alternatives the system catalog
itself provides for value literals and selectors.  With this abstraction
level, a depot consists simply of a language name plus one or two database
value literals.  The format for specifying a system catalog is exactly the
same as the format for specifying the user data of a database.  All a
Muldis D parser/generator has to know is how to parse static Muldis D value
literals and its done.  That said, C<code_as_data> includes all of the
special grammar dealing with value literals, including those for many
specific scalar or nonscalar types.  This level is analagous to a
high-level assembly language in a way; what you say in code is exactly what
you get in the system catalog, but your code would be too verbose for the
tastes of someone preferring normal high-level language code.

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

Examples:

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

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

=head2 plain_rtn_inv

When the C<catalog_abstraction_level> pragma is C<plain_rtn_inv>, then the
following grammar definitions are in effect:

    <value> ::=
        <value__code_as_data>

    <catalog> ::=
        <catalog__plain_rtn_inv>

    <expr> ::=
        <expr__plain_rtn_inv>

This abstraction level is the lowest one that can be recommended for
general use, and every Muldis D implementation that is expected to be
directly used by programmers (in contrast to its main use just being by way
of wrapper APIs or code generators) should support at least this level,
even if that implementation is being touted as "minimal".  This abstraction
level has the simplest grammar that could reasonably be considered as like
that of a general purpose programming language.  Unlike the C<code_as_data>
level, the C<plain_rtn_inv> level makes everything that isn't conceptually
a value literal or selector look like typical routine or type declarations
or value expressions or statements, just as programmers typically expect.

One of Muldis D's primary features is that, as much as possible, the
system-defined language features are defined in terms of ordinary types and
routines.  This means for one thing that users are empowered to create
their own types and routines with all of the capabilities, flexibility, and
syntax as the language's built-in features have.  This also means that it
should be relatively simple to parse Muldis D code because the vast
majority of language features don't have their own special syntax to
account for, and the L</Generic Function Invocation Expressions> syntax
covers most of them, in terms of the common prefix/polish notation that in
practice most invocations of user-defined routines are formatted as anyway.

The C<plain_rtn_inv> abstraction level is all about having code that looks
like general purpose programming language code but that everything looks
like user-defined routines and types.  The code is mostly just nested
invocations of functions or procedures in basic polish notation, and both
that code and material declarations have a C-language-like syntax.

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

Examples:

    Muldis_D:"http://muldis.com":"1.2.3":PTMD_STD:{
        catalog_abstraction_level => plain_rtn_inv
    }
    depot-catalog {
        public function cube (Int <-- $topic : Int) {
            Integer.power( radix => $topic, exponent => 3 )
        }
    }

=head2 rtn_inv_alt_syn

When the C<catalog_abstraction_level> pragma is C<rtn_inv_alt_syn>, then
the following grammar definitions are in effect:

    <value> ::=
        <value__code_as_data>

    <catalog> ::=
        <catalog__plain_rtn_inv>

    <expr> ::=
        <expr__rtn_inv_alt_syn>

This abstraction level is the highest one and is the most recommended one
for general use, assuming that all the Muldis D implementations you want to
use support it.  The expectation is that, in general, minimal Muldis D
implementations won't support it but non-minimal ones would, so code
written to it may not be the most universally portable as-is but should be
portable in most common environments.

In practice a huge payoff of improved user code brevity and readability
(and writability) is gained by the C<rtn_inv_alt_syn> abstraction level
over the C<plain_rtn_inv> level by adding special syntax for a lot of
commonly used built-in routines, such as infix syntax for common math
operators or postcircumfix syntax for attribute accessors.  The tradeoff
for this user code brevity is a significant amount of extra complexity in
parsers, due to all the extra special cases, though this complexity can be
mitigated somewhat by standardizing these additions in format where
possible.  These 2 highest levels both look like a general purpose
programming language, but C<rtn_inv_alt_syn> is a lot more concise.

In particular, C<rtn_inv_alt_syn> is probably the I<only> Muldis D dialect
that conceivably can match or beat the conciseness of a majority of general
purpose programming languages, and would probably be the most preferred
abstraction level for developers.  This fact would also help to drive a
majority of implementations to support this greatest complexity level.  And
even then, this most complex of standard Muldis D grammars still generally
has simpler grammar rules than a lot of general languages, even if this
difference is more subtle.  It certainly is simpler and more easier to
parse grammar than SQL in its general case.

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

Examples:

    Muldis_D:"http://muldis.com":"1.2.3":PTMD_STD:{
        catalog_abstraction_level => rtn_inv_alt_syn
    }
    depot-catalog {
        public function cube (Int <-- $topic : Int) {
            $topic I^ 3
        }
    }

=head1 VALUE LITERALS AND SELECTORS

Grammar:

    <value__the_floor> ::=
          <Scalar>
        | <Tuple>
        | <Relation>

    <value__code_as_data> ::=
          <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>
        | <RatRoundRule>
        | <String>

    <coll_value_selector> ::=
          <Scalar>
        | <Tuple>
        | <Database>
        | <Relation>
        | <Set>
        | <Maybe>
        | <Array>
        | <Bag>
        | <Interval>

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> 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<Muldis_D> node with a C<value> second element 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<value_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*
            [<type_name> ':' \s*]?
        ]?
        <value_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
        | RatRoundRule
        | String | BString | OString | UCPString
        | DH? Scalar
        | DH? Tuple
        | Database
        | DH? Relation
        | DH? Set
        | DH? [Maybe | Single]
        | DH? Array
        | DH? Bag
        | DH? Interval

    <type_name> ::=
        <NameChain_payload>

    <value_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>
        | <RatRoundRule_payload>
        | <String_payload>
        | <Scalar_payload>
        | <Tuple_payload>
        | <Database_payload>
        | <Relation_payload>
        | <Set_payload>
        | <Maybe_payload>
        | <Array_payload>
        | <Bag_payload>
        | <Interval_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<value_payload> generally necessary to
interpret the latter; what grammars are valid for C<value_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<value_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<Tuple:d0>,
C<Relation:d0c0>, C<Relation:d0c1>, 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<value_payload> is a member of the named subtype.  Iff C<value_kind> is
C<[|DH]Scalar> then C<type_name> is mandatory; otherwise, C<type_name> is
optional for all C<value>, except that C<type_name> must be omitted when
C<value_kind> is one of the 2 [C<Bool>, C<Order>]; this isn't because those
2 types can't be subtyped, but because in practice doing so isn't useful.

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

This is mandatory for all C<value>.

=back

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

=head1 OPAQUE VALUE LITERALS

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.OVLScaValExprNodeSet>, a tuple of which is what
every kind of C<opaque_value_literal> node distills to when it is beneath
the context of a C<depot> node, as it describes some semantics.

=head2 Boolean Literals

Grammar:

    <Bool> ::=
        [Bool ':' \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*]?
        <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*
            [<type_name> ':' \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*
            [<type_name> ':' \s*]?
        ]?
        <Int_payload>

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

    <num_max_col_val> ::=
        <pint_head>

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

    <nnint_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_nnint_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*
            [<type_name> ':' \s*]?
        ]?
        <Rat_payload>

    <Rat_payload> ::=
          <num_max_col_val> ';' \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*
            [<type_name> ':' \s*]?
        ]?
        <Blob_payload>

    <Blob_payload> ::=
        <blob_max_col_val> ';' \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*
            [<type_name> ':' \s*]?
        ]?
        <Text_payload>

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

    <escaped_char> ::=
          '\b' | '\a' | '\q' | '\g' | '\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
    \g  | F;60      | GRAVE ACCENT    | `   | delim as-val Comment literals
    \h  | F;23      | NUMBER SIGN     | #   | dlm no-val Comment (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*
        [<type_name> ':' \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*
        [<type_name> ':' \s*]?
        <NameChain_payload>

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

    <DeclNameChain> ::=
        DeclNameChain ':' \s*
        [<type_name> ':' \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 7 C<Name> values, which is a top-level namespace:
C<sys>, C<mnt>, C<tpc>, C<fed>, C<dep>, C<sdp>, C<lex>.
(Actually, C<type> is a 8th 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<Tuple.attr> rather than
C<sys.std.Core.Tuple.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 value expression / etc reference, 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.  Furthermore, if such an unqualified chain has more than exactly
1 element in it, it is further assumed that the chain is referring to an
attribute of a tuple (or database) typed value expression / etc.

The third special case is an extension to the second special case that
involves any context where a referenced-by-name value expression / etc has
the declaration name C<topic>, I<and> C<topic> is tuple (or database)
typed.  In only such a context, a
C<NameChain_payload> may be prefixed with a chain-element-separator /
period token instead of having a leading (post C<lex> omission) C<topic>
element; a parser encountering a chain with a leading period will assume
the chain sans that period is unqualified and will prepend both a C<lex>
and C<topic> element to it.  So for example a C<$.foo> is treated as being
C<$lex.topic.foo>.  Note that PTMD_STD doesn't confuse this with the use of
an empty string chain element because those must always be delimited, so
C<$"".foo> is still treated as C<$lex."".foo>.  Note that the third special
case may only be used to reference attributes of C<$lex.topic> (or
attributes of those, etc), not C<$lex.topic> itself; you still have to use
C<$topic> for that.

The fourth 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<[|dh_][tuple|relation]_from> or
C<[|dh_][set|maybe|single|array|bag|interval]_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 fourth special case is
completely orthogonal to which of the 7 normal top-level namespaces is in
use (implicitly or explicitly) by the chain being prefixed, and works for
all 7 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"

    NameChain:.attr  # same as NameChain:lex.topic.attr #

    DeclNameChain:gene.sorted_person_name

    DeclNameChain:stats."samples by order"

    DeclNameChain:[]

=head2 Code Comment Literals

Grammar:

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

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

    <non_value_comment> ::=
        [
            '#' ** 2..*
          | '#' ' '*
                [<-[\\\#\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<Comment> 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 backticks/grave-accents (C<`>) rather than apostrophes/single-quotes.

A C<non_value_comment> node is I<also> interpreted as a Muldis D
C<sys.std.Core.Type.Cat.Comment> value in essentially the same way as a
C<Comment>, but for a few formatting differences described further below.
The primary reason for both C<Comment> and C<non_value_comment> to exist is
so that code comments can be placed in Muldis D code in very different ways
without there being any confusion on interpretation.

A C<Comment> node is used when the comment is normal data that is an
integral part of the Muldis D code proper, same as every part of the code
that isn't a comment, such as when the comment I<is> an C<expr> or C<value>
node.

A C<non_value_comment> node, in contrast, is strictly not part of the code
proper; Muldis D code can contain these almost anywhere as meta-data for
the code, and in large part it is treated as if it were part of the
insignificant whitespace; that all being said, generally speaking any
C<non_value_comment> is retained in the parse tree adjusted to live in the
contextually nearest place where a resulting system catalog node has a
C<comment> attribute.  I<Details of determining the contextually nearest
place for these comments to go is pending.>

Syntactically, a C<non_value_comment> node differs from C<Comment_payload>
only in that each string segment is delimited by number-signs/hash-marks
rather than backticks/grave-accents, and also that:

Note that any leading or trailing space (F;20) characters inside the C<#>
delimiters of a C<non_value_comment> 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>.

Note that a run of 3+ C<#> is equivalent to exactly 2 adjacent ones, which
denotes an empty comment segment.  This feature exists to empower things
like making visual dividing lines in the code just out of hash-marks.

Note that the hash-mark does have other uses in PTMD_STD code besides
delimiting comments, so since C<non_value_comment> may conceptually be
placed almost anywhere in code, the other parts of the grammar that
specifically enable this need to ensure appropriate measures are taken to
avoid ambiguity, for example mandating that the comments are bounded by
whitespace.

Examples (the first 2 are as values, the third is not as a value):

    Comment:`This does something.`

    `So does this.`

    # And also this. #

=head2 TAI Temporal Literals

Grammar:

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

    <Instant_payload> ::=
        <Rat_payload>

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

    <Duration_payload> ::=
        <Rat_payload>

An C<Instant> node represents a single point in time which is specified in
terms of atomic seconds; it is a rational numeric type, that is disjoint
from both C<Rat> and C<Duration>.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Instant> value 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 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*
        [<type_name> ':' \s*]?
        <UTCInstant_payload>

    <UTCInstant_payload> ::=
        <UTCDuration_payload>

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

    <FloatInstant_payload> ::=
        <UTCDuration_payload>

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

    <UTCDuration_payload> ::=
          <num_max_col_val> ';' \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,6,,,] # 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 Rational Rounding Rule Literals

Grammar:

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

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

    <radix> ::=
        <Int_payload>

    <min_exp> ::=
        <Int_payload>

    <round_meth> ::=
        <RatRoundMeth_payload>

A C<RatRoundRule> node represents a rational rounding rule.  It is
interpreted as a Muldis D C<sys.std.Core.Type.Cat.RatRoundRule> value whose
attributes are defined by the C<RatRoundRule_payload>.  A
C<RatRoundRule_payload> 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 C<radix> and C<min_exp> must qualify as a valid
C<Int_payload>, and C<round_meth> must qualify as a valid
C<RatRoundMeth_payload>.

Examples:

    RatRoundRule:[10,-2,half_even]

    RatRoundRule:[2,-7,to_zero]

=head2 Low Level Integer String Literals

Grammar:

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

    <String_payload> ::=
          <num_max_col_val> ';' \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.

=head2 Scalar Selectors

Grammar:

    <Scalar> ::=
        DH? Scalar ':' \s*
        <type_name> ':' \s*
        <Scalar_payload>

    <Scalar_payload> ::=
          <possrep_name> ';' \s* <possrep_attrs>
        | <possrep_attrs>

    <possrep_name> ::=
        <Name_payload>

    <possrep_attrs> ::=
        <Tuple_payload>

A C<Scalar> node represents a literal or selector invocation for a
scalar subtype value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Scalar> subtype value whose declared type is specified
by the node's (mandatory for C<Scalar>) C<type_name> and whose attributes
are defined by the C<Scalar_payload>.  If the C<Scalar_payload> is just a
C<possrep_attrs>, then it is interpreted as if it also had an explicit
C<possrep_name> that is the empty string.  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 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<DHScalar> rather than C<Scalar>, then the C<value> node is interpreted
simply as an C<Scalar> node that is appropriately further restricted; the
C<type_name> must name a C<DHScalar> subtype, and the C<possrep_attrs> must
specify only deeply homogeneous typed attribute values.

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

Examples:

    Scalar:sys.std.Core.Type.Cat.Name:{ "" => 'the_thing' }

    Scalar:sys.std.Core.Type.Rat:float;{
        mantissa => 45207196,
        radix    => 10,
        exponent => 37
    }

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

    Scalar:fed.lib.the_db.WeekDay:name;{
        "" => "monday"
    }

    Scalar:fed.lib.the_db.WeekDay:number;{
        "" => 5
    }

    Scalar:Int:{ "" => Scalar:String."<42>":{} }

    Scalar:Text:nfd_codes;{ "" => Scalar:String."<80><101><114><109>":{} }

=head2 Tuple Selectors

Grammar:

    <Tuple> ::=
        DH? Tuple ':' \s*
        [<type_name> ':' \s*]?
        <Tuple_payload>

    <Tuple_payload> ::=
        <tuple_list> | <tuple_d0>

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

    <attr_name> ::=
        <Name_payload>

    <tuple_d0> ::=
        d0

A C<Tuple> node represents a literal or selector invocation for a tuple
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.Tuple> value
whose attributes are defined by the C<Tuple_payload>.

Iff the C<Tuple_payload> is a C<tuple_list> then each name+expr pair of the
C<Tuple_payload> defines a named attribute of the new 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<DHTuple> rather than
C<Tuple>, then the C<value> node is interpreted simply as an C<Tuple> node
that is appropriately further restricted; the C<Tuple_payload> must specify
only deeply homogeneous typed attribute values.

Iff the C<Tuple_payload> is a C<tuple_d0> then the C<Tuple> node is
interpreted as the special value C<Tuple:d0> aka C<d0>, which is the only
C<Tuple> value with exactly zero attributes.  Note that this is just an
alternative syntax, as C<tuple_list> can select that value too.

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

Examples:

    Tuple:{}

    Tuple:d0  # same as previous #

    d0  # same as previous #

    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*
        [<type_name> ':' \s*]?
        <Database_payload>

    <Database_payload> ::=
        <Tuple_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<Tuple_payload>, it is in fact significantly further restricted, such
that every attribute value of the C<Database> can only be a C<DHRelation>.

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

=head2 Relation Selectors

Grammar:

    <Relation> ::=
        DH? Relation ':' \s*
        [<type_name> ':' \s*]?
        <Relation_payload>

    <Relation_payload> ::=
          <r_empty_body_payload>
        | <r_nonordered_attr_payload>
        | <r_ordered_attr_payload>
        | <relation_d0>

    <r_empty_body_payload> ::=
        '{' \s*
            [<attr_name> ** [\s* ',' \s*]]?
        \s* '}'

    <r_nonordered_attr_payload> ::=
        '{' \s*
            [<Tuple_payload> ** [\s* ',' \s*]]?
        \s* '}'

    <r_ordered_attr_payload> ::=
        '[' \s*
            [<attr_name> ** [\s* ',' \s*]]?
        \s* ']'
        ';' \s*
        '{' \s*
            [<ordered_tuple_attrs> ** [\s* ',' \s*]]?
        \s* '}'

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

    <relation_d0> ::=
        d0c0 | d0c1

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

Iff the C<Relation_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<Relation_payload> is a C<r_empty_body_payload> with at least
one C<attr_name> element, then it defines the attribute names of a
relation having zero tuples.

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

Iff the C<Relation_payload> is a C<r_ordered_attr_payload>, then:  The
new relation value's attribute names are defined by the
C<attr_name> elements, and the relation body's tuples' attribute values
are defined by the C<ordered_tuple_attrs> 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_tuple_attrs> elements must appear in the same order as their
corresponding attribute names appear in the collection of C<attr_name>
elements, as the names and values in the relation literal are matched up by
ordinal position here.

Iff the C<Relation_payload> is a C<relation_d0> then the C<Relation> node
is interpreted as one of the 2 special values C<Relation:d[0|1]> aka
C<d[0|1]>, which are the only C<Relation> values with exactly zero
attributes.  Note that this is just an alternative syntax, as other
C<Relation_payload> formats can select those values too.

If the C<value_kind> of a C<value> node is C<DHRelation> rather than
C<Relation>, then the C<value> node is interpreted simply as an
C<Relation> node that is appropriately further restricted; the
C<Relation_payload> specify only deeply homogeneous 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
a C<Relation> node distills to when it is beneath the context of a
C<depot> node, as it describes some semantics.

Examples:

    Relation:{}  # zero attrs + zero tuples #

    Relation:d0c0  # same as previous #

    Relation:{ x, y, z }  # 3 attrs + zero tuples #

    Relation:{ {} }  # zero attrs + 1 tuple #

    d0c1  # same as previous #

    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:

    <Set> ::=
        DH? Set ':' \s*
        [<type_name> ':' \s*]?
        <Set_payload>

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

A C<Set> node represents a literal or selector invocation for a set
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.Set> value
whose elements are defined by the C<Set_payload>.  Each C<expr> of the
C<Set_payload> defines a unary tuple of the new set; each
C<expr> defines the C<value> attribute of the tuple.  If the
C<value_kind> of a C<value> node is C<DHSet> rather than C<Set>, 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
a C<Set> node distills to when it is beneath the context of a
C<depot> 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:

    <Maybe> ::=
        DH? [Maybe | Single] ':' \s*
        [<type_name> ':' \s*]?
        <Maybe_payload>

    <Maybe_payload> ::=
        <maybe_list> | <maybe_nothing>

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

    <maybe_nothing> ::=
        nothing | '∅'

A C<Maybe> node represents a literal or selector invocation for a maybe
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.Maybe> value
whose elements are defined by the C<Maybe_payload>.

Iff the C<Maybe_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 tuple of the
new maybe, which is a 'single'; the C<expr> defines the C<value> attribute
of the tuple.  If the C<value_kind> of a C<value> node is C<DHMaybe> or
C<[|DH]Single> rather than C<Maybe>, then the C<value> node is further
restricted, either to having only deeply homogeneous resulting C<expr> or
to having exactly one C<expr>, as appropriate.

Iff the C<Maybe_payload> is a C<maybe_nothing> then the C<Maybe> node is
interpreted as the special value C<Maybe:nothing>, aka C<nothing>, aka
I<empty set>, aka C<∅>, which is the only C<Maybe> 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<[|DH]Maybe> when the C<Maybe_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
a C<Maybe> node distills to same as when C<Set> does.

Examples:

    Maybe:{ 'I know this one!' }

    Maybe:nothing

    Maybe:∅

    nothing

    ∅

=head2 Array Selectors

Grammar:

    <Array> ::=
        DH? Array ':' \s*
        [<type_name> ':' \s*]?
        <Array_payload>

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

A C<Array> node represents a literal or selector invocation for a
array value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Array> value whose elements are defined by the
C<Array_payload>.  Each C<expr> of the C<Array_payload> defines a binary
tuple of the new sequence; the C<expr> defines the C<value> attribute
of the tuple, and the C<index> attribute of the 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<DHArray> rather than C<Array>, 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
a C<Array> node distills to when it is beneath the context of a
C<depot> 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:

    <Bag> ::=
        DH? Bag ':' \s*
        [<type_name> ':' \s*]?
        <Bag_payload>

    <Bag_payload> ::=
          <bag_payload_counted_values>
        | <bag_payload_repeated_values>

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

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

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

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

Iff the C<Bag_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<Bag_payload> is a C<bag_payload_counted_values> with at least
one C<expr>/C<count>-pair element, then each pair defines a binary
tuple of the new bag; the C<expr> defines the C<value>
attribute of the tuple, and the C<count> defines the C<count>
attribute.

Iff the C<Bag_payload> is a C<bag_payload_repeated_values> with at least
one <expr> element, then each C<expr> contributes to a binary tuple
of the new bag; the C<expr> defines the C<value> attribute of the
tuple.  The bag has 1 tuple for every distinct (after
normalization or evaluation) C<expr> and C<expr>-derived value in the
C<Bag_payload>, and the C<count> attribute of that 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
a C<Bag> node distills to when it is beneath the context of a
C<depot> node, as it describes some semantics.

Further concerning C<bag_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
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 Interval Selectors

Grammar:

    <Interval> ::=
        DH? Interval ':' \s*
        [<type_name> ':' \s*]?
        <Interval_payload>

    <Interval_payload> ::=
        '{' \s*
            <min> \s* <interval_boundary_kind> \s* <max>
        \s* '}'

    <min> ::=
        <expr>

    <max> ::=
        <expr>

    <interval_boundary_kind> ::=
        '..' | '..^' | '^..' | '^..^'

An C<Interval> node represents a literal or selector invocation for an
interval value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Interval> value whose attributes are defined by the
C<Interval_payload>.  Each of C<min> and C<max> is an C<expr> node that
defines the C<min> and C<max> attribute value, respectively, of the new
interval.  Each of the 4 C<interval_boundary_kind> values C<..>, C<..^>,
C<^..>, C<^..^> corresponds to one of the 4 possible combinations of
C<excludes_min> and C<excludes_max> values that the new interval can have,
which in order are: C<[false,false]>, C<[false,true]>, C<[true,false]>,
C<[true,true]>.

See also the definition of the catalog data type
C<sys.std.Core.Type.Cat.IvlSelExprNodeSet>, a tuple of which is what
an C<Interval> node distills to when it is beneath the context of a
C<depot> node, as it describes some semantics.

Examples:

    Interval:{1..10}

    Interval:{2.7..^9.3}

    Interval:{'a'^..'z'}

    Interval:{ UTCInstant:[2002,12,6,,,] ^..^ UTCInstant:[2002,12,20,,,] }

=head1 DEPOT SPECIFICATION

Grammar:

    <depot> ::=
        <depot_catalog>
        [\s+ <depot_data>]?

    <depot_catalog> ::=
        'depot-catalog' \s+ <catalog>

    <depot_data> ::=
        'depot-data' \s+ <Database>

    <catalog__code_as_data> ::=
        <Database>

    <catalog__plain_rtn_inv> ::=
          <Database>
        | <depot_catalog_payload>

    <depot_catalog_payload> ::=
        '{' \s*
            [[
                  <subdepot>
                | <material>
                | <self_local_dbvar_type>
            ] ** \s+]?
        \s* '}'

    <subdepot> ::=
        subdepot \s+ <subdepot_declared_name> \s+ <depot_catalog_payload>

    <subdepot_declared_name> ::=
        <Name_payload>

    <self_local_dbvar_type> ::=
        'self-local-dbvar-type' \s+ <NameChain_payload>

A C<depot> node specifies a single complete depot, which is the widest
scope user-defined DBMS entity that is a completely self-defined, and
doesn't rely on any user-defined entities external to itself to be
unambiguously understood.  A C<depot> node defines a (possibly empty)
system catalog database, holding user material (routine and type)
definitions, plus optionally a normal-user-data database.

A C<depot_catalog_payload> node in the PTMD_STD grammar is interpreted as a
Muldis D C<sys.std.Core.Type.Cat.Depot> value (which is also a C<Database>
value) whose attributes are defined by its child elements.

A C<subdepot> node specifies a single public entity namespace under a depot
and all of the C<subdepot> nodes under a C<depot> comprise a hierarchy of
such namespaces.

But a C<subdepot> node doesn't have a corresponding data type for its
entire content like with a C<depot_catalog_payload>; rather, a C<subdepot>
node hierarchy is stored flattened in the system catalog, such that each
tuple of the C<subdepot> attribute from the parent C<Depot> names one
subdepot that exists, and all the subdepot's materials are flattened into
tuples of the materials-defining attributes of the C<Depot>.

A C<self_local_dbvar_type> node specifies what the normal-user-data
database has as its declared data type.  The value of the C<data> attribute
of the parent C<Depot> is determined from this node.  Iff
C<self_local_dbvar_type> is not specified then C<depot_data> must be
omitted; iff C<self_local_dbvar_type> is specified then C<depot_data> must
be present.  The most liberal value of C<self_local_dbvar_type> is simply
C<Database>, meaning C<depot_data> may define any database value at all.  A
C<depot_catalog_payload> may have at most 1 C<self_local_dbvar_type>.

Examples:

    # A completely empty depot that doesn't have a self-local dbvar. #
    depot-catalog {}

    # Empty depot with self-local dbvar with unrestricted allowed values. #
    depot-catalog {
        self-local-dbvar-type Database
    }
    depot-data Database:{}

    # A depot having just one function and no dbvar. #
    depot-catalog {
        public function cube (Int <-- $topic : Int) {
            $topic I^ 3
        }
    }

=head1 MATERIAL SPECIFICATION

Grammar:

    <material> ::=
          <function>
        | <updater>
        | <procedure>
        | <scalar_type>
        | <nonscalar_type>
        | <union_type>
        | <subset_type>

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

A C<material> node in the PTMD_STD grammar corresponds directly to a tuple
of a (routine or type defining) attribute of a value of the catalog data
type C<sys.std.Core.Type.Cat.Depot>, which is how a material specification
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<material> nodes corresponds to a set of said attribute tuples,
one attribute tuple per C<material> node.  In the nonsugared form, every
C<material> node has an explicitly designated name, 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 material 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 material nodes, especially so when the C<material> in
question is a simple function or type that is only being used in one place,
such as a typical C<value-filter> function or a typical subset type.

When a C<material> node is contained within another C<material> node, the
first material is conceptually part of the implementation of the second
material; the first material is hereafter referred to as an I<inner>
material for this inter-material relationship.  When a C<material> node is
I<not> contained within any other C<material> node, but rather is directly
contained within a C<depot_catalog_payload> node, then this material is
hereafter referred to as an I<outer> material.  Both inner and outer
C<material> nodes may contain 0..N other (inner) C<material> nodes.

When a C<material> node defines an outer material C<foo> directly within a
subdepot (or depot) C<bar>, and C<foo> has no child inner materials, then
the material definition will be stored in the system catalog exactly as
conceived, as a new material named C<foo> directly in the subdepot C<bar>.
For example, the outer material will have the name C<dep.lib.bar.foo>.

In contrast, when said C<material> node has at least one child inner
material C<baz>, then what happens in the system catalog instead is that a
new subdepot named C<foo> is created directly in the subdepot C<bar> and
every one of the whole hierarchy of said C<material> nodes is stored
directly in the subdepot C<foo>; the outer material is stored under the
name that is the empty string, and its inner materials are stored under
their own names.  For example, the outer material will have the name
C<dep.lib.bar.foo.""> and the inner will be named C<dep.lib.bar.foo.baz>.
Such a material hierarchy is stored in a flat namespace so it is required
for all inner materials having a common outer material to have distinct
declaration names, none of which are the empty string, regardless of
whether any of them was declared inside another inner material node or
directly inside the common outer node.

It is mandatory for outer C<material> nodes to have explicitly specified
declaration names, because they are expected to be invoked by name in the
general case, like any public routine or type.  An inner C<material> may
optionally have an explicitly specified declaration name, for either
self-documentation purposes or in case it might be invoked by name; however
an inner C<material> may also be anonymous, in which case it may only be
used inline with its declaration, or by way of a C<MaterialRef> value which
is defined inline with the material's declaration.  When an inner material
is declared as anonymous, it still actually has a name in the system
catalog (I<all> materials in the system catalog are named), but that name
is generated by the PTMD_STD parser; strictly speaking this material could
still be invoked by that name like an explicitly named one, but that would
not be a good practice; use explicit names if you want to invoke by name.
Strictly speaking, the algorithm to generate material names should be fully
deterministic, but the names would be non-descriptive so akin to random.

=head2 Material Specification Common Elements

Every material has 2-4 elements, illustrated by this grammar:

    <x_material> ::=
        <named_material> | <anon_material>

    <named_material> ::=
        [<priv_or_pub> \s+]?
        <material_kind> \s+ <material_declared_name> \s+ <material_payload>

    <anon_material> ::=
        <material_kind> \s+ <material_payload>

    <material_kind> ::=
          function
            | [type | state | transition] '-constraint'
            | 'named-value'
            | 'possrep-map'
            | 'virtual-attr-map'
            | 'order-determination'
            | 'value-' [filter | map | reduction]
        | updater
        | procedure
        | 'scalar-type'
        | 'nonscalar-type'
        | 'union-type'
        | 'subset-type'

    <priv_or_pub> ::=
        private | public

    <material_declared_name> ::=
        <Name_payload>

    <material_payload> ::=
          <function_payload>
        | <updater_payload>
        | <procedure_payload>
        | <scalar_type_payload>
        | <nonscalar_type_payload>
        | <union_type_payload>
        | <subset_type_payload>

So a C<x_material>|C<material> node has 2-4 elements in general:

=over

=item C<material_kind>

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

=item C<priv_or_pub>

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

=item C<material_declared_name>

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

=item C<material_payload>

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

=back

For material examples, see the subsequent documentation sections.

=head2 Function Specification

I<TODO.>

=head2 Updater Specification

I<TODO.>

=head2 Procedure Specification

I<TODO.>

=head2 Scalar Type Specification

I<TODO.>

=head2 Nonscalar Type Specification

I<TODO.>

=head2 Union Type Specification

I<TODO.>

=head2 Subset Type Specification

I<TODO.>

=head1 GENERIC VALUE EXPRESSIONS

Grammar:

    <expr__plain_rtn_inv> ::=
        <expr_core_options>

    <expr__rtn_inv_alt_syn> ::=
          <expr_core_options>
        | <func_invo_alt_syntax>

    <expr_core_options> ::=
          <delim_expr>
        | <expr_name>
        | <named_expr>
        | <value>
        | <accessor>
        | <func_invo>
        | <if_else_expr>
        | <given_when_def_expr>
        | <lib_entity_ref_selector>

    <delim_expr> ::=
        '(' \s* <expr> \s* ')'

    <expr_name> ::=
        <data_sigil> <Name_payload>

    <data_sigil> ::=
        '$'

    <named_expr> ::=
        <expr_name> \s+ <infix_bind_op> \s+ <expr>

    <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 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 tuples, one
attribute tuple 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 a C<delim_expr>, then it is interpreted simply as if it
were its child C<expr> element; the I<only> reason that the C<delim_expr>
grammar element exists is to assist the parser in determining the
boundaries of an C<expr> where code otherwise might be ambiguous or be
interpreted differently than desired due to nesting precedence rules (see
L</NESTING PRECEDENCE RULES> for more about those).  There is never a
distinct node in a parser's output for a C<delim_expr> itself.

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 the C<expr> element of the
C<named_expr> is being declared with an explicit name, and the C<expr_name>
element of the C<named_expr> is that name.  But if the C<expr> element of
the C<named_expr> is an C<expr_name> (or a C<named_expr> I<TODO: or a
C<param> >), then the C<named_expr> is in fact declaring a new node itself
(rather than simply naming its child node), which is a tuple of a Muldis D
C<sys.std.Core.Type.Cat.AccExprNodeSet> value; the new node is simply
declaring an alias for another node, namely the C<expr> element.

Examples:

    # an expr_name node #
    $foo_expr

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

=head2 Generic Expression Attribute Accessors

Grammar:

    <accessor> ::=
        <acc_via_named> | <acc_via_anon>

    <acc_via_named> ::=
        <data_sigil> <NameChain_payload>

    <acc_via_anon> ::=
        <expr> \s* '.' \s* <DeclNameChain_payload>

An C<accessor> node represents an accessor or alias for an attribute of
another, tuple-valued expression node.  It is interpreted as a tuple of a
Muldis D C<sys.std.Core.Type.Cat.AccExprNodeSet> value.  If an C<accessor>
is an C<acc_via_named>, then the C<NameChain_payload> element specifies the
C<target> attribute of the new C<AccExprNodeSet>.  If an C<accessor> is an
C<acc_via_anon>, then the C<target> is derived from a catenation of the
node name that C<expr> has (explicitly or that will be generated for it by
the parser) with the C<DeclNameChain_payload> in that order.  Note that an
C<acc_via_anon> whose C<expr> is an C<expr_name> is also an
C<acc_via_named>, and vice-versa.

Examples:

    # an accessor node of a named tuple-valued node #
    $foo_t.bar_attr

    # an accessor node of an anonymous tuple-valued node #
    sdp.lib.tuple_res_func( $arg ).quux_attr

=head2 Generic Function Invocation Expressions

Grammar:

    <func_invo> ::=
        <routine_name> <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> ::=
        <Name_payload>

    <anon_ro_arg> ::=
        <expr>

A C<func_invo> node represents the result of invoking a named
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>,
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>,
these 2 special cases apply (similar to the prior-mentioned latter
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 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
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 'topic' param, two optional #
    sdp.lib.barfunc( $mand_arg, oa1 => $opt_arg1, oa2 => $opt_arg2 )

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

    # a user-defined 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> ::=
        [
              [if \s+ <if_expr> \s+ then \s+ <then_expr> \s+ else \s+]*
            | [<if_expr> \s+ '??' \s+ <then_expr> \s+ '!!' \s+]*
        ]
        <else_expr>

    <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 = ∅ or $y = ∅ then ∅
        else s ((v $x) I+ ((v $y) I^ 3)

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

    'My answer is: ' T~ ($maybe ?? 'yes' !! 'no')

=head2 Generic Given-When-Default Expressions

Grammar:

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

    <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>
        | <upd_ref>
        | <proc_ref>
        | <type_ref>
        | <ord_det_func_ref>

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

    <upd_ref> ::=
        'U->' <routine_name>

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

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

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

A C<[func|upd|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.MaterialRefSelExprNodeSet> value, which when
evaluated at runtime would result in a C<sys.std.Core.Type.Cat.MaterialRef>
value.  The C<[routine|type]_name> element specifies the C<referencing>
attribute of the new C<sys.std.Core.Type.Cat.MaterialRefSelExprNodeSet>,
which is the name of the routine or type being invoked by way of the new
reference value.

Examples:

    F->sdp.lib.filter

    U->sdp.lib.swap

    P->sdp.lib.try_block

    T->sdp.lib.foo_type

    ODF->sdp.lib.order_bars

=head1 FUNCTION INVOCATION ALTERNATE SYNTAX EXPRESSIONS

Grammar:

    <func_invo_alt_syntax> ::=
          <comm_infix_reduce_op_invo>
        | <noncomm_infix_reduce_op_invo>
        | <sym_dyadic_infix_op_invo>
        | <nonsym_dyadic_infix_op_invo>
        | <monadic_prefix_op_invo>
        | <monadic_postfix_op_invo>
        | <postcircumfix_op_invo>
        | <rat_op_invo_with_round>
        | <ord_compare_op_invo>
        | ...

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

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> ::=
        <expr> ** [\s+ <comm_infix_reduce_op> \s+]

    <comm_infix_reduce_op ::=
          and | '∧' | or | '∨' | xnor | '↔' | iff | xor | '⊻' | '↮'
        | 'I+' | 'I*'
        | 'N+' | 'N*'
        | '∪' | 'R+' | union | '∩' | 'R*' | intersect
        | '∆' | 'R%' | exclude | symdiff
        | '⋈' | join | '×' | times | 'cross-join'

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 (set or 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<Set> or C<Bag> 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.

Some of the keywords are aliases for each other:

    keyword | aliases
    --------+--------
    and     | ∧
    or      | ∨
    xnor    | ↔ iff
    xor     | ⊻ ↮
    ∪       | R+ union
    ∩       | R* intersect
    ∆       | R% exclude symdiff
    ⋈       | join
    ×       | times cross-join

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] } )
    xnor -> Bool.xnor( Bag:{ $expr[0], ..., $expr[n] } )
    xor  -> 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] } )
    ∪    -> Core.Relation.union( Set:{ $expr[0], ..., $expr[n] } )
    ∩    -> Core.Relation.intersection( Set:{ $expr[0], ..., $expr[n] } )
    ∆    -> Relation.exclusion( Bag:{ $expr[0], ..., $expr[n] } )
    ⋈    -> Core.Relation.join( Set:{ $expr[0], ..., $expr[n] } )
    ×    -> Core.Relation.product( Set:{ $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 } ∪ Set:{ 4, 5, 6 } ∪ Set:{ 0, 9 }

    Set:{ 1, 3, 5, 7, 9 } ∩ Set:{ 3, 4, 5, 6, 7, 8 } ∩ Set:{ 2, 5, 9 }

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

Grammar:

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

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

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 (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<Array> 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.
Exception: with some of these, the actual C<func_arg_list> derived from
this has 2 actual arguments, the first a collection and the second taking a
different type of value, from the last op input list element.

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~    -> Array.catenation( Array:{ $expr[0], ..., $expr[n] } )

    //    -> Set.Maybe.attr_or_value(
                Array:{ $expr[0], ..., $expr[n-1] }, value => $expr[n] )
    //d   -> Set.Maybe.attr_or_default(
                Array:{ $expr[0], ..., $expr[n-1] }, default => $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 ]

    $a // $b // 42

    $a //d $b //d T->sdp.lib.foo_type

=head2 Simple Symmetric Dyadic Infix Operators

Grammar:

    <sym_dyadic_infix_op_invo> ::=
        <expr> \s+ <sym_dyadic_infix_op> \s+ <expr>

    <sym_dyadic_infix_op> ::=
          '=' | '≠' | '!='
        | nand | '⊼' | '↑' | nor | '⊽' | '↓'
        | 'I|-|' | 'N|-|'

A C<sym_dyadic_infix_op_invo> node is for using infix notation to invoke a
symmetric 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<sym_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<sym_dyadic_infix_op_invo>
supply the values of those arguments, and which arguments get which C<expr>
isn't significant.

Some of the keywords are aliases for each other:

    keyword | aliases
    --------+--------
    ≠       | !=
    nand    | ⊼ ↑
    nor     | ⊽ ↓

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] )
    nand -> Bool.nand( $expr[0], $expr[1] )
    nor  -> Bool.nor( $expr[0], $expr[1] )
    I|-| -> Integer.abs_diff( $expr[0], $expr[1] )
    N|-| -> Rational.abs_diff( $expr[0], $expr[1] )

Examples:

    $foo = $bar

    $foo ≠ $bar

    false nand true

    15 I|-| 17

    7.5 N|-| 9.0

=head2 Simple Non-symmetric Dyadic Infix Operators

Grammar:

    <nonsym_dyadic_infix_op_invo> ::=
        <lhs> \s+ <nonsym_dyadic_infix_op> \s+ <rhs>

    <lhs> ::=
        <expr>

    <rhs> ::=
        <expr>

    <nonsym_dyadic_infix_op> ::=
        | isa | '!isa' | 'not-isa' | as | asserting
        | imp | '→' | implies | nimp | '↛' | if | '←' | nif | '↚'
        | 'I-' | 'I/' | '%' | mod | 'I^'
        | 'N-' | 'N/'
        | Bx | Tx | Ax
        | '∈' | '∉' | '∋' | '∌'
        | 'S∈' | 'S∉' | 'S∋' | 'S∌'
        | 'B∈' | 'B∉' | 'B∋' | 'B∌'
        | '⊆' | '⊈' | '⊇' | '⊉'
        | '⊂' | '⊄' | '⊃' | '⊅'
        | '∖' | 'R-' | minus | except
        | '⊿' | '!matching' | 'not-matching' | antijoin | semiminus
        | '⋉' | matching | semijoin
        | '÷' | 'R/' | divideby
        | like | '!like' | 'not-like'

A C<nonsym_dyadic_infix_op_invo> node is for using infix notation to
invoke a non-symmetric dyadic operator function.  Such a function takes
exactly 2 arguments, which are the inputs of the operation; the inputs
and the result may possibly be all of the same type, or they might all be
of different types.  A single C<nonsym_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<nonsym_dyadic_infix_op_invo> supply the values of those arguments, which
are associated in the appropriate sequence.

Some of the keywords are aliases for each other:

    keyword | aliases
    --------+--------
    !isa    | not-isa
    imp     | → implies
    nimp    | ↛
    if      | ←
    nif     | ↚
    %       | mod
    ∖       | R- minus except
    ⊿       | !matching not-matching antijoin semiminus
    ⋉       | matching semijoin
    ÷       | R/ divideby
    !like   | not-like

Currently the alternate syntaxes for 20 functions, those testing set
membership or sub/superset relationships, only come in versions that use
trans-ASCII characters; if you are stuck using plain ASCII then you'll just
have to use the generic function invocation syntax to invoke them for now.
Plain ASCII infix syntax that is reasonable is yet to be determined.

This table indicates which function is invoked by each keyword:

    isa  -> Core.Universal.is_value_of_type( $lhs, type => $rhs )
    !isa -> Core.Universal.is_not_value_of_type( $lhs, type => $rhs )
    as   -> Core.Universal.treated( $lhs, as => $rhs )
    asserting -> Core.Universal.assertion( $lhs, is_true => $rhs )
    imp  -> Bool.imp( $lhs, $rhs )
    nimp -> Bool.nimp( $lhs, $rhs )
    if   -> Bool.if( $lhs, $rhs )
    nif  -> Bool.nif( $lhs, $rhs )
    I-   -> Integer.diff( 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.diff( minuend => $lhs, subtrahend => $rhs )
    N/   -> Rational.quotient( dividend => $lhs, divisor => $rhs )
    Bx   -> Blob.replication( $lhs, count => $rhs )
    Tx   -> Text.replication( $lhs, count => $rhs )
    Ax   -> Array.replication( $lhs, count => $rhs )
    ∈    -> Core.Tuple.is_member( t => $lhs, r => $rhs )
    ∉    -> Core.Tuple.is_not_member( t => $lhs, r => $rhs )
    ∋    -> Core.Relation.has_member( r => $lhs, t => $rhs )
    ∌    -> Core.Relation.has_not_member( r => $lhs, t => $rhs )
    S∈   -> Set.value_is_member( value => $lhs, set => $rhs )
    S∉   -> Set.value_is_not_member( value => $lhs, set => $rhs )
    S∋   -> Set.has_member( set => $lhs, value => $rhs )
    S∌   -> Set.has_not_member( set => $lhs, value => $rhs )
    B∈   -> Bag.value_is_member( value => $lhs, bag => $rhs )
    B∉   -> Bag.value_is_not_member( value => $lhs, bag => $rhs )
    B∋   -> Bag.has_member( bag => $lhs, value => $rhs )
    B∌   -> Bag.has_not_member( bag => $lhs, value => $rhs )
    ⊆    -> Core.Relation.is_subset( $lhs, $rhs )
    ⊈    -> Core.Relation.is_not_subset( $lhs, $rhs )
    ⊇    -> Core.Relation.is_superset( $lhs, $rhs )
    ⊉    -> Core.Relation.is_not_superset( $lhs, $rhs )
    ⊂    -> Relation.is_proper_subset( $lhs, $rhs )
    ⊄    -> Relation.is_not_proper_subset( $lhs, $rhs )
    ⊃    -> Relation.is_proper_superset( $lhs, $rhs )
    ⊅    -> Relation.is_not_proper_superset( $lhs, $rhs )
    ∖    -> Core.Relation.diff( source => $lhs, filter => $rhs )
    ⊿    -> Core.Relation.semidiff( source => $lhs, filter => $rhs )
    ⋉    -> Core.Relation.semijoin( source => $lhs, filter => $rhs )
    ÷    -> Core.Relation.quotient( dividend => $lhs, divisor => $rhs )

    like  -> sys.std.Text.is_like( look_in => $lhs, look_for => $rhs )
    !like -> sys.std.Text.is_not_like( look_in => $lhs, look_for => $rhs )

Note that while the C<is[|_not]_like> functions also have an optional third
parameter C<escape>, you will have to use a C<func_invo> node to exploit
it; for simplicity, the infix C<like> and C<!like> don't support that
customization; but most actual uses of like/etc don't use C<escape> anyway.

Examples:

    $bar isa T->sdp.lib.foo_type

    $bar !isa T->sdp.lib.foo_type

    $scalar as T->Int

    $int asserting ($int ≠ 0)

    true implies false

    34 I- 21

    5 I/ 3

    5 % 3

    2 I^ 63

    9.2 N- 0.1

    1;101.01 N/ 1;11.0

    '-' Tx 80

    Set:{ 8, 4, 6, 7 } ∖ Set:{ 9, 0, 7 }

    Relation:[ x, y ];{ [ 5, 6 ], [ 3, 6 ] } ÷ Relation:{ { y => 6 } }

=head2 Simple Monadic Prefix Operators

Grammar:

    <monadic_prefix_op_invo> ::=
        <monadic_prefix_op> \s+ <expr>

    <monadic_prefix_op> ::=
        d | not | '¬' | '!' | 'I||' | 'N||' | 'R#' | t | r | s | v

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.

Some of the keywords are aliases for each other:

    keyword | aliases
    --------+--------
    not     | ¬ !

This table indicates which function is invoked by each keyword:

    d   -> Core.Universal.default( of => $expr )
    not -> Core.Bool.not( $expr )
    I|| -> Integer.abs( $expr )
    N|| -> Rational.abs( $expr )
    R#  -> Core.Relation.cardinality( $expr )
    t   -> Core.Relation.Tuple_from_Relation( $expr )
    r   -> Core.Relation.Relation_from_Tuple( $expr )
    s   -> Set.Maybe.single( value => $expr )
    v   -> Set.Maybe.attr( $expr )

Examples:

    d T->sdp.lib.foo_type

    not true

    I|| -23

    N|| -4.59

    R# Set:{ 5, -1, 2 }

    t $relvar

    r $tupvar

    s ((v $a) N+ (v $b))

=head2 Simple Monadic Postfix Operators

Grammar:

    <monadic_postfix_op_invo> ::=
        <expr> \s+ <monadic_postfix_op>

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

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.inc( $expr )
    -- -> Integer.dec( $expr )
    I! -> Integer.factorial( $expr )

Examples:

    13 ++

    4 --

    5 I!

=head2 Simple Postcircumfix Operators

Grammar:

    <postcircumfix_op_invo> ::=
          <pcf_acc_op_invo>
        | <s_pcf_op_invo> | <t_pcf_op_invo> | <r_pcf_op_invo>
        | <pcf_ary_op_invo>

    <pcf_acc_op_invo> ::=
        <pcf_s_acc_op_invo> | <pcf_t_acc_op_invo>

    <pcf_s_acc_op_invo> ::=
        <expr> \s* '.${' [\s* <possrep_name> ';']? \s*
            <attr_name>
        \s* '}'

    <pcf_t_acc_op_invo> ::=
        <expr> \s* '.%{' \s* <attr_name> \s* '}'

    <s_pcf_op_invo> ::=
        <expr> \s* '${' [\s* <possrep_name> ';']? \s*
            [<pcf_projection> | <pcf_cmpl_proj>]
        \s* '}'

    <t_pcf_op_invo> ::=
        <expr> \s* '%{' \s*
            [
                  <pcf_rename>
                | <pcf_projection> | <pcf_cmpl_proj>
                | <pcf_wrap> | <pcf_cmpl_wrap>
                | <pcf_unwrap>
            ]
        \s* '}'

    <r_pcf_op_invo> ::=
        <expr> \s* '@{' \s*
            [
                  <pcf_rename>
                | <pcf_projection> | <pcf_cmpl_proj>
                | <pcf_wrap> | <pcf_cmpl_wrap>
                | <pcf_unwrap>
                | <pcf_group> | <pcf_cmpl_group>
                | <pcf_ungroup>
                | <pcf_count_per_group>
            ]
        \s* '}'

    <pcf_rename> ::=
        <pcf_rename_map>

    <pcf_rename_map> ::=
        [<atnm_after> \s* '<-' \s* <atnm_before>] ** [\s* ',' \s*]

    <atnm_after> ::=
        <attr_name>

    <atnm_before> ::=
        <attr_name>

    <pcf_projection> ::=
        <pcf_atnms>?

    <pcf_cmpl_proj> ::=
        '!' \s* <pcf_atnms>

    <pcf_atnms> ::=
        <attr_name> ** [\s* ',' \s*]

    <pcf_wrap> ::=
        '%' <outer_atnm> \s* '<-' \s* <inner_atnms>

    <pcf_cmpl_wrap> ::=
        '%' <outer_atnm> \s* '<-' \s* '!' \s* <cmpl_inner_atnms>

    <pcf_unwrap> ::=
         <inner_atnms> \s* '<-' \s* '%' <outer_atnm>

    <pcf_group> ::=
        '@' <outer_atnm> \s* '<-' \s* <inner_atnms>

    <pcf_cmpl_group> ::=
        '@' <outer_atnm> \s* '<-' \s* '!' \s* <cmpl_inner_atnms>

    <pcf_ungroup> ::=
         <inner_atnms> \s* '<-' \s* '@' <outer_atnm>

    <pcf_count_per_group> ::=
        '#@' <count_atnm> \s* '<-' \s* '!' \s* <cmpl_inner_atnms>

    <outer_atnm> ::=
        <attr_name>

    <count_atnm> ::=
        <attr_name>

    <inner_atnms> ::=
        <pcf_atnms>

    <cmpl_inner_atnms> ::=
        <pcf_atnms>

    <pcf_ary_op_invo> ::=
        <pcf_ary_acc_op_invo> | <pcf_ary_slice_op_invo>

    <pcf_ary_value_op_invo> ::=
        <expr> \s* '.[' \s* <index> \s* ']'

    <index> ::=
          <num_max_col_val> ';' \s* <nnint_body>
        | <d_nnint_body>

    <pcf_ary_slice_op_invo> ::=
        <expr> \s* '[' \s*
            <min_index> \s* <interval_boundary_kind> \s* <max_index>
        \s* ']'

    <min_index> ::=
        <index>

    <max_index> ::=
        <index>

A C<postcircumfix_op_invo> node is for using postcircumfix notation to
invoke a relational operator function whose operation involves deriving a
single tuple|relation from another single tuple|relation customized only by
further inputs that are attribute names.  Such a function takes exactly 2
(C<expr> and C<pcf_rename_map>|C<pcf_atnms>) or 3 (C<expr> and
C<outer_atnm> and C<inner_atnms>|C<cmpl_inner_atnms>) or 3 (C<expr> and
C<count_atnm> and C<cmpl_inner_atnms>) primary arguments, which are the
inputs of the operation.  A single C<postcircumfix_op_invo> node is
equivalent to a single C<func_invo> node whose C<func_arg_list> element
defines 2-3 arguments, and the 2-3
C<expr|pcf[_rename_map|atnms]|[outer|count]_atnm|[|cmpl_]inner_atnms>
elements of the C<postcircumfix_op_invo> supply the values of those
arguments, which are associated in the appropriate sequence.

This table indicates which function is invoked by each format-keyword:

    .${} -> Core.Scalar.attr( $expr, possrep => $possrep_name,
                name => $attr_name )
    .%{} -> Core.Tuple.attr( $expr, name => $attr_name )

    %{<-} -> Core.Tuple.rename( $expr,
                map => Relation:{
                    { after => $atnm_after[0], before => $atnm_before[0] },
                    ...,
                    { after => $atnm_after[n], before => $atnm_before[n] },
                } )
    @{<-} -> Core.Relation.rename( $expr,
                map => Relation:{
                    { after => $atnm_after[0], before => $atnm_before[0] },
                    ...,
                    { after => $atnm_after[n], before => $atnm_before[n] },
                } )

    ${}  -> Core.Scalar.projection( $expr, possrep => $possrep_name,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )
    %{}  -> Core.Tuple.projection( $expr,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )
    @{}  -> Core.Relation.projection( $expr,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )
    ${!} -> Core.Scalar.cmpl_proj( $expr, possrep => $possrep_name,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )
    %{!} -> Core.Tuple.cmpl_proj( $expr,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )
    @{!} -> Core.Relation.cmpl_proj( $expr,
                attr_names => Set:{ $pcf_atnms[0], ..., $pcf_atnms[n] } )

    %{%<-}  -> Core.Tuple.wrap( $expr, outer => $outer_atnm,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] } )
    @{%<-}  -> Core.Relation.wrap( $expr, outer => $outer_atnm,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] } )
    %{%<-!} -> Core.Tuple.cmpl_wrap( $expr, outer => $outer_atnm,
                   cmpl_inner => Set:{ $cmpl_inner_atnms[0], ... } )
    @{%<-!} -> Core.Relation.cmpl_wrap( $expr, outer => $outer_atnm,
                   cmpl_inner => Set:{ $cmpl_inner_atnms[0], ... } )
    %{<-%}  -> Core.Tuple.unwrap( $expr,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] },
                   outer => $outer_atnm )
    @{<-%}  -> Core.Relation.unwrap( $expr,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] },
                   outer => $outer_atnm )

    @{@<-}  -> Core.Relation.group( $expr, outer => $outer_atnm,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] } )
    @{@<-!} -> Core.Relation.cmpl_group( $expr, outer => $outer_atnm,
                   group_per => Set:{ $cmpl_inner_atnms[0], ... } )
    @{<-@}  -> Core.Relation.ungroup( $expr,
                   inner => Set:{ $inner_atnms[0], ..., $inner_atnms[n] },
                   outer => $outer_atnm )

    @{#@<-!} -> Core.Relation.cardinality_per_group( $expr,
                   count_attr_name => $count_atnm,
                   group_per => Set:{ $cmpl_inner_atnms[0], ... } )

    .[] -> Array.value( $expr, index => $index )
    []  -> Array.slice( $expr, index_interval => Interval:{
                $min_index $interval_boundary_kind $max_index } )

Examples:

    $birthday.${date;day}

    $pt.%{city}

    $pt%{pnum<-pno, locale<-city}

    $pr@{pnum<-pno, locale<-city}

    $birthday${date;year,month}

    $pt%{color,city}

    $pr@{color,city}

    $pt%{}  # null projection #

    $pr@{}  # null projection #

    $rnd_rule${!round_meth}  # radix,min_exp #

    $pt%{!pno,pname,weight}

    $pr@{!pno,pname,weight}

    $person%{%name <- fname,lname}

    $people@{%name <- fname,lname}

    $person%{%all_but_name <- !fname,lname}

    $people@{%all_but_name <- !fname,lname}

    $person%{fname,lname <- %name}

    $people@{fname,lname <- %name}

    $orders@{@vendors <- vendor}

    $orders@{@all_but_vendors <- !vendor}

    $orders@{vendor <- @vendors}

    $people@{#@count_per_age_ctry <- !age,ctry}

    $ary.[3]

    $ary[10..14]

=head2 Rational Operators That Do Rounding

Grammar:

    <rat_op_invo_with_round> ::=
        <rat_op_invo> \s+ <rounded_with_rule_clause>

    <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>
        'log-e'

    <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
involves 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 2 or 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 )
    log-e -> 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 log-e round RatRoundRule:[3,-5,to_floor]

=head2 Order Comparison Operators

Grammar:

    <ord_compare_op_invo> ::=
        <sca_ord_det_op_invo> | <gen_compare_op_invo>

    <sca_ord_det_op_invo> ::=
        <lhs> \s+ '<=>' \s+ <rhs>
            [\s+ <assuming_clause>]?
            [\s+ <reversed_clause>]?

    <gen_compare_op_invo> ::=
        [
              <compare_reduce_op_invo>
            | <dyadic_compare_op_invo>
            | <triadic_compare_op_invo>
        ]
        [\s+ <gen_compare_op_ordered_clause>]?

    <compare_reduce_op_invo> ::=
        <expr> ** [\s+ <compare_reduce_op> \s+]

    <compare_reduce_op ::=
        min | max

    <dyadic_compare_op_invo> ::=
        <lhs> \s+ <dyadic_compare_op> \s+ <rhs>

    <dyadic_compare_op> ::=
        <is_before_op> | <is_after_op> | <interval_membership_op>

    <is_before_op> ::=
        '<' | '≤' | '<='

    <is_after_op> ::=
        '>' | '≥' | '>='

    <interval_membership_op> ::=
        'I∈' | 'I∉' | 'I∋' | 'I∌'

    <triadic_compare_op_invo> ::=
        [[not | '!'] \s+]?
        <min> \s+ <is_before_op> \s+ <expr> \s+ <is_before_op> \s+ <max>

    <gen_compare_op_ordered_clause> ::=
        ordered \s+ <using_clause> | <ordered_by_clause>

An C<ord_compare_op_invo> node is for using infix notation to invoke an
order comparison operator function.  Such a function takes exactly 2
(C<lhs> and C<rhs>) or 3 (C<min> and C<expr> and C<max>) or N/2+ (C<expr>)
main op args, which are the inputs of the operation, plus 2 extra op args
(C<assuming> and C<reversed> for the C<< <=> >> op, or C<func> and
C<assuming> for any other op) which let you customize the semantics of the
operation.  A single C<ord_compare_op_invo> node is equivalent to a single
C<func_invo> node whose C<func_arg_list> element defines 2-N arguments, and
the C<expr|lhs|rhs|min|max|func|assuming|reversed> elements of the
C<ord_compare_op_invo> supply the values of those arguments, which are
associated in the appropriate sequence, except for the N-adic operators
which are commutative (and associative and idempotent) so the relative
order of the main op args isn't significant.  Details on the extra op args
are pending.

Some of the keywords are aliases for each other:

    keyword | aliases
    --------+--------
    ≤       | <=
    ≥       | >=
    ≤≤      | <=<=
    ≤<      | <=<
    <≤      | <<=
    !≤≤     | !<=<=
    !≤<     | !<=<
    !<≤     | !<<=

This table indicates which function is invoked by each keyword:

    <=> -> Core.Scalar.order( $lhs, $rhs )

    min -> Ordered.min( Set:{ $expr[0], ..., $expr[n] } )
    max -> Ordered.max( Set:{ $expr[0], ..., $expr[n] } )

    <   -> Ordered.is_before( $lhs, $rhs )
    >   -> Ordered.is_after( $lhs, $rhs )
    ≤   -> Ordered.is_before_or_same( $lhs, $rhs )
    ≥   -> Ordered.is_after_or_same( $lhs, $rhs )
    I∈  -> Ordered.is_member( value => $lhs, interval => $rhs )
    I∉  -> Ordered.is_not_member( value => $lhs, interval => $rhs )
    I∋  -> Interval.has_member( interval => $lhs, value => $rhs )
    I∌  -> Interval.has_not_member( interval => $lhs, value => $rhs )

    ≤≤  -> Ordered.is_member( value => $expr,
                interval => Interval:{ $min .. $max } )
    ≤<  -> Ordered.is_member( value => $expr,
                interval => Interval:{ $min ..^ $max } )
    <≤  -> Ordered.is_member( value => $expr,
                interval => Interval:{ $min ^.. $max } )
    <<  -> Ordered.is_member( value => $expr,
                interval => Interval:{ $min ^..^ $max } )
    !≤≤ -> Ordered.is_not_member( value => $expr,
                interval => Interval:{ $min .. $max } )
    !≤< -> Ordered.is_not_member( value => $expr,
                interval => Interval:{ $min ..^ $max } )
    !<≤ -> Ordered.is_not_member( value => $expr,
                interval => Interval:{ $min ^.. $max } )
    !<< -> Ordered.is_not_member( value => $expr,
                interval => Interval:{ $min ^..^ $max } )

Details regarding the extra op args is pending.  But most of the time you
wouldn't be using them, so just the main args represents typical usage.

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

    $foo <=> $bar

    $a min $b min $c

    $a max $b max $c

    $foo < $bar

    $foo > $bar

    $foo ≤ $bar

    $foo ≥ $bar

    $a I∈ Interval:{1..5}

    $min ≤ $foo ≤ $max

    $min ≤ $foo < $max

    not $min < $foo ≤ $max

    not $min < $foo < $max

=head1 NESTING PRECEDENCE RULES

This documentation section outlines Muldis D's PTMD_STD dialect's nesting
precedence rules, meaning how it accepts Muldis D code lacking explicit
expression delimiters and implicitly delimits the expressions therein, in a
fully deterministic manner.

Unlike many languages which can have over a dozen precedence levels, such
as Perl (about 24) or C, PTMD_STD only has about 8 precedence levels in the
interest of simplicity, and so you will likely have to use more explicit
expression delimiters to force the nesting precedence you want.  That 8
figure assumes the C<catalog_abstraction_level> pragma is
C<rtn_inv_alt_syn>; if it is C<plain_rtn_inv> instead, then 3 of the levels
can be eliminated, so then PTMD_STD has just 4; if it is C<code_as_data>
instead, then 3 more can be eliminated, leaving just 1.

Here we list the 8 levels from "tightest" to "loosest":

=over

=item *

The I<terms> and I<delimited expressions> and I<tagged delimiteds>, which
includes every kind of C<< <expr> >> that is also a C<< <value> >> (meaning
any C<< <opaque_value_literal> >> and C<< <coll_value_selector> >>), as
well as any C<< <non_value_comment> >> and
C<< <delim_expr> >> and C<< <expr_name> >> and C<< <func_invo>
>> and C<< <lib_entity_ref_selector> >>.  In general these are very simple
or are entirely or mostly surrounded by some kind of delimiters.  These are
non-associative or associativity is not applicable.

=item *

The I<accessors> and I<postcircumfix operators> and I<postfix operators>,
which includes every kind of C<< <accessor> >> and C<<
<postcircumfix_op_invo> >> and C<< <monadic_postfix_op_invo> >> and C<<
<postfix_rat_op_invo> >> and C<< <rat_op_invo> \s+
<rounded_with_rule_clause> >>.  These are left-associative.

=item *

Every C<< <ord_compare_op_invo> >> that is a C<< <triadic_compare_op_invo>
>>.  The C<< <triadic_compare_op_invo> >> have been special-cased with
their own higher precedence level so that, for example, C<< not $min < $foo
≤ $max >> could be recognizable as its own entity rather than the C<not
$min> or C<< $min < $foo >> substrings always being eaten on their own
before the larger entity has a chance to be considered.  These are
left-associative.

=item *

The I<prefix operators>, which includes every kind of
C<< <monadic_prefix_op_invo> >> and C<< <prefix_rat_op_invo> >>.  These are
right-associative.

=item *

The I<dyadic infix operators>, which includes every kind of C<<
<sym_dyadic_infix_op_invo> >> and C<< <nonsym_dyadic_infix_op_invo> >> and
C<< <infix_rat_op_invo> >> and every C<< <ord_compare_op_invo> >> that is
not also a C<< <triadic_compare_op_invo> >> or C<< <compare_reduce_op_invo>
>>.  These are left-associative.

=item *

The I<infix reduction operators>, which includes every kind of C<<
<comm_infix_reduce_op_invo> >> and C<< <noncomm_infix_reduce_op_invo> >>.
These are left-associative.

=item *

Every C<< <if_else_expr> >> and C<< <given_when_def_expr> >>.  The C<??!!>
form is right-associative, meaning that C<$a ?? $b !! $c ?? $d !! $e> will
parse as C<$a ?? $b !! ($c ?? $d !! $e)> (like most languages) and not as
C<($a ?? $b !! $c) ?? $d !! $e> (like PHP).  The C<if-then-else> and
C<given-when-default> forms are unambiguous for associativity.

=item *

Every C<< <named_expr> >>, that is, associating an explicit name with an
expression node/tree.  These are right-associative, meaning that given a
C<$a ::= $b ::= 5>, the expression node of value C<5> has the name C<b> and
another, alias node for C<b> has the name C<a>.

=back

Any imperative code that embeds a value expression has looser precedence
than all value expressions.

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT

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

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

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut