NAME

RTF::Writer - for generating documents in Rich Text Format

SYNOPSIS

  use RTF::Writer;
  my $rtf = RTF::Writer->new_to_file("greetings.rtf");
  $rtf->prolog( 'title' => "Greetings, hyoomon" );
  $rtf->number_pages;
  $rtf->paragraph(
    \'\fs40\b\i',  # 20pt, bold, italic
    "Hi there!"
  );
  $rtf->close;

DESCRIPTION

This module is for generating documents in Rich Text Format.

This module is a class; an object belonging to this class acts like an output filehandle, and calling methods on it causes RTF text to be written.

Incidentally, this module also exports a few useful functions, upon request.

The following documentation assumes some familiarity with the RTF Specification. Users not already intimately familiar with RTF should look at RTF::Cookbook and/or my book RTF Pocket Guide from O'Reilly, <http://www.oreilly.com/catalog/rtfpg/>

METHODS

$h = RTF::Writer->new_to_file($filename);

This creates a new RTF output stream object, such that sending text to this object will write to the filespec given. This is basically a wrapper around new_to_handle. If opening a write-handle to $filename fails (or if $filename is undef or zero-length), then a fatal error results.

$h = RTF::Writer->new_to_handle(*FILEHANDLE);

This creates a new RTF output stream object, such that sending text to this object will write to the filehandle given. The filehandle can be a glob (*FH) or a filehandle object (*FH{IO} or the value from "IO::File->new(...)").

$h = RTF::Writer->new_to_string(\$string);

This creates a new RTF output stream object, such that sending text to this object will append to the string that you've passed a reference to.

$h->print(...);

This is the basic method for writing text to an RTF stream. This takes a list of items. Each item is either:

$h->prolog(...);

This writes an RTF prolog to $h. You are free to make your own prolog using just $h->print(\'...your own code...'), but I find in easier to automate this task, particularly with some sane defaults.

Since emitting a prolog opens a "{"-group, calling $h->prolog(...) sets a flag in $h so that when you call $h->close(), a closing "}" will automatically be written before the stream object is actually closed.

The options to the prolog() method are passed as a list of keys and values, for controlling the contents of the prolog written. The options are listed below, roughly with the most important options first.

(Be careful with the spelling of these options. Some are rather odd, because they are (mostly) based on the name of the relevent RTF command, and a systematic naming scheme for commands is one thing you won't find in RTF!)

$h->printf('format', ...items...);

This is just short for $h->print(sprintf('format', ...items...)

$h->printf(\'format', ...items...);

In this case, 'format' is assumed to contain already-escaped RTF code. The items in ...items... are escaped as necessary, and then interpolated. I.e., this is rather like: $h->print(\sprintf 'format', map rtfesc($_), ...items...)) except that numeric items don't get escaped (and don't need to be). Example:

    $h->printf(
      \'{\i "%s"} was found in %2.2f percent of matches\par',
      $word, 100 * $count / $total
    );
    

$h->number_pages();

$h->number_pages(...);

This is just a handy wrapper for some code that turns on page numbering. If you call this method, you should call it right after you emit a prolog.

The page numbering consists of just putting the page number at the top-right of each page. If you provide items in the list (...), then that is pre-pended to the page number. Example:

    $h->number_pages("Lexicon, p.");
    

Or:

    $h->number_pages(\'\b\fs30\f2', "page ");
    

$trdecl = RTF::Writer::TableRowDecl->new( ...options... )

This constructs an object representing a declaration for a table row. You can have to use it in calls to $h->row($tabldecl,...), and can reuse it on subsequent calls. This object is for declaring the dimensions of table rows.

The work that a declaration has to do, is best explained in this diagram of a bordered three-cell table (first cell containing "Foo ya!"), placed near a left margin (shown as the line of colons). The things in brackets are not on the page, but just for our reference:

  :    [..w1...]
  :            [......w2.......]
  :                            [...w3....]
  [.A..]     [.B.]           [.B.]
  :
  :    +-------+---------------+---------+
  :    |  Foo  |  Bar baz      |  Yee!   |
  :    |  ya!  |  quuxi quuxo  |         |
  :    |       |  quaqua.      |         |
  :    +-------+---------------+---------+
  :
  [.A..]     [.B.]           [.B.]
  [..r1........]
  [.....r2.....................]
  [........r3............................]
    

Here the horizontal dimensions of the three-celled table are expressed in terms of: A, the distance from the current left margin; B, the minimum distance between the content of the cells (or you can think of this as twice the internal left or right borders in each cell); and then EITHER [w1, w2, w3], expressing the width of each cell, OR [r1, r2, r3], expressing each cell's right end's distance from the current left margin. All distances are, of course, in twips.

