\documentclass[11pt,a4paper]{article}
\usepackage[LGR,T1]{fontenc}
\usepackage[greek,english]{babel}
\usepackage[utf8]{inputenc}
\usepackage[unicode,pdftex,bookmarks,colorlinks,linkcolor=blue]{hyperref}
\usepackage{verbatim}
\usepackage[margin=2cm]{geometry}
%\usepackage{wrapfig,graphicx}
\usepackage{mathtools} % loads amsmath
%\usepackage{amssymb}
\pagestyle{plain}

%% formatting
% use a san-serif font for online display
\renewcommand\familydefault{cmss}
\usepackage{parskip}

\author{Martin Gregory}
\title{REDUCE functions provided by redcas}
%\VignetteIndexEntry{REDUCE functions provided by redcas}
\begin{document}
\maketitle
\tableofcontents

%%
%% introduction
%%
\section{Introduction}
\label{sec:intro}
The {\it redcas} package provides a number of REDUCE procedures which are required for the
package to function. While knowledge of these procedures is not needed to use {\it
  redcas}, they may be of interest for use in REDUCE itself. There
are three types of procedures. The first type produce outputs in a format which can be
used by {\it redcas}. The second type are utility procedures needed by the first
type. Finally there are declarations of symbolic procedures for use in algebraic mode
using the{ \tt symbolic operator} statement. This third type are also utilites used by the
first type.

%%
%% Extracting the reduce functions
%%
\section{Extracting the REDUCE code}
All procedures are included in the file {\it redcas.red} in the {\it reduce} directory of
the installed package. You can extract the code to a location of your choice
using the following code:
\begin{verse}
  file.copy(system.file("reduce/redcas.red", package="redcas"), "mydir")
\end{verse}
where {\it mydir} is a writable directory of your choice. 

%%
%% Output procs
%%
\section{Output procedures}
\label{sec:output-procs}

%%
%% asltx
%%
\subsection{asltx: calls arrayltx or exprltx depending on the object type}
\label{sec:asltx}

\begin{description}
\item [Syntax] 
\begin{verbatim}
  asltx(x, math, mode, name) ;
  arrayltx (arrx, math, mode, name) ;
  exprltx(expr, math, mode, name) ;
\end{verbatim}
where
\begin{description}
\item [x] identifier of an object to be typeset.
\item [arrx] identifier of an array.
\item [expr] an expression or identifier of such.
\item [math] string naming a \LaTeX{} math environment to enclose the expression or each
  element of an array. If empty no math environment is written.
\item [mode] string naming the print mode: nat|fancy. {\it nat} is the standard REDUCE
  plain text output while {\it fancy} produces \LaTeX{} output using the REDUCE package
  TMPRINT. If not specified, defaults to nat.
\item [name] string providing the name to use when printing.
\end{description}

\item [Details] {\it asltx} is a convenience function which calls {\it arrayltx} for
  arrays, {\it exprltx} for expressions and returns an error for any other type.

  {\it arrayltx} accepts an array of arbitrary dimensions and displays each element using
  the specified mode.

  {\it exprltx} prints an expression using the specified mode. Expressions may be
  unbound identifiers or those containing an expression, equation or matrix. Explicit
  expressions may also be specified.

  Since REDUCE procedures do not support named arguments\footnote{lists might be used},
  all arguments must be specified.

  Plain text has two modes controlled by the NAT switch. When on, the default, expressions
  will print on multiple lines if they include exponents or fractions. When off,
  expressions   print on a single line in the form expressions are input and include as
  terminator the dollar sign. 

  Since there is a print method for matrices a math mode will enclose the entire matrix,
  not the elements.
  
\item [Value] None. Called for side effect of producing the output in the desired format.
\end{description}

%%
%% utility procs
%%
\section{Utility procedures}
\label{sec:util-procs}

%%
%% array2flatls
%%
\subsection{array2flatls: converts an array to a flattened list}
\label{sec:array2flatls}
{\it array2flatls} converts an array to a flattened list using the procedure {\it
  array\_to\_list} from the REDUCE package ASSIST and a for loop using the {\it join}
action.  This is called by {\it arrayltx} to allow handling arrays with an arbitrary
number of dimensions.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  array2flatls(arrx) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [arrx] identifier of array to convert
\end{description}

