
			Input/output and plotting

*INTRO
This chapter contains commands to use for input and output and plotting. All output
commands write to the same destination stream, called the "current
output". This is initially the screen, but may be
redirected by some commands. Similarly, most input commands
read from the "current input" stream, which can also be redirected. The
exception to this rule are the commands for reading script files,
which simply read a specified file.

*CMD FullForm --- print an expression in LISP-format
*CORE
*CALL
	FullForm(expr)

*PARMS

expr - expression to be printed in LISP-format

*DESC

Evaluates "expr", and prints it in LISP-format on the current
output. It is followed by a newline. The evaluated expression is also
returned.

This can be useful if you want to study the internal representation of
a certain expression.

*E.G.

	In> FullForm(a+b+c);
	(+ (+ a b )c )
	Out> a+b+c;
	In> FullForm(2*I*b^2);
	(* (Complex 0 2 )(^ b 2 ))
	Out> Complex(0,2)*b^2;

The first example shows how the expression {a+b+c} is
internally represented. In the second example, {2*I} is
first evaluated to {Complex(0,2)} before the expression
is printed.

*SEE LispRead, Listify, Unlist

*CMD Echo --- high-level printing routine
*STD
*CALL
	Echo(item)
	Echo(list)
	Echo(item,item,item,...)

*PARMS

{item} -- the item to be printed

{list} -- a list of items to be printed

*DESC

If passed a single item, {Echo} will evaluate it and print it to the
current output, followed by a newline. If {item} is a string, it is
printed without quotation marks.

If there is one argument, and it is a list, {Echo} will print all the
entries in the list subsequently to the current output, followed by a
newline. Any strings in the list are printed without quotation
marks. All other entries are followed by a space.

{Echo} can be called with a variable number of arguments, they will all
be printed, followed by a newline.

{Echo} always returns {True}.

*E.G.

	In> Echo(5+3);
	 8
	Out> True;
	In> Echo({"The square of two is ", 2*2});
	The square of two is 4
	Out> True;
	In> Echo("The square of two is ", 2*2);
	The square of two is 4 
	Out> True;

Note that one must use the second calling format if one wishes to
print a list:

	In> Echo({a,b,c});
	a b c
	Out> True;
	In> Echo({{a,b,c}});
	{a,b,c}
	Out> True;

*SEE PrettyForm, Write, WriteString, RuleBaseListed

*CMD PrettyForm --- print an expression nicely with ASCII art
*STD
*CALL
	PrettyForm(expr)

*PARMS

expr - an expression

*DESC

PrettyForm renders an expression in a nicer way, using ascii art.
This is generally useful when the result of a calculation is more
complex than a simple number.

*E.G.

	In> Taylor(x,0,9)Sin(x)
	Out> x-x^3/6+x^5/120-x^7/5040+x^9/362880;
	In> PrettyForm(%)
	
	     3    5      7       9
	    x    x      x       x
	x - -- + --- - ---- + ------
	    6    120   5040   362880
	
	Out> True;

*SEE EvalFormula, PrettyPrinter

*CMD EvalFormula --- print an evaluation nicely with ASCII art
*STD
*CALL
	EvalFormula(expr)

*PARMS

expr - an expression

*DESC

Show an evaluation in a nice way, using PrettyPrinter
to show 'input = output'.

*E.G.

	In> EvalFormula(Taylor(x,0,7)Sin(x))
	
	                                      3    5
	                                     x    x  
	Taylor( x , 0 , 5 , Sin( x ) ) = x - -- + ---
	                                     6    120
	
	Out> True

*SEE PrettyForm

*CMD TeXForm --- export expressions to $LaTeX$
*STD
*CALL
	TeXForm(expr)

*PARMS

{expr} -- an expression to be exported

*DESC

{TeXForm} returns a string containing a $LaTeX$ representation of the Yacas expression {expr}. Currently the exporter handles most expression types but not all.

*EG

	In> TeXForm(Sin(a1)+2*Cos(b1))
	Out> "$\sin a_{1} + 2 \cos b_{1}$";

