Mercurial > hg > octave-nkf
changeset 2679:79c851e2f0ee
[project @ 1997-02-14 04:32:00 by jwe]
author | jwe |
---|---|
date | Fri, 14 Feb 1997 04:33:35 +0000 |
parents | d1b51420fd85 |
children | 8e7e5137d3f8 |
files | doc/interpreter/data.texi doc/interpreter/errors.texi doc/interpreter/eval.texi doc/interpreter/grammar.texi doc/interpreter/numbers.texi doc/interpreter/struct.texi doc/interpreter/tips.texi doc/interpreter/var.texi |
diffstat | 8 files changed, 2090 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/interpreter/data.texi @@ -0,0 +1,170 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Data Types, Numeric Data Types, Getting Started, Top +@chapter Data Types +@cindex data types + +All versions of Octave include a number of built-in data types, +including real and complex scalars and matrices, character strings, and +a data structure type. + +It is also possible to define new specialized data types by writing a +small amount of C++ code. On some systems, new data types can be loaded +dynamically while Octave is running, so it is not necessary to recompile +all of Octave just to add a new type. @xref{Dynamically Linked +Functions} for more information about Octave's dynamic linking +capabilities. + +@menu +* Built-in Data Types:: +* User-defined Data Types:: +* Object Sizes:: +@end menu + +@node Built-in Data Types, User-defined Data Types, Data Types, Data Types +@section Built-in Data Types +@cindex data types, built-in +@cindex built-in data types + +The standard built-in data types are real and complex scalars and +matrices, character strings, and a data structure type. Additional +built-in data types may be added in future versions. If you need a +specialize data type that is not currently provided as a built-in type, +you are encouraged to write your own user-defined data type and +contribute it for distribution in a future release of Octave. + +@menu +* Numeric Objects:: +* String Objects:: +* Data Structure Objects:: +@end menu + +@node Numeric Objects, String Objects, Built-in Data Types, Built-in Data Types +@subsection Numeric Objects +@cindex numeric constant +@cindex numeric value + +Octave's built-in numeric objects include real and complex scalars and +matrices. All built-in numeric data is currently stored as double +precision numbers. On systems that use the IEEE floating point format, +values in the range +@iftex +@tex + $2.2251\times10^{-308}$ to $1.7977\times10^{308}$ +@end tex +@end iftex +@ifinfo + 2.2251e-308 to 1.7977e+308 +@end ifinfo + can be stored, and the relative precision is approximately +@iftex +@tex + $2.2204\times10^{-16}$. +@end tex +@end iftex +@ifinfo + 2.2204e-16. +@end ifinfo +The exact values are given by the variables @var{realmin}, +@var{realmax}, and @var{eps}, respectively. + +Matrix objects can be of any size, and can be dynamically reshaped and +resized. It is easy to extract individual rows, columns, or submatrices +is using a variety of powerful indexing features. + +@xref{Numeric Data Types}, for more information. + +@node String Objects, Data Structure Objects, Numeric Objects, Built-in Data Types +@subsection String Objects +@cindex strings +@cindex character strings +@opindex " +@opindex ' + +A character string in Octave consists of a sequence of characters +enclosed in either double-quote or single-quote marks. Internally, +Octave currently stores strings as matrices of characters. All the +indexing operations that work for matrix objects also work for strings. + +@xref{Strings}, for more information. + +@node Data Structure Objects, , String Objects, Built-in Data Types +@subsection Data Structure Objects +@cindex structures +@cindex data structures + +Octave's data structure type can help you to organize related objects of +different types. The current implementation uses an associative array +with indices limited to strings, but the syntax is more like C-style +structures. + +@xref{Data Structures}, for more information. + +@node User-defined Data Types, Object Sizes, Built-in Data Types, Data Types +@section User-defined Data Types +@cindex user-defined data types +@cindex data types, user-defined + +@node Object Sizes, , User-defined Data Types, Data Types +@section Object Sizes + +The following functions allow you to determine the size of a variable or +expression. These functions are defined for all objects. They return +-1 when the operation doesn't make sense. For example, Octave's data +structure type doesn't have rows or columns, so @code{rows} and +@code{columns} return -1 for structure arguments. + +@deftypefn {Function File} {} columns (@var{a}) +Return the number of columns of @var{a}. +@end deftypefn + +@deftypefn {Function File} {} rows (@var{a}) +Return the number of rows of @var{a}. +@end deftypefn + +@deftypefn {Function File} {} length (@var{a}) +Return the number of rows of @var{a} or the number of columns of +@var{a}, whichever is larger. +@end deftypefn + +@deftypefn {Function File} {} size (@var{a}, @var{n}) +Return the number rows and columns of @var{a}. + +With one input argument and one output argument, the result is returned +in a 2 element row vector. If there are two output arguments, the +number of rows is assigned to the first, and the number of columns to +the second. For example, + +@example +@group +octave:13> size ([1, 2; 3, 4; 5, 6]) +ans = + + 3 2 + +octave:14> [nr, nc] = size ([1, 2; 3, 4; 5, 6]) +nr = 3 + +nc = 2 +@end group +@end example + +If given a second argument of either 1 or 2, @code{size} will return +only the row or column dimension. For example + +@example +octave:15> size ([1, 2; 3, 4; 5, 6], 2) +ans = 2 +@end example + +@noindent +returns the number of columns in the given matrix. +@end deftypefn + +@deftypefn {Function File} {} isempty (@var{a}) +Return 1 if @var{a} is an empty matrix (either the number of rows, or +the number of columns, or both are zero). Otherwise, return 0. +@end deftypefn +
new file mode 100644 --- /dev/null +++ b/doc/interpreter/errors.texi @@ -0,0 +1,114 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Error Handling, Input and Output, Functions and Scripts, Top +@chapter Error Handling + +@deftypefn {Built-in Function} {} error (@var{template}, @dots{}) +The @code{error} function formats the optional arguments under the +control of the template string @var{template} using the same rules as +the @code{printf} family of functions (@pxref{Formatted Output}). +The resulting message is prefixed by the string @samp{error: } and +printed on the @code{stderr} stream. + +Calling @code{error} also sets Octave's internal error state such that +control will return to the top level without evaluating any more +commands. This is useful for aborting from functions or scripts. + +If the error message does not end with a new line character, Octave will +print a traceback of all the function calls leading to the error. For +example, given the following function definitions: + +@example +@group +function f () g () end +function g () h () end +function h () nargin == 1 || error ("nargin != 1"); end +@end group +@end example + +@noindent +calling the function @code{f} will result in a list of messages that +can help you to quickly locate the exact location of the error: + +@example +@group +f () +error: nargin != 1 +error: evaluating index expression near line 1, column 30 +error: evaluating binary operator `||' near line 1, column 27 +error: called from `h' +error: called from `g' +error: called from `f' +@end group +@end example + +If the error message ends in a new line character, Octave will print the +message but will not display any traceback messages as it returns +control to the top level. For example, modifying the error message +in the previous example to end in a new line causes Octave to only print +a single message: + +@example +@group +function h () nargin == 1 || error ("nargin != 1\n"); end +f () +error: nargin != 1 +@end group +@end example +@end deftypefn + +@defvr {Built-in Variable} error_text +This variable contains the the text of error messages that would have +been printed in the body of the most recent @code{unwind_protect} or +@code{try} statement or the @var{try} part of the most recent call to +the @code{eval} function. Outside of the @code{unwind_protect} and +@code{try} statements or the @code{eval} function, or if no error has +ocurred within them, the value of @code{error_text} is guaranteed to be +the empty string. + +Note that the message does not include the first @samp{error: } prefix, +so that it may easily be passed to the @code{error} function without +additional processing@footnote{Yes, it's a kluge, but it seems to be a +reasonably useful one.}. + +@xref{The try Statement} and @ref{The unwind_protect Statement}. +@end defvr + +@defvr {Built-in Variable} beep_on_error +If the value of @code{beep_on_error} is nonzero, Octave will try +to ring your terminal's bell before printing an error message. The +default value is 0. +@end defvr + +@deftypefn {Built-in Function} {} warning (@var{msg}) +Print the message @var{msg} prefixed by the string @samp{warning: }. +@end deftypefn + +@deftypefn {Built-in Function} {} usage (@var{msg}) +Print the message @var{msg}, prefixed by the string @samp{usage: }, and +set Octave's internal error state such that control will return to the +top level without evaluating any more commands. This is useful for +aborting from functions. + +After @code{usage} is evaluated, Octave will print a traceback of all +the function calls leading to the usage message. +@end deftypefn + +The following pair of functions are of limited usefulness, and may be +removed from future versions of Octave. + +@deftypefn {Function File} {} perror (@var{name}, @var{num}) +Print the error message for function @var{name} corresponding to the +error number @var{num}. This function is intended to be used to print +useful error messages for those functions that return numeric error +codes. +@end deftypefn + +@deftypefn {Function File} {} strerror (@var{name}, @var{num}) +Return the text of an error message for function @var{name} +corresponding to the error number @var{num}. This function is intended +to be used to print useful error messages for those functions that +return numeric error codes. +@end deftypefn
new file mode 100644 --- /dev/null +++ b/doc/interpreter/eval.texi @@ -0,0 +1,110 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Evaluation, Statements, Expressions, Top +@chapter Evaluation + +Normally, you evaluate expressions simply by typing them at the Octave +prompt, or by asking Octave to interpret commands that you have saved in +a file. + +Sometimes, you may find it necessary to evaluate an expression that has +been computed and stored in a string, or use a string as the name of a +function to call. The @code{eval} and @code{feval} functions allow you +to do just that, and are necessary in order to evaluate commands that +are not known until run time, or to write functions that will need to +call user-supplied functions. + +@deftypefn {Built-in Function} {} eval (@var{command}) +Parse the string @var{command} and evaluate it as if it were an Octave +program, returning the last value computed. The @var{command} is +evaluated in the current context, so any results remain available after +@code{eval} returns. For example, + +@example +octave:13> a +error: `a' undefined +octave:14> eval ("a = 13") +a = 13 +ans = 13 +octave:15> a +a = 13 +@end example + +In this case, two values are printed: one for the expression that was +evaluated, and one for the value returned from @code{eval}. Just as +with any other expression, you can turn printing off by ending the +expression in a semicolon. For example, + +@example +octave:13> a +error: `a' undefined +octave:14> eval ("a = 13;") +ans = 13 +octave:15> a +a = 13 +@end example +@end deftypefn + +@deftypefn {Built-in Function} {} feval (@var{name}, @dots{}) +Evaluate the function named @var{name}. Any arguments after the first +are passed on to the named function. For example, + +@example +octave:12> feval ("acos", -1) +ans = 3.1416 +@end example + +@noindent +calls the function @code{acos} with the argument @samp{-1}. + +The function @code{feval} is necessary in order to be able to write +functions that call user-supplied functions, because Octave does not +have a way to declare a pointer to a function (like C) or to declare a +special kind of variable that can be used to hold the name of a function +(like @code{EXTERNAL} in Fortran). Instead, you must refer to functions +by name, and use @code{feval} to call them. +@end deftypefn + +@cindex Fordyce, A. P. +@findex newtroot +Here is a simple-minded function using @code{feval} that finds the root +of a user-supplied function of one variable using Newton's method. + +@example +@group +function result = newtroot (fname, x) + +# usage: newtroot (fname, x) +# +# fname : a string naming a function f(x). +# x : initial guess + + delta = tol = sqrt (eps); + maxit = 200; + fx = feval (fname, x); + for i = 1:maxit + if (abs (fx) < tol) + result = x; + return; + else + fx_new = feval (fname, x + delta); + deriv = (fx_new - fx) / delta; + x = x - fx / deriv; + fx = fx_new; + endif + endfor + + result = x; + +endfunction +@end group +@end example + +Note that this is only meant to be an example of calling user-supplied +functions and should not be taken too seriously. In addition to using a +more robust algorithm, any serious code would check the number and type +of all the arguments, ensure that the supplied function really was a +function, etc. +
new file mode 100644 --- /dev/null +++ b/doc/interpreter/grammar.texi @@ -0,0 +1,53 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Grammar, Copying, Emacs, Top +@chapter Grammar +@cindex grammar rules +@cindex language definition + +Someday I hope to expand this to include a semi-formal description of +Octave's language. + +@menu +* Keywords:: +@end menu + +@node Keywords, , Grammar, Grammar +@section Keywords +@cindex keywords + +The following identifiers are keywords, and may not be used as variable +or function names: + +@example +@group +all_va_args endwhile +break for +catch function +continue global +else gplot +elseif gsplot +end if +end_try_catch return +end_unwind_protect try +endfor unwind_protect +endfunction unwind_protect_cleanup +endif while +@end group +@end example + +The following command-like functions are also reserved, and may not be +used as variable or function names: + +@example +@group +casesen echo load show +cd edit_history ls type +chdir format more which +clear help run_history who +diary history save whos +dir hold set +@end group +@end example
new file mode 100644 --- /dev/null +++ b/doc/interpreter/numbers.texi @@ -0,0 +1,532 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Numeric Data Types, Strings, Data Types, Top +@chapter Numeric Data Types +@cindex numeric constant +@cindex numeric value + +A @dfn{numeric constant} may be a scalar, a vector, or a matrix, and it +may contain complex values. + +The simplest form of a numeric constant, a scalar, is a single number +that can be an integer, a decimal fraction, a number in scientific +(exponential) notation, or a complex number. Note that all numeric +constants are represented within Octave in double-precision floating +point format (complex constants are stored as pairs of double-precision +floating point values). Here are some examples of real-valued numeric +constants, which all have the same value: + +@example +@group +105 +1.05e+2 +1050e-1 +@end group +@end example + +To specify complex constants, you can write an expression of the form + +@example +@group +3 + 4i +3.0 + 4.0i +0.3e1 + 40e-1i +@end group +@end example + +all of which are equivalent. The letter @samp{i} in the previous example +stands for the pure imaginary constant, defined as +@iftex +@tex + $\sqrt{-1}$. +@end tex +@end iftex +@ifinfo + @code{sqrt (-1)}. +@end ifinfo + +For Octave to recognize a value as the imaginary part of a complex +constant, a space must not appear between the number and the @samp{i}. +If it does, Octave will print an error message, like this: + +@example +@group +octave:13> 3 + 4 i + +parse error: + + 3 + 4 i + ^ +@end group +@end example + +You may also use @samp{j}, @samp{I}, or @samp{J} in place of the +@samp{i} above. All four forms are equivalent. + +@menu +* Matrices:: +* Ranges:: +* Predicates for Numeric Objects:: +@end menu + +@node Matrices, Ranges, Numeric Data Types, Numeric Data Types +@section Matrices +@cindex matrices + +@opindex [ +@opindex ] +@opindex ; +@opindex , + +It is easy to define a matrix of values in Octave. The size of the +matrix is determined automatically, so it is not necessary to explicitly +state the dimensions. The expression + +@example +a = [1, 2; 3, 4] +@end example + +@noindent +results in the matrix + +@iftex +@tex +$$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$ +@end tex +@end iftex +@ifinfo +@example +@group + + / \ + | 1 2 | + a = | | + | 3 4 | + \ / + +@end group +@end example +@end ifinfo + +Elements of a matrix may be arbitrary expressions, provided that the +dimensions all make sense when combining the various pieces. For +example, given the above matrix, the expression + +@example +[ a, a ] +@end example + +@noindent +produces the matrix + +@example +@group +ans = + + 1 2 1 2 + 3 4 3 4 +@end group +@end example + +@noindent +but the expression + +@example +[ a, 1 ] +@end example + +@noindent +produces the error + +@example +error: number of rows must match near line 13, column 6 +@end example + +@noindent +(assuming that this expression was entered as the first thing on line +13, of course). + +Inside the square brackets that delimit a matrix expression, Octave +looks at the surrounding context to determine whether spaces and newline +characters should be converted into element and row separators, or +simply ignored, so commands like + +@example +[ linspace (1, 2) ] +@end example + +@noindent +and + +@example +@group +a = [ 1 2 + 3 4 ] +@end group +@end example + +@noindent +will work. However, some possible sources of confusion remain. For +example, in the expression + +@example +[ 1 - 1 ] +@end example + +@noindent +the @samp{-} is treated as a binary operator and the result is the +scalar 0, but in the expression + +@example +[ 1 -1 ] +@end example + +@noindent +the @samp{-} is treated as a unary operator and the result is the +vector @code{[ 1 -1 ]}. + +Given @code{a = 1}, the expression + +@example +[ 1 a' ] +@end example + +@noindent +results in the single quote character @samp{'} being treated as a +transpose operator and the result is the vector @code{[ 1 1 ]}, but the +expression + +@example +[ 1 a ' ] +@end example + +@noindent +produces the error message + +@example +error: unterminated string constant +@end example + +@noindent +because to not do so would make it impossible to correctly parse the +valid expression + +@example +[ a 'foo' ] +@end example + +For clarity, it is probably best to always use commas and semicolons to +separate matrix elements and rows. It is possible to enforce this style +by setting the built-in variable @code{whitespace_in_literal_matrix} to +@code{"ignore"}. + +@defvr {Built-in Variable} whitespace_in_literal_matrix +This variable allows some control over how Octave decides to convert +spaces to commas and semicolons in matrix expressions like +@samp{[m (1)]} or + +@example +[ 1, 2, + 3, 4 ] +@end example + +If the value of @code{whitespace_in_literal_matrix} is @code{"ignore"}, +Octave will never insert a comma or a semicolon in a literal matrix +list. For example, the expression @samp{[1 2]} will result in an error +instead of being treated the same as @samp{[1, 2]}, and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in the vector [1 2 3 4] instead of a matrix. + +If the value of @code{whitespace_in_literal_matrix} is @code{"traditional"}, +Octave will convert spaces to a comma between identifiers and @samp{(}. For +example, given the matrix + +@example +m = [3 2] +@end example + +@noindent +the expression + +@example +[m (1)] +@end example + +@noindent +will be parsed as + +@example +[m, (1)] +@end example + +@noindent +and will result in + +@example +[3 2 1] +@end example + +@noindent +and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in a matrix because the newline character is converted to a +semicolon (row separator) even though there is a comma at the end of the +first line (trailing commas or semicolons are ignored). This is +apparently how @sc{Matlab} behaves. + +Any other value for @code{whitespace_in_literal_matrix} results in behavior +that is the same as traditional, except that Octave does not +convert spaces to a comma between identifiers and @samp{(}. For +example, the expression + +@example +[m (1)] +@end example + +will produce @samp{3}. This is the way Octave has always behaved. +@end defvr + +When you type a matrix or the name of a variable whose value is a +matrix, Octave responds by printing the matrix in with neatly aligned +rows and columns. If the rows of the matrix are too large to fit on the +screen, Octave splits the matrix and displays a header before each +section to indicate which columns are being displayed. + +@noindent +You can use the following variables to control the format of the output. + +@defvr {Built-in Variable} output_max_field_width +This variable specifies the maximum width of a numeric output field. +The default value is 10. +@end defvr + +@defvr {Built-in Variable} output_precision +This variable specifies the minimum number of significant figures to +display for numeric output. The default value is 5. +@end defvr + +It is possible to achieve a wide range of output styles by using +different values of @code{output_precision} and +@code{output_max_field_width}. Reasonable combinations can be set using +the @code{format} function. @xref{Basic Input and Output}. + +@defvr {Built-in Variable} split_long_rows +For large matrices, Octave may not be able to display all the columns of +a given row on one line of your screen. This can result in missing +information or output that is nearly impossible to decipher, depending +on whether your terminal truncates or wraps long lines. + +If the value of @code{split_long_rows} is nonzero, Octave will display +the matrix in a series of smaller pieces, each of which can fit within +the limits of your terminal width. Each set of rows is labeled so that +you can easily see which columns are currently being displayed. +For example: + +@smallexample +@group +octave:13> rand (2,10) +ans = + + Columns 1 through 6: + + 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467 + 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201 + + Columns 7 through 10: + + 0.90174 0.11854 0.72313 0.73326 + 0.44672 0.94303 0.56564 0.82150 +@end group +@end smallexample + +@noindent +The default value of @code{split_long_rows} is nonzero. +@end defvr + +@menu +* Empty Matrices:: +@end menu + +@node Empty Matrices, , Matrices, Matrices +@subsection Empty Matrices + +A matrix may have one or both dimensions zero, and operations on empty +matrices are handled as described by Carl de Boor in @cite{An Empty +Exercise}, SIGNUM, Volume 25, pages 2--6, 1990 and C. N. Nett and W. M. +Haddad, in @cite{A System-Theoretic Appropriate Realization of the Empty +Matrix Concept}, IEEE Transactions on Automatic Control, Volume 38, +Number 5, May 1993. Briefly, given a scalar @code{s}, and an @var{m} by +@var{n} matrix @code{M(mxn)}, and an @var{m} by @var{n} empty matrix +@code{[](mxn)} (with either one or both dimensions equal to zero), the +following are true: + +@example +@group +s * [](mxn) = [](mxn) * s = [](mxn) + + [](mxn) + [](mxn) = [](mxn) + + [](0xm) * M(mxn) = [](0xn) + + M(mxn) * [](nx0) = [](mx0) + + [](mx0) * [](0xn) = 0(mxn) +@end group +@end example + +By default, dimensions of the empty matrix are printed along with the +empty matrix symbol, @samp{[]}. For example: + +@example +@group +octave:13> zeros (3, 0) +ans = + +[](3x0) +@end group +@end example + +The built-in variable @code{print_empty_dimensions} controls this +behavior. + +@defvr {Built-in Variable} print_empty_dimensions +If the value of @code{print_empty_dimensions} is nonzero, the +dimensions of empty matrices are printed along with the empty matrix +symbol, @samp{[]}. For example, the expression + +@example +zeros (3, 0) +@end example + +@noindent +will print + +@example +ans = + +[](3x0) +@end example +@end defvr + +Empty matrices may also be used in assignment statements as a convenient +way to delete rows or columns of matrices. +@xref{Assignment Ops, ,Assignment Expressions}. + +Octave will normally issue a warning if it finds an empty matrix in the +list of elements that make up another matrix. You can use the variable +@code{empty_list_elements_ok} to suppress the warning or to treat it as +an error. + +@defvr {Built-in Variable} empty_list_elements_ok +This variable controls whether Octave ignores empty matrices in a matrix +list. + +For example, if the value of @code{empty_list_elements_ok} is +nonzero, Octave will ignore the empty matrices in the expression + +@example +a = [1, [], 3, [], 5] +@end example + +@noindent +and the variable @samp{a} will be assigned the value @samp{[ 1 3 5 ]}. + +The default value is @code{"warn"}. +@end defvr + +When Octave parses a matrix expression, it examines the elements of the +list to determine whether they are all constants. If they are, it +replaces the list with a single matrix constant. + +@defvr {Built-in Variable} propagate_empty_matrices +If the value of @code{propagate_empty_matrices} is nonzero, +functions like @code{inverse} and @code{svd} will return an empty matrix +if they are given one as an argument. The default value is 1. +@end defvr + +@node Ranges, Predicates for Numeric Objects, Matrices, Numeric Data Types +@section Ranges +@cindex range expressions +@cindex expression, range + +@opindex : + +A @dfn{range} is a convenient way to write a row vector with evenly +spaced elements. A range expression is defined by the value of the first +element in the range, an optional value for the increment between +elements, and a maximum value which the elements of the range will not +exceed. The base, increment, and limit are separated by colons (the +@samp{:} character) and may contain any arithmetic expressions and +function calls. If the increment is omitted, it is assumed to be 1. +For example, the range + +@example +1 : 5 +@end example + +@noindent +defines the set of values @samp{[ 1 2 3 4 5 ]}, and the range + +@example +1 : 3 : 5 +@end example + +@noindent +defines the set of values @samp{[ 1 4 ]}. + +Although a range constant specifies a row vector, Octave does @emph{not} +convert range constants to vectors unless it is necessary to do so. +This allows you to write a constant like @samp{1 : 10000} without using +80,000 bytes of storage on a typical 32-bit workstation. + +Note that the upper (or lower, if the increment is negative) bound on +the range is not always included in the set of values, and that ranges +defined by floating point values can produce surprising results because +Octave uses floating point arithmetic to compute the values in the +range. If it is important to include the endpoints of a range and the +number of elements is known, you should use the @code{linspace} function +instead (@pxref{Special Utility Matrices}). + +When Octave parses a range expression, it examines the elements of the +expression to determine whether they are all constants. If they are, it +replaces the range expression with a single range constant. + +@node Predicates for Numeric Objects, , Ranges, Numeric Data Types +@section Predicates for Numeric Objects + +@deftypefn {Function File} {} is_matrix (@var{a}) +Return 1 if @var{a} is a matrix. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_vector (@var{a}) +Return 1 if @var{a} is a vector. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_scalar (@var{a}) +Return 1 if @var{a} is a scalar. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_square (@var{x}) +If @var{x} is a square matrix, then return the dimension of @var{x}. +Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_symmetric (@var{x}, @var{tol}) +If @var{x} is symmetric within the tolerance specified by @var{tol}, +then return the dimension of @var{x}. Otherwise, return 0. If +@var{tol} is omitted, use a tolerance equal to the machine precision. +@end deftypefn
new file mode 100644 --- /dev/null +++ b/doc/interpreter/struct.texi @@ -0,0 +1,201 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Data Structures, Variables, Strings, Top +@chapter Data Structures +@cindex structures +@cindex data structures + +Octave includes support for organizing data in structures. The current +implementation uses an associative array with indices limited to +strings, but the syntax is more like C-style structures. Here are some +examples of using data structures in Octave. + +Elements of structures can be of any value type. For example, the three +expressions + +@example +@group +x.a = 1 +x.b = [1, 2; 3, 4] +x.c = "string" +@end group +@end example + +@noindent +create a structure with three elements. To print the value of the +structure, you can type its name, just as for any other variable: + +@example +@group +octave:2> x +x = +@{ + a = 1 + b = + + 1 2 + 3 4 + + c = string +@} +@end group +@end example + +@noindent +Note that Octave may print the elements in any order. + +Structures may be copied. + +@example +@group +octave:1> y = x +y = +@{ + a = 1 + b = + + 1 2 + 3 4 + + c = string +@} +@end group +@end example + +Since structures are themselves values, structure elements may reference +other structures. The following statements change the value of the +element @code{b} of the structure @code{x} to be a data structure +containing the single element @code{d}, which has a value of 3. + +@example +@group +octave:1> x.b.d = 3 +x.b.d = 3 +octave:2> x.b +ans = +@{ + d = 3 +@} +octave:3> x +x = +@{ + a = 1 + b = + @{ + d = 3 + @} + + c = string +@} +@end group +@end example + +Note that when Octave prints the value of a structure that contains +other structures, only a few levels are displayed. For example, + +@example +@group +octave:1> a.b.c.d.e = 1; +octave:2> a +a = +@{ + b = + @{ + c = <structure> + @} +@} +@end group +@end example + +@noindent +This prevents long and confusing output from large deeply nested +structures. + +@defvr {Built-in Variable} struct_levels_to_print +You can tell Octave how many structure levels to display by setting the +built-in variable @code{struct_levels_to_print}. The default value is 2. +@end defvr + +Functions can return structures. For example, the following function +separates the real and complex parts of a matrix and stores them in two +elements of the same structure variable. + +@example +@group +octave:1> function y = f (x) +> y.re = real (x); +> y.im = imag (x); +> endfunction +@end group +@end example + +When called with a complex-valued argument, @code{f} returns the data +structure containing the real and imaginary parts of the original +function argument. + +@example +@group +octave:2> f (rand (3) + rand (3) * I); +ans = +@{ + im = + + 0.26475 0.14828 + 0.18436 0.83669 + + re = + + 0.040239 0.242160 + 0.238081 0.402523 +@} +@end group +@end example + +Function return lists can include structure elements, and they may be +indexed like any other variable. For example, + +@example +@group +octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) +x.u = + + -0.40455 -0.91451 + -0.91451 0.40455 + +x.s = + + 0.00000 0.00000 0.00000 + 0.00000 5.46499 0.00000 + 0.00000 0.00000 0.36597 + +x.v = + + -0.57605 0.81742 + -0.81742 -0.57605 +@end group +@end example + +It is also possible to cycle through all the elements of a structure in +a loop, using a special form of the @code{for} statement +(@pxref{The for Statement}) + +The following functions are available to give you information about +structures. + +@deftypefn {Built-in Function} {} is_struct (@var{expr}) +Returns 1 if the value of the expression @var{expr} is a structure. +@end deftypefn + +@deftypefn {Built-in Function} {} struct_contains (@var{expr}, @var{name}) +This function returns 1 if the expression @var{expr} is a structure and it +includes an element named @var{name}. The first argument must be a +structure and the second must be a string. +@end deftypefn + +@deftypefn {Built-in Function} {} struct_elements (@var{expr}) +If the expression @var{expr} is a structure, this function returns a +list of strings naming the elements of the structure. It is an error to +call @code{struct_elements} with an argument that is not a structure. +@end deftypefn
new file mode 100644 --- /dev/null +++ b/doc/interpreter/tips.texi @@ -0,0 +1,355 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Tips, Trouble, System Utilities, Top +@appendix Tips and Standards +@cindex tips +@cindex standards of coding style +@cindex coding standards + +This chapter describes no additional features of Octave. Instead it +gives advice on making effective use of the features described in the +previous chapters. + +@menu +* Style Tips:: Writing clean and robust programs. +* Coding Tips:: Making code run faster. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Function Headers:: Standard headers for functions. +@end menu + +@node Style Tips, Coding Tips, Tips, Tips +@section Writing Clean Octave Programs + +Here are some tips for avoiding common errors in writing Octave code +intended for widespread use: + +@itemize @bullet +@item +Since all global variables share the same name space, and all functions +share another name space, you should choose a short word to distinguish +your program from other Octave programs. Then take care to begin the +names of all global variables, constants, and functions with the chosen +prefix. This helps avoid name conflicts. + +If you write a function that you think ought to be added to Octave under +a certain name, such as @code{twiddle-matrix}, don't call it by that name +in your program. Call it @code{mylib-twiddle-matrix} in your program, +and send mail to @samp{bug-octave@@bevo.che.wisc.edu} suggesting that it +be added to Octave. If and when it is, the name can be changed easily +enough. + +If one prefix is insufficient, your package may use two or three +alternative common prefixes, so long as they make sense. + +Separate the prefix from the rest of the symbol name with an underscore +@samp{_}. This will be consistent with Octave itself and with most +Octave programs. + +@item +When you encounter an error condition, call the function @code{error} +(or @code{usage}). The function @code{error} does not return. +@xref{Errors}. + +@item +Please put a copyright notice on the file if you give copies to anyone. +Use the same lines that appear at the top of the function files +distributed with Octave. If you have not signed papers to assign the +copyright to anyone else, then place your name in the copyright notice. +@end itemize + +@node Coding Tips, Documentation Tips, Style Tips, Tips +@section Tips for Making Code Run Faster. +@cindex execution speed +@cindex speedups + +Here are some ways of improving the execution speed of Octave programs. + +@itemize @bullet +@item +Avoid looping wherever possible. + +@item +Use iteration rather than recursion whenever possible. +Function calls are slow in Octave. + +@item +Avoid resizing matrices unnecessarily. When building a single result +matrix from a series of calculations, set the size of the result matrix +first, then insert values into it. Write + +@example +@group +result = zeros (big_n, big_m) +for i = over:and_over + r1 = @dots{} + r2 = @dots{} + result (r1, r2) = new_value (); +endfor +@end group +@end example + +@noindent +instead of + +@example +@group +result = []; +for i = ever:and_ever + result = [ result, new_value() ]; +endfor +@end group +@end example + +@item +Avoid calling @code{eval} or @code{feval} whenever possible, because +they require Octave to parse input or look up the name of a function in +the symbol table. + +If you are using @code{eval} as an exception handling mechanism and not +because you need to execute some arbitrary text, use the @code{try} +statement instead. @xref{The try Statement}. +@end itemize + +@node Documentation Tips, Comment Tips, Coding Tips, Tips +@section Tips for Documentation Strings + +Here are some tips for the writing of documentation strings. + +@itemize @bullet +@item +Every command, function, or variable intended for users to know about +should have a documentation string. + +@item +An internal variable or subroutine of an Octave program might as well have +a documentation string. + +@item +The first line of the documentation string should consist of one or two +complete sentences that stand on their own as a summary. + +The documentation string can have additional lines that expand on the +details of how to use the function or variable. The additional lines +should also be made up of complete sentences. + +@item +For consistency, phrase the verb in the first sentence of a +documentation string as an infinitive with ``to'' omitted. For +instance, use ``Return the frob of A and B.'' in preference to ``Returns +the frob of A and B@.'' Usually it looks good to do likewise for the +rest of the first paragraph. Subsequent paragraphs usually look better +if they have proper subjects. + +@item +Write documentation strings in the active voice, not the passive, and in +the present tense, not the future. For instance, use ``Return a list +containing A and B.'' instead of ``A list containing A and B will be +returned.'' + +@item +Avoid using the word ``cause'' (or its equivalents) unnecessarily. +Instead of, ``Cause Octave to display text in boldface,'' write just +``Display text in boldface.'' + +@item +Do not start or end a documentation string with whitespace. + +@item +Format the documentation string so that it fits in an Emacs window on an +80-column screen. It is a good idea for most lines to be no wider than +60 characters. + +However, rather than simply filling the entire documentation string, you +can make it much more readable by choosing line breaks with care. +Use blank lines between topics if the documentation string is long. + +@item +@strong{Do not} indent subsequent lines of a documentation string so +that the text is lined up in the source code with the text of the first +line. This looks nice in the source code, but looks bizarre when users +view the documentation. Remember that the indentation before the +starting double-quote is not part of the string! + +@item +The documentation string for a variable that is a yes-or-no flag should +start with words such as ``Nonzero means@dots{}'', to make it clear that +all nonzero values are equivalent and indicate explicitly what zero and +nonzero mean. + +@item +When a function's documentation string mentions the value of an argument +of the function, use the argument name in capital letters as if it were +a name for that value. Thus, the documentation string of the operator +@code{/} refers to its second argument as @samp{DIVISOR}, because the +actual argument name is @code{divisor}. + +Also use all caps for meta-syntactic variables, such as when you show +the decomposition of a list or vector into subunits, some of which may +vary. +@end itemize + +@node Comment Tips, Function Headers, Documentation Tips, Tips +@section Tips on Writing Comments + +Here are the conventions to follow when writing comments. + +@table @samp +@item # +Comments that start with a single sharp-sign, @samp{#}, should all be +aligned to the same column on the right of the source code. Such +comments usually explain how the code on the same line does its job. In +the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) +command automatically inserts such a @samp{#} in the right place, or +aligns such a comment if it is already present. + +@item ## +Comments that start with two semicolons, @samp{##}, should be aligned to +the same level of indentation as the code. Such comments usually +describe the purpose of the following lines or the state of the program +at that point. +@end table + +@noindent +The indentation commands of the Octave mode in Emacs, such as @kbd{M-;} +(@code{indent-for-comment}) and @kbd{TAB} (@code{octave-indent-line}) +automatically indent comments according to these conventions, +depending on the number of semicolons. @xref{Comments,, +Manipulating Comments, emacs, The GNU Emacs Manual}. + +@node Function Headers, , Comment Tips, Tips +@section Conventional Headers for Octave Functions +@cindex header comments + +Octave has conventions for using special comments in function files +to give information such as who wrote them. This section explains these +conventions. + +The top of the file should contain a copyright notice, followed by a +block of comments that can be used as the help text for the function. +Here is an example: + +@example +## Copyright (C) 1996 John W. Eaton +## +## This file is part of Octave. +## +## Octave 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, or (at your option) any later version. +## +## Octave is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied +## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +## PURPOSE. See the GNU General Public License for more +## details. +## +## You should have received a copy of the GNU General Public +## License along with Octave; see the file COPYING. If not, +## write to the Free Software Foundation, 59 Temple Place - +## Suite 330, Boston, MA 02111-1307, USA. + +## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) +## +## Start a subprocess with two-way communication. COMMAND +## specifies the name of the command to start. ARGS is an +## array of strings containing options for COMMAND. IN and +## OUT are the file ids of the input and streams for the +## subprocess, and PID is the process id of the subprocess, +## or -1 if COMMAND could not be executed. +## +## Example: +## +## [in, out, pid] = popen2 ("sort", "-nr"); +## fputs (in, "these\nare\nsome\nstrings\n"); +## fclose (in); +## while (isstr (s = fgets (out))) +## fputs (stdout, s); +## endwhile +## fclose (out); +@end example + +Octave uses the first block of comments in a function file that do not +appear to be a copyright notice as the help text for the file. For +Octave to recognize the first comment block as a copyright notice, it +must match the regular expression + +@example +^ Copyright (C).*\n\n This file is part of Octave. +@end example + +@noindent +or + +@example +^ Copyright (C).*\n\n This program is free softwar +@end example + +@noindent +(after stripping the leading comment characters). This is a fairly +strict requirement, and may be relaxed somewhat in the future. + +After the copyright notice and help text come several @dfn{header +comment} lines, each beginning with @samp{## @var{header-name}:}. For +example, + +@example +@group +## Author: jwe +## Keywords: subprocesses input-output +## Maintainer: jwe +@end group +@end example + +Here is a table of the conventional possibilities for @var{header-name}: + +@table @samp +@item Author +This line states the name and net address of at least the principal +author of the library. + +@smallexample +## Author: John W. Eaton <jwe@@bevo.che.wsic.edu> +@end smallexample + +@item Maintainer +This line should contain a single name/address as in the Author line, or +an address only, or the string @samp{jwe}. If there is no maintainer +line, the person(s) in the Author field are presumed to be the +maintainers. The example above is mildly bogus because the maintainer +line is redundant. + +The idea behind the @samp{Author} and @samp{Maintainer} lines is to make +possible a function to ``send mail to the maintainer'' without +having to mine the name out by hand. + +Be sure to surround the network address with @samp{<@dots{}>} if +you include the person's full name as well as the network address. + +@item Created +This optional line gives the original creation date of the +file. For historical interest only. + +@item Version +If you wish to record version numbers for the individual Octave program, +put them in this line. + +@item Adapted-By +In this header line, place the name of the person who adapted the +library for installation (to make it fit the style conventions, for +example). + +@item Keywords +This line lists keywords. Eventually, it will be used by an apropos +command to allow people will find your package when they're looking for +things by topic area. To separate the keywords, you can use spaces, +commas, or both. +@end table + +Just about every Octave function ought to have the @samp{Author} and +@samp{Keywords} header comment lines. Use the others if they are +appropriate. You can also put in header lines with other header +names---they have no standard meanings, so they can't do any harm.
new file mode 100644 --- /dev/null +++ b/doc/interpreter/var.texi @@ -0,0 +1,555 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Variables, Expressions, Data Structures, Top +@chapter Variables +@cindex variables, user-defined +@cindex user-defined variables + +Variables let you give names to values and refer to them later. You have +already seen variables in many of the examples. The name of a variable +must be a sequence of letters, digits and underscores, but it may not begin +with a digit. Octave does not enforce a limit on the length of variable +names, but it is seldom useful to have variables with names longer than +about 30 characters. The following are all valid variable names + +@cindex job hunting +@cindex getting a good job +@cindex flying high and fast +@example +@group +x +x15 +__foo_bar_baz__ +fucnrdthsucngtagdjb +@end group +@end example + +@noindent +However, names like @code{__foo_bar_baz__} that begin and end with two +underscores are understood to be reserved for internal use by Octave. +You should not use them in code you write, except to access Octave's +documented internal variables and built-in symbolic constants. + +Case is significant in variable names. The symbols @code{a} and +@code{A} are distinct variables. + +A variable name is a valid expression by itself. It represents the +variable's current value. Variables are given new values with +@dfn{assignment operators} and @dfn{increment operators}. +@xref{Assignment Ops, ,Assignment Expressions}. + +A number of variables have special built-in meanings. For example, +@code{PWD} holds the current working directory, and @code{pi} names the +ratio of the circumference of a circle to its diameter. @xref{Summary of +Built-in Variables}, for a list of all the predefined variables. Some +of these built-in symbols are constants and may not be changed. Others +can be used and assigned just like all other variables, but their values +are also used or changed automatically by Octave. + +Variables in Octave do not have fixed types, so it is possible to first +store a numeric value in a variable and then to later use the same name +to hold a string value in the same program. Variables may not be used +before they have been given a value. Doing so results in an error. + +@menu +* Global Variables:: +* Status of Variables:: +* Summary of Built-in Variables:: +* Defaults from the Environment:: +@end menu + +@node Global Variables, Status of Variables, Variables, Variables +@section Global Variables +@cindex global variables +@cindex @code{global} statement +@cindex variables, global + +A variable that has been declared @dfn{global} may be accessed from +within a function body without having to pass it as a formal parameter. + +A variable may be declared global using a @code{global} declaration +statement. The following statements are all global declarations. + +@example +@group +global a +global b = 2 +global c = 3, d, e = 5 +@end group +@end example + +It is necessary declare a variable as global within a function body in +order to access it. For example, + +@example +@group +global x +function f () +x = 1; +endfunction +f () +@end group +@end example + +@noindent +does @emph{not} set the value of the global variable @samp{x} to 1. In +order to change the value of the global variable @samp{x}, you must also +declare it to be global within the function body, like this + +@example +@group +function f () + global x; + x = 1; +endfunction +@end group +@end example + +Passing a global variable in a function parameter list will +make a local copy and not modify the global value. For example, given +the function + +@example +@group +function f (x) + x = 0 +endfunction +@end group +@end example + +@noindent +and the definition of @samp{x} as a global variable at the top level, + +@example +global x = 13 +@end example + +@noindent +the expression + +@example +f (x) +@end example + +@noindent +will display the value of @samp{x} from inside the function as @samp{0}, +but the value of @samp{x} at the top level remains unchanged, because +the function works with a @emph{copy} of its argument. + +@defvr {Built-in Variable} warn_comma_in_global_decl +If the value of @code{warn_comma_in_global_decl} is nonzero, a +warning is issued for statements like + +@example +global a = 1, b +@end example + +@noindent +which makes the variables @samp{a} and @samp{b} global and assigns the +value 1 to the variable @samp{a}, because in this context, the comma is +not interpreted as a statement separator. + +The default value of @code{warn_comma_in_global_decl} is nonzero. +@end defvr + +@deftypefn {Built-in Function} {} is_global (@var{name}) +Return 1 if @var{name} is globally visible. Otherwise, return 0. For +example, + +@example +@group +global x +is_global ("x") + @result{} 1 +@end group +@end example +@end deftypefn + +@node Status of Variables, Summary of Built-in Variables, Global Variables, Variables +@section Status of Variables + +@deffn {Command} clear options pattern @dots{} +Delete the names matching the given patterns from the symbol table. The +pattern may contain the following special characters: +@table @code +@item ? +Match any single character. + +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will +match all lower and upper case alphabetic characters. +@end table + +For example, the command + +@example +clear foo b*r +@end example + +@noindent +clears the name @code{foo} and all names that begin with the letter +@code{b} and end with the letter @code{r}. + +If @code{clear} is called without any arguments, all user-defined +variables (local and global) are cleared from the symbol table. If +@code{clear} is called with at least one argument, only the visible +names matching the arguments are cleared. For example, suppose you have +defined a function @code{foo}, and then hidden it by performing the +assignment @code{foo = 2}. Executing the command @samp{clear foo} once +will clear the variable definition and restore the definition of +@code{foo} as a function. Executing @samp{clear foo} a second time will +clear the function definition. + +This command may not be used within a function body. +@end deffn + +@deffn {Command} who options pattern @dots{} +@deffnx {Command} whos options pattern @dots{} +List currently defined symbols matching the given patterns. The +following are valid options. They may be shortened to one character but +may not be combined. + +@table @code +@item -all +List all currently defined symbols. + +@item -builtins +List built-in variables and functions. This includes all currently +compiled function files, but does not include all function files that +are in the @code{LOADPATH}. + +@item -functions +List user-defined functions. + +@item -long +Print a long listing including the type and dimensions of any symbols. +The symbols in the first column of output indicate whether it is +possible to redefine the symbol, and whether it is possible for it to be +cleared. + +@item -variables +List user-defined variables. +@end table + +Valid patterns are the same as described for the @code{clear} command +above. If no patterns are supplied, all symbols from the given category +are listed. By default, only user defined functions and variables +visible in the local scope are displayed. + +The command @code{whos} is equivalent to @code{who -long}. +@end deffn + +@deftypefn {Built-in Function} {} exist (@var{name}) +Return 1 if the name exists as a variable, and 2 if the name (after +appending @samp{.m}) is a function file in the path. Otherwise, return +0. +@end deftypefn + +@deftypefn {Built-in Function} {} document (@var{symbol}, @var{text}) +Set the documentation string for @var{symbol} to @var{text}. +@end deftypefn + +@deffn {Command} type options name @dots{} +Display the definition of each @var{name} that refers to a function. + +Normally also displays if each @var{name} is user-defined or builtin; +the @code{-q} option suppresses this behaviour. + +Currently, Octave can only display functions that can be compiled +cleanly, because it uses its internal representation of the function to +recreate the program text. + +Comments are not displayed because Octave's parser currently discards +them as it converts the text of a function file to its internal +representation. This problem may be fixed in a future release. +@end deffn + +@deffn {Command} which name @dots{} +Display the type of each @var{name}. If @var{name} is defined from a +function file, the full name of the file is also displayed. +@end deffn + +@node Summary of Built-in Variables, Defaults from the Environment, Status of Variables, Variables +@section Summary of Built-in Variables + +Here is a summary of all of Octave's built-in variables along with +cross references to additional information and their default values. In +the following table @code{OCT_HOME} stands for the root directory where +Octave is installed (for example, @file{@value{OCTAVEHOME}}, @code{VERSION} +stands for the Octave version number (for example, @value{VERSION}, and +@code{SYS} stands for the type of system for which Octave was compiled +(for example, @code{@value{TARGETHOSTTYPE}}). + +@vtable @code +@item EDITOR +@xref{Commands For History}. + +Default value: @code{"vi"}. + +@item EXEC_PATH +@xref{Controlling Subprocesses}. + +Default value: @code{":$PATH"}. + +@item INFO_FILE +@xref{Getting Help}. + +Default value: @code{"OCT_HOME/info/octave.info"}. + +@item INFO_PROGRAM +@xref{Getting Help}. + +Default value: @code{"OCT_HOME/libexec/octave/VERSION/exec/SYS/info"}. + +@item LOADPATH +@xref{Function Files}. + +Default value: @code{".:OCT_HOME/lib/VERSION"}. + +@item PAGER +@xref{Input and Output}. + +Default value: @code{"less", or "more"}. + +@item PS1 +@xref{Customizing the Prompt}. + +Default value: @code{"\s:\#> "}. + +@item PS2 +@xref{Customizing the Prompt}. + +Default value: @code{"> "}. + +@item PS4 +@xref{Customizing the Prompt}. + +Default value: @code{"+ "}. + +@item automatic_replot +@xref{Two-Dimensional Plotting}. + +Default value: 0. + +@item beep_on_error +@xref{Error Handling}. + +Default value: 0. + +@item completion_append_char +@xref{Commands For Completion}. + +Default value: @code{" "}. + +@item default_return_value +@xref{Multiple Return Values}. + +Default value: @code{[]}. + +@item do_fortran_indexing +@xref{Index Expressions}. + +Default value: 0. + +@item define_all_return_values +@xref{Multiple Return Values}. + +Default value: 0. + +@item empty_list_elements_ok +@xref{Empty Matrices}. + +Default value: @code{"warn"}. + +@item gnuplot_binary +@xref{Three-Dimensional Plotting}. + +Default value: @code{"gnuplot"}. + +@item history_file +@xref{Commands For History}. + +Default value: @code{"~/.octave_hist"}. + +@item history_size +@xref{Commands For History}. + +Default value: 1024. + +@item ignore_function_time_stamp +@xref{Function Files}. + +Default value: @code{"system"}. + +@item implicit_str_to_num_ok +@xref{String Conversions}. + +Default value: 0. + +@item ok_to_lose_imaginary_part +@xref{Special Utility Matrices}. + +Default value: @code{"warn"}. + +@item output_max_field_width +@xref{Matrices}. + +Default value: 10. + +@item output_precision +@xref{Matrices}. + +Default value: 5. + +@item page_screen_output +@xref{Input and Output}. + +Default value: 1. + +@item prefer_column_vectors +@xref{Index Expressions}. + +Default value: 0. + +@item prefer_zero_one_indexing +@xref{Index Expressions}. + +Default value: 0. + +@item print_answer_id_name +@xref{Terminal Output}. + +Default value: 1. + +@item print_empty_dimensions +@xref{Empty Matrices}. + +Default value: 1. + +@item resize_on_range_error +@xref{Index Expressions}. + +Default value: 1. + +@item return_last_computed_value +@xref{Returning From a Function}. + +Default value: 0. + +@item save_precision +@xref{Simple File I/O}. + +Default value: 17. + +@item saving_history +@xref{Commands For History}. + +Default value: 1. + +@item silent_functions +@xref{Defining Functions}. + +Default value: 0. + +@item split_long_rows +@xref{Matrices}. + +Default value: 1. + +@item struct_levels_to_print +@xref{Data Structures}. + +Default value: 2. + +@item suppress_verbose_help_message +@xref{Getting Help}. + +Default value: 1. + +@item treat_neg_dim_as_zero +@xref{Special Utility Matrices}. + +Default value: 0. + +@item warn_assign_as_truth_value +@xref{The if Statement}. + +Default value: 1. + +@item warn_comma_in_global_decl +@xref{Global Variables}. + +Default value: 1. + +@item warn_divide_by_zero +@xref{Arithmetic Ops}. + +Default value: 1. + +@item warn_function_name_clash +@xref{Function Files}. + +Default value: 1. + +@item whitespace_in_literal_matrix +@xref{Matrices}. + +Default value: @code{""}. +@end vtable + + +@node Defaults from the Environment, , Summary of Built-in Variables, Variables +@section Defaults from the Environment + +Octave uses the values of the following environment variables to set the +default values for the corresponding built-in variables. In addition, +the values from the environment may be overridden by command-line +arguments. @xref{Command Line Options}. + +@vtable @code +@item EDITOR +@xref{Commands For History}. + +Built-in variable: @code{EDITOR}. + +@item OCTAVE_EXEC_PATH +@xref{Controlling Subprocesses}. + +Built-in variable: @code{EXEC_PATH}. +Command-line argument: @code{--exec-path}. + +@item OCTAVE_PATH +@xref{Function Files}. + +Built-in variable: @code{LOADPATH}. +Command-line argument: @code{--path}. + +@item OCTAVE_INFO_FILE +@xref{Getting Help}. + +Built-in variable: @code{INFO_FILE}. +Command-line argument: @code{--info-file}. + +@item OCTAVE_INFO_PROGRAM +@xref{Getting Help}. + +Built-in variable: @code{INFO_PROGRAM}. +Command-line argument: @code{--info-program}. + +@item OCTAVE_HISTSIZE +@xref{Commands For History}. + +Built-in variable: @code{history_size}. + +@item OCTAVE_HISTFILE +@xref{Commands For History}. + +Built-in variable: @code{history_file}. +@end vtable