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