Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

MLDBM::TinyDB
create and mainpulate structured MLDBM tied hash references

MLDBM::TinyDB - create and mainpulate structured MLDBM tied hash references


SYNOPSIS


        use MLDBM::TinyDB;

        ## or

        use MLDBM::TinyDB qw/db add_common/;

        @common = qw/created updated/; ## optional

        $tree = [TABLE, FIELDS_LIST,

                        [TABLE1, FIELDS_LIST1,

                                [TABLE2, FIELDS_LIST2],

                                ...

                        ],

                        ...

                ];

        MLDBM::TinyDB::add_common($tree,\@common); ## optional

        ## or

        add_common($tree,\@common);

        %obj = ();

        $obj{TABLE} = MLDBM::TinyDB->init(TABLE, $tree);

        ## or

        $obj{TABLE} = 

                MLDBM::TinyDB->init(TABLE, $tree, undef, $mode, $perms);

        ## or 

        $obj{TABLE} = MLDBM::TinyDB->init(TABLE); ## NEVER FIRST TIME

        @down = $obj{TABLE}->down; ## TABLE1

        $obj{TABLE1} = MLDBM::TinyDB::db(TABLE1);

        ## or

        $obj{TABLE1} = db(TABLE1);

        $table = $obj{TABLE}->table; ## TABLE

        @down = $obj{TABLE1}->down; ## TABLE2

        $obj{TABLE2} = MLDBM::TinyDB::db(TABLE2);

        ## or

        $obj{TABLE2} = db(TABLE2);

        @set_recs_indices = 

                $obj{TABLEn}->set_recs(ARRAYREF_TO_HASHREF,[LIST]);

        $up = $obj{TABLE2}->up; ## TABLE1

        

        $aref_of_href = $obj{TABLE}->get_ext_recs; 

        ## or

        ($aref_of_href, @get_recs_indices) = $obj{TABLE}->get_ext_recs;

        $aref_of_href1 = $obj{TABLE}->get_recs; ## NOT THE SAME AS ABOVE

        ## or

        ($aref_of_href1, @get_recs_indices1) =  $obj{TABLE}->get_recs;

        @indices_of_recs_found = $obj{TABLE}->search($criteria, [$limit]);

        @indices_of_recs_found = $obj{TABLE}->lsearch($criteria, [$limit]);

        

        @indices_and_sort_field_values = $obj{TABLE}->sort($sort_formula_string);

        @indices_and_sort_field_values = $obj{TABLE}->lsort($sort_formula_string);

        

        $obj{TABLEn}->delete([LIST]); 

        $obj{TABLEn}->last;



=head1 DESCRIPTION

MLDBM::TinyDB is MLDBM based module. It allows to create/manipulate data structure of related tables = more-then-flatfile-database. The main idea is to create array reference which will reflect database structure. The first scalar value in the array is table name, next ones are fields names - if the array contains array reference it denotes interior (related) table where first scalar value is that table name (in that case the record will contain the field of the same name as interior table) and the next ones are fields names and so on... If database structure isn't written on disk then that structure is fetched from the array reference and written to disk. Object is always built from disk structures. To define record you may use any field name except ``nodes'' which is restricted field name and shouldn't be specified explicitly. created and updated fields are handled internally - if they are specified then: 1)on append record operation time function value is set to created record field 2)on write to existing record operation time function value is set to updated record field. Data get from and set to records are in form of array reference to hash references where hash keys are fields names. The fields names that are interior tables names contain array references. That array store indices (similar to array indices) identifying particular records. Those fields MUST be set to proper values before write records set_recs operation.

UTILITY

MLDBM::TinyDB::add_common
add_common
Utility sub - allow to arbitrary fields names set (except nodes) i.e. created, updated, blahblah to be added just after first element (name of table) to all (sub-)arrays pointed by $tree data structure. It's not exported by deafult.




=head2 CONSTRUCTOR(S)
init
This method creates database structure according to passed array reference $tree (which defines hierarchical structure of related tables) if the structure doesn't exist on disk - in that case you may change default mode O_CREAT|O_RDWR or perms 0666 if you specify them. Afterwards init read these structures and builds object from them.

MLDBM::TinyDB::db
db
Returns object reference of interior TABLE. If underlying database structure doesn't exist on disk then it's created. Returns undef on failure. Must be invoked after init. It's not exported by default.

METHODS

The following methods may be applied to object references returned by both init and MLDBM::TinyDB::db CONSTRUCTORS

flds
Returns array of all fields names of record on which operate object.

last
Returns last record's index or -1 if there are no records.

down
Returns fields names that are also interior tables names or empty array otherwise.

up
Returns field name of superior table or undef otherwise.

set_recs
Takes as first argument array reference to hash references and writes it as data records according to indices list if supplied or at the end of table otherwise. Each array element represents record data. If LIST is supplied then method writes at most as much array elements as LIST counts. If LIST is NOT supplied then it writes all array elements. May cause autovivification effect - it will add records if there is a gap between last record's index (see:last) and supplied index of unexisted record. i.e. while last index (1) if supplied (3) then it will add (2, 3) records. Returns array of written records indices.

