Base Table
==========
A base table implementation using Scheme association lists is
available as the value of the identifier `alist-table' after doing:
`(require 'alist-table)'
Association list base tables are suitable for small databases and
support all Scheme types when temporary and readable/writeable Scheme
types when saved. I hope support for other base table implementations
will be added in the future.
This rest of this section documents the interface for a base table
implementation from which the Note:Relational Database package
constructs a Relational system. It will be of interest primarily to
those wishing to port or write new base-table implementations.
All of these functions are accessed through a single procedure by
calling that procedure with the symbol name of the operation. A
procedure will be returned if that operation is supported and `#f'
otherwise. For example:
(require 'alist-table)
(define open-base (alist-table 'make-base))
make-base => *a procedure*
(define foo (alist-table 'foo))
foo => #f
- Function: make-base filename key-dimension column-types
Returns a new, open, low-level database (collection of tables)
associated with FILENAME. This returned database has an empty
table associated with CATALOG-ID. The positive integer
KEY-DIMENSION is the number of keys composed to make a PRIMARY-KEY
for the catalog table. The list of symbols COLUMN-TYPES describes
the types of each column for that table. If the database cannot
be created as specified, `#f' is returned.
Calling the `close-base' method on this database and possibly other
operations will cause FILENAME to be written to. If FILENAME is
`#f' a temporary, non-disk based database will be created if such
can be supported by the base table implelentation.
- Function: open-base filename mutable
Returns an open low-level database associated with FILENAME. If
MUTABLE? is `#t', this database will have methods capable of
effecting change to the database. If MUTABLE? is `#f', only
methods for inquiring the database will be available. If the
database cannot be opened as specified `#f' is returned.
Calling the `close-base' (and possibly other) method on a MUTABLE?
database will cause FILENAME to be written to.
- Function: write-base lldb filename
Causes the low-level database LLDB to be written to FILENAME. If
the write is successful, also causes LLDB to henceforth be
associated with FILENAME. Calling the `close-database' (and
possibly other) method on LLDB may cause FILENAME to be written
to. If FILENAME is `#f' this database will be changed to a
temporary, non-disk based database if such can be supported by the
underlying base table implelentation. If the operations completed
successfully, `#t' is returned. Otherwise, `#f' is returned.
- Function: sync-base lldb
Causes the file associated with the low-level database LLDB to be
updated to reflect its current state. If the associated filename
is `#f', no action is taken and `#f' is returned. If this
operation completes successfully, `#t' is returned. Otherwise,
`#f' is returned.
- Function: close-base lldb
Causes the low-level database LLDB to be written to its associated
file (if any). If the write is successful, subsequent operations
to LLDB will signal an error. If the operations complete
successfully, `#t' is returned. Otherwise, `#f' is returned.
- Function: make-table lldb key-dimension column-types
Returns the BASE-ID for a new base table, otherwise returns `#f'.
The base table can then be opened using `(open-table LLDB
BASE-ID)'. The positive integer KEY-DIMENSION is the number of
keys composed to make a PRIMARY-KEY for this table. The list of
symbols COLUMN-TYPES describes the types of each column.
- Constant: catalog-id
A constant BASE-ID suitable for passing as a parameter to
`open-table'. CATALOG-ID will be used as the base table for the
system catalog.
- Function: open-table lldb base-id key-dimension column-types
Returns a HANDLE for an existing base table in the low-level
database LLDB if that table exists and can be opened in the mode
indicated by MUTABLE?, otherwise returns `#f'.
As with `make-table', the positive integer KEY-DIMENSION is the
number of keys composed to make a PRIMARY-KEY for this table. The
list of symbols COLUMN-TYPES describes the types of each column.
- Function: kill-table lldb base-id key-dimension column-types
Returns `#t' if the base table associated with BASE-ID was removed
from the low level database LLDB, and `#f' otherwise.
- Function: make-keyifier-1 type
Returns a procedure which accepts a single argument which must be
of type TYPE. This returned procedure returns an object suitable
for being a KEY argument in the functions whose descriptions
follow.
Any 2 arguments of the supported type passed to the returned
function which are not `equal?' must result in returned values
which are not `equal?'.
- Function: make-list-keyifier key-dimension types
The list of symbols TYPES must have at least KEY-DIMENSION
elements. Returns a procedure which accepts a list of length
KEY-DIMENSION and whose types must corresopond to the types named
by TYPES. This returned procedure combines the elements of its
list argument into an object suitable for being a KEY argument in
the functions whose descriptions follow.
Any 2 lists of supported types (which must at least include
symbols and non-negative integers) passed to the returned function
which are not `equal?' must result in returned values which are not
`equal?'.
- Function: make-key-extractor key-dimension types column-number
Returns a procedure which accepts objects produced by application
of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This
procedure returns a KEY which is `equal?' to the COLUMN-NUMBERth
element of the list which was passed to create COMBINED-KEY. The
list TYPES must have at least KEY-DIMENSION elements.
- Function: make-key->list key-dimension types
Returns a procedure which accepts objects produced by application
of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This
procedure returns a list of KEYs which are elementwise `equal?' to
the list which was passed to create COMBINED-KEY.
In the following functions, the KEY argument can always be assumed to
be the value returned by a call to a _keyify_ routine.
In contrast, a MATCH-KEYS argument is a list of length equal to the
number of primary keys. The MATCH-KEYS restrict the actions of the
table command to those records whose primary keys all satisfy the
corresponding element of the MATCH-KEYS list. The elements and their
actions are:
`#f'
The false value matches any key in the corresponding position.
an object of type procedure
This procedure must take a single argument, the key in the
corresponding position. Any key for which the procedure
returns a non-false value is a match; Any key for which the
procedure returns a `#f' is not.
other values
Any other value matches only those keys `equal?' to it.
The KEY-DIMENSION and COLUMN-TYPES arguments are needed to decode the
combined-keys for matching with MATCH-KEYS.
- Function: for-each-key handle procedure key-dimension column-types
match-keys
Calls PROCEDURE once with each KEY in the table opened in HANDLE
which satisfy MATCH-KEYS in an unspecified order. An unspecified
value is returned.
- Function: map-key handle procedure key-dimension column-types
match-keys
Returns a list of the values returned by calling PROCEDURE once
with each KEY in the table opened in HANDLE which satisfy
MATCH-KEYS in an unspecified order.
- Function: ordered-for-each-key handle procedure key-dimension
column-types match-keys
Calls PROCEDURE once with each KEY in the table opened in HANDLE
which satisfy MATCH-KEYS in the natural order for the types of the
primary key fields of that table. An unspecified value is
returned.
- Function: delete* handle key-dimension column-types match-keys
Removes all rows which satisfy MATCH-KEYS from the table opened in
HANDLE. An unspecified value is returned.
- Function: present? handle key
Returns a non-`#f' value if there is a row associated with KEY in
the table opened in HANDLE and `#f' otherwise.
- Function: delete handle key
Removes the row associated with KEY from the table opened in
HANDLE. An unspecified value is returned.
- Function: make-getter key-dimension types
Returns a procedure which takes arguments HANDLE and KEY. This
procedure returns a list of the non-primary values of the relation
(in the base table opened in HANDLE) whose primary key is KEY if
it exists, and `#f' otherwise.
- Function: make-putter key-dimension types
Returns a procedure which takes arguments HANDLE and KEY and
VALUE-LIST. This procedure associates the primary key KEY with
the values in VALUE-LIST (in the base table opened in HANDLE) and
returns an unspecified value.
- Function: supported-type? symbol
Returns `#t' if SYMBOL names a type allowed as a column value by
the implementation, and `#f' otherwise. At a minimum, an
implementation must support the types `integer', `symbol',
`string', `boolean', and `base-id'.
- Function: supported-key-type? symbol
Returns `#t' if SYMBOL names a type allowed as a key value by the
implementation, and `#f' otherwise. At a minimum, an
implementation must support the types `integer', and `symbol'.
`integer'
Scheme exact integer.
`symbol'
Scheme symbol.
`boolean'
`#t' or `#f'.
`base-id'
Objects suitable for passing as the BASE-ID parameter to
`open-table'. The value of CATALOG-ID must be an acceptable
`base-id'.