Provided by: libpostscript-file-perl_2.20+dfsg-1_all bug

NAME

       PostScript::File::Functions - Collection of useful PostScript functions

VERSION

       This document describes version 2.20 of PostScript::File::Functions, released February 11,
       2012 as part of PostScript-File version 2.20.

SYNOPSIS

         use PostScript::File;

         my $ps = PostScript::File->new;
         $ps->use_functions(qw( setColor showCenter ));
         $ps->add_to_page("1 setColor\n" .
                          "400 400 (Hello, World!) showCenter\n");

DESCRIPTION

       PostScript::File::Functions provides a library of handy PostScript functions that can be
       used in documents created with PostScript::File.  You don't normally use this module
       directly; PostScript::File's "use_functions" method loads it automatically.

POSTSCRIPT FUNCTIONS

   boxPath
         LEFT TOP RIGHT BOTTOM boxPath

       Given the coordinates of the sides of a box, this creates a new, closed path starting at
       the bottom right corner, across to the bottom left, up to the top left, over to the top
       right, and then back to the bottom right.

   clipBox
          LEFT TOP RIGHT BOTTOM clipBox

       This clips to the box defined by the coordinates.

   drawBox
          LEFT TOP RIGHT BOTTOM drawBox

       This calls boxPath to and then strokes the path using the current pen.

   fillBox
         LEFT TOP RIGHT BOTTOM COLOR fillBox

       This fills the path created by boxPath with "COLOR", which can be anything accepted by
       setColor.

   hLine
         WIDTH X Y hline

       Stroke a horizontal line with the current pen with the left endpoint at position "X, Y",
       extending "WIDTH" points rightwards.

   setColor
         RGB-ARRAY|BW-NUMBER setColor

       This combines "setgray" and "setrgbcolor" into a single function.  You can provide either
       an array of 3 numbers for "setrgbcolor", or a single number for "setgray".  The "str" in
       PostScript::File function was designed to format the parameter to this function.

   showCenter
         X Y STRING showCenter

       This prints "STRING" centered horizontally at position X using baseline Y and the current
       font.

   showLeft
         X Y STRING showLeft

       This prints "STRING" left justified at position X using baseline Y and the current font.

   showLines
         X Y LINES SPACING FUNC showLines

       This calls "FUNC" for each element of "LINES", which should be an array of strings.
       "FUNC" is called with "X Y STRING" on the stack, and it must pop those off.  "SPACING" is
       subtracted from "Y" after every line.  "FUNC" will normally be "showCenter", "showLeft",
       or "showRight".

   showRight
         X Y STRING showRight

       This prints "STRING" right justified at position X using baseline Y and the current font.

   vLine
         HEIGHT X Y vline

       Stroke a vertical line with the current pen with the bottom endpoint at position "X, Y",
       extending "HEIGHT" points upwards.

METHODS

       While you don't normally deal with PostScript::File::Functions objects directly, it is
       possible.  The following methods are available:

   new
         $funcs = PostScript::File::Functions->new;

       The constructor takes no parameters.

   add
         $funcs->add('functionRequested', ...);

       Add one or more functions to the procset to be generated.  All dependencies of the
       requsted functions are added automatically.  See "POSTSCRIPT FUNCTIONS" for the list of
       available functions.

   add_to_file
         $funcs->add_to_file($ps, $basename);

       This is short for

         $ps->add_procset( $funcs->generate_procset($basename) );

       $ps should normally be a PostScript::File object.  See "add_procset" in PostScript::File.

   generate_procset
         ($name, $code, $version) = $funcs->generate_procset($basename);

       This collects the requsted functions into a block of PostScript code.

       $name is a suitable name for the procset, created by appending the ids of the requsted
       functions to $basename.  If $basename is omitted, it defaults to the class name with "::"
       replaced by "_".

       $code is a block of PostScript code that defines the functions.  It contains no comments
       or excess whitespace.

       $version is the version number of the procset.

       In scalar context, returns $code.

DIAGNOSTICS

       "%s is not an available function"
           You requsted a function that this version of PostScript::File::Functions doesn't
           provide.

CONFIGURATION AND ENVIRONMENT

       PostScript::File::Functions requires no configuration files or environment variables.

INCOMPATIBILITIES

       None reported.

BUGS AND LIMITATIONS

       No bugs have been reported.

AUTHOR

       Christopher J. Madsen  "<perl AT cjmweb.net>"

       Please report any bugs or feature requests to "<bug-PostScript-File AT rt.cpan.org>" or
       through the web interface at
       http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-File
       <http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-File>.

       You can follow or contribute to PostScript-File's development at
       http://github.com/madsen/postscript-file <http://github.com/madsen/postscript-file>.

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Christopher J. Madsen.

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

DISCLAIMER OF WARRANTY

       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE,
       TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
       COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF
       ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
       THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE
       DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
       HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY
       THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
       INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
       LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY
       OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
       SUCH DAMAGES.