WHAT AM I

File README for DBIx::FileSystem

DBIx::FileSystem - Manage database tables like a filesystem

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

perl Makefile.PL
make
make test
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:

create the database on the server using SQL or commandline:
createdb warehouse
modify example 'pawactl' to connect to this database. Edit the lines where these variables are set:
$DBCONN $DBUSER $DBPWD
run example 'perl -Iblib/lib examples/pawactl recreatedb' to install the sample data in db
play around with the example shell: 'perl -Iblib/lib examples/pawactl' NOTE: take a look at the comments in pawactl
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 <afrika@cpan.org>

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