=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Routines_Catalog -
Muldis D data definition routines

=head1 VERSION

This document is Muldis::D::Core::Routines_Catalog version 0.101.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.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

These core routines are more special-purpose in nature and are intended for
use in working with the system catalog.

=head1 FUNCTIONS FOR SIMPLE GENERIC SCALAR TYPES

=head2 sys.std.Core.Cat.Order.reverse

C<< function sys.std.Core.Cat.Order.reverse (Order <-- $topic : Order) >>

This function results in the reverse value of its argument; an
C<Order:increase> or C<Order:decrease> argument results in the other one of
the two; an C<Order:same> argument results in itself.

=head2 sys.std.Core.Cat.Order.conditional_reverse

C<< function sys.std.Core.Cat.Order.conditional_reverse (Order <--
$topic : Order, $is_reverse_order : Bool) >>

This function results in the reverse value of its C<topic> argument as per
C<Order.reverse> iff its C<is_reverse_order> argument is C<Bool:true>;
otherwise this function simply results in C<topic> itself.  This function
is intended for use in the definition of C<order-determination> functions
where the definer wants to expend the minimal coding effort while
supporting the mandatory C<is_reverse_order> parameter; they can just write
the fundamental function body once, for the normal ascending algorithm, and
pass the result of that algorithm through C<Order.conditional_reverse>.

=head2 sys.std.Core.Cat.Order.reduction

C<< function sys.std.Core.Cat.Order.reduction (Order <--
$topic? : array_of.Order) >>

This function results in the lowest-indexed of its N input element values
that isn't equal to C<Order:same>, if there is such an input value, and
otherwise it results in C<Order:same>.  It is a reduction operator that
recursively takes each consecutive pair of input values, for each pair
picking the lower-indexed one if that isn't equal to C<Order:same> and
otherwise picking the higher-indexed one (a process which is associative),
until just one is left, which is the result.  If C<topic> has zero values,
then C<Order.reduction> results in C<Order:same>, which is the identity
value for this operation.  The purpose of this function is to provide a
canonical terse way to chain invocations of multiple C<order-determination>
functions to derive a larger such function, such as when you want to define
an C<order-determination> function for a tuple type, which would then be
your control for sorting a relation as per a SQL "ORDER BY" or "RANK".
Note that this operation is also known as I<reduction over order> or
C<< [<=>] >>.

=head1 ROUTINES FOR INVOKING ROUTINES

=head2 sys.std.Core.Cat.func_invo

C<< function sys.std.Core.Cat.func_invo (Universal <--
$function : FuncRef, $args? : Tuple) >>

This function results in the result of invoking the other function named in
its C<function> argument with arguments supplied by this function's C<args>
argument; each attribute name of C<args> is mapped to a parameter name of
the invoked function, and the corresponding attribute value is the
corresponding argument for the function invocation.  This function will
fail if the invoked function has any non-optional parameters such that
there aren't any corresponding attributes in C<args>, or if there are any
attributes in C<args> that don't have corresponding parameters, or if any
attribute values aren't of the declared types of the corresponding
parameters.  The purpose of C<func_invo> is to support invocation of any
function whose name or parameters potentially aren't known until runtime;
it forms the foundation of all other system-defined functions that want to
invoke a function whose name they take as an argument.  The C<args>
parameter is optional and defaults to the zero-attribute tuple if no
explicit argument is given to it.

=head2 sys.std.Core.Cat.curried_func

C<< function sys.std.Core.Cat.curried_func (FuncRef <--
$function : FuncRef, $args : Tuple) >>

This function results in a reference to a new anonymous function which is
the result of currying the other function named in its C<function> argument
with 0..N arguments supplied by this function's C<args> argument; each
attribute name of C<args> is mapped to a parameter name of the curried
function, and the corresponding attribute value is the corresponding
pre-bound parameter of the curried function.  This function will fail if
there are any attributes in C<args> that don't have corresponding
parameters, or if any attribute values aren't of the declared types of the
corresponding parameters.  A curried function effectively does not have the
parameters of the original function that were pre-bound, and attempts to
supply arguments to those on the curried function will fail.  Note that the
result of a C<curried_func> invocation can be used as input to another one,
as there is effectively no difference in their kind.  The purpose of
C<curried_func> is to support the passing of functions as arguments to
invocations of other routines where the passed function wants to use
runtime-defined information in the context that invoked routine, without
having to pass that information separately as additional routine arguments.
Or the purpose of C<curried_func> is just to easily support defining
functions as simplified versions of others.

=head2 sys.std.Core.Cat.upd_invo

C<updater sys.std.Core.Cat.upd_invo ($updater : UpdRef,
&$upd_args : Tuple, $ro_args? : Tuple)>

