File::SmartNL 0.05

File::SmartNL is a slurp text files no matter the New Line (NL) sequence.

SYNOPSIS

#####
# Subroutine Interface
#
use File::SmartNL qw(config fin fout smartnl);

$old_value = config( $option );
$old_value = config( $option => $new_value);
(@all_options) = config( );

$data = smart_nl($data);
$data = fin( $file_name, @options );
$char_count = fout($file_name, $data, @options);

######
# Object Interface
#
use File::SmartNL;

$default_options = File::SmartNL->default(@options);

$old_value = $default_options->config( $option );
$old_value = $default_options->config( $option => $new_value);
(@all_options) = $default_options->config( );

$data = File::SmartNL->smart_nl($data);
$data = File::SmartNL->fin( $file_name, @options );
$char_count = File::SmartNL->fout($file_name, $data, @options);

Generally, if a subroutine will process a list of options, @options, that subroutine will also process an array reference, @options, [@options], or hash reference, %options, {@options}. If a subroutine will process an array reference, @options, [@options], that subroutine will also process a hash reference, %options, {@options}. See the description for a subroutine for details and exceptions.

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), 15, character and a new line when it received a Line Feed (LF), 12 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 New Line (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. By using the fin and fout methods, text files may be freely exchanged between operating systems without any other processing.

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.

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 program module.