A perl5 extension which makes available the pgplot library.

1 files changed, 218 insertions, 0 deletions

diff --git a/graphics/pgperl/pkg-descr b/graphics/pgperl/pkg-descr
new file mode 100644
index 000000000000..6ee3207b11c7
--- /dev/null
+++ b/graphics/pgperl/pkg-descr
@@ -0,0 +1,218 @@
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+    PGPERL        - A GRAPHICS EXTENSION FOR PERL.
+    ------        - A MACRO LANGUAGE FOR PGPLOT.
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+INTRODUCTION
+------------
+
+'pgperl' is a version of the Perl language which has available
+the PGPLOT FORTRAN library, a very popular package for plotting
+astronomical data. (As a glance through any issue of ApJ or MNRAS will
+confirm.) The details of this involve some complicated C glue routines
+but are transparent to the user.
+
+The idea is to provide a command langage for PGPLOT and a more
+beautiful alternative to the various (incompatible) flavours of MONGO.
+Personally I have always thought that PGPLOT produced far nicer plots
+but at greater pain owing to the long compile/link/run cycle of F77 or
+C.  Wouldn't it be nice if one could call PGPLOT subroutines directrly
+from the elegant perl language?  Five days after reading `Programming
+Perl' I found myself at a telescope with little to do, so I hacked out
+the basics of `pgperl'.  The rest followed during the odd spare evening
+in Cambridge.
+
+Unlike MONGO, perl is a real C-like language with full control
+structures, and is very fast and efficient. All the power of perl (and
+believe me that is a *lot*) is available to extract data to plot from
+multitudes of files in complicated free formats. Using pgperl one has
+all the extra functionality of SM (v.t. `SuperMongo') and IMHO the
+language is far more robust and elegant.  Unlike the MONGOs pgperl is
+free and public domain - though I trust people will communicate
+improvements back to me to avoid version explosions.
+
+pgperl is *complete* - all the PGPLOT routines can be used and I have
+tested most of them.
+
+I have tried very hard to keep the pgperl calls "obvious" to anybody
+who knows PGPLOT and perl. See the notes below for examples of PGPLOT
+use from pgperl. I refer people to the excellent reference manuals
+available for PGPLOT and perl for complete information.
+
+The current version is 1.0 and is built with PGPLOT v5.0 commands.
+There are versions availalable for perl4 (which requires making a new
+perl executable linked with pgplot) and perl5 (as a dynamically loadble
+perl5 module). If you use pgperl please drop me an email and I can put
+you on my mailing list for updates.
+
+See the file LICENSE in the pgperl distribution for copyright/licensing
+information and the file pgperl.doc on how to use pgplot from perl.
+This is also similar documentation on the pgperl WWW Home Page at:
+
+http://www.ast.cam.ac.uk/~kgb/pgperl.html
+
+Many thanks to Frossie for the original inspiration, and to Larry Wall
+and Tim Pearson for providing the excellent ingredients I stuck
+together.
+
+enjoy (I hope),
+
+Karl Glazebrook, 
+---
+kgb@mail.ast.cam.ac.uk              
+Institute of Astronomy, Cambridge
+
+THE PERL5 VERSION OF PGPERL - CHANGES FROM PERL4
+------------------------------------------------
+
+This file describes the use and enhancements of the pgperl package (PGPLOT
+graphics for perl) with perl5. For installation instructions see the file
+BUILDING.
+
+
+LOADING PGPERL
+--------------
+
+Since perl5 supports dynamic loading it is no longer necessary to make
+a special version of the perl binary which has been linked with PGPLOT.
+One just uses the normal perl5 binary and the statement:
+
+use PGPLOT; # Load PGPLOT module (perl5)
+
+will load in the PGPLOT module which contains all the C/perl necessary for
+pgperl (assuming pgperl has been installed in the correct place).
+
+This replaces the older perl4 statement:
+
+require 'pgplot.pl';  # Obsolete - perl4 only
+
+This will still work though - it aliases to the new command - so all old
+pgperl scripts should work unchanged with perl5, subject to the areas where
+perl5 itself has a behaviour slightly different from perl4. These are rare
+though and are changes for the better.
+
+
+IMPROVEMENTS IN CALLING SYNTAX
+------------------------------
+
+In the old pgperl pgplot routines were called thus:
+
+&pgdraw($x, $y);
+
+In the new perl5 version the "&" is no longer necessary and one
+can say:
+
+pgdraw($x, $y);
+
+Moreover all functions can now be used as list operators and so one
+can even say:
+
+pgdraw $x, $y ;
+
+(Beware operator precedence though! - see perlop(1))
+
+
+IMPROVEMENTS IN ARRAY PASSING 
+-----------------------------
+
+In the old pgperl the only way to pass an array was to use the "*"
+notation ("*x" passes a "glob reference" to all variables named "x"),
+e.g.:
+
+&pgpoint($n, *x, *y, $symbol); # Still works
+
+This continues to work. However one can also pass new-style references 
+to individual arrays, e.g.:
+
+pgpoint($n, \@x, \@y, 17); # Direct reference
+
+or using variables to hold references:
+
+$xref = \@x; $yref = \@y;
+pgpoint($n, $xref, $yref, 17);
+
+or even:
+
+pgpoint 3, [1,2,3], [4,5,6], 17;   # Anonymous references
+
+See perlref(1) for all the grubby details on references in perl5.
+
+
+SCALARS INSTEAD OF ARRAYS
+-------------------------
+
+Because of the extra magic now built into pgperl it is possible to
+use scalar variables with array routines, e.g.:
+
+$x=2; $y=4;
+pgpoint(1, $x, $y, 17); # Plot a single point
+
+
+This was not possible in perl4 which resulted in the creation of special
+routines to deal with scalars, e.g. pgpoint1($x,$y,$sym). These old names
+will still work, for easy backwards compatability, but they are no longer
+necessary.
+
+
+TWO-DIMENSIONAL ARRAYS
+----------------------
+
+perl5 now supports multi-dimensional arrays by means of the reference 
+syntax. (In fact it supports N-dimensional mixtures of normal arrays
+and associative arrays but let's not go into that - see perlref(1)).
+
+In the old pgperl 2D arrays had to be passed to pgplot as one-D arrays,
+e.g.:
+
+pggray(*img, $nx, $ny, 1, $nx, 1,$ny, $max, $min ,*tr); # @img is 1D
+
+This still works but is also now possible to pass a reference to a 
+2D array, e.g.:
+
+for($i=0; $i<128; $i++) { for($j=0; $j<128; $j++) { # Set up 128x128 image
+   $$img[$i][$j] = sqrt($i*$j) / 128; 
+}}
+pggray($img,128,128,1,128,1,128,1,0,*tr);  # Plot image
+
+The type of the array is automatically sensed - but make sure the array
+is square and all the elements are defined!
+
+
+Finally there exists a mechanism for efficient memory handling of large
+images. They can be stored as byte-arrays in scalar variables and are
+automgically sensed and passed onwards to the PGPLOT routines with no
+conversion, e.g.:
+
+open(IMG,"test.img");       # Read in 128x128 image stored in file as binary 
+read(IMG, $img, 4*128*128); # data, i.e. list of 4 byte float [C type] /REAL*4
+close(IMG);                 # [f77 type] values, and store as perl string. 
+pggray($img,128,128,1,128,1,128,1,0,*tr); # Plot
+
+Obviously it is not possible to do any operations on such objects with perl
+functions unless they are first converted to normal perl arrays (e.g. with
+@image = unpack("f*",$img);) but this is useful for efficient passing around
+of large images and one might imagine using library routines to read data
+from files and return these structures. (Note: by "large" I mean >=1024x1024
+- for the 128x128 example it makes negligible difference.)
+
+
+EXAMPLES
+--------
+
+All these features are demonstrated in the new test script called
+testpgperl10.pg (which only works with perl5).
+
+perl5 also has trendy object-oriented features - an example of
+using this with PGPLOT is shown in testpgperl11.pg for the sake of 
+amusement.
+
+
+Karl Glazebrook, 
+---
+kgb@ast.cam.ac.uk  Institute of Astronomy, Cambridge, U.K.
+pgperl software:   http://www.ast.cam.ac.uk/~kgb/pgperl.html
+
+-----------------------------------------------------------------------------
+                                               Last Modified. 18/May/1995.