NAME

Chj::IO::File

SYNOPSIS

 my $f = new Chj::IO::File;
 $f->xopen("<foo/file.txt");
 my $g = Chj::IO::File->xopen("<foo/file.txt");

 ...

DESCRIPTION

Something like IO::File, but more lightweight (IO::File takes about 0.3 seconds to load on my laptop, whereas this module takes less than 30ms), and with methods that throw (currently untyped) exceptions on error.

NEW: $Chj::IO::ERRNO is set to $!+0 on strategic positions $Chj::IO::ERRSTR to $! for later reference. HACK state is creeping in. Because of ugly Perl bugs. todo finish putting those into every other part of these modules.

CLASS METHODS

new ("path")

Gives a new unopened filehandle object. (Not really sure what for; you should be able to use perl builtins on it.)

xopen (path [,.. ])

Creates new filehandle and calls builtin open, croaks on errors. (May also be called on an existing object if I'm not wrong.)

OBJECT METHODS

read ( $buf, numbytes [, offset ] )

xread ( ... )

Calls builtin, without/with error checking.

xreadline

Same as builtin readline, but checks $! for errors. (Not sure that really works.)

xreadline_chomp

Does xreadline and chomp's the result(s) (unless undefined).

getline

Same as <$self>. Added since MIME::Parse expects this method.

xreadchunk ( length )

Read a chunk of max length chars/bytes and return it. Return undef on end of file.

# IDEA: xxreadchunk that throws exception on end of file? So no check needed.

xxreadchunk ( length )

# Yeah try it. Only string exception so far

xsysreadcompletely( buf, length [,offset]) -> bool

Like xsysread, but resumes reading upon intterrupted system calls and partial reads from pipes until the required length has been read. Returns true if buf was read completely, false on EOF upon start of message. EOF after having read part but not all of buf results in an exception.

xsyswritecompletely( buf [,length [,offset]])

Like xsyswrite, but resumes writing upon interrupted system calls until everything is written. Does not return anything.

content

xcontent

Returns full contents. Latter also checks $! for errors (see above).

seek / xseek

Only special thing is that if you only give one argument, it does imply SEEK_SET as the whence value. (Hmmm well, there's also xrewind for xseek(0) purpose.)

truncate / xtruncate

Totally normal. Just let me state that if your file pointer will not be changed by this call, so be sure to call xrewind as well if you plan to continue to write to the file handle.

BUGS

I wanted to overload <> to xreadline(), but that does not work (on perl 5.6.1), since the CORE::readline function will call into <> again causing an infinite recursion. There does not seem to be a solution, thus I leave <> the default (without error checking).

(BTW there's another perl bug: http://bugs6.perl.org/rt2/Ticket/Display.html?id=6748 )

Not yet fully tested.

SEE ALSO

Chj::xopen, Chj::IO::SysFile, Chj::xsysopen

NOTE

This is alpha software! Read the status section in the package README or on the website.