get_ext_recs
Gets record's data specified by indices list (or all records if list is not supplied) and returns array reference to hash references plus got records indices list. If record field name is the same as interior table name then corresponding hash value will contain array reference - first element of the array will be other array reference to hash refrences (if one of that hash keys contain name of interior table then that hash value will be appropriate array reference and so on) and the rest of elements will be list of corresponding external records indices.

get_recs
Gets data records specified by indices list or all records if list is not supplied and returns array reference to hash references plus got records indices list. If any record field name is the same as interior table then corresponding hash value will contain array reference - the array will contain external records indices.

search
lsearch
Searches records in table in order to find ones that match supplied criteria, returns array of indices of those records. The criteria is a string which may contain something like i.e. field_name > 1000 && (field_name1 =~ /PATTERN/ || field_name2 lt $string) or i.e. defined(field_name) meaning you can construct criteria string similar to perl expressions. IMPORTANT: The use of fields names that are interior tables names (SEE: down method) will take no effect. Second (optional) argument is $limit, which defines what number of record indices matching the criteria should be at most returned. lsearch differs from search method in one way - it uses locale pragma - it uses system locale settings in string comparison/matching operations.

sort
lsort
Sort the all records of table associated with object according to $sort_formula_string which must be specified. Returns array of array references, where each pointed array contains as first element index of record followed by sorted fields values in order they appear in $sort_formula_string. Sort formula string is similar to perl sort function BLOCK i.e. a(field_name) <=> b(field_name) - in this case field_name value will be second element of each pointed array a(field_name1) cmp b(field_name1)||length a(field_test2) <=> length b(field_test2) - in this case field_name1 and field_name2 value will be second and third element of each pointed array. If empty array is returned then something went wrong. lsort differs from sort method in one way - it uses locale pragma - it sorts lexically in system locale sorting order.

delete
Deletes records of specified indices or all records if no arguments. If for record to be deleted exists field nodes and it contains array of numeric values then those values are indices identifying particular external table records and data in these external records pointing to that deleting record will be deleted too.



=item table

Returns TABLE associated with object.

name
Sets/gets name of object.


EXAMPLE1


        ## DEFINE

        perl -e"use MLDBM::TinyDB;$tree=[qw/f a b/];$it=MLDBM::TinyDB->init(q/f/,$tree);"

        ## ADD

        perl -e"use MLDBM::TinyDB;$it=MLDBM::TinyDB->init(q/f/);$it->set_recs([{a=>11,b=>12},{a=>12,b=>13}]);"

        ## GET

        perl -e"use MLDBM::TinyDB;$it=MLDBM::TinyDB->init(q/f/);$g=$it->get_recs;for(@$g){print qq/@{[%$_]}\n/}"


EXAMPLE2


        use MLDBM::TinyDB qw/db add_common/;

        @common = qw/created updated/; ## option

        $tree = [qw/table1 field1/,

                        [qw/table2 field2/,[qw/table3 field31 field32/]]

                ];

        add_common($tree,\@common); ## option

        %obj = ();

        $obj{table1} = MLDBM::TinyDB->init("table1", $tree);

        $obj{table2} = db("table2");

        $obj{table3} = db("table3");

        @x = qw/green blue yellow black red/;

        @y = (1, undef, 3, 5, 2);

        for(my $i = 0; $i<@x; $i++) {

                my $href;

                $href->{field31} = $x[$i];

                $href->{field32} = $y[$i];

                push(@$aref, $href);

        }

        ## NOTE: order of follownig statements is crucial to set all information 

        ## needed about relations between these records

        @set = $obj{table3}->set_recs($aref); ## append three records 

        print "@set\n";

        @indices_and_sort_field_values = $obj{table3}->sort('a(field31) cmp b(field31)');

        foreach (@indices_and_sort_field_values) {

                print "@$_\n";

        }

        @found = $obj{table3}->search('length(field31)>4||!defined(field32)', 3);

        print "@found\n";# 0 1 2

        $href->{table3} = [@set]; ## store indices of those records

        $href->{field2} = "22222";

        @set = $obj{table2}->set_recs([$href]);

        $href->{table2} = [@set];

        $href->{field1} = "11111";

        $obj{table1}->set_recs([$href]);

        $aref1 = $obj{table1}->get_ext_recs; ## get everything 

        

        use Data::Dumper;

        print Dumper($aref1);

        

        $obj{table3}->delete(0, -1); ## first and last record

        $aref2 = $obj{table2}->get_ext_recs; ##

        print Dumper($aref2);

        @flds = $obj{table3}->flds;

        print "@flds\n";


CAVEATS

Slow, slow, slow.


AUTHOR

Darek Adamkiewicz <d.adamkiewicz@i7.com.pl>


COPYRIGHT

Copyright (c) Darek Adamkiewicz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Please feel free to e-mail me if it concerns this module.


VERSION

Version 0.20 27 NOV 2002


SEE ALSO

MLDBM, SDBM_File, Storable

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy