NAME

File::FileUtil - various low-level subroutines that involve files

SYNOPSIS

use File::FileUtil

$data          = smart_nl($data)
$data          = File::FileUtil->fin( $file_name )
$success       = File::FileUtil->fout($file_name, $data)

$package       = File::FileUtil->is_package_loaded($package)
$error         = File::FileUtil->load_package($package)
$errors        = File::FileUtil->pod_errors($package)

$file          = File::FileUtil->fspec2fspec($from_fspec, $to_fspec $fspec_file, [$nofile])
$os_file       = File::FileUtil->fspec2os($fspec, $file, [$no_file])
$fspec_file    = File::FileUtil->os2fspec($fspec, $file, [$no_file])
$pm_file       = File::FileUtil->fspec2pm( $fspec, $file )
$file          = File::FileUtil->pm2file($pm_file)
$file          = File::FileUtil->pm2require($pm_file)

($file, $path) = File::FileUtil->find_in_path($fspec, $file, [\@path])
@INC           = File::FileUtil->test_lib2inc()
@t_path        = File::FileUtil->find_t_paths()

$fh            = File::FileUtil->pm2datah($pm_file)
$data          = File::FileUtil->pm2data($pm_file)

@sub_modules   = File::FileUtil->sub_modules($base_file, @dirs)
$module        = File::FileUtil->is_module($module, @modules)

@globed_files  = File::FileUtil->fspec_glob($fspec, @files)

DESCRIPTION

The methods in the File::FileUtil package are designed to support the Test::STDmaker and the ExtUtils::SVDmaker package. This is the focus and no other focus. Since File::FileUtil is a separate package, the methods may be used elsewhere. In all likehood, any revisions will maintain backwards compatibility with previous revisions. However, support and the performance of the Test::STDmaker and ExtUtils::SVDmaker packages has priority over backwards compatibility.

Many of the methods in this package are use the File::Spec module submodules. The File::Spec uses the current operating system, as specified by the $^O to determine the proper File::Spec submodule to use. Thus, when using File::Spec method, only the submodule for the current operating system is loaded and the File::Spec method directed to the corresponding method of the File::Spec submodule.

Many methods in this package, manipulate file specifications for operating systems other then the current site operating system. The input variable $fspec tells the methods in this package the file specification for file names used as input to the methods. Thus, when using methods in this package up to two, the method may load up to two File::Spec submodules methods and neither of them is a submodule for the current site operating system.

Supported operating system file specifications are as follows:

MacOS
MSWin32
os2
VMS
epoc

Of course since, the variable $^O contains the file specification for the current site operating system, it may be used for the $fspec variable.

fin fout method

$data = File::FileUtil->fin( $file_name )
$success = File::FileUtil->fout($file_name, $data, \%options)

Different operating systems have different new line sequences. Microsoft uses \015\012 for text file, \012 for binary files, Macs \015 and Unix 012. Perl adapts to the operating system and uses \n as a logical new line. The \015 is the ASCII Carraige Return (CR) character and the \012 is the ASCII Line Feed character.

The fin method will translate any CR LF combination into the logical Perl \n character. Normally fout will use the Perl \n character. In other words fout uses the CR LF combination appropriate of the operating system and file type. However supplying the option {binary = 1}> directs fout to use binary mode and output the CR LF raw without any translation.

By using the fin and fout methods, text files may be freely exchanged between operating systems without any other processing. For example,

==> my $text = "=head1 Title Page\n\nSoftware Version Description\n\nfor\n\n";
==> File::FileUtil->fout( 'test.pm', $text, {binary => 1} );
==> File::FileUtil->fin( 'test.pm' );

=head1 Title Page\n\nSoftware Version Description\n\nfor\n\n

==> my $text = "=head1 Title Page\r\n\r\nSoftware Version Description\r\n\r\nfor\r\n\r\n";
==> File::FileUtil->fout( 'test.pm', $text, {binary => 1} );
==> File::FileUtil->fin( 'test.pm' );

find_in_path method

($file_absolute, $path) = File::FileUtil->find_in_path($fspec, $file_relative, [\@path])

The find_in_path method looks for the $file_relative in one of the directories in the @INC path or else the @path in the order listed. The file $file_relative may include relative directories. When find_in_path finds the file, it returns the abolute file $file_absolute and the directory $path where it found $file_relative. The input variable $fspec is the file specification for $file_relative.

For example, running on Microsoft windows with C:\Perl\Site\t in the @INC path, and the file Test\TestUtil\TestUtil.t present

