Provided by: libfortran-format-perl_0.90-3_all 
NAME
Fortran::Format - Read and write data according to a standard Fortran 77 FORMAT
SYNOPSYS
use Fortran::Format;
my $f = Fortran::Format->new("2('N: ',I4,2X)");
print $f->write(1 .. 10);
# prints the following:
# N: 1 N: 2
# N: 3 N: 4
# N: 5 N: 6
# N: 7 N: 8
# N: 9 N: 10
# if you don't want to save the format object,
# just chain the calls:
Fortran::Format->new("2('N: ',I4,2X)")->write(1 .. 10);
DESCRIPTION
This is a Perl implementation of the Fortran 77 formatted input/output facility. One
possible use is for producing input files for old Fortran programs, making sure that their
column-oriented records are rigorously correct. Fortran formats may also have some
advantages over "printf" in some cases: it is very easy to output an array, reusing the
format as needed; and the syntax for repeated columns is more concise. Unlike "printf",
for good or ill, Fortran-formatted fields never exceed their desired width. For example,
compare
printf "%3d", 12345; # prints "12345"
print Fortran::Format->new("I3")->write(12345); # prints "***"
This implementation was written in pure Perl, with portability and correctness in mind. It
implements the full ANSI standard for Fortran 77 Formats (or at least it should). It was
not written with speed in mind, so if you need to process millions of records it may not
be what you need.
FORMATS
What follows is a very brief summary of Fortran formats. For a rigorous description, see
the ANSI standard. A format consists of a list of "edit descriptors" or sublists of edit
descriptors. Edit descriptors are separated by commas, but the comma may be omitted if
there's no ambiguity. Spaces and case are ignored, except within strings, so 'i 1 2' is
the same as 'I12'.
Repeatable edit descriptors
The following edit descriptors may be repeated if they are preceded by a number; for
example, '3I4' is the same as 'I4,I4,I4' or 'I4I4I4' or 'I4,2I4'. Lists can be nested by
using parentheses, so '2(I2I3)' is the same as 'I2I3I2I3'. Most descriptors include a
width w. If the width is larger than needed, the output is right-justified. If the width
is not large enough, the entire field is filled with asterisks.
Iw
Iw.m
An integer with width w, and optionally a minimum number of digits m (adding zeroes on
the left if needed).
Fw.d
An fixed precision floating-point number with width w, and d digits after the decimal
point.
Ew.d
Ew.dEe
Dw.d
A number in exponential notation with width w, d digits after the decimal point, and
optionally e digits after the exponent.
Gw.d
Gw.dEe
For values between 0.1 and 10^d, format like F. For values outside that range, format
like E.
Fw Treat the variable as Boolean and output either T or F in a field of width w.
A
Aw Insert a string variable. If the width is not specified, it outputs the entire string.
If the width is smaller than the string, the string is truncated (instead of filling
with asterisks).
Non-repeatable edit descriptors
Most of the following descriptors don't output anything but act as control strings. "Non-
repeatable" descriptors can be repeated only by including them in a repeated list within
parentheses.
'string'
Insert string as is. Quotes may be escaped by doubling them; for example, 'Joe''s'
produces Joe's.
nHstring...
Insert The next n characters after the H as is.
Tc
TLc
TRc Move to position c of the current record (T), or c characters to the left (TL), or c
characters to the right (TR).
nX Move n characters to the right.
/ Move to the beginning of the next record (the next line).
: Stop producing output immediately if there are no more variables left to format.
S
SP
SS Control whether the plus sign is included for positive numbers. Include it for SP, do
not include it for SS, and use the default (do not include) for S.
kP Scaling factor for output in exponential notation. By default, a number such as 1.23
would be written as 0.123E+01. When a scaling factor k is given, the decimal point is
shifted k positions to the left and the exponent is decreased by k orders of
magnitude. With 1P the output would be 1.23E+00.
METHODS
new
my $format = Fortran::Format->new($format_string);
Create a new format object. The string is parsed and compiled when the object is
constructed. Croaks if there is a syntax error.
format
my $format_string = $format->format;
Returns the format string used by the object.
write
$output = $format->write(@data);
Formats the data. This is equivalent to the Fortran "WRITE" statement, except that it
just returns the formatted string. It does not write directly to a file. Data items
may be either scalar or array references (which can be nested).
For matrices (multidimensional arrays), the contents are formatted in column-major
order, same as in Fortran. For example,
my $a = [[1,2],[3,4]];
Fortran::Format->new('4I4')->write($a);
will print
1 3 2 4
or
Fortran::Format->new('2I4')->write($a);
will print
1 3
2 4
This is effectively equivalent to transposing the matrix before printing it in the
row-major order that would be expected by most non-Fortran programmers. This kludge is
necessary to ensure that the output can be read properly by a Fortran program.
Note: this is incompatible with Fortran::Format 0.5x, which simply flattened the
nested arrays, producing the output in row-major order. Also note that the behavior is
undefined if the nested array is not rectangular. For example, [[1],[2,3]] will give
strange results.
read
my (@results) = $format->read($fh, @input_list);
Read data from the filehandle $fh using the format ($fh can also be a string instead
of a filehandle). The input list is a list of array sizes: 1 for simple scalars, n for
simple arrays, and an array reference of dimensions (such as [3,3]) for
multidimensional arrays. For example,
my ($i, $matrix, $j) = $format->read($fh, 1, [3,3], 2)
will read one scalar, followed by a 3x3 matrix, followed by an array with size two.
Note: this method should be called in list context!
The input list is needed because Fortran formats are reused automatically for
subsequent lines until all the variables are read.
Matrices are read in column-major order. See "write" for details.
When reading, it is also possible to specify the length of the resulting string
variables by appending "Alength". For example,
my $s = $format->read($fh, '1A40')
will read the data into a 40-character long string variable (this is regardless of the
field width specified in the format string itself). The string will be padded with
trailing spaces if needed to ensure that it is exactly 40 characters long. This
attempts to emulate Fortran's peculiar string length semantics. It is needed if you
want to read a string, write it back, and be sure that you get the exact same output
that you would get with Fortran.
For example,
my $in = 'hello world';
my $a5 = Fortran::Format->new('A5');
my $a20 = Fortran::Format->new('A20');
my ($s) = $a5->read($in, '1A10');
print $a20->write($s);
# prints " hello "
Notice that 1) $s was padded with five space, to a length of ten characters; 2) the
output is right-justified to a total width of 20 characters.
Now, if we do this instead:
my ($s) = $a5->read($in, '1A3');
print $a20->write($s);
# prints " llo"
Five character are read from the left of the string ("hello"), but only the rightmost
three are copied to the 3-character-long variable ("llo").
VERSION
0.90
SEE ALSO
The Fortran format specification:
<http://www.fortran.com/fortran/F77_std/rjcnf0001-sh-13.html>
AUTHOR
Ivan Tubert-Brohman <itub@cpan.org>
COPYRIGHT
Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as Perl itself.