=pod

=encoding utf8

=head1 NAME

Muldis::D::Dialect::HDMD_Perl_Tiny -
How to format Perl Hosted Data Muldis D

=head1 VERSION

This document is Muldis::D::Dialect::HDMD_Perl_Tiny version 0.13.0.

=head1 PREFACE

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

=head1 DESCRIPTION

This document outlines the grammar of the I<Hosted Data Muldis D> dialect
named C<HDMD_Perl_Tiny>.  The fully-qualified name of this Muldis D
dialect, in combination with the base language spec it is bundled with, is
C<Muldis_D:'cpan:DUNCAND':'N.N.N':'HDMD_Perl_Tiny'> (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<HDMD_Perl_Tiny> 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.  This dialect similarly matches the C<PTMD_Tiny> dialect, which is
documented at L<Muldis::D::Dialect::PTMD_Tiny>.

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 tiny, hence the dialect's C<Tiny> name.  Likewise, a code
generator for this dialect from the system catalog can be tiny.

The C<HDMD_Perl_Tiny> dialect is defined to be hosted in either Perl 5 or
Perl 6, and as composed of just|mainly core Perl types.  Where Perl 5 and 6
differ, the terminology and examples in this documentation specifically
uses Perl 6 terminology and examples by default, and adds analogous Perl 5
terminology as necessary.

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

This document mainly just specifies a way to represent Muldis D values as
Perl values.  Since the fundamental way to do data definition in Muldis D
is to update catalog (information schema) variables, aka the Muldis D
meta-model, which are themselves just data, then this document only needs
to tell you how to define values to put in the catalog variables.  Defining
data types or routines are done by defining catalog values describing them.

See instead L<Muldis::D::Core> for how to actually define the
tuples and relations that define your data types and routines and queries
and so forth.

For the present, this document will use the term I<PHMD> (I<Perl Hosted
Muldis D>) for brevity when referring to aspects of the Perl-Tiny dialect.

=head1 GENERAL STRUCTURE

A PHMD value is composed mainly of a tree of Perl Array, such that each
Array is a tree node.  The elements of each node/Array include typically a
native Perl payload value, which may be a PHMD value itself, plus meta-data
for that payload, that meta-data typically including the analogy of a class
name, were PHMD nodes instead represented by a tree of PHMD-specific
objects.  As an exception, one kind of PHMD node is not a Perl Array, but
just a Perl C<Str>; if you see a C<Str> where you expect a PHMD node,
assume it is a C<Cat.Name> node; this exception is for huffmanizing.

It should be emphasized that no Perl undefined values are allowed anywhere
in a PHMD value; you must use only defined values instead.  This
documentation also assumes that only defined values are used, and that
supplying a Perl undef will result in an error.  If you genuinely want to
represent that a value is unknown or inapplicable, then the C<Nothing> node
type is provided as one way you can explicitly say so.  I<This policy may
be reconsidered.>

=head1 LANGUAGE NAME

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

=over

=item *

Node type / language base name: the Perl C<Str> value C<Muldis_D>.

=item *

Base authority: a Perl C<Str> as per the payload of a C<Text> node;
typically the Perl C<Str> value C<cpan:DUNCAND>.

=item *

Base version number: a Perl C<Str> as per the payload of a C<Text> node;
typically a Perl C<Str> value like C<1.2.3>.

=item *

Dialect: the Perl C<Str> value C<HDMD_Perl_Tiny>.

=item *

Extensions: a Perl C<Hash|Mapping> as per the payload of a C<Tuple> node.

=back

Examples:

    [ 'Muldis_D', 'cpan:DUNCAND', '1.2.3', 'HDMD_Perl_Tiny', {} ]

More specifically, a language name PHMD node like the above would generally
be the input for a Perl Hosted Muldis D implementating virtual machine's
configuration step, which provides a context for subsequent feeding of
other PHMD trees to said virtual machine.

=head1 CORE GENERIC SCALAR VALUES

=head2 sys.Core.Scalar.Bool

This node type represents a logical boolean value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Bool>.

=item *

Format; one of: C<md_enum>, C<perl_bool>, C<any_perl>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Scalar.Bool> value as
follows:

=over

=item *

If the format is C<md_enum>, then the payload must be a Perl C<Str>
having one of the values C<false>, C<true>.  This format specifically is
what the Plain Text Muldis D grammar uses, and is the result of parsing it.

=item *

If the format is C<perl_bool>, then:  Under Perl 6, the payload must
be a Perl C<Bool>, and so C<Bool::False> and C<Bool::True> are mapped
directly.  Under Perl 5, the payload must be just the specific result of a
Perl 5 logical expression, such as C<(1 == 0)> or C<(1 == 1)>, and nothing
else; said values are probably the empty string and number 1, respectively.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into a boolean context as per Perl's own
semantics; typically for built-in scalars, the empty string and number zero
are considered false, and everything else true.

=back

Examples:

    [ 'Bool', 'md_enum', 'true' ]

    [ 'Bool', 'perl_bool', Bool::False ] # Perl 6 only

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

    [ 'Bool', 'perl_any', 42 ]

=head2 sys.Core.Scalar.Int

This node type represents an integer value.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Int>.

=item *

Format; one of: C<md_int>, C<perl_int>, C<any_perl>.

=item *

Only when format is C<md_int>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Scalar.Int> value as
follows:

=over

=item *

If the format is C<md_int>, then the max-col-val must be a Perl C<Str>
composed of a single C<[1-9A-Z]> character, and the payload must be a Perl
C<Str> of the format C<0> or C<< \-?<[1-9A-Z]><[0-9A-Z]>* >>.  This format
specifically is what the Plain Text Muldis D grammar uses, and is the
result of parsing it.  The payload is interpreted as a base-I<N> integer
where I<N> might be between 2 and 36, and the given max-col-val says which
possible value of I<N> to use.  Assuming all column values are between zero
and I<N>-minus-one, the max-col-val contains that I<N>-minus-one.  So to
specify, eg, bases [2,8,10,16], use max-col-val of [1,7,9,F].

=item *

If the format is C<perl_int>, then:  Under Perl 6, the payload must
be a Perl C<Int>, which is mapped directly.  Under Perl 5, the payload must
be just a canonical integer value according to Perl.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into an integer context as per Perl's own
semantics, meaning base-10 where applicable.  If something doesn't look
numeric, it becomes zero; if something looks like a fractional number, it
is truncated.

=back

Examples:

    [ 'Int', 'md_int', '1', '11001001' ] # binary

    [ 'Int', 'md_int', '7', '0' ] # octal

    [ 'Int', 'md_int', '7', '644' ] # octal

    [ 'Int', 'md_int', '9', '-34' ] # decimal

    [ 'Int', 'md_int', '9', '42' ] # decimal

    [ 'Int', 'md_int', 'F', 'DEADBEEF' ] # hexadecimal

    [ 'Int', 'md_int', 'Z', '-HELLOWORLD' ] # base-36

    [ 'Int', 'perl_int', 21 ]

    [ 'Int', 'any_perl', ' 171 ' ]

    [ 'Int', 'md_int', '3', '301' ] # base-4

    [ 'Int', 'perl_int', 0 ]

    [ 'Int', 'md_int', 'B', 'A09B' ] # base-12

    [ 'Int', 'perl_int', 101 ]

=head2 sys.Core.Scalar.Blob

This node type represents a bit string.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Blob>.

=item *

Format; one of: C<md_blob>, C<perl_blob>.

=item *

Only when format is C<md_blob>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Scalar.Blob> value as
follows:

=over

=item *

If the format is C<md_blob>, then the max-col-val must be a Perl
C<Str> composed of a single C<[137F]> character, and the payload must be a
Perl C<Str> of the format C<< <[0-9A-F]>* >>.  This format specifically is
what the Plain Text Muldis D grammar uses, and is the result of parsing it.
Each column of the payload specifies a sequence of one of [1,2,3,4] bits,
depending on whether max-col-val is [1,3,7,F].

=item *

If the format is C<perl_blob>, then:  Under Perl 6, the payload must
be a Perl C<Blob>, which is mapped directly.  Under Perl 5, the payload
must be just a canonical Perl bit string, which is a scalar whose utf-8
flag is false.

=back

Examples:

    [ 'Blob', 'md_blob', '1', '00101110100010' ] # binary

    [ 'Blob', 'md_blob', '3', ''

    [ 'Blob', 'md_blob', 'F', 'A705E' # hexadecimal

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

    [ 'Blob', 'md_blob', '7', '523504376' ]

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

=head2 sys.Core.Scalar.Text

This node type represents a character string.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Text>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Scalar.Text> value by
directly mapping the payload.  Note that, while Plain Text Muldis D may
contain a few escape sequences, those would be replaced with what they
represent prior to making a PHMD node.  Under Perl 6, the payload must be a
Perl C<Str>, which is mapped directly.  Under Perl 5, the payload must be
just a canonical Perl character string, which is a scalar whose utf-8 flag
is true, or that doesn't contain any octets with a C<1>-valued highest bit.

Examples:

    [ 'Text', 'Ceres' ]

    [ 'Text', 'サンプル' ] # note: Perl 5 needs "use utf8;" pragma to work

    [ 'Text', '' ]

    [ 'Text', 'Perl' ]

=head1 CORE GENERIC NONSCALAR VALUES

=head2 sys.Core.Tuple.Tuple

This node type represents a tuple value.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Tuple>.

=item *

The payload; a Perl C<Hash|Mapping> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Tuple.Tuple> value whose
attributes are defined by the payload.  Each key+value pair of the payload
defines a named attribute of the new tuple; the pair's key and value are,
respectively, a Perl C<Str> that specifies the attribute name, and a PHMD
node that specifies the attribute value.

Examples:

    [ 'Tuple', {} ]

    [ 'Tuple', {
        'login_name' => [ 'Text', 'hartmark' ],
        'login_pass' => [ 'Text', 'letmein' ],
        'is_special' => [ 'Bool', 'md_enum', 'true' ],
    } ]

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

=head2 sys.Core.Relation.Relation

This node type represents a relation value.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Relation>.

=item *

The payload; a Perl C<Array|Seq|Set|KeySet> of C<Str|Hash|Mapping> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Relation> value
whose tuples and attribute names are defined by the payload.  Iff the
payload has zero elements, then it defines the only relation value having
zero attributes and zero tuples.  If the payload has elements, then either
the elements must all be C<Str>, or they must all be C<Hash|Mapping>, but
not both kinds in the same payload.  Iff a payload's elements are each
C<Str>, then the payload defines the attribute names of a relation having
zero tuples; each element must be as per the payload of a
C<Cat.Name>-defining PHMD node.  Iff a payload's elements are each
C<Hash|Mapping>, then each element of the payload defines a tuple of the
new relation; each element is as per the payload of a tuple-defining PHMD
node; every tuple-defining element of the payload must be of the same
degree and have the same attribute names as its sibling elements; these are
the degree and attribute names of the relation as a whole, which is its
heading for the current purposes.

Examples:

    [ 'Relation', [] ]

    [ 'Relation', [ {}, ] ]

    [ 'Relation', [ 'x', 'y', 'z', ] ]

    [ 'Relation', [
        {
            'login_name' => [ 'Text', 'hartmark' ],
            'login_pass' => [ 'Text', 'letmein' ],
            'is_special' => [ 'Bool', 'md_enum', 'true' ],
        },
    ] ]

    [ 'Relation', [
        {
            'name' => [ 'Text', 'Michelle' ],
            'age'  => [ 'Int', 'perl_int', 17 ],
        },
    ] ]

=head2 sys.Core.Relation.Set

This node type represents a set value.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Set>.

=item *

The payload; a Perl C<Array|Seq|Set|KeySet> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Set> value whose
elements are defined by the payload.  Each element of the payload defines a
unary tuple of the new set; each element is a PHMD node that defines the
C<value> attribute of the tuple.

Examples:

    [ 'Set', [
        [ 'Text', 'Canada' ],
        [ 'Text', 'Spain' ],
        [ 'Text', 'Jordan' ],
        [ 'Text', 'Thailand' ],
    ] ]

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

=head2 sys.Core.Relation.Nothing

This node type represents a 'nothing' value; it is interpreted as a Muldis
D C<sys.Core.Relation.Nothing>.  It has 1 element, which is the Perl C<Str>
value C<Nothing>.

Examples:

    [ 'Nothing' ]

=head2 sys.Core.Relation.Single

This node type represents a 'single' value.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Single>.

=item *

The payload; a PHMD node that defines a single scalar or nonscalar value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Single> value
whose element is defined by the payload.  The payload is a PHMD node that
defines the C<value> attribute of the single tuple of the new 'single'.

Examples:

    [ 'Single', [ 'Text', '2003.07.24' ] ]

=head2 sys.Core.Relation.Seq

This node type represents a sequence value.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Seq>.

=item *

The payload; a Perl C<Array|Seq> value.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Seq> value whose
elements are defined by the payload.  Each element of the payload defines a
binary tuple of the new sequence; the element value is a PHMD node that
defines the C<value> attribute of the tuple, and the element index is used
as the C<index> attribute of the tuple.

Examples:

    [ 'Seq', [
        [ 'Text', 'Alphonse' ],
        [ 'Text', 'Edward' ],
        [ 'Text', 'Winry' ],
    ] ]

    [ 'Seq', [
        [ 'Int', 'perl_int', 57 ],
        [ 'Int', 'perl_int', 45 ],
        [ 'Int', 'perl_int', 63 ],
        [ 'Int', 'perl_int', 61 ],
    ] ]

=head2 sys.Core.Relation.Bag

This node type represents a bag value.  It has 3 elements:

=over

=item *

Node type: the Perl C<Str> value C<Bag>.

=item *

Format; one of: C<aoa_counted>, C<array_repeated>, C<perl_bag> (p6).

=item *

The payload; a Perl C<Bag|KeyBag> value or C<Array|Seq> or
C<Array|Seq> of C<Array|Seq>.

=back

This node is interpreted as a Muldis D C<sys.Core.Relation.Bag> value whose
elements are defined by the payload.  The payload is interpreted as
follows:

=over

=item *

If the format is C<aoa_counted>, then the payload must be a Perl
C<Array|Seq>, and each element of the payload defines a binary tuple of the
new bag; the element is a 2-element C<Array|Seq>, and those 2 elements, by
index order, are a PHMD node that defines the C<value> attribute of the
tuple, and a 2-3-element C<Array|Seq> (which is the same as an 'Int' PHMD
node minus the first constant element) that defines the C<count> attribute
of the tuple; the count must be a positive integer.

=item *

If the format is C<array_repeated>, then the payload must be a Perl
C<Array|Seq>, and each element of the payload contributes to a binary tuple
of the new bag; the element value is a PHMD node that defines the C<value>
attribute of the tuple.  The bag has 1 tuple for every distinct (after
format normalization) element value in the payload, and the C<count>
attribute of that tuple says how many instances of said element were in the
payload.

=item *

If the format is C<perl_bag>, then the payload must be a Perl 6
(there is no Perl 5 analogy) C<Bag|KeyBag> value; the payload elements are
PHMD nodes corresponding to the C<value> attribute of the new bag's tuples,
and the mapping is as you should expect.

=back

Examples:

    [ 'Bag', 'aoa_counted', [
        [
            [ 'Text', 'Apple' ],
            [ 'md_int', '9', '500' ],
        ],
        [
            [ 'Text', 'Orange' ],
            [ 'perl_int', 300 ],
        ],
        [
            [ 'Text', 'Banana' ],
            [ 'perl_int', 400 ],
        ],
    ] ]

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

=head1 QUASI-NONSCALAR VALUES

Every PHMD node type for a nonscalar literal has a corresponding extra PHMD
node type for a quasi-nonscalar literal.  The corresponding extra quasi-
node types are exactly the same in format to the non-quasi types but that
for each one of them, the value of its first element has the Perl C<Str>
value C<Quasi> prepended.  So PHMD nodes whose first elements each are
[C<QuasiTuple>, C<QuasiRelation>, C<QuasiSet>, C<QuasiNothing>,
C<QuasiSingle>, C<QuasiSeq>, C<QuasiBag>] are interpreted as Muldis D
[C<sys.Core.QuasiTuple.QuasiTuple>,
C<sys.Core.QuasiRelation.QuasiRelation>,
C<sys.Core.QuasiRelation.QuasiSet>, C<sys.Core.QuasiRelation.QuasiNothing>,
C<sys.Core.QuasiRelation.QuasiSingle>, C<sys.Core.QuasiRelation.QuasiSeq>,
C<sys.Core.QuasiRelation.QuasiBag>] values, respectively.

=head1 CATALOG SCALAR VALUES

=head2 sys.Core.Cat.Name

This node type 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>.

Unlike every other PHMD node type, a canonical short name is simply a Perl
C<Str> value, which is its payload; it is not encapsulated in a Perl Array;
this difference is done for huffmanizing reasons, since a short name is
probably the most often used node type, and moreover this change allows for
simplifying other parts of the grammar.

This node is interpreted as a Muldis D C<sys.Core.Cat.Name> value by
directly mapping itself / the payload.  Note that, while Plain Text Muldis
D may contain a few escape sequences, those would be replaced with what
they represent prior to making a PHMD node.  The node / its payload must be
as per the payload of a C<Text> PHMD node.

Examples:

    'login_pass'

    'First Name'

=head2 sys.Core.Cat.NameChain

This node type represents a canonical long name for invoking some a DBMS
entity in some contexts; it is conceptually a sequence of entity short
names.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.NameChain>.

=item *

The payload; a Perl C<Array|Seq> value or C<Str> (char-mode scalar) value.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.NameChain> value as
follows:

=over

=item *

If the payload is an C<Array|Seq>, then it must have at least 1 element,
and every element must be a valid payload for a C<Cat.Name> PHMD node (that
is, any Perl character string).  Each element of the payload, in
order, defines an element of the sequence possrep of a C<Cat.NameChain>.

=item *

If the payload is a C<Str>, then it must be formatted as a catenation
(using period (C<.>) separators) of at least 1 part, where each part is
escaped such that backslashes, single-quotes, and periods are escaped as
C<\b>, C<\q> and C<\p> respectively.

=back

Examples:

    [ 'Cat.NameChain', ['fed','the_db','gene','sorted_person_name'] ]

    [ 'Cat.NameChain', 'fed.the_db.stats.samples_by_order' ]

=head2 sys.Core.Cat.Comment

This node type 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
has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Comment>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.Comment> value by
directly mapping the payload.  Note that, while Plain Text Muldis D may
contain a few escape sequences, those would be replaced with what they
represent prior to making a PHMD node.  The payload must be as per the
payload of a C<Text> PHMD node.

Examples:

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

=head2 sys.Core.Cat.E_TK

This node type represents a type kind.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_TK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_TK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 8 values C<special>, C<scalar>, C<tuple>, C<relation>,
C<quasi_scalar>, C<quasi_tuple>, C<quasi_relation>, C<remnant>.

Examples:

    [ 'Cat.E_TK', 'scalar' ]

=head2 sys.Core.Cat.E_TDM

This node type represents a type definition method.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_TDM>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_TDM> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 9 values C<special>, C<root>, C<restriction>, C<alias>, C<union>,
C<intersection>, C<exclusion>, C<difference>, C<negation>.

Examples:

    [ 'Cat.E_TDM', 'alias' ]

=head2 sys.Core.Cat.E_ENK

This node type represents an expression node kind.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_ENK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_ENK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 11 values C<default>, C<scalar>, C<tuple>, C<relation>,
C<quasi_scalar>, C<quasi_tuple>, C<quasi_relation>, C<param>, C<upd_param>,
C<ro_param>, C<func>.

Examples:

    [ 'Cat.E_ENK', 'default' ]

=head2 sys.Core.Cat.E_PSAK

This node type represents a procedural statement argument kind.  It has 2
elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_PSAK>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Core.Cat.E_PSAK> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 5 values C<default>, C<upd_param>, C<ro_param>, C<inner_var>,
C<outer_var>.

Examples:

    [ 'Cat.E_PSAK', 'ro_param' ]

=head1 RATIONAL EXTENSION SCALAR VALUES

=head2 sys.Rational.Rat.Rat

This node type represents a rational value.  It has 3-4 elements:

=over

=item *

Node type: the Perl C<Str> value C<Rat>.

=item *

Format; one of: C<md_radix>, C<md_ratio>, C<md_float>, C<perl_rat>,
C<perl_float>, C<perl_int_ratio>, C<perl_int_float>, C<any_perl>,
C<any_perl_ratio>, C<any_perl_float>.

=item *

Only when format is C<md_radix>|C<md_ratio>|C<md_float>; the max-col-val.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Rational.Rat.Rat> value as
follows:

=over

=item *

If the format is C<md_radix>, then the max-col-val must be a Perl C<Str>
composed of a single C<[1-9A-Z]> character, and the payload must be a Perl
C<Str> of the format C<0> or C<< \-?<[1-9A-Z]><[0-9A-Z]>*\.?<[0-9A-Z]>* >>.
This format specifically is what the Plain Text Muldis D grammar uses
('radix' option), and is the result of parsing it.  The payload is
interpreted as a base-I<N> rational where I<N> might be between 2 and 36,
and the given max-col-val says which possible value of I<N> to use.
Assuming all column values are between zero and I<N>-minus-one, the
max-col-val contains that I<N>-minus-one.  So to specify, eg, bases
[2,8,10,16], use max-col-val of [1,7,9,F].

=item *

If the format is C<md_ratio>, then the max-col-val must be as per
C<md_radix>, and the payload must be a 2-element C<Array|Seq> where the
first element is a Perl C<Str> of the format C<0> or C<<
\-?<[1-9A-Z]><[0-9A-Z]>* >> (an integer) and the second element is a Perl
C<Str> of the format C<< <[1-9A-Z]><[0-9A-Z]>* >> (a positive integer). The
payload is interpreted as per C<md_radix> but that its value comes from the
first element (a numerator) divided by the second (a denominator).  Note
that while the C<md_radix> format is limited to representing rationals
whose denominator is a power of some I<N> between 2 and 36, the C<md_ratio>
format can represent those with any I<N> that is greater than or equal to
2, such as 1/43.

=item *

If the format is C<md_float>, then the max-col-val must be as per
C<md_radix>, and the payload must be a 3-element C<Array|Seq> where the
first element is a Perl C<Str> of the format C<0> or C<<
\-?<[1-9A-Z]><[0-9A-Z]>* >> (an integer) and the second element is a Perl
C<Str> of the format C<< <[2-9A-Z]><[0-9A-Z]>* >> (an integer greater than
1) and the third element is as per the first (an integer).  The payload is
interpreted as per C<md_radix> but that its value comes from the first
element (a mantissa) multiplied by the result of the second element (a
radix) taken to the power of the third (an exponent).  Note that while the
C<md_ratio> format can represent all rationals, the very large or very
small ones would be quite verbose written in that format, and so the
C<md_float> format allows writing those values in a more terse fashion,
such as 1.56*10^37.

=item *

If the format is C<perl_rat>, then:  Under Perl 6, the payload must be a
Perl C<Rat> (or C<Num>), which is mapped directly.  Under Perl 5, the
payload must be just a canonical rational or numeric value according to
Perl.

=item *

If the format is C<perl_float>, then:  Under Perl 6, the payload must be a
Perl C<Float> (or C<Num>), which is mapped directly.  Under Perl 5, the
payload must be just a canonical floating-point or numeric value according
to Perl.

=item *

If the format is C<perl_int_ratio>, then the payload must a 2-element
C<Array|Seq> where each element must be a canonical integer (or positive
integer, respectively) to Perl as per defining a C<perl_int>; the
rational's value is interpreted as the first element divided by the second.

=item *

If the format is C<perl_int_float>, then the payload must a 3-element
C<Array|Seq> where each element must be a canonical integer (or integer
greater than 2, or integer, respectively) to Perl as per defining a
C<perl_int>; the rational's value is interpreted as the first element
multiplied by the result of the second element taken to the power of the
third.

=item *

If the format is C<any_perl>, then the payload may be any Perl value,
and it is simply coerced into a numeric context as per Perl's own
semantics, meaning base-10 where applicable.  If something doesn't look
numeric, it becomes zero.

=item *

If the format is C<any_perl_ratio>, then the payload is as per
C<perl_int_ratio> but that each array element is simply coerced into an
integer context.  If Perl's coercion of the denominator produces an integer
less than 1, it becomes a 1.  I<This may be revised to fail instead.>

=item *

If the format is C<any_perl_float>, then the payload is as per
C<perl_int_float> but that each array element is simply coerced into an
integer context.  If Perl's coercion of the radix produces an integer
less than 2, it becomes a 2.  I<This may be revised to fail instead.>

=back

Examples:

    [ 'Rat', 'md_radix', '1', '-1.1' ]

    [ 'Rat', 'md_radix', '9', '-1.5' ] # same val as prev

    [ 'Rat', 'md_radix', '9', '3.14159' ]

    [ 'Rat', 'md_radix', 'A', '0.0' ]

    [ 'Rat', 'md_radix', 'F', 'DEADBEEF.FACE' ]

    [ 'Rat', 'md_radix', 'Z', '0.000AZE' ]

    [ 'Rat', 'md_ratio', '6', [ '500001', '1000' ] ]

    [ 'Rat', 'md_ratio', 'B', [ 'A09B', 'A' ] ]

    [ 'Rat', 'md_float', '1', [ '1011101101', '10', '-11011' ] ]

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

    [ 'Rat', 'perl_rat', 21.003 ]

    [ 'Rat', 'perl_float', 5.428**295 ]

    [ 'Rat', 'perl_int_ratio', [ 1, 43 ] ]

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

    [ 'Rat', 'any_perl', ' 54.67 ' ]

    [ 'Rat', 'any_perl_ratio', [ ' 57 ', ' 71 ' ] ]

    [ 'Rat', 'any_perl_float', [ ' 656573456 ', ' 8 ', ' 243323 ' ] ]

=head2 sys.Rational.Cat.E_RM

This node type represents a rounding method.  It has 2 elements:

=over

=item *

Node type: the Perl C<Str> value C<Cat.E_RM>.

=item *

The payload.

=back

This node is interpreted as a Muldis D C<sys.Rational.Cat.E_RM> value by
directly mapping the payload.  The payload must be a Perl C<Str> having one
of the 7 values C<half_down>, C<half_up>, C<half_even>, C<to_floor>,
C<to_ceiling>, C<to_zero>, C<to_inf>.

Examples:

    [ 'Cat.E_RM', 'half_up' ]

=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-2008, Darren Duncan.

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