Perl6::Form(3pm)

Formatting jargon

Format

A string that is used as a template for the creation of text. It will contain zero or more fields, usually with some literal characters and whitespace between them.

Text

A string that is created by replacing the fields of a format with specific data values. For example, the string that a call to "form" returns.

Field

A fixed-width slot within a format string, into which data will be formatted.

Data

A string or numeric value (or an array of such values) that is interpolated into a format, in order to fill in a particular field.

Single-line field

A field that interpolates only as much of its corresponding data value as will fit inside it within a single line of text.

Block field

A field that interpolates all of its corresponding data value, over a series of text lines – as many as necessary – producing a text block.

Text block

The column of newline-separated text lines. A text block is produced when data is formatted into a block field that is too small to contain the data in a single line

Column

The amount of space on an output device required to display one single-width character. One character will occupy one column in most cases, the most obvious exceptions being CJK double-width characters.

Return values

When called in a scalar or list context, "form" returns a string containing the complete formatted text:

    my $formatted_text = form $format, *@data;
    @texts = ( form($format, *@data1), form($format, *@data2) );  # 2 elems

When called in a void context, "form" dies, bitterly pointing out how useless that is to format something and then just throw the result away.

Justifying fields

The most commonly used fields are those that justify their contents: to the left, to the right, to the left and right, or towards the centre.

Left-justified and right-justified fields extract from their data source the largest substring that will fit inside them, push that string to the left or right as appropriate, and then pad the string out to the required field width with spaces (or the nominated fill character).

Centred fields ("{>>>><<<<}" and "{]]]][[[[}") likewise extract as much data as possible, and then pad both sides of it with (near) equal numbers of spaces. If the amount of padding required is not evenly divisible by 2, the one extra space is added after the data.

There is a second syntax for centred fields – a tip-o'-the-hat to Perl 5 formats: "{|||||||||}" and "{IIIIIIII}". This variant also makes it easier to specify centering fields that are only three columns wide: "{|}" and "{I}".

Note, however, that the behaviour of centering fields specified this way is exactly the same in every respect as the bracket-based versions, so we're free to use whichever we prefer.

Fully justified fields ("{<<<<>>>>}" and "{[[[[]]]]}") extract a maximal substring and then distribute any padding as evenly as possible into the existing whitespace gaps in that data. For example:

    print form '({<<<<<<<<<>>>>>>>>>>>})',
               'A fellow of infinite jest, of most excellent fancy';

would print:

    (A fellow  of  infinite)

A fully-justified block field ("{[[[[]]]]}") does the same across multiple lines, except that the very last line is always left-justified. Hence, this:

    print form '({[[[[[[[[]]]]]]]})',
               'All the world's a stage, And all the men and women merely players.'

would print:

    (All the world's a)
    (stage,  And   all)
    (the men and women)
    (merely players.  )

By the way, with both centred fields ("{>>>><<<}") and fully justified fields ("{<<<>>>>}"), the actual number of left vs right arrows is irrelevant, so long as there is at least one of each.

Non-numeric data

You're probably wondering what happens if we try to format a number that's too large for the available places (as 123456.78 would be in the above format). Whereas "sprintf" would extend a numeric field to accommodate the number, "form" insists on preserving the specified layout; in particular, the position of the decimal point. But it obviously can't just cut off the extra high-order digits; that would change the value:

    Thy score be: 23456.78

So, instead, it indicates that the number doesn't fit by filling the field with octothorpes (the way many spreadsheets do):

    Thy score be: #####.###

It's also possible that someone (not you, of course!) might attempt to pass a numeric field some data that isn't numeric at all:

    my @mixed_data = (1, 2, "three", {4=>5}, "6", "7-Up");
    print form 'Thy score be: {]]]].[[}',
                              \@mixed_data;

Unlike Perl itself, "form" doesn't autoconvert non-numeric values. Instead it marks them with another special string, by filling the field with question-marks:

    Thy score be:     1.0
    Thy score be:     2.0
    Thy score be: ?????.???
    Thy score be: ?????.???
    Thy score be:     6.0
    Thy score be: ?????.???

Note that strings per se aren't a problem – "form" will happily convert strings that contain valid numbers, such as "6" in the above example. But it does reject strings that contain anything else besides a number (even when Perl itself would successfully convert the number – as it would for "7-Up" above).

Those who'd prefer Perl's usual, more laissez-faire attitude to numerical conversion can just pre-numerify the values themselves:

    print form 'Thy score be: {]]]].[[}',
                              [map {$_+0} @mixed_data];

This version would print something like:

    Thy score be:     1.0
    Thy score be:     2.0
    Thy score be:     0.0
    Thy score be:     1.0
    Thy score be:     6.0
    Thy score be:     7.0

Decimal markers

Of course, not everyone uses a dot for their decimal point. The other main contender is the comma, and naturally "form" supports that as well. If we specify a numeric field with a comma between the brackets:

    @les_nums = (1, 1.2, 1.23, 11.234, 111.235, 1.0001);
    print form 'Votre score est: {]]]],[[}',
                                 \@les_nums;

the call prints:

    Votre score est:     1,0
    Votre score est:     1,2
    Votre score est:     1,23
    Votre score est:    11,234
    Votre score est:   111,235
    Votre score est:     1,000

In fact, "form" is extremely flexible about the characters we're allowed to use as a decimal marker: anything except an angle- or square bracket or a plus sign is acceptable.

As a bonus, "form" allows us to use the specified decimal marker in the data as well as in the format. So this works too:

    @les_nums = ("1", "1,2", "1,23", "11,234", "111,235", "1,0001");
    print form 'Vos score est: {]]]],[[}',
                               \@les_nums;

Negative numbers

Negative numbers work as expected, with the minus sign taking up one column of the field's allotted span:

    @nums = ( 1, -1.2,  1.23, -11.234,  111.235, -12345.67);
    print form 'Thy score be: {]]]].[[}',
                              \@nums;

This would print:

    Thy score be:     1.0
    Thy score be:    -1.2
    Thy score be:     1.23
    Thy score be:   -11.234
    Thy score be:   111.235
    Thy score be: #####.###

However, "form" can also format numbers so that the minus sign trails the number. To do that we simple put an explicit minus sign inside the field specification, at the end:

    print form 'Thy score be: {]]]].[[-}',
                              \@nums;

which would then print:

    Thy score be:     1.0
    Thy score be:     1.2-
    Thy score be:     1.23
    Thy score be:    11.234-
    Thy score be:   111.235
    Thy score be: 12345.67-

"form" also understands the common financial usage where negative numbers are represented as positive numbers in parentheses. Once again, we draw an abstract picture of what we want (by putting parens at either end of the field specification):

    print form 'Thy dividend be: {(]]]].[[)}',
                                 \@nums;

and "form" obliges:

    Thy dividend be:      1.0
    Thy dividend be:     (1.2)
    Thy dividend be:      1.23
    Thy dividend be:    (11.234)
    Thy dividend be:    111.235
    Thy dividend be: (12345.67)

Note that the parens have to go inside the field's braces. Otherwise, they're just literal parts of the format string.

Thousands separators

If we add so-called "thousands separators" inside a numeric field at the usual places, "form" includes them appropriately in its output. It can handle the five major formatting conventions:

    my @nums = (0, 1, 1.1, 1.23, 4567.89, 34567.89, 234567.89, 1234567.89);
    print form
        'Brittannic      Continental     Subcontinental   Tyrolean        Asiatic',
        '_____________   _____________   ______________   _____________   _____________',
        '{],]]],]]].[}   {].]]].]]],[}    {]],]],]]].[}   {]']]]']]],[}   {]]]],]]]].[}',
         \@nums,         \@nums,          \@nums,         \@nums,         \@nums;

