NAME
Muldis::Rosetta::Interface - Common public API for Muldis Rosetta Engines
VERSION
This document describes Muldis::Rosetta::Interface version 0.9.0 for Perl 5.
It also describes the same-number versions for Perl 5 of Muldis::Rosetta::Interface::Machine ("Machine"), Muldis::Rosetta::Interface::Process ("Process"), Muldis::Rosetta::Interface::Value ("Value").
SYNOPSIS
This simple example declares two Perl variables containing relation data, then does a (N-ary) relational join (natural inner join) on them, producing a third Perl variable holding the relation data of the result.
use Muldis::Rosetta::Interface;
my $machine = Muldis::Rosetta::Interface::new_machine({
'engine_name' => 'Muldis::Rosetta::Engine::Example' });
my $process = $machine->new_process();
$process->update_command_lang({ 'lang' => [ 'Muldis_D',
'http://muldis.com', '0.43.0', 'HDMD_Perl_Tiny', {} ] });
my $r1 = $process->new_value({ 'source_code' => [ 'Relation', [
{
'x' => [ 'Int', 'perl_int', 4 ],
'y' => [ 'Int', 'perl_int', 7 ],
},
{
'x' => [ 'Int', 'perl_int', 3 ],
'y' => [ 'Int', 'perl_int', 2 ],
},
] ] });
my $r2 = $process->new_value({ 'source_code' => [ 'Relation', [
{
'y' => [ 'Int', 'perl_int', 5 ],
'z' => [ 'Int', 'perl_int', 6 ],
},
{
'y' => [ 'Int', 'perl_int', 2 ],
'z' => [ 'Int', 'perl_int', 1 ],
},
{
'y' => [ 'Int', 'perl_int', 2 ],
'z' => [ 'Int', 'perl_int', 4 ],
},
] ] });
my $r3 = $process->func_invo({
'function' => 'sys.std.Core.Relation.join',
'args' => {
'topic' => [ 'QuasiSet', [ $r1, $r2 ] ],
}
});
my $r3_as_perl = $r3->source_code();
# Then $r3_as_perl contains:
# [ 'Relation', [
# {
# 'x' => [ 'Int', 'perl_int', 3 ],
# 'y' => [ 'Int', 'perl_int', 2 ],
# 'z' => [ 'Int', 'perl_int', 1 ],
# },
# {
# 'x' => [ 'Int', 'perl_int', 3 ],
# 'y' => [ 'Int', 'perl_int', 2 ],
# 'z' => [ 'Int', 'perl_int', 4 ],
# },
# ] ]
For most examples of using Muldis Rosetta, and tutorials, please see the separate Muldis::Rosetta::Cookbook distribution (when that comes to exist).
DESCRIPTION
Muldis::Rosetta::Interface, aka Interface, comprises the minimal core of the Muldis Rosetta framework, the one component that probably every program would use. Together with the Muldis D language (see Muldis::D), it defines the common API for Muldis Rosetta implementations to do and which applications invoke.
This documentation is pending.
INTERFACE
The interface of Muldis::Rosetta::Interface is fundamentally object-oriented; you use it by creating objects from its member classes (or more specifically, of implementing subclasses of its member roles) and then invoking methods on those objects. All of their attributes are private, so you must use accessor methods.
To aid portability of your applications over multiple implementing Engines, the normal way to create Interface objects is by invoking a constructor-wrapping method of some other object that would provide context for it; since you generally don't have to directly invoke any package names, you don't need to change your code when the package names change due to switching the Engine. You only refer to some Engine's root package name once, as a Muldis::Rosetta::Interface::new_machine
argument, and even that can be read from a config file rather than being hard-coded in your application.
The usual way that Muldis::Rosetta::Interface indicates a failure is to throw an exception; most often this is due to invalid input. If an invoked routine simply returns, you can assume that it has succeeded, even if the return value is undefined.
The Muldis::Rosetta::Interface Module
The Muldis::Rosetta::Interface
module is the stateless root package by way of which you access the whole Muldis Rosetta API. That is, you use it to load engines and instantiate virtual machines, which provide the rest of the Muldis Rosetta API.
new_machine of Muldis::Rosetta::Interface::Machine (Str :$engine_name!, Any :$machine_config?)
-
This constructor function creates and returns a
Machine
object that is implemented by the Muldis Rosetta Engine named by its named argument$engine_name
; that object is initialized using the$machine_config
argument. The named argument$engine_name
is the name of a Perl module that is expected to be the root package of a Muldis Rosetta Engine, and which is expected to declare anew_machine
subroutine with a single named argument$machine_config
; invoking this subroutine is expected to return an object of some class of the same Engine which does theMuldis::Rosetta::Interface::Machine
role. This function will start by testing if the root package is already loaded (it may be declared by some already-loaded file of another name), and only if not, will it do a Perl 'require' of the$engine_name
.
The Muldis::Rosetta::Interface::Machine Role
A Machine
object represents a single active Muldis Rosetta virtual machine / Muldis D environment, which is the widest scope stateful context in which any other database activities happen. Other activities meaning the compilation and execution of Muldis D code, mounting or unmounting depots, performing queries, data manipulation, data definition, and transactions. If a Machine
object is ever garbage collected by Perl while it has any active transactions, then those will all be rolled back, and then an exception thrown.
new_process of Muldis::Rosetta::Interface::Process (Any :$process_config?)
-
This method creates and returns a new
Process
object that is associated with the invocantMachine
; thatProcess
object is initialized using the$process_config
argument. assoc_processes of Array ()
-
This method returns, as elements of a new (unordered) Array, all the currently existing
Process
objects that are associated with the invocantMachine
.
The Muldis::Rosetta::Interface::Process Role
A Process
object represents a single Muldis Rosetta in-DBMS process, which has its own autonomous transactional context, and for the most part, its own isolated environment. It is associated with a specific Machine
object, the one whose new_process
method created it.
A new Process
object's "expected command language" attribute is undefined by default, meaning that each command fed to it must declare what language it is written in; if that attribute was made defined, then commands fed to it would not need to declare their language and will be interpreted according to the expected language.
assoc_machine of Muldis::Rosetta::Interface::Machine ()
-
This method returns the
Machine
object that the invocantProcess
is associated with. command_lang of Any ()
-
This method returns the fully qualified name of its invocant
Process
object's "expected command language" attribute, which might be undefined; if it is defined, then is either a Perl Str that names a Plain Text language, or it is a Perl (ordered) Array that names a Perl Hosted Data language; these may be Muldis D dialects or some other language. update_command_lang (Any :$lang!)
-
This method assigns a new (possibly undefined) value to its invocant
Process
object's "expected command language" attribute. This method dies if the specified language is defined and its value isn't one that the invocant's Engine knows how to or desires to handle. execute (Any :$source_code!)
-
This method compiles and executes the (typically Muldis D) source code given in its
$source_code
argument. This method dies if the source code fails to compile for some reason, or if the executing code has a runtime exception. new_value of Muldis::Rosetta::Interface::Value (Any :$source_code!)
-
This method creates and returns a new
Value
object that is associated with the invocantProcess
; thatValue
object is initialized using the (typically Muldis D) source code given in its$source_code
argument, which defines a value literal. If the$source_code
is in a Perl Hosted Data language, then it may consist partially of otherValue
objects. If$source_code
is itself just aValue
object, then this method will just return that same object. assoc_values of Array ()
-
This method returns, as elements of a new (unordered) Array, all the currently existing
Value
objects that are associated with the invocantProcess
. func_invo of Muldis::Rosetta::Interface::Value (Str :$function!, Hash :$args?)
-
This method invokes the Muldis D function named by its
$function
argument, giving it arguments from$args
, and then returning the result as aValue
object. Each$args
Hash key must match the name of a parameter of the named function, and the corresponding Hash value is the argument for that parameter; each Hash value may be either aValue
object or some other Perl value that would be suitable as the sole constructor argument for a newValue
object. upd_invo (Str :$updater!, Hash :$upd_args!, Hash :$ro_args?)
-
This method invokes the Muldis D updater named by its
$updater
argument, giving it subject-to-update arguments from$upd_args
and read-only arguments from$ro_args
; theValue
objects in$upd_args
are possibly substituted for othervalue
objects as a side-effect of the updater's execution. The$ro_args
parameter is as per the$args
parameter of thefunc_invo
method, but the$upd_args
parameter is a bit different; each Hash value in the$upd_args
argument must be a Perl scalar reference pointing to the Perl variable being bound to the subject-to-update parameter; said Perl variable is then what holds aValue
object et al prior to the updater's execution, and that may have been updated to hold a differentValue
object as a side-effect. proc_invo (Str :$procedure!, Hash :$upd_args?, Hash :$ro_args?)
-
This method invokes the Muldis D procedure (or system_service) named by its
$procedure
argument, giving it subject-to-update arguments from$upd_args
and read-only arguments from$ro_args
; theValue
objects in$upd_args
are possibly substituted for othervalue
objects as a side-effect of the procedure's execution. The parameters ofproc_invo
are as per those of theupd_invo
method, save that onlyupd_invo
makes$upd_args
mandatory, whileproc_invo
makes it optional. trans_nest_level of Int ()
-
This method returns the current transaction nesting level of its invocant's virtual machine process. If no explicit transactions were started, then the nesting level is zero, in which case the process is conceptually auto-committing every successful Muldis D statement. Each call of
start_trans
will increase the nesting level by one, and eachcommit_trans
orrollback_trans
will decrease it by one (it can't be decreased below zero). Note that all transactions started or ended within Muldis D code (except direct boot_call transaction management) are attached to a particular lexical scope in the Muldis D code (specifically a "try/catch" context), and so they will never have any effect on the nest level that Perl sees (assuming that a Muldis D host language will never be invoked by Muldis D), regardless of whether the Muldis D code successfully returns or throws an exception. start_trans ()
-
This method starts a new child-most transaction within the invocant's virtual machine process.
commit_trans ()
-
This method commits the child-most transaction within the invocant's virtual machine process; it dies if there isn't one.
rollback_trans ()
-
This method rolls back the child-most transaction within the invocant's virtual machine process; it dies if there isn't one.
The Muldis::Rosetta::Interface::Value Role
A Value
object represents a single Muldis Rosetta in-DBMS value, which is conceptually immutable, eternal, and not fixed in time or space; the object is immutable. It is associated with a specific Process
object, the one whose new_value
method created it. You can use Value
objects in Perl routines the same as normal immutable Perl values or objects, including that you just do ordinary Perl variable assignment. Value
objects are the normal way to directly share or move data between the Muldis Rosetta DBMS and main Perl environments. The value that a Value
object represents is set when the Value
object is created, and it can't be changed afterwards.
assoc_process of Muldis::Rosetta::Interface::Process ()
-
This method returns the
Process
object that the invocantValue
is associated with. source_code of Any (Any :$lang?)
-
This method returns (typically Muldis D) source code that defines a value literal equivalent to the in-DBMS value that the invocant
Value
represents. The language of the source code to return must be explicitly specified, either by giving a defined$lang
argument, or by ensuring that theProcess
object associated with thisValue
has a defined "expected command language" attribute.
DIAGNOSTICS
This documentation is pending.
CONFIGURATION AND ENVIRONMENT
This documentation is pending.
DEPENDENCIES
This file requires any version of Perl 5.x.y that is at least 5.8.1, and recommends one that is at least 5.10.0.
It also requires these Perl 5 packages that are bundled with any version of Perl 5.x.y that is at least 5.10.0, and are also on CPAN for separate installation by users of earlier Perl versions: version.
It also requires these Perl 5 packages that are on CPAN: Moose::Role-0.55.
INCOMPATIBILITIES
None reported.
SEE ALSO
Go to Muldis::Rosetta for the majority of distribution-internal references, and Muldis::Rosetta::SeeAlso for the majority of distribution-external references.
BUGS AND LIMITATIONS
The Muldis Rosetta framework for Perl 5 is built according to certain old-school or traditional Perl-5-land design principles, including that there are no explicit attempts in code to enforce privacy of the framework's internals, besides not documenting them as part of the public API. (The Muldis Rosetta framework for Perl 6 is different.) That said, you should still respect that privacy and just use the public API that Muldis Rosetta provides. If you bypass the public API anyway, as Perl 5 allows, you do so at your own peril.
This documentation is pending.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net
)
LICENSE AND COPYRIGHT
This file is part of the Muldis Rosetta framework.
Muldis Rosetta is Copyright © 2002-2008, Darren Duncan.
See the LICENSE AND COPYRIGHT of Muldis::Rosetta for details.
TRADEMARK POLICY
The TRADEMARK POLICY in Muldis::Rosetta applies to this file too.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::Rosetta apply to this file too.