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

=head1 PREFACE

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

=head1 DESCRIPTION

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

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

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

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

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

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

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

=head1 GENERAL STRUCTURE

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

The grammar in this file is formatted as a Perl 6 grammar (see
L<http://perlcabal.org/syn/S05.html> for details) which could be used to
parse it, but it is only meant to be illustrative, and would need further
additions or changes to actually function in Perl 6.  The grammar consists
mainly of named I<tokens> which define matching rules.  A token's name is
declared as a bareword following the keyword C<token> and it is
subsequently referenced with C<< '<' and '>' >> delimiters.  Any other
bareword in a token definition consisting of alphanumerics is matched
literally, and all non-quoted whitespace is not significant.  Any pairs of
parenthesis (C<'(' and ')'>) in token definitions are capturing groups, and
each parser match by a pair corresponds to a capture I<node> or node
element in the concrete syntax tree resulting from the parse.

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

=head1 BOOTLOADER

Grammar:

    token bootloader {
        (
            <language_name>
            [<term_sep> [
                  <value>
                | <depot>
                | <boot_stmt> ** <term_sep>
            ]]?
        )
    }

    token term_sep { \s+ }

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

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

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

=head1 LANGUAGE NAME

Grammar:

    token language_name {
        (
            <ln_base_name>
            <value_node_elem_sep>
            <ln_base_authority>
            <value_node_elem_sep>
            <ln_base_version_number>
            <value_node_elem_sep>
            <ln_dialect>
            [
                <value_node_elem_sep>
                <ln_extensions>
            ]?
        )
    }

    token ln_base_name { (Muldis_D) }

    token ln_base_authority { <Name_payload> }

    token ln_base_version_number { <Name_payload> }

    token ln_dialect { (PTMD_STD) }

    token ln_extensions { <QTuple_payload> }

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

=over

=item C<ln_base_name>

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

=item C<ln_base_authority>

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

=item C<ln_base_version_number>

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

=item C<ln_dialect>

This is the dialect name; it is simply the bareword character string
C<PTMD_STD>.

=item C<ln_extensions>

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

=back

Examples:

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

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

=head1 VALUE LITERALS AND SELECTORS

Grammar:

    token value {
          <opaque_value_literal>
        | <coll_value_selector>
    }

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

    token coll_value_selector {
          <QScalar>
        | <QTuple>
        | <Database>
        | <QRelation>
        | <QSet>
        | <QMaybe>
        | <QArray>
        | <QBag>
    }

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

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

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

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

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

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

=head2 Value Literal Common Elements

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

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

    token x_value {
        (
            [
                <value_kind> <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <payload>
        )
    }

    token value_node_elem_sep { \s* ':' \s* }

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

    token type_name { <NameChain_payload> }

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

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

=over

=item C<value_kind>

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

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

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

=item C<type_name>

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

How a Muldis D parser treats a C<value> node with a C<type_name> element
depends on the wider context.  In the general case where the C<value> is an
C<expr> beneath the context of a C<depot> or C<boot_stmt> node, the
C<value> is treated as if it had an extra parent C<func_invo_expr> 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_expr> parent.

=item C<payload>

This is mandatory for all C<value>.

=back

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

=head1 OPAQUE VALUE LITERALS

=head2 Boolean Literals

Grammar:

    token Bool {
        (
            [(Bool) <value_node_elem_sep>]?
            <Bool_payload>
        )
    }

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

    token Order {
        (
            [(Order) <value_node_elem_sep>]?
            <Order_payload>
        )
    }

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

    token RatRoundMeth {
        (
            [
                (RatRoundMeth) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <RatRoundMeth_payload>
        )
    }

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

    token Int {
        (
            [
                (Int | NNInt | PInt) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <Int_payload>
        )
    }

    token Int_payload {
        (
              (<num_max_col_val>) <value_payload_elem_sep> (<int_body>)
            | <d_int_body>
        )
    }

    token value_payload_elem_sep { \s* ';' \s* }

    token num_max_col_val { <pint_head> }

    token int_body { [0 | \-?<pint_body>] }

    token pint_body { <pint_head> <pint_tail>? }

    token pint_head { <[ 1..9 A..Z ]> }

    token pint_tail { [[_?<[ 0..9 A..Z ]>+]+] ** <segment_sep> }

    token segment_sep { \s* '~' \s* }

    token d_int_body { [0 | \-?<d_pint_body>] }

    token d_pint_body { <d_pint_head> <d_pint_tail>? }

    token d_pint_head { <[ 1..9 ]> }

    token d_pint_tail { [[_?<[ 0..9 ]>+]+] ** <segment_sep> }

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:

    token Rat {
        (
            [
                (Rat | NNRat | PRat) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <Rat_payload>
        )
    }

    token Rat_payload {
        (
              (<num_max_col_val>) <value_payload_elem_sep> (<rat_body>)
            | <d_rat_body>
        )
    }

    token rat_body {
          <int_body>\.<pint_tail>
        | (<int_body>) \s* \/ \s* (<pint_body>)
        | (<int_body>) \s* \* \s* (<pint_body>) \s* \^ \s* (<int_body>)
    }

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

    token Blob {
        (
            [
                (Blob | OctetBlob) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <Blob_payload>
        )
    }

    token Blob_payload {
        ((<blob_max_col_val>) <value_payload_elem_sep> (<blob_body>))
    }

    token blob_max_col_val { <[137F]> }

    token blob_body {
        [
            <[']>
                (<[ 0..9 A..F ]>*)
            <[']>
        ] ** <segment_sep>
    }

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:

    token Text {
        (
            [
                (Text) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <Text_payload>
        )
    }

    token Text_payload {
        (
            [
                <[']>
                    ([ <-[\\\'\t\n\f\r]> | <escaped_char>]*)
                <[']>
            ] ** <segment_sep>
        )
    }

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

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

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

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

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

The meanings of the simple escape sequences are:

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

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

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

There is currently just one complex escape sequence, of the format C<<
\c<...> >>, that supports specifying characters in terms of their Unicode
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 codepoint number.  One reason for this
feature is to empower specifying exactly which sequence of codepoints you
want for a particular grapheme (which text editors tend to abstract away
when you write characters literally), and also it 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:

    token Name {
        (
            (Name) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <Name_payload>
        )
    }

    token Name_payload {
        (<nonquoted_name_str> | <quoted_name_str>)
    }

    token nonquoted_name_str { <[ a..z A..Z _ ]><[ a..z A..Z 0..9 _ - ]>* }

    token quoted_name_str {
        [
            <["]>
                ([ <-[\\\"\t\n\f\r]> | <escaped_char>]*)
            <["]>
        ] ** <segment_sep>
    }

    token NameChain {
        (
            (NameChain) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <NameChain_payload>
        )
    }

    token NameChain_payload {
        (<Name_payload> ** <name_chain_elem_sep>)
    }

    token name_chain_elem_sep { \s* '.' \s* }

    token DeclNameChain {
        (
            (DeclNameChain) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <DeclNameChain_payload>
        )
    }

    token DeclNameChain_payload {
        <NameChain_payload> | (<ord_list_open> <ord_list_close>)
    }

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 C<name_chain_elem_sep>
tokens (C<.>); each element of the sequence, in order, defines an element
of the C<array> possrep's attribute of the result C<NameChain> value.

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

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

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

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_name

    NameChain:fed.data.the_db.stats."samples by order"

    DeclNameChain:gene.sorted_person_name

    DeclNameChain:stats."samples by order"

    DeclNameChain:[]

=head2 Code Comment Literals

Grammar:

    token Comment {
        (
            [
                (Comment) <value_node_elem_sep>
                [<type_name> <value_node_elem_sep>]?
            ]?
            <Comment_payload>
        )
    }

    token Comment_payload {
        (
            [
                '#' ' '*
                    ([ <-[\\\#\t\n\f\r]> | <escaped_char>]*)
                ' '* '#'
            ] ** \s*
        )
    }

A C<Comment> node represents the text of a Muldis D code comment; it is a
character string type, that is disjoint from both C<Text> and C<Name>.  It
is interpreted as a Muldis D C<sys.std.Core.Type.Cat.Comment> value as
follows:

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

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

Examples:

    Comment:# This does something. #

    # So does this. #

=head2 TAI Temporal Literals

Grammar:

    token Instant {
        (
            (Instant) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <Instant_payload>
        )
    }

    token Instant_payload {
        <Rat_payload>
    }

    token Duration {
        (
            (Duration) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <Duration_payload>
        )
    }

    token Duration_payload {
        <Rat_payload>
    }

An C<Instant> node represents a single point in time which is specified in
terms of of atomic seconds; it is a rational numeric type, that is disjoint
from both C<Rat> and C<Duration>.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Instant> value as follows:  An C<Instant_payload> is
formatted and interpreted in the same way as a C<Rat_payload>.

A C<Duration> node represents a single amount of time (the difference
between two instants) which is specified in terms of of atomic seconds; it
is a rational numeric type, that is disjoint from both C<Rat> and
C<Instant>.  This node is interpreted as a Muldis D
C<sys.std.Core.Type.Duration> value as follows:  A C<Duration_payload> is
formatted and interpreted in the same way as a C<Rat_payload>.

Examples:

    Instant:1235556432.0

    Instant:854309115.0

    Duration:3600.0

    Duration:-50.0

    Duration:3.14159

    Duration:1;1011101101*10^-11011

    Duration:1/43

=head2 UTC and Float Temporal Literals

Grammar:

    token UTCInstant {
        (
            (UTC [Instant | DateTime | Date | Time]) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <UTCInstant_payload>
        )
    }

    token UTCInstant_payload {
        <UTCDuration_payload>
    }

    token FloatInstant {
        (
            (Float [Instant | DateTime | Date | Time])
                <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <FloatInstant_payload>
        )
    }

    token FloatInstant_payload {
        <UTCDuration_payload>
    }

    token UTCDuration {
        (
            (UTCDuration) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <UTCDuration_payload>
        )
    }

    token UTCDuration_payload {
        (
              (<num_max_col_val>) <value_payload_elem_sep>
                    (<utc_duration_body>)
            | <d_utc_duration_body>
        )
    }

    token utc_duration_body {
        <ord_list_open>
            [(<int_body>)? <list_elem_sep>] ** 5
            (<rat_body>)
        <ord_list_close>
    }

    token d_utc_duration_body {
        <ord_list_open>
            [(<d_int_body>)? <list_elem_sep>] ** 5
            (<d_rat_body>)
        <ord_list_close>
    }

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

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

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

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

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

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

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

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

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

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

Examples:

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

    UTCInstant:[2002,12,16,,,] # a UTCDate #

    UTCInstant:[,,,14,2,29.0] # a UTCTime #

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

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

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

=head2 Low Level Integer String Literals

Grammar:

    token String {
        (
            (String | BString | OString | UCPString) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <String_payload>
        )
    }

    token String_payload {
        (
              (<num_max_col_val>) <value_payload_elem_sep> (<string_body>)
            | <d_string_body>
        )
    }

    token string_body {
        <ord_list_open>
            ([(<int_body>) ** <list_elem_sep>]?)
        <ord_list_close>
    }

    token d_string_body {
        <ord_list_open>
            ([(<d_int_body>) ** <list_elem_sep>]?)
        <ord_list_close>
    }

    token ord_list_open { \s* '[' \s* }

    token ord_list_close { \s* ']' \s* }

    token list_elem_sep { \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:F;[50,65,72,6C] # Unicode codepoints = 'Perl' #

    String:[80,101,114,109] # same thing #

=head1 COLLECTION VALUE SELECTORS

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

=head2 Scalar Selectors

Grammar:

    token QScalar {
        (
            (Q? Scalar) <value_node_elem_sep>
            <type_name> <value_node_elem_sep>
            <QScalar_payload>
        )
    }

    token QScalar_payload {
        (<possrep_name> <value_payload_elem_sep> <possrep_attrs>)
    }

    token possrep_name { <Name_payload> }

    token possrep_attrs { <QTuple_payload> }

A C<QScalar> node represents a literal or selector invocation for a
quasi-scalar subtype value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QScalar> subtype value whose declared type is specified
by the node's (mandatory for C<QScalar>) C<type_name> and whose attributes
are defined by the C<QScalar_payload>.  The C<possrep_attrs> is interpreted
specifically as attributes of the declared type's possrep which is
specified by the C<possrep_name>.  Each name+expr pair of the
C<possrep_attrs> defines a named possrep attribute of the new quasi-scalar;
the pair's name and expr specify, respectively, the possrep attribute name,
and the possrep attribute value.  If the C<value_kind> of a C<value> node
is C<Scalar> rather than C<QScalar>, then the C<value> node is interpreted
simply as an C<QScalar> node that is appropriately further restricted; the
C<type_name> must name a C<Scalar> subtype, and the C<possrep_attrs> must
not specify any quasi- typed attribute values.

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

Examples:

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

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

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

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

=head2 Tuple Selectors

Grammar:

    token QTuple {
        (
            (Q? Tuple) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QTuple_payload>
        )
    }

    token QTuple_payload {
        <nonord_list_open>
            ([(<Name_payload> <pair_elem_sep> <expr>) ** <list_elem_sep>]?)
        <nonord_list_close>
    }

    token nonord_list_open { \s* '{' \s* }

    token nonord_list_close { \s* '}' \s* }

    token pair_elem_sep { \s* '=>' \s* }

A C<QTuple> node represents a literal or selector invocation for a
quasi-tuple value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QTuple> value whose attributes are defined by the
C<QTuple_payload>.  Each name+expr pair of the C<QTuple_payload> defines a
named attribute of the new quasi-tuple; the pair's name and expr specify,
respectively, the attribute name, and the attribute value.  If the
C<value_kind> of a C<value> node is C<Tuple> rather than C<QTuple>, then
the C<value> node is interpreted simply as an C<QTuple> node that is
appropriately further restricted; the C<QTuple_payload> must not specify
any quasi- typed attribute values.

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

Examples:

    Tuple:{}

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

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

=head2 Database Selectors

Grammar:

    token Database {
        (
            (Database) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <Database_payload>
        )
    }

    token Database_payload {
        <QTuple_payload>
    }

A C<Database> node represents a literal or selector invocation for a
'database' value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.Database> value whose attributes are defined by the
C<Database_payload>.  Each name+relation pair of the C<Database_payload>
defines a named attribute of the new 'database'; the pair's name and
relation specify, respectively, the attribute name, and the attribute
value.  While this grammar mentions that C<Database_payload> is a
C<QTuple_payload>, it is in fact significantly further restricted, such
that every attribute value of the C<Database> can only be a relation.

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

=head2 Relation Selectors

Grammar:

    token QRelation {
        (
            (Q? Relation) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QRelation_payload>
        )
    }

    token QRelation_payload {
          <r_empty_qbody_payload>
        | <r_nonordered_qattr_payload>
        | <r_ordered_qattr_payload>
    }

    token r_empty_qbody_payload {
        <nonord_list_open>
            ([<Name_payload> ** <list_elem_sep>]?)
        <nonord_list_close>
    }

    token r_nonordered_qattr_payload {
        <nonord_list_open>
            ([<QTuple_payload> ** <list_elem_sep>]?)
        <nonord_list_close>
    }

    token r_ordered_qattr_payload {
        (
            <ord_list_open>
                ([<Name_payload> ** <list_elem_sep>]?)
            <ord_list_close>
            <value_payload_elem_sep>
            <nonord_list_open>
                ([<ordered_qtuple_qattrs> ** <list_elem_sep>]?)
            <nonord_list_close>
        )
    }

    token ordered_qtuple_qattrs {
        <ord_list_open>
            ([<expr> ** <list_elem_sep>]?)
        <ord_list_close>
    }

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

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

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

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

Iff the C<QRelation_payload> is a C<r_ordered_qattr_payload>, then:  The
new quasi-relation value's attribute names are defined by the
C<Name_payload> elements, and the relation body's tuples' attribute values
are defined by the C<ordered_qtuple_qattrs> elements.  This format is meant
to be the most compact of the generic relation selector formats, as the
attribute names only appear once for the relation rather than repeating for
each tuple.  As a trade-off, the attribute values per tuple from all of the
C<ordered_qtuple_attrs> elements must appear in the same order as their
corresponding attribute names appear in the collection of C<Name_payload>
elements, as the names and values in the relation literal are matched up by
ordinal position here.

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

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

Examples:

    Relation:{}  # zero attrs + zero tuples #

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

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

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

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

=head2 Set Selectors

Grammar:

    token QSet {
        (
            (Q? Set) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QSet_payload>
        )
    }

    token QSet_payload {
        <nonord_list_open>
            ([<expr> ** <list_elem_sep>]?)
        <nonord_list_close>
    }

A C<QSet> node represents a literal or selector invocation for a quasi-set
value.  It is interpreted as a Muldis D C<sys.std.Core.Type.QSet> value
whose elements are defined by the C<QSet_payload>.  Each C<expr> of the
C<QSet_payload> defines a unary quasi-tuple of the new quasi-set; each
C<expr> defines the C<value> attribute of the quasi-tuple.  If the
C<value_kind> of a C<value> node is C<Set> rather than C<QSet>, then the
C<value> node is further restricted.

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

Examples:

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

    Set:{
        3,
        16,
        85
    }

=head2 Maybe Selectors

Grammar:

    token QMaybe {
        (
            (Q? (Maybe | Single)) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QMaybe_payload>
        )
    }

    token QMaybe_payload {
        (<maybe_list> | <maybe_nothing>)
    }

    token maybe_list {
        <nonord_list_open> <expr> <nonord_list_close>
    }

    token maybe_nothing {
        nothing
    }

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

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

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

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

Examples:

    Maybe:{ 'I know this one!' }

    Maybe:nothing

    nothing

=head2 Array Selectors

Grammar:

    token QArray {
        (
            (Q? Array) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QArray_payload>
        )
    }

    token QArray_payload {
        <ord_list_open>
            ([<expr> ** <list_elem_sep>]?)
        <ord_list_close>
    }

A C<QArray> node represents a literal or selector invocation for a
quasi-array value.  It is interpreted as a Muldis D
C<sys.std.Core.Type.QArray> value whose elements are defined by the
C<QArray_payload>.  Each C<expr> of the C<QArray_payload> defines a binary
quasi-tuple of the new sequence; the C<expr> defines the C<value> attribute
of the quasi-tuple, and the C<index> attribute of the quasi-tuple is
generated such that the first C<expr> gets an C<index> of zero and
subsequent ones get consecutive higher integer values.  If the
C<value_kind> of a C<value> node is C<Array> rather than C<QArray>, then
the C<value> node is further restricted.

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

Examples:

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

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

=head2 Bag Selectors

Grammar:

    token QBag {
        (
            (Q? Bag) <value_node_elem_sep>
            [<type_name> <value_node_elem_sep>]?
            <QBag_payload>
        )
    }

    token QBag_payload {
          <qbag_payload_counted_values>
        | <qbag_payload_repeated_values>
    }

    token qbag_payload_counted_values {
        <nonord_list_open>
            ([(<expr> <pair_elem_sep> <count>) ** <list_elem_sep>]?)
        <nonord_list_close>
    }

    token count {
        (
              (<num_max_col_val>) <value_payload_elem_sep> (<pint_body>)
            | <d_pint_body>
        )
    }

    token qbag_payload_repeated_values {
        <nonord_list_open>
            ([<expr> ** <list_elem_sep>]?)
        <nonord_list_close>
    }

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

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

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

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

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

Examples:

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

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

=head1 DEPOT DECLARATION

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

Grammar:

    token depot {
        (depot)
        <nonord_list_open>
            <depot_catalog>
            <depot_data>?
        <nonord_list_close>
    }

=head1 BOOTLOADER STATEMENT

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

Grammar:

    token boot_stmt {
        (
              <generic_boot_stmt>
            | ...
        )
    }

    token generic_boot_stmt
        (boot_stmt)
        <value_node_elem_sep>
        <imperative_routine_name>
        <value_node_elem_sep>
        <imperative_routine_upd_args>
        <value_node_elem_sep>
        <imperative_routine_ro_args>
    }

    token imperative_routine_name { <NameChain_payload> }

    token imperative_routine_upd_args {
        <nonord_list_open>
            [[<Name_payload> <pair_elem_sep> <NameChain_payload>]
                ** <list_elem_sep>]?
        <nonord_list_close>
    }

    token imperative_routine_ro_args { <QTuple_payload> }

Examples:

    boot_stmt:sys.std.Core.Cat.create_depot_procedure:{}:{ ... }

=head1 MULDIS D TINY DIALECT PRAGMAS

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

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT

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

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

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

=head1 TRADEMARK POLICY

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

=head1 ACKNOWLEDGEMENTS

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

=cut
