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

This document contains one or more sections that were moved here from
L<Muldis::D::Core> so that said other document would not be too large.

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 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, $is_public? : Bool,
[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, $is_public? : Bool,
[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