to produce:

    Brittannic      Continental     Subcontinental   Tyrolean        Asiatic
    _____________   _____________   ______________   _____________   _____________
             0.0             0,0              0.0             0,0             0.0
             1.0             1,0              1.0             1,0             1.0
             1.1             1,1              1.1             1,1             1.1
             1.23            1,23             1.23            1,23            1.23
         4,567.89        4.567,89         4,567.89        4'567,89         4567.89
        34,567.89       34.567,89        34,567.89       34'567,89       3,4567.89
       234,567.89      234.567,89      2,34,567.89      234'567,89      23,4567.89
     1,234,567.89    1.234.567,89     12,34,567.89    1'234'567,89     123,4567.89

It also accepts a space character as a "thousands separator" (with, of course, any decimal marker we might like):

    print form
        'Hyperspatial',
        '_____________',
        '{] ]]] ]]]:[}',
         \@nums;

to produce:

    Hyperspatial
    _____________
             0:0
             1:0
             1:1
             1:23
         4 567:89
        34 567:89
       234 567:89
     1 234 567:89

You can also put separators in a regular "{">>>>>>}> or "{]]]]]]]}" field, to print integers with (say) commas:

    print form
        'Integral',
        '___________',
        '{]],]]],]]}',
         \@nums;

which produces:

    Integral
    ___________
              0
              1
              1
              1
          4,568
         34,568
        234,568
      1,234,568

Notice that the numbers are still rounded; in this case, to integers.

Line-breaking

Whenever a field is passed more data than it can accommodate in a single line, "form" is forced to "break" that data somewhere.