This update operator has the same purpose and features as
C<sys.std.Core.Cat.func_invo> but that it invokes an updater rather
than a function; there is no result to deal with, and there are both
subject-to-update parameters and read-only parameters of the invoked
updater to bind to; they are bound with the attributes of this updater's
C<upd_args> and C<ro_args> arguments, respectively.  The C<ro_args>
parameter is optional and defaults as per the C<args> parameter of
C<func_invo>; the C<upd_args> parameter is non-optional because an updater
must always be invoked with at least one subject-to-update argument.

These procedures are applicable to use in all kinds of procedures.

=head2 sys.std.Core.Cat.proc_invo

C<procedure sys.std.Core.Cat.proc_invo ($procedure : ProcRef,
&$upd_args? : Tuple, $ro_args? : Tuple)>

This procedure is the same as C<sys.std.Core.Cat.upd_invo> but that it
invokes a procedure (or system-service) rather than an updater, and
that C<upd_args> is optional.

=head1 ROUTINES FOR WORKING WITH EXCEPTIONS

=head2 sys.std.Core.Cat.fail

C<procedure sys.std.Core.Cat.fail ($topic : Exception)>

This procedure will throw the exception given as its argument; this results
in the call stack unwinding, and transaction rollbacks, until it is caught.

=head2 sys.std.Core.Cat.try_catch

C<procedure sys.std.Core.Cat.try_catch
($try : ProcRef, &$try_upd_args? : Tuple, $try_ro_args? : Tuple,
$catch? : ProcRef, &$catch_upd_args? : Tuple, $catch_ro_args? : Tuple)>

