=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.148.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 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 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 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 func_invo (Universal <--
function : APFunctionNC, 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_invo

C<< function curried_func_invo (Universal <--
function : CurriedFuncNC) {...} >>

This function is a simple wrapper for C<func_invo> that has the latter's 2
parameters combined into a single binary tuple parameter.  It is likely
that C<curried_func_invo> will see the most use in practice, as
C<CurriedFuncNC> would be the type of choice for higher-order function
parameters of other routines.

=head2 sys.std.Core.Cat.curried_func_static_exten

C<< function curried_func_static_exten (CurriedFuncNC <--
function : CurriedFuncNC, args : Tuple) >>

This function results in the C<CurriedFuncNC> value that is the same as its
C<function> argument except that the value's C<args> attribute has been
extended with the attributes given in the C<args> argument.  This function
will fail if its C<function> and C<args> arguments have any same-named
arguments for the curried function.  Note that this operation is also known
as C<assuming>.

=head2 sys.std.Core.Cat.proc_invo

C<procedure proc_invo (procedure : APProcedureNC,
&upd_args? : Tuple, ro_args? : Tuple) {...}>

This procedure has the same purpose and features as
C<sys.std.Core.Cat.func_invo> but that it invokes a procedure 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
procedure to bind to; they are bound with the attributes of this
procedure'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 if the invoked
is an updater, because an updater must always be invoked with at least one
subject-to-update argument, and it is optional otherwise.

=head1 PROCEDURES FOR WORKING WITH EXCEPTIONS

=head2 sys.std.Core.Cat.fail

C<procedure 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.

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

=head1 RECIPES FOR BOOTSTRAPPING A MULDIS D PROGRAM OR DATABASE

These recipes 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 recipes can do the following:
create|mount and drop|unmount depots,
create|drop subdepots, create|drop user-defined routines and
data types; they can not create or drop relvars.

=head1 Recipes For Defining Depot Mounts

=head2 sys.std.Core.Cat.create_depot_mount

C<recipe create_depot_mount (name : Name,
scm_comment? : Comment, is_temporary? : Bool, create_on_mount? : Bool,
delete_on_unmount? : Bool, we_may_update? : Bool,
allow_auto_run? : Bool, details? : SysScaValExprNodeSet,
&mounts ::= mnt.cat.mounts) {...}>

This recipe 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 recipe is analogous to a SQL
CONNECT statement or SQLite ATTACH statement.

=head2 sys.std.Core.Cat.drop_depot_mount

C<recipe drop_depot_mount (name : Name,
&mounts ::= mnt.cat.mounts) {...}>

This recipe 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 recipe is analogous to a
SQL DISCONNECT statement or SQLite DETACH statement.

=head2 sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update

C<recipe alter_depot_mount_so_we_may_not_update
(name : Name, &mounts ::= mnt.cat.mounts) {...}>

This recipe 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 Recipes For Defining In-Depot Namespaces

=head2 sys.std.Core.Cat.create_subdepot

C<recipe create_subdepot (depot : Name,
parent? : NameChain, name : Name, scm_comment? : Comment,
scm_vis_ord? : NNInt, &cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe 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
recipe is analogous to a SQL CREATE SCHEMA statement or an Oracle CREATE
PACKAGE statement.

=head2 sys.std.Core.Cat.drop_subdepot

C<recipe drop_subdepot (depot : Name,
parent? : NameChain, name : Name,
&cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe 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 recipe is analogous to a SQL DROP SCHEMA
statement or an Oracle DROP PACKAGE statement.

=head1 Recipes For Defining Depot Materials

=head2 sys.std.Core.Cat.create_function

C<recipe create_function (depot : Name,
subdepot? : NameChain, name : Name,
scm_comment? : Comment, scm_vis_ord? : NNInt,
material : Function, &cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=depot}.depot.functions>.  It will create a
new function, in the depot mounted under the name given by the C<depot>
argument, whose name and other details match the other arguments.  This
recipe is analogous to a SQL CREATE FUNCTION statement.

=head2 sys.std.Core.Cat.drop_function

C<recipe drop_function (depot : Name,
subdepot? : NameChain, name : Name,
&cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe is an abstraction over deleting a tuple from the catalog relvar
C<fed.cat.mounts{name=depot}.depot.functions>.  It will drop an existing
depot function.  This recipe is analogous to a SQL DROP FUNCTION statement.

=head2 sys.std.Core.Cat.create_procedure

C<recipe create_procedure (depot : Name,
subdepot? : NameChain, name : Name,
scm_comment? : Comment, scm_vis_ord? : NNInt,
material : Procedure, &cat ::= fed.cat) {...}>

This recipe is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=depot}.depot.procedures>.
It will create a new procedure, in the depot mounted under
the name given by the C<depot> argument, whose name and other details match
the other arguments.  This recipe is analogous to a SQL CREATE PROCEDURE
statement.

=head2 sys.std.Core.Cat.drop_procedure

C<recipe drop_procedure (depot : Name,
subdepot? : NameChain, name : Name, &cat ::= fed.cat) {...}>

This recipe is an abstraction over deleting a tuple from the catalog relvar
C<fed.cat.mounts{name=depot}.depot.procedures>.  It will
drop an existing depot procedure.  This recipe is analogous
to a SQL DROP PROCEDURE statement.

=head2 sys.std.Core.Cat.create_[scalar|tuple|relation|domain|subset|mixin]_type

C<recipe create_[scalar|tuple|relation|domain|subset|mixin]_type
(depot : Name, subdepot? : NameChain, name : Name,
scm_comment? : Comment, scm_vis_ord? : NNInt,
material : [Scalar|Tuple|Relation|Domain|Subset|Mixin]Type,
&cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=depot}.depot
.[scalar|tuple|relation|domain|subset|mixin]_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 recipe is analogous to a SQL CREATE TYPE|DOMAIN statement.

=head2 sys.std.Core.Cat.drop_[scalar|tuple|relation|domain|subset|mixin]_type

C<recipe drop_[scalar|tuple|relation|domain|subset|mixin]_type
(depot : Name, subdepot? : NameChain, name : Name,
&cat ::= fed.cat, &data ::= fed.data) {...}>

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

=head2 sys.std.Core.Cat.create_[|distrib_][key|subset]_constr

C<recipe create_[|distrib_][key|subset]_constr
(depot : Name, subdepot? : NameChain, name : Name,
scm_comment? : Comment, scm_vis_ord? : NNInt,
material : [|Distrib][Key|Subset]Constr,
&cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe is an abstraction over inserting a tuple into the catalog
relvar
C<fed.cat.mounts{name=depot}.depot.[|distrib_][key|subset]_constrs>.
It will create a new constraint, in the depot mounted under the name given
by the C<depot> argument, whose name and other details match the other
arguments.

=head2 sys.std.Core.Cat.drop_[|distrib_][key|subset]_constr

C<recipe drop_[|distrib_][key|subset]_constr
(depot : Name, subdepot? : NameChain, name : Name,
&cat ::= fed.cat, &data ::= fed.data) {...}>

This recipe is an abstraction over deleting a tuple from the catalog relvar
C<fed.cat.mounts{name=depot}.depot.[|distrib_][key|subset]_constrs>.
It will drop an existing depot constraint.

=head2 sys.std.Core.Cat.create_stim_resp_rule

C<recipe create_stim_resp_rule (depot : Name,
subdepot? : NameChain, name : Name, scm_comment? : Comment,
scm_vis_ord? : NNInt, material : StimRespRule, &cat ::= fed.cat) {...}>

This recipe is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=depot}.depot.stim_resp_rules>.  It will
create a new stimulus-response rule, in the depot mounted under the name
given by the C<depot> argument, whose name and other details match the
other arguments.  This recipe is analogous to a SQL CREATE TRIGGER
statement.

=head2 sys.std.Core.Cat.drop_stim_resp_rule

C<recipe drop_stim_resp_rule (depot : Name,
subdepot? : NameChain, name : Name, &cat ::= fed.cat) {...}>

This recipe is an abstraction over deleting a tuple from the catalog relvar
C<fed.cat.mounts{name=depot}.depot.stim_resp_rules>.  It will drop an
existing depot stimulus-response rule.  This recipe is analogous to a SQL
DROP TRIGGER statement.

=head1 SYSTEM-DEFINED CONSTRAINT MATERIALS

=head2 sys.std.Core.Cat.nil_key_constr

C<key-constraint nil_key_constr {}>

This is a unique key constraint or candidate key, for a relation type,
which ranges over zero attributes, and is not designated a I<primary key>.
This exists as a C<key-constraint> material as a convenience for the
definition of relation types whose values are allowed to have at most one
tuple (C<Maybe> being an example).

=head2 sys.std.Core.Cat.nil_prim_key

C<key-constraint nil_prim_key {}>

This is exactly the same as C<sys.std.Core.Cat.nil_key_constr>, a key over
zero attributes, but that it I<is> designated a I<primary key>.

=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-2011, 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