*SEE PrettyForm, CForm, ShowPS

*CMD CForm --- export expression to C code
*STD
*CALL
	CForm(expr)
	
*PARMS

{expr} -- expression to be exported

*DESC

{CForm} returns a string containing a C/C++ code implementing the Yacas expression {expr}. Currently the exporter handles most expression types but not all.

*EG

	In> CForm(Sin(a1)+2*Cos(b1));
	Out> "sin(a1) + 2 * cos(b1)";

*SEE PrettyForm, TeXForm

*CMD Write --- low-level printing routine
*CORE
*CALL
	Write(expr, ...)

*PARMS

{expr} -- expression to be printed

*DESC

The expression "expr" is evaluated and written to the current
output. Note that Write accept an arbitrary number of arguments, all
of which are written to the current output (see second
example). {Write} always returns {True}.

*E.G.

	In> Write(1);
	1Out> True;
	In> Write(1,2);
	 1 2Out> True;

Write does not write a newline, so the {Out>} prompt
immediately follows the output of {Write}.

*SEE Echo, WriteString

*CMD WriteString --- low-level printing routine for strings
*CORE
*CALL
	WriteString(string)

*PARMS

{string} -- the string to be printed

*DESC

The expression "string" is evaluated and written to the current
output without quotation marks. The argument should be a
string. WriteString always returns True.

*E.G.

	In> Write("Hello, world!");
	"Hello, world!"Out> True;
	In> WriteString("Hello, world!");
	Hello, world!Out> True;

This example clearly shows the difference between Write and
WriteString. Note that Write and WriteString do not write a newline,
so the {Out>} prompt immediately follows the output.

*SEE Echo, Write

*CMD Space --- print one or more spaces
*STD
*CALL
	Space()
	Space(nr)

*PARMS

{nr} -- the number of spaces to print

*DESC

The command {Space()} prints one space on the
current output. The second form prints {nr} spaces on the current
output. The result is always True.

*E.G.

	In> Space(5);
	     Out> True;

*SEE Echo, Write, NewLine

*CMD NewLine --- print one or more newline characters
*STD
*CALL
	NewLine()
	NewLine(nr)

*PARMS

{nr} -- the number of newline characters to print

*DESC

The command {NewLine()} prints one newline character
on the current output. The second form prints "nr" newlines on the
current output. The result is always True.

*E.G.

	In> NewLine();
	
	Out> True;

*SEE Echo, Write, Space

*CMD FromFile --- connect current input to a file
*CORE
*CALL
	FromFile(name) body

*PARMS

{name} - string, the name of the file to read

{body} - expression to be evaluated

*DESC

The current input is connected to the file "name". Then the expression
"body" is evaluated. If some functions in "body" try to read
from current input, they will now read from the file "name". Finally, the
file is closed and the result of evaluating "body" is returned.

*E.G.

Suppose that the file {foo} contains

	2 + 5;

Then we can have the following dialogue:

	In> FromFile("foo") res := Read();
	Out> 2+5;
	In> FromFile("foo") res := ReadToken();
	Out> 2;

*SEE ToFile, FromString, Read, ReadToken

*CMD FromString --- connect current input to a string
*CORE
*CALL
	FromString(str) body;

*PARMS

str - a string containing the text to parse

body - expression to be evaluated

*DESC

The commands in "body" are executed, but everything that is read
from the current input is now read from the string "str". The
result of "body" is returned.

*E.G.

	In> FromString("2+5; this is never read") \
	  res := Read();
	Out> 2+5;
	In> FromString("2+5; this is never read") \
	  res := Eval(Read());
	Out> 7;

*SEE ToString, FromFile, Read, ReadToken

*CMD ToFile --- connect current output to a file
*CORE
*CALL
	ToFile(name) body

*PARMS

name - string, the name of the file to write the result to

body - expression to be evaluated

*DESC

The current output is connected to the file "name". Then the expression
"body" is evaluated. Everything that the commands in "body" print
to the current output, ends up in the file "name". Finally, the
file is closed and the result of evaluating "body" is returned.

