dbtcl - Handle a hierarchical structured database objects

Note :    Version alpha 0.1

Download

Get last package : http://sourceforge.net/projects/dbtcl/

REQUIREMENTS

This package require :

SYNOPSIS

dbase object tag
object method ?args?

STANDARD OPTIONS

See itcl document

DESCRIPTION

The db package provide a class named dbase. The dbase handle a metakit database with the structure :

View :
            db.data

db.data properties :
id Store objects names. 
The name needs be structured in the format :
name.name.name...name
Rules :
- Id is unique.
- name is alpha-numeric ( no spaces ).
title Store a short title.
details Store details about the id.
validate Store a procedure that will validate data linked to id.
Use this to validate the values that will be stored in the value property. 
default Store a script ( procedure ) to eval a default value
Default values are applied in children paths.
format Store a variable that represents the value format.
The db uses a Built-in namespace called dbVars to store variables. If variables don't exists, then a error is generate. Before the value is stored, the system evaluate and format it.
value Store the object's value.

db.data sub-views :
            flag     - Store flags that will be evaluate when objects are created, accessed, etc.

Flag properties :
attrib Store attrib's description.
The built-in attribes : Read, Scan, Delete, Rename, Move Usable, Lock and Folder.
flag Store flag for handle object's access.
The built-in flags :
Read   -> Ro ( read only )       / Rw ( read write )
Scan   -> Si ( scan inhibit )        / Sc ( scan )
Delete -> Di ( Delete Inhibit )    / De ( delete )
Rename -> Ri ( rename inhibit ) / Re ( rename )
Move   -> Mi ( move inhibit )    / Mv ( move )
Usable -> Ui ( use inhibit )         / Us ( usable )
Lock   -> Lk ( lock )               / Uk ( unlock )
Folder -> Fo ( is Folder )        / Le ( is Leaf )
value Store a optional value for evaluate thinks about the flag.

        events    -     Store events that will be evaluate when objects are created, accessed, etc.
Events  properties :
 
event Store the event name
The Built-in events :
OnCreate
OnSelect 
OnMove
OnCopy
OnScan
OnRead
OnWrite
OnLeave
OnWrite
Each event is bind to the procedure dbControl::MainReturn. The default return is 1 ( true ).
value Store the procedure that will be evaluate
The default procedure is dbControl::MainReturn.

          First, you need create the database using the procedure dbControl::Create base and then open it  with the command mk::file open tag database. Then you create a new object bind it to a tag's database : dbase object tag. The object is used to handle the database. You may create any number of objects. The syntax is : object Method ?args?.

METHODS

          There are a pointer variable that point to a registry  for each object created by the class dbase. The atualpath variable is actualized each time that the pointer changes. The path is the id in the database. Pointer have 0 ( zero ) when the object is created. The first id of the database ( root ) is ".".

          Md path ?args?

Create a new object with name path and flag Fo ( is Folder ). The path is unique ( no duplicate ) and the father needs exists. The scan, delete, folder and lock flags for the father affect the method. If scan = Si or delete = Di or folder = Le or lock = Lk for the father the Md fail and return null. Else, Md returns path.
See Set method to know about args.

Cd ?path?

Go to a id. If no path is passed, the method returns the actual path stored in the atualpath variable. Else, the pointer is positioned in the new path and the path is returned. If path doesn't exist, the value null is returned. The scan flag affect the method. If scan have Si for the path, the value null is returned.

Ls ?path?

Lists all the ids ( the children ) under the path . If no path is passed, Ls lists the atualpath. If the path doesn't exist, the value null is returned. The scan flag affect the method. If scan have Si for the id or child id, then the id isn't listed.

Tree ?path?

Lists all the ids under the path and under the children and so on. If no path is passed, tree lists the atualpath. If the path doesn't exist, the value null is returned. The scan flag affect the method. If scan have Si for the id or child id, then the id isn't listed.

Rd ?path?

Remove the path from the database and all links references. The scan, delete and lock flags affect the method. If scan = Si or delete = Di or lock = Lk, the Rd don't remove the path. The child's flags don't affect the method.

Set path ?args?

Set values to the path's properties.
path       The id that will be set.
Set the basic information for id. Args in pairs, where :
        -title         Set the id's title.
        -detail      Set the id's details
        -validate  Set the id's validate
        -default    Set the id's default value
        -format    Set the id's format value
        -value      Set the id's value
