NAME
Text::FixedWidth::Helper - Create or verify samples of fixed-width data
SYNOPSIS
use Text::FixedWidth::Helper qw( d2fw f2dw );
$output = d2fw( $delimited_input_file, $fixed_width_output_file );
$output = f2dw( $fixed_width_output_file, $delimited_input_file );
DESCRIPTION
Preparation and verification of fixed-width data are often part of software development projects. Because fixed-width data is more difficult for humans to visually decode than character-delimited data, it is often difficult to construct and/or verify small sample files. This library provides assistance with that task.
This library assumes that the user of a program can type a plain-text file in a simple format and present it, perhaps via a GUI interface, to a Perl program using the library.
Two variations are possible: delimited-data-to-fixed-width (d2fw), and fixed-width-to-delimited-data (fw2d). In each case, the plain-text file consists of two parts: metadata and sample data. The metadata is a mapping of data field names to the widths of the those fields in the fixed-width record. In each case, the subroutine handling the case is exported by this module on demand only.
Delimited data to fixed width (d2fw)
In d2fw, the sample data consists of at most 3 rows of data in a pipe-delimited format. The user presents the file to the program, which then generates a second file which shows how those records will look in a fixed-width format. Here is an example:
fname 15
mi 1
lname 15
customer_id 10
city 20
state 2
zip 5
Sylvester|J|Gomez|M789294592X|Rochester|NY|14618
Arthur|X|Fridrikkson|M783891590X|Oakland|CA|94601
Kasimir|E|Kristemanaczewski|N389182992X|Buffalo|NY|14214
The user enters one data field per line: a string holding the field's name, followed by one or more whitespace characters, followed by a number which is the field's width in characters.
The user then types one blank line to separate the metadata from the sample data. The user then enters the metadata, one record per line, separating the fields with pipe characters.
When this file is run through the program, a second file is generated that looks like this:
12345678901234567890123456789012345678901234567890123456789012345678
| || | | | |
Sylvester JGomez M789294592Rochester NY14618
Arthur XFridrikkson M783891590Oakland CA94601
Kasimir EKristemanaczewsN389182992Buffalo NY14214
The index row at the top has a length equal to the sum of the sizes of the fixed-width fields. The second, or spacer row, displays pipe characters at the start of each fixed-width field. Finally, the data rows show how the data will be positioned within a fixed-width record. In each field, data is written flush-left and space-padded on the right. Data which exceeds the allotted width for a field is truncated.
While this format is very limited (e.g., it does not permit numerical fields to be flushed-right or zero-padded on the left, it is sufficient for visualization of sample data.
Fixed width data to delimited (fw2d)
In f2dw, the metadata is entered in the same way as in d2fw. The sample data consists of at most 3 rows of fixed-width data. The user presents the file to the program, which then generates a second file which shows how those records will look in a pipe-delimited format. Here is an example:
fname 15
mi 1
lname 15
customer_id 10
city 20
state 2
zip 5
Sylvester JGomez M789294592Rochester NY14618
Arthur XFridrikkson M783891590Oakland CA94601
Kasimir EKristemanaczewsN389182992Buffalo NY14214
Output:
Sylvester|J|Gomez|M789294592X|Rochester|NY|14618
Arthur|X|Fridrikkson|M783891590X|Oakland|CA|94601
Kasimir|E|Kristemanaczews|N389182992X|Buffalo|NY|14214
Note that if data internded for a fixed-width field exceeded the field's allotted width, it is truncated and therefore cannot be fully restored in a delimited format.
SUBROUTINES
d2fw()
Purpose
Given an input file with metadata (as described above) about data fields and sample data in pipe-delimited format, generate an output file which displays how that data will look in fixed-width format.
Arguments
$output = d2fw( $delimited_input_file, $fixed_width_output_file );
List of 2 elements, of which second element is optional: Strings holding name of input file with delimited records and output file with fixed-width records.
If a value is not supplied for the second argument, the name of the output file will default to that of the input file appended by
.out
.Return Value
String holding path to output file.
fw2d()
Purpose
Given an input file with metadata (as described above) about data fields and sample data in fixed-width format, generate an output file which displays how that data will look in pipe-delimited format.
Arguments
$output = f2dw( $fixed_width_output_file, $delimited_input_file );
Return Value
String holding path to output file.
AUTHOR
James E Keenan
CPAN ID: jkeenan
jkeenan@cpan.org
http://thenceforward.net/perl/modules/Text-FixedWidth-Helper
Thanks to Natasha Salam for describing the need for this functionality.
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
perl(1).