|
Language::MuldisD::PerlHosted - How to format Perl Hosted Abstract Muldis D |
Language::MuldisD::PerlHosted - How to format Perl Hosted Abstract Muldis D
This document is Language::MuldisD::PerlHosted version 0.4.1.
This document is part of the Muldis D language specification, whose root document is the Language::MuldisD manpage; you should read that root document before you read this one, which provides subservient details.
This document outlines the specification of Abstract Muldis D as hosted in either Perl 5 or Perl 6, and as composed of just|mainly core Perl types; for brevity, the term PHMD will be used to refer to this spec.
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 the Language::MuldisD::Core manpage for how to actually define the tuples and relations that define your data types and routines and queries and so forth.
Note that this document (along with the aforementioned) is also intended to serve as a proposal for a generic portable AST that various Perl applications and components can use to represent their database schemas and queries, regardless of whether a native Muldis D implementation is in use; or this document can be used as a point of departure for documenting some alternative AST for that purpose.
This documentation is pending.
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.
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, then the Maybe node type is provided
as one way you can explicitly say so. This policy may be reconsidered.
The root Perl Array of a PHMD value has 4 elements, which are:
Str value
MuldisD for this spec.
Str value. The
authority string is interpreted within the context of the language/schema
name, which for the MuldisD spec is the range of authority string
formats permitted for the long names of Perl 6 packages, such as a CPAN
identifier or an http url, although what's allowed may be open-ended. For
the official/original Muldis D language spec by Darren Duncan, that string
is always cpan:DUNCAND during the foreseeable future. If someone else
wants to embrace and extend Muldis D, such as to include proprietary
extensions, or incompatible changes, then they must use something other
than cpan:DUNCAND for the authority, (and optionally, change the name
from MuldisD as well if that seems appropriate), to prevent ambiguity.
Str value.
The version number string is interpreted within the context of both the
language/schema name and language/schema authority, which for the
MuldisD plus cpan:DUNCAND spec is the normal 3-integer-parts
(X.Y.Z) version format normal for the long names of Perl 6 packages and
many other versioned projects in general. At the present time, the
official spec version number to use is shown in the VERSION and DESCRIPTION
of the MuldisD.pm file, when corresponding to the spec containing that
file.
Examples of a root node:
[ 'MuldisD', 'cpan:DUNCAND', '1.2.3', [ 'Bool', 'md_enum', 'false' ] ]
Both the payload node under the root node and every other node is a Perl
Array with usually 2+ elements, where the first element is a Perl Str
saying what kind of node it is, and the last element is the
typically-single payload, and any sometimes-optional intermediate elements
give extra meta-data to specify which of possibly several representation
formats the payload is, so that it is correctly interpreted. Typically
speaking, only the payload element might be a Perl collection type, and
typically all the other elements are Perl scalars.
Note that a Hosted Abstract Muldis D implementation may eschew the above 4-element Array as the root PHMD node for all PHMD trees, and instead have a separate virtual machine configuration step taking just the first 3 elements (base name, authority, version number), to provide a context for subsequent use of PHMD trees that consist of just what would otherwise be the 4th (payload) element.
Examples; at VM config time:
[ 'MuldisD', 'cpan:DUNCAND', '1.2.3' ]
Then later, just:
[ 'Bool', 'md_enum', 'false' ]
This node type represents a logical boolean value. It has 3 elements:
Str value Bool.
md_enum, perl_bool, any_perl.
This node is interpreted as a Muldis D sys.Core.Bool.Bool value as
follows:
md_enum, then the payload must be a Perl Str
having one of the values false, true. This format specifically is
what the Concrete Muldis D grammar uses, and is the result of parsing it.
perl_bool, then: Under Perl 6, the payload must
be a Perl Bool, and so Bool::False and Bool::True are mapped
directly. Under Perl 5, the payload must be just the specific result of a
Perl 5 logical expression, such as (1 == 0) or (1 == 1), and nothing
else; said values are probably the empty string and number 1, respectively.
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.
Examples:
[ 'Bool', 'md_enum', 'true' ]
[ 'Bool', 'perl_bool', Bool::False ] # Perl 6 only
[ 'Bool', 'perl_bool', (1 == 0) ]
[ 'Bool', 'perl_any', 42 ]
This node type represents an order-determination. It has 3 elements:
Str value Order.
md_enum, perl_order.
This node is interpreted as a Muldis D sys.Core.Order.Order value as
follows:
md_enum, then the payload must be a Perl Str
having one of the values increase, same, decrease. This format
specifically is what the Concrete Muldis D grammar uses, and is the result
of parsing it.
perl_order, then: Under Perl 6, the payload must be a
Perl Order, and so Order::Increase and Order::Same and
Order::Decrease are mapped directly. Under Perl 5, the payload must be
just the specific result of a Perl 5 order-determining expression, such as
(1 <=> 2) or (1 <=> 1) or (2 <=> 1), and nothing else;
said values are probably the numbers [-1, 0, 1], respectively.
Examples:
[ 'Order', 'md_enum', 'same' ]
[ 'Order', 'perl_order', Order::Increase ] # Perl 6 only
[ 'Order', 'perl_order', (2 <=> 1) ]
This node type represents an integer value. It has 3-4 elements:
Str value Int.
md_int, perl_int, any_perl.
md_int; the max-col-val.
This node is interpreted as a Muldis D sys.Core.Int.Int value as
follows:
md_int, then the max-col-val must be a Perl
Str composed of a single [1-9A-Z] character, and the payload must be
a Perl Str of the format 0 or \-?<[1-9A-Z]><[0-9A-Z]>*. This
format specifically is what the Concrete Muldis D grammar uses, and is the
result of parsing it. The payload is interpreted as a base-N integer
where N might be between 2 and 36, and the given max-col-val says which
possible value of N to use. Assuming all column values are between zero
and N-minus-one, the max-col-val contains that N-minus-one. So to
specify, eg, bases [2,8,10,16], use max-col-val of [1,7,9,F].
perl_int, then: Under Perl 6, the payload must
be a Perl Int, which is mapped directly. Under Perl 5, the payload must
be just a canonical integer value according to Perl.
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.
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 ' ]
This node type represents an unsigned / non-negative integer value; it is
interpreted as a Muldis D sys.Core.Int.UInt. Its format is the same as
for sys.Core.Int.Int but that the node type is 'UInt', its formats are
respectively named for 'uint', and the payload may not have a leading -.
Examples:
[ 'UInt', 'md_uint', '3', '301' ] # base-4
[ 'UInt', 'perl_uint', 0 ]
This node type represents a positive integer value; it is interpreted as a
Muldis D sys.Core.Int.PInt. Its format is the same as for
sys.Core.Int.UInt but that the node type is 'PInt', formats 'pint', and
the payload may not be 0.
Examples:
[ 'PInt', 'md_pint', 'B', 'A09B' ] # base-12
[ 'PInt', 'perl_pint', 101 ]
This node type represents a rational value. It has 3-4 elements:
Str value Rat.
md_rat, perl_rat, any_perl.
md_rat; the max-col-val.
This node is interpreted as a Muldis D sys.Core.Rat.Rat value as
follows:
md_rat, then the max-col-val must be a Perl Str
composed of a single [1-9A-Z] character, and the payload must be a Perl
Str of the format 0 or \-?<[1-9A-Z]><[0-9A-Z]>*\.?<[0-9A-Z]>*.
This format specifically is what the Concrete Muldis D grammar uses, and
is the result of parsing it. The payload is interpreted as a base-N
rational where N might be between 2 and 36, and the given max-col-val
says which possible value of N to use. Assuming all column values are
between zero and N-minus-one, the max-col-val contains that
N-minus-one. So to specify, eg, bases [2,8,10,16], use max-col-val of
[1,7,9,F].
perl_rat, then: Under Perl 6, the payload must be a
Perl Rat (or Num), which is mapped directly. Under Perl 5, the
payload must be just a canonical rational or numeric value according to
Perl.
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.
Examples:
[ 'Rat', 'md_rat', '1', '-1.1' ]
[ 'Rat', 'md_rat', '9', '-1.5' ] # same val as prev
[ 'Rat', 'md_rat', '9', '3.14159' ]
[ 'Rat', 'md_rat', 'A', '0.0' ]
[ 'Rat', 'md_rat', 'F', 'DEADBEEF.FACE' ]
[ 'Rat', 'md_rat', 'Z', '0.000AZE' ]
[ 'Rat', 'perl_rat', 21.003 ]
[ 'Rat', 'any_perl', ' 54.67 ' ]
This node type represents a unsigned / non-negative rational value; it is
interpreted as a Muldis D sys.Core.Rat.URat. Its format is the same as
for sys.Core.Rat.Rat but that the node type is 'URat', its formats are
respectively named for 'urat', and the payload may not have a leading -.
Examples:
[ 'URat', 'md_urat', '6', '500.001' ]
[ 'URat', 'perl_urat', 0.01 ]
This node type represents a positive rational value; it is interpreted as a
Muldis D sys.Core.Rat.PRat. Its format is the same as for
sys.Core.Rat.URat but that the node type is 'PRat', formats 'prat', and
the payload may not be 0.
Examples:
[ 'PRat', 'md_prat', 'B', 'A09.B' ]
[ 'PRat', 'perl_prat', 0.101 ]
This node type represents a bit string. It has 3-4 elements:
Str value Blob.
md_blob, perl_blob.
md_blob; the max-col-val.
This node is interpreted as a Muldis D sys.Core.Blob.Blob value as
follows:
md_blob, then the max-col-val must be a Perl
Str composed of a single [137F] character, and the payload must be a
Perl Str of the format <[0-9A-F]>*. This format specifically is
what the Concrete 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].
perl_blob, then: Under Perl 6, the payload must
be a Perl 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.
Examples:
[ 'Blob', 'md_blob', '1', '00101110100010' ] # binary
[ 'Blob', 'md_blob', '3', ''
[ 'Blob', 'md_blob', 'F', 'A705E' # hexadecimal
[ 'Blob', 'perl_blob', (pack 'H2', 'P') ]
This node type represents a non-empty bit-string value; it is interpreted
as a Muldis D sys.Core.Blob.NEBlob. Its format is the same as for
sys.Core.Blob.Blob but that the node type is 'Blob', its formats are
respectively named for 'neblob', the payload may not be the empty string.
Examples:
[ 'NEBlob', 'md_blob', '7', '523504376' ]
[ 'NEBlob', 'perl_neblob', (pack 'H2', 'Z') ]
This node type represents a character string. It has 2 elements:
Str value Text.
This node is interpreted as a Muldis D sys.Core.Text.Text value by
directly mapping the payload. Note that, while Concrete 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 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 1-valued highest bit.
Examples:
[ 'Text', 'Ceres' ]
[ 'Text', 'サンプル' ] # note: Perl 5 needs "use utf8;" pragma to work
[ 'Text', '' ]
This node type represents a non-empty character string value; it is
interpreted as a Muldis D sys.Core.Text.NEText. Its format is the same
as for sys.Core.Text.Text but that the node type is 'Text', and the
payload may not be the empty string.
Examples:
[ 'NEText', 'Perl' ]
This node type represents a tuple value. It has 3 elements:
Str value Tuple.
Array|Str that is a valid payload for a Cat.NameChain.
Hash|Mapping value.
This node is interpreted as a Muldis D sys.Core.Tuple.Tuple value whose
heading was predefined, as a tuple data type, for referencing now by the
type name, and whose body is defined now 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 Str that specifies the attribute
name, and a PHMD node that specifies the attribute value. The tuple body
defined by the payload must correspond to the tuple heading named by the
type name; that is, they must have the same degree, same attribute names,
and compatible types.
Examples:
[ 'Tuple', 'sys.Core.Tuple.D0', {} ]
[ 'Tuple', 'fed.the_db.account.user_t', {
'login_name' => [ 'Text', 'hartmark' ],
'login_pass' => [ 'Text', 'letmein' ],
'is_special' => [ 'Bool', 'md_enum', 'true' ],
} ]
[ 'Tuple', 'fed.the_db.gene.person_t', {
'name' => [ 'Text', 'Michelle' ],
'age' => [ 'Int', 'perl_int', 17 ],
} ]
This node type represents a database value; it is interpreted as a Muldis D
sys.Core.Tuple.Database. Its format is the same as for
sys.Core.Tuple.Tuple but that the node type is 'Database', the type name
must be of a database type rather than just a tuple type, and all payload
PHMD values must be of relation types.
Examples:
[ 'Database', 'sys.Core.Tuple.D0', {} ]
[ 'Database', 'fed.the_db.account', {
'user' => [ 'Relation', 'fed.the_db.account.user_r', ... ],
} ]
[ 'Database', 'fed.the_db.gene', {
'person' => [ 'Relation', 'fed.the_db.gene.person_r', ... ],
} ]
This node type represents a relation value. It has 3 elements:
Str value Relation.
Array|Str that is a valid payload for a Cat.NameChain.
Array|Seq|Set|KeySet of Hash|Mapping value.
This node is interpreted as a Muldis D sys.Core.Relation.Relation value
whose heading was predefined, as a relation data type, for referencing now
by the type name, and whose body is defined now by the payload. 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, including the need to
correspond to the relation heading, which is common to all tuples in it.
Examples:
[ 'Relation', 'sys.Core.Relation.D0C0', [] ]
[ 'Relation', 'sys.Core.Relation.D0C1', [ {} ] ]
[ 'Relation', 'fed.the_db.account.user_r', [
{
'login_name' => [ 'Text', 'hartmark' ],
'login_pass' => [ 'Text', 'letmein' ],
'is_special' => [ 'Bool', 'md_enum', 'true' ],
},
] ]
[ 'Relation', 'fed.the_db.gene.person_r', [
{
'name' => [ 'Text', 'Michelle' ],
'age' => [ 'Int', 'perl_int', 17 ],
},
] ]
This node type represents a set value. It has 3 elements:
Str value Set.
Array|Str that is a valid payload for a Cat.NameChain.
Array|Seq|Set|KeySet value.
This node is interpreted as a Muldis D sys.Core.Relation.Set value whose
heading was predefined, as a set data type, for referencing now by the type
name, and whose body is defined now 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 value attribute of the tuple.
Examples:
[ 'Set', 'fed.the_db.account.country_name', [
[ 'Text', 'Canada' ],
[ 'Text', 'Spain' ],
[ 'Text', 'Jordan' ],
[ 'Text', 'Thailand' ],
] ]
[ 'Set', 'fed.the_db.stats.some_ages', [
[ 'Int', 'perl_int', 3 ],
[ 'Int', 'perl_int', 16 ],
[ 'Int', 'perl_int', 85 ],
] ]
This node type represents a maybe value; it is interpreted as a Muldis D
sys.Core.Relation.Maybe. Its format is the same as for
sys.Core.Relation.Set but that the node type is 'Maybe', and the payload
must have at most 1 element.
Examples:
[ 'Maybe', 'fed.the_db.gene.person_death_date', [] ]
[ 'Maybe', 'fed.the_db.gene.person_death_date', [
[ 'Text', '2003.07.24' ],
] ]
This node type represents a sequence value. It has 3 elements:
Str value Seq.
Array|Str that is a valid payload for a Cat.NameChain.
Array|Seq value.
This node is interpreted as a Muldis D sys.Core.Relation.Seq value whose
heading was predefined, as a sequence data type, for referencing now by the
type name, and whose body is defined now 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 value attribute of the tuple, and the
element index is used as the index attribute of the tuple.
Examples:
[ 'Seq', 'fed.the_db.gene.sorted_person_name', [
[ 'Text', 'Alphonse' ],
[ 'Text', 'Edward' ],
[ 'Text', 'Winry' ],
] ]
[ 'Seq', 'fed.the_db.stats.samples_by_order', [
[ 'Int', 'perl_int', 57 ],
[ 'Int', 'perl_int', 45 ],
[ 'Int', 'perl_int', 63 ],
[ 'Int', 'perl_int', 61 ],
] ]
This node type represents a bag value. It has 3 elements:
Str value Bag.
Array|Str that is a valid payload for a Cat.NameChain.
aoa_counted, array_repeated, perl_bag (p6).
Bag|KeyBag value or Array|Seq or
Array|Seq of Array|Seq.
This node is interpreted as a Muldis D sys.Core.Relation.Bag value whose
heading was predefined, as a bag data type, for referencing now by the type
name, and whose body is defined now by the payload. The payload is
interpreted as follows:
aoa_counted, then the payload must be a Perl
Array|Seq, and each element of the payload defines a binary tuple of the
new bag; the element is a 2-element Array|Seq, and those 2 elements, by
index order, are PHMD nodes that define the value and count
attributes of the tuple; the count must be a positive integer.
array_repeated, then the payload must be a Perl
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 value
attribute of the tuple. The bag has 1 tuple for every distinct (after
format normalization) element value in the payload, and the count
attribute of that tuple says how many instances of said element were in the
payload.
perl_bag, then the payload must be a Perl 6
(there is no Perl 5 analogy) Bag|KeyBag value; the payload elements are
PHMD nodes corresponding to the value attribute of the new bag's tuples,
and the mapping is as you should expect.
Examples:
[ 'Bag', 'fed.the_db.inventory.fruit', 'aoa_counted', [
[
[ 'Text', 'Apple' ],
[ 'PInt', 'perl_uint', 500 ],
],
[
[ 'Text', 'Orange' ],
[ 'PInt', 'perl_uint', 300 ],
],
[
[ 'Text', 'Banana' ],
[ 'PInt', 'perl_uint', 400 ],
],
] ]
[ 'Bag', 'fed.the_db.inventory.whatsits', 'array_repeated', [
[ 'Text', 'Foo' ],
[ 'Text', 'Quux' ],
[ 'Text', 'Foo' ],
[ 'Text', 'Bar' ],
[ 'Text', 'Baz' ],
[ 'Text', 'Baz' ],
] ]
This node type represents a canonical short name for any kind of DBMS
entity when declaring it; it is a non-empty character string type, that is
disjoint from Text. It has 2 elements:
Str value Cat.Name.
This node is interpreted as a Muldis D sys.Core.Cat.Name value by
directly mapping the payload. Note that, while Concrete Muldis D may
contain a few escape sequences, those would be replaced with what they
represent prior to making a PHMD node. They payload must be as per a
NEText PHMD node.
Examples:
[ 'Cat.Name', 'login_pass' ]
[ 'Cat.Name', 'First Name' ]
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:
Str value Cat.NameChain.
Array|Seq value or Str (char-mode scalar) value.
This node is interpreted as a Muldis D sys.Core.Cat.NameChain value as
follows:
Array|Seq, then it must have at least 1 element,
and every element must be a valid payload for a Cat.Name PHMD node (that
is, any non-empty Perl character string). Each element of the payload, in
order, defines an element of the sequence possrep of a Cat.NameChain.
Str, then it must be formatted as a catenation
(using period (.) separators) of at least 1 part, where each part is
escaped such that backslashes, single-quotes, and periods are escaped as
\b, \q and \p respectively.
Examples:
[ 'Cat.NameChain', ['fed','the_db','gene','sorted_person_name'] ]
[ 'Cat.NameChain', 'fed.the_db.stats.samples_by_order' ]
Go to the Language::MuldisD manpage for the majority of distribution-internal references, and the Language::MuldisD::SeeAlso manpage for the majority of distribution-external references.
Darren Duncan (perl@DarrenDuncan.net)
This file is part of the formal specification of the Muldis D language.
Muldis D is Copyright © 2002-2007, Darren Duncan.
See the LICENSE AND COPYRIGHT of the Language::MuldisD manpage for details.
The ACKNOWLEDGEMENTS in the Language::MuldisD manpage apply to this file too.
|
Language::MuldisD::PerlHosted - How to format Perl Hosted Abstract Muldis D |