*E.G.

Here is how one can create a file with C code to evaluate an expression:

	In> ToFile("expr1.c") WriteString(
	  CForm(Sqrt(x-y)*Sin(x)) );
	Out> True;
The file {expr1.c} was created in the current working directory and it contains
	sqrt(x-y)*sin(x)

As another example, take a look at the following command:

	In> [ Echo("Result:");  \
	  PrettyForm(Taylor(x,0,9) Sin(x)); ];
	Result:
	
	     3    5      7       9
	    x    x      x       x
	x - -- + --- - ---- + ------
	    6    120   5040   362880
	
	Out> True;

Now suppose one wants to send the output of this command to a
file. This can be achieved as follows:

	In> ToFile("out") [ Echo("Result:");  \
	  PrettyForm(Taylor(x,0,9) Sin(x)); ];
	Out> True;

After this command the file {out} contains:

	
	Result:
	
	     3    5      7       9
	    x    x      x       x
	x - -- + --- - ---- + ------
	    6    120   5040   362880
	

*SEE FromFile, ToString, Echo, Write, WriteString, PrettyForm, Taylor

*CMD ToString --- connect current output to a string
*CORE
*CALL
	ToString() body

*PARMS

body - expression to be evaluated

*DESC

The commands in "body" are executed. Everything that is printed on
the current output, by {Echo} for instance, is
collected in a string and this string is returned.

*E.G.

	In> str := ToString() [ WriteString(  \
	  "The square of 8 is "); Write(8^2); ];
	Out> "The square of 8 is  64";

*SEE FromFile, ToString, Echo, Write, WriteString

*CMD Read --- read an expression from current input
*CORE
*CALL
	Read()

*DESC

Read an expression from the current input, and return it unevaluated. When
the end of an input file is encountered, the token atom {EndOfFile} is returned.

*E.G.

	In> FromString("2+5;") Read();
	Out> 2+5;
	In> FromString("") Read();
	Out> EndOfFile;

*SEE FromFile, FromString, LispRead, ReadToken, Write

*CMD LispRead --- read an expression in LISP-syntax
*CORE
*CALL
	LispRead()

*DESC

Read an expression in LISP syntax from the current input, and return
it unevaluated. When the end of an input file is encountered, the
token atom {EndOfFile} is returned.

The expression {a+b} is written in LISP syntax as {(+ a b)}. The advantage of this syntax is that it is
less ambiguous than the infix operator grammar that Yacas uses by
default.

*E.G.

	In> FromString("(+ a b)") LispRead();
	Out> a+b;
	In> FromString("(List (Sin x) (- (Cos x)))") \
	  LispRead();
	Out> {Sin(x),-Cos(x)};

*SEE FromFile, FromString, Read, ReadToken, FullForm

*CMD ReadToken --- read an token from current input
*CORE
*CALL
	ReadToken()

*DESC

Read a token from the current input, and return it unevaluated. When
the end of an input file is encountered, the token atom {EndOfFile} is returned.

A token is for computer languages what a word is for human languages:
it is the smallest unit in which a command can be divided, so that the
semantics (that is the meaning) of the command is in some sense a
combination of the semantics of the tokens. Hence {a := foo} consists of three tokens, namely {a}, {:=}, and {foo}.

*E.G.

	In> FromString("a := Sin(x)") While \
	  ((tok := ReadToken()) != EndOfFile) \
	  Echo(tok);
	a
	:=
	Sin
	(
	x
	)
	Out> True;

*SEE FromFile, FromString, Read, LispRead

*CMD Load --- evaluate all expressions in a file
*CORE
*CALL
	Load(name)

*PARMS

name - string, name of the file to load

*DESC

The file "name" is opened. All expressions in the file are read and
evaluated. {Load} always returns {true}.

*SEE Use, DefLoad, DefaultDirectory, FindFile

*CMD Use --- load a file, but not twice
*CORE
*CALL
	Use(name)

*PARMS

name - string, name of the file to load

*DESC

