.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Alien::Gnuplot 3pm"
.TH Alien::Gnuplot 3pm 2024-04-19 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Alien::Gnuplot \- Find and verify functionality of the gnuplot executable.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& package MyGnuplotter;
\&
\& use strict;
\&
\& use Alien::Gnuplot;
\&
\& $gnuplot = $Alien::Gnuplot::executable;
\&
\& \`$gnuplot < /tmp/plotfile\`;
\&
\& 1;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Alien::Gnuplot verifies existence and sanity of the gnuplot external
application. It only declares one access method,
\&\f(CW\*(C`Alien::Gnuplot::load_gnuplot\*(C'\fR, which does the actual work and is
called automatically at load time. Alien::Gnuplot doesn't have any
actual plotting methods \- making use of gnuplot, once it is found and
verified, is up to you or your client module.
.PP
Using Alien::Gnuplot checks for existence of the executable, verifies
that it runs properly, and sets several global variables to describe
the properties of the gnuplot it found:
.IP \(bu 3
\&\f(CW$Alien::Gnuplot::executable\fR
.Sp
gets the path to the gnuplot executable.
.IP \(bu 3
\&\f(CW$Alien::Gnuplot::version\fR
.Sp
gets the self-reported version number of the executable.
.IP \(bu 3
\&\f(CW$Alien::Gnuplot::pl\fR
.Sp
gets the self-reported patch level.
.IP \(bu 3
\&\f(CW@Alien::Gnuplot::terms\fR
.Sp
gets a list of the names of all supported terminal devices.
.IP \(bu 3
\&\f(CW%Alien::Gnuplot::terms\fR
.Sp
gets a key for each supported terminal device; values are the 1\-line
description from gnuplot. This is useful for testing whether a
particular terminal is supported.
.IP \(bu 3
\&\f(CW@Alien::Gnuplot::colors\fR
.Sp
gets a list of the names of all named colors recognized by this gnuplot.
.IP \(bu 3
\&\f(CW%Alien::Gnuplot::colors\fR
.Sp
gets a key for each named color; values are the \f(CW\*(C`#RRGGBB\*(C'\fR form of the color.
This is useful for decoding colors, or for checking whether a particular color
name is recognized. All the color names are lowercase alphanumeric.
.PP
You can point Alien::Gnuplot to a particular path for gnuplot, by
setting the environment variable GNUPLOT_BINARY to the path. Otherwise
your path will be searched (using File::Spec) for the executable file.
.PP
If there is no executable application in your path or in the location
pointed to by GNUPLOT_BINARY, then the module throws an exception.
You can also verify that it has not completed successfully, by
examining \f(CW$Alien::Gnuplot::version\fR, which is undefined in case of
failure and contains the gnuplot version string on success.
.PP
If you think the global state of the gnuplot executable may have
changed, you can either reload the module or explicitly call
\&\f(CWAlien::Gnuplot::load_gnuplot()\fR to force a fresh inspection of
the executable.
.SH "INSTALLATION STRATEGY"
.IX Header "INSTALLATION STRATEGY"
When you install Alien::Gnuplot, it checks that gnuplot itself is
installed as well. If it is not, then Alien::Gnuplot attempts to
use one of several common package managers to install gnuplot for you.
If it can't find one of those, if dies (and refuses to install), printing
a friendly message about how to get gnuplot before throwing an error.
.PP
In principle, gnuplot could be automagically downloaded and built,
but it is distributed via Sourceforge \-\- which obfuscates interior
links, making such tools surprisingly difficult to write.
.SH "CROSS-PLATFORM BEHAVIOR"
.IX Header "CROSS-PLATFORM BEHAVIOR"
On POSIX systems, including Linux and MacOS, Alien::Gnuplot uses
fork/exec to invoke the gnuplot executable and asynchronously monitor
it for hangs. Microsoft Windows process control is more difficult, so
if $^O contains "MSWin32", a simpler system call is used, that is
riskier \-\- it involves waiting for the unknown executable to complete.
.SH REPOSITORIES
.IX Header "REPOSITORIES"
Gnuplot's main home page is at .
.PP
Alien::Gnuplot development is at .
.PP
A major client module for Alien::Gnuplot is PDL::Graphics::Gnuplot, which
can be found at .
PDL is at .
.SH AUTHOR
.IX Header "AUTHOR"
Craig DeForest
.PP
(with special thanks to Chris Marshall, Juergen Mueck, and
Sisyphus for testing and debugging on the Microsoft platform)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2013 Craig DeForest
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.