File::Read - Unique interface for reading one or more files

File-Read documentation Contained in the File-Read distribution.

Index

Code Index:

NAME

Top

File::Read - Unique interface for reading one or more files

VERSION

Top

Version 0.0801

SYNOPSIS

Top

    use File::Read;

    # read a file
    $file = read_file($path);

    # read several files
    @files = read_files(@paths);

    # aggregate several files
    $file = read_files(@paths);

    # read a file as root, skip comments and blank lines
    $file = read_file({ as_root => 1, skip_comments => 1, skip_blanks => 1 }, $path);

DESCRIPTION

Top

This module mainly proposes functions for reading one or more files, with different options. See below for more details and examples.

Rationale

This module was created to address a quite specific need: reading many files, some as a normal user and others as root, and eventually do a little more processing, all while being at the same time compatible with Perl 5.004. File::Slurp addresses the first point, but not the others, hence the creation of File::Read. If you don't need reading files as root or the post-processing features, then it's faster to directly use File::Slurp.

EXPORT

Top

By default, this module exports all the functions documented afterhand. It also recognizes import options. For example

    use File::Read 'err_mode=quiet';

set read_file()'s err_mode option default value to "quiet".

FUNCTIONS

Top

read_file()

Read the files given in argument and return their content, as as list, one element per file, when called in list context, or as one big chunk of text when called in scalar context. Options can be set using a hashref as first parameter.

Options

  • aggregate controls how the function returns the content of the files that were successfully read. By default, When set to true (default), the function returns the content as a scalar; when set to false, the content is returned as a list.
  • as_root tells the function to read the given file(s) as root using the command indicated by the cmd option.
  • cmd sets the shell command used for reading files as root. Default is "sudo cat". Therefore you need sudo(8) and cat(1) on your system, and sudoers(5) must be set so the user can execute cat(1).
  • err_mode controls how the function behaves when an error occurs. Available values are "croak", "carp" and "quiet". Default value is "croak".
  • skip_comments tells the functions to remove all comment lines from the read files.
  • skip_blanks tells the functions to remove all blank lines from the read files.
  • to_ascii tells the functions to convert the text to US-ASCII using Text::Unidecode. If this module is not available, non-ASCII data are deleted.

Examples

Just read a file:

    my $file = read_file($path);

Read a file, returning it as list:

    my @file = read_file({ aggregate => 0 }, $path);

Read a file, skipping comments:

    my $file = read_file({ skip_comments => 1 }, $path);

Read several files, skipping blank lines and comments:

    my @files = read_file({ skip_comments => 1, skip_blanks => 1 }, @paths);
read_files()

read_files() is just an alias for read_file() so that it look more sane when reading several files.

DIAGNOSTICS

Top

Bad value '%s' for option '%s'

(E) You gave a bad value for the indicated option. Please check the documentation for the valid values.

This function needs at least one path

(E) You called a function without giving it argument.

SEE ALSO

Top

File::Slurp

IO::All

AUTHOR

Top

Sébastien Aperghis-Tramoni, <sebastien at aperghis.net>

BUGS

Top

Please report any bugs or feature requests to bug-file-read at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Read. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Top

You can find documentation for this module with the perldoc command.

    perldoc File::Read

You can also look for information at:

COPYRIGHT & LICENSE

Top

Copyright (C) 2006, 2007 Sébastien Aperghis-Tramoni, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

File-Read documentation Contained in the File-Read distribution. 
package File::Read;
use strict;
use Carp;
use File::Slurp ();
require Exporter;

{   no strict;
    $VERSION = '0.0801';
    @ISA = qw(Exporter);
    @EXPORT = qw(read_file read_files);
}

*read_files = \&read_file;


my %defaults = (
    aggregate       => 1, 
    cmd             => "sudo cat",
    err_mode        => 'croak', 
    skip_comments   => 0, 
    skip_blanks     => 0, 
    to_ascii        => 0, 
);

sub import {
    my ($module, @args) = @_;
    my @new = ();

    # parse arguments
    for my $arg (@args) {
        if (index($arg, '=') >= 0) {
            my ($opt, $val) = split '=', $arg;
            $defaults{$opt} = $val if exists $defaults{$opt};
        }
        else {
            push @new, $arg
        }
    }

    $module->export_to_level(1, $module, @new);
}

sub read_file {
    my %opts = ref $_[0] eq 'HASH' ? %{+shift} : ();
    my @paths = @_;
    my @files = ();

    # check options
    for my $opt (keys %defaults) {
        $opts{$opt} = $defaults{$opt} unless defined $opts{$opt}
    }

    # define error handler
    $opts{err_mode} =~ /^(?:carp|croak|quiet)$/
        or croak "error: Bad value '$opts{err_mode}' for option 'err_mode'";

    my %err_with = (
        'carp'  => \&carp, 
        'croak' => \&croak, 
        'quiet' => sub{}, 
    );
    my $err_sub = $err_with{$opts{err_mode}};

    $err_sub->("error: This function needs at least one path") unless @paths;

    for my $path (@paths) {
        my @lines = ();
        my $error = '';
        
        # first, read the file
        if ($opts{as_root}) {   # ... as root
            my $redir = $opts{err_mode} eq 'quiet' ? '2>&1' : '';
            @lines = `$opts{cmd} $path $redir`;

            if ($?) {
                if (not -f $path) {
                    $! = eval { require Errno; Errno->import(":POSIX"); ENOENT() } ||  2
                }
                elsif (not -r $path) {
                    $! = eval { require Errno; Errno->import(":POSIX"); EACCES() } || 13
                }
                else {
                    $! = 1024
                }
                ($error = "$!") =~ s/ 1024//;
            }
        }
        else {                  # ... as a normal user
            @lines = eval { File::Slurp::read_file($path) };
            $error = $@;
        }

        # if there's an error
        $error and $err_sub->("error: $error");

        # if there's any content at all...
        if (@lines) {
            # ... then do some filtering work if asked so
            @lines = grep { ! /^$/    } @lines  if $opts{skip_blanks};
            @lines = grep { ! /^\s*#/ } @lines  if $opts{skip_comments};
            @lines = map { _to_ascii($_) } @lines  if $opts{to_ascii};
        }

        push @files, $opts{aggregate} ? join('', @lines) : @lines;
    }

    # how to return the content(s)?
    return wantarray ? @files : join '', @files
}


# Text::Unidecode doesn't work on Perl 5.6
my $has_unidecode = eval "require 5.008; require Text::Unidecode; 1"; $@ = "";

sub _to_ascii {
    # use Text::Unidecode if available
    if ($has_unidecode) {
        return Text::Unidecode::unidecode(@_)
    }
    else { # use a simple s///
        my @text = @_;
        map { s/[^\x00-\x7f]//g } @text;
        return @text
    }
}


1; # End of File::Read