% flowctrl.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: flowctrl.tex 1274 2012-07-21 00:57:18Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Programming: flow control}

This chapter describes Pyxplot's facilities for automating
repetitive tasks by using loops. At the end, we turn to Pyxplot's
interaction with the shell and filing system in which it operates, introducing
a simple framework for automatically re-executing Pyxplot scripts whenever they
change, allowing plots to be automatically regenerated whenever the scripts
used to produce them are modified.

\section{Conditionals}

The {\tt if} statement\indcmd{if} can be used to conditionally execute a series
of commands only when a certain criterion is satisfied. In its simplest form,
its syntax is

\begin{verbatim}
if <expression> { .... }
\end{verbatim}

\noindent where the expression can take the form of, for example, {\tt x<0} or
{\tt y==1}. Note that the operator {\tt ==} is used to test the equality of two
algebraic expressions; the operator {\tt =} is only used to assign values to
variables and functions. A full list of the operators available can be found in
Table~\ref{tab:operators_table}. As in many other programming languages,
algebraic expressions are deemed to be true if they evaluate to any non-zero
value, and false if they exactly equal zero. Thus, the following two examples
are entirely legal syntax, and the first {\tt print} statement will execute,
but the second will not:

\begin{verbatim}
if 2*3 {
  print "2*3 is True"
 }

if 2-2 {
  print "2-2 is False"
 }
\end{verbatim}

\noindent The variables {\tt true} and {\tt false} are predefined constants, making the following syntax legal:

\begin{verbatim}
if false {
  print "Never gets here"
 }
\end{verbatim}

As in C, the block of commands which are to be conditionally executed is
enclosed in braces (i.e.\ {\tt \{~\}}).  The closing brace must be on a line by
itself at the end of the block, or separated from the last command in the block
by a semi-colon.

\begin{verbatim}
if (x==0)
 {
  print "x is zero"
 }

if (x==0) { print "x is zero" ; }
\end{verbatim}

After such an {\tt if} clause, it is possible to string together further
conditions in {\tt else if} clauses, perhaps with a final {\tt else} clause, as
in the example:

\begin{verbatim}
if (x==0)
 {
  print "x is zero"
 } else if (x>0) {
  print "x is positive"
 } else {
  print "x is negative"
 }
\end{verbatim}

Here, as previously, the first script block is executed if the first
conditional, {\tt x==0}, is true. If this script block is not executed, the
second conditional, {\tt x>0}, is then tested. If this is true, then the second
script block is executed.  The final script block, following the {\tt else}, is
executed if none of the preceding conditionals have been true. Any number of
{\tt else if} statements can be chained one after another, and a final {\tt
else} statement can always be optionally supplied. The {\tt else} and {\tt else
if} statements must always be placed on the same line as the closing brace of
the preceding script block.

The precise way in which a string of {\tt else if} statements are arranged in a
Pyxplot script is a matter of taste: the following is a more compact but
equivalent version of the example given above:

\begin{verbatim}
if      (x==0) { print "x is zero"     ; } \
else if (x> 0) { print "x is positive" ; } \
else           { print "x is negative" ; }
\end{verbatim}

\section{For loops}
\indcmd{for}

For loops may be used to execute a series of commands multiple times. Pyxplot
allows {\tt for} loops to follow either the syntax of the BASIC programming
language, or the C syntax:

\begin{verbatim}
for <variable> = <start> to <end> [step <step>]
                          [loopname <loopname>]
  <code>

for (<initialise>; <criterion>; <step>)
  <code>
\end{verbatim}

\noindent Here, {\tt <code>} may be substituted by any block of Pyxplot
commands enclosed in braces \{\}. The closing brace must be on a new line after
the last command of the block.

The first form is similar to how the \indcmdt{for} works in BASIC.  The first
time that the script block is executed, {\tt variable} has the value {\tt start}. Upon each iteration
of the loop, it is incremented by amount {\tt step}. The loop finishes when
the value exceeds {\tt end}. If {\tt step} is negative, then {\tt end} is
required to be less than or equal to {\tt start}. A step size of zero is
considered to be an error.  The iterator variable can have any physical
dimensions, so long as {\tt start}, {\tt end} and {\tt step} all have the same
dimensions, but the iterator variable must always be a real number. If no step
size is given then a step size of unity is assumed.  As an example, the
following script would print the numbers 0, 2, 4, 6 and 8:

