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)

$result        = File::FileUtil->hex_dump( $string );

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.

2167A Bundle

The File::FileUtil module was orginally developed to support the US DOD 2167A Bundle. The original functional interface modules in the US DOD 2167A bundle are shown in the below dependency tree

File::FileUtil 
  Test::STD::Scrub
    Test::Tech
       DataPort::FileType::FormDB DataPort::DataFile Test::STD::STDutil
           Test::STDmaker ExtUtils::SVDmaker

Note the File::FileUtil, Test::STD::STDutil Test::STD::Scrub program modules breaks up the Test::TestUtil program module and Test::TestUtil has disappeared.

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

hex_dump method

Sometimes the eyes need to see the actual bytes of a file content. The hex_dump method provides these eyes. For example,

==> $text
1..8 todo 2 5;
# OS            : MSWin32
# Perl          : 5.6.1
# Local Time    : Thu Jun 19 23:49:54 2003
# GMT Time      : Fri Jun 20 03:49:54 2003 GMT
# Number Storage: string
# Test::Tech    : 1.06
# Test          : 1.15
# Data::Dumper  : 2.102
# =cut 
# Pass test
ok 1
EOF

==> File::FileUtil->hex_dump( $text )

312e2e3820746f646f203220353b0a23204f5320
20202020202020202020203a204d5357696e3332
0a23205065726c202020202020202020203a2035
2e362e310a23204c6f63616c2054696d65202020
203a20546875204a756e2031392032333a34393a
353420323030330a2320474d542054696d652020
202020203a20467269204a756e2032302030333a
34393a3534203230303320474d540a23204e756d
6265722053746f726167653a20737472696e670a
2320546573743a3a54656368202020203a20312e
30360a232054657374202020202020202020203a
20312e31350a2320446174613a3a44756d706572
20203a20322e3130320a23203d637574200a2320
5061737320746573740a6f6b20310a

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.

An example of the smart_nl method follows:

==> $text

"line1\015\012line2\012\015line3\012line4\015"

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

"line1\nline2\nline3\nline4\n"

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.

SEE_ALSO:

Modules with end-user functional interfaces relating to US DOD 2167A automation are as follows:

Test::STDmaker
ExtUtils::SVDmaker
DataPort::FileType::FormDB
DataPort::DataFile
Test::Tech
Test
Data::Dumper
Test::STD::Scrub
Test::STD::STDutil
File::FileUtil

The design modules for Test::STDmaker have no other conceivable use then to support the Test::STDmaker functional interface. The Test::STDmaker design module are as follows:

Test::STD::Check
Test::STD::FileGen
Test::STD::STD2167
Test::STD::STDgen
Test::STDtype::Demo
Test::STDtype::STD
Test::STDtype::Verify

Some US DOD 2167A Software Development Standard, DIDs and other related documents that complement the US DOD 2167A automation bundle are as follows:

US DOD Software Development Standard
US DOD Specification Practices
Computer Operation Manual (COM) DID
Computer Programming Manual (CPM) DID)
Computer Resources Integrated Support Document (CRISD) DID
Computer System Operator's Manual (CSOM) DID
Database Design Description (DBDD) DID
Engineering Change Proposal (ECP) DID
Firmware support Manual (FSM) DID
Interface Design Document (IDD) DID
Interface Requirements Specification (IRS) DID
Operation Concept Description (OCD) DID
Specification Change Notice (SCN) DID
Software Design Specification (SDD) DID
Software Development Plan (SDP) DID
Software Input and Output Manual (SIOM) DID
Software Installation Plan (SIP) DID
Software Programmer's Manual (SPM) DID
Software Product Specification (SPS) DID
Software Requirements Specification (SRS) DID
System or Segment Design Document (SSDD) DID
System or Subsystem Specification (SSS) DID
Software Test Description (STD) DID
Software Test Plan (STP) DID
Software Test Report (STR) DID
Software Transition Plan (STrP) DID
Software User Manual (SUM) DID
Software Version Description (SVD) DID
Version Description Document (VDD) DID

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1393:: =back doesn't take any parameters, but you said =back =for html

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

2167A Bundle

fin fout method

find_in_path method

find_t_paths method

fspec_glob method

fspec2fspec method

fspec2os method

fspec2pm method

hex_dump 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

SEE_ALSO:

Module Install Instructions