% programming.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: programming.tex 1302 2012-09-05 17:30:27Z 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: Pyxplot's data types}
\label{chap:progDataTypes}

This chapter describes Pyxplot's built-in object types, which include lists,
dictionaries, vectors, matrices and file handles.

All objects in Pyxplot, including numbers, have {\it methods}, which act on or
return information about the object. Some methods are common to all objects.
For example, they all have a method {\tt str()} which returns a string
representation of the object (as used by the {\tt print} command). All objects
also have a method called {\tt methods()}, which returns a list of the names of
all of methods of that object. These methods can be called as follows (we don't
show the output, as it is long):

\begin{verbatim}
print pi.str()
print "My son, it's a wisp of fog.".methods()
\end{verbatim}

\noindent Methods are like functions in that printing them returns brief
documentation about them, as we demonstrate below on two methods of string
objects:

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

The following sections describe each of Pyxplot's types in turn, and the
methods that can be applied to each of them.  A comprehensive list of all of
Pyxplot's object types can be found in Chapter~\ref{ch:types_list}, which also
lists the methods available in each object type.

\section{Instantiating objects}

A list of all of Pyxplot's built-in object types can be found in the {\tt
types} module, which contains the {\it object prototypes} for each type. Its
contents are as follows:

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

\noindent These object prototypes can be called like functions to produce an
instance of each data type. Each prototype can take various different kinds of
argument; for example, the {\tt number} prototype can take a {\tt number}, {\tt
boolean} or a {\tt string} from which to create a number. For example:

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

\noindent Full documentation of the types of inputs supported by each prototype
are listed in the Reference Manual, in Section~\ref{sec:functions_types}.

In many cases there are much more succinct ways of creating objects of each
type. For example, lists can be creating by enclosing a comma-separated list of
elements in square brackets:

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

\noindent Dictionaries can be can be creating by enclosing key--value pairs in curly brackets:

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


\section{Strings}
\label{sec:stringvars}
\index{variables!string}

