NAME
GSAPI - Perl extension for accessing GNU Ghostscript
SYNOPSIS
use GSAPI;
my $inst = GSAPI::new_instance();
GSAPI::init_with_args($inst);
GSAPI::run_string($inst, "12345679 9 mul pstack quit\n");
GSAPI::exit($inst);
GSAPI::delete_instance $inst;
ABSTRACT
GSAPI is an interface to GNU Ghostscript. It's mainly written to provide a simply interface to ghostscript that works under Win32 and Unix.
DESCRIPTION
GSAPI is a very simple interface to the GNU Ghostscript Interpreter API. This API allows you to use Ghostscript without calling an external program. It also provides to more control over any output.
Please read the current Ghostscript documentation for more details.
FUNCTIONS
revision
my($prod, $cpy, $rev, $revd) = GSAPI::revision();
Returns Product name, Copyright, Revision and Revision Date of the ghostscript release.
new_instance
my $inst = GSAPI::new_instance();
Returns the instance handle.
delete_instance
GSAPI::delete_instance($inst);
Destroys the instance.
set_stdio
GSAPI::set_stdio($inst, &stdin, &stdout, &stderr)
Sets the callbacks for ghostscript I/O stdin
gets the maximum number of bytes to return on input and should return a string up to that length.
stdout/stderr
gets the string passed and they should return the number of bytes written.
Example:
set_stdio $inst,
sub { "\n" },
sub { print STDOUT $_[0]; length $_[0] },
sub { print STDERR $_[0]; lenngth $_[0] };
init_with_args
$rc = GSAPI::init_with_args($inst, @args)
Initializes the ghostscript library. @args
is an array that contains the same strings you would use on the gs
command line.
exit
$rc = GSPAI::exit($inst)
Calls gsapi_exit
run_string
$rc = GSAPI::run_string($inst, $string, [$user_errors ])
Calls gsapi_run_string_with_length()
, executing the Postscript code in $string
.
run_file
$rc = GSAPI::run_file($inst, $filename, [$user_errors])
Calls gsapi_run_file()
, running the Postscript code in $filename
.
run_string_begin
$rc = GSAPI::run_string_begin($inst, [$user_errors])
Calls gsapi_run_string_begin()
, which gets the interpreter ready to run the Postscript code given via subsequent "run_string_continue" calls.
run_string_continue
$rc = GSAPI::run_string_continue($inst, $string, [$user_errors])
Calls gsapi_run_string_continue()
, running the Postscript code in $string
in the interpreter which has been prepared with "run_string_begin".
run_string_end
$rc = GSAPI::run_string_end($inst, [$user_errors])
Calls gsapi_run_string_end(), finishing the execution started in "run_string_begin".
set_display_callback
$rc = GSAPI::set_display_callback( $inst, &callback );
Sets the callback used for -sDEVICE=display
.
Your callback should look like:
sub callback {
my( $func, $handle, $device, @more ) = @_;
...
return $rv;
}
The arguments are:
- $func
-
Name of the current callback. See below.
- $handle
-
Value of
-dDeviceHandle=
as passed to init_with_args. - $device
-
Opaque pointer to Ghostscript's internal device.
- @more
-
Extra parameters. See below.
The callback function is called multiple times. What is happening is decided by $func
.
- display_open
-
New device has been opened. First call.
- display_presize
-
Allows you to accept or reject a size and/or format.
my( $width, $height, $raster, $format ) = @more;
$width
width of the page. Note that this is different from the width of the image, if there is a bounding box defined.$height
is the height of the page.$raster
is the byte count of a row.$format
format of the data. - display_size
-
Called when the page size is fixed.
my( $width, $height, $raster, $format ) = @more;
Note that in the GSAPI, display_size() is called with a pointer (
pimage
) to the raw data. However, because of how XS works, this data is only available to "display_sync" and "display_page". - display_sync
-
my( $pimage ) = @more;
Called when a page is ready to be flushed. Note that
$pimage
will be a blank page, if this is called before "display_page". - display_page
-
Called when a page is ready to be shown.
my( $copies, $flush, $pimage ) = @more;
$pimage
is a string containing the raw image data. It's format is decided by-dDisplayFormat
which you passed to "init_with_args".To get the start of a given row, you use
$rowN * $raster
where$raster
was provided to "display_size".See
eg/imager.pl
for an example of how to get the data. - display_preclose
-
Device is about to be closed.
- display_close
-
Device has been closed. This is the last call for this device.
Please refer to the Ghostscript documentation and examples for more details.
TIEHANDLE
TIEHANDLE 'GSAPI', [ stdin => sub { getc STDIN }, ]
[ stdout => &stdout, ]
[ stderr => stderr, ]
[ args => [ arg1, arg2, ...], ]
[ user_errors => 0|1, ]
You may also tie a GSAPI instance to a file handle. This allows you to print your Postscript code as if to the gs
command.
my $output = '';
tie *FH, "GSAPI", stdout => sub { $output .= $_[0]; length $_[0] },
args => [ "gsapi",
"-sDEVICE=pdfwrite",
"-dNOPAUSE",
"-dBATCH",
"-sPAPERSIZE=a4",
"-DSAFER",
"-sOutputFile=/dev/null",
];
$output = '';
print FH "12345679 9 mul pstack quit\n";
close FH;
## $output will contain 111111111.
EXPORT
None by default.
SEE ALSO
http://pages.cs.wisc.edu/~ghost/doc/svn/Readme.htm
AUTHORS
Stefan Traby, <stefan@hello-penguin.com> Philip Gwyn, <gwyn-at-cpan.org>
COPYRIGHT AND LICENSE
Copyright 2008 by Philip Gwyn. Copyright 2003,2005 by Stefan Traby <stefan@hello-penguin.com>. Copyright (C) 2003,2005 by KW-Computer Ges.m.b.H Graz, Austria.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License 2.0 or any later version.
The main reason why this module is not available under dual license (Artistic/GPL) is simply the fact that GNU Gostscript is only available under GPL and not under Artistic License.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 417:
=begin without a target?