WHAT AM I
---------
File README for DBIx::FileSystem
DBIx::FileSystem - Manage database tables like a filesystem
(C) 2003, 2018 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
1.8 21 jan 2008
- bugfix: 'use of uninitialized value' when saving a file where a
var is NULL/undef and defined with option 'uniq'
1.9 28 mar 2008
- bugfix: user supplied valok-check got string 'NULL' instead of
undef when an enum has nothing selected
- bugfix: enum descriptions in vi/cat now sorted numerically by
enum value instead of lexically by enum value
2.0 08 jul 2008
- added new alternate parameter rdbh for constructor of access class
- added test for above parameter
2.1 missing
2.2 08 sep 2011
- modified handling of 'ref' type: Now similar like enum/flags
- new column property 'cpdelete': delete value on copy 'cp'
2.3 18 oct 2011
- bugfix: can now save a flags field with undefined value as given
when editing a file with vi
2.4 04 jan 2012
- bugfix: #466 fisctl shell -- use of uninitialized value bei cat/vi
2.5 22 feb 2018
- bugfix: #2962 DBIx::FileSystem: Bugfix POSIX::tmpnam --> File::Temp
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>
---------------------------------------------------------------------------
Alexander Haderer afrika@cpan.org
---------------------------------------------------------------------------