Strings can be enclosed either in single ({\tt '}) or double ({\tt "}) quotes.
Strings may also be enclosed by three quote characters in a row: either {\tt
\textquoteright\textquoteright\textquoteright} or {\tt """}. Special care needs
to be taken when using apostrophes or quotes in single-quote delimited strings,
as these characters may be misinterpreted as string delimiters, as in the
example:

\begin{dontdo}
'Robert's data'
\end{dontdo}

\noindent This easiest way to avoid such problems is to use three quotes:

\begin{dodo}
\textquoteright\textquoteright\textquoteright Robert's data\textquoteright\textquoteright\textquoteright
\end{dodo}

Special characters such as tabs and newlines can be inserted into strings using
escape codes such as {\tt $\backslash$t} and {\tt $\backslash$n}; see
Table~\ref{tab:escape_sequences2} for a list of these. The following string is
split over three lines:

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

Sometimes these escape codes can be rather annoying, especially when entering
\latexdcf\ control codes, which all begin with backslash characters. Rather than
having to escape every backslash, it is generally easier to prefix the string
with the character {\tt r}, which turns off all escape codes:

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

\begin{table}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l>{\columncolor{LightGrey}}l|}
\hline
{\bf Escape sequence} & {\bf Description} \\
\hline
{\tt $\backslash$?} & Question mark \\
{\tt $\backslash$'} & Apostrophe \\
{\tt $\backslash$"} & Double quote \\
{\tt $\backslash\backslash$} & Literal backslash \\
{\tt $\backslash$a} & Bell character \\
{\tt $\backslash$b} & Backspace \\
{\tt $\backslash$f} & Formfeed \\
{\tt $\backslash$n} & Newline \\
{\tt $\backslash$r} & Carriage return \\
{\tt $\backslash$t} & Horizontal tab \\
{\tt $\backslash$v} & Vertical tab \\
\hline
\end{tabular}
\end{center}
\caption{A complete list of Pyxplot's string escape sequences. These are a subset of those available in C.}
\label{tab:escape_sequences2}
\end{table}

Once defined, a string variable can be used anywhere in Pyxplot where a quoted
string could have been used, for example in the {\tt set title} command:

\begin{verbatim}
plotname = "Insert title here"
set title plotname
\end{verbatim}

Strings can be concatenated together using the {\tt +} operator:

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

\subsection{The string substitution operator}
\label{sec:stringsubop}

Most string manipulations are performed using the string substitution operator,
{\tt \%}\index{\% operator@{\tt \%} operator}, which performs a similar role to
the {\tt sprintf} statement in C.

This operator should be preceded by a format string, such as {\tt 'x=\%f'}, in
which tokens such as {\tt \%f} mark places where numbers and strings should be
substituted. The substitution operator is followed by a bracketed list of the
quantities which should be substituted in place of these tokens. This behaviour
is similar to that of the Python programming language's \% operator\footnote{As
in Python, the brackets are optional when only one item is being substituted.
For example, {\tt '\%d'\%2} is equivalent to {\tt '\%d'\%(2)}.}

For example, to concatenate the two strings contained in the variables {\tt a}
and {\tt b} into a single string variable {\tt c}, one would issue the
command:\index{string operators!concatenation}

\begin{verbatim}
c = "%s%s"%(a,b)
\end{verbatim}

One application of this operator might be to label plots with the title of the
\datafile\ being plotted, as in the following example:
\begin{verbatim}
filename="data_file.dat"
title=r"A plot of the data in {\tt %s}."%filename
set title title
plot filename
\end{verbatim}

The syntax of the substitution tokens placed in the format string is similar to
that used by many other languages (including C and Python).  All substitution
tokens begin with a {\tt \%} character, after which there may be placed, in
order:

\begin{enumerate}
\item An optional minus sign, to specify that the substituted item should be left-justified.
\item An optional integer specifying the minimum character width of the substituted item, or a {\tt *} (see below).
\item An optional decimal point/period ({\tt .}) separator.
\item An optional integer, or a {\tt *} (see below), specifying either (a) the maximum number of characters to be printed from a string, or (b) the number of decimal places of a floating-point number to be displayed, or (c) the minimum number of digits of an integer to be displayed, padded to the left with zeros.
\item A conversion character.
\end{enumerate}

\noindent The conversion character is a single character which specifies what
kind of substitution should take place. Its possible values are listed in
Table~\ref{tab:conversion_chars}.

\begin{table}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l>{\columncolor{LightGrey}}p{9cm}|}
\hline
{\bf Character} & {\bf Substitutes} \\
\hline
{\tt d}, {\tt i}   & An integer value. \\
{\tt e}, {\tt E}   & A floating-point value in scientific notation using either the character {\tt e} or {\tt E} to indicate exponentiation. \\
{\tt f}            & A floating-point value without the use of scientific notation. \\
{\tt g}, {\tt G}   & A floating-point value, either using scientific notation, if the exponent is greater than the precision or less than $-4$, otherwise without the use of scientific notation. \\
{\tt o}            & An integer value in octal (base~8). \\
{\tt s}, {\tt S}, {\tt c} & A string, if a string is provided, or a numerical quantity, with units, if such is provided. \\
{\tt x}, {\tt X}   & An integer value in hexadecimal (base~16). \\
{\tt \%}           & A literal {\tt \%} sign. \\
\hline
\end{tabular}
\end{center}
\caption{The conversion characters recognised by the string substitution operator, {\tt \%}.}
\label{tab:conversion_chars}
\end{table}

Where the character {\tt *} is specified for either the character width or the
precision of the substitution token, an integer is read from the list of items
to be substituted, as happens in C's {\tt printf} command:

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

\subsection{Converting strings to numbers}

Strings which contain numerical data can be converted to numbers by passing
them to the object {\tt types.number()}, as in the examples:

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

\noindent It is an error to try to convert a string to a number if it does not contain a correctly-formatted number:

\begin{dontdo}
types.number("this is not a number")
\end{dontdo}

\subsection{Slicing strings}

Segments of strings can be cut out by using square brackets to slice the string:

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

\noindent If a single number is placed in the square brackets, a single
character is taken out of the string. If two colon-separated numbers are
specified, {\tt [x:y]}, then the substring from character position {\tt x} up to
but not including {\tt y} is returned. If either {\tt x} or {\tt y} are
omitted, then the start or end of the string is used respectively. If either
number of negative, then it counts from the end of the string, $-1$ being the
last character in the string.

\subsection{String methods}

Strings have many methods for performing simple string manipulations. Here we
list their names using the {\tt foreach} command, which will be introduced in
the next chapter:

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

\noindent Full documentation of them can be found in
Section~\ref{sec:string_methods}. As in Python, the {\tt strip()} method
removes whitespace characters from the beginning and end of strings, and the
{\tt split()} method splits a string up into whitespace-separated words. The
{\tt splitOn(x)} method splits a string on all occurrences of the sub-string
{\tt x}.  The following examples demonstrate the use of some of them:

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

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

\subsection{Regular expressions}

String variables can be modified using the search-and-replace string
operator\index{string operators!search and replace}\footnote{Programmers with
experience of {\tt perl} will recognise this syntax.}, =$\sim$\index{=$\sim$
operator}, which takes a regular expression with a syntax similar to that
expected by the shell command {\tt sed}\index{sed shell command@{\tt sed} shell
command} and applies it to the specified string variable.\footnote{Regular
expression syntax is a massive subject, and is beyond the scope of this manual.
The official GNU documentation for the {\tt sed} command is heavy reading, but
there are many more accessible tutorials on the web.}\index{regular
expressions} In the following example, the first instance of the letter {\tt s} in
the string variable {\tt twister} is replaced with the letters {\tt th}:

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

Note that only the {\tt s} (substitute) command of {\tt sed} is implemented in
Pyxplot. Any character can be used in place of the {\tt /} characters in the
above example, for example:

\begin{verbatim}
twister =~ s's'th'
\end{verbatim}

\noindent Flags can be passed, as in {\tt sed} or {\tt perl}, to modify the
precise behaviour of the regular expression. In the following example the {\tt
g} flag is used to perform a global search-and-replace of all instances of the
letter {\tt s} with the letters {\tt th}:

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

\noindent Table~\ref{tab:re_flags} lists all of the regular expression flags
recognised by the =$\sim$ operator.

\begin{table}
{\footnotesize
\begin{tabular}{|>{\columncolor{LightGrey}}p{5mm}>{\columncolor{LightGrey}}p{10.5cm}|}
\hline
{\tt g} & Replace {\it all} matches of the pattern; by default, only the first match is replaced. \\
{\tt i} & Perform case-insensitive matching, such that expressions like {\tt [A-Z]} will match lowercase letters, too. \\
{\tt l} & Make {\tt $\backslash$w}, {\tt $\backslash$W}, {\tt $\backslash$b}, {\tt $\backslash$B}, {\tt $\backslash$s} and {\tt $\backslash$S} dependent on the current locale. \\
{\tt m} & When specified, the pattern character {\tt \^{}} matches the beginning of the string and the beginning of each line immediately following each newline. The pattern character {\tt \$} matches at the end of the string and the end of each line immediately preceding each newline. By default, {\tt \^{}} matches only the beginning of the string, and {\tt \$} only the end of the string and immediately before the newline, if present, at the end of the string. \\
{\tt s} & Make the {\tt .} special character match any character at all, including a newline; without this flag, {\tt .} will match anything except a newline. \\
{\tt u} & Make {\tt $\backslash$w}, {\tt $\backslash$W}, {\tt $\backslash$b}, {\tt $\backslash$B}, {\tt $\backslash$s} and {\tt $\backslash$S} dependent on the Unicode character properties database. \\
{\tt x} & This flag allows the user to write regular expressions that look nicer. Whitespace within the pattern is ignored, except when in a character class or preceded by an un-escaped backslash. When a line contains a {\tt \#}, neither in a character class nor preceded by an un-escaped backslash, all characters from the left-most such {\tt \#} through to the end of the line are ignored. \\
\hline
\end{tabular}}
\caption{A list of the flags accepted by the =$\sim$ operator. Most are rarely used, but the {\tt g} flag is very useful.}
\label{tab:re_flags}
\end{table}

\section{Lists}

List objects hold ordered sequences of other Pyxplot objects, which may
include lists and dictionaries to create hierarchical data structures. They are
created by enclosing a comma-separated list of objects by square brackets.

For example:

\begin{verbatim}
a = [10,colors.green,"bottles"]
\end{verbatim}

Once created, more items can be added to a list using its {\tt append(item)}
and {\tt insert(n,item)} methods, where the latter inserts an item at position
$n$:

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

\noindent
A complete list of the methods available on lists (itself a list of strings)
can be found by calling the method {\tt [].methods()}; they are also listed in
Section~\ref{sec:list_methods}. As with string methods, documentation of list
methods is returned if the method object is printed:

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

Most methods that operate on lists, for example, append, extend and sort
operations, return the list as their output. Unless this is stored in a
variable, Pyxplot prints this return value to the terminal. In some cases this
is useful: in the example above, it allowed us to see how the list was changing
when we called its {\tt append()} and {\tt insert()} methods. Often, however,
this terminal spam is unwanted. The \indcmdt{call} allows methods to be called
without printing their output, which is discarded:

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

\subsection{Using lists as stacks}

The following example demonstrates the use of a list as a stack; note that the
last item added to the stack is the first one to be popped:

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

\subsection{Using lists as buffers}

The following example demonstrates the use of a list as a buffer in which the
first item added to the stack is the first one to be popped:

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

\noindent The function {\tt prime(x)} returns true if {\tt x} is a prime
number, and false otherwise. In the final line, we make use of the fact that a
list tests true if it contains any items, or false if it is empty.

\subsection{Sorting lists}

Methods are provided for sorting data in lists. The simplest of these is the
{\tt sort()} method, which sorts the members into order of ascending
value.\footnote{Non-numeric items are assigned arbitrary but consistent values
for the purposes of sorting.  Booleans are always lower-valued than numbers,
but numbers are lower-valued than lists. Longer lists are always higher valued
than shorter lists; larger dictionaries are always higher-valued than smaller
dictionaries.} The {\tt reverse()} method can be used to invert the order of
the list afterwards if descending order is wanted.

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

\subsubsection{Custom sorting}

Often, however, a custom ordering is wanted. The {\tt sortOn(f)} method takes a
function of two arguments as its input. The function {\tt f(a,b)} should return
$-1$ if {\tt a} is to be placed before {\tt b} in the sorted list, $1$ if {\tt
a} is to be placed after {\tt b} in the sorted list, and zero if the two
elements have equal ranking.

\noindent The {\tt cmp(a,b)} function is often useful in making comparison
functions for use with the {\tt sortOn(f)} method: it returns either $-1$, $0$
or $1$ depending on Pyxplot's default way of comparing two objects. In the
example below, we pass it the magnitude of {\tt a} and {\tt b} to sort a list
in order of magnitude.

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

In this example, the {\tt range(start,end,step)} function is used to generate a
raster of values between $-8$ and $8$. It outputs a vector, which is converted
into a list using the vector's {\tt list()} method. More information about
vectors is in Section~\ref{sec:vectors}.

The subroutine command, which is often used to implement more complicated
sorting functions, will be covered in Section~\ref{sec:subroutines}. For
example, the function used above could have been written:

\begin{verbatim}
subroutine absCmp(a,b)
 {
  return cmp(abs(a),abs(b))
 }
\end{verbatim}

\subsubsection{Sorting lists of lists}

The {\tt sortOnElement(n)} method can be used to sort a list of lists on the
$n$th sub-element of each sublist.

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

\subsection{Iterating over lists}

The \indcmdt{foreach} can be used to iterate over the members of a list; it
will be covered in more detail in Section~\ref{sec:foreach}. The following
example iterates over the words in a sentence:

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

\subsection{Calling functions with lists of arguments}

The \indfunt{call($f,a$)} function can be used to call a function with an
arbitrary list of arguments. For example:

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

\subsection{List mapping and filtering}
\label{sec:listfilter}

The methods {\tt filter(f)}, {\tt map(f)} and {\tt reduce(f)} can be used to
perform actions on all of the members of a list in turn. {\tt filter(f)} takes
a function of one argument as its argument, and returns a new list of all of
the members {\tt x} of the original list for which {\tt f(x)} tests true. For
example:

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

The method {\tt map(f)} also takes a function of one argument as its argument,
and returns a list of the results {\tt f(x)} for each of the members {\tt x} of
the original list. In other words, if {\tt f} were {\tt sin}, and the original
list contained values of {\tt x}, the result would be a list of values of {\tt
sin(x)}. This example converts a list of numbers into Roman numerals:

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

The method {\tt reduce(f)} takes a function of two arguments as its argument. It
first calls $f(a,b)$ on the first two elements of the list, and then continues
through the list calling $f(a,b)$ on the result and the next item in the list.
The final result is returned:

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


\subsection{Vectors versus lists}

Vectors are similar to lists, except that all of their elements must be real
numbers, and that all of the elements of any given vector must share common
physical dimensions.  Vectors are stored much more efficiently in memory than
lists, since information about the types and physical units of each of the
elements need not be stored. In addition they support a wide range of vector
and matrix arithmetic operations.

Data from lists can also be plotted onto graphs, but the list must first be
converted into a vector. See~\ref{sec:vectors} for more information.

\section{Dictionaries}

Dictionaries, also known as associative arrays or content-addressable memories
in other programming languages, store collections of objects, each of which has
a unique name (or key). Objects are addressed by name, rather than by number:

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

As the first line of this example shows, dictionaries can be created by
enclosing a list of key--value pairs in curly brackets. As in python, a colon
separates each key from its corresponding value, while the list of key--value
pairs are comma-separated. That is, the general syntax is:
\begin{verbatim}
{ key1:value1 , key2:value2 , ... }
\end{verbatim}

It is also possible to generate an empty dictionary, as {\tt \{\}}. Items can
later be referenced or assigned by name, where the name is placed in square
brackets after the name of the dictionary. Items can be deleted with the
dictionary's {\tt delete(key)} method.

It is not an error to assign an item to a name which is already defined in the
dictionary; the new assignment overwrites the old object with that name. It is,
however, an error to attempt to access a key which is not defined in the
dictionary. The method {\tt hasKey(key)} may be used to test whether a key is
defined before attempting to access it.

Unlike in python, keys {\bf must} be strings.

\section{Vectors and matrices}
\label{sec:vectors}

Vectors are similar to lists, except that all of their elements must be real
numbers, and that all of the elements of any given vector must share common
physical dimensions.  Vectors are stored much more efficiently in memory than
lists, since information about the types and physical units of each of the
elements need not be stored. In addition they support a wide range of vector
and matrix arithmetic operations.

For example, applying the addition {\tt +} operator to two lists concatenates
the lists together, meanwhile the same operator applied to two vectors performs
vector addition:

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

In fact, whilst vectors do support the same {\tt append} and {\tt extend}
methods as lists, to add either a single new element, or a list of new
elements, to the end of the vector, these are very time consuming methods to
run. It is much more efficient to create a vector of the desired length, and
then to populate it with elements:

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

As the above example demonstrates, the {\tt vector()} prototype can take not
only a list or vector from which to make a vector object copy, but
alternatively a single integer, which creates a zeroed vector of the specified
length.

Similarly, the {\tt matrix()} prototype can create a matrix from a list of
lists, a list of vectors, a series of list arguments, a series of vector
arguments, or two integers. In the final case, a zero matrix with the specified
number of rows and columns is returned. If a matrix is specified as a series of
vectors, these are taken to be the columns of the matrix; but if the matrix is
specified as a series of lists, these are taken to be the rows of the matrix:

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

Like vectors, matrices can have physical units, and adding two matrices together performs element-wise addition:

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

\subsection{Dot and cross products}

The dot product of two vectors can be found simply by multiplying the two vectors together:

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

\noindent
The cross product of two vectors, which is only defined for pairs of three-element vectors, can be found by passing the two vectors to the {\tt cross(a,b)} function:

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


\subsection{Matrix algebra}

Matrices can be multiplied by one another and by vectors to perform matrix
arithmetic. This not only allows matrix equations to be solved, but also allows
transformation matrices to be applied to vector positions on the vector
graphics canvas. All of Pyxplot's vector graphics commands, which will be
described in detail in Chapter~\ref{ch:vector_graphics}, can accept positions
as either comma-separated numerical components, or as vector objects. The
following example demonstrates the use of a rotation matrix:

\begin{verbatim}
rotate(a) = matrix( [[cos(a),-sin(a)], \
                     [sin(a), cos(a)] ] )
pos = vector(0,5)*unit(cm)
theta = 30*unit(deg)
arrow from 0,0 to rotate(theta)*pos with linewidth 3
\end{verbatim}

In addition to matrix multiplication, other arithmetic operations are available
via the methods of matrix objects. Their methods {\tt diagonal()} and {\tt
symmetric()} return {\tt true} or {\tt false} as appropriate. Their {\tt size()}
method returns the vector size of the matrix (rows, columns). Their {\tt det()}
method returns the determinate of the matrix and their {\tt transpose()} method
returns the matrix transpose.

Among more complex operations, {\tt inv()} returns the inverse of a matrix,
{\tt eigen\-values()} returns a vector of the matrix's eigen\-values, and {\tt
eigen\-vectors()} returns a list of the matrix's corresponding eigen\-vectors.

\subsection{Plotting data from vectors}
\label{sec:vectorplot}

Vectors can be used to pass calculated data to the \indcmdt{plot} for plotting.
Instead of supplying the name of a \datafile, or a function to be plotted, a
series of colon-separated vector objects should be passed to the
\indcmdt{plot}. Each of the vectors should be the same length; the $n$th
elements of each of the vectors are put together to form the columns of data
for the $n$th \datapoint.

The following example draws 100 random points on a graph:

\begin{verbatim}
N=100
a=vector(N) ; b=vector(N)
for i=0 to 99 { a[i]=random.random() ; }
for i=0 to 99 { b[i]=random.random() ; }
plot [0:1][0:1] a:b
\end{verbatim}

Vectors support the same {\tt filter()}, {\tt map()} and {\tt reduce()} methods
as lists (see Section~\ref{sec:listfilter}), and these can prove especially
useful for preparing data for plotting. The following example selects fifty
random points along the $x$-axis, and uses them to plot $\sin(x)$:

\begin{verbatim}
N=50
a=vector(N)
for i=0 to 99 { a[i]=random.random() ; }
b=a.map(sin)
plot [0:1][0:1] a:b
\end{verbatim}

\section{Colors}
\label{sec:colorObjects}

Most of Pyxplot's graph plotting and vector graphics commands have settings for
specifying colors. A selection of widely-used colors may be specified by name,
for example {\tt red} and {\tt blue}. However, greater freedom in choice of
color is available by passing these commands objects of type {\tt color}.

Several functions are available for making color objects:

\begin{itemize}
\item {\tt gray(x)} returns a shade of gray. The argument $x$ should be in the range 0--1. If $x=0$, black is returned; if $x=1$, white is returned.
\item {\tt rgb(r,g,b)} returns a color with the specified RGB components, which should be in the range 0--1.
\item {\tt cmyk(c,m,y,k)} returns a color with the specified CMYK components, which should be in the range 0--1.
\item {\tt hsb(h,s,b)} returns a color with the specified coordinates in hue--saturation--brightness color space, which should be in the range 0--1.
\end{itemize}

\noindent In addition, color objects corresponding to all of Pyxplot's built-in
named colors can be found in the {\tt colors} module.

\begin{verbatim}
a = colors.red
b = rgb(0,0.5,0)
box from 0,0 to 3,3 with color a fillcolor b lw 5
\end{verbatim}

Once a color object has been made, various operations are supported.
Multiplying or dividing a color by a number changes the brightness of the
color. When two colors are compared, brighter colors are greater than darker
colors. When two colors are added together, they are additively mixed in RGB
space, so that adding red and green together produces yellow. When one color is
subtracted from another, the opposite happens, so that yellow minus green is
red.

\noindent The methods available on {\tt color} objects are listed in
Section~\ref{sec:color_methods}.

\subsection{Color representations of the electromagnetic spectrum}

Two functions, in the {\tt colors} module, provide color objects which
approximate the color of particular wavelengths of light, or of electromagnetic
spectra.

\funcdef{colors.wavelength($\lambda$,$norm$)}{returns a color representation of monochromatic light at wavelength $\lambda$, normalised to brightness $norm$. A value of $norm=1$ is recommended for plotting the complete span of the electromagnetic spectrum without colors clipping to white.}
\funcdef{colors.spectrum($spec,norm$)}{returns a color representation of the spectrum $spec$, normalised to brightness $norm$. $spec$ should be a function object that takes a single input (wavelength) with units of length, and may return an output with arbitrary units.}

\noindent For an example of the use of these functions, see
Section~\ref{sec:colormaps}.

\section{Dates}

Pyxplot has a {\tt date} object type which simplifies the process of working
with dates and times.  Pyxplot provides a range of pre-defined functions, in
the {\tt time} module, for creating and manipulating {\tt date} objects. The
functions for creating {\tt date} objects are as follows:

\funcdef{time.fromCalendar($year,month,day,hour,min,sec$)}{creates a date
object from the specified calendar date. It takes six inputs: the year, the
month number (1--12), the day of the month (1--31), the hour of day (0--24),
the number of minutes (0--59), and the number of seconds (0--59). To enter
dates before {\footnotesize AD}\,1, a year of~$0$ should be passed to indicate
1\,{\footnotesize BC}, $-1$ should be passed to indicate the year
2\,{\footnotesize BC}, and so forth. The \texttt{set calendar} command is used
to change the current calendar.}
\funcdef{time.fromJD($t$)}{creates a date object from the specified numerical Julian date.}
\funcdef{time.fromMJD($t$)}{creates a date object from the specified numerical modified Julian date.}
\funcdef{time.fromUnix($t$)}{creates a date object from the specified numerical Unix time.}
\funcdef{time.now()}{creates a date object representing the present time.}

The following example creates a date object representing midnight on 1st January 2000:

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

Once created, it is possible to add numbers with physical units of time to
dates, as in the following example:

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

\noindent In addition, if one date is subtracted from
another date, the time interval between the two dates is returned as a number
with physical dimensions of time:

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

Standard string representations of calendar dates can be produced with the {\tt
print} command.  It is also possible to use the string substitution operator,
as in {\tt "\%s"\%(date)}, or the {\tt str} method of {\tt date} objects, as in
{\tt date.str()}.  In addition, the {\tt time.string} function can be used to
choose a custom display format for the date; for more information, see
Section~\ref{sec:time_series}.

Several functions are provided for converting {\tt date} objects back into various numerical forms of timekeeping and components of calendar dates:

\methdef{toDayOfMonth()}{returns the day of the month of a date object in the current calendar.}
\methdef{toDayWeekName()}{returns the name of the day of the week of a date object.}
\methdef{toDayWeekNum()}{returns the day of the week (1--7) of a date object.}
\methdef{toHour()}{returns the integer hour component (0--23) of a date object.}
\methdef{toJD()}{converts a date object to a numerical Julian date.}
\methdef{toMinute()}{returns the integer minute component (0--59) of a date object.}
\methdef{toMJD()}{converts a date object to a modified Julian date.}
\methdef{toMonthName()}{returns the name of the month in which a date object falls.}
\methdef{toMonthNum()}{returns the number (1--12) of the month in which a date object falls.}
\methdef{toSecond()}{returns the seconds component (0--60) of a date object, including the non-integer component.}
\methdef{toUnix()}{converts a date object to a Unix time.}
\methdef{toYear()}{returns the year in which a date object falls in the current calendar.}

For example:

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

More information on the manipulation of {\tt date} objects can be found in Section~\ref{sec:time_series}.

\section{Modules and classes}

Modules provide a convenient way to group functions and variables together.
Pyxplot's default functions are grouped into modules such as {\tt os} and {\tt
random}.  New modules can be created by calling the {\tt module} object, which
is a synonym for {\tt types.module}. Once created, a module is like a
dictionary, except that its elements can be accessed both as {\tt module[item]}
and more commonly as {\tt module.item}. For example:

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

Modules can also serve as class prototypes. If a module is called like a
function, the return value is an {\it instance} of the module:

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

The module {\it instance} inherits all of the functions and variables of its
parent object, but may also contain its own additional functions and variables,
some of which may supersede those in the parent object if they have the same
name. When functions or subroutines of a module instance are called, the
special variable {\tt self} is defined to equal the module instance object.
This allows the function to store private data in the module instance, or to
call other methods on the instance.

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

As this example demonstrates, it is also possible to hierarchically instantiate
modules: {\tt tiddles} is an instance of {\tt cat}, which is itself an instance
of {\tt animal}.

\section{File handles}

File handles provide a means of reading data directly from text files, or of
writing data or logging information to files. Files are opened using the {\tt
open()} function:

\vspace{2mm}
\funcdef{open($x$[,$y$])}{opens the file $x$ with string access mode $y$, and returns a file handle object.}
\vspace{4mm}

\noindent The most commonly used access modes are {\tt "r"}, to open a file read-only, {\tt "w"}, to open a file for writing, erasing any pre-existing file of the same filename, and {\tt "a"}, to append data to the end of a file.

Alternatively, if what is wanted is a temporary scratch space, the {\tt os.tmpfile()} function should be used:

\vspace{2mm}
\funcdef{os.tmpfile()}{returns a file handle for a temporary file. The resulting file handle is open for both reading and writing.}
\vspace{4mm}

The following methods are defined for file handles:

\methdef{close()}{closes a file handle.}
\methdef{dump($x$)}{stores a typeable ASCII representation of the object $x$ to a file. Note that this method has no checking for recursive hierarchical data structures.}
\methdef{eof()}{returns a boolean flag to indicate whether the end of a file has been reached.}
\methdef{flush()}{flushes any buffered data which has not yet physically been written to a file.}
\methdef{getPos()}{returns a file handle's current position in a file.}
\methdef{isOpen()}{returns a boolean flag indicating whether a file is open.}
\methdef{read()}{returns the contents of a file as a string.}
\methdef{readline()}{returns a single line of a file as a string.}
\methdef{readlines()}{returns the lines of a file as a list of strings.}
\methdef{setPos($x$)}{sets a file handle's current position in a file.}
\methdef{write($x$)}{writes the string $x$ to a file.}

\subsection{Storing data structures in text files}

The {\tt dump(x)} method of file handles is provided as a means of writing a
typeable ASCII representation of the object {\tt x} to file, for later recovery
using the {\tt load} command. It is similar to the {\tt pickle()} function in
Python.

There is no limit to the depth to which it will traverse hierarchically nested
data structures, and will produce output of infinite length if there is
recursive nesting.

Note that it is not able to store representations of function definitions or
file handles, which are stored as null objects; class instances lose their
relationship with their parents and are stored as free-standing modules.