NAME¶

Paranoid::IO::Line - Paranoid Line-based I/O functions

VERSION¶

$Id: lib/Paranoid/IO/Line.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

SYNOPSIS¶

  use Paranoid::IO::Line;
  PIOMAXLNSIZE = 4096;
  $nlines = sip($filename, @lines);
  $nlines = sip($filename, @lines, 1);
  $nlines = tailf($filename, @lines);
  $nlines = tailf($filename, @lines, 1);
  $nlines = tailf($filename, @lines, 1, -100);
  piolClose($filename);
  $nlines = slurp($filename, @lines);
  # Non-locking variants
  $nlines = nlsip($filename, @lines);
  $nlines = nltailf($filename, @lines);
  $nlines = nlslurp($filename, @lines);

DESCRIPTION¶

This module extends and leverages Paranoid::IO's capabilities with an eye towards line-based text files, such as log files. It does so while maintaining a paranoid stance towards I/O. For that reason the functions here only work on limited chunks of data at a time, both in terms of maximum memory kept in memory at a time and the maximum record length. Paranoid::IO provides PIOMAXFSIZE which controls the former, but this module provides PIOMAXLNSIZE which controls the latter.

Even with the paranoid slant of these functions they should really be treated as convenience functions which can simplify higher level code without incurring any significant risk to the developer or system. They inherit not only opportunistic I/O but platform-agnostic record separators via internal use of pchomp from Paranoid::Input.

NOTE: while this does build off the foundation provided by Paranoid::IO it is important to note that you should not work on the same files using :<Paranoid::IO>'s functions while also using the functions in this module. While the former works from raw I/O the latter has to manage buffers in order to identify record boundaries. If you were to, say, sip from a file, then pread or pseek elsewhere it would render those buffers not only useless, but corrupt. This is important to note since the functions here do leverage the file handle caching features provided by popen.

It should also be noted that since we're anticipating line-based records we expect every line, even the last line in a file, to be properly terminated with a record separator (new line sequence).

As with all Paranoid modules string descriptions of errors can be retrieved from Paranoid::ERROR as they occur.

IMPORT LISTS¶

This module exports the following symbols by default:

    sip nlsip tailf nltailf slurp nlslurp piolClose

The following specialized import lists also exist:

    List        Members
    --------------------------------------------------------
    all         @defaults PIOMAXLNSIZE

SUBROUTINES/METHODS¶

    $nlines = sip($filename, @lines);
    $nlines = sip($filename, @lines, 1);

    $nlines = sip($filename, @lines);
    warn "successfully extracted lines" 
        if $nlines and scalar @lines;
    warn "no errors, but no lines" 
        if $nlines and ! scalar @lines;
    warn "line length exceeded on some lines" 
        if !$nlines and scalar @lines;
    warn "I/O errors or all lines exceeded line length" 
        if !$nlines and ! scalar @lines;

    warn "good to go" if scalar @lines or $nlines;
 
    # or, more likely:
    if (@lines) {
        # process input...
    }

    $nlines = nlsip($filename, @lines);
    $nlines = nlsip($filename, @lines, 1);

    $nlines = tailf($filename, @lines);
    $nlines = tailf($filename, @lines, 1);
    $nlines = tailf($filename, @lines, 1, -100);

    $nlines = nltailf($filename, @lines);
    $nlines = nltailf($filename, @lines, -100);
    $nlines = nltailf($filename, @lines, -100, 1);

  $nlines = slurp($filename, @lines);
  $nlines = slurp($filename, @lines, 1);

  $nlines = nlslurp($filename, @lines);
  $nlines = nlslurp($filename, @lines, 1);

  $rv = piolClose($filename);

DEPENDENCIES¶

o

Fcntl

o

Paranoid

o

Paranoid::Debug

o

Paranoid::Input

o

Paranoid::IO

BUGS AND LIMITATIONS¶

While all of these functions will just as happily accept file handles as well as file names doing will almost certainly cause any number of bugs. Beyond the inherited Paranoid::IO issues (like not getting the fork-safe features for any file handle opened directly by the developer) there are other issues. Buffers, for instance, can only be managed by one consistent name, there is no way to correlate them and make them interchangeable. There are other subtleties as well, but there is no need to detail them all.

Suffice it to say that when using this module one should only use file names, and use them consistently.

AUTHOR¶

Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT¶

This software is free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either:

  a)     the GNU General Public License
         <https://www.gnu.org/licenses/gpl-1.0.html> as published by the 
         Free Software Foundation <http://www.fsf.org/>; either version 1
         <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
         <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
  b)     the Artistic License 2.0
         <https://opensource.org/licenses/Artistic-2.0>,

subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark.

(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc. (www.paranoid.com)