.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::Data 3pm"
.TH File::Data 3pm "2012-06-04" "perl v5.14.2" "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"
File::Data \- interface to file data
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Wraps all the accessing of a file into a convenient set of calls for
reading and writing data, including a simple regex interface.
.PP
Note that the file needs to exist prior to using this module!
.PP
See \fInew()\fR
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use strict;
\&
\&    use File::Data;
\&
\&    my $o_dat = File::Data\->new(\*(Aq./t/example\*(Aq);
\&
\&    $o_dat\->write("complete file contents\en");
\&
\&    $o_dat\->prepend("first line\en"); # line 0
\&
\&    $o_dat\->append("original second (last) line\en");
\&
\&    $o_dat\->insert(2, "new second line\en"); # inc. zero!
\&
\&    $o_dat\->replace(\*(Aqline\*(Aq, \*(AqLINE\*(Aq);
\&
\&    print $o_dat\->READ;
.Ve
.Sp
.RS 4
Or, perhaps more seriously :\-}
.Sp
.Vb 1
\&    my $o_sgm = File::Data\->new(\*(Aq./sgmlfile\*(Aq);
\&
\&    print "new SGML data: ".$o_sgm\->REPLACE(
\&        \*(Aq\e<\es*((?i)tag)\es*\e>\es*((?s).*)\es*\e<\es*((?i)\es*\e/\es*tag)\es*\e>\*(Aq,
\&        qq|<tag>key="val"</tag>|,
\&    ) if $o_sgm;
.Ve
.Sp
See \s-1METHODS\s0 and \s-1EXAMPLES\s0.
.RE
.SH "IMPORTANT"
.IX Header "IMPORTANT"
lowercase method calls return the object itself, so you can chain calls.
.PP
.Vb 1
\&    my $o_obj = $o_dat\->read; # ! <= object !
.Ve
.PP
\&\s-1UPPERCASE\s0 method calls return the data relevant to the operation.
.PP
.Vb 1
\&    my @data  = $o_dat\->READ; # ! <= data   !
.Ve
.PP
While this may occasionally be frustrating, using the \fBprinciple of
least surprise\fR, it is at least consistent.
.PP
See do
.SH "EXPLANATION"
.IX Header "EXPLANATION"
.RS 4
The idea is to standardise accessing of files for repetitive and straight
forward tasks, and remove the repeated and therefore error prone file
access I have seen in many sites, where varying, (with equivalently
varying success), methods are used to achieve essentially the same result
\&\- a simple search and replace and/or a regex match.
.Sp
Approaches to opening and working with files vary so much, where
one person may wish to know if a file exists, another wishes to know
whether the target is a file, or if it is readable, or writable and so on.
Sometimes, in production code even (horror), file's are opened without any
checks of whether the open was succesful.  Then there's a loop through
each line to find the first or many patterns to read and/or replace.
With a failure, normally the only message is 'permission denied', is
that read or write access, does the file even exist? etc.
.Sp
This module attempts to provide a plain/generic interface to accessing
a file's data.  This will not suit every situation, but I have included
some examples which will hopefully demonstrate that it may be used
in situations where people would normally go through varying and
inconsistent, (and therefore error-prone),  procedures \- to get at the
same data.
.Sp
Theoretically you can mix and match your read and writes so long as you
don't open read-only.
.Sp
.Vb 1
\&    my $o_dat  = File::Data\->new($file);
\&
\&    my $i_snrd = $o_dat\->append($append)\->REPLACE($search, $replace);
\&
\&    print $o_dat\->READ;
.Ve
.Sp
One last thing \- I'm sure this could be made more efficient, and I'd be
receptive to any suggestions to that effect.  Note though that the intention
has been to create a simple and consistent interface, rather than a complicated
one.
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
Create a new File::Data object (default read-write).
.Sp
.Vb 1
\&    my $o_rw = File::Data\->new($filename); # read\-write
\&
\&    my $o_ro = File::Data\->new($filename, \*(Aqro\*(Aq); # read\-only
.Ve
.Sp
Each file should have it's own discrete object.
.Sp
Note that if you open a file read-only and then attempt to write to it,
that will be regarded as an error, even if you change the permissions
in the meantime.
.Sp
Further: The file \fBmust\fR exist before succesful use of this method
is possible.  This is \fBnot\fR a replacement for modules which create and
delete files, this is purely designed as an interface to the \fBdata\fR
of existing files.  A \fBcreate\fR function is a future possibility.
.Sp
Look in \s-1EXAMPLES\s0 for a more complete explanation of possible arguments
to the \fB\f(BInew()\fB\fR method
.IP "read" 4
.IX Item "read"
Read all data from file
.Sp
.Vb 1
\&    $o_dat = $o_dat\->read; # !
\&
\&    my @data = $o_dat\->READ;
.Ve
.IP "_internal" 4
.IX Item "_internal"
read
.Sp
.Vb 1
\&    does this...
.Ve
.IP "write" 4
.IX Item "write"
Write data to file
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->WRITE; # !
\&
\&    my @written = $o_dat\->write;
.Ve
.IP "prepend" 4
.IX Item "prepend"
Prepend to file
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->prepen(\e@lines); # !
\&
\&    my @prepended = $o_dat\->prepend(\e@lines);
.Ve
.IP "insert" 4
.IX Item "insert"
Insert data at line number, starting from '0'
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->insert($i_lineno, \e@lines); # !
\&
\&    my @inserted = $o_dat\->INSERT($i_lineno, \e@lines);
.Ve
.IP "append" 4
.IX Item "append"
Append to file
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->append(\e@lines); # !
\&
\&    my @appended = $o_dat\->APPEND(\e@lines);
.Ve
.IP "search" 4
.IX Item "search"
Retrieve data out of a file, simple list of all matches found are returned.
.Sp
Note \- you must use capturing parentheses for this to work!
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->search(\*(Aq/^(.*\e@.*)$/\*(Aq); # !
\&
\&    my @addrs = $o_dat\->SEARCH(\*(Aq/^(.*\e@.*)$/\*(Aq);
\&
\&    my @names = $o_dat\->SEARCH(\*(Aq/^(?:[^:]:){4}([^:]+):/\*(Aq);
.Ve
.IP "replace" 4
.IX Item "replace"
Replace data in a 'search and replace' manner, returns the final data.
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->replace($search, $replace); # !
\&
\&    my @data = $o_dat\->REPLACE($search, $replace);
\&
\&    my @data = $o_dat\->REPLACE(
\&        q|\e<a href=([\*(Aq"])([^$1]+)?$1| => q|\*(Aqmy.sales.com\*(Aq|,
\&    );
.Ve
.Sp
This is \fBsimple\fR, in that you can do almost anything in the \fBsearch\fR side,
but the \fBreplace\fR side is a bit more restricted, as we can't effect the
replacement modifiers on the fly.
.Sp
If you really need this, perhaps \fB(?{})\fR can help?
.IP "xreturn" 4
.IX Item "xreturn"
Returns the product of the given (or last) \fB\f(BIdo()\fB\fR, undef on failure.
.Sp
.Vb 1
\&    my $o_dat = $o_dat\->prepend($A)\->append($b)\->return(\*(Aqprepend\*(Aq); # !
\&
\&    my @prepended = $o_dat\->prepend($A)\->append($b)\->RETURN(\*(Aqprepend\*(Aq);
\&
\&    my @appended  = $o_dat\->prepend($A)\->append($b)\->RETURN; # like read()
.Ve
.IP "create" 4
.IX Item "create"
placeholder \- unsupported
.IP "delete" 4
.IX Item "delete"
placeholder \- unsupported
.IP "close" 4
.IX Item "close"
Close the file
.Sp
.Vb 1
\&    my $i_closed = $o_dat\->close; # 1|0
.Ve
.IP "info" 4
.IX Item "info"
placeholder \- unsupported
.SH "VARIABLES"
.IX Header "VARIABLES"
Various variables may be set affecting the behaviour of the module.
.ie n .IP "$File::Data::DEBUG" 4
.el .IP "\f(CW$File::Data::DEBUG\fR" 4
.IX Item "$File::Data::DEBUG"
Set to 0 (default) or 1 for debugging information to be printed on \s-1STDOUT\s0.
.Sp
.Vb 1
\&    $File::Data::DEBUG = 1;
.Ve
.Sp
Alternatively  set to a regex of any of the prime methods to debug them individually.
.Sp
.Vb 1
\&    $File::Data::DEBUG = \*(Aq(ap|pre)pend\*(Aq;
.Ve
.ie n .IP "$File::Data::FATAL" 4
.el .IP "\f(CW$File::Data::FATAL\fR" 4
.IX Item "$File::Data::FATAL"
Will die if there is any failure in accessing the file, or reading the data.
.Sp
Default = 0 (don't die \- just warn);
.Sp
.Vb 1
\&    $File::Data::FATAL = 1;    # die
.Ve
.ie n .IP "$File::Data::REFERENCE" 4
.el .IP "\f(CW$File::Data::REFERENCE\fR" 4
.IX Item "$File::Data::REFERENCE"
Will return a reference, not a list, useful with large files.
.Sp
Default is 0, ie; methods normally returns a list.
.Sp
Hopefully future versions of perl may return a reference if you request one,
but as this is not supported generically yet, nor do we, so we require the
variable to be set.  There may be an argument to make this a reference by
default, feedback will decide.
.Sp
.Vb 1
\&    $File::Data::REFERENCE = 1;
\&
\&    my $a_ref = $o_dat\->search(\*(Aq.*\*(Aq);
\&
\&    print "The log: \en".@{ $a_ref };
.Ve
.ie n .IP "$File::Data::SILENT" 4
.el .IP "\f(CW$File::Data::SILENT\fR" 4
.IX Item "$File::Data::SILENT"
Set to something other than zero if you don't want error messages ?\-\e
.Sp
.Vb 1
\&    $File::Data::SILENT = 0; # per line
.Ve
.ie n .IP "$File::Data::STRING" 4
.el .IP "\f(CW$File::Data::STRING\fR" 4
.IX Item "$File::Data::STRING"
Where regex's are used, default behaviour is to treate the entire file as a
single scalar string, so that, for example, \fB(?ms:...)\fR matches are effective.
.Sp
Unset if you don't want this behaviour.
.Sp
.Vb 1
\&    $File::Data::STRING = 0; # per line
.Ve
.ie n .IP "$File::Data::PERMISSIONS" 4
.el .IP "\f(CW$File::Data::PERMISSIONS\fR" 4
.IX Item "$File::Data::PERMISSIONS"
File will be opened read-write (\fB\f(BIinsert()\fB\fR compatible) unless this
variable is set explicitly or given via \fB\f(BInew()\fB\fR.  In either case,
unless it is one of our valid permission \fBkeys\fR declared below,
it will be passed on to \fBFileHandle\fR and otherwise not modified.
We don't support fancy permission sets, just read or write.
.Sp
Read-only permissions may be explicitly set using one of these \fBkeys\fR:
.Sp
.Vb 1
\&    $File::Data::PERMISSIONS = \*(Aqro\*(Aq; # or readonly or <
.Ve
.Sp
Or, equivalently, for read-write (default):
.Sp
.Vb 1
\&    $File::Data::PERMISSIONS = \*(Aqrw\*(Aq; # or readwrite or +<
.Ve
.Sp
Note that it makes no sense to have an 'append only' command (>>),
we'd have to disable all of write, search and replace, and insert,
etc. in that case \- just use the \fB\f(BIappend()\fB\fR method only.
.Sp
This is a KISS-compatible module remember?
.PP
# ================================================================
.SH "SPECIAL"
.IX Header "SPECIAL"
\&...
.IP "\s-1AUTOLOAD\s0" 4
.IX Item "AUTOLOAD"
Any unrecognised function will be passed to the FileHandle object for final
consideration, behaviour is then effectively 'o_dat \s-1ISA\s0 FileHandle'.
.Sp
.Vb 1
\&    $o_dat\->truncate;
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Typical construction examples:
.PP
.Vb 1
\&    my $o_rw = File::Data\->new($filename, \*(Aqrw\*(Aq);
\&
\&    my $o_ro = File::Data\->new($filename, \*(Aqro\*(Aq);
.Ve
.IP "complete" 4
.IX Item "complete"
.Vb 1
\&    my $o_dat = File::Data\->new(\*(Aq./jabber\*(Aq);
\&
\&    $o_dat\->write("  Bewxre the Jabberwock my son,\en");
\&
\&    $o_dat\->prepend("The Jxbberwock by Lewis Cxrroll:\en");
\&
\&    $o_dat\->append("  the claws thxt snxtch,\en  ...\en");
\&
\&    $o_dat\->insert(2, "  the jaws which bite.\en");
\&
\&    $o_dat\->replace(\*(Aqx\*(Aq, \*(Aqa\*(Aq);
\&
\&    print $o_dat\->SEARCH(\*(AqThe.+\en\*(Aq)\->REPLACE("The.+\en", \*(Aq\*(Aq)\->return(\*(Aqsearch\*(Aq);
\&
\&    print $o_dat\->READ;
.Ve
.IP "error" 4
.IX Item "error"
Failure is indicated by an error routine being called, this will print
out any error to \s-1STDERR\s0, unless warnings are declared fatal, in which
case we croak.  You can register your own error handlers for any method
mentioned in the \s-1METHOD\s0 section of this document, in addition is a
special \fBinit\fR call for initial file opening and general setting up.
.Sp
Create a read-write object with a callback for all errors:
.Sp
.Vb 3
\&    my $o_rw = File::Data\->new($filename, \*(Aqro\*(Aq, {
\&        \*(Aqerror\*(Aq        => \e&myerror,
\&    });
.Ve
.Sp
Create a read-only object with a separate object handler for each error type:
.Sp
.Vb 7
\&    my $o_rw = File::Data\->new($filename, \*(Aqrw\*(Aq, {
\&        \*(Aqerror\*(Aq        => $o_generic\->error_handler,
\&        \*(Aqinsert\*(Aq    => $o_handler\->insert_error,
\&        \*(Aqopen\*(Aq        => $o_open_handler,
\&        \*(Aqread\*(Aq        => \e&carp,
\&        \*(Aqwrite\*(Aq        => \e&write_error,
\&    });
.Ve
.IP "commandline" 4
.IX Item "commandline"
From the command line:
.Sp
.Vb 1
\&    C<perl \-MFile::Data \-e "File::Data\->new(\*(Aq./test.txt\*(Aq)\->write(\*(Aqsome stuff\*(Aq)">
.Ve
.Sp
And (very non-obfuscated)
.Sp
.Vb 10
\&  C<
\&  perl \-MFile::Data \-e "@x=sort qw(perl another hacker just);
\&    print map {split(\e"\en\e", ucfirst(\e$_).\e" \e")}\e
\&    File::Data\->new(\e"./t/japh\e")\->\e
\&      write(shift(@x).\e"\en\e")\->    \e
\&      append(shift(@x).\e"\en\e")\->   \e
\&      prepend(shift(@x).\e"\en\e")\->  \e
\&      insert(2, shift(@x).\e"\en\e")\->\e
\&    READ;"
\&  >
.Ve
.Sp
If you still have problems, mail me the output of
.Sp
.Vb 1
\&    make test TEST_VERBOSE=1
.Ve
.SH "PRIVATE"
.IX Header "PRIVATE"
.RS 4
Private methods not expected to be called by anybody, and completely unsupported.
.Sp
Expected to metamorphose regularly \- do \fBnot\fR call these \- you have been warned!
.Sp
_var
.Sp
Variable get/set method
.Sp
.Vb 1
\&    my $get = $o_dat\->_var($key);        # get
\&
\&    my $set = $o_dat\->_var($key, $val);    # set
.Ve
.Sp
_debug
.Sp
Print given args on \s-1STDOUT\s0
.Sp
.Vb 1
\&    $o_dat\->_debug($msg) if $File::Data::DEBUG;
.Ve
.Sp
_vars
.Sp
Return dumped env and object \fBkey\fR and \fBvalues\fR
.Sp
.Vb 1
\&    print $o_dat\->_vars;
.Ve
.Sp
_err
.Sp
Get/set error handling methods/objects
.Sp
.Vb 1
\&    my $c_sub = $o_dat\->_err(\*(Aqinsert\*(Aq); # or default
.Ve
.Sp
_error
.Sp
By default prints error to \s-1STDERR\s0, will \fBcroak\fR if \fBFile::Data::FATAL\fR set, returning ().
.Sp
See \s-1EXAMPLES\s0 for info on how to pass your own error handlers in.
.Sp
_mapfile
.Sp
Maps file
.Sp
.Vb 1
\&    my $file = $o_dat\->_mapfile($filename);
.Ve
.Sp
_mapperms
.Sp
Maps given permissions to appropriate form for \fBFileHandle\fR
.Sp
.Vb 1
\&    my $perms = $o_dat\->_mapperms(\*(Aq+<\*(Aq);
.Ve
.Sp
_maperrs
.Sp
Map error handlers, if given
.Sp
.Vb 1
\&    my $h_errs = $o_dat\->_maperrs(\e%error_handlers);
.Ve
.Sp
_enter
.Sp
Mark the entering of a special section, or state
.Sp
.Vb 1
\&    my $entered = $o_dat\->enter(\*(Aqsearch\*(Aq);
.Ve
.Sp
_leave
.Sp
Mark the leaving of a special section, or state
.Sp
.Vb 1
\&    my $left = $o_dat\->_leave(\*(Aqsearch\*(Aq);
.Ve
.Sp
_fh
.Sp
Get and set \fBFileHandle\fR.
.Sp
Returns undef otherwise.
.Sp
.Vb 1
\&    my $FH = $o_dat\->_fh($FH);
.Ve
.RE
.SH "UTILITY"
.IX Header "UTILITY"
Private methods not expected to be called by anybody, and completely unsupported.
.PP
Expected to metamorphose regularly \- do \fBnot\fR call these \- you have been warned!
.Sp
.RS 4
The following utility methods return integer values
.Sp
.Vb 1
\&    1 = success
\&
\&    0 = failure
.Ve
.Sp
_init
.Sp
Setup object, open a file, with permissions.
.Sp
.Vb 1
\&    my $i_ok = $o_date\->_init($file, $perm, $h_errs);
.Ve
.Sp
_check_access
.Sp
Checks the args for existence and appropriate permissions etc.
.Sp
.Vb 1
\&    my $i_isok = $o_dat\->_check_access($filename, $permissions);
.Ve
.Sp
_open
.Sp
Open the file
.Sp
.Vb 1
\&    my $i_ok = $o_dat\->_open;
.Ve
.Sp
_lock
.Sp
Lock the file
.Sp
.Vb 1
\&    my $i_ok = $o_dat\->_lock;
.Ve
.Sp
_unlock
.Sp
Unlock the file
.Sp
.Vb 1
\&    my $i_ok = $o_dat\->_unlock;
.Ve
.Sp
_close
.Sp
Close the filehandle
.Sp
.Vb 1
\&    my $i_ok = $o_dat\->_close;
.Ve
.Sp
do
.Sp
Simple wrapper for method calls, returning the content.
.Sp
.Vb 1
\&    my @inserted = $o_dat\->do(\*(Aqinsert\*(Aq, @this);
\&
\&    my @appended = $o_dat\->do(\*(Aqappend\*(Aq, @this);
.Ve
.Sp
An addendum to this method, and to make life generally easier, is that
you can also call any of the above methods in uppercase, to call via
\&\fB\f(BIdo()\fB\fR eg;
.Sp
.Vb 1
\&    my @data = $o_dat\->WRITE($this)\->APPEND\->($that)\->read;
.Ve
.Sp
First argument is the method to call, followed by the arguments that
method expects.
.Sp
.Vb 2
\&    perl \-MFile::Data \-e "print File::Data\->new($file)\->INSERT(3,
\&    \e"third line\en\e")\->READ";
.Ve
.Sp
If you want to get at the output of a particular called method see
\&\fIreturn()\fR
.RE
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012 by Richard Foley <file.data@rfi.net>
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 63:" 4
.IX Item "Around line 63:"
You forgot a '=back' before '=head1'
.IP "Around line 872:" 4
.IX Item "Around line 872:"
You can't have =items (as at line 878) unless the first thing after the =over is an =item
.IP "Around line 1181:" 4
.IX Item "Around line 1181:"
You can't have =items (as at line 1189) unless the first thing after the =over is an =item