==> File::FileUtil->find_in_path('Unix', 'Test/TestUtil/TestUtil.t')

C:\Perl\Site\t\Test\TestUtil\TestUtil.t
C:\Perl\Site\t

find_t_paths method

This method operates on the assumption that the test files are a subtree to a directory named t and the t directories are on the same level as the last directory of each directory tree specified in @INC. If this assumption is not true, this method most likely will not behave very well.

The find_t_paths method returns the directory trees in @INC with the last directory changed to t.

For example,

==> @INC

myperl/lib
perl/site/lib
perl/lib 

=> File::FileUtil->find_t_paths()

myperl/t
perl/site/t
perl/t

fspec_glob method

@globed_files = File::FileUtil->fspec_glob($fspec, @files)

The fspec_glob method BSD globs each of the files in @files where the file specification for each of the files is $fspec.

For example, running under the Microsoft operating system, that contains a directory Drivers with file Generators.pm Driver.pm IO.pm under the current directory

=> File::FileUtil->fspec_glob('Unix','Drivers/G*.pm')

Drivers\Generate.pm

=> File::FileUtil->fspec_glob('MSWin32','Drivers\\I*.pm') 

Drivers\IO.pm

fspec2fspec method

$to_file = File::FileUtil->fspec2fspec($from_fspec, $to_fspec $from_file, $nofile)

THe fspec2fspec method translate the file specification for $from_file from the $from_fspec to the $to_fpsce. Supplying anything for $nofile, tells the fspec2fspec method that $from_file is a directory tree; otherwise, it is a file.

For example,

=> File::FileUtil->fspec2fspec( 'Unix', 'MSWin32', 'Test/TestUtil.pm') 

Test\\TestUtil.pm

fspec2os method

$os_file = File::FileUtil->fspec2os($fspec, $file, $no_file)

The fspec2os method translates a file specification, $file, from the current operating system file specification to the $fspec file specification. Supplying anything for $nofile, tells the fspec2fspec method that $from_file is a directory tree; otherwise, it is a file.

For example, running under the Microsoft operating system:

==> File::FileUtil->fspec2os( 'Unix', 'Test/TestUtil.pm')

Test\\TestUtil.pm

fspec2pm method

$pm_file = File::FileUtil->fspec2pm( $fspec, $file )

The fspec2pm method translates a filespecification $file in the $fspce format to the Perl module formate.

For example,

==> File::FileUtil->fspec2pm('Unix', 'Test/TestUtil.pm')

File::FileUtil

is_module method

$driver = Test::TestUtil->is_module($module, @modules)

The is_module method determines if $module is present in @modules. The detemination is case insensitive and only the leading characters are needed.

For example,

==> @drivers

(Driver
Generate
IO)

==> Test::TestUtil->is_driver('dri', @drivers )

Driver

is_package_loaded method

$package = File::FileUtil->is_package_loaded($package)

The is_package_loaded method determines if a package vocabulary is present.

For example, if File::Basename is not loaded

==> File::FileUtil->is_package_loaded('File::Basename')

''

load_package method

$error = File::FileUtil->load_package($package)

The load_package method loads attempts to load a package. The return is any $error that occurred during the load attempt. The load_package will check that the package vocabulary is present. Altough it is a Perl convention, the package name(s) in a package file do not have to be the same as the package file name. For these few cases, this method will load the packages in the file, but fail the package vocabulary test.

For example,

==> File::FileUtil->load_package( 'File::Basename' )
''

os2fspec method

$file = File::FileUtil->os2fspec($fspec, $os_file, $no_file)

For example, running under the Microsoft operating system:

==> File::FileUtil->os2fspec( 'Unix', 'Test\\TestUtil.pm')

Test/TestUtil.pm

pm2datah method

$fh = File::FileUtil->pm2datah($pm_file)

The pm2datah method will open the $pm_file and return a handle positioned at the first /[\012\015]__DATA__/ token occuring in the file. This function is very similar to the DATA file handle that Perl creates when loading a module file with the /[\012\015]__DATA__/ token. The differences is that pm2datah works whether or not the file module is loaded. The method does not close the file handle. Unlike the DATA file handle, which cannot be reused after the module data is read the first time, the pm2datah will always return an opened file handle, the first time, the second time, any time.

CAUTION:

If the /[\012\015]__DATA__/ token appears in the code section, say in a comment, or as a value assigned to a variable, the pm2datah method will misbehave.

For example,

==> my $fh = File::FileUtil->pm2datah('File::FileUtil::Drivers::Driver')
==> join '',<$fh>;