If the field in question is W columns wide, "form" first squeezes any whitespace (as specified by the user's "ws" option) and then looks at the next W columns of the string.

"form"'s breaking algorithm then searches for a newline, a carriage return, any other whitespace character, or a hyphen. If it finds a newline or carriage return within the first W columns, it immediately breaks the data string at that point. Otherwise it locates the last whitespace or hyphen in the first W columns and breaks the string immediately after that space or hyphen. If it can't find anywhere suitable to break the string, it breaks it at the (W-1)th column and appends a hyphen.

So, for example:

    $data = "You can play no part but Pyramus;\nfor Pyramus is a sweet-faced man";
    print form "|{[[[[[}|",
                 $data;

prints:

    |You can|
    |play no|
    |part   |
    |but    |
    |Pyramu-|
    |s;     |
    |for    |
    |Pyramus|
    |is a   |
    |sweet- |
    |faced  |
    |man    |

Note the line-breaks after can (at a whitespace), part (after a whitespace), sweet- (after a hyphen), and s; (at a newline). Note too that Pyramus; doesn't fit in the field, so it has to be chopped in two and a hyphen inserted.

Of course, this particular style of line-breaking may not be suitable to all applications, and we might prefer that "form" use some other algorithm. For example, if "form" used the TeX breaking algorithm it would have broken Pyramus; less clumsily, yielding:

    |You can|
    |play no|
    |part   |
    |but    |
    |Pyra-  |
    |mus;   |
    |for    |
    |Pyramus|
    |is a   |
    |sweet- |
    |faced  |
    |man    |

To support different line-breaking strategies "form" provides the "break" option. The "break" option's value must be a closure/subroutine, which will then be called whenever a data string needs to be broken to fit a particular field width.

That subroutine is passed three arguments: a reference to the data string itself, an integer specifying how wide the field is, and a regex indicating which (if any) characters are to be squeezed. It is expected to return a list of two values: a string which is taken as the "broken" text for the field, and a boolean value indicating whether or not any data remains after the break (so "form" knows when to stop breaking the data string). The subroutine is also expected to update the ".pos" of the data string to point immediately after the break it has imposed.

For example, if we always wanted to break at the exact width of the field (with no hyphens), we could do that with:

    sub break_width {
        my ($data_ref, $width, $ws) = @_;
        for ($$data_ref) {
            # Treat any squeezed or vertical whitespace as a single character
            # (since they'll subsequently be squeezed to a single space)
            my $single_char = qr{ $ws | [\n\r]+ | . }
            # Give up if there are no more characters to grab...
            return ("", 0) unless m/\G (single_char{1,$width}) /gcx;
            # Squeeze the resultant substring...
            (my $result = $1) =~ s/ $ws | [\n\r] / /gx;
            # Check for any more data still to come...
            my $more = m/\G (?= .* \S) /gcx;
            # Return the squeezed substring and the "more" indicator...
            return ($result, $more);
        }
    }
    print form
        {break=>\&break_width},
        '|{[[[[[}|',
          $data;

producing:

    |You can|
    |play no|
    |part bu|
    |t Pyram|
    |us; for|
    |Pyramus|
    |is a sw|
    |eet-fac|
    |ed man |

Or we might prefer to break on every single whitespace-separated word:

    sub break_word {
        my ($data_ref, $width, $ws) = @_;
        for ($$data_ref) {
            # Locate the next word (no longer than $width cols)
            my $found = m/\G \s* (\S{1,$width}) /gcx;
            # Fail if no more words...
            return ("", 0) unless $found;
            my $word = $1;
            # Check for any more data still to come...
            my bool $more = m/\G (?= .* \S) /gcx;
            # Otherwise, return broken text and "more" flag...
            return ($word, $more);
        }
    }
    print form
        {break=>\&break_word},
        '|{[[[[[}|',
          $data;

producing:

    |You    |
    |can    |
    |play   |
    |no     |
    |part   |
    |but    |
    |Pyramus|
    |;      |
    |for    |
    |Pyramus|
    |is     |
    |a      |
    |sweet-f|
    |aced   |
    |man    |

We'll see yet another application of user-defined breaking when we discuss user-defined fields.

Interleaving data

There are (at least) three schools of thought when it comes to setting out a call to "form" that uses more than one format. The "traditional" way (i.e. the way Perl 5 formats do it) is to interleave each format string with a line containing the data it is to interpolate, with each datum aligned directly under the field into which it is to be fitted. Like so:

    print form
        'Name:                                                  ',
        '  {[[[[[[[[[[[[}                                       ',
           $name,
        '                  Biography:                           ',
        'Status:             {<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<}',
                             $bio,
        '  {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
           $status,
        '                    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        'Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        '  {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
           $comments;

This approach has the advantage that it self-documents: to know what a particular field is supposed to contain, we merely need to look down one line.

It does, however, break up the "abstract picture" that the formats portray, which can make it more difficult to envisage what the final formatted text will look like. So some people prefer to put all the data to the right of the formats:

    print form
        'Name:                                                  ',
        '  {[[[[[[[[[[[[}                                       ', $name,
        '                  Biography:                           ',
        'Status:             {<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<}', $bio,
        '  {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}', $status,
        '                    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        'Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        '  {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}', $comments;

And that's perfectly acceptable too.

Sometimes, however, the data to be interpolated doesn't come neatly pre-packaged in separate variables that are easy to intersperse between the formats. For example, the data might be a list returned by a subroutine call ("get_info($next_person)") or might be stored in a hash ( @person{qw( name biog stat comm )} ). In such cases it's a nuisance to have to tease that data out into separate variables (or hash accesses) and then sprinkle them through the formats:

    print form
        'Name:                                                  ',
        '  {[[[[[[[[[[[[}                                       ',$person{name},
        '                  Biography:                           ',
        'Status:             {<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<}',$person{biog},
        '  {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',$person{stat},
        '                    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        'Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',
        '  {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}',$person{comm};

So "form" has an option that lets us put a single, multi-line format at the start of the argument list, place all the data together after it, and have that data automatically interleaved as necessary. Not surprisingly, that option is: "interleave". It's normally used in conjunction with a heredoc, since that's the easiest way to specify a multi-line string in Perl:

    print form {interleave=>1}, <<'EOFORMAT',
    Name:
      {[[[[[[[[[[[[}
                      Biography:
    Status:             {<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<}
      {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    EOFORMAT
         @person{qw( name biog stat comm )};

When "interleave" is in effect, "form" grabs the first string argument it's passed and breaks that argument up into individual lines. It treats those individual lines as a series of distinct formats and grabs as many of the remaining arguments as are required to provide data for each format.

Multi-line formats

It's important to point out that, even when we're using "form"'s default non-interleaving behaviour, it's still okay to use a format that spans multiple lines. There is however a significant (and useful) difference in behaviour between the two alternatives.

The normal behaviour of "form" is to take each format string, fill in each field in the format with a substring from the corresponding data source, and then repeat that process until all the data sources have been exhausted. Which means that a multi-line format like this:

    print form
         <<'EOFORMAT',
    Name:    {[[[[[[[[[[[[[[[}   Role: {[[[[[[[[[[}
    Address: {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}
    _______________________________________________
    EOFORMAT
         \@names, \@roles, \@addresses;

would normally produce this:

    Name:    King Lear           Role: Protagonist
    Address: The Cliffs, Dover
    _______________________________________________
    Name:    The Three Witches   Role: Plot devices
    Address: Dismal Forest, Scotland
    _______________________________________________
    Name:    Iago                Role: Villain
    Address: Casa d'Otello, Venezia
    _______________________________________________

because the entire three-line format is repeatedly filled in as a single unit, line-by-line and datum-by-datum.

On the other hand, if we tell "form" that it's supposed to automatically interleave the data coming after the format, like so:

    print form {interleave=>1},
         <<'EOFORMAT',
    Name:    {[[[[[[[[[[[[[[[}   Role: {[[[[[[[[[[}
    Address: {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}
    _______________________________________________
    EOFORMAT
         \@names, \@roles, \@addresses;

then the call produces:

    Name:    King Lear           Role: Protagonist
    Name:    The Three Witches   Role: Plot devices
    Name:    Iago                Role: Villain
    Address: The Cliffs, Dover
    Address: Dismal Forest, Scotland
    Address: Casa d'Otello, Venezia
    _______________________________________________

because that second version is really equivalent to:

    print form
         'Name:    {[[[[[[[[[[[[[[[}   Role: {[[[[[[[[[[}',
                   \@names,                  \@roles,
         'Address: {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}',
                   \@addresses,
         '_______________________________________________';

That's not much use in this particular example, but it was exactly what was needed for the biography example earlier. It's just a matter of choosing the right type of data placement to achieve the particular effect we want.

Layout control

As we saw earlier, with follow-on fields and overflow fields, "form" is perfectly happy to have several fields in a single format that are all fed by the same data source. For example:

    print form
        '{[[[[[[[[]]]]]]]]]]:}   {:[[[[[[[]]]]]]]]]]:}   {:[[[[[[[[]]]]]]]]]]}',
             $soliloquy,             $soliloquy,              $soliloquy;

In fact, that kind of format is particularly useful for creating multi-column outputs (like newspaper columns, for example).

But a small quandry arises. In what order should "form" fill in these fields? Should the data be formatted down the page, filling each column completely before starting the next (and therefore potentially leaving the last column "short"):

    Now is the winter  of   torious  wreaths;   /   front; / And now, in-
    our discontent / Made   Our bruised arms hung   stead of mounting ba-
    glorious  summer   by   up for  monuments;  /   rded steeds / To fri-
    this sun of  York;  /   Our stern alarums ch-   ght the souls of fea-
    And  all  the  clouds   anged to merry meeti-   rful  adversaries,  /
    that lour'd upon  our   ngs, /  Our  dreadful   He capers nimbly in a
    house / In  the  deep   marches to delightful   lady's chamber.
    bosom  of  the  ocean   measures.   /   Grim-
    buried. / Now are our   visaged war hath smo-
    brows bound with vic-   oth'd  his   wrinkled

Or should the data be run line-by-line across all three columns (the way a Perl 5 "format" does it), filling one line completely before starting the next:

    Now is the winter  of   our discontent / Made   glorious  summer   by
    this sun of  York;  /   And  all  the  clouds   that lour'd upon  our
    house / In  the  deep   bosom  of  the  ocean   buried. / Now are our
    brows bound with vic-   torious  wreaths;   /   Our bruised arms hung
    up for  monuments;  /   Our stern alarums ch-   anged to merry meeti-
    ngs, /  Our  dreadful   marches to delightful   measures.   /   Grim-
    visaged war hath smo-   oth'd  his   wrinkled   front; / And now, in-
    stead of mounting ba-   rded steeds / To fri-   ght the souls of fea-
    rful  adversaries,  /   He capers nimbly in a   lady's chamber.

Or should the text run down the columns, but in such a way as to leave those columns as evenly balanced in length as possible:

    Now is the winter  of   brows bound with vic-   visaged war hath smo-
    our discontent / Made   torious  wreaths;   /   oth'd  his   wrinkled
    glorious  summer   by   Our bruised arms hung   front; / And now, in-
    this sun of  York;  /   up for  monuments;  /   stead of mounting ba-
    And  all  the  clouds   Our stern alarums ch-   rded steeds / To fri-
    that lour'd upon  our   anged to merry meeti-   ght the souls of fea-
    house / In  the  deep   ngs, /  Our  dreadful   rful  adversaries,  /
    bosom  of  the  ocean   marches to delightful   He capers nimbly in a
    buried. / Now are our   measures.   /   Grim-   lady's chamber.

Well, of course, there's no "right" answer to that; it depends entirely on what kind of effect we're trying to achieve.

The first approach (i.e. lay out the text down each column first) works well if we're formatting a news-column, or a report, or a description of some kind. The second (i.e. lay out the text across each line first), is excellent for putting diagrams or call-outs in the middle of a piece of text (as we did for Mrs Miggins). The third approach (i.e. lay out the data downwards but balance the columns) is best for presenting a single list of data in multiple columns – like "ls" does.

So we need an option with which to tell "form" which of these useful alternatives we want for a particular format. That option is named "layout" and can take one of three string values: "down", "across", or "balanced". So, for example, to produce three versions of Richard III's famous monologue in the order shown above, we'd use:

    print form {layout=>"down"},
        '{[[[[[[[[]]]]]]]]]]:}   {:[[[[[[[]]]]]]]]]]:}   {:[[[[[[[[]]]]]]]]]]}',
             $soliloquy,             $soliloquy,              $soliloquy;

then:

    print form {layout=>"across"},
        '{[[[[[[[[]]]]]]]]]]:}   {:[[[[[[[]]]]]]]]]]:}   {:[[[[[[[[]]]]]]]]]]}',
             $soliloquy,             $soliloquy,              $soliloquy;

then:

    print form {layout=>"balanced"},
        '{[[[[[[[[]]]]]]]]]]:}   {:[[[[[[[]]]]]]]]]]:}   {:[[[[[[[[]]]]]]]]]]}',
             $soliloquy,             $soliloquy,              $soliloquy;

By the way, the default value for the "layout" option is "balanced" since formatting regular columns of data is more common than formatting news or advertising inserts.

Tabular layout

The "layout" option controls one other form of inter-column formatting: tabular layout.

So far, all the examples of tables we've created (for example, our normalized scores) lined up nicely. But that was only because each item in each row happened to take the same number of lines (typically just one). So, a table generator like this:

    my @play = map {"$_\r"}  ( "Othello", "Richard III", "Hamlet"   );
    my @name = map {"$_\r"}  ( "Iago",    "Henry",       "Claudius" );
    print form
         'Character       Appears in  ',
         '____________    ____________',
         '{[[[[[[[[[[}    {[[[[[[[[[[}',
          \@name,         \@play;

correctly produces:

    Character       Appears in
    ____________    ____________
    Iago            Othello
    Henry           Richard III
    Claudius        Hamlet

Note that we appended "\r" to each element to add an extra newline after each entry in the table. We can't use "\n" to specify a line-break within an array element, because "form" uses "\n" as an "end-of-element" marker. So, to allow line breaks within a single element of an array datum, "form" treats "\r" as "end-of-line-but-not-end-of-element" (somewhat like Perl 5's "format" does).

However, if we were to use the full titles for each character and each play:

    my @play = map {"$_\r"}  ( "Othello, The Moor of Venice",
                               "The Life and Death of King Richard III",
                               "Hamlet, Prince of Denmark",
                             );
    my @name = map {"$_\r"}  ( "Iago",
                               "Henry,\rEarl of Richmond",
                               "Claudius,\rKing of Denmark",
                             );

the same formatter would produce:

    Character       Appears in
    ____________    ____________
    Iago            Othello, The
                    Moor of
    Henry,          Venice
    Earl of
    Richmond        The Life and
                    Death of
    Claudius,       King Richard
    King of         III
    Denmark
                    Hamlet,
                    Prince of
                    Denmark

The problem is that the two block fields we're using just grab all the data from each array and format it independently into each column. Usually that's fine because the columns are independent (as we've previously seen).

But in a table, the data in each column specifically relates to data in other columns, so corresponding elements from the column's data arrays ought to remain vertically aligned. To achieve this, we simply tell "form" that the data in the various columns should be laid out like a table:

    print form {layout=>"tabular"},
         'Character       Appears in  ',
         '____________    ____________',
         '{[[[[[[[[[[}    {[[[[[[[[[[}',
          \@name,         \@play;

which then produces the desired result:

    Character       Appears in
    ____________    ____________
    Iago            Othello, The
                    Moor of
                    Venice
    Henry,          The Life and
    Earl of         Death of
    Richmond        King Richard
                    III
    Claudius,       Hamlet,
    King of         Prince of
    Denmark         Denmark

Declarative field widths

When specific field widths are required (perhaps by some design document or data formatting protocol) laying out wide fields can be error-prone. For example, most people can't visually distinguish between a 52-column field and a 53-column field and are therefore forced to manually verify the width of the corresponding field specifier in some way.

To catch mistakes of this kind, fields can be specified with an embedded integer in parentheses (with optional whitespace inside the parens). For example:

    print form '{[[[( 15 )[[[[} {<<<<<(17)<<<<<<}  {]]](14)]]].[[}',
               $problem,        $ID,               $description;

The integer in the parentheses acts like a checksum. Its value must be identical to the actual width of the field (including the delimiting braces and the embedded integer itself). Otherwise an exception is thrown. For instance, running the above example produces the error message:

    Inconsistent width for field 3.
    Specified as '{]]](14)]]].[[}' but actual width is 15
    in call to &form at demo.pl line 1

Numeric fields can be given a decimal checksum, which then also specifies their number of decimal places.

    print form
        '{[[[( 15 )[[[[} {<<<<<(17)<<<<<<}  {]](14.2)]].[}',
        $problem,        $ID,               $description;

Note that the digits before the decimal still indicate the total width of the field. So the "{]](14.2)]].[}" field in the above example means must be 14 columns wide, including 2 decimal places, in exactly the same way as a "%14.2f" specifier would in a "sprintf".

Imperative field widths

Of course, in some instances it would be much more convenient if we could simply tell "form" that we want a particular field to be a particular width, instead of having to explicitly show it.

So there's another type of integer field annotation that, instead of acting like a checksum, acts like an...err..."tellsum". That is, we can tell "form" to ignore a field's physical width and instead insist that it be magically expanded (or shrunk) to a nominated width. Such a field is said to have an imperative width. The integer specifying the imperative width is placed in curly braces instead of parens.

For example, the format in the previous example could be specified imperatively as:

    print form
        '{[{15}[} {<{17}<<}  {]]]]{14.2}]]]].[[}',
        $problem, $ID,       $description;

Note that the actual width of any field becomes irrelevant if it contains an imperative width. The field will be condensed or expanded to the specified width, with subsequent fields pushed left or right accordingly.

Distributive field widths

A special form of imperative width field is the starred field. A starred field is one that contains an imperative width specification in which the number is replaced by a single asterisk.

The width of a starred field is not fixed, but rather is computed during formatting. That width is whatever is required to cause the entire format to fill the current page width of the format (by default, 78 columns). Consider, for example:

    print form
        '{]]]]]]]]]]]]]]} {]]].[[}  {[[{*}[[}  ',
         \@names,         \@scores, \@comments;

The width of the starred comment field in this case is 49 columns – the default page width of 78 columns minus the 29 columns consumed by the fixed-width portions of the format (including the other two fields).

If a format contains two or more starred fields, the available space is shared equally between them. So, for example, to create two equal columns (say, to compare the contents of two files), we might use:

    use Perl6::Slurp;
    print form
         '{[[[[{*}[[[[}   {[[[[{*}[[[[}',
          slurp($file1),  slurp($file2);

(And, yes, Perl 6 does have a built-in "slurp" function that takes a filename, opens the file, reads in the entire contents, and returns them as a single string. For more details see the Perl6::Slurp module – now on the CPAN.)

There is one special case for starred fields: a starred verbatim field:

    {""""{*}""""}

It acts like any other starred field, growing according to the available space, except that it will never grow any wider than the widest line of the data it is formatting. For example, whereas a regular starred field:

    print form
         '| {[[{*}[[} |',
            $monologue;

expands to the full page width:

    | Now is the winter of our discontent                           |
    | Made glorious summer by this sun of York;                     |
    | And all the clouds that lour'd upon our house                 |
    | In the deep bosom of the ocean buried.                        |
    | Now are our brows bound with victorious wreaths               |
    | Our bruised arms hung up for monuments;                       |
    | Our stern alarums changed to merry meetings,                  |
    | Our dreadful marches to delightful measures.                  |
    | Grim-visaged war hath smooth'd his wrinkled front;            |
    | And now, instead of mounting barded steeds                    |
    | To fright the souls of fearful adversaries,                   |
    | He capers nimbly in a lady's chamber.                         |

a starred verbatim field:

    print form
         '| {""{*}""} |',
            $monologue;

only expands as much as is strictly necessary to accommodate the data:

    | Now is the winter of our discontent                |
    | Made glorious summer by this sun of York;          |
    | And all the clouds that lour'd upon our house      |
    | In the deep bosom of the ocean buried.             |
    | Now are our brows bound with victorious wreaths;   |
    | Our bruised arms hung up for monuments;            |
    | Our stern alarums changed to merry meetings,       |
    | Our dreadful marches to delightful measures.       |
    | Grim-visaged war hath smooth'd his wrinkled front; |
    | And now, instead of mounting barded steeds         |
    | To fright the souls of fearful adversaries,        |
    | He capers nimbly in a lady's chamber.              |

Extensible fields

By now you've probably noticed that there is quite a large overlap between the functionality of "form" and that of "(s)printf". For example, the call:

    for (@procs) {
        print form
            '{>>>}  {<<<<<<<(20)<<<<<<<}  {>>>>>>}  {>>.}%',
            $_->{pid}, $_->{cmd},         $_->{time}, $_->{cpu};
    }

has approximately the same effect as the call:

    for (@procs) {
        printf "%5d  %-20s  %8s  %5.1f%%\n",
               $_->{pid}, $_->{cmd}, $_->{time}, $_->{cpu};
    }

One is more WYSIWYG, the other more concise, but (placed in a suitable loop), they would both print out lines like these:

     2461  vi -ii henry           0:55.83   11.6%
     2395  ex cathedra            0:06.59    3.5%
     2439  head anne.boleyn       0:00.18    0.1%
     2581  dig -short grave       0:01.04    0.0%

There is, however, a crucial difference between these two formatting facilities; one that only shows up when one of our processes runs over 99 hours. For example, suppose our browser has been running continuously for a few months (or, more precisely, for 1214:23.75 hours). Then the calls to "printf" would print:

     2461  vi -ii henry           0:55.83   11.6%
     2395  ex cathedra            0:06.59    3.5%
    27384  lynx www.divorce.com  1214:23.75    0.8%
     2439  head anne.boleyn       0:00.18    0.1%
     2581  dig -short grave       0:01.04    0.0%

whilst the calls to "form" would print:

     2461  vi -ii henry           0:55.83   11.6%
     2395  ex cathedra            0:06.59    3.5%
    27384  lynx www.divorce.com  1214:23-    0.8%
     2439  head anne.boleyn       0:00.18    0.1%
     2581  dig -short grave       0:01.04    0.0%

In other words, field widths in a "printf" represent minimal spacing (even if that throws off the overall layout), whereas field widths in a "form" represent guaranteed spacing (even if that truncates some of the data).

Of course, in a situation like this – where we knew that the data might not fit and we didn't want it truncated – we could use a block field instead:

    for (@procs) {
        print form
            '{>>>}  {<<<<<<<(19)<<<<<<}  {]]]]]]}  {>>.%}',
            $_->{pid}, $_->{cmd},        $_->{time},  $_->{cpu};
    }

in which case we'd get:

     2461  vi -ii henry           0:55.83   11.6%
     2395  ex cathedra            0:06.59    3.5%
    27384  lynx www.divorce.com  1214:23-    0.8%
                                      .75
     2439  head anne.boleyn       0:00.18    0.1%
     2581  dig -short grave       0:01.04    0.0%

That preserves the data, but the results are still ugly, and it also requires some fancy footwork – making the percentage sign part of the field specification, as if it were a currency marker – to make the last field work correctly. In other words: it's a kludge. The sad truth is that sometimes variable-width fields are a better solution.

So "form" provides them too. Any field specification may include a plus sign ("+") anywhere between its braces, in which case it specifies an extensible field: a field whose width is minimal, rather than absolute. So, in the above example, our call to "form" should actually look like this:

    for (@procs) {
        print form
            '{>>>}  {<<<<<<<(20)<<<<<<<}  {>>>>>+}  {>>.}%',
            $_->{pid}, $_->{cmd},        $_->{time},  $_->{cpu};
    }

and would produce this:

     2461  vi -ii henry           0:55.83   11.6%
     2395  ex cathedra            0:06.59    3.5%
    27384  lynx www.divorce.com  1214:23.75    0.8%
     2439  head anne.boleyn       0:00.18    0.1%
     2581  dig -short grave       0:01.04    0.0%

just like "printf" does.

Likewise, if we thought the command names might exceed 20 columns we could let that field stretch too:

    for (@procs) {
        print form
            '{>>>}  {<<<<<<<(20+)<<<<<<}  {>>>>>+}  {>>.}%',
            $_->{pid}, $_->{cmd},        $_->{time},  $_->{cpu};
    }

Note that the field width specifier would still warn us if the field's "picture" was not exactly 20 columns wide, but the resulting field would nevertheless stretch as necessary to accommodate longer data.

Whitespace squeezing

When a field is being filled in, whitespace is normally left as-is (except for justification, and wrapping of lines in block fields). However, this behaviour can be altered by specifying a whitespace squeezing strategy. Squeezing replaces those substrings of the data that match a specified pattern (for example: "/\s+/"), substituting a single space character.

If we don't want the default (non-)squeezing strategy we can use the "ws" option specify the particular pattern that is to be used for squeezing:

    print form
        {ws=>qr/\h+/},           # squeeze any horizontal whitespace
        $format1, \@data1,
        {ws=>qr/$comment|\s+/},  # now squeeze comments or whitespace
        $format2, \@data2;

For example, suppose we have a eulogy generator:

    sub eulogize ($who, $to, $blaming) {...}

that (rather poorly) drops the appropriate names into a pre-formatted template, to produce strings like:

    Friends,   Romans  , countrymen, lend me your ears;
    I come to bury    Caesar   , not to praise him.
    The evil that men do lives after them;
    The good is oft interred with their bones;
    So let it be with    Caesar    . The noble    Brutus
    Hath told you     Caesar     was ambitious:
    If it were so, it was a grievous fault,
    And grievously hath    Caesar    answer'd it.

If we interpolate that string, with its extra spaces and its embedded newlines, into a "form" field:

    print form
         '| {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[} |',
            eulogize('Caesar', 'Romans', 'Brutus');

we'd get:

    | Friends,   Romans  , countrymen, lend me   |
    | your ears;                                 |
    | I come to bury    Caesar   , not to praise |
    | him.                                       |
    | The evil that men do lives after them;     |
    | The good is oft interred with their bones; |
    | So let it be with    Caesar    . The noble |
    | Brutus                                     |
    | Hath told you     Caesar     was           |
    | ambitious:                                 |
    | If it were so, it was a grievous fault,    |
    | And grievously hath    Caesar    answer'd  |
    | it.                                        |

Note that the extra spaces and the embedded newlines are preserved in the resulting text.

But, if we told "form" to squeeze all whitespaces:

    print form {ws => qr/\s+/},
         '| {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[} |',
            eulogize('Caesar', 'Romans', 'Brutus');

we'd get:

    | Friends, Romans , countrymen, lend me your |
    | ears; I come to bury Caesar , not to       |
    | praise him. The evil that men do lives     |
    | after them; The good is oft interred with  |
    | their bones; So let it be with Caesar .    |
    | The noble Brutus Hath told you Caesar was  |
    | ambitious: If it were so, it was a         |
    | grievous fault, And grievously hath Caesar |
    | answer'd it.                               |

with each sequence of characters that match "/\s+/" being reduced to a single space.

On the other hand, if we wanted to preserve the newlines and squeeze only horizontal whitespace, that would be:

    print form {ws => qr/[ \t]+/},
         '| {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[} |',
            eulogize('Caesar', 'Romans', 'Brutus');

which produces:

    | Friends, Romans , countrymen, lend me your |
    | ears;                                      |
    | I come to bury Caesar , not to praise him. |
    | The evil that men do lives after them;     |
    | The good is oft interred with their bones; |
    | So let it be with Caesar . The noble       |
    | Brutus                                     |
    | Hath told you Caesar was ambitious:        |
    | If it were so, it was a grievous fault,    |
    | And grievously hath Caesar answer'd it.    |

Of course, for this particular text, none of these solutions is entirely satisfactory since squeezing the whitespaces to a single space still leaves a single space in places like "Caesar ." and "Romans ,".

To remove those blemishes we need to take advantage of a more sophisticated aspect of "form"'s whitespace squeezing behaviour. Namely that, when squeezing whitespace using a particular pattern, "form" detects if that pattern captures anything and doesn't squeeze the captured items.

More precisely, if the squeeze pattern matches but doesn't capture, "form" simply replaces the entire match with a single space character. But if the squeeze pattern does capture, "form" doesn't insert a space character, but instead replaces the entire match with the concatenation of the captured substrings.

That means we can completely eliminate any whitespace before a punctuation character with:

    print form {ws => qr/[ \t]+ ([.!?,:;])?/},
         '| {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[} |',
            eulogize('Caesar', 'Romans', 'Brutus');

which produces the desired:

    | Friends, Romans, countrymen, lend me your  |
    | ears;                                      |
    | I come to bury Caesar, not to praise him.  |
    | The evil that men do lives after them;     |
    | The good is oft interred with their bones; |
    | So let it be with Caesar. The noble Brutus |
    | Hath told you Caesar was ambitious:        |
    | If it were so, it was a grievous fault,    |
    | And grievously hath Caesar answer'd it.    |

This works because, in those instances where the pattern matches some whitespace followed by one of the punctuation characters, the punctuation character is captured, and the captured character is then used to replace the entire whitespace-plus-punctuator. On the other hand, if the pattern matches whitespace but no punctuator (and it's allowed to do that because the punctuator is optional), then nothing is captured, so "form" falls back to replacing the whitespace with a single space.

Field filling

Fields are (almost) always of a fixed width. So, if there isn't enough data to fill a particular field, the unused portions of that field are filled in with spaces to preserve the vertical alignment of other columns of formatted data. However, spaces are only the default. The "hfill" (horizontal fill) option can be used to change fillers. For example:

    print form
        {hfill=>"=-"},                  # Fill next fields with "=-"
        '{|{*}|}',                      # Full width field for title
        '[ Table of Contents ]',        # Title
        {hfill=>" ."},                  # Fill next fields with spaced dots
        '   {[[[[[{*}[[[[[}{]]]}   ',   # Two indented block fields
            \@contents,    \@page;      # Data for those blocks

This fills the empty space either side of the centred title with a repeated "=-=-=-" sequence. It then fills the gaps to the right of the left-justified the contents field, and to left of the right-justified pages field, with spaced dots. Which, rather prettily, produces something like:

    =-=-=-=-=-=-=-[ Table of Contents ]-=-=-=-=-=-=-=
       Foreword. . . . . . . . . . . . . . . . . .i
       Preface . . . . . . . . . . . . . . . . .iii
       Glossary. . . . . . . . . . . . . . . . . vi
       Introduction. . . . . . . . . . . . . . . .1
       The Tempest . . . . . . . . . . . . . . . .7
       Two Gentlemen of Verona . . . . . . . . . 17
       The Merry Wives of Winsor . . . . . . . . 27
       Twelfh Night. . . . . . . . . . . . . . . 39
       Measure for Measure . . . . . . . . . . . 50
       Much Ado About Nothing. . . . . . . . . . 62
       A Midsummer Night's Dream . . . . . . . . 73
       Love's Labour's Lost. . . . . . . . . . . 82
       The Merchant of Venice. . . . . . . . . . 94
       As You Like It. . . . . . . . . . . . . .105

Note that the fill sequence doesn't have to be a single character and that the fill pattern is consistent across multiple fields and between adjacent lines. That is, it's as if every field is first filled with the same fill pattern, then the actual data written over the top. That's particularly handy in the above example, because it ensures that the fill pattern seamlessly bridges the boundary between the adjacent contents and pages fields.

It's also possible to specify separate fill sequences for the left- and right-hand gaps in a particular field, using the "lfill" and "rfill" options. This is particularly common for numerical fields. For example, this call to "form":

    print form
      'Name              Bribe (per dastardry)',
      '=============     =====================',
      '{[[[[[[[[[[[}         {]],]]].[[[}     ',
      \@names,               \@bribes;

would print something like:

    Name              Bribe (per dastardry)
    =============     =====================
    Crookback                  12.676
    Iago                        1.62
    Borachio               45,615.0
    Shylock                    19.0003

with the numeric field padded with whitespace and only showing as many decimal places as there are in the data.

However, in order to prevent subsequent..err...creative calligraphy (they are, after all, villains and would presumably not hesitate to add a few digits to the front of each number), we might prefer to put stars before the numbers and show all decimal places. We could do that like so:

    print form
      'Name              Bribe (per dastardry)',
      '=============     =====================',
      '{[[[[[[[[[[[}         {]],]]].[[[}     ',
      \@names,               {lfill=>'*', rfill=>'0'},
                             \@bribes;

which would then print:

    Name              Bribe (per dastardry)
    =============     =====================
    Crookback             *****12.6760
    Iago                  ******1.6200
    Borachio              *45,615.0000
    Shylock               *****19.0003

Note that the "lfill" and "rfill" options are specified after the format string and, more particularly, before the data for the second field. This means that those options only take effect for that particular field and the previous fill behaviour is then reasserted for subsequent fields. Many other "form" options – for example "ws", "height", or "break" – can be specified in this way, so as to apply them only to a particular field.

There is also a general "fill" option that sets the default sequence for any filling that isn't otherwise specified.

Zero-filled numeric fields

Filling numeric fields with zeros is so common that "form" offers a shorthand notation for it. If the first character inside a numeric field specification is a zero, then the left-fill string for that field is set to "0". Likewise if the last character in the field is a zero, it is right-filled with zeros. For example:

    my @nums = (0, 1, -1.2345, 1234.56, -1234.56, 1234567.89);
    print form
        '{]]]].[[}     {]]]].[0}     {0]]].[[}     {0]]].[0}',
         \@nums,       \@nums,       \@nums,       \@nums;

prints:

        0.0           0.000     00000.0       00000.000
        1.0           1.000     00001.0       00001.000
       -1.234        -1.234     -0001.234     -0001.234
     1234.56       1234.560     01234.56      01234.560
    -1234.56      -1234.560     -1234.56      -1234.560
    #####.###     #####.###     #####.###     #####.###

Up and down, up and down, I will lead them up and down...

Formatted text blocks are also filled vertically. Empty lines at the end of the block are normally filled with spaces (so as to preserve the alignment of any other fields on the same line). However, this too can be controlled, with the "vfill" option. Alternatively – as with horizontal filling – separate fill sequences can be specified for above and below the text using the "tfill" and "bfill" ("top" and "bottom" fill) options.

For example, if we had six elements in @task, but only four processors:

    print form
        {bfill=>'[unallocated]'},
        'Task                      Processor',
        '====                      =========',
        '{[[[[[[[[[[[[[[[[[[[[}  {]]]]]][[[[[}',
         \@task,                     [1..4];

we'd get:

    Task                      Processor
    ====                      =========
    Borrow story                  1
    Rename characters             2
    Subdivide into scenes         3
    Write dialogue                4
    Check rhythm and meter  [unallocated]
    Insert puns and japes   [unallocated]

Height control

It is possible to constrain the minimum and maximum number of lines that a particular format or block field must cover, regardless of how much data it contains. We do that using the "height" option. For example:

    print form
        {height=>3},
        '{[[[[}{IIII}{]]]]}',
         $l,   $c,   $r;

This will cause the call to "form" to generate exactly three output lines, even if the contents of the data variables would normally fit in fewer lines or would actually require more.

To specify a range of heights we can use the "min" and "max" suboptions:

    print form
        {height=>{ min=>3, max=>20 }},
        '{[[[[}{IIII}{]]]]}',
         $l,   $c,   $r;

This specifies that, no matter how much data is available, the output will be no less than three lines and no more than 20.

Note, however, that the "height" option refers to the height of individual fields, not of entire output pages. we'll see how to control the latter shortly.

Minimal height fields

As we saw earlier, a block overflow field ("{VVVVVVVVV}") has the special property that it only overflows as much as necessary to fill the output lines generated by other block fields. That enabled us to create an overflowing column of text like so:

    print form
        {interleave=>1}, <<EOFORMAT,
    Name:
      {[[[[[[[[[[[[}
                      Biography:
    Status:             {<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<}
      {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    EOFORMAT
        $name,
        $biography,
        $status,
        $comments;

without the first "{VVVVVVVVV}" field eating all the data out of $bio and leaving a large gap between the Status and the Comments.

That's a very handy feature, but restricting the "minimal height" feature to overflow fields turns out to be not good enough in the general case. For instance, suppose we had wanted the biography field to start at the first line of the output text:

    Name:             Biography:
      William           William Shakespeare was born on
      Shakespeare       April 23, 1564 in Strathford-upon-
                        Avon, England; he was third of
    Status:             eight children from Father John
      Deceased (1564    Shakespeare and Mother Mary Arden.
      -1616)            Shakespeare began his education at
                        the age of seven when he probably
    Comments:           attended the Strathford grammar
      Theories          school. The school provided
      abound as to      Shakespeare with his formal
      the true          education. The students chiefly
      author of his     studied Latin rhetoric, logic, and
      plays. The        literature. His knowledge and
      prime             imagination may have come from his
      alternative       reading of ancient authors and
      candidates        poetry. In November 1582,
      being Sir         Shakespeare received a license to
      Francis           marry Anne Hathaway. At the time of
      Bacon,            their marriage, Shakespeare was 18
      Christopher       years old and Anne was 26. They had
      Marlowe, or       three children, the oldest Susanna,
      Edward de         and twins- a boy, Hamneth, and a
      Vere              girl, Judith. Before his death on
                        April 23 1616, William Shakespeare
                        had written thirty-seven plays. He
                        is generally considered the greatest
                        playwright the world has ever known
                        and has always been the world's most
                        popular author.

To do that, we would have required a call to "form" like this:

    print form
        {interleave=>1}, <<EOFORMAT,
    Name:             Biography:
      {[[[[[[[[[[[[}    {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Status:             {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    EOFORMAT
        $name,
        $biography,
        $status,
        $comments;

Note that the first line of the Biography field now has to be a block field, not a single-line field (as in previous versions). It can't be a single-line, because the Name field is a block field and that would leave a gap in the Biography column:

    Name:             Biography:
      William           William Shakespeare was born on
      Shakespeare
                        April 23, 1564 in Strathford-upon-
    Status:             Avon, England; he was third of
                        etc.

So it has to be a block field, to "keep up" with however much output the multi-line Name field produces. Unfortunately, starting the Biography column with a normal block field doesn't solve the problem either. In fact we get:

    Name:             Biography:
      William           William Shakespeare was born on
      Shakespeare       April 23, 1564 in Strathford-upon-
                        Avon, England; he was third of
                        eight children from Father John
                        Shakespeare and Mother Mary Arden.
                        Shakespeare began his education at
                        the age of seven when he probably
                        attended the Strathford grammar
                        school. The school provided
                        Shakespeare with his formal
                        education. The students chiefly
                        studied Latin rhetoric, logic, and
                        literature. His knowledge and
                        imagination may have come from his
                        reading of ancient authors and
                        poetry. In November 1582,
                        Shakespeare received a license to
                        marry Anne Hathaway. At the time of
                        their marriage, Shakespeare was 18
                        years old and Anne was 26. They had
                        three children, the oldest Susanna,
                        and twins- a boy, Hamneth, and a
                        girl, Judith. Before his death on
                        April 23 1616, William Shakespeare
                        had written thirty-seven plays. He
                        is generally considered the
                        greatest playwright the world has
                        ever known and has always been the
                        world's most popular author.
    Status:
      Deceased (1564
      -1616)
    Comments:
      Theories
      abound as to
      the true
      author of his
      plays. The
      prime
      alternative
      candidates
      being Sir
      Francis
      Bacon,
      Christopher
      Marlowe, or
      Edward de
      Vere

Normal block fields are remorseless in consuming all of their data. So the first Biography field absolutely will not stop formatting, ever, until your entire $biography string is gone.

What we really need here, is a kinder, gentler block field; a block field that formats minimally, like an overflow field. And we get that with yet another "height" option: "height=>"minimal"". Like so:

    print form
        {interleave=>1}, <<EOFORMAT,
    Name:             Biography:
      {[[[[[[[[[[[[}    {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Status:             {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[[}    {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
                        {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    Comments:           {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
      {[[[[[[[[[[[}     {VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV}
    EOFORMAT
         $name,
         {height=>"minimal"}, $biography,
         $status,
         $comments;

When this option is applied to a particular field (by placing it immediately before the field's data), that field only consumes as much of its data is is required to fill the output lines created by the other (non-minimal) fields in the same format. In this case, that means that the first Biography field only extracts as much data from $biography as is needed to fill the text lines created by the Name field.

Note that any kind of block field can be modified in this way: justified, numeric, currency, or verbatim.

Underlining

As some of the examples we've seen so far illustrate, formats frequently consist of a set of column titles, followed by the corresponding columns of data. And, typically, those column titles are underlined to make them stand out:

    print form
      'Name              Bribe (per dastardry)',
      '=============     =====================',
      '{[[[[[[[[[[[}         {]],]]].[[[}     ',
      \@names,               \@bribes;

So "form" has an option that automates that process. For example, the payments example above could also have been written:

    print form
      'Name              Bribe (per dastardry)',
      {under=>"="},
      '{[[[[[[[[[[[}         {]],]]].[[[}     ',
      \@names,               \@bribes;

The "under" option takes a string and uses it to underline the most recently formatted line. It does this by examining the formats immediately before and after the "under". It then generates a series of underlines by repeating the specified underlining string as many times as required. The underlines are generated such that every field and every other non-whitespace literal in the preceding format has a underline under it and every field/non-whitespace in the next format has an "overline" above it.

For example, this call to "form":

    print form
        '      Rank Name         Serial Number',
        {under=>"_"},
        '{]]]]]]]]} {[[[[[[[[[}     {IIIII}',
            \@ranks,\@names,        \@nums;

prints:

          Rank Name         Serial Number
    __________ ___________  _____________
      Corporal Nym              CMXVII
    Lieutenant Bardolph          CCIV
       Captain Spurio           MMMCDX
       General Pompey             XI

The usual effect is that the auto-generated underlines always extend to the edges of both the preceding title and the following field, whichever is wider.

Many people, of course, prefer to draw the underlines themselves, as the results are then much easier to visualize when looking at the code. The "under" option is most useful when we're constructing tables programmatically, with columns and column titles that are only known at run-time.

Output trimming

The default fill-with-spaces behaviour of fields is useful to preserve the vertical alignment of columns within a formatted text, but it could also potentially increase the size of "form"'s output unnecessarily. For example, the following:

    print form
        'To Do:',
        '   {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}',
            \@todo;

might produce something like:

    To Do:
       Dissemble
       Deceive
       Dispute
       Defy
       Duel
       Defeat
       Dispatch

That looks fine but, because each line is produced by the large left-justified field that is automatically filled with whitespace, the output contains several hundred more space characters than are strictly necessary (you probably didn't notice them, but they're all there – hanging off the right sides of the individual To-Do items).

Fortunately, however, "form" is smarter than that. Extraneous trailing whitespace on the right-hand side of any output line is automatically trimmed. So the above example actually produces:

    To Do:
       Dissemble
       Deceive
       Dispute
       Defy
       Duel
       Defeat
       Dispatch

Of course, if you really do need those "invisible" trailing whitespaces for some reason, "form" provides a way to keep them – the "untrimmed" option:

    print form {untrimmed=>1},
        'To Do:',
        '   {[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}',
            \@todo;

Measure his woe the length and breadth of mine...

The "page => { length => ... }" suboption determines the number of output lines per page (including headers and footers). Normally, this suboption is set to infinity, which produces that single, arbitrarily long, unbroken page of text. But the suboption can be set to any positive integer value, to cause "form" to generate distinct pages of that many lines each.

Note however, that if the value specified for the page length results in no formatted text appearing on a page (because the available length is entirely consumed by headers or footers), then the length will be (silently) increased so that a single line of content appears on each page.

The value of the "page => { width => ... }" suboption is used to determine the width of distributive fields and in some page body postprocessors. By default, this suboption is set to 78 (columns), but it may be set to any positive integer value.

The "page => { number => ... }" suboption specifies the current page number. By default it starts at 1, but may be set to any numeric value. This suboption is generally only of use in headers and footers (see below).

Headers and footers

The "page => { header => ... }" suboption specifies a hash containing a set of strings or subroutines that are to be used to create page headers. Each key of the hash indicates a particular kind of page that the corresponding value will provide the header for. For example:

    header => { first => "           'The Tempest' by W. Shakespeare          ",
                last  => "                   -- The End --                    ",
                odd   => "Act $act, Scene $scene                              ",
                even  => "                                                    ",
                other => "          [Thys hedder intenshunally blanke]        ",
              }

Given the above specification, "form" will:

•

use the full title and author as the header of the first page,

•

write "-- The End --" across the top of the last page,

•

prepend the act and scene information to the start of any odd page (except, of course, the first or the last), and

•

provide an empty line as the header of any even page (except the last, if it happens to be even).

Note that, in this case, since we've provided specific headers for every odd and even page, the "other" header will never be used. On the other hand, if we'd specified:

    header => { first => "           'The Tempest' by W. Shakespeare          ",
                other => "                                       'The Tempest'",
              }

then every page except the first would have just a right-justified title at the top.

Of course, if we want every page to have the same header, we can just write:

    header => { other => "                                       'The Tempest'"}

But that's a little klunky, so "form" also accepts a single string instead of a hash, to specify a header to be used for every page:

    header  => "                                       'The Tempest'"

Headers don't all have to be the same size either. For example, we might prefer a more imposing first header:

    header => { first => "                  'The Tempest'                   \n"
                       . "                        by                        \n"
                       . "                  W. Shakespeare                  \n"
                       . "____________________________________________________",
                other => "                                       'The Tempest'",
              }

"form" simply notes the number of lines each header requires and then reduces the available number of lines within the page accordingly, so as to preserve the exact overall page length.

Often we'll need headers that aren't fixed strings. For example, we might want each page to include the appropriate page number. So instead of a string, we're allowed to specify a particular header as a subroutine. That subroutine is then called each time that particular header is required, and its return value is used as the required header.

When the subroutine is called, the current set of active formatting options are passed to it as a list of pairs. Typically, then, the subroutine will specify one or more named-only parameters corresponding to the options it cares about, followed by a starred hash parameter to collect the rest. For example if every page should have its (left-justified) page number for a header:

    header => sub { return $_[0]{page}{number}; }

Footers work in exactly the same way in almost all respects; the obvious exception being that they're placed at the end of a page, rather than the start.

Pagefeeds work the same way too. A pagefeed is a string that is placed between the footer of one page and the header of the next. They're like formfeeds, except they can be any string we choose. They're called "pagefeeds" instead of "formfeeds" because they're placed between pages, not between calls to "form".

Page body postprocessing

Sometimes it's useful to be able to grab the entire body of a page (i.e. the contents of the page between the header and footer) after it's been formatted together. For example, we might wish to centre those contents, or to crop them at a particular column.

To this end, the "page => { body => ... }" suboption allows us to specify a page body post-processor. That is, a subroutine or format that lays out the page's formatted text between the page's header and footer. Like the "header", "footer", and "feed" suboptions, the "body" suboption can take either a closure, a hash, or a string.

If the value of the "body" suboption is a string or a hash of pairs, the text of the body is (recursively) "form"'ed using that string (or those string values) as its format. A very common usage is to arrange for the formatted text to be horizonally and vertically centred on each page:

    body => '{=I{*}I=}'

A more sophisticated variation on this is to use a hash to insert a left or right "gutter" for each page:

    $gutter = " " x $gutter_width;
    body => { odd   =>  $gutter ~ '{"""{*}"""}',
              even  =>  '{"""{*}"""}' ~ $gutter,
            }

On the other hand, if the value of the "body" suboption is a subroutine, the body text is passed to that sub as a reference to an array of lines. A second array reference is also passed in, containing as many newlines as would be needed to pad out the body text to the correct number of lines for the page. Finally, the current formatting options are passed as a hash reference. As with the "header" etc. suboption, the closure is expected to return a single string (representing the final formatting of the page body).

For example, to add line numbers to the text each page (but not to the headers or footers or filler lines):

    my $linenum = 1;
    sub numerate {
        my @lines = @{$_[0]};
        my @fill  = @{$_[1]};
        my $page  = ${$_[2]}{page};
        # Compute range of line numbers
        my @linenums = ($linenum .. $linenum+@lines-1);
        # Reformat body lines verbatim,
        # with a left-justified line number before each...
        my $body = form '{[[[[} {"""{*}"""}',
                         \@linenums, \@lines,
                        @fill;
        # Update the final line number and return the new body text...
        $linenum += @lines;
        return $body;
    }
    print form
        page => { body   => \&numerate,
                  header => "\n==========\n\n",
                  length => 12,
                },
        # Left-justify the Briton...
        '{[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[}',
        $soliloquy{RichardIII},
                         # Right-justify the Dane...
        '                 {]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}',
                          $soliloquy{Hamlet};

which produces:

    ==========
    1      Now is the winter of our discontent /
    2      Made glorious summer by this sun of
    3      York; / And all the clouds that lour'd
    4      upon our house / In the deep bosom of
    5      the ocean buried. / Now are our brows
    6      bound with victorious wreaths; / Our
    7      bruised arms hung up for monuments; /
    8      Our stern alarums changed to merry
    9      meetings, / Our dreadful marches to
    ==========
    10     delightful measures. Grim-visaged war
    11     hath smooth'd his wrinkled front; / And
    12     now, instead of mounting barded steeds
    13     / To fright the souls of fearful
    14     adversaries, / He capers nimbly in a
    15     lady's chamber.
    ==========
    16                      To be, or not to be -- that is the question: /
    17                         Whether 'tis nobler in the mind to suffer /
    18                       The slings and arrows of outrageous fortune /
    19                         Or to take arms against a sea of troubles /
    20                       And by opposing end them. To die, to sleep --
    21                         / No more -- and by a sleep to say we end /
    22                      The heartache, and the thousand natural shocks
    23                      / That flesh is heir to. 'Tis a consummation /
    24                        Devoutly to be wished. To die, to sleep -- /
    ==========
    25                         To sleep -- perchance to dream: ay, there's
    26                          the rub, / For in that sleep of death what
    27                         dreams may come / When we have shuffled off
    28                             this mortal coil, / Must give us pause.
    29                        There's the respect / That makes calamity of
    30                                                       so long life.
                   E<nbsp>

Single-column fields

User-defined fields are also a handy way to create single-character markers for single-column fields (in order to preserve the one-to-one spacing of a format). For example:

    print form
        {field => { '^' => '{<III{1}III}',   # 1-char-wide, top-justified block
                    '=' => '{<=II{1}II=}',   # 1-char-wide, middle-justified block
                    '_' => '{<_II{1}II_}',   # 1-char-wide, bottom-justified block
                  }
        },
        '~~~~~~~~~',
        '^ _ = _ ^',   qw(like round and orient perls),
        '~~~~~~~~~';

prints:

    ~~~~~~~~~
    l     o p
    i r a r e
    k o n i r
    e u d e l
      n   n s
      d   t
    ~~~~~~~~~

Single fields are particularly useful for labelling the vertical axes of a graph:

    use Perl6::Form {field => [ '=' => '{<=II{1}II=}' ] };
    $vert_label = "Success";
    $hor_label  = "Time";
    print form
       '   ^                                        ',
       ' = | {""""""""""""""""""""""""""""""""""""} ', $vert_label, \@data,
       '   +--------------------------------------->',
       '    {|||||||||||||||||||||||||||||||||||||} ', $hor_label;

which produces:

        ^
        |
        |       *
        |     *   *
      S |    *     *
      u |
      c |   *       *
      c |
      e |  *         *
      s |
      s |
        |
        | *           *
        +--------------------------------------->
                           Time

Specifying these kinds of single-character block markers is perhaps the commonest use of user-defined fields. But the:

    field => [ '=' => '{<=II{1}II=}' ]

syntax is uncomfortably verbose for that purpose. So calls to "form" can also accept a short-hand notation to define a single-character field:

    single => '='

or to define several at once:

    single => ['#', '*', '+']

The "single" option does exactly the same thing as the "field" options shown above. It takes a single-character string, or a reference to an array of such strings, as its value. It then turns each of those strings into a single-column field marker. If the character is '=' then the field is vertically "middled" within its block. If the character is '_' then the field is "bottomed" within its block. If the single character is anything else, the resulting block is top-justified. So our previous example could also have been written:

    print form
        {single => "="},
        '    ^                                        ',
        ' =  | {""""""""""""""""""""""""""""""""""""} ', $vert_label, \@data,
        '    +--------------------------------------->',
        '     {|||||||||||||||||||||||||||||||||||||} ', $hor_label;