MetaKit for TCL

[www.equi4.com]

MetaKit for TCL
version 0.2

This is a preview release of the Tcl interface to a flexible and efficient C++ storage library. The main reason for making this code available at this stage is to offer proof of concept, and to sollicit feedback at an early stage to arrive at a "natural" interface for use in Tcl.

About MetaKit

Stores highly structured binary data, can easily scale to millions of entries
Data files are very compact, their structure can be changed instantly
Fail-safe storage, commit/rollback, on-demand loading, can be streamed
Portable, both the code (Unix, Windows, Mac, VMS) and the data files

Some more facts about this library: MetaKit has been field-tested in many thousands of copies, the Win32 DLL is under 100 Kb, ports are freely available (source license is required for royalty-free commercial use), this product is actively supported and extended.

About this Tcl extension

The extension is packaged as a single DLL, and uses the "mk::" namespace
The Tcl interface is still young, ugly things like memory leaks can happen
There is not yet an interface to use derived views, joins, selections, etc
Streaming is to and from file only, there is not yet a channel interface

Visit the MetaKit homepage at [http://www.equi4.com/metakit/] for the latest news.
Send problem reports and suggestions to jcw@equi4.com, this is a supported product.

-- Jean-Claude Wippler

Download MetaKit-0.2-WinTcl.zip for Windows 95/NT, requires Tcl 8.0


TERMINOLOGY

    MetaKit uses the following model: a file contains a number of
    views (tables).  Each view hold zero or more rows (records),
    all consisting of a number of common properties (attributes).
    Views may be nested, by defining subview properties in rows.
    
    A cursor is a lightweight iterator for a view or subview.
    To refer to a specific subview you must specify its path.
    Datafiles are accessed via a tag, as specified when opened.


VIEW STRUCTURES

    View structures are described using a list of property names,
    a ":X" suffix must be used to specify non-string datatypes:

        name        string, using only as many characters as needed
        name:I      integer, automatically adjusts to use 1..32-bit
        name:F      single precision floating point
        name:D      double precision floating point
        name:B      binary data (like string, may include 0-bytes)
        name:M      memo data (binary, better for large entries)

    Subview properties are specified as a list with a sublist:

        {subview {prop ...}}

    The datatype must be specified whenever the property is used.
    This is an artefact of the current setup, to be changed later.


SYNTAX

    path ::= tag.view[!row.view]*
                    a path describes a specific (sub-) view
    cursor ::= tag[.view!row]+
                    a cursor refers to a row in a view

    Note: cursors may be used anywhere where paths are expected.


LINKED TO TCL 8.0 DLL'S FOR USE ON WIN 95/NT

    package require mk
                    see the "demo.tcl" script for a few examples


DATAFILE SETUP - RETURNS TAG

    mk::file open tag filename ?-readonly? ?-nocommit?
                    nocommit prevents automatic commit on close
    mk::file close tag
                    close datafile
    mk::file commit tag
                    commit now
    mk::file rollback tag
                    rollback now


RESTRUCTURING, REMOVING VIEWS - RETURNS PATH

    mk::view layout tag.view {structure}
                    defines or restructures view as needed
    mk::view delete tag.view
                    removes entire view (permanent once committed)


GET/SET THE SIZE OF A VIEW

    mk::view size path
                    returns size
    mk::view size path size
                    resizes view, returns path


INSERTING, REMOVING, REPLACING ROWS - RETURNS CURSOR
    
    mk::row ?create? ?prop value ?...??
                    returns cursor to a fresh temporary row
    mk::row append path ?prop value ?...??
                    add a new row, optionally setting values
    mk::row insert cursor cursor2 ?count?
                    insert row at cursor2 before cursor
    mk::row delete cursor ?count?
                    delete row(s) at cursor
    mk::row replace cursor cursor2
                    copy row at cursor2 over row at cursor
    mk::row replace cursor
                    clear contents at cursor


CURSOR POSITIONING - RETURNS CURSOR

    mk::cursor ?create? cursorName path ?index?
                    set up a cursor for a view, default index is 0
    mk::cursor position cursorName 0
                    reposition cursor to first row
    mk::cursor position cursorName end
                    reposition cursor to last row
    mk::cursor position cursorName index
                    reposition cursor to specified row
    mk::cursor position cursorName
                    returns current cursor position
    mk::cursor incr cursorName ?step?
                    advance the cursor by given step, or by 1


CURSOR ITERATION

    mk::loop cursorName {cmds...}
                    perform cmds for each row (cursor must exist)
    mk::loop cursorName path {cmds...}
                    perform cmds for each row in specified path
    mk::loop cursorName path first ?limit ?step?? {cmds...}
                    default limit is past end, default step is 1


GET/SET PROPERTY VALUES

    mk::get cursor
                    gets all property value(s) as keyed list
    mk::get cursor prop ?...?
                    gets specified property value(s)
    mk::set cursor prop value ?prop value ?...??
                    sets property value(s), returns cursor


LOADING/SAVING AS STREAMING BINARY DATA - RETURNS TAG
    
    mk::file load tag filename
                    ### only from file right now
    mk::file save tag filename
                    save all data in "serialized" format