WHAT AM I --------- File README for DBIx::FileSystem DBIx::FileSystem - Manage database tables like a filesystem (C) 2003, 2007 by Alexander Haderer You may distribute under the terms of the GNU General Public License. DESCRIPTION: ------------ from the manpage: The module DBIx::FileSystem offers you a filesystem like view to database tables. To interact with the database tables, FileSystem implements a command line shell which offers not only a subset of well known shell commands to navigate, view and manipulate data in tables, but also gives the convenience of history, command line editing and tab completion. FileSystem sees the database as a filesystem: each table is a different directory with the tablename as the directory name and each row in a table is a file within that directory. DBIx::FileSystem also contains a class to access the data in the Database. The function get_conf_by_var() respects the defaultfile function from the shell. The motivation for FileSystem was the need for a terminal based configuration interface to manipulate database entries which are used as configuration data for a server process. FileSystem is neither complete nor a replacement for dbish or other full-feature SQL shells or editors. Think of FileSystem as a replacement for a Web/CGI based graphical user interface for manipulating database contents. EXAMPLE: -------- The file pawactl implements a sample shell using DBIx::FileSystem. It implements the configure shell of a virtual package warehouse. Sample session: ----------> pawactl sample session start ---------> pawactl (/source): ls (dest) acity factory2 lcity (source) bcity generic (warehouse) factory1 kcity pawactl (/source): cat bcity # # Settings for SourceName 'bcity' (defaults: 'generic') # # - this is a comment, comments always start in the first column. # - all lines begin in the first column or are blank lines # - a unset variable will write NULL into the database column # - unset variables use the default values # # # SourceID # Internal source idenficator (4 characters) # # default: ---- # SourceID = CIB ... more file contents ... pawactl (/source): sum bcity SourceID = CIB Distance = 2434 Destination = moon pawactl (/source): vgrep destina acity: Destination = mars bcity: Destination = moon factory1: Destination = moon factory2: Destination = venus fromfar: Destination = mars generic: Destination = *unset* kcity: Destination = moon pawactl (/source): cd dest pawactl (/dest): ls (dest) (warehouse) moon venus (source) mars neptun pawactl (/dest): rm venus rm: cannot remove: file 'venus' referenced by: source/factory2 warehouse/sx0001 pawactl (/dest): vi venus ... vi session ... ... save & quit ... ERROR: line 23: invalid value: valid range: (1..100) Do you want to edit again ('n' will abort) [y/n] ? n pawactl (/dest): <---------- pawactl sample session end <--------- REQUIREMENTS: ------------- - build, test and install Perl 5 (at least 5.003) - build, test and install the DBI module (at least 1.00) - build, test and install Gnu::ReadLine (recommended) - to use datatypes 'cidr' and 'inet': a PostgreSql database - a database server running - a perl DBD module installed to connect to the database server PLATFORMS: ---------- This release of DBIx::FileSystem has been developed using FreeBSD. INSTALLATION: ------------- 1. perl Makefile.PL 2. make 3. make test 4. make install ( 1. to 3. as normal user, not as root ! ) TESTING: -------- - the shell: t/00_shell.t: The test currently is only a dummy because I don't know how to test an interactive shell across many different platforms and terminals. Workaround: Do a test of all required modules. Run the sample pawactl. - access class: t/02_access_data.t This test requires a running database server containing the sample database coming with the sample program pawactl. To prepare the tests for the access class do: 1. create the database on the server using SQL or commandline: CREATEDB warehouse 2. modify example 'pawactl' to connect to this database. Edit the lines where these variables are set: $DBCONN $DBUSER $DBPWD 3. run example 'perl -Iblib/lib examples/pawactl recreatedb' to install the sample data in db 4. modify the test t/02_access_data.t to connect to the sample database. Edit the lines where the following variables are set, so that they have the same values as in pawactl: $DBCONN $DBUSER $DBPWD 5. do not change the sample database by playing around with pawactl! 6. now you can test: either: 'make test' or manually: 'perl -Iblib/lib t/02_access_data.t' USING EXAMPLES: --------------- To play around with the example warehouse you need a sample database: 1. create the database on the server using SQL or commandline: createdb warehouse 2. modify example 'pawactl' to connect to this database. Edit the lines where these variables are set: $DBCONN $DBUSER $DBPWD 3. run example 'perl -Iblib/lib examples/pawactl recreatedb' to install the sample data in db 4. play around with the example shell: 'perl -Iblib/lib examples/pawactl' NOTE: take a look at the comments in pawactl 5. play around with the access sample: 'perl -Iblib/lib examples/access' CHANGES: -------- 1.00 24 Mar 2003 initial version 1.01 8 Apr 2003 - rmcheck option added - volok option added - vi now can create new files (usefull with 'NOT NULL' constraint) 1.02 7 May 2003 - added (dummy) t/dummy.t testing - internal release 1.03 8 May 2003 - rename: t/dummy.t to t/use.t 1.04 16 June 2003 - cp: missing filenamecheck for new file added - vdirs: desc now may be multiline by adding '\n' to the text 1.05 10 July 2003 - the valok custom check functions now get a second parameter holding a hash ref of all variables read in from the to-be-edited-file, key is the columnname (cols) - pawactl modify to show an example how to use the above hashref 1.06 14 July 2003 - comcol in %vdirs hash introduced: define a column that will hold comments for a file - introduced new commands 'll' and 'ld' - check length of fnamcol column againtst $LS_COL_WIDTH - added possibility to add custom commands - rmcheck and volok callbacks: added param dbh 1.07 21 july 2003 - added missing t/use.t to MANIFEST 1.08 11 aug 2003 - more %vdirs checking at startup - vi/cat now use 'desc' instead of 'var' when column is fnamcol 1.09 03 feb 2004 - delcp option: when saving a file this var will also checked against duplicate entries in other files in this dir (unique test) - delcp now is called 'uniq', print out warning msg when delcp used - added 'vgrep' command 1.10 skipped 1.1 skipped 1.2 10 jun 2007 - extended int datatype to behave like a collection of configurable flags (bits) if option 'flags' is set - added new types 'cidr' and 'inet' (will work with PostgreSql only) - added flags example to pawactl - added cidr example to pawactl - minor bug fixes in application and docs 1.3 11 jul 2007 - bugfix: display of defaultvalues from defaultfile wrong (cat/vi) - pawactl: setup some more usefull sample values 1.4 11 nov 2007 - extended int datatype to behave like a enum integer type if option 'enums' is set - added enums example to pawactl 1.5 4 dec 2007 - added access class for database values, the access function respects the defaultfile function 1.6 12 dec 2007 - fixed locale dependency in test 01_access_isanumber.t 1.7 13 dec 2007 - using multiple 'use constant' instead of single one to be compatible with older perls - added missing requirement "Test::Simple" to Makefile.PL COPYRIGHT: ---------- You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. HOW TO GET THE LATEST VERSION: ------------------------------ Look at CPAN. IF YOU HAVE PROBLEMS: --------------------- Please send comments and bug-reports to CVS INFO: -------- Last Update: $Author: marvin $ Update Date: $Date: 2007/12/13 15:06:47 $ Source File: $Source: /home/cvsroot/tools/FileSystem/README,v $ CVS/RCS Revision: $Revision: 1.19 $ Status: $State: Exp $ --------------------------------------------------------------------------- Alexander Haderer afrika@cpan.org ---------------------------------------------------------------------------