| Current File : //home/strato/chroot/opt/RZperl536/man/man3/Sprite.3 |
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sprite 3"
.TH Sprite 3 "1998-04-23" "perl v5.36.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sprite \- Module to manipulate text delimited databases using SQL.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Sprite;
\&
\& $rdb = new Sprite;
\&
\& $rdb\->set_delimiter (\-Read => \*(Aq::\*(Aq) ## OR: (\*(AqRead\*(Aq, \*(Aq::\*(Aq);
\& $rdb\->set_delimiter (\-Write => \*(Aq::\*(Aq) ## OR: (\*(AqWrite\*(Aq, \*(Aq::\*(Aq);
\&
\& $rdb\->set_os (\*(AqWin95\*(Aq);
\&
\& ## Valid arguments (case insensitive) include:
\& ##
\& ## Unix, Win95, Windows95, MSDOS, NT, WinNT, OS2, VMS,
\& ## MacOS or Macintosh. Default determined by $^O.
\&
\& $rdb\->set_lock_file (\*(Aqc:\ewin95\etmp\eSprite.lck\*(Aq, 10);
\&
\& $rdb\->set_db_dir (\*(AqMac OS:Perl 5:Data\*(Aq) || die "Can\*(Aqt access dir!\en";
\&
\& $data = $rdb\->sql (<<Query); ## OR: @data = $rdb\->sql (<<Query);
\& .
\& . (SQL)
\& .
\& Query
\&
\& foreach $row (@$data) { ## OR: foreach $row (@data) {
\& @columns = @$row; ## NO null delimited string \-\- v3.2
\& }
\&
\& $rdb\->close;
\& $rdb\->close ($database); ## To save updated database
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Here is a simple database where the fields are delimited by commas:
.PP
.Vb 6
\& Player,Years,Points,Rebounds,Assists,Championships
\& ...
\& Larry Bird,13,25,11,7,3
\& Michael Jordan,14,29,6,5,5
\& Magic Johnson,13,22,7,11,5
\& ...
.Ve
.PP
\&\fINote:\fR The first line must contain the field names (case sensitive).
.SH "Supported SQL Commands"
.IX Header "Supported SQL Commands"
Here are a list of the \s-1SQL\s0 commands that are supported by Sprite:
.IP "\fIselect\fR \- retrieves records that match specified criteria:" 5
.IX Item "select - retrieves records that match specified criteria:"
.Vb 3
\& select col1 [,col2] from database
\& where (cond1 OPERATOR value1)
\& [and|or (cond2 OPERATOR value2) ...]
.Ve
.Sp
The '*' operator can be used to select all columns.
.Sp
The \fIdatabase\fR is simply the file that contains the data. If the file
is not in the current directory, the path must be specified.
.Sp
Sprite does \fInot\fR support multiple tables (or commonly knows as \*(L"joins\*(R").
.Sp
Valid column names can be used where [cond1..n] and [value1..n] are expected,
such as:
.Sp
\&\fIExample 1\fR:
.Sp
.Vb 2
\& select Player, Points from my_db
\& where (Rebounds > Assists)
.Ve
.Sp
The following \s-1SQL\s0 operators can be used: =, <, >, <=, >=, <> as well as
Perl's special operators: =~ and !~. The =~ and !~ operators are used to
specify regular expressions, such as:
.Sp
\&\fIExample 2\fR:
.Sp
.Vb 2
\& select * from my_db
\& where (Name =~ /Bird$/i)
.Ve
.Sp
Selects records where the Name column ends with \*(L"Bird\*(R" (case insensitive).
For more information, look at a manual on regexps.
.Sp
\&\fINote:\fR A path to a database can contain only the following characters:
.Sp
.Vb 1
\& \ew, \ex80\-\exFF, \-, /, \e, ., :
.Ve
.Sp
If you have directories with spaces or other 'invalid' characters, you
need to use the \fIset_db_dir\fR method.
.IP "\fIupdate\fR \- updates records that match specified criteria." 5
.IX Item "update - updates records that match specified criteria."
.Vb 4
\& update database
\& set cond1 = (value1)[,cond2 = (value2) ...]
\& where (cond1 OPERATOR value1)
\& [and|or (cond2 OPERATOR value2) ...]
.Ve
.Sp
\&\fIExample\fR:
.Sp
.Vb 3
\& update my_db
\& set Championships = (Championships + 1)
\& where (Player = \*(AqLarry Bird\*(Aq)
\&
\& update my_db
\& set Championships = (Championships + 1),
\& Years = (12)
\& where (Player = \*(AqLarry Bird\*(Aq)
.Ve
.IP "\fIdelete\fR \- removes records that match specified criteria:" 5
.IX Item "delete - removes records that match specified criteria:"
.Vb 3
\& delete from database
\& where (cond1 OPERATOR value1)
\& [and|or (cond2 OPERATOR value2) ...]
.Ve
.Sp
\&\fIExample\fR:
.Sp
.Vb 3
\& delete from my_db
\& where (Player =~ /Johnson$/i) or
\& (Years > 12)
.Ve
.IP "\fIalter\fR \- simplified version of \s-1SQL\-92\s0 counterpart" 5
.IX Item "alter - simplified version of SQL-92 counterpart"
Removes the specified column from the database. The other standard \s-1SQL\s0
functions for alter table are not supported:
.Sp
.Vb 2
\& alter table database
\& drop column column\-name
\&
\& alter table database
\& add column column\-name
.Ve
.Sp
\&\fIExample\fR:
.Sp
.Vb 2
\& alter table my_db
\& drop column Years
\&
\& alter table my_db
\& add column Legend
.Ve
.IP "\fIinsert\fR \- inserts a record into the database:" 5
.IX Item "insert - inserts a record into the database:"
.Vb 4
\& insert into database
\& (col1, col2, ... coln)
\& values
\& (val1, val2, ... valn)
.Ve
.Sp
\&\fIExample\fR:
.Sp
.Vb 4
\& insert into my_db
\& (Player, Years, Points, Championships)
\& values
\& (\*(AqKareem Abdul\-Jabbar\*(Aq, 21, 26, 6)
.Ve
.Sp
You don't have to specify all of the fields in the database! Sprite also
does not require you to specify the fields in the same order as that of
the database.
.Sp
\&\fINote:\fR You should make it a habit to quote strings.
.SH "METHODS"
.IX Header "METHODS"
Here are the available methods:
.IP "\fIset_delimiter\fR" 5
.IX Item "set_delimiter"
The set_delimiter function sets the read and write delimiter for the
database. The delimiter is not limited to one character; you can have
a string, and even a regexp (for reading only).
.Sp
\&\fIReturn Value\fR
.Sp
None
.IP "\fIset_os\fR" 5
.IX Item "set_os"
The set_os function can be used to notify Sprite as to the operating
system that you're using. Default is determined by $^O.
.Sp
\&\fINote:\fR If you're using Sprite on Windows 95/NT or on \s-1OS2,\s0 make sure
to use backslashes \*(-- and \s-1NOT\s0 forward slashes \*(-- when specifying a path
for a database or to the \fIset_db_dir\fR or \fIset_lock_file\fR methods!
.Sp
\&\fIReturn Value\fR
.Sp
None
.IP "\fIset_lock_file\fR" 5
.IX Item "set_lock_file"
For any O/S that doesn't support flock (i.e Mac, Windows 95 and \s-1VMS\s0), this
method allows you to set a lock file to use and the number of tries that
Sprite should try to obtain a 'fake' lock. However, this method is \s-1NOT\s0
fully reliable, but is better than no lock at all.
.Sp
\&'Sprite.lck' (either in the directory specified by \fIset_db_dir\fR or in
the current directory) is used as the default lock file if one
is not specified.
.Sp
\&\fIReturn Value\fR
.Sp
None
.IP "\fIset_db_dir\fR" 5
.IX Item "set_db_dir"
A path to a database can contain only the following characters:
.Sp
.Vb 1
\& \ew, \ex80\-\exFF, \-, /, \e, ., :
.Ve
.Sp
If your path contains other characters besides the ones listed above,
you can use this method to set a default directory. Here's an example:
.Sp
.Vb 1
\& $rdb\->set_db_dir ("Mac OS:Perl 5:Data");
\&
\& $data = $rdb\->sql ("select * from phone.db");
.Ve
.Sp
Sprite will look for the file \*(L"Mac OS:Perl 5:Data:phone.db\*(R". Just to
note, the database filename cannot have any characters besides the one
listed above!
.Sp
\&\fIReturn Value\fR
.Sp
.Vb 2
\& 0 \- Failure
\& 1 \- Success
.Ve
.IP "\fIsql\fR" 5
.IX Item "sql"
The sql function is used to pass a \s-1SQL\s0 command to this module. All of the
\&\s-1SQL\s0 commands described above are supported. The \fIselect\fR \s-1SQL\s0 command
returns an array containing the data, where the first element is the status.
All of the other other \s-1SQL\s0 commands simply return a status.
.Sp
\&\fIReturn Value\fR
1 \- Success
0 \- Error
.IP "\fIclose\fR" 5
.IX Item "close"
The close function closes the file, and destroys the database object. You
can pass a filename to the function, in which case Sprite will save the
database to that file; the directory set by \fIset_db_dir\fR is used as
the default.
.Sp
\&\fIReturn Value\fR
.Sp
None
.SH "NOTES"
.IX Header "NOTES"
Sprite is not the solution to all your data manipulation needs. It's fine
for small databases (less than 1000 records), but anything over that, and
you'll have to sit there and twiddle your fingers while Sprite goes
chugging away ... and returns a few *seconds* or so later.
.PP
The main advantage of Sprite is that you can use Perl's regular expressions
to search through your data. Yippee!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::CSV, \s-1RDB\s0
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
I would like to thank the following, especially Rod Whitby and Jim Esten,
for finding bugs and offering suggestions:
.PP
.Vb 10
\& Rod Whitby (rwhitby@geocities.com)
\& Jim Esten (jesten@wdynamic.com)
\& Dave Moore (dmoore@videoactv.com)
\& Shane Hutchins (hutchins@ctron.com)
\& Josh Hochman (josh@bcdinc.com)
\& Barry Harrison (barryh@topnet.net)
\& Lisa Farley (lfarley@segue.com)
\& Loyd Gore (lgore@ascd.org)
\& Tanju Cataltepe (tanju@netlabs.net)
\& Haakon Norheim (hanorhei@online.no)
.Ve
.SH "COPYRIGHT INFORMATION"
.IX Header "COPYRIGHT INFORMATION"
.Vb 2
\& Copyright (c) 1995\-1998, Shishir Gundavaram
\& All Rights Reserved
\&
\& Permission to use, copy, and distribute is hereby granted,
\& providing that the above copyright notice and this permission
\& appear in all copies and in supporting documentation.
.Ve