Options to RTF::Writer::TableRowDecl->new( ...options... ) are:

$h->paragraph(...);

This makes the items in the list (...) into a paragraph. Basically just a wrapper for $h->print([ \'{\par', ..., \'\pard}', ])

$h->row($trdecl, ...items...);

This emits a table row, with dimensions as stipulated by the $trdecl object, and with row content from the items given.

You must provide a value for $trdecl, or a fatal error results.

If you provide fewer items than $trdecl declares cells, then you get empty cells to fill out the row. If you provide more items than $trdecl declares cells, then the width of the last declared row is used in figuring the width of the additional cells for this row.

Example:

    my $decl = RTF::Writer::TableRowDecl->new('widths' => [1500,1900]);
    $h->row($decl, "Stuff", "Hmmm");
    $h->row($decl, [\'\ul', 'Foo'], 'Bar', \'\bullet');
    $h->row($decl, "Hooboy.");
    

This creates a table resembing:

    +-------------+-------------------+
    | Stuff       | Hmm               |
    +-------------+-------------------+-------------------+
    | _Foo_       | Bar               | *                 |
    +-------------+-------------------+-------------------+
    | "Hooboy."   |                   |
    +-------------+-------------------+
    

Note that you MUST NOT use '\par' commands in any items you emit in row cells!

The $h->row(...) method is a wrapper for producing elementary tables in RTF, with the minimum of parameters; the myriad other options that tables can have (for example, changing borders) are not supported. If you really need to generate tables fancier than what $h->row(...) can produce, start off reading the RTF spec, reading the source for row() (and the RTF::Writer::TableRowDecl class), and progress from there. Note that MSWord has been known to crash when given malformed RTF table code.

$h->table($trdecl, [...row1 items...], [...row2 items...], ... );

$h->table([...row1 items...], [...row2 items...], ... );

This is a wrapper around $h->row. It takes a list of arrayrefs, which are fed to calls to h->row($tr_decl, @$each_arrayref). You should provide a $trdecl, but if you don't, then one is crudely guessed at, based on the maximum number of columns in all rows.

$h->image( image_parameters )

This returns a scalar-reference to RTF-code representing the given image with given parameters. For example:

  $h->paragraph(
    "See here: ",
    $h->image( 'filename' => "foo.png", ),
  );
    

The legal options are explained below:

$h->image_paragraph( image_parameters );

This take the same options as "$h->image(...)", but has three differences: First, it is a shortcut for this:

   $h->paragraph( \'\qc',
     $h->image( ...params...),
   );
    

Secondly, whereas "$h->image(...)" returns the image data (as an RTF scalarref), "$h->image_paragraph(...)" doesn't return much of anything.

Thirdly, "$h->image_paragraph(...)" is often much more memory-efficient, since it can write the image data to a file as it's RTF-ified, instead of building it all up in memory.

$h->close();

