[![Actions Status](https://github.com/tecolicom/IO-Factotum/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/tecolicom/IO-Factotum/actions?workflow=test) [![MetaCPAN Release](https://badge.fury.io/pl/IO-Factotum.svg)](https://metacpan.org/release/IO-Factotum) # 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](https://metacpan.org/pod/Command%3A%3ARun): 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](https://metacpan.org/pod/IO%3A%3AFile) 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](https://metacpan.org/pod/IO%3A%3AFactotum%3A%3Askylighting), [IO::Factotum::sourcehighlight](https://metacpan.org/pod/IO%3A%3AFactotum%3A%3Asourcehighlight), [Getopt::EX::Factotum](https://metacpan.org/pod/Getopt%3A%3AEX%3A%3AFactotum) [Command::Run](https://metacpan.org/pod/Command%3A%3ARun) # 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.