NAME

Fortran::Format - 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 output facility (input will be available in a future version). 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 begining 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

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.

my $format_string = $format->format()

Returns the format string used by the object.

my $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 example, $format->write(1,[2,3],[4,[5,6[7]],8],9) is exactly the same as $format->write(1,2,3,4,5,6,7,8,9).

SEE ALSO

The Fortran format specification: http://www.fortran.com/fortran/F77_std/rjcnf0001-sh-13.html

AUTHOR

Ivan Tubert <itub@cpan.org>

COPYRIGHT

Copyright (c) 2004 Ivan Tubert. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.