---
name: formline
signature: 'formline PICTURE, LIST'
since: 5.0
status: documented
categories: ["Misc"]
---

```{index} single: formline; Perl built-in
```

*[Misc](../perlfunc-by-category)*

# formline

Format a list of values into a picture string and append the result to
the format accumulator [`$^A`](../perlvar).

`formline` is the low-level engine behind Perl's [`format`](format) /
[`write`](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`](../perlvar) accumulator (also known as `$ACCUMULATOR` under
`use English`). Every call to [`write`](write) flushes [`$^A`](../perlvar) to
the associated filehandle and clears it; outside of [`write`](write), you
manage [`$^A`](../perlvar) yourself — read it for the formatted text, then
reset it to `""` before the next call.

`PICTURE` is the same mini-language that [`format`](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

```perl
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`](../perlvar). If you need the
text as a value, read [`$^A`](../perlvar) after the call and then clear it:

```perl
$^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`](../perlvar) — the **format accumulator**. `formline` appends to it;
  it is never cleared automatically. Also known as `$ACCUMULATOR` under
  `use English`.
- [`$:`](../perlvar) — 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:

```perl
$^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`:

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

An `swrite` helper — `formline` is to [`write`](write) what
[`sprintf`](sprintf) is to [`printf`](printf):

```perl
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:

```perl
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:

```perl
$^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`](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`](../perlvar) 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:

  ```perl
  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`](format)
  declaration.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`write`](write) — drives one or more `formline` calls from a named
  [`format`](format) and flushes [`$^A`](../perlvar) to a filehandle
- [`format`](format) — declaration syntax for the picture/value pairs
  that [`write`](write) feeds into `formline`
- [`sprintf`](sprintf) — the other "format into a string" primitive;
  use `sprintf` for `printf`-style `%`-directives, `formline` for
  fixed-width report columns and fill-mode text blocks
- [`$^A`](../perlvar) — the accumulator `formline` writes into; read it
  for the result, clear it before the next logical use
- [`$:`](../perlvar) — characters that fill-mode fields (`^*`, `^<<<`)
  may break on