NAME

Text::Flowed - text formatting routines for RFC2646 format=flowed

SYNOPSIS

 use Text::Flowed qw(reformat quote quote_fixed);
 print reformat($text, {
     quote => 1,
     fixed => 1,
     opt_length => 72,
     max_length => 79
 });
 print quote($text);      # alias for quote => 1
 print quote_fixed(text); # alias for quote => 1, fixed => 1

DESCRIPTION

This module provides functions that deals with formatting data with Content-Type 'text/plain; format=flowed' as described in RFC2646 (http://www.rfc-editor.org/rfc/rfc2646.txt). In a nutshell, format=flowed text solves the problem in plain text files where it is not known which lines can be considered a logical paragraph, enabling lines to be automatically flowed (wrapped and/or joined) as appropriate when displaying.

In format=flowed, a soft newline is expressed as " \n", while hard newlines are expressed as "\n". Soft newlines can be automatically deleted or inserted as appropriate when the text is reformatted.

reformat($text [, \%args])

The reformat() function takes some format=flowed text as input, and reformats it. Paragraphs will be rewrapped to the optimum width, with lines being split or combined as necessary.

    my $formatted_text = reformat($text, \%args);
    

If $args->{quote} is true, a level of quoting will be added to the beginning of every line.

If $args->{fixed} is true, unquoted lines in $text will be interpreted as format=fixed (i.e. leading spaces are interpreted literally, and lines will not be joined together). (Set it to 2 to make all lines interpreted as format=fixed.) This is useful for processing messages posted in web-based forums, which are not format=flowed, but preserve paragraph structure due to paragraphs not having internal line breaks.

$args->{max_length} (default 79) is the maximum length of line that reformat() or quote() will generate. Any lines longer than this length will be rewrapped, unless there is an excessively long word that makes this impossible, in which case it will generate a long line containing only that word.

$args->{opt_length} (default 72) is the optimum line length. When reformat() or quote() rewraps a paragraph, the resulting lines will not exceed this length (except perhaps for excessively long words).

If a line exceeds opt_length but does not exceed max_length, it might not be rewrapped.

quote($text)

quote($text) is an alias for reformat($text, {quote => 1}).

    my $quoted_text = quote($text);
    

quote_fixed($text)

quote_fixed($text) is an alias for reformat($text, {quote => 1, fixed => 1}).

    my $quoted_text = quote_fixed($text);
    

COPYRIGHT

Copyright 2002-2003, Philip Mak

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.