
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. 

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 shows the usage of 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 <---------

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

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>


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


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 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 program pawactl.


CVS INFO:
--------
Last Update:		$Author: marvin $
Update Date:		$Date: 2007/06/15 13:58:56 $
Source File:		$Source: /home/cvsroot/tools/FileSystem/README,v $
CVS/RCS Revision:	$Revision: 1.13 $
Status:			$State: Exp $


---------------------------------------------------------------------------
   Alexander Haderer   					afrika@cpan.org
---------------------------------------------------------------------------

