=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.111.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 : 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.upd_invo

C<updater sys.std.Core.Cat.upd_invo ($updater : APUpdaterNC,
&$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.

=head2 sys.std.Core.Cat.proc_invo

C<procedure sys.std.Core.Cat.proc_invo ($procedure : APProcedureNC,
&$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 rather than an updater, and
that C<upd_args> is optional.

=head1 RECIPES FOR WORKING WITH EXCEPTIONS

=head2 sys.std.Core.Cat.fail

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

This recipe 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 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<recipe sys.std.Core.Cat.noop ()>

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

=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 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 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 sys.std.Core.Cat.drop_depot_mount ($name : Name)>

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 sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update
($name : Name)>

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 sys.std.Core.Cat.create_subdepot ($depot : Name,
$parent? : NameChain, $name : Name, $comment? : Comment)>

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 sys.std.Core.Cat.drop_subdepot ($depot : Name,
$parent? : NameChain, $name : Name)>

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 Routines and Data Types

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

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

This recipe 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 recipe is analogous to a SQL CREATE
FUNCTION|PROCEDURE statement.

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

C<recipe sys.std.Core.Cat.drop_[function|updater|procedure]
($depot : Name, $subdepot? : NameChain, $name : Name)>

This recipe 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 recipe
is analogous to a SQL DROP FUNCTION|PROCEDURE statement.

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

C<recipe sys.std.Core.Cat.create_[scalar|tuple|relation|domain|subset]_type
($depot : Name, $subdepot? : NameChain, $name : Name, $comment? : Comment,
$material : [Scalar|Tuple|Relation|Domain|Subset]Type)>

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]_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]_type

C<recipe sys.std.Core.Cat.drop_[scalar|tuple|relation|domain|subset]_type
($depot : Name, $subdepot? : NameChain, $name : Name)>

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]_types>.
It will drop an existing depot type.  This recipe is analogous 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-2010, 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