\begin{verbatim}
for x = 0 to 10 step 2
 {
  print x
 }
\end{verbatim}

In the C form of the \indcmdt{for}, three expressions are provided, separated
by semicolons. These are evaluated (a) when the loop initialises, (b) as a
boolean test of whether the loop should continue iterating, and (c) at the end
of each iteration, usually to increment/decrement variables as required. For
example:

\begin{verbatim}
for (i=1,j=1; i<=256; i*=2,j++) { print "%3d %3d"%(j,i); }
\end{verbatim}

The syntax

\begin{verbatim}
for (a; b; c) { ... ; }
\end{verbatim}

\noindent is {\it almost} equivalent to

\begin{verbatim}
a; while (b) { ... ; c ; }
\end{verbatim}

\noindent with the single exception that {\tt continue} statements behave
slightly differently.  In the C form of the \indcmdt{for}, the {\tt continue}
statement executes the expression {\tt c} before the next iteration is started,
even though the {\tt while} loop above would not.

The optional {\tt loopname} which can be specified in the {\tt for} statement
is used in conjunction with the {\tt break} and {\tt continue} statements which
will be introduced in Section~\ref{sec:breakcontinue}.

\section{Foreach loops}
\label{sec:foreach}
\indcmd{foreach}
\index{wildcards}

Foreach loops may be used to run a script block once for each item in a list or
dictionary. Alternatively, if a string is supplied, it is treated as a filename
wildcard, and all matching files are returned. For example:

\begin{verbatim}
foreach x in [-1,pi,10]
 { print x ; }

foreach x in "*.dat"
 { print x ; }

myDict = { 'a':1 , 'b':2 }
foreach x in myDict
 { print x ; }

\end{verbatim}

The first of these loops would iterate three times, with the variable {\tt x}
holding the values $-1$, $\pi$ and $10$ in turn. The second of these loops
would search for any \datafile s in the user's current directory with filenames
ending in {\tt .dat} and iterate for each of them. As previously, the wildcard
character {\tt *} matches any string of characters, and the character {\tt ?}
matches any single character. Thus, {\tt foo?.dat} would match {\tt foo1.dat}
and {fooX.dat}, but not {\tt foo.dat} or {\tt foo10.dat}. The effect of the
{\tt print} statement in this particular example would be rather similar to
typing:

\begin{verbatim}
!ls *.dat
\end{verbatim}

An error is returned if there are no files in the present directory which match
the supplied wildcard. The following example would produce plots of all of the
\datafile s in the current directory with filenames {\tt foo\_*.dat} or {\tt
bar\_*.dat} as {\tt eps} files with matching filenames:

\begin{verbatim}
set terminal eps
foreach x in "foo_*.dat" "bar_*.dat"
 {
  outfilename =  x
  outfilename =~ s/dat/eps/
  set output outfilename
  plot x using 1:2
 }
\end{verbatim}

If a dictionary is supplied to loop over, then the loop variable iterates over
each of the keys in the dictionary.

\section{Foreach datum loops}
\label{sec:foreach_datum}

Foreach datum loops are similar to foreach loops in that they run a script
block once for each item in a list.  In this case, however, the list in
question is the list of \datapoint s in a \datafile, samples of a function, or
values in a vector. The syntax of the \indcmdt{foreach datum} is similar to
that of the commands met in the previous chapter for acting on \datafile s:
the standard modifiers {\tt every}, {\tt index}, {\tt select} and {\tt using}
can be used to select which columns of the \datafile, and which subset of the
datapoints, should be used:

\begin{verbatim}
foreach datum i,j,name in "data.dat" using 1:2:"%s"%($3)
  <code>

foreach datum x,y,z in sin(x):cos(x)
  <code>

foreach datum a,b in vector_a:vector_b
  <code>
\end{verbatim}

The \indcmdt{foreach datum} is followed by a comma-separated list of the
variable(s) which are to be read from the input data on each iteration of the
loop. The {\tt using} modifier specifies the columns or rows of data which are
to be used to set the values of each variable. In the first example above, the
third variable, {\tt name}, is set as a string, indicating that it will be set
to equal whatever string of text is found in the third column of the \datafile.

