GSAPI - Perl extension for accessing GNU Ghostscript

GSAPI documentation Contained in the GSAPI distribution.

Index

Code Index:

NAME

Top

GSAPI - Perl extension for accessing GNU Ghostscript

SYNOPSIS

Top

  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

Top

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

Top

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

Top

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

Top

    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.
GSAPI documentation Contained in the GSAPI distribution. 
package GSAPI;

use 5.008;
use strict;
use warnings;
use Carp;

require Exporter;
use AutoLoader;

use Tie::Handle;

our @ISA = qw(Exporter Tie::Handle);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use GSAPI ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'const' => [ qw(
    DISPLAY_555_MASK
    DISPLAY_ALPHA_FIRST
    DISPLAY_ALPHA_LAST
    DISPLAY_ALPHA_MASK
    DISPLAY_ALPHA_NONE
    DISPLAY_BIGENDIAN
    DISPLAY_BOTTOMFIRST
    DISPLAY_COLORS_CMYK
    DISPLAY_COLORS_GRAY
    DISPLAY_COLORS_MASK
    DISPLAY_COLORS_NATIVE
    DISPLAY_COLORS_RGB
    DISPLAY_DEPTH_1
    DISPLAY_DEPTH_12
    DISPLAY_DEPTH_16
    DISPLAY_DEPTH_2
    DISPLAY_DEPTH_4
    DISPLAY_DEPTH_8
    DISPLAY_DEPTH_MASK
    DISPLAY_ENDIAN_MASK
    DISPLAY_FIRSTROW_MASK
    DISPLAY_LITTLEENDIAN
    DISPLAY_NATIVE_555
    DISPLAY_NATIVE_565
    DISPLAY_TOPFIRST
    DISPLAY_UNUSED_FIRST
    DISPLAY_UNUSED_LAST
    DISPLAY_VERSION_MAJOR
    DISPLAY_VERSION_MINOR
    ERROR_NAMES
    GSDLLAPI
    GSDLLAPIPTR
    GSDLLCALL
    GSDLLCALLPTR
    GSDLLEXPORT
    LEVEL1_ERROR_NAMES
    LEVEL2_ERROR_NAMES
    e_ExecStackUnderflow
    e_Fatal
    e_Info
    e_InterpreterExit
    e_NeedInput
    e_NeedStderr
    e_NeedStdin
    e_NeedStdout
    e_Quit
    e_RemapColor
    e_VMerror
    e_VMreclaim
    e_configurationerror
    e_dictfull
    e_dictstackoverflow
    e_dictstackunderflow
    e_execstackoverflow
    e_interrupt
    e_invalidaccess
    e_invalidcontext
    e_invalidexit
    e_invalidfileaccess
    e_invalidfont
    e_invalidid
    e_invalidrestore
    e_ioerror
    e_limitcheck
    e_nocurrentpoint
    e_rangecheck
    e_stackoverflow
    e_stackunderflow
    e_syntaxerror
    e_timeout
    e_typecheck
    e_undefined
    e_undefinedfilename
    e_undefinedresource
    e_undefinedresult
    e_unknownerror
    e_unmatchedmark
    e_unregistered
    gs_error_interrupt	
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'const'} } );

our @EXPORT = qw(
	
);

our $VERSION = '0.5';

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.

    my $constname;
    our $AUTOLOAD;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "&GSAPI::constant not defined" if $constname eq 'constant';
    my ($error, $val) = constant($constname);
    if ($error) { croak $error; }
    {
	no strict 'refs';
	# Fixed between 5.005_53 and 5.005_61
#XXX	if ($] >= 5.00561) {
#XXX	    *$AUTOLOAD = sub () { $val };
#XXX	}
#XXX	else {
	    *$AUTOLOAD = sub { $val };
#XXX	}
    }
    goto &$AUTOLOAD;
}

require XSLoader;
XSLoader::load('GSAPI', $VERSION);

# Preloaded methods go here.

# Below is stub documentation for your module. You'd better edit it!


sub TIEHANDLE {
   my ($class,%args) = @_;
   my $inst = new_instance();
   $args{stdin} ||= sub { getc STDIN };
   $args{stdout} ||= sub { print STDOUT $_[0]; length $_[0] };
   $args{stderr} ||= sub { print STDERR $_[0]; length $_[0] };
   $args{args} ||= [];
   $args{user_errors} ||= 0;
   $args{inst} = $inst;
   set_stdio($inst, $args{stdin}, $args{stdout}, $args{stderr});
   delete @args{qw/stdin stdout stderr/};
   init_with_args($inst, @{$args{args}});
   run_string_begin($inst, $args{user_errors});
   bless \%args, $class;
}

sub WRITE ($$$$) {
   my ($ref, $buf, $len, $offs) = @_;
   run_string_continue($ref->{inst}, substr($buf, 0, $len), $ref->{user_errors});
}

sub DESTROY ($) {
   my $inst = $_[0]->{inst};
   run_string_end($inst, $_[0]->{user_errors});
   GSAPI::exit($inst);
   delete_instance($inst);
}


1;
__END__