If the file "name" has been loaded before, either by an earlier call
to {Use} or via the {DefLoad}
mechanism, nothing happens. Otherwise all expressions in the file are
read and evaluated. {Use} always returns {true}.

The purpose of this function is to make sure that the file will at
least have been loaded, but is not loaded twice.

*SEE Load, DefLoad, DefaultDirectory

*CMD DefLoad --- load a {.def} file
*CORE
*CALL
	DefLoad(name)

*PARMS

name - string, name of the file (without {.def} suffix)

*DESC

The suffix {.def} is appended to "name" and the
file with this name is loaded. It should contain a list of functions,
terminated by a closing brace \} (the end-of-list delimiter). This
tells the system to load the file "name" as soon as the user calls
one of the functions named in the file (if not done so already). This
allows for faster startup times, since not all of the rules databases
need to be loaded, just the descriptions on which files to load for
which functions.

*SEE Load, Use, DefaultDirectory

*CMD FindFile --- find a file in the current path
*CORE
*CALL
	FindFile(name)

*PARMS

name - string, name of the file or directory to find

*DESC

The result of this command is the full path to the file that would be
opened when the command {Load(name)} would be
invoked. This means that the input directories are subsequently
searched for a file called "name". If such a file is not found, {FindFile} returns an empty string.

{FindFile("")} returns the name of the default directory (the first one on the search path).

*SEE Load, DefaultDirectory

*CMD PatchLoad --- execute commands between {<?} and {?>} in file
*CORE
*CALL
	PatchLoad(name)

*PARMS

name - string, name of the file to "patch"

*DESC

{PatchLoad} loads in a file and outputs the contents to the current
output. The file can contain blocks delimited by {<?} and {?>}
(meaning "Yacas Begin" and "Yacas End"). The piece of text between
such delimiters is treated as a separate file with Yacas instructions,
which is then loaded and executed. All output of write statements
in that block will be written to the same current output.

This is similar to the way PHP works. You can have a static text file
with dynamic content generated by Yacas.

*SEE PatchString, Load

*CMD Nl --- the newline character
*STD
*CALL
	Nl()

*DESC

This function returns a string with one element in it, namely a newline
character. This may be useful for building strings to send to some
output in the end.

Note that the second letter in the name of this command is a lower
case {L} (from "line").

*E.G.

	In> WriteString("First line" : Nl() : "Second line" : Nl());
	First line
	Second line
	Out> True;

*SEE NewLine

*CMD V, Verbose --- set verbose output mode
*STD
*CALL
	V(expression)

*PARMS

{expression} -- expression to be evaluated in verbose mode

*DESC

The function {V(expression)} will evaluate the expression in 
verbose mode. Various parts of Yacas can show extra information
about the work done while doing a calculation when using {V}.

The function is currently implemented using a global variable {Verbose} which can be set to {True} or {False}.

*E.G.

	In> Solve({x+2==0},{x})
	Out> {{-2}};
	In> V(Solve({x+2==0},{x}))
	Entering Solve
	From  x+2==0  it follows that  x  = -2 
	   x+2==0  simplifies to  True 
	Leaving Solve
	Out> {{-2}};

*SEE Echo, N, Solve



*CMD Plot2D --- adaptive two-dimensional plotting
*STD
*CALL
	Plot2D(f(x))
	Plot2D(f(x), a:b)
	Plot2D(f(x), a:b, option=value)
	Plot2D(f(x), a:b, option=value, ...)
	Plot2D(list, ...)

*PARMS

{f(x)} -- unevaluated expression containing one variable (function to be plotted)

{list} -- list of functions to plot

{a}, {b} -- numbers, plotting range

{option} -- atom, option name

{value} -- atom, number or string (value of option)

*DESC
The routine {Plot2D} performs adaptive plotting of one or several functions
of one variable in the specified range. Several functions are specified by
giving a list of expressions. Various plotting options can be
specified. Output can be directed to a plotting program (the default is to use
{gnuplot}), to a data file, or to a list of values.

