NAME

IO::Util - A selection of general-utility IO function

VERSION 1.3

The latest versions changes are reported in the Changes file in this distribution.

INSTALLATION

CPAN

perl -MCPAN -e 'install IO::Util'

Standard installation

From the directory where this file is located, type:

perl Makefile.PL
make
make test
make install

SYNOPSIS

use IO::Util qw(capture slurp uniqid);

# captures the selected file handler
$output_ref = capture { any_printing_code() } ;
# now $$output_ref eq 'something'

sub any_printing_code {
    print 'something'
}


# captures FILEHANDLER
$output_ref = capture { any_special_printing_code() } FILEHEANDLER ;
# now $$output_ref eq 'something'

sub any_special_printing_code {
    print 'to STDOUT';
    print FILEHANDLER 'something'
}


$_ = '/path/to/file' ;
$content_ref = slurp ;

$content_ref = slurp '/path/to/file' ;
$content_ref = slurp \*FILEHANDLER ;

$temporarily_unique_id = Tid()  # like 'Q9MU1N_NVRM'
$locally_unique_id     = Lid()  # like '2MS_Q9MU1N_P5F6'
$universally_unique_id = Uid()  # like 'MGJFSBTK_2MS_Q9MU1N_PWES'

DESCRIPTION

This is a micro-weight module that exports a few functions of general utility in IO operations.

FUNCTIONS

capture { code } [ FILEHANDLER ]

The capture function espects a code block as the first argument and an optional FILEHANDLER as the second argument. If FILEHANDLER is omitted the selected file handler will be used by default (usually STDOUT). The function returns the reference to the captured output.

It executes the code inside the first argument block, and captures the output it sends to the selected file handler (or to a specific file handler). It "hijacks" all the print and printf statements addressed to the captured filehandler, returning the scalar reference to the output. Sort of "print to scalar" function.

Note: This function ties the FILEHANDLER to IO::Util class and unties it after the execution of the code. If FILEHANDLER is already tied to any other class, it just temporary re-bless the tied object to IO::Util class, re-blessing it again to its original class after the execution of the code, thus preserving the original FILEHANDLER configuration.

slurp [ file|FILEHANDLER ]

The slurp function expects a path to a file or an open FILEHANDLER, and returns the reference to the whole file|FILEHANDLER content. If no argument is passed it will use $_ as the argument.

*id ([ options ])

The *id functions (Tid, Lid and Uid) return an unique ID string useful to name temporary files, or use for other purposes.

Tid

This function returns a temporary ID valid for the current process only. Different temporarily-unique strings are granted to be unique for the current process only ($$)

Lid

This function returns a local ID valid for the local host only. Different locally-unique strings are granted to be unique when generated by the same local host

Uid

This function returns an universal ID. Different universally-unique strings are granted to be unique also when generated by different hosts. use this function if you have more than one machine generating the IDs for the same context. This function includes the host IP number in the id algorithm.

They accepts an optional hash of named arguments:

chars

You can specify the set of characters used to generate the uniquid string. You have the following options:

chars => 'base34'

uses [1..9, 'A'..'N', 'P'..'Z']. No lowercase chars, no number 0 no capital 'o'. Useful to avoid human mistakes when the uniqid may be represented by non-electronical means (e.g. communicated by voice or read from paper). This is the default (used if you don't specify any chars option).

chars => 'base62'

Uses [0..9, 'a'..'z', 'A'..'Z']. This option tryes to generate shorter ids.

chars => \@chars

Any reference to an array of arbitrary characters.

separator

The character used to separate group of cheracters in the id. Default '_'.

IP

Applies to Uid only. This option allows to pass the IP number used generating the universally-unique id. Use this option if you know what you are doing.

$ui = Tid()                         # Q9MU1N_NVRM
$ui = Lid()                         # 2MS_Q9MU1N_P5F6
$ui = Uid()                         # MGJFSBTK_2MS_Q9MU1N_PWES
$ui = Uid(separator=>'-')           # MGJFSBTK-2DH-Q9MU6H-7Z1Y
$ui = Tid(chars=>'base62')          # 1czScD_2h0v
$ui = Lid(chars=>'base62')          # rq_1czScD_2jC1
$ui = Uid(chars=>'base62')          # jQaB98R_rq_1czScD_2rqA
$ui = Lid(chars=>[ 0..9, 'A'..'F']) # 9F4_41AF2B34_62E76

IMPORT NOTE: If you really want to use IO::Util::*id from its package without importing any symbol (and only in that case), you must explicitly load Time::HiRes. You must also load Sys::Hostname if you use IO::Util::Uid:

use IO::Util ()   ; # no symbol imported
use Time::HiRes   ; # used by any IO::Util::*id
use Sys::Hostname ; # used by IO::Util::Uid

$uniqid = IO::Util::Uid()

SUPPORT and FEEDBACK

If you need support or if you want just to send me some feedback or request, please use this link: http://perl.4pro.net/?IO::Util.

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

cpanm IO::Util

perl -MCPAN -e shell
install IO::Util