Text::FixedWidth::Helper - Create or verify samples of fixed-width data
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 );
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.
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.
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
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.
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.
$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
String holding path to output file.
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.
$output = f2dw( $fixed_width_output_file, $delimited_input_file );
String holding path to output file.
James E Keenan CPAN ID: jkeenan email@example.com http://thenceforward.net/perl/modules/Text-FixedWidth-Helper
Thanks to Natasha Salam for describing the need for this functionality.
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.