# perldoc > Text::Reform

yaml
---
type: CommandReference
command: Text::Reform
mode: perldoc
section: 
source: perldoc
---
## Quick Reference
- `form $template, $data, ...` — format text using picture strings
- `tag $specifier, $text` — wrap text in HTML-like tags
- `form {squeeze=>1, fill=>1}, $template, $data` — collapse whitespace
- `form {trim=>1}, $template, $data` — trim trailing whitespace
- `form {filler=>'*'}, $template, $data` — use custom fill character
- `form {interleave=>1}, $template, \@data1, \@data2` — interleave multi-line formats
- `form {break => \&sub}, $template, $data` — custom hyphenation
- `form {cols => [qw(key1 key2)], from => \@hashrefs}, $template` — extract columns from hashrefs

## Name
Manual text wrapping and reformatting

## Synopsis
perl
use Text::Reform;
print form $template, $data, $to, $fill, $it, $with;

use Text::Reform qw( tag );
print tag 'B', $enboldened_text;
## Options

### Field specifiers in picture strings
- `<` — left-justified field (two or more `<` characters)
- `>` — right-justified field (two or more `>`)
- `<<<>>>` — fully-justified field (at least 2 `<` and 2 `>`)
- `^` — centre-justified field (two or more `^`)
- `>>>.<<<<` — numeric field with decimal places
- `[` — left-justified block field (repeats on subsequent lines)
- `]` — right-justified block field (repeats)
- `[[[]]]` — fully-justified block field (repeats)
- `|` — centre-justified block field (repeats)
- `]]].[[[[` — numeric block field (repeats)
- `~` — one-character wide block field
- `\` — escape next character (e.g. `\~` is literal `~`)

### Global formatting options
- `squeeze` — replace multiple spaces/tabs (but not newlines) with single space
- `fill` — squeeze newlines only
- `trim` — remove trailing whitespace from each line
- `filler` — string to fill short lines (default `" "`); can be a hashref with `left` and `right` keys
- `break` — reference to custom hyphenation subroutine (receives string, max length, field width; returns list of two strings)
- `minbreak` — minimum characters to leave on current line before breaking (default 2)
- `interleave` — treat multi-line format as separate lines, interleaving data sources
- `numeric` — `AllPlaces` forces maximal decimal places; `SkipNaN` ignores non-numeric data
- `cols` — hashref with `cols` (array of keys/indices) and `from` (arrayref of hashrefs or arrayrefs) to extract columns from nested data
- `pagenum` — scalar or reference to scalar for page numbering
- `pagelen` — total lines per page (including headers/footers)
- `pagewidth` — total columns per page (default 72)
- `header` — string, subroutine, or hashref for page header
- `footer` — string, subroutine, or hashref for page footer (called with `$pagenum` and `$lastpage` flag)
- `pagefeed` — string, subroutine, or hashref appended after footer (not counted in page length)

## Examples

### Basic formatting with `form`
perl
$count = 1;
$text = "A big long piece of text to be formatted exquisitely";
print form q{
       ||||  <<<<<<<<<<   },
$count, $text,
q{       ----------------   },
q{       ^^^^  ]]]]]]]]]]|  },
$count+11, $text;
### Using `squeeze` and `fill`
perl
$format = "EG> [[[[[[[[[[[[[[[[[[[[[";
$data   = "h  e\t l lo\nworld\t\t\t\t\t";
print form $format, $data;                     # preserves whitespace
print form {squeeze=>1}, $format, $data;       # only newlines preserved
print form {fill=>1}, $format, $data;          # only spaces/tabs preserved
print form {squeeze=>1, fill=>1}, $format, $data; # all whitespace collapsed
### Custom filler character
perl
print form { filler=>'*' },
    "Pay bearer: ^^^^^^^^^^^^^^^^^^^",
    '$123.45';
# prints: Pay bearer: ******$123.45******
### Multi-line block fields with interleaving
perl
my @values   = (1..12);
my @squares  = map { sprintf "%.6g", $_**2    } @values;
my @roots    = map { sprintf "%.6g", sqrt($_) } @values;
my @logs     = map { sprintf "%.6g", log($_)  } @values;
my @inverses = map { sprintf "%.6g", 1/$_     } @values;

print form
"  N      N**2    sqrt(N)      log(N)      1/N",
"=====================================================",
"| [[  |  [[[  |  [[[[[[[[[[ | [[[[[[[[[ | [[[[[[[[[ |",
"-----------------------------------------------------",
\@values, \@squares, \@roots, \@logs, \@inverses;
### Custom hyphenation with `break_at`
perl
use Text::Reform qw( form break_at );
form { break => break_at('-') }
    "[[[[[[[[[[[[[[",
    "The Newton-Raphson methodology";
# returns: "The Newton-\nRaphson\nmethodology"
### Column extraction from hashrefs
perl
@data = (
    { name=>'Tom',   score=>88, time=>15 },
    { name=>'Dick',  score=>54, time=>13 },
    { name=>'Harry', score=>99, time=>18 },
);
print form
'-------------------------------',
'Name             Score     Time',
'-------------------------------',
'[[[[[[[[[[[[[[   |||||     ||||',
{ cols => [qw(name score time)],
  from => \@data
};
### Using `tag` for HTML-like markup
perl
$text = "three lines\nof tagged\ntext";
print tag "A HREF=#nextsection", $text;
# prints: <A HREF=#nextsection>three lines\nof tagged\ntext</A>
## See Also
- [perlform](http://perldoc.perl.org/perlform) — Perl's built-in format mechanism
- [Text::Wrap](http://search.cpan.org/perldoc/Text::Wrap) — simple line wrapping
- [TeX::Hyphen](http://search.cpan.org/perldoc/TeX::Hyphen) — TeX-style hyphenation (used by `break_TeX`)

## Exit Codes
Not applicable (Perl module, no exit codes).