\example{ex:meansd}{Calculating the mean and standard deviation of data}{
The following Pyxplot script calculates the mean and standard deviation of a
set of \datapoint s using the \indcmdt{foreach datum}:
\nlscf
\noindent{\tt N\_data = 0}\newline
\noindent{\tt sum\_x  = 0}\newline
\noindent{\tt sum\_x2 = 0}\newline
\\
\noindent{\tt foreach datum x in '--'}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}N\_data ++}\newline
\noindent{\tt \phantom{xx}sum\_x  += x}\newline
\noindent{\tt \phantom{xx}sum\_x2 += x**2}\newline
\noindent{\tt \phantom{x}\}}\newline
\noindent{\tt 1.3}\newline
\noindent{\tt 1.2}\newline
\noindent{\tt 1.5}\newline
\noindent{\tt 1.1}\newline
\noindent{\tt 1.3}\newline
\noindent{\tt END}\newline
\\
\noindent{\tt mean = sum\_x / N\_data}\newline
\noindent{\tt SD   = sqrt(sum\_x2 / N\_data - mean**2)}\newline
\\
\noindent{\tt print "Mean = \%s"\%mean}\newline
\noindent{\tt print "SD   = \%s"\%SD}
\nlscf
\noindent For the data supplied, a mean of $1.28$ and a standard deviation of
$0.133$ are returned.
}

\section{While and do loops}

The \indcmdt{while} may be used to continue running a script block until some
stopping criterion is met. Two types of while loop are supported:

\begin{verbatim}
while <criterion> [ loopname <name> ]
 {
  ....
 }

do [ loopname <name> ]
 {
  ....
 } while <criterion>
\end{verbatim}
\indcmd{do}

In the former case, the enclosed script block is executed repeatedly, and the
algebraic expression supplied to the \indcmdt{while} is tested immediately
before each repetition. If it tests false, then the loop finishes.  The latter
case is very similar, except that the supplied algebraic expression is tested
immediately {\it after} each repetition. Thus, the former example may never
actually execute the supplied script block if the looping criterion tests false
on the first iteration, but the latter example is always guaranteed to run
its script block at least once.

The following example would continue looping indefinitely until stopped by the
user, since the value {\tt 1} is considered to be true:

\begin{verbatim}
while (1)
 {
  print "Hello, world!"
 }
\end{verbatim}

\section{The {\tt break} and {\tt continue} statements}
\label{sec:breakcontinue}
\indcmd{break}
\indcmd{continue}

The {\tt break} and {\tt continue} statements may be placed within loop
structures to interrupt their iteration. The {\tt break} statement terminates
execution of the smallest loop currently being executed, and Pyxplot resumes
execution at the next statement after the closing brace which marks the end of
that loop structure. The {\tt continue} statement terminates execution of the
{\it current iteration} of the smallest loop currently being executed, and
execution proceeds with the next iteration of that loop, as demonstrated by the
following pair of examples:

\vspace{3mm}
\input{fragments/tex/flow_break.tex}
\vspace{3mm}

Note that if several loops are nested, the {\tt break} and {\tt continue}
statements only act on the innermost loop. If either statement is encountered
outside of a loop structure, an error results. Optionally, the {\tt for}, {\tt
foreach}, {\tt do} and {\tt while} commands may be supplied with a name for the
loop, prefixed by the word {\tt loopname}, as in the examples:

\begin{verbatim}
for i=0 to 4 loopname iloop
...
foreach i in "*.dat" loopname DatafileLoop
...
\end{verbatim}

\noindent When loops are given such names, the {\tt break} and {\tt continue}
statements may be followed by the name of the loop to be broken out of,
allowing the user to act on loops other than the innermost one.

\section{The conditional operator}
\label{sec:conditional_operator}

The conditional operator provides a compact means of inserting conditional
expressions.  Following the syntax of C, it takes three arguments and is
written as {\tt a ? b : c}. The first argument, {\tt a} is a truth criterion to
be tested. If the criterion is true, then the operator returns its second
argument {\tt b} as its output. Otherwise, the function's third argument {\tt
c} is returned.