If path isn't passed, then Set uses the atualpath. Set return a list with the path and the information about the id.

Get path prop

Get the property prop stored to the path. The properties are -title, -detail, -validate, -default, -format and -value. The Scan flag affects the method. If Scan = Si the method fail and return null. Get return the value stored in property.

Mv source target

Move id and your children from a source id to a target id. Source and target needs be different. The source can't exists in the target. The read, folder and lock flags affect the method. If read = Ro or Folder = Le or Lock = Lk the method fail and return null. Mv return a list with the new folder locations.

Cp source target

Copy id and your children from a source id to a target id. Source and target needs be different. The source can't exists in the target. The read, folder and lock affect the method. If read = Ro or Folder = Le or Lock = Lk the method fail and return null.  Cp return a list with the new folder locations.

Flag path attrib value

Set the flag to the path. The attrib is the flag name ( ex.: Scan ) and value is the flag ( ex.: Si ).

BUILT-IN VARIABLES

         The system create a namespace called dbVars. DbVars store variables that are used in the format property of the object and control thinks about the system like commit the databases opened in the interp after x milli-seconds.

BUILT-IN PROCEDURES

The system create a namespace called dbControl. DbControl have the procedures :
 
Create Create a new metakit database with the structure required for the system.
Syntax : dbControl::Create database
Refresh Because the metakit database not delete the records into the database when required, we need refresh the database to remove them. Refresh make a new copy of the database without the deleted records. The database needs closed.
syntax : dbControl::Refresh database
Commit Commit the data into the database after x milli-seconds. X is controlled by the variable dbVars::saveEach. The default value is 300000.
MainReturn It is the default procedure bind to the system events. Return 1 as the default. The dbase class have a method called EventExec that call the event procedure. The system call the procedure using the syntax :
dbControl::MainReturn path event database-tag
Format Format evaluate the property value of the object and returns the value formatted. After the property value is set, the system looks the property format. The arg format is a variable containing the format string.
Syntax : dbControl::Format format value
Default Default evaluate the procedure stored into the property defaultand returns the value . The system uses this procedure to set the property value for the children's path.
Syntax : dbControl::Default procedure
CheckValue It is used to validate the property value of the path. CheckValue evaluate the procedure stored into the property validate using value and return 0 ( false ) or 1 ( true ).
Syntax : dbControl::CheckValue validate value

OTHERS METHODS

 
SetAtualPath Set the variable atualpath.
GetResolvedPath Resolve the name's path.
Checkpath Verify if the path name is correct.
Findpath Find the path for 4 ways.
GetNodefather Get the node father for the path.
GetLastname Get the last name for the path.
InsertFlags Set the initial flag for the path.
GetFlags Return a list with the flags of the path.
InsertEvents Set the initial events for the path.
Event Set a event to the path.
GetEvents Return a list with the events of the path.
EventExec Executes a procedure of a event of the path.

EXAMPLE

        This is a simple example that demonstrate how to use the package. The database system.db alread exists.

% package require db
0.1
(tests) 2 % mk::file open db system.db
db
(tests) 3 % dbase sys db
sys
(tests) 4 % sys Ls
.users
(tests) 5 % sys Ls users
.users.access .users.mauro
(tests) 6 % sys Ls users.mauro
.users.mauro.identification .users.mauro.login .users.mauro.allowAccess
(tests) 7 % sys Cd users.mauro.login
.users.mauro.login
(tests) 8 % sys Ls
.users.mauro.login.alias sers.mauro.login.pwdLength
.users.mauro.login.pwdChangeAfterLogin .users.mauro.login.pwdChangeEachDays
.users.mauro.login.pwdDayToChange .users.mauro.login.pwdNeverExpire .users.mauro.login.pwd
(tests) 9 % sys Set pwd -value password
.users.mauro.login.pwd {title {User's password} detail {} validate {} default {} format {} value password}
(tests) 10 % sys Md .test
.test
(tests) 11 % sys Ls .
.users .test
(tests) 12 % sys Rd .test
.test
(tests) 13 % sys Ls .
.users

AUTHOR

Mauro Serão Filho    mserao@users.sourceforge.net
Copyright (C) 2001