NAME

File::SmartNL - slurp text files no matter the NL sequence

SYNOPSIS

use File::SmartNL

$data          = File::SmartNL->smart_nl($data)
$data          = File::SmartNL->fin( $file_name, {@options} )
$success       = File::SmartNL->fout($file_name, $data, {@options})
$hex_string    = File::SmartNL->hex_dump( $string );

DESCRIPTION

The NL Story

Different operating systems have different sequences for new-lines. Historically when computers where first being born, one of the mainstays was the teletype. The teletype understood ASCII. The teletype was an automated typewriter that would perform a carriage return when it received an ASCII Carriage Return (CR), \015, character and a new line when it received a Line Feed (LF), \012 character.

After some time came Unix. Unix had a tty driver that had a raw mode that sent data unprocessed to a teletype and a cooked mode that performed all kinds of translations and manipulations. Unix stored data internally using a single NL character at the ends of lines. The tty driver in the cooked mode would translate the NL character to a CR,LF sequence. When driving a teletype, the physicall action of performing a carriage return took some time. By always putting the CR before the LF, the teletype would actually still be performing a carriage return when it received the LF and started a line feed.

After some time came DOS. Since the tty driver is actually one of the largest peices of code for UNIX and DOS needed to run in very cramp space, the DOS designers decided, that instead of writing a tailored down tty driver, they would stored a CR,LF in the internal memory. Data internally would be either 'text' data or 'binary' data.

Needless to say, after many years and many operating systems about every conceivable method of storing new lines may be found amoung the various operating systems. This greatly complicates moving files from one operating system to another operating system.

The smart NL methods in this package are designed to take any combination of CR and NL and translate it into the special NL seqeunce used on the site operating system. Thus, by using these methods, the messy problem of moving files between operating systems is mostly hidden in these methods. The one thing not hidden is that the methods need to know if the data is 'text' data or 'binary' data. Normally, the assume the data is 'text' and are overriden by setting the 'binary' option.

The methods in the File::SmartNL package are designed to support the Test::STDmaker and the ExtUtils::SVDmaker packages. These packages generate test scripts and CPAN distribution files that must be portable between operating systems. Since File::SmartNL is a separate package, the methods may be used elsewhere.

Note that 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 may be preferable over the smart_nl method of this package. However, when moving code from one operating system to another system, there will be target operating systems for the near and probable far future that have not upgraded to Perl 5.6.

System Overview

The "File::SmartNL" module is used to support the expansion of the "Test" module by the "Test::Tech" module as follows::

File::Load
   File::SmartNL
       Test::Tech

The "Test::Tech" module is the foundation of the 2167A bundle that includes the Test::STDmaker and ExtUtils::SVDmaker modules. The focus of the "File::SmartNL" is the support of these other modules. 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.

METHODs

fin fout method

$data = File::SmartNL->fin( $file_name, {@options} )
$success = File::SmartNL->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::SmartNL->fout( 'test.pm', $text, {binary => 1} );
==> File::SmartNL->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::SmartNL->fout( 'test.pm', $text, {binary => 1} );
==> File::SmartNL->fin( 'test.pm' );

smart_nl method

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

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 (LF) 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 for the operating system and file type or device. However supplying the option {binary = 1}> directs fout to use binary mode and outputs CRs and LFs raw without any translation.

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::SmartNL->smart_nl( $text )

"line1\nline2\nline3\nline4\n"

REQUIREMENTS

The requirements are coming.

NOTES

AUTHOR

The holder of the copyright and maintainer is

<support@SoftwareDiamonds.com>

COPYRIGHT NOTICE

Copyrighted (c) 2002 Software Diamonds

All Rights Reserved

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:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. 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.

cpanm Tie::Gzip

perl -MCPAN -e shell
install Tie::Gzip