\item [Value] A list containing the elements of the array. Assuming the array has $n$
  dimensions the list will have depth $n$ and the array element $(i_1, \ldots, i_n)$ is
  found by descending the list in the order of $i_j$. In terms of the dot operator from
  the ASSIST package and assuming the list is named $l$, this would be
  $(((l.i_1).i_2). \ldots).i_n$ or in R notation $l[[i_1]][[i_2]] \ldots [[i_n]]$

\end{description}


%%
%% asltx_marker
%%
\subsection{asltx\_marker: mark output for extraction}
\label{sec:asltx_marker}
{\it asltx\_marker} calls {\it asltx} and encloses the output between a line {\tt
  \#\#START label} and {\tt \#\#END label}, so that it can be easily extracted from a
REDUCE log.

%% \begin{enumerate}
%% \item {\color{red}also export redSplitOut or just call it from redExtract?}
%% \item {\color{red} do this in 1.0.1 or wait for next version?}  
%% \item {\color{red} consider this for the markers:}
%% \begin{verbatim}
%%   ##< label
%%   output
%%   ##> label
%% \end{verbatim}
%% \end{enumerate}

\begin{description}
\item [Syntax] 
\begin{verbatim}
  asltx_marker (thing,  math, mode, name, label) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [x] identifier of an object to be typeset.
\item [math] string naming a \LaTeX{} math environment in which to enclose each array
  element. If empty no math environment is written.
\item [mode] string naming the print mode: nat|fancy. {\it nat} is the standard REDUCE
  output while {\it fancy} produces \LaTeX{} output using the REDUCE package TMPRINT. If not
  specified, defaults to nat.
\item [name] string providing the name to use when printing expressions.
\item [label] an arbitrary string to identify the output.
\end{description}

\item [Details] This procedure allows extraction of specific outputs from the log of a
  reduce program which has been run  independently of {\it redcas}

  %% or using  or {\it
  %%   redcas::redBatch}. While extraction can be done using any program, {\it
  %%   redcas::redExtract} provides a way to do this.

\item [Value] None. Called for side effect of producing the output in the desired format
  enclosed in the start and end markers. This function is used by some package tests to
  extract output from REDUCE programs executed outside {\it redcas}.
\end{description}

%%
%% atoi
%%
\subsection{atoi: converts a string to an integer}
\label{sec:atoi}
{\it atoi} converts a string containing an integer or float in base 10 to a number.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  atoi(string) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [string] a string containing only base 10 digits and a single period.
\end{description}

\item [Value] a number. ROUNDED must be off in order to convert a float.
\end{description}

%%
%% itoa
%%
\subsection{itoa: converts an integer to a string}
\label{sec:itoa}
{\it itoa} converts an integer to a string. Useful for formatting output.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  itoa(integer) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [integer] an arbitrary integer.
\end{description}

\item [Value] a string representation of the integer.
\end{description}

%%
%% list_dialect
%%
\subsection{lisp\_dialect}
\label{sec:lisp_dialect}
{\it lisp\_dialect} determines whether REDUCE is running under CSL or PSL 
\begin{description}
\item [Syntax] 
\begin{verbatim}
  lisp_dialect() ;
\end{verbatim}

\item [Arguments] None

\item [Details] this function is intended for use in a condition, for example
\begin{verbatim}
  if lisp_dialect = 'csl then ... ;
\end{verbatim}

\item [Value] the quoted symbol {\tt 'csl} or {\tt 'psl}
\end{description}

%%
%% swget
%%
\subsection{swget}
\label{sec:swget}
{\it swget} tests whether a REDUCE switch is on or off.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  swget(s) 
\end{verbatim}
where
\begin{description}
\item [s] the identifier of the switch to test 
\end{description}

\item [Details] if the value of {\it swget} is {\it nil} it prints as blank. It should
  only be used in a condition, for example,
\begin{verbatim}
   if swget(echo) then write "on" else write "off";
\end{verbatim}
\item [Value] Boolean.
\end{description}

%%
%% swreset
%%
\subsection{swreset}
\label{sec:swreset}
{\it swreset} restores the status of switches which were toggled by {\it swset}.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  swreset(l) 
\end{verbatim}
where
\begin{description}
\item [l] the identifier of the list of toggled switches produced by {\it swset}. 
\end{description}

\item [Details] {\it swreset} uses {\it swtoggle} to restore the
  previous state and displays the restored state 

  Independently of {\it swset} an explicit list may also be passed in order to toggle
  multiple switches.

\item [Value] None.
\end{description}

%%
%% swset
%%
\subsection{swset}
\label{sec:swset}
{\it swset} ensures that one or more switches are in a desired state.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  swset(lon, loff) 
\end{verbatim}
where
\begin{description}
\item [lon] is a list, or identifier of the list, of switches which should be on.
\item [loff] is a list, or identifier of the list, of switches which should be off.
\end{description}

\item [Details] {\it swset} checks the current state of each switch in {\it lon} and {\it
  loff} and if it is not in the desired state uses {\it swtoggle} to
  change it.

\item [Value] A list of the switches which were toggled. This can be later passed to {\it
  swreset} in order to restore the original state.
\end{description}

%%
%% swtoggle
%%
\subsection{swtoggle}
\label{sec:swtoggle}
{\it swtoggle} toggles a REDUCE switch.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  swtoggle(s) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [s] the identifier of the switch to toggle 
\end{description}

\item [Value] the new state of the switch.
\end{description}

%%
%% symbolic procs
%%
\section{Symbolic procedures}
\label{sec:sym-procs}
This section describes existing symbolic procedures which have been declared algebraic by
using the {\tt symbolic operator} statement.

%%
%% arrayp
%%
\subsection{arrayp: array predicate}
\label{sec:arrayp}
{\it arrayp} is a predicate function to test whether an object is an array or not.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  array(x)  
\end{verbatim}

\item [Arguments]
\begin{description}
\item [x] an identifier to test
\end{description}

\item [Details]  if the value of {\it arrayp} is {\it nil} it prints as blank. It should
  only be used in a condition, for example,
\begin{verbatim}
   if arrayp(x) then ... ;
\end{verbatim}
\item [Value] Boolean.
\end{description}

%%
%% concat
%%
\subsection{concat: concatenate 2 strings}
\label{sec:concat}
{\it concat} concatenates two strings.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  result := concat(a, b) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [a] first string
\item [b] second string
\end{description}

\item [Details]

\item [Value] string containing the concatenation of the first and second strings.
\end{description}

%%
%% gettype
%%
\subsection{gettype: distinguishing arrays from "simple" expressions}
\label{sec:gettype}
{\it gettype} returns the type of an identifier.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  gettype(x)
\end{verbatim}

\item [Arguments]
\begin{description}
\item [x] the object for which type should be returned
\end{description}

\item [Details] {\it gettype} is used by {\it asltx} to determine whether to call {\it
  arrayltx} or {\it exprltx}.

\item [Value] the type of the object as a quoted identifier, for example, {\tt 'array}.
\end{description}

%%
%% id2string
%%
\subsection{id2string}
\label{sec:id2string}
{\it id2string} returns an identifier's name as a string
\begin{description}
\item [Syntax] 
\begin{verbatim}
  id_as_string := id2string(x) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [x] identifier whose name is to be returned as a string
\end{description}
\item [Value] string containing the name of the identifier.
\end{description}

%%
%% onoff
%%
\subsection{onoff: required by swtoggle}
\label{sec:onoff}
{\it onoff} is a symbolic function which sets a switch.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  onoff(s, bool) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [s] identifier of the switch.
\item [bool] a boolean to set the switch on (t) or off (nil).
\end{description}

\item [Details] This is used by swtoggle.

\item [Value] None, used for side effect of changing switch state.
\end{description}

%%
%% tex_string
%%
\subsection{tex\_string: render string as \LaTeX}
\label{sec:tex_string}
{\it tex\_string} prevents REDUCE replacing \textbackslash{} with
\textbackslash{}textbackslash and \{\} with \textbackslash\{\textbackslash\} when the FANCY
switch is on.
\begin{description}
\item [Syntax] 
\begin{verbatim}
  result := tex_string(s) ;
\end{verbatim}

\item [Arguments]
\begin{description}
\item [s] a string to render as \LaTeX
\end{description}

\item [Details] {\it redcas} uses {\it tex\_string} when writing the math environment to
  ensure the string is not modified.

\item [Value] the original string without the unwanted conversions.
\end{description}

\end{document}