<!-- -*-  mode: nxml -*- -->
<!--
    perl.xml: "Using PLplot from Perl" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999, 2000, 2001, 2002, 2003  Alan W. Irwin
Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004  Rafael Laboissiere
Copyright (C) 2003  Joao Cardoso

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="perl">
  <title>Using PLplot from Perl</title>
  <para>
    There are no proper bindings for the Perl language delivered with the
    PLplot sources.  However, a PLplot interface has been added to the Perl
    Data Language (PDL) since version 2.4.0.  If the PLplot library is
    installed in the system, it is automatically detected by the PDL
    configuration script, such that PLplot support for PDL should work out
    of the box.  For further information see the <ulink
    url="http://pdl.perl.org">PDL homepage</ulink>.
  </para>

  <para>
    The PDL PLplot interface (PDL::Graphics::PLplot) can interact with
    PLplot in two ways: (1) A low level mapping one to one mapping of
    perl functions to PLplot API functions and (2) A high level object
    oriented wrapper that simplifies generating 2D plots. The PLplot
    source distribution contains multiple examples of how to use the
    low level interface (see examples/perl). A key thing to note is
    that, due to the architecture of PDL, all the array arguments to
    a function come first, followed by the scalars. This means that
    the argument order for some of the functions in the PLplot API
    is different when called from PDL.
  </para>

  <para>
    Here is an usage example comparing the low level and the
    object oriented interfaces to PLplot.
  </para>

  <para>
    <programlisting>
      use PDL;
      use PDL::Graphics::PLplot;

      my $x = pdl (0..5);
      my $y = $x ** 2;

      # low level interface

      plsdev ("xwin");
      plinit ();
      plcol0 (1);

      plenv (-0.5, 5.5, -1, 26, 0, 0);
      plline ($x, $y);

      plend ();

      # OO interface

      my $pl = PDL::Graphics::PLplot->new (DEV => "xwin", );
      $pl->xyplot($x, $y, TITLE => 'X vs. Y');
      $pl->close;
    </programlisting>
  </para>

  <para>
  </para>

  <para>
    There is also a Perl PLplot interface on <ulink
    url="http://www.cpan.org">CPAN</ulink> which is not dependent on PDL.
    The Perl module is called <ulink
    url="http://search.cpan.org/~tjenness/Graphics-PLplot/">Graphics::PLplot</ulink> and is
    appropriate for small data arrays.  The API is very similar to the C
    API except that if the number of elements in an array is required by
    the C function the perl interface calculates it automatically.  Also,
    return values are returned and not supplied as arguments.  Here is the
    PDL example above translated to Graphics::PLplot:
  </para>

  <para>
    <programlisting>
      use Graphics::PLplot qw/ :all /;

      @x = (0..5);
      @y = map {$_ * $_} @x;

      plsdev ("xwin");
      plinit ();
      plcol0 (1);

      plenv (-0.5, 5.5, -1, 26, 0, 0);
      plline (\@x, \@y);

      plend ();
    </programlisting>
  </para>

</chapter>