This procedure invokes the procedure (or system-service)
named in its C<try> argument
with arguments supplied by this procedure's C<try_upd_args> and
C<try_ro_args> arguments; each attribute name of C<try_[upd|ro]_args> is
mapped to a parameter name of the invoked procedure, and the corresponding
attribute value is the corresponding argument for the procedure
invocation.  If the C<try> routine
throws an exception, then any state changes it made roll back (but changes
made before that don't), and the call stack unwinds to the C<try_catch>
itself; then the procedure named by C<catch> is invoked similarly
to C<try> was, with corresponding arguments, but with the extra read-only
argument C<topic> whose value is an C<Exception>; if the C<catch> routine
also throws an exception (such as to say its not handling the thrown one),
then that one is not caught and the call stack unwinding plus applicable
transaction rollback carries on to the caller of the C<try_catch>.  If the
C<try> routine succeeds (doesn't throw an exception), then the C<catch>
routine is not called.  Each of the C<[try|catch]_[upd|ro]_args>
parameters is optional and defaults to the zero-attribute tuple if no
explicit argument is given to it.

=head1 ROUTINES FOR SPECIAL ENTITY REFERENCE DEFAULT VALUES

These routines are defined primarily for use in the definitions of several
reference types that are references to routines; each one is an example
routines of an appropriate structure such that the reference types can use
references to these routines as their default values.

=head2 sys.std.Core.Cat.pass_topic

C<< function sys.std.Core.Cat.pass_topic (Bool <-- $topic : Universal) >>

This C<value-filter> function unconditionally results in C<Bool:true>
regardless of the values of its arguments.

=head2 sys.std.Core.Cat.map_to_topic

C<< function sys.std.Core.Cat.map_to_topic (Universal <--
$topic : Universal) >>

This C<value-map> function unconditionally results in its C<topic> argument
regardless of the values of its arguments.

=head2 sys.std.Core.Cat.reduce_to_v1

C<< function sys.std.Core.Cat.reduce_to_v1 (Universal <-- $v1 : Universal,
$v2 : Universal) >>

This C<value-reduction> function unconditionally results in its C<v1>
argument regardless of the values of its arguments.

=head2 sys.std.Core.Cat.noop

C<< procedure sys.std.Core.Cat.noop () >>

This procedure has no parameters and doesn't do anything at all.

=head1 PROCEDURES FOR BOOTSTRAPPING A MULDIS D PROGRAM OR DATABASE

These procedures comprise a set of commonly useful system-defined data
definition routines, which simplify some tasks of manipulating the Muldis D
system catalog dbvars.  The following procedures can do the following:
create|mount and drop|unmount depots, set|clear topic namespaces,
create|drop subdepots, create|drop user-defined routines and
data types; they can not create or drop relvars.

=head1 Procedures For Defining Depot Mounts

=head2 sys.std.Core.Cat.create_depot_mount

C<procedure sys.std.Core.Cat.create_depot_mount ($name : Name,
$comment? : Comment, $is_temporary? : Bool, $create_on_mount? : Bool,
$delete_on_unmount? : Bool, $we_may_update? : Bool,
$details? : OVLScaValExprNodeSet)>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<mnt.cat.mounts>.  It will create a new depot mount in the DBMS
whose name is given by the C<name> argument and whose other mount control
details match the other arguments; the mount may be for either an existing
depot or for a newly created one.  This procedure is analagous to a SQL
CONNECT statement or SQLite ATTACH statement.

=head2 sys.std.Core.Cat.drop_depot_mount

C<procedure sys.std.Core.Cat.drop_depot_mount ($name : Name)>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<mnt.cat.mounts>.  It will drop an existing depot mount from the
DBMS whose name is given by the argument; the depot behind the mount may
then either cease to exist or persist on.  This procedure is analagous to a
SQL DISCONNECT statement or SQLite DETACH statement.

=head2 sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update

C<procedure sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update
($name : Name)>

This procedure is an abstraction over updating a tuple of the catalog
relvar C<mnt.cat.mounts> such that its C<we_may_update> attribute is made
C<Bool:false>.

=head1 Procedures For Defining Topic Namespaces

=head2 sys.std.Core.Cat.select_topic_namespaces

C<procedure sys.std.Core.Cat.select_topic_namespaces
($depot? : maybe_of.Name, $subdepot? : maybe_of.DeclNameChain,
$comment? : Comment)>

This procedure is an abstraction over assigning a new value to the catalog
variable C<tpc.cat>; the 3 parameters correspond directly to the attributes
of C<tpc.cat>.  If all the arguments are omitted, then C<tpc.cat> will have
its default value of all-C<nothing> attributes, meaning there are no
default namespaces.  If C<subdepot> is a C<Single> then C<depot> must be.

=head1 Procedures For Defining In-Depot Namespaces

These 2 procedures conceptually have the extra 2 parameters C<$depot :
Name, $parent? : DeclNameChain>, whose values are implicitly supplied from
C<tpc.cat.topic_[depot|subdepot]> respectively; those 1 or 2 (as
applicable) catalog variables must be non-empty as a precondition to
invoking the 2 procedures.

=head2 sys.std.Core.Cat.create_subdepot

C<procedure sys.std.Core.Cat.create_subdepot ($name : Name,
$comment? : Comment)>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.subdepots>.  It will create a
new subdepot, in the depot mounted under the name given by the C<depot>
argument, whose name and other details match the other arguments.  This
procedure is analagous to a SQL CREATE SCHEMA statement or an Oracle CREATE
PACKAGE statement.

=head2 sys.std.Core.Cat.drop_subdepot

C<procedure sys.std.Core.Cat.drop_subdepot ($name : Name)>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.subdepots>.  It will drop an
existing subdepot.  This procedure is analagous to a SQL DROP SCHEMA
statement or an Oracle DROP PACKAGE statement.

=head1 Procedures For Defining Depot Routines and Data Types

These 14 procedures conceptually have the extra 2 parameters C<$depot :
Name, $subdepot? : DeclNameChain>, whose values are implicitly supplied
from C<tpc.cat.topic_[depot|subdepot]> respectively; those 1 or 2 (as
applicable) catalog variables must be non-empty as a precondition to
invoking the 14 procedures.

=head2 sys.std.Core.Cat.create_[function|updater|procedure]

C<procedure sys.std.Core.Cat.create_[function|updater|procedure]
($name : Name, $comment? : Comment,
[Function|Updater|Procedure] $material)>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.[function|updater|procedure]s>.
It will create a new function|updater|procedure, in the depot mounted under
the name given by the C<depot> argument, whose name and other details match
the other arguments.  This procedure is analagous to a SQL CREATE
FUNCTION|PROCEDURE statement.

=head2 sys.std.Core.Cat.drop_[function|updater|procedure]

C<procedure sys.std.Core.Cat.drop_[function|updater|procedure]
($name : Name)>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.[function|updater|procedure]s>.
It will drop an existing depot function|updater|procedure.  This procedure
is analagous to a SQL DROP FUNCTION|PROCEDURE statement.

=head2 sys.std.Core.Cat.create_[scalar|nonscalar|union|subset]_type

C<procedure sys.std.Core.Cat.create_[scalar|nonscalar|union|subset]_type
($name : Name, $comment? : Comment,
[Scalar|Nonscalar|Union|Subset]$material : Type)>

This procedure is an abstraction over inserting a tuple into the catalog
relvar
C<fed.cat.mounts{name=$depot}.depot.[scalar|nonscalar|union|subset]_types>.
It will create a new type, in the depot mounted under the name given by the
C<depot> argument, whose name and other details match the other arguments.
This procedure is analagous to a SQL CREATE TYPE|DOMAIN statement.

=head2 sys.std.Core.Cat.drop_[scalar|nonscalar|union|subset]_type

C<procedure sys.std.Core.Cat.drop_[scalar|nonscalar|union|subset]_type
($name : Name)>

This procedure is an abstraction over deleting a tuple from the catalog
relvar
C<fed.cat.mounts{name=$depot}.depot.[scalar|nonscalar|union|subset]_types>.
It will drop an existing depot type.  This procedure is analagous to a SQL
DROP TYPE|DOMAIN statement.

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT

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

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

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

=head1 TRADEMARK POLICY

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

=head1 ACKNOWLEDGEMENTS

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

=cut