The function parameter {f(x)} must be an unevaluated expression containing
a variable (not necessarily called {x}). Several functions may be specified as a list and they do not have to depend on the same variable, for example, {{f(x), g(y)}}.

Data files are created in a temporary directory {/tmp/plot.tmp/}. File names
and other information is printed if the {Verbose} option is switched on using {V()}.

The current algorithm uses Newton-Cotes quadratures and some heuristics for error estimation (see the essay chapter on adaptive plotting).
The initial grid of {points+1} points is refined between any grid points $a$, $b$ where the integral
$Integrate(x,a,b)f(x)$ is not approximated within given precision by
the existing grid.

Default plotting range is {-5:5}. Range can also be specified by {x=-5:5};
currently the variable name {x} is ignored.

Options are of the form {option=value}. Currently supported option names
are: "points", "precision", "depth", "output", "filename". Option values
are either numbers or special unevaluated atoms such as {data}. If names of these atoms
are needed in the program, strings can be used (e.g. {output="gnuplot"}). Several option/value pairs may be specified (the function {Plot2D} has a variable number of arguments).

*	{points}: initial number of points (default 23) -- at least that
many points will be plotted. The initial grid of this many points will be
adaptively refined. 
*	{precision}: graphing precision (default $10^(-6)$). This is interpreted as the relative precision of computing the integral of $f(x)-Min(f(x))$ using the grid points. For a smooth, non-oscillating function this value should be roughly 1/(number of screen pixels in the plot).
*	{depth}: max. refinement depth, logarithmic (default 5) -- means there will be at most $2^depth$ extra points per initial grid point.
*	{output}: symbolic name of the plotting backend. Supported values:
{gnuplot} (default), {plotutils}, {datafile}, {data}. The {gnuplot} value will display
the plot on the screen (requires the {gnuplot} program). The {plotutils}
value requires the GNU {plotutils} suite and the {graph} program (under X Window).The {datafile} value will write the data to a text file with specified name. The {data} value will return the data as a list of pairs such as {{{x1,y1}, {x2,y2}, ...}}
*	{filename}: specify name of the output file (currently used only by the {datafile} output option). For example: {filename="data1.txt"}. Default is the name {"output.data"}.

Other options may be supported in the future. Note that currently the
support for {gnuplot} and GNU {plotutils} is Unix-specific.

A frequently encountered problem: the parameter {f(x)} <i>must</i> evaluate to
an expression that contains a variable (or to a constant). Test your function
for this! If you have defined some {f(x)} which accepts a number but does not
accept an undefined variable, {Plot2D} will fail to plot it. Use
{NFunction} to overcome this difficulty.

The current implementation can deal with a singularity at endpoints or at any
grid point only if the function {f(x)} returns {Infinity}, {-Infinity} or
{Undefined}. If the function {f(x)} generates a numerical error and fails at a
singularity, {Plot2D} will fail too, if one of the grid points falls on the
singularity. (All grid points are generated by bisection so in principle the
endpoints and the {points} parameter could be chosen to avoid numerical
singularities.)


*E.G.
	In> Plot2D({(2+x)/(2-x),Exp(y)},-1.8:1.5)
	Out> True;
	In> V(Plot2D(Sin(1/x),0:1, depth=4, \
	In>   precision=0.001, output=plotutils))
	Plot2D: using 65 points for function Sin(1/x)
	Plot2D'datafile: created file '/tmp/plot.tmp/data1'
	Out> True;

If a function takes a long time to evaluate, one can use
{MakeFunctionPlugin} (a Unix-specific tool) to compile the function and plot it faster:

	In> f(x) := Cos( (Abs(Pi/x))^1.5 )
	Out> True;
	In> Time( Plot2D(f(x),0:1) )
	94.93 seconds taken
	Out> True;
	In> MakeFunctionPlugin("f1", f(x))
	Function f1(x) loaded from plugins.tmp/
	  libf1_plugin_cc.so
	Out> True;
	In> Time( Plot2D(f1(x),0:1) )
	6.97 seconds taken
	Out> True;


*SEE V, NFunction, MakeFunctionPlugin