\vspace{2mm}
\input{fragments/tex/flow_conditional.tex}

\section{Subroutines}
\indcmd{subroutine}
\label{sec:subroutines}

Subroutines are similar to mathematical functions (see
Section~\ref{sec:functions}), and once defined, can be used anywhere in
algebraic expressions, just as functions can be.  However, instead of being
defined by a single algebraic expression, whenever a subroutine is evaluated, a
block of Pyxplot commands of arbitrary length is executed. This gives much
greater flexibility for implementing complex algorithms. Subroutines are
defined using the following syntax:
\begin{verbatim}
subroutine <name>(<variable1>,...)
 {
  ...
  return <value>
 }
\end{verbatim}
Where {\tt name} is the name of the subroutine, {\tt variable1} is an argument
taken by the subroutine, and the value passed to the {\tt return} statement is
the value returned to the caller. Once the {\tt return} statement is reached,
execution of the subroutine is terminated. The following two examples would
produce entirely equivalent results:
\begin{verbatim}
f(x,y) = x*sin(y)

subroutine f(x,y)
 {
  return x*sin(y)
 }
\end{verbatim}
In either case, the function/subroutine could be evaluated by typing:
\begin{verbatim}
print f(1,pi/2)
\end{verbatim}
If a subroutine ends without any value being returned using the {\tt return}
statement, then a value of zero is returned.

Subroutines may serve one of two purposes. In many cases they are used to
implement complicated mathematical functions for which no simple algebraic
expression may be given. Secondly, they may be used to repetitively execute a
set of commands whenever they are required. In the latter case, the subroutine
may not have a return value, but may merely be used as a mechanism for
encapsulating a block of commands.  In this case, the \indcmdt{call} may be
used to execute a subroutine, discarding any return value which it may produce,
as in the example:

\vspace{3mm}
\input{fragments/tex/flow_subroutine.tex}
\vspace{3mm}

\example{ex:newton}{An image of a Newton fractal}{
Newton fractals are formed by iterating the equation
\begin{displaymath}
z_{n+1} = z_n - \frac{f(z_n)}{f^\prime(z_n)},
\end{displaymath}
subject to the starting condition that $z_0=c$, where $c$ is any complex number
$c$ and $f(z)$ is any mathematical function. This series is the Newton-Raphson
method for numerically finding solutions to the equation $f(z)=0$, and with
time usually converges towards one such solution for well-behaved functions.
The complex number $c$ represents the initial guess at the position of the
solution being sought. The Newton fractal is formed by asking which solution
the iteration converges upon, as a function of the position of the initial
guess $c$ in the complex plane. In the case of the cubic polynomial
$f(z)=z^3-1$, which has three solutions, a map might be generated with points
colored red, green or blue to represent convergence towards the three roots.
\nlnp
If $c$ is close to one of the roots, then convergence towards that particular
root is guaranteed, but further afield the map develops a fractal structure. In
this example, we define a Pyxplot subroutine to produce such a map as a
function of $c=x+iy$, and then plot the resulting map using the {\tt colormap}
plot style (see Section~\ref{sec:colormaps}).  To make the fractal prettier --
it contains, after all, only three colors as strictly defined -- we vary the
brightness of each point depending on how many iterations are required before
the series ventures within a distance of $|z_n-r_i|<10^{-2}$ of any of the
roots $r_i$.

\nlscf
\input{examples/tex/ex_newton_1.tex}
\nlscf
\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_newton}
\end{center}
}

