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

=item C<function sys.std.Core.Cat.Order_reverse result Order params {
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.

=item C<function sys.std.Core.Cat.Order_reduction result Order params {
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 q/tuple type, which would then be
your control for sorting a q/relation as per a SQL "ORDER BY" or "RANK".

=head1 PROCEDURES FOR BOOTSTRAPPING A MULDIS D PROGRAM OR DATABASE

These procedures comprise a minimal set of system-defined data definition
routines that can be used by capability-limited bootloader routines in
order to setup a DBMS environment in which the rest of the Muldis D program
would live, and in order to create more other routines in that environment
which are more capable than bootloaders at setting up the rest of the DBMS
environment.

Generally speaking, most data definition requires manipulating the Muldis D
system catalog dbvars in sometimes complicated ways, and bootloaders alone
aren't capable of that in the general case, so typically a bootloader will
create procedures and updaters using its limited abilities such that the
created are capable of doing the more complicated manipulations.

After the bootloader creates those other routines and invokes them, the
bootloader can then invoke appropriate system-defined update operators
defined in L<Muldis::D::Core::Routines> to seed the database with data, if
applicable, such that those calls would probably make up the bulk of the
bootloader if the bootloader is a restore program for a database dump.

The following procedures can do the following: create|mount and
drop|unmount depots, set|clear topic namespaces, create|drop subdepots and
packages, create|drop user-defined routines and data types; they can not
create or drop relvars.

=head2 Procedures For Defining Depot Mounts

=over

=item C<procedure sys.std.Core.Cat.create_depot_mount update {} read {
name(Name), comment(Comment)?, is_temporary(Bool)?, create_on_mount(Bool)?,
delete_on_unmount(Bool)?, we_may_update(Bool)?, details(ScaLitExprNodeSet)?
}>

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.

=item C<procedure sys.std.Core.Cat.drop_depot_mount update {} read {
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.

=item C<procedure sys.std.Core.Cat.alter_depot_mount_so_we_may_not_update
update {} read { 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>.

=back

=head2 Procedures For Defining Topic Namespaces

=over

=item C<procedure sys.std.Core.Cat.select_topic_namespaces update {} read {
depot(maybe_of.Name)?, subdepot(maybe_of.DeclNameChain)?,
package(maybe_of.Name)?, comment(Comment)? }>

This procedure is an abstraction over assigning a new value to the catalog
variable C<tpc.cat>; the 4 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;
likewise C<package> depends on C<subdepot> and C<depot> (but C<subdepot>
can be the empty name chain).

=back

=head2 Procedures For Defining In-Depot Namespaces

These 4 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 4 procedures.

=over

=item C<procedure sys.std.Core.Cat.create_subdepot update {} read {
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.

=item C<procedure sys.std.Core.Cat.drop_subdepot update {} read {
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.

=item C<procedure sys.std.Core.Cat.create_package update {} read {
name(Name), comment(Comment)?, package(Package)? }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.packages>.  It will create a new
package, 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 an Oracle CREATE PACKAGE statement.

=item C<procedure sys.std.Core.Cat.drop_package update {} read { name(Name)
}>

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

=back

=head2 Procedures For Defining Depot Routines and Data Types

These 8 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 4 procedures.

=over

=item C<procedure
sys.std.Core.Cat.create_depot_(function|updater|procedure) update {} read {
name(Name), comment(Comment)?, head(Cat.(Func|Upd|Proc)Head),
body(Cat.(Func|Upd|Proc)Body) }>

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.

=item C<procedure sys.std.Core.Cat.drop_depot_(function|updater|procedure)
update {} read { 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.

=item C<procedure sys.std.Core.Cat.create_depot_type update {} read {
name(Name), comment(Comment)?, type(Type) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot.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.

=item C<procedure sys.std.Core.Cat.drop_depot_type update {} read {
name(Name) }>

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

=back

=head2 Procedures For Defining Package Routines and Data Types

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

=over

=item C<procedure
sys.std.Core.Cat.create_package_(function|updater|procedure) update {} read
{ name(Name), comment(Comment)?, is_public(Bool)?,
head(Cat.(Func|Upd|Proc)Head), body(Cat.(Func|Upd|Proc)Body) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package
.(function|updater|procedure)s>.  It will create a new
function|updater|procedure, in the package having the name given by the
C<package> argument, in the depot mounted under the name given by the
C<depot> argument, whose name and other details match the other arguments.

=item C<procedure
sys.std.Core.Cat.drop_package_(function|updater|procedure) update {} read {
name(Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package
.(function|updater|procedure)s>.  It will drop an existing package
function|updater|procedure.

=item C<procedure sys.std.Core.Cat.create_package_type update {} read {
name(Name), comment(Comment)?, is_public(Bool)?, type(Type) }>

This procedure is an abstraction over inserting a tuple into the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package.types>.  It will create a
new type, in the package having the name given by the C<package> argument,
in the depot mounted under the name given by the C<depot> argument, whose
name and other details match the other arguments.

=item C<procedure sys.std.Core.Cat.drop_package_type update {} read {
name(Name) }>

This procedure is an abstraction over deleting a tuple from the catalog
relvar C<fed.cat.mounts{name=$depot}.depot
.packages{parent=$subdepot,name=$package}.package.types>.  It will drop an
existing package type.

=back

=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<perl@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, Darren Duncan.

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
