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 theENDblocks 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
undefwith$!set when the file can not be opened.The handle has the
:rawlayer. Set the encoding bybinmode: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 ofSTDINitself, with the layers it has. -
load(name, ...)
Register the converters of the modules
IO::Factotum::name, by calling theirsetupfunction. It dies when there is no such module.IO::Factotum::load('skylighting'); -
tie_argv()
Tie
ARGV, so that<>reads the files of@ARGVbyopen_input. A program which reads by<>gets the converted content with no change in it:IO::Factotum::tie_argv(); while (<>) { print "$ARGV: $_"; }@ARGVis looked at when the first line is read, so the options can be taken from it before. As with the plain<>,$ARGVis the name of the file,$.counts the lines of all the files,eof()is true at the end of the last file,close ARGVstarts the line numbers again, and the standard input is read when there is no file.<<>>and the-ioption of perl are not supported.
SEE ALSO
IO::Factotum::skylighting, IO::Factotum::sourcehighlight, Getopt::EX::Factotum
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.