NAME

Launcher::Cascade::FileReader - a class to read a file or the output of a command, locally or through ssh.

SYNOPSIS

    use Launcher::Cascade::FileReader;

    my $f = new Launcher::Cascade::FileReader
        -path => q{date '+%H:%M:%S' |},
        -host => q{host.domain},
    ;
    my $fh = $f->open();
    while ( <$fh> ) {
        print; # what time is it over there?
    }
    close $fh;

DESCRIPTION

The purpose of this class is to provide a file handle that gives access to a file or the output of a command. If a host() is provided, the file or the command are fetched through ssh, otherwise, run locally. The class takes care of escaping quote characters as appropriate.

Attributes

path

The path to the file to open. If the last character is a vertical bar (or "pipe", ASCII 0x7c), path() will be considered a command and run. The standard ouput will be available in the filehandle returned by method open().

host

If set, the path() will be considered remote, i.e., the command actually run by method open() will be a ssh host .... Either the content of the remote file or the standard output of the remote command will be made available in the filehandle returned by open().

user

The remote user to login as. When omitted, ssh(1) will login with the same user as the local user.

filehandle

The filehandle as returned by method open().

context

An array reference containing the line that matched the pattern given to method search(), plus lines of context if either of context_after() or context_before() are not null.

context_after

context_before

Determines the number of lines to include in context() after, respectively before, a pattern has been matched. The number of lines in context() should be context_before() + 1 + context_after(), unless the end of the file was reached too soon to provide enough context after the match.

Both attributes default to 0, so the default context contains only one line, the one that matched the pattern.

Methods

open

Opens the file or command specified by attribute path(), possible over ssh on remote host(), and returns a filehandle make its content (for a file) or standard output (for a command) available for reading.

close

Closes the filehandle.

search PATTERN, PATTERN, ...

Search the filehandle for PATTERNs and returns the index of the one that matched (starting with 0), or -1 if the end of file was reached before any pattern could be matched.

PATTERNs should be regular expressions, possibly pre-compiled with the qr// operator.

After a search(), the context() attribute contains an arrayref containing the line that matched, plus a number of context lines before and after the match, as defined by the context_after() and context_before() attributes.

The filehandle is closed after the search().

BUGS AND CAVEATS

• ssh(1) must be in one of directories listed in the PATH environment variable.

• there is nothing provided for non-interactive logging. The DSA or RSA key pairs should be properly generated and ssh configured to avoid interactive login.

SEE ALSO

Launcher::Cascade.

AUTHOR

Cédric Bouvier <cbouvi@cpan.org>

COPYRIGHT & LICENSE

Copyright (C) 2006 Cédric Bouvier, All Rights Reserved.

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