From: Dobrica Pavlinusic <dpavlin@rot13.org>
Date: Fri, 8 Oct 2004 23:43:06 +0000 (+0000)
Subject: documentation improvements, API 0.04
X-Git-Url: http://git.rot13.org/?p=Fuse-DBI;a=commitdiff_plain;h=17f71d3ea4691a9575688d5943c780e7361f550f

documentation improvements, API 0.04


git-svn-id: svn://svn.rot13.org/fuse_dbi/trunk@28 17f4e80c-d0e0-0310-8903-bfc3ae804c12
---

diff --git a/DBI.pm b/DBI.pm
index 741117e..406db38 100755
--- a/DBI.pm
+++ b/DBI.pm
@@ -13,7 +13,7 @@ use Carp;
 use Data::Dumper;
 
 
-our $VERSION = '0.03';
+our $VERSION = '0.04';
 
 =head1 NAME
 
@@ -24,7 +24,7 @@ Fuse::DBI - mount your database as filesystem and use it
   use Fuse::DBI;
   Fuse::DBI->mount( ... );
 
-See C<run> below for examples how to set parametars.
+See C<run> below for examples how to set parameters.
 
 =head1 DESCRIPTION
 
@@ -32,7 +32,7 @@ This module will use C<Fuse> module, part of C<FUSE (Filesystem in USErspace)>
 available at L<http://sourceforge.net/projects/avf> to mount
 your database as file system.
 
-That will give you posibility to use normal file-system tools (cat, grep, vi)
+That will give you possibility to use normal file-system tools (cat, grep, vi)
 to manipulate data in database.
 
 It's actually opposite of Oracle's intention to put everything into database.
@@ -46,15 +46,69 @@ It's actually opposite of Oracle's intention to put everything into database.
 
 Mount your database as filesystem.
 
+Let's suppose that your database have table C<files> with following structure:
+
+ id:		int
+ filename:	text
+ size:		int
+ content:	text
+ writable:	boolean
+
+Following is example how to mount table like that to C</mnt>:
+
   my $mnt = Fuse::DBI->mount({
-	filenames => 'select name from files_table as filenames',
-	read => 'sql read',
-	update => 'sql update',
-	dsn => 'DBI:Pg:dbname=webgui',
-	user => 'database_user',
-	password => 'database_password'
+	'filenames' => 'select id,filename,size,writable from files',
+	'read' => 'select content from files where id = ?',
+	'update' => 'update files set content = ? where id = ?',
+	'dsn' => 'DBI:Pg:dbname=test_db',
+	'user' => 'database_user',
+	'password' => 'database_password',
+	'invalidate' => sub { ... },
   });
 
+Options:
+
+=over 5
+
+=item filenames
+
+SQL query which returns C<id> (unique id for that row), C<filename>,
+C<size> and C<writable> boolean flag.
+
+=item read
+
+SQL query which returns only one column with content of file and has
+placeholder C<?> for C<id>.
+
+=item update
+
+SQL query with two pace-holders, one for new content and one for C<id>.
+
+=item dsn
+
+C<DBI> dsn to connect to (contains database driver and name of database).
+
+=item user
+
+User with which to connect to database
+
+=item password
+
+Password for connecting to database
+
+=item invalidate
+
+Optional anonymous code reference which will be executed when data is updated in
+database. It can be used as hook to delete cache (for example on-disk-cache)
+which is created from data edited through C<Fuse::DBI>.
+
+=item fork
+
+Optional flag which forks after mount so that executing script will continue
+running. Implementation is experimental.
+
+=back
+
 =cut
 
 my $dbh;
@@ -182,7 +236,7 @@ Checks if C<fuse> module is loaded in kernel.
   die "no fuse module loaded in kernel"
   	unless (Fuse::DBI::fuse_module_loaded);
 
-This function in called by L<mount>, but might be useful alone also.
+This function in called by C<mount>, but might be useful alone also.
 
 =cut
 
@@ -469,6 +523,10 @@ Nothing.
 C<FUSE (Filesystem in USErspace)> website
 L<http://sourceforge.net/projects/avf>
 
+Example for WebGUI which comes with this distribution in
+directory L<examples/webgui.pl>. It also contains a lot of documentation
+about design of this module, usage and limitations.
+
 =head1 AUTHOR
 
 Dobrica Pavlinusic, E<lt>dpavlin@rot13.orgE<gt>