\example{ex:pendulum}{The dynamics of the simple pendulum}{
The equation of motion for a pendulum bob may be derived from the rotational
analogue to Newton's Second Law, $G=I\ddot\theta$ where $G$ is torque, $I$ is
moment of inertia and $\theta$ is the displacement of the pendulum bob from the
vertical. For a pendulum of length $l$, with a bob of mass $m$, this
equation becomes $-mgl\sin\theta=ml^2\ddot\theta$. In the small-angle
approximation, such that $\sin\theta\approx\theta$, it reduces to
the equation for simple harmonic motion, with the solution
\\ \noindent
\begin{equation}
\theta_\mathrm{approx}=\omega\sin\left(\sqrt{\frac{g}{l}}t\right).
\label{eq:pendulum_approx}
\end{equation}
\nlnp
A more exact solution requires integration of the second-order differential
equation of motion including the $\sin\theta$ term. This integral cannot be
done analytically, but the solution can be written in the form
\\ \noindent
\begin{equation}
\theta_\mathrm{exact}(t) = 2\sin^{-1}\left[ k\,\mathrm{sn}\left(\sqrt{\frac{g}{l}}t,k\right)\right].
\label{eq:pendulum_exact}
\end{equation}
\\ \noindent
where $\mathrm{sn}(u,m)$ is a Jacobi elliptic function and
$k=\sin\left(\omega/2\right)$.  The Jacobi elliptic function cannot be
analytically computed, but can be numerically approximated using the {\tt
jacobi\_\-sn(u,m)} function in Pyxplot.
\nlnp
Below, we produce a plot of Equations~(\ref{eq:pendulum_approx}) and
(\ref{eq:pendulum_exact}).  The horizontal axis is demarcated in units of the
dimensionless period of the pendulum to eliminate $g$ and $l$, and a swing
amplitude of $\pm30^\circ$ is assumed:
\nlscf
\input{examples/tex/ex_pendulum_1.tex}
\nlscf
\centerline{\includegraphics[width=9cm]{examples/eps/ex_pendulum}}
\nlnp
As is apparent, at this amplitude, the exact solution begins to deviate
noticeably from the small-angle solution within 2--3 swings of the pendulum. We
now seek to quantify more precisely how long the two solutions take to diverge
by defining a subroutine to compute how long $T$ it takes before the two
solutions to deviate by some amount $\psi$. We then plot these times as a
function of amplitude $\omega$ for three deviation thresholds. Because this
subroutine takes a significant amount of time to run, we only compute~40
samples for each value of $\psi$:
\nlscf
\input{examples/tex/ex_pendulum_2.tex}
\nlscf
\centerline{\includegraphics[width=9cm]{examples/eps/ex_pendulum2}}
}

\section{Macros}
\index{macros}
\index{@ operator@{\tt @} operator}

The $@$ operator can be used for literal substitution of the content of a
string variable into the command line.  The name of the string variable follows
the $@$ sign, and its content is expanded to the command line, as in this
example
\begin{verbatim}
mac = "with lines lw 2 lt 1"
plot sin(x) @mac
\end{verbatim}
which is equivalent to 
\begin{verbatim}
plot sin(x) with lines lw 2 lt 1
\end{verbatim}

The macro, being a string, can contain any characters, but as with other
variable names, the name of the macro can contain only alphanumeric characters
and the underscore sign. This also means that any operator, with the exception
of the {\tt and} and {\tt or} operators, can signify the end of the macro name,
without the need for a trailing white space. Therefore, in the example
\begin{verbatim}
foo = "50"
print @foo*3
\end{verbatim}
the end result is 150; {\tt 50*3} is passed to the command line interpreter.

\section{The \indcmdt{exec}}

The \indcmdt{exec} can be used to execute Pyxplot commands contained within
string variables. For example:

\begin{verbatim}
terminal="eps"
exec "set terminal %s"%(terminal)
\end{verbatim}

\noindent It can also be used to write obfuscated Pyxplot scripts, and its use
should be minimized wherever possible.

\section{Assertions}
\index{assertions}

The \indcmdt{assert} can be used to assert that a logical expression, such as
{\tt x>0}, is true. An error is reported if the expression is false, and
optionally a string can be supplied to provide a more informative error message
to the user:

\begin{verbatim}
assert x>0
assert y<0 "y must be less than zero."
\end{verbatim}

The \indcmdt{assert} can also be used to test the version number of Pyxplot. It
is possible to test either that the version is newer than or equal to a
specific version, using the {\tt $>$=} operator, or that it is older than a
specific version, using the {\tt $<$} operator, as demonstrated in the
following examples:

\begin{verbatim}
assert version >= 0.8.2
assert version <  0.8  "This script is designed for Pyxplot 0.7"
\end{verbatim}


\section{Raising exceptions}

