/ 
PostScript-Convert-0.03
River stage one • 2 direct dependents • 2 total dependents
/ PostScript::Convert

NAME

PostScript::Convert - Use Ghostscript to convert PostScript or PDF to other formats

VERSION

This document describes version 0.03 of PostScript::Convert, released March 15, 2014.

SYNOPSIS

use PostScript::Convert;

psconvert($filename, $output_filename);

# Base output filename on input filename:
psconvert($filename, format => 'pdf');

my $postscript = "%!PS-Adobe-3.0 ...";
psconvert(\$postscript, $output_filename);

my $ps = PostScript::File->new;
$ps->add_to_page(...);
psconvert($ps, filename => $output_filename, format => 'pnggray');

DESCRIPTION

PostScript::Convert uses Ghostscript to convert PostScript or PDF to other formats. You will need to have Ghostscript installed.

It exports a single function:

psconvert

psconvert($input, [$output_filename], [options...])

This takes the PostScript code or PDF file pointed to by $input and processes it through Ghostscript. The return value is not meaningful. It throws an exception if an error occurs.

Input specifications

$input must be one of the following:

A string

This is interpreted as a filename to open.

A scalar reference

This must be a reference to a string containing a PostScript document.

An array reference

This must be a reference to an array of strings, which when joined together form a PostScript document. No newlines are added when joining.

An open filehandle

Any argument accepted by "openhandle" in Scalar::Util is interpreted as a filehandle to read from.

A PostScript::File object

Note: in eps mode, this will generate multiple output files if the document has multiple pages.

Any other object

The object must implement a get__PostScript_File method that returns a PostScript::File object. (Note: there are 2 underscores after get)

Output options

The remaining arguments after $input are key-value pairs that control the output. If there are an odd number of arguments following $input, then the first one is the filename.

Options added since version 0.01 are marked with the version they were added in (e.g. "(v0.02)").

filename

This is the output filename. If omitted, it will be calculated from input and format.

format

This is the output format. If omitted, it will be taken from the extension of filename. Accepted formats are:

png

24-bit color PNG

pnggray

8-bit grayscale PNG

pngmono

1-bit monochrome PNG

pdf

The preferred PDF version (currently 1.4, but subject to change).

pdf14

PDF version 1.4 (Acrobat 5.0 - 2001)

pdf13

PDF version 1.3 (Acrobat 4.0 - 1999)

pdf12

PDF version 1.2 (Acrobat 3.0 - 1996)

jpg

(v0.03) color JPEG with default extension .jpg (Note: JPEG encoding is not recommended. It's designed for photo-realistic images, not the text and line art more commonly found in PostScript files.)

You can control the compression quality by using gs_param => ['-dJPEGQ=N'] (where N is an integer from 0 to 100). The default depends on your Ghostscript, but is usually 75.

jpeg

(v0.03) color JPEG with default extension .jpeg

jpeggray

(v0.03) grayscale JPEG with default extension .jpeg

ghostscript

This is the Ghostscript executable to use. It defaults to gs, except on Microsoft Windows, where it is gswin32c.exe. (You may use a pathname here.)

include

An arrayref of directories to add to Ghostscript's search path (for advanced users only).

input

This is the input filename. (This is used only for calculating filename when necessary. It does not mean to actually read from this file, and it need not exist on disk.) If omitted, it will be taken from $input (if that is a filename or a PostScript::File object containing a filename).

paper_size

(v0.02) The desired output paper size. This can be a string indicating a known paper size, a string of the form WIDTHxHEIGHT (where WIDTH and HEIGHT are in inches), or an arrayref of two numbers [ WIDTH, HEIGHT ] (where WIDTH and HEIGHT are in points). If omitted, Ghostscript will use its default paper size, unless you pass a PostScript::File object (or an object that supplies a PostScript::File), in which case the paper size will be taken from that object.

resolution

(v0.02) The desired output resolution in pixels per inch. This is either a string of two integers separated by x (XRESxYRES) or a single integer (if the X and Y resolution should be the same). (Passed to gs as its -r option.)

device

The Ghostscript device to use (for advanced users only). This is normally set automatically from the format.

gs_param

An arrayref of additional parameters to pass to Ghostscript (for advanced users only).

unsafe

Ghostscript is normally run with -dSAFER, which prevents the PostScript code from accessing the filesystem. Passing unsafe => 1 will use -dNOSAFER instead. Don't do this unless you trust the PostScript code you are converting.

Paper Sizes

Paper sizes are not case sensitive. These are the known sizes: "comm #10 envelope", "envelope-c5", "envelope-dl", "envelope-monarch", europostcard, executive, folio, "half-letter", ledger, legal, letter, superb, tabloid, "us-legal", "us-letter", A0 - A10, B0 - B10.

DIAGNOSTICS

Can't %s STDIN: %s

There was an error while redirecting STDIN in order to run Ghostscript.

Can't seek temporary file: %s

A seek failed for the specified reason.

Don't know how to handle a %s

You passed an object that psconvert doesn't accept as $input.

Don't know how to handle a %s ref

psconvert only accepts a scalar or array reference as $input.

Expected extension in %s

The temporary filename created by PostScript::File must have an extension, but it didn't.

Ghostscript failed: exit status %s

Ghostscript did not exit successfully. The exit status is reported as a decimal number ($? >> 8), followed by " (signal %d)" if $? & 127 is non-zero, followed by " (core dumped)" if $? & 128.

ghostscript not defined

The ghostscript option was somehow unset. This shouldn't happen, since it has a default value.

Must have PostScript::File 2.00 or later, this is only %s

PostScript::Convert isn't directly compatible with versions of PostScript::File older than 2.00. (If you can't upgrade PostScript::File, then you can write the PostScript to a file and pass that file to psconvert.)

No extension defined for format %s

The specified format failed to define a file extension.

No extension in %s

The output filename must have a file extension.

No output device supplied

The device option (which normally comes from the format) was not set.

No output filename supplied

You didn't specify an output filename, nor did you provide an input filename to guess it from.

No output format or filename supplied

You didn't specify the format option, nor did you supply an output filename from which to guess it.

Unable to determine format from %s

You didn't specify the format option, and the output filename you supplied doesn't match any known format.

Unable to open %s: %s

Opening the specified file failed for the specified reason.

Unknown format %s

The format you specified is not valid.

Unknown paper size %s

The paper_size you specified is not valid.

CONFIGURATION AND ENVIRONMENT

PostScript::Convert expects to find a Ghostscript executable somewhere on your $ENV{PATH}. (See the ghostscript option for details.)

DEPENDENCIES

PostScript::Convert depends on Carp, Exporter, File::Spec, File::Temp, and Scalar::Util. All of these are core modules, but you may need to install a newer version of File::Temp.

It also requires you to have Ghostscript (http://pages.cs.wisc.edu/~ghost/) installed somewhere on your PATH, unless you use the ghostscript option to specify its location.

INCOMPATIBILITIES

PostScript::Convert is not compatible with versions of PostScript::File older than 2.00. (However, you could have an older version of PostScript::File write the PostScript to a file, and then pass that file to psconvert.)

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-Convert AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-Convert.

You can follow or contribute to PostScript-Convert's development at https://github.com/madsen/postscript-convert.

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.