formline#

Format a list of values into a picture string and append the result to the format accumulator $^A.

formline is the low-level engine behind Perl’s format / write report mechanism. It takes a PICTURE string describing field widths and alignment, interpolates the values from LIST into those fields, and appends the resulting text to the global $^A accumulator (also known as $ACCUMULATOR under use English). Every call to write flushes $^A to the associated filehandle and clears it; outside of write, you manage $^A yourself — read it for the formatted text, then reset it to "" before the next call.

PICTURE is the same mini-language that format uses: @<<<< for a left-justified text field, @>>>> for right-justified, @|||| for centered, @####.## for a right-justified numeric field with a decimal point, @* for an unbounded multi-line text field, and ^<<< (and friends) for the fill-mode field that consumes its scalar argument incrementally. See perldoc perlform for the full picture vocabulary.

Synopsis#

formline PICTURE, LIST
formline $picture, @values

What you get back#

formline always returns 1. The useful output is the side effect: the formatted text is appended to $^A. If you need the text as a value, read $^A after the call and then clear it:

$^A = "";
formline '@<<<<<<<<  @>>>>', $name, $score;
my $line = $^A;
$^A = "";

Because the result goes to an accumulator, consecutive formline calls build up multi-line output without any intermediate join.

Global state it touches#

$^A — the format accumulator. formline appends to it; it is never cleared automatically. Also known as $ACCUMULATOR under use English.
$: — the set of characters on which fill-mode fields (^*, ^<<<) are allowed to break. Defaults to " \n-". Also known as $FORMAT_LINE_BREAK_CHARACTERS under use English.
LC_NUMERIC locale — if use locale is in effect when the picture is compiled, the decimal point character in numeric fields (@###.##) follows the locale.
Fill-mode fields (^…) mutate their scalar arguments in place, chopping off the portion that was consumed so the next formline call picks up where the previous one left off. Pass a copy if you need the original preserved.

Examples#

Build one formatted line and read it back:

$^A = "";
formline '@<<<<<<<<  @>>>>>', "widget", 42;
print $^A, "\n";            # "widget       42\n"
$^A = "";

Build a multi-line block in one call — the picture may contain newlines, and each line of the picture consumes its own values from LIST:

$^A = "";
formline <<'END', "Alice", 30, "Bob", 25;
@<<<<<<<<<<  @###
@<<<<<<<<<<  @###
END
print $^A;                  # "Alice         30\nBob           25\n"
$^A = "";

An swrite helper — formline is to write what sprintf is to printf:

sub swrite {
    my $picture = shift;
    local $^A = "";
    formline $picture, @_;
    return $^A;
}

my $row = swrite '@<<<<<<<<  @>>>>', "total", 1234;

Fill-mode field consumes its scalar across repeated calls — note that $text shrinks each time:

my $text = "the quick brown fox jumps over the lazy dog";
$^A = "";
formline '^<<<<<<<<<<<<<<<', $text;
formline "\n";
formline '^<<<<<<<<<<<<<<<', $text;
print $^A;                  # two lines, word-broken on spaces
$^A = "";

Numeric field with decimal places and overflow filling — a value that does not fit is rendered as # characters:

$^A = "";
formline '@##.##', 3.14159;
formline "\n";
formline '@##.##', 9999.9;  # overflow
print $^A;                  # "  3.14\n######\n"
$^A = "";

Edge cases#

Quoting the picture: inside double quotes, @ introduces an array interpolation. Write pictures as single-quoted strings or heredocs with a quoted terminator (<<'END') to keep @ literal. The classic trap: formline "@<<<<<<<", $name interpolates @< before formline ever sees the string.
Newlines in the picture: formline does not care how many newlines PICTURE contains. The ~ (suppress-if-all-empty) and ~~ (repeat-until-exhausted) tokens treat the whole picture as one logical line, so a record format with ~~ typically needs one formline per physical line. A format declaration splits a multi-line form into one formline call per output line; when calling formline directly, you make that split yourself.
Accumulator is not cleared: the most common mistake is forgetting to reset $^A between logical uses. Appending is the defined behaviour, not a bug. Use local $^A = ""; inside helpers.
Field count vs. value count: surplus values in LIST are silently ignored; missing values render as empty (regular field) or blanked (special ^ numeric field).
undef in a regular field stringifies to the empty string under use warnings and triggers a uninitialized warning. A special field (^###) blanks the whole field on undef without warning.
Using a format scalar — capturing write output: opening a filehandle onto a scalar reference is often easier than driving formline manually:
```
open my $fh, ">", \my $out or die $!;
format FH =
@<<<<<<<<  @>>>>
$name,     $score
.
$~ = "FH";
select((select($fh), $~ = "FH")[0]);
write $fh;
```
Reach for formline directly when you want the picture-to-string path without involving a filehandle or a named format declaration.

Differences from upstream#

Fully compatible with upstream Perl 5.42.