.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::Read 3pm" .TH File::Read 3pm "2015-06-05" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::Read \- Unique interface for reading one or more files .SH "VERSION" .IX Header "VERSION" Version 0.0801 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::Read; \& \& # read a file \& $file = read_file($path); \& \& # read several files \& @files = read_files(@paths); \& \& # aggregate several files \& $file = read_files(@paths); \& \& # read a file as root, skip comments and blank lines \& $file = read_file({ as_root => 1, skip_comments => 1, skip_blanks => 1 }, $path); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module mainly proposes functions for reading one or more files, with different options. See below for more details and examples. .SS "Rationale" .IX Subsection "Rationale" This module was created to address a quite specific need: reading many files, some as a normal user and others as root, and eventually do a little more processing, all while being at the same time compatible with Perl 5.004. \f(CW\*(C`File::Slurp\*(C'\fR addresses the first point, but not the others, hence the creation of \f(CW\*(C`File::Read\*(C'\fR. If you don't need reading files as root or the post-processing features, then it's faster to directly use \f(CW\*(C`File::Slurp\*(C'\fR. .SH "EXPORT" .IX Header "EXPORT" By default, this module exports all the functions documented afterhand. It also recognizes import options. For example .PP .Vb 1 \& use File::Read \*(Aqerr_mode=quiet\*(Aq; .Ve .PP set \f(CW\*(C`read_file()\*(C'\fR's \f(CW\*(C`err_mode\*(C'\fR option default value to \f(CW"quiet"\fR. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .IP "\fB\f(BIread_file()\fB\fR" 4 .IX Item "read_file()" Read the files given in argument and return their content, as as list, one element per file, when called in list context, or as one big chunk of text when called in scalar context. Options can be set using a hashref as first parameter. .Sp \&\fBOptions\fR .RS 4 .IP "\(bu" 4 \&\f(CW\*(C`aggregate\*(C'\fR controls how the function returns the content of the files that were successfully read. By default, When set to true (default), the function returns the content as a scalar; when set to false, the content is returned as a list. .IP "\(bu" 4 \&\f(CW\*(C`as_root\*(C'\fR tells the function to read the given file(s) as root using the command indicated by the \f(CW\*(C`cmd\*(C'\fR option. .IP "\(bu" 4 \&\f(CW\*(C`cmd\*(C'\fR sets the shell command used for reading files as root. Default is \f(CW"sudo cat"\fR. Therefore you need \fB\f(BIsudo\fB\|(8)\fR and \fB\f(BIcat\fB\|(1)\fR on your system, and \fI\fIsudoers\fI\|(5)\fR must be set so the user can execute \fB\f(BIcat\fB\|(1)\fR. .IP "\(bu" 4 \&\f(CW\*(C`err_mode\*(C'\fR controls how the function behaves when an error occurs. Available values are \f(CW"croak"\fR, \f(CW"carp"\fR and \f(CW"quiet"\fR. Default value is \f(CW"croak"\fR. .IP "\(bu" 4 \&\f(CW\*(C`skip_comments\*(C'\fR tells the functions to remove all comment lines from the read files. .IP "\(bu" 4 \&\f(CW\*(C`skip_blanks\*(C'\fR tells the functions to remove all blank lines from the read files. .IP "\(bu" 4 \&\f(CW\*(C`to_ascii\*(C'\fR tells the functions to convert the text to US-ASCII using \&\f(CW\*(C`Text::Unidecode\*(C'\fR. If this module is not available, non-ASCII data are deleted. .RE .RS 4 .Sp \&\fBExamples\fR .Sp Just read a file: .Sp .Vb 1 \& my $file = read_file($path); .Ve .Sp Read a file, returning it as list: .Sp .Vb 1 \& my @file = read_file({ aggregate => 0 }, $path); .Ve .Sp Read a file, skipping comments: .Sp .Vb 1 \& my $file = read_file({ skip_comments => 1 }, $path); .Ve .Sp Read several files, skipping blank lines and comments: .Sp .Vb 1 \& my @files = read_file({ skip_comments => 1, skip_blanks => 1 }, @paths); .Ve .RE .IP "\fB\f(BIread_files()\fB\fR" 4 .IX Item "read_files()" \&\f(CW\*(C`read_files()\*(C'\fR is just an alias for \f(CW\*(C`read_file()\*(C'\fR so that it look more sane when reading several files. .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .ie n .IP """Bad value \*(Aq%s\*(Aq for option \*(Aq%s\*(Aq""" 4 .el .IP "\f(CWBad value \*(Aq%s\*(Aq for option \*(Aq%s\*(Aq\fR" 4 .IX Item "Bad value %s for option %s" \&\fB(E)\fR You gave a bad value for the indicated option. Please check the documentation for the valid values. .ie n .IP """This function needs at least one path""" 4 .el .IP "\f(CWThis function needs at least one path\fR" 4 .IX Item "This function needs at least one path" \&\fB(E)\fR You called a function without giving it argument. .SH "SEE ALSO" .IX Header "SEE ALSO" File::Slurp .PP IO::All .SH "AUTHOR" .IX Header "AUTHOR" Se\*'bastien Aperghis-Tramoni, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-file\-read at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc File::Read .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation \- .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings \- .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker \- .IP "\(bu" 4 Search \s-1CPAN \- \&\s0 .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright (C) 2006, 2007 Se\*'bastien Aperghis-Tramoni, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.