\=head1 Title Page

 Software Version Description

 for

 ${TITLE}

 Revision: ${REVISION}

 Version: ${VERSION}

 Date: ${DATE}

 Prepared for: ${END_USER} 

 Prepared by:  ${AUTHOR}

 Copyright: ${COPYRIGHT}

 Classification: ${CLASSIFICATION}

\=cut

EOF

pm2data method

$data = File::FileUtil->pm2data($pm_file)

The pm2data uses the pm2datah to return all the data in a $pm_file form the __DATA__ token to the end of the file.

For example,

==> my $fh = File::FileUtil->pm2data('File::FileUtil::Drivers::Driver')

\=head1 Title Page

 Software Version Description

 for

 ${TITLE}

 Revision: ${REVISION}

 Version: ${VERSION}

 Date: ${DATE}

 Prepared for: ${END_USER} 

 Prepared by:  ${AUTHOR}

 Copyright: ${COPYRIGHT}

 Classification: ${CLASSIFICATION}

\=cut

EOF

pm2file method

($file, $path) = File::FileUtil->pm2file($pm_file)

The pm2file method returns the absolute file and the directory in @INC for a the program module $pm_file.

For example, running on a Microsoft operating system, if File::FileUtil is in the C:\myperl\t directory, and C:\myperl\t is in the @INC path,

==> File::FileUtil->pm2file( 'File::FileUtil');

(C:\myperl\t\Test\TestUtil.pm
C:\myperl\t)

pod_errors method

$errors = File::FileUtil->pod_errors($package)

The pod_errors uses Pod::Checker to analyze a package and returns the number of $errors

For example,

==> File::FileUtil->pod_errors( 'File::Basename')

0

pm2require

$file = File::FileUtil->pm2require($pm_file)

The pm2require method returns the file suitable for use in a Perl require given the $pm_file file.

For example, running under Microsoft Windows

==> File::FileUtil->pm2require( 'File::FileUtil')

File\FileUtil.pm

smart_nl method

$data = File::FileUtil->smart_nl( $data  )

Perl 5.6 introduced a built-in smart nl functionality as an IO discipline :crlf. See Programming Perl by Larry Wall, Tom Christiansen and Jon Orwant, page 754, Chapter 29: Functions, open function. For Perl 5.6 or above, the :crlf IO discipline my be preferable over the smart_nl method of this package.

sub_modules method

@sub_modules = File::FileUtil->sub_modules($base_file, @dirs)

Placing sub modules in their own private directory provides a method to add a new sub_modules without changing the using module. The parent object finds all the available sub_modules by listing the modules in the sub_module directory using the sub_modules method.

The sub_modules method takes as its input a $base_file, a file in the parent directory, and a list of subdirectories, @dirs, relative to the $base_file. It returns the a list, @sub_modules, of *.pm file names stripped of the extension .pm in the identified directory.

For example, if the subdirectory Drivers to the file __FILE__ contains the files Driver.pm Generate.pm IO.pm, then

==> join ',', sort File::FileUtil->sub_modules( __FILE__, 'Drivers' );

'Driver, Generate, IO'

NOTES

AUTHOR

The holder of the copyright and maintainer is

<support@SoftwareDiamonds.com>

COPYRIGHT NOTICE

BINDING REQUIREMENTS NOTICE

Binding requirements are indexed with the pharse 'shall[dd]' where dd is an unique number for each header section. This conforms to standard federal government practices, 490A ("3.2.3.6" in STD490A). In accordance with the License, Software Diamonds is not liable for any requirement, binding or otherwise.

LICENSE

Software Diamonds permits the redistribution and use in source and binary forms, with or without modification, provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

SOFTWARE DIAMONDS, http::www.softwarediamonds.com, PROVIDES THIS SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE OF THIS SOFTWARE, EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE POSSIBILITY OF SUCH DAMAGE.

To install File::FileUtil, copy and paste the appropriate command in to your terminal.

cpanm

cpanm File::FileUtil

CPAN shell

perl -MCPAN -e shell
install File::FileUtil

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

fin fout method

find_in_path method

find_t_paths method

fspec_glob method

fspec2fspec method

fspec2os method

fspec2pm method

is_module method

is_package_loaded method

load_package method

os2fspec method

pm2datah method

pm2data method

pm2file method

pod_errors method

pm2require

smart_nl method

sub_modules method

NOTES

AUTHOR

COPYRIGHT NOTICE

BINDING REQUIREMENTS NOTICE

LICENSE

Module Install Instructions