This completes writing to the stream denoted by the object in $h; this generally (assuming you'd called $h->prolog) involves just writing a final close-brace to $h, and then closing whatever filehandle or file $h writes to (unless we're writing to a string, in which case we just discard $h's reference to it). After you call "$h->close", you should not call any other methods with $h!

Note that you don't have to explicitly call "$h->close" -- when an unclosed RTF::Writer object goes out of scope (or, more precisely speaking, when if its refcount hits zero), then something equivalent to calling "$h->close" is done automatically for you.

AUTOMETHODS

In addition to any of the above methods, you can use any RTF command (and optional integer arguments) as a valid method name, by just capitalizing its first letter, as shown below:

$h->Foo();

The same as $h->print( \'\foo' );

For example, $h->Page() is the same as $h->print(\'\page')

$h->Foo(...);

(Where "..." is a non-empty list.)

The same as $h->print( [ \'\foo', ... ] );

For example: "$h->I('stuff')" is the same as $h->print([\'\i', 'stuff'])

$h->Foo123();

The same as $h->print( \'\foo123' ). I.e., command word "\foo" with an integer argument of 123.

For example: $h->Cols2() is the same as $h->print(\'\cols2')

$h->Foo123(...);

(Where "..." is a non-empty list.)

The same as $h->print( [ \'\foo123', ... ] );

For example: $h->F2('stuff') is the same as $h->print([\'\f2', 'stuff']).

$h->Foo_123();

The same as $h->print( \'\foo-123' );, i.e., command word "\foo" with an integer argument of negative 123. (You can't have a "-" in a method name, so I use an underscore instead.)

For example: $h->Li_1440() is the same as $h->print([\'\li-1440', 'stuff'])

$h->Foo_123(...);

(Where "..." is a non-empty list.)

The same as $h->print( [ \'\foo-123', ... ] );

FUNCTIONS

None of these functions are exported by default, but they can be exported on request, as in:

  use RTF::Writer qw(inches cm rtfesc);

inch($x), inches($x), in($x)

These synonymous functions all construe the numeric value in $x as inches, and return the equivalent number of twips. For example, "inches(1.5)" returns 2160, because an inch and a half is exactly 2160 twips. The return value of these functions is always an integer, as fractions of twips are not used in RTF.

point($x), points($x), pt($x)

These synonymous functions all construe the numeric value in $x as points, and return the equivalent number of twips. For example, "points(54)" returns 1080, because fifty-four points is exactly 1080 twips. The return value of these functions is always an integer, as fractions of twips are not used in RTF.

cm(x)

This function construes the numeric value in $x as centimeters, and returns the equivalent number of twips. For example, "cm(1.5)" returns 850, because 1.5cm is approximately 850 twips (i.e., it's 850, when rounded to the nearest whole number). Since twips and points are both are defined in terms of inches (1440 twips = 72 points = 1 inch), conversion between cm and these other units is approximate.

The return value of "cm($x)" is always an integer, as fractions of twips are not used in RTF.

rtfesc($text); # void context

rtfesc($x, $y); # void context

rtfesc(@z); # void context

$escaped = rtfesc($x);

@escaped = rtfesc($x, $y, ...);

This escapes some plaintext so it's good RTF. E.g., it turns "Foo\nBar\\" into "Foo\n\\line Bar\\'5c" (since a plaintext backslash needs to be escaped in RTF, and a "\n"'s RTF equivalent is the '\line' command).

In void context (i.e., where you aren't capturing the return value), this in-place alters the values you pass it.

In scalar or list context, doesn't alter the original(s), but returns an escaped copy of what you pass in.

    NW  N  NE        TL  T  TR
      \ | /            \ | /
    W - C - E        L - C - R
      / | \            / | \
    SW  S  SE        BL  B  BR

           s : Single-thickness border
          th : Double-thickness border
          sh : Shadowed border
          db : Double border
         dot : Dotted border
        hair : Hairline border
        dash : Dashed border
       inset : Inset border
      dashsm : Dashed border (small)
       dashd : Dot-dashed border
      dashdd : Dot-dot-dashed border
      outset : Outset border
      triple : Triple border
      tnthsg : Thick-thin border (small)
      thtnsg : Thin-thick border (small)
    tnthtnsg : Thin-thick thin border (small)
      tnthmg : Thick-thin border (medium)
      thtnmg : Thin-thick border (medium)
    tnthtnmg : Thin-thick thin border (medium)
      tnthlg : Thick-thin border (large)
      thtnlg : Thin-thick border (large)
    tnthtnlg : Thin-thick-thin border (large)
        wavy : Wavy border
      wavydb : Double wavy border
  dashdotstr : Striped border
      emboss : Embossed border
     engrave : Engraved border
       frame : Border resembles a "frame"

  borders=> [ "ns-30-db w-25", "all-10-wavy", "none", 13 ],

    borderdec := 
       'borders' =>  '0'    # no borders at all
                   | '1'    # same as ["all-15-s"]
                   | [ cellspec, cellspec, ... ]
                   | cellspec   # default for one-cell form of the above
    cellspec :=  "" | undef    # same as "all-15-s"
                 | int         # same as "all-INT-s" (note: 2 <= int <= 75)
                 | "none"      # no borders on this cell
                 | (border ( ', ' . border )* )
                      # a list of border expressions separated by
                      # a comma (and/or whitespace, in fact)
    border    := direction-thickness-type # For example, "nse-15-s"
                 | direction-type         #  same as "DIR-15-TYPE"
                 | direction-thickness    #  same as "DIR-THICK-s"
                 | direction              #  same as "DIR-15-s"
    direction := "all" | qr/^[nsewtblrNSEWTBLR]+$/
       # Note that "nw" doesn't mean the direction northwest, but
       # simultaneously the north and west sides.
    
    thickness := integer in the range 1 - 75
    
    type  :=  "s" | "th" | "sh" | "db" | "dot" | "hair" | (etc)

SEE ALSO

RTF::Cookbook

The book RTF Pocket Guide from O'Reilly. <http://www.oreilly.com/catalog/rtfpg/>

COPYRIGHT AND DISCLAIMER

Copyright 2001,2,3 Sean M. Burke.

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

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

The author of this document is not affiliated with the Microsoft corporation.

Product and company names mentioned in this document may be the trademarks or service marks of their respective owners. Trademarks and service marks are not identified, although this must not be construed as the author's expression of validity or invalidity of each trademark or service mark.

AUTHOR

Sean M. Burke, <sburke@cpan.org>