\section{\&} The `\&' operator forces \fudgit\ to use the built-in following fitting mode command and to ignore any existing macro or alias with the same name. This can be useful in constructions like: \nopagebreak\begin{verbatim} macro cd 1 pmode cd "$1" &cd $1 # The built-in cd stop \end{verbatim} \Seealso \bq macro, cd \eq \section{$\backslash$} If anywhere in the middle of a line, a `\verb+\+' will indicate \fudgit\ to take the following character as is. If at the end of a line, a `\verb+\+' indicates that the present line continues on the following one, and thus to ignore the following carriage return. \Seealso \bq line editing\eq \section{!} Any line beginning with the so-called bang operator `!' will execute the system command line with a Bourne shell. Aliased commands as found in your interactive C-shell do not hold any more. For example, commands like {\tt !rm} will not be interactive (i.e. /bin/rm -i) even if you have such an alias in your {\it .cshrc} file. Be careful! A nice turnaround is to alias rm to `{\tt ! rm -i}' in your {\it .fudgitrc} file and to use the {\tt rm} command directly from \fudgit's shell. When used in a macro name or an alias name, the `!' character has still another meaning. This tells the parser that characters following the `!' are optional. Therefore, if one types the following, interactively, (see NOTE) \nopagebreak\begin{verbatim} set noexpand alias da!te !date set expand \end{verbatim} then the parser will recognize {\tt da}, {\tt dat} and {\tt date} as all synonymous to the system command {\tt ! date} run through a Bourne shell. NOTE: In interactive mode, the history functions will try to interpret a history substitution if the `!' is not followed by a space. See the appendices. To avoid that the line be scanned for a history event designator, use the {\tt set noexpand} command. In some cases, it might be simpler to use the {\tt system} command. \Syntax \bq !{\it command}\eq \Example \bq ! mail\eq \Seealso \bq alias, ls, vi, foreach, system, set expand\eq \section{?} A question mark will indicate \fudgit\ to try to get the possible options available to the command presently typed. This kind of help is context sensitive and works when an insufficient number of arguments is supplied. The question mark also serves as a wild character in string subtraction. \Syntax \bq {\it command} ? \eq \Examples \bq ?\\ show ?\\ set function ?\eq \Seealso \bq help, strings \eq \section{\$} The `\$' operator expands scalar variables or constants (double precision numbers from C-calculator mode lookup table) as well as string variables or constants. Existing scalar variables can thus be expanded as a string in order to serve as a file name or directory name, for example. The expansion is done according to the value given to the {\tt set vformat} command which initially defaults to ``\%.3g''. Using the scalar variable expansion operator in C-calculator mode is not recommanded since a lot of precision might be lost (actually it is a waste!). Scalar variable expansion is essentially provided to allow alternative procedures in certain cases, such as generating filenames from numbers. Math function {\tt scan} can be considered as the complement of scalar variable expansion. The `\$' character also expands string variables. Expansion is done by replacing the \${\it String-Variable-Name} by the value of the string variable. This can be used to replace {\tt scan} in cases where the string variable or constant represents a number. For example \nopagebreak\begin{verbatim} foreach File in echo 2.2 4.4 6.7 8.32 let x = $File . . . end \end{verbatim} In both cases, if the variable name has to be followed by alphanumeric characters, then the variable name can be delimited by braces as in standard csh. Followed by an integer number, the `\$' character serves to designate the arguments of a macro. Refer to the description of {\tt macro}, concerning this point. \Syntax \bq \${\it name}\eq or \bq\$\{{\it name}\}\eq \Seealso \bq C, cmode, macro, echo, exit \eq \section{\_dumplot} Command {\tt \_dumplot} is generally used in a macro to dump vectors in the plotting pipe. It is described in more detail under {\tt special} item. \section{\_killplot} Command {\tt \_killplot} is rarely used. It sends a KILL signal to the plotting program. It is described in more detail under {\tt special} item. \section{adjust} The {\tt adjust} command is used to specify the parameters to be adjusted in the ``least square linear'' and the ``Marquardt-Levenberg nonlinear'' fitting methods. Parameters not being adjusted will have their standard deviation set to zero. \Syntax \bq adjust {\it index-list} \eq \Example \bq adjust 1 2 4\eq \Seealso \bq set parameters, set method, set function, fit, show fit \eq \section{alias} The {\tt alias} command is used to alias a multiple word command to a single word. Although macros and aliases are different objects, it is not allowed to define a macro and an alias with the same name since aliases are always expanded first. Recall that the bang operator (`!'), at the beginning of a line is recognized from a macro, an alias or a script file so that an alias like \nopagebreak\begin{verbatim} alias date !date \end{verbatim} is perfectly legal. However, this would have to be typed \nopagebreak\begin{verbatim} alias date ! date \end{verbatim} at the interactive command line, to avoid that the `!' be interpreted by the history functions. When called without arguments, {\tt alias} will list all the current aliases. For obvious reasons, it is not allowed to {\tt alias} {\it unalias}. {\tt alias} also supports the command abbreviation character `!'. To enter a `!' without having it interpreted by the history functions, just {\tt set noexpand} for the time entering the command. When a `!' is part of the alias name this indicates that the alias command name can be abbreviated down to that point. Since the {\tt \&} operator is used to refer to the native commands, it is therefore forbidden to start an alias name by character '\&'. \Syntax \bq alias {\it command} {\it command-list} \eq \Examples \nopagebreak\begin{verbatim} alias mv !mv alias . quit alias da!te !date \end{verbatim} \Seealso \bq !, \&, macro, unalias, set expand \eq \section{append and save} The {\tt append} command can be used to append various things to an existing file. If the file does not already exists, it will be automatically created. The {\tt save} command can be used to save various things to a file. If a file with the same name already exists, it will be overwritten without any warning. \subsection{append history} History can be saved or appended to a file. Any file saved this way can later be executed by the {\tt load} command. Note that {\tt append history} will silently fail if the file does not exist. \Syntax \bq append history {\it filename}\\ save history {\it filename}\eq \Seealso \bq load, line editing, fmode \eq \subsection{append macros} All the current macros and aliases can be saved or appended to a file. Any file saved this way can be subsequently {\tt load}ed at any time. To avoid confusion between data files and script files we recommand that you use the {\it .ft} extension for your script files. \Syntax \bq append macros {\it filename}\\ save macros {\it filename}\eq \Seealso \bq alias, unalias, load, show, macro, unmacro \eq \subsection{append parameters} Parameters can be saved into a file at any time. The number output format will be the one chosen by the {\tt set format} command. The column order will be a parameter followed by its standard deviation. All columns are separated by a tab. Therefore, if one has previously set parameters, i.e. \nopagebreak\begin{verbatim} set parameters MYPAR 3 . . . save parameters myfile \end{verbatim} then there will be 6 columns as follows: \nopagebreak\begin{verbatim} MYPAR[1] DMYPAR[1] . . . MYPAR[3] DMYPAR[3] \end{verbatim} in file {\it myfile}. Most of the time, the user will desire to save parameters along with some variables or constants. This can be done by giving the variable or constant (either string or scalar) names on the command line. For example, \nopagebreak\begin{verbatim} let t = 0.23 set parameters A 2 . . . save parameters t parfile \end{verbatim} will create a file {\it parfile} containing the value of scalar variable {\tt t}, followed by the 2 values of parameters {\tt A}, alternated with the value of their standard deviations {\tt DA}. Note that the given list of variables will be printed first. \Syntax \bq append parameters {\it variable-list\optio} {\it filename}\\ save parameters {\it variable-list\optio} {\it filename}\eq \Seealso \bq set format, set parameters, show parameters\eq \subsection{append variables} Any variable or number of variables can be saved to a file at any time. Vector elements referenced by an explicit index are considered as variables. String variables and constants are recognized as well. \Syntax \bq append variables {\it variable-list} {\it filename} \\ save variables {\it variable-list} {\it filename}\eq \Examples \nopagebreak\begin{verbatim} append variables x Y[3] a VECTOR[78] datafile1 save variables t PARAM[2] DPARAM[2] datafile2 \end{verbatim} \Seealso \bq load, cmode, let, C, show, auto \eq \subsection{append vectors} Any vector or number of vectors can be saved to a file. All the values are written in columns separated by a tab. The number format will be the one chosen by the {\tt set format} command. \Syntax \bq append vectors {\it VECTOR-list} {\it filename}\\ save vectors {\it VECTOR-list} {\it filename}\eq \Examples \nopagebreak\begin{verbatim} append vectors X Y ERROR1 TEST2 datafile1 save vectors TIME TEMP DT datafile2 \end{verbatim} \Seealso \bq set format, set data, read, fit, fft, show, auto \eq \section{auto} The {\tt auto} keyword is used to define automatic variables. The type of variable can be a scalar variable, a VECTOR or a String, depending on the upper-lower case letters in the variable name. The scope of auto variables is delimited by braces as in C. All auto variables are stored on the stack and are freed when the scope of the variable is left. Definition of variables can only be done right after a brace has been opened. Only scalar variables can be assigned as the are defined, while vectors are assigned to zero, and strings are empty. Contrarily to C, automatic scalar variables are set to zero if not assigned. {\tt auto} is a C-calculator mode keyword. \Syntax \bq auto {\it var-list} \eq \Examples \nopagebreak\begin{verbatim} # Some dummy examples set data 100 cmode x = y = 1 # These (x, y) are global X = y++ # As well as vector X { auto x=2, X, Y # All these variables are local... X=3; Y=sin(x) . . . } # ...and stop existing here x # This x still contains 1 # An example with a procedure proc test(x) { auto y=2 z = x + y++ # This z is global } fmode \end{verbatim} \Seealso \bq C, cmode, func, proc\eq \section{break} The {\tt break} keyword is used as in C to break C-calculator mode {\tt for} or {\tt while} loops. {\tt break} is a C-calculator mode command. \Syntax \bq break \eq \Seealso \bq C, continue, cmode, for, while \eq \section{C} The following gives a brief description of the supported C-calculator syntax and differences with standard C. The following operators are recognized, in order of precedence: \nopagebreak\begin{verbatim} ++, -- (post and pre) increment-decrement -, ! unary minus and logical NOT ^ exponentiation, right associative /, *, % division, multiplication, modulo +, - addition, subtraction >, >=, <, <=, ==, != relational operators && logical AND || logical OR =, +=, -=, /=, *= assignments, right associative \end{verbatim} All operators are left associatives except those specified. They are all common to C except for the exponentiation operator. The following keywords are reserved tokens: {\tt auto, if, else, while, for, break, continue}, and {\tt return}, plus two extra keywords {\tt proc, func}. They roughly obey the same syntax as in C so that statements like: \bq if ({\it conditions})\\ {\it cmode-line-statement}\eq or \bq if ({\it conditions}) {\it cmode-line-statement} \eq or \bq if ({\it conditions}) \{\\ {\it cmode-statements}\\ \}\eq The same thing is true for the else constructions {\tt else} of which some examples follow: \bq if ({\it conditions}) \\ {\it cmode-line-statement}\\ else\\ {\it cmode-line-statement}\eq or \bq if ({\it conditions}) \{\\ {\it cmode-statements}\\ \} else \{\\ {\it cmode-statements}\\ \}\eq Here {\it cmode-line-statement} means any semicolon separated list of C-calculator mode statements typed on the same line. Since semicolons are separators and not terminators, empty statements are defined by empty braces {\tt \{ \}}. The {\tt return} keyword must have parentheses when returning a value from a function as in {\tt return(x * sin(y))}. A single {\tt return} will only be recognized from within a procedure. To avoid potential confusion with variables, keywords cannot be abbreviated. As opposed to C, there exists no integer in the C-calculator mode. All scalar variables and numbers are double precision. This means that logical true is 1.0 and false is 0.0. As in C, one must be careful with comparison operators. The C {\tt switch} syntax is not supported (would require integers). As an extension, string comparison is possible with the equality operators `==' and `!='. This will return true or false if the string variables (or constants) are identical or not. Assignments of string variables actually copies all characters of the string on the RHS to the string variable on the LHS. String additions and subtractions are also possible. Function and procedure definitions are defined with prototypes, i.e., a list of variables representing the proper kind of variable. At run-time, the arguments of the function are checked for type compatibility and for their number. All variables are global except automatic variables defined using the {\tt auto} keyword. \Seealso \bq cmode, let, math, scan, strings, auto \eq \section{cd} The {\tt cd} command changes the working directory. Called with no argument, {\tt cd} will bring you to your \$HOME directory. Note that {\tt cd} changes the current working directory of \fudgit\ only. Therefore, your plotting program will still be in the previous directory. To get around this difficulty, you only have to define a macro as follows, if your plotting program supports {\tt cd}: \nopagebreak\begin{verbatim} macro Cd 1 pmode cd "$1" &cd $1 stop alias cd Cd \end{verbatim} \Syntax \bq cd {\it filename\optio}\eq \Examples \nopagebreak\begin{verbatim} cd cd /nazgul/users/fulano \end{verbatim} \Seealso \bq \&, pwd, alias\eq \section{cmode} The {\tt cmode} command allows you to go in the C-calculator mode. The only way to come back to the main fitting mode is by using the {\tt fmode} command or to type \^{ }D in interactive mode. Commands cannot be abbreviated in {\tt cmode}. Parallel to the {\tt cmode} command, the {\tt let} command can be used to pass one single command, or command line to mathematical parser. To be consistent with {\tt pmode} command, {\tt cmode} also accepts arguments in which case it is equivalent to the {\tt let} command. It is not an error to call {\tt cmode} from the C-calculator mode. A warning message will be given though. \Syntax \bq cmode {\it command-list\optio}\eq The C-calculator mode supports most of C syntax (see item C), and most of the C math library. Thus, the following functions are supported: \nopagebreak\begin{verbatim} trigo: hyperbolic: expo: special: conversion: random: cos() cosh() ln() besy0() trunc() srand() cot() coth() log() besy1() floor() rand() csc() csch() exp() besj0() ceil() sec() sech() sqrt() besj1() rint() sin() sinh() cbrt() besjn() abs() tan() tanh() besyn() int() acos() acosh() erf() scan() asin() asinh() erfc() min() atan() atanh() lgamma() max() atan2() interp() sum() vread() \end{verbatim} Any upper case variable (possibly including `\_') possibly mixed with digits will be recognized as a vector, e.g., {\tt TEMP\_2, TEST, D}, etc. Any lower case name will be taken as a scalar variable, e.g., {\tt x, t4}, etc. There are two predefined constants, {\tt pi} $=\pi$ and {\tt e}$=e$, which should not be unlocked and modified. As well, the built-in constant {\tt data} contains the current size of the vectors and can be modified through the {\tt set data} command, by the {\tt read}/{\tt exec} commands, or by {\tt unlock}ing the constant and modifying it directly. The built-in constant {\tt chi2} contains the value of $\chi^2$ as obtained from the latest fit. And finally, the built-in scalar constant {\tt param} contains the number of parameters as defined by {\tt set parameters}. A mix of upper case and lower case letters will serve to indicate a string variable. Strings values are indicated by double quotes as in C. Unlike C, \fudgit\ considers strings as self-contained objects that can be added, subtracted, and checked for (in)equality. Thus, string objects (i.e. string variables, string constants and string values) can: serve as argument to {\tt scan} function; be part of string assignment statements or of a truth statement involving (in)equality operator; be added (concatenated using the `+' operator) one with another; be subtracted (remove string termination using the `-' operator) one with another; and finally be argument of string functions. A predefined string constant called {\tt Tmp} contains the string "/tmp/fudgitPID" where PID is the process id number of the current process. This file, and any file belonging to you, whose name starts with the same string, will be erased automatically by the {\tt exit} or {\tt quit} commands. This string is typically used by the {\tt gnuplot} macro in order to pass data to the \gnuplot\ plotting program which cannot read data from standard input. Another predefined string constant is {\tt ReadFile} which contains the last data filename that has been loaded. Finally, the string constant {\tt Cwd} is made available in order to get the current working directory. The following table contains all the built-in constants. \nopagebreak\begin{verbatim} chi2 Value of chi^2 from the last fit; data Length of all vectors (< samples) as set by set data; e Neperian number; param Number of parameters as set by set parameters; pi Guess this one; Cwd Current working directory; ReadFile The last file (program) read by read (exec); Tmp A temporary filename "/tmp/fudgitPID"; \end{verbatim} Constants (either strings and scalars) can also be created by {\tt lock}ing a variable. In the same manner, a constant can be modified directly if it has been {\tt unlock}ed. The algebraic operations applicable to scalar variables can be applied to vectors. Vector algebra can be mixed with scalar variable algebra in which case the user has to take the implied loop into account. For example, although the following operation is not standard C programming: \footnote {NOTE: In order to show that some commands can be typed from both C-calculator mode and the fitting fmode, the following examples shows the typing mode from the first line. However, one can always type the same C-calculator mode command from the fitting mode by using the {\tt let} command (or {\tt cmode} command).} \nopagebreak\begin{verbatim} cmode x = 0 X = x++ \end{verbatim} will define a vector $X$ of size {\tt data} (see {\tt set data}) ranging from $X[1]$ to $X[data]$ and taking values from 0 to $data-1$. Multiple commands can be given with the separator `;', for example, another version of the previous command could be written \nopagebreak\begin{verbatim} cmode x=0;X=++x \end{verbatim} in which case a vector $X$ taking values from 1 to $data$ will be created. (Note that the latter uses a pre-increment whereas the former uses a post-increment operator on {\tt x}: results are thus different). Vector elements can be referenced by elements using standard C grammar. Therefore, the same vector could be created by using a {\tt while} construction as in: \nopagebreak\begin{verbatim} fmode set data 1000 let X=0;i=0 cmode while (i++ <= data) X[i] = i fmode \end{verbatim} or, using a {\tt for} loop, \nopagebreak\begin{verbatim} cmode for (x=0;x<=data;x++) { X[x] = x } fmode \end{verbatim} Noninteger variables will be truncated to the nearest lower integer to form a vector index. \nopagebreak\begin{verbatim} cmode y= 2.01 x=2.23; X[2]=Z[y]+5^x \end{verbatim} Assigning a vector to a constant will assign all the elements to that constant. \nopagebreak\begin{verbatim} fmode let X = pi let Z2 = 0 \end{verbatim} The C-calculator checks for undefined variables on the RHS of any assignment. From C-calculator mode, variables values can be seen by typing the variable name by itself or by using the {\tt print} command, if the output is selected to be {\it stdout}. From the fitting mode, contents of constants and variables (either strings or scalars) is displayed using {\tt show variables} command, or by using the `\$' expansion operator. However, vectors can be only be seen from the fitting mode by using the {\tt show vector} command. Each unknown vector name given on the command line allocates a vector of {\tt sample} size. To be a calculator as such, the C-calculator prints the value of the expression given on the command line. Thus, the statement \nopagebreak\begin{verbatim} cmode x + 2 \end{verbatim} will print the value of $x + 2.0$. The contents of many variables can be displayed at the same time by giving a coma separated list such as in \nopagebreak\begin{verbatim} cmode x,"temperature", t \end{verbatim} where the string {\it temperature} will be printed between the values of variables $x$ and $t$. Note that the C-calculator mode recognizes strings by double quotes. Special characters such as '\verb+\n+' are also legal in a string. We conclude by giving some examples involving string variables: \nopagebreak\begin{verbatim} fmode let String = "new.file" let x = (String == "new.file") let y = ("file1" == "file2") let Bing = "\a\a\a" let Here = Cwd # Store the value of the current working directory let Input = Read() # Read from stdin let Test = FileName(ReadFile) - ".data" let Dir = DirName(InputFile) let y = scan(Read(), "%lf") let File = "STRING_23.4" let number = scan("%*[_A-Z]%lf", File) let Message = "A tab \t and a newline\n" \end{verbatim} where the truth statement could be legally used as a condition for an {\tt if}, a {\tt while}, or a {\tt for}. \Seealso \bq let, C, data, func, proc, print, fmode, math, while, for, return,\\ auto, if, break, samples, quotes, strings\eq \section{comments} By default, anything following a `{\tt \#}' will be treated as a comment and ignored. This holds for data files as well as for command script files loaded with the {\tt load} command. This default can be changed with the {\tt set comment} command. Sometimes a comment character needs to be taken literally in a script file. The comment character will be accepted as data if it follows the `\verb+\+' escape operator, i.e. `\verb+\+\#', or, in the fitting mode only, whenever the comment character is somewhere inside quotes or parentheses. The comment character is always accepted literally when typed on the interactive command line. \Seealso \bq set comment, read, load, show comment, exec \eq \section{continue} The {\tt continue} keyword has the same usage it has in C for sending the control to the next iteration of a {\tt for} or {\tt while} loop. {\tt continue} is a C-calculator mode command. \Syntax \bq continue \eq \Seealso \bq for, while, cmode, C \eq \section{data files} Files containing data are loaded by specifying the name of the data file to the {\tt read} command. Data files should contain one data point per line. A data point can be a 256 dimensional object. By default, anything following character `{\tt \#}' will be treated as comment and ignored. In all cases, the numbers on each line of a data file must be separated by any number of blank spaces or tabs. These blanks divide each line into columns. Thus, \fudgit\ can handle up to 256 columns per line. Warning will be given if a line has a different number of columns. Strings such as {\it NaN} or {\it Infinity} are recognized and refused. The default compilation gives a maximum line size of 1024 characters. \Seealso \bq read, exec, set comment \eq \section{echo} The {\tt echo} command allows the user to print a string to the standard output. If no argument is given {\tt echo} will only print a newline. This command can be used to display a message or, when coupled with the variable expansion operator `\$', to see the value of a printable (either string or scalar) variable defined in the C-calculator. \Syntax \bq echo {\it string-list}\eq \Examples \nopagebreak\begin{verbatim} echo Starting the fit echo $Mydir \end{verbatim} \Seealso \bq cmode, \$ \eq \section{else} The {\tt else} keyword is used in {\tt if} constructions, both in C-calculator anf fitting modes. Refer to the {\tt if} entries for a complete description. \section{end} The {\tt end} command is used to complete a {\tt foreach} loop or a {\tt while} loop. Keyword {\tt end} is also used to tell {\tt read} that we are finished writing data to stdin. This command should always be found on a line by itself (comments are allowed though). \Seealso \bq foreach, while, read, stop\eq \section{endif} The {\tt endif} command is used to complete an {\tt if} construction in fitting mode. Keyword {\tt endif} must always be used on a line by itself (comments are allowed though). Refer to the {\tt if} entries for a the complete description. \section{environment} \fudgit\ is sensitive to the following environment variables: $\bullet$ PAGER for the program called to format long listings. $\bullet$ HOME for the directory to which {\tt cd} defaults. $\bullet$ SHELL for the shell called by {\tt system} when this latter is called without arguments. If not defined, the default pager is {\it /usr/?/more} (path depends on system) and the default shell {\it /bin/csh}. \Seealso \bq cd, system, show vectors, help \eq \section{exec} The command {\tt exec} executes a program and reads data from it. It supports the same syntax {\tt read} does except that the program name replaces the file name. A program is a program name or anything that can be typed in a shell. If the command line has more than one string, it must be glued with quotes. On a successful call, {\tt exec} will set the string constant {\tt ReadFile} to the name of the program which generated the data. \Syntax \bq exec {\it commands} {\it assignment$[$range$]$\optio} \ldots\eq \Examples \nopagebreak\begin{verbatim} exec simulate X:1 Y:2[0:200] exec "cat data | myfilter -g" X1:1[0:*] X2:2 X3:4 \end{verbatim} \Seealso \bq read, comments\eq \section{exit} The commands {\tt exit} and {\tt quit} will exit \fudgit. See details under item {\tt quit}. \Syntax \bq exit\eq \Seealso \bq quit, cmode \eq \section{fft} The {\tt fft} command will take the Fourier transform of the specified vectors and put the real part in a vector specified by the third argument. The imaginary part will be put in a vector specified by the fourth argument. Input vectors can be used for output. The resulting vectors will contain frequencies ranging from 0 to $N/2$ followed by $-(N/2 - 1)$ to $-1$ in units of $1/(N*\Delta)$ where $\Delta$ is the sampling rate. If a real vector is transformed $h(t) -> H(f)$, we should have $H(-f) = H^*(f)$. Therefore, with $H = R + iI$ and $H^* = R - iI$ be the transformed vectors, we should have $R(-f) = R(f)$ and $I(-f) = -I(f)$, where $f$ is discrete and ranges as mentioned above. In terms of vector indices, these relations become $R[i] = R[N-i+2]$ and $I[i] = -I[N-i+2]$ for $1 < i < N/2$ in addition to the fact that $I[1] = I[(N/2)+1] = 0$. Therefore, because the negative frequency part is the mirror image of the positive one, it is common to plot only the positive frequencies of the Fourier transform of a real vector. This can be done by reducing {\tt data} to half its value. Because of the use of a FFT algorithm, the number of data points must be an integer power of 2. If not, the user should pad the vector with zeros up to the next largest power of two. Each transform is normalized by the factor $\sqrt{(N)}$ so that {\tt fft RE IM T\_RE T\_IM} followed by {\tt invfft T\_RE T\_IMA RE2 IMA2} will not introduce a factor $N$ in vectors {\tt RE2} and {\tt IMA2} (i.e., {\tt RE} = {\tt RE2} and {\tt IM} = {\tt IM2}). At his choice, the user can use the C-calculator functionality in order to implement windowing. The power spectrum can be obtained from: \nopagebreak\begin{verbatim} fft RE IMA T_RE T_IMA let POW = T_RE^2 + T_IMA^2 \end{verbatim} where $POW[i]$ will contain the power value associated with frequency $f$, which goes from 0 to $N/2$ followed by $-(N/2 - 1)$ to $-1$ (in units of $1/(N*\Delta)$) as $i$ goes from 1 to $N$. \Syntax \bq fft {\it real-VECTOR} {\it ima-VECTOR} {\it real-VECTOR} {\it ima-VECTOR}\eq \Examples \nopagebreak\begin{verbatim} # real vector X let IM=0 # re-use IM vector for output fft X IM Z IM # complex vectors X+iY where i = sqrt(-1) transformed in V+iW fft X Y V W \end{verbatim} \Seealso \bq invfft, smooth, cmode, let, read, math, data \eq \section{fit} The {\tt fit} command is used to fit a function, chosen by {\tt set function}, to a pair of vectors containing the independent and dependent variables. Depending on the type of fit, selected by the {\tt set method} command, a third vector containing the standard deviation might be required. {\tt fit} allocates a vector having the name of the dependent variable appended with the string {\tt FIT}. This vector contains the computed values of the function for the given independent vector. Depending on the method, the built-in constant {\tt chi2} will contain the value of the mean square deviation weighted by vector {\it $\sigma$-VECTOR} or the mean absolute deviation. \Syntax \bq fit {\it independent-VECTOR} {\it dependent-VECTOR} {\it $\sigma$-VECTOR}\eq \Example \nopagebreak\begin{verbatim} fit X Y DY \end{verbatim} will create a vector {\tt YFIT} containing the value of the fitted function for each of the values of the independent vector {\tt X}. Note that the standard deviation is required for most fitting routines since it is used to weigh the value of local square deviation from the fit (in fact, this is the definition of $\chi^2$). If {\it $\sigma$-VECTOR} is unavailable just use \nopagebreak\begin{verbatim} let DY=1 \end{verbatim} using the previous example. This simply gives the same weight to all data points. \Seealso \bq set method, set function, show fit, show parameters, append\eq \section{fmode} The {\tt fmode} command allows you to return to the fitting mode, when the program is in one of the C-calculator or plotting modes. The fitting mode, is the main mode of the program. The two other modes are the C-calculator mode, accessed by the {\tt cmode} command, and the plotting mode, accessed by the {\tt pmode} command. When used interactively, \^{ }D returns to the fitting mode from either of the C-calculator mode or from the plotting mode. It is not an error to call {\tt fmode} from the fitting mode. A warning message will be given though. \Syntax \bq fmode\eq \Seealso \bq cmode, pmode, let\eq \section{for} The {\tt for} command is a C-calculator mode command. It behaves roughly like a standard C {\tt for} construction. In interactive mode, any new input line will be prompted with a ``n\{\ldots n\verb+\t+'' where `n' stands for the nesting level and `\verb+\t+' for a tab. Keyword {\tt for} is a C-calculator mode command. \Syntax \bq for ({\it init-expressions}; {\it cond-expressions}; {\it loop-expressions}) \\ {\it cmode-line-statement}\eq or \bq for ({\it init-expressions}; {\it cond-expressions}; {\it loop-expressions}) \{\\ {\it cmode-statements}\\ \}\eq \Examples \nopagebreak\begin{verbatim} cmode for (i=1,j=2;i+j <= data; i+=2,j+=3) A[i] = X[j] fmode # Another example: # A macro to remove point x in a vector. Syntax: delete "vector" "index" macro delete 2 cmode for(i=$2;i #include "fudgit.h" /* An example of a user-defined routine inversing the order of an even * vector. Typical call would be: * myproc(A_VEC, data) * from C-calculator mode. NOTE that both VEC and expr are pointers. * To make things explicit, fudgit.h contains a few typedef's. */ void myproc(X, dn) VEC X; expr dn; { int i, half_n; int n = (int)*dn; /* note that dn is a pointer to a double */ double tmp; if (n%2 == 1) /* report error if odd number (Why not?)*/ Ft_matherror("%s: Called with an odd number %d.", "myproc", n); /* You have full use of math and stdio libraries too!!! */ fprintf(stderr, "BTW, Did you know that %lf is the sqrt(pi)?\n", sqrt(M_PI)); half_n = n >>1; /* half of n */ for (i=0;i - * * */ double myfunc(A, B, dn) VEC A, B; expr dn; { int i, n = (int)*dn; /* Again, dn is a pointer to a double */ double sumA, sumB, sumAB; sumA = sumB = sumAB = 0.0; /* sum up the values of interest */ for (i=0;i 709$ on most machines), although $y$ is in fact 0. If one uses {\tt set error 0 1 2 3}, then no error will be reported and $y$ will be set to zero accordingly. \Syntax \bq set debug {\it value-list} \eq \Example \bq set error 0 2 3\eq \Seealso \bq C, cmode \eq \subsection{set expand} In interactive mode, history expansion and substitution will occur only if the {\tt expand} variable is set. It is disabled using {\tt set noexpand}. The default is on. \Syntax \bq set expand \eq \Seealso \bq set noexpand, history, line editing \eq \subsection{set format} The command {\tt set format} will set the printf format for variables. Use only if you are sure of what you are doing. It defaults to ``\% 10.8e". See {\tt man printf(3)} if in doubt. \Syntax \bq set format {\it string}\eq \Examples \nopagebreak\begin{verbatim} set format %6.2lf set format "% .8g" \end{verbatim} \Seealso \bq show, append \eq \subsection{set function} The {\tt set function} command is perhaps the most crucial command in data fitting. It is used to select a built-in fitting function or to enter a user-defined function. The following fitting functions are available: \nopagebreak\begin{verbatim} NAME DESCRIPTION PARAMETERS REQUIRED ---- ----------- ------------------- straight Straight line (2 parameters) sine Sine series (N parameters) cosine Cosine series (N parameters) legendre Legendre series (N parameters) polynomial Power series (N parameters) gauss Gaussian series (3N parameters) expo Exponential series (2N parameters) user User-defined function (N parameters) \end{verbatim} Assume a variable vector $X$ and a parameter vector $A$ then, the nonlinear gauss fitting function is a series of gaussians where \[ f(X,A) = \sum_{i=1,4,7, \ldots, N} A[i] \times e^{- \left( \frac{(X - A[i+1])}{A[i+2]}\right)^ 2}. \] The nonlinear expo function is a series of exponentials where \[ f(X,A) = \sum_{1=1,3,\ldots, N} A[i] \times e^{X*A[i+1]} .\] For a user-defined function, the {\tt set function user} will prompt for more input. The following input is related to the variable to fit. For purposes of clarity, let's say that we have to fit vectors {\tt X Y DY}. This requires a fit function {\tt YFIT} (the name is made from the dependent variable appended with {\tt FIT}) and all the partial derivatives {\tt DYFITD1, DYFITD2, \ldots, DYFITDN} taken with respect to the parameters $n=1,\ldots N$. All these functions are defined one per line as in the case of a macro until a {\tt stop} is entered. Temporary variables are permitted. {\tt set function user} actually defines a C-calculator mode macro that will be executed before each iteration of the fit. Therefore the complete C-calculator mode grammar is fully supported here. Temporary vectors can thus be used to speed up the calculation. The C-calculator macro can be a simple call to a predefined procedure. When defined so, the parsing does not have to be done at each iteration, and a slightly faster process should result. \Example \nopagebreak\begin{verbatim} # read column 1, 2 and 3 of file "file" read file T:1 R:2 DR:3 # make a three parameter fit set parameter K 3 # this is a linear fit; use singular value decomposition set method svd_fit # enter my function set function user RFIT = K[1] + K[2]*T^0.5 + K[3]*T^1.5 DRFITD1 = 1 DRFITD2 = T^0.5 DRFITD3 = T^1.5 stop fit T R DR \end{verbatim} The vector {\tt RFIT} will contain the fitted function. The difference between the fit and real data can be obtained right away by defining a vector \nopagebreak\begin{verbatim} let RDIFF = R - RFIT \end{verbatim} that can be plotted with respect to {\tt T}. The same thing is done for nonlinear fit with the exception that the partial derivatives of the function with respect to the parameters will contain reference to some parameter(s). (This is precisely the meaning of nonlinear here). There is virtually no restriction on the number of parameters (memory is the sole limitation: {\tt set parameter} command allocates a matrix of {\tt parameters} X {\tt samples} ). The only conditions are that a linear regression must have 2 parameters defined (this is obvious) and the built-in nonlinear functions must be modulo 3 for the series of gaussians and modulo 2 for the series of exponentials. \Seealso \bq fit, set method, adjust, proc, auto \eq \subsection{set input} The {\tt set input} command selects the file for the input of the C-calculator mode {\tt Read} and {\tt vread} command. The string {\it stdin} is valid as a filename. If the selected file does not exist or cannot be read, an error message will be given and the value will go back to the default value, which is {\it stdin}. \Syntax \bq set input {\it filename} \eq \Seealso \bq Read, vread \eq \subsection{set iteration} The {\tt set iteration} command permits the user to change the iteration number for the Marquardt-Levenberg nonlinear fitting method. See {\tt set function}. The default value is 10. However, the fitting process will stop if there is no difference in $\chi^2$ for two consecutive iterations. However, a negative value will force to iterate up to the absolute value of that number, without checking for convergence. \Syntax \bq set iteration {\it value}\eq \Example \bq set iteration 3\eq \Seealso \bq fit, set method, set function \eq \subsection{set method} The {\tt set method} command allows the user to select the fitting method to be used when calling the {\tt fit} command. The following methods are available: \nopagebreak\begin{verbatim} NAME DESCRIPTION ---- ----------- ls_reg least square linear regression (2 parameters) lad_reg least absolute deviation linear regression (2 parameters) ls_fit general least square linear fit using QR decomposition svd_fit general least square linear fit using singular value decomposition ml_fit general least square nonlinear fit using Marquardt-Levenberg method \end{verbatim} Among them, only {\tt ml\_fit} and {ls\_fit} depends on {\tt iteration} and {\tt adjust}. For all methods except {\tt lad\_reg}, the value of $\chi^2$ will be put in the scalar constant {\tt chi2}. In the case of {\tt lad\_reg}, %\chi^2$ will contain the average absolute deviation. \Syntax \bq set method {\it method}\eq \Example \bq set method svd\eq \Seealso \bq fit, set iteration, set function \eq \subsection{set noexpand} The {\tt set noexpand} command disallows history expansion on the interactive command line. \Syntax \bq set noexpand \eq \Seealso \bq set expand \eq \subsection{set output} The {\tt set output} command selects the file for the output of the C-calculator mode {\tt print} command. The strings {\it stdout} and {\it stderr} are both valid as a filename. If the selected file already exists, it will be overwritten with no warning. The default value is {\it stdout}. \Syntax \bq set output {\it filename} \eq \Seealso \bq print \eq \subsection{set pager} The {\tt set pager} command allows the user to select a pager. A pager is the program that is called when the structure to be displayed has more than 24 elements. The default pager is (1) the environment variable PAGER if it exists or (2) {\it /usr/?/more} (path depends on system) if not. If {\tt pager} is defined to a null string ({\tt ""}), then no pager will be used. \Syntax \bq set pager {\it string}\eq \Example \bq set pager "more -c"\eq \Seealso \bq show, show pager \eq \subsection{set parameters} The command {\tt set parameters} will fix the parameter name and size. Since the set of parameters is a kind of vector, parameter name cannot contain lower case letters. Parameters are initialized to zero. A built-in scalar constant called {\tt param} contains the number of parameters at all time. \Syntax \bq set parameters {\it parameter-name} {\it size}\eq \Example \nopagebreak\begin{verbatim} # set the vector D of size 3 to be determined by the fit. set parameters D 3 \end{verbatim} \Seealso \bq show parameters, show setup\eq \subsection{set plotting} The {\tt set plotting} command changes the default plotting program used by the plotting mode. The default is \gnuplot\ but this can be changed to any plotting program that can be driven from stdin. A maximum of 16 arguments can be passed when the program is first called. Changing the plotting program will send a KILL signal to the existing plotting program (if any). If the plotting program is set to a null string ({\tt ""}), \fudgit\ will ignore all the plotting commands and warning messages will be given. Setting the plotting program to a file that cannot be found or executed will result in an error at the first {\tt pmode} call. \Syntax \bq set plotting {\it command}\eq \Examples \nopagebreak\begin{verbatim} set plotting "/usr/local/bin/sgiplot -p" set plotting /usr/local/bin/gnuplot \end{verbatim} \Seealso \bq show plotting \eq \subsection{set prompts} All three \fudgit\ prompts can be changed by the {\tt set} command. The name of the prompts are: $\bullet$ {\tt prompt-cm} for the C-calculator mode prompt (default: "cmode$>$ "; $\bullet$ {\tt prompt-fm} for the fitting mode prompt (default: "fudgit$>$ "; $\bullet$ {\tt prompt-pm} for the plotting mode prompt (default: "pmode$>$ ". A null string {\tt ""} (i.e., two consecutive quotes) can be given to any of these. \Syntax \bq set prompt-cm {\it string}\\ set prompt-fm {\it string}\\ set prompt-pm {\it string}\eq \Seealso \bq show prompts \eq \subsection{set samples} The command {\tt set samples} changes the current capacity of the fitting program. Typically, {\tt samples} is set at the beginning of a session since all the existing vectors and variables are erased on this call. The default setting is 4000 points. \Syntax \bq set samples {\it value}\eq \Example \bq set samples 6000\eq \Seealso \bq set data, cmode, let, lock \eq \subsection{set vformat} The command {\tt set vformat} will set the sprintf format used for the expansion of scalar variables by the expansion operator `\$'. Use only if you are sure of what you are doing. It defaults to ``\%.3lg''. See {\tt man printf(3)} if in doubt. \Syntax \bq set vformat {\it string}\eq \Examples \nopagebreak\begin{verbatim} set vformat %6.2lf set vformat "%.4lg" \end{verbatim} \Seealso \bq \$, cmode, C \eq \section{shell} The {\tt shell} command starts a shell according to your SHELL environment variable. It is equivalent to {\tt system} command. Refer to the latter for details. \section{show} The {\tt show} command is used to see the chosen options or to look at any defined vectors, parameters or variables. \Seealso \bq set, echo \eq \subsection{show comment} The {\tt show comment} command echoes the current comment escape character. \Syntax \bq show comment \eq \Seealso \bq set comment, comments \eq \subsection{show data} The {\tt show data} command displays the current value of {\tt data} constant. Left for compatibility. \Syntax \bq show data \eq \Seealso \bq set data, lock, unlock, set samples \eq \subsection{show debug} The {\tt show debug} command displays the current value of the {\tt debug} variable. The value is displayed in octal since the {\tt set debug} $n$ command turns on the $n^{th}$ bit of this number. \Syntax \bq show debug \eq \Seealso \bq set debug \eq \subsection{show error} The {\tt show error} command displays the current value of the {\tt error} computational check variable. The value is displayed in octal since the {\tt set error} $n$ command turns on the $n^{th}$ bit of this number. \Syntax \bq show error \eq \Seealso \bq set error \eq \subsection{show input} The {\tt show input} command shows the filename selected for the input of the C-calculator mode {\tt Read} and {\tt vread} command. The default value is {\it stdin} \Syntax \bq show input \eq \Seealso \bq set input, Read, vread \eq \subsection{show iteration} The {\tt show iteration} command displays the current value of {\tt iteration} variable. \Syntax \bq show iteration \eq \Seealso \bq set iteration, set method \eq \subsection{show fit} The {\tt show fit} command displays the different quantities relevant to the current fitting method. Typical examples are $\chi^2$, the covariance matrix, the curvature matrix, correlation factor, etc\ldots \Syntax \bq show fit\eq \Seealso \bq fit, set parameters, set function, set method \eq \subsection{show format} The {\tt show format} command displays the current value of {\tt format} variable. The {\tt format} string is used when displaying any number on the screen. Refer to printf(3) of the \unix\ manual. \Syntax \bq show format \eq \Seealso \bq set format, show \eq \subsection{show function} The command {\tt show function} displays the current function type. If the function type is {\tt user}, then the user-defined function will be displayed. \Syntax \bq show function\eq \Seealso \bq set function, show setup, fit, math \eq \subsection{show macros} If called with an argument, the {\tt show macros} command will display the specified macro. Otherwise, all currently defined macros will be displayed. The selected {\tt pager} is called if the command is given in interactive mode (at the command line prompt). \Syntax \bq show macros {\it macroname}\optio\eq \Seealso \bq set pager, save macros, alias \eq \subsection{show memory} The {\tt show memory} function will display the current state of memory consumption of the program. All sizes are given in bytes. It uses a direct call to mallinfo(3). The arena is the size of memory requested by the process to the kernel. It is then split in different blocks shared among the internal matrices and user's vectors, macros, functions, procedures, variables and history. \Syntax \bq show memory\eq \Seealso \bq free, show table \eq \subsection{show method} The {\tt show method} command displays the current value of the fitting {\tt method}. It contains {\it none} by default. \Syntax \bq show method \eq \Seealso \bq set method, fit, set function \eq \subsection{show output} The {\tt show output} command shows the filename selected for the output of the C-calculator mode {\tt print} command. The default value is {\it stdout} \Syntax \bq show output \eq \Seealso \bq set output, print \eq \subsection{show pager} The {\tt show pager} command displays the current value of the {\tt pager} program. \Syntax \bq show pager \eq \Seealso \bq set pager, environment, show\eq \subsection{show parameters} The command {\tt show parameters} will display the parameter values on the screen. If the number of parameters is larger than 24, then the selected {\tt pager} will be called if the command is given in interactive mode (at the command line prompt). As with {\tt append} and {\tt save parameters}, {\tt show parameter} can accept optional variable or constant (either string or scalar) list of names, in which case the value of the given variables will be displayed along with the parameter values. \Syntax \bq show parameters {\it variable-list\optio}\eq \Seealso \bq set pager, set parameters, save parameters, show fit \eq \subsection{show plotting} The {\tt show plotting} command displays the current value of the {\tt plotting} program. \Syntax \bq show plotting \eq \Seealso \bq set plotting, startup, pmode\eq \subsection{show prompts} The {\tt show prompts} command displays the current values of the different mode {\tt prompts}. \Syntax \bq show prompt-cm\\ show prompt-fm\\ show prompt-pm\eq \Seealso \bq set prompt, startup\eq \subsection{show samples} The {\tt show samples} command displays the current value of the {\tt samples} variable. Recall that although {\tt data} is responsible for the visible part of all vectors, vectors all have a fixed allocated length of {\tt samples} long. Any change to {\tt samples} through {\tt set samples} frees all the existing vectors. \Syntax \bq show samples \eq \Seealso \bq set samples, set data, cmode\eq \subsection{show setup} The command {\tt show setup} will show some values of the program, such as the last data filename read, the number of data points, current capacity, current comment character, current iteration number, current plotting program, etc. Left for compatibility. \Syntax \bq show setup\eq \Seealso \bq set comments\eq \subsection{show table} The command {\tt show table} displays the current lookup table of the C-calculator mode parser. It shows all current variables, numbers, vectors and functions included in the internal table. It also shows the state of the internal machine (C interpreter), stack and frame used in the C-calculator. This is used mainly for debugging or to prevent stack or machine code overflow. \Syntax \bq show table\eq \Seealso \bq free, show memory, cmode \eq \subsection{show variables} Any constants or variables can be displayed on the screen. The {\tt show variable} command differs from {\tt print} as follows: $\bullet$ {\tt show variables} only accepts integers for indexing vector elements; $\bullet$ {\tt show variables} requires a blank separated list; $\bullet$ {\tt show variables} cannot be part of a function or procedure. As it has been mentioned previously, this is due to the different types of parsing between the C-calculator and fitting modes. As with all other number displaying commands, the printing format is always the one selected by the {\tt set format} command. \Syntax \bq show variables {\it variable-list} \eq \Example \bq show variables x X[2] Y[2] DY[2] time\eq \Seealso \bq print, save variables, show table, show vectors, cmode \eq \subsection{show vectors} Any vector or number of vectors can be seen on the screen. If the size of vectors is larger than 24, the selected {\tt pager} will be called if the command is given in interactive mode (at the command line prompt). \Syntax \bq show vectors {\it VECTOR-list} \eq \Example \bq show vectors X Y DY\eq \Seealso \bq set pager, append vectors, read, cmode, let \eq \subsection{show vformat} The command {\tt show vformat} will display the printf format used for the expansion of scalar variables by the expansion operator `\$'. Refer to the printf(3) description in the \unix\ manual for more details. \Syntax \bq show vformat\eq \Seealso \bq \$, cmode, C, set vformat \eq \section{smooth} The {\tt smooth} command uses a gaussian windowing function (low-pass filter) on a Fourier transform loop in order to smooth the given vector. The windowing function is $\exp(-(f/(\sigma \times f_{max}))^2)$ where $f_{max}$ is equal to half of the smallest power of 2 larger than the number of data points {\tt data}. Variable $f$ is the frequency that ranges from 0 to $f_{max}$. More likely, the smoothing factor is a non null positive real number from the (0, 1] interval. A smoothing factor $\sigma >= 1$ leaves the vector unchanged. The number of data points {\tt data} needs not to be a power of 2. To be used with discernment! \Syntax \bq smooth {\it $\sigma$} {\it in-VECTOR} {\it out-VECTOR}\eq \Seealso \bq fft, invfft, cmode, C \eq \section{special} The following special commands are left for debugging or macro purposes. They start with an underscore to avoid mistakes and remind of their special character. {\tt \_killplot} will kill the current plotting program. \Syntax \bq \_killplot \eq {\tt \_dumplot} will send the following vectors in the plotting program pipe. This is only useful if the current plotting program accept data from its stdin. {\tt \_dumplot} can accept up to 16 arguments. \Syntax \bq \_dumplot {\it VECTOR-list}\eq \Example \bq \_dumplot X Y DY \eq \Seealso \bq macro, show macros, plot \eq \section{spline} The {\tt spline} function initializes the internal table for the calculation of interpolated values using cubic spline method. Interpolated values are obtained from calls to the C-calculator math function {\tt interp()}. The value of the first derivative at the first and last data points can be specified by optional arguments. If not specified, or if one of the optional arguments is an asterisk {\tt *}, then a {\it natural} cubic spline is assumed in which case the interpolated curve is such that the second derivative at the extreme points (or one of them) is null. The asterisk is more likely to be used in cases where the user would like to specify the first derivative at the last point only. The independent vector must be such that its value increases monotonically. \Syntax \bq spline {\it indep-VECTOR} {\it dep-VECTOR} {\it y1\optio} {\it yn\optio}\eq \Example \nopagebreak\begin{verbatim} # Read vectors having a functional relation Y = F(X) from file "datafile" read datafile X:1 Y:2 # Initialize the spline (as being natural) spline X Y # Save extreme values let from = X[1]; to = X[data] # Say there were data=10 points and you want 100 set data 100 # Rebuild X vector # First build X ranging [0, 1] let x=0; X=x++; tmp=data-1; X/=tmp # Then from 'from' to 'to': from + (to - from)*X let tmp=(to-from); X = from + X*tmp # Rebuild Y vector possibly containing original values as a subset let Y = interp(X) # Note that any value can be asked for let interp(2.34*pi) \end{verbatim} \Seealso \bq math interp\eq \section{startup} If a file {\it .fudgitrc} exists in your home directory, it will be automatically loaded at startup time of the program. This is useful if one wants to include his own macros or have his own preferences loaded to \fudgit. This file is loaded for both interactive use ({\tt fudgit}) and batch use ({\tt fudgit {\it script1} {\it script2}\ldots}). \Examples \nopagebreak\begin{verbatim} set plotting /usr/local/bin/sgiplot set prompt-pm "" set comment ? set samples 10000 \end{verbatim} A file called {\it .hist\_fudgit} is will be created in your home directory in order to keep history between calls of \fudgit. The number of events is determined at compilation time and defaults to 52. \Seealso \bq environment, alias, set plotting, set prompt \eq \section{stop} The command {\tt stop} is used to terminate a macro or a fitting function defined by the user. However, it can also be used in a script file in order to stop execution at a certain point. In this case, an warning message will report that {\tt stop} is being used outside a macro or function and the file from which the command was found will be considered as at the end of file (EOF). \Seealso \bq macro, set function \eq \section{string functions} \fudgit\ has a set of functions returning string objects. These are made available to deal with filename construction, or to read from standard input. To be consistent with string type, string functions are named with both lower case and upper case letters. Strings can be added or subtracted in the C-calculator mode. String addition {\it s1} + {\it s2} simply concatenates strings {\it s2} to string {\it s1}. String subtraction {\it s1} - {\it s2} removes {\it s2} from the end of {\it s1}. Note that the wild card `?' is supported in string subtractions. \subsection{string function DirName} The string function {\tt DirName} returns the directory name as extracted from the filename given as an argument. \Syntax \bq Dirname({\it String})\eq \Seealso \bq string functions FileName, Scan, Read\eq \subsection{string function FileName} The string function {\tt FileName} strips the leading directory names of the filename given as an argument. Note that the \unix\ command: \bq basename {\it File} {\it Extension}\eq is equivalent to the \fudgit\ command: \bq FileName({\it File}) - {\it Extension}\eq so that filename constructions can be made in {\tt foreach} loop for example. \Syntax \bq FileName({\it String})\eq \Examples \nopagebreak\begin{verbatim} foreach File in ls /usr/machin/data/*.32 read $File X:1 Y:2{2:23} # Some commands . . # let File be the filename only, less the ".32" extension let File = FileName(File) - ".32" # And let Dir be the directory name let Dir = DirName(File) end \end{verbatim} \Seealso \bq foreach, string functions, cmode, \$ \eq \subsection{string function Read} The {\tt Read} function read a line from the file chosen by the {\tt set input} function, strips the newline character and returns the resulting string. If the input is {\tt stdin}, the user will be prompted by a {\it ?} and the program will stop until a non-null string is entered. This is most likely to be used in macros requiring some input during run time. The {\tt Read()} function can be used to read numbers with the help of {\tt scan()}. See the example below. {\tt Read} can also be used to build vectors by taking one every $n$ points. This can be done by two imbedded {\tt for} loops. Note: The newline character is not passed to the string. \Examples \nopagebreak\begin{verbatim} # Read a string from stdin (the default) set input stdin let String = Read() # How to get a value out of a string: equivalent to vread() let value = scan(Read(), "\%lf") \eq # How to skip lines in a file # Read say file project/numbers.data set input project/numbers.data cmode for (i=1; i<=top; i++) { Line = Read() # Read one line X[i] = scan(Line, "%lf"); # get first column Y[i] = scan(Line, "%*lf %*lf %lf"); # get third column for (j=1; j