PostScript::Convert - Use Ghostscript to convert PostScript or PDF to other formats
This document describes version 0.03 of PostScript::Convert, released March 15, 2014.
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');
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($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
$input must be one of the following:
This is interpreted as a filename to open.
This must be a reference to a string containing a PostScript document.
This must be a reference to an array of strings, which when joined together form a PostScript document. No newlines are added when joining.
Any argument accepted by "openhandle" in Scalar::Util is interpreted as a filehandle to read from.
Note: in eps mode, this will generate multiple output files if the document has multiple pages.
eps
The object must implement a get__PostScript_File method that returns a PostScript::File object. (Note: there are 2 underscores after get)
get__PostScript_File
get
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.
filename
Options added since version 0.01 are marked with the version they were added in (e.g. "(v0.02)").
This is the output filename. If omitted, it will be calculated from input and format.
input
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.
gs_param => ['-dJPEGQ=N']
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.)
gs
gswin32c.exe
include
An arrayref of directories to add to Ghostscript's search path (for advanced users only).
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.
WIDTHxHEIGHT
[ WIDTH, HEIGHT ]
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.)
x
XRESxYRES
-r
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.
-dSAFER
unsafe => 1
-dNOSAFER
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.
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.
$? >> 8
$? & 127
$? & 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.
PostScript::Convert expects to find a Ghostscript executable somewhere on your $ENV{PATH}. (See the ghostscript option for details.)
$ENV{PATH}
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.
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.)
psconvert
No bugs have been reported.
Christopher J. Madsen <perl AT cjmweb.net>
<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.
<bug-PostScript-Convert AT rt.cpan.org>
You can follow or contribute to PostScript-Convert's development at https://github.com/madsen/postscript-convert.
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.
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.
To install PostScript::Convert, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PostScript::Convert
CPAN shell
perl -MCPAN -e shell install PostScript::Convert
For more information on module installation, please visit the detailed CPAN module installation guide.