NAME

IO::Factotum - read files through a converter chosen by their names

SYNOPSIS

use IO::Factotum;

IO::Factotum::register(
    match   => qr/\.gz$/,
    command => [ 'gzip', '-dc' ],
);

my $fh = IO::Factotum::open_input($file) or die "$file: $!";
while (<$fh>) {
    ...
}

VERSION

Version 0.03

DESCRIPTION

A factotum is a person who does all kinds of work for someone. This module is one for the files a program reads: tell it what to do with which files, and it gives them to the program ready to read. A file is opened through a converter chosen by its name, and the handle gives the output of the converter instead of the content of the file. The file itself is not changed, and the program keeps its name.

Converters are registered with a condition on the file name. A file which no converter takes, and a file whose converter fails, is read as it is.

FUNCTIONS

Nothing is exported.

register(match => condition, command => command)

Register a converter. Converters are tried in the order they were registered, and the first one that matches is used.

condition is a regex which the file name is matched against, or a code reference which is called with the file name and returns true for the file to convert.

command is an array reference in the form of Command::Run: an external command with its arguments, or a code reference with its arguments. The file name is added as the last argument, and what the command writes to the standard output is the converted content, taken byte for byte. The command is not given to the shell.

register(match => qr/\.gz$/, command => [ 'gzip', '-dc' ]);

register(match   => sub { -B $_[0] },
         command => [ \&to_text, '--plain' ]);

The command runs in a process of its own, with the standard error thrown away. It fails by an exit status other than 0; a code reference fails by die. A code reference prints bytes, and the END blocks of the program do not run in its process.

clear()

Remove all the converters.

open_input(file)

Open the file for reading and return the handle, an IO::File object. When a converter matches the name and exits with status 0, the handle reads its output, which is kept in a temporary file without a name. Otherwise the handle reads the file itself.

It returns undef with $! set when the file can not be opened.

The handle has the :raw layer. Set the encoding by binmode:

my $fh = IO::Factotum::open_input($file) or die "$file: $!";
binmode $fh, ':encoding(utf8)';

The name - is the standard input, which is not converted: the handle is that of STDIN itself, with the layers it has.

load(name, ...)

Register the converters of the modules IO::Factotum::name, by calling their setup function. It dies when there is no such module.

IO::Factotum::load('skylighting');
tie_argv()

Tie ARGV, so that <> reads the files of @ARGV by open_input. A program which reads by <> gets the converted content with no change in it:

IO::Factotum::tie_argv();
while (<>) {
    print "$ARGV: $_";
}

@ARGV is looked at when the first line is read, so the options can be taken from it before. As with the plain <>, $ARGV is the name of the file, $. counts the lines of all the files, eof() is true at the end of the last file, close ARGV starts the line numbers again, and the standard input is read when there is no file. <<>> and the -i option of perl are not supported.

SEE ALSO

IO::Factotum::skylighting, IO::Factotum::sourcehighlight, Getopt::EX::Factotum

Command::Run

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright 2026 Kazumasa Utashiro.

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