Pyxplot's {\tt raise(e,s)} function is used to raise exceptions when error
conditions are met.  Its first argument {\tt e} specifies the type of
exception, and should be an object of type {\tt exception}. The second argument
should be an error message string.  Pyxplot has a range of default exception
types, which can be found as {\tt exception} objects in the module {\tt
exceptions}. Alternatively, the object {\tt types.exception} may be called with
a single string argument to make a new exception type. For example:

\begin{verbatim}
raise(exceptions.syntax , "Input could not be parsed")

a=types.exception("user error")
raise(a, "The user made a mistake")
\end{verbatim}

Alternatively, {\tt exception} objects have a method {\tt raise(s)} which can be called as follows:

\begin{verbatim}
a=types.exception("user error")
a.raise("The user made a mistake")
\end{verbatim}


\section{Shell commands}

Shell commands\index{shell commands!executing} may be executed directly from
within Pyxplot by prefixing them with an \indcmdts{!} character. The
remainder of the line is sent directly to the shell, for example:

\begin{verbatim}
!ls -l
\end{verbatim}

\noindent Semi-colons cannot be used to place further Pyxplot commands after a
shell command on the same line.

\begin{dontdo}
!ls -l ; set key top left
\end{dontdo}

It is also possible to substitute the output of a shell command into a Pyxplot
command. To do this, the shell command should be enclosed in back-quotes (`),
as in the following example:\index{backquote character}\index{shell
commands!substituting}

\begin{verbatim}
a=`ls -l *.ppl | wc -l`
print "The current directory contains %d Pyxplot scripts."%(a)
\end{verbatim}

It should be noted that back-quotes can only be used outside quotes. For
example,

\begin{dontdo}
set xlabel '`ls`'
\end{dontdo}

\noindent will not work. One way to do this would be

\begin{verbatim}
set xlabel `echo "'" ; ls ; echo "'"`
\end{verbatim}

\noindent a better way would be to use the {\tt os.system} or {\tt os.popen} functions:

\begin{dodo}
fileList = os.popen("ls","r").read()\newline
set xlabel fileList
\end{dodo}

Note that it is not possible to change the current working directory by sending
the {\tt cd} command to a shell, as this command would only change the working
directory of the shell in which the single command is executed:

\begin{dontdo}
!cd ..
\end{dontdo}

\noindent Pyxplot has its own \indcmdt{cd} for this purpose, as well as its own
\indcmdt{pwd}:

\begin{dodo}
cd ..
\end{dodo}

\section{Script watching: pyxplot\_watch}

Pyxplot includes a simple tool for watching command script files and executing
them whenever they are modified. This may be useful when developing a command
script, if one wants to make small modifications to it and see the results in a
semi-live fashion. This tool is invoked by calling the {\tt
pyxplot\_watch}\index{pyxplot\_watch}\index{watching scripts} command from a
shell prompt. The command-line syntax of {\tt pyxplot\_watch} is similar to
that of Pyxplot itself, for example:

\begin{verbatim}
pyxplot_watch script.ppl
\end{verbatim}

\noindent would set {\tt pyxplot\_watch} to watch the command script file
{\tt script.ppl}. One difference, however, is that if multiple script files are
specified on the command line, they are watched and executed independently,
\textit{not} sequentially, as Pyxplot itself would do. Wildcard characters can
also be used to set {\tt pyxplot\_watch} to watch multiple
files.\footnote{Note that {\tt pyxplot\_watch *.script} and
{\tt pyxplot\_watch $\backslash$*.script} will behave differently in most
UNIX shells.  In the first case, the wildcard is expanded by your shell, and a
list of files passed to {\tt pyxplot\_watch}. Any files matching the
wildcard, created after running {\tt pyxplot\_watch}, will not be picked up.
In the latter case, the wildcard is expanded by {\tt pyxplot\_watch} itself,
which {\it will} pick up any newly created files.}

This is especially useful when combined with \ghostview's\index{Ghostview}
watch facility. For example, suppose that a script {\tt foo.ppl} produces
PostScript output {\tt foo.ps}. The following two commands could be used to
give a live view of the result of executing this script:

\begin{verbatim}
gv --watch foo.ps &
pyxplot_watch foo.ppl
\end{verbatim}