--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/var.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,624 @@
+@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{ans} 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 @code{x} to 1.  In
+order to change the value of the global variable @code{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 @code{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 @code{x} from inside the function as 0,
+but the value of @code{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 @code{a} and @code{b} global and assigns the
+value 1 to the variable @code{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
+
+@defvr default_global_variable_value
+if @code{initialize_global_variables} is nonzero, the value of
+@code{default_glbaol_variable_value} is used as the initial value of
+global variables that are not explicitly initialized.  for example,
+
+@example
+@group
+initialize_global_variables = 1;
+default_global_variable_value = 13;
+global foo;
+foo
+     @result{} 13
+@end group
+@end example
+
+the variable @code{default_global_variable_value} is initially undefined.
+@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 @kbd{clear foo} once
+will clear the variable definition and restore the definition of
+@code{foo} as a function.  Executing @kbd{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 @kbd{whos} is equivalent to @kbd{who -long}.
+@end deffn
+
+@deftypefn {Built-in Function} {} exist (@var{name})
+Return 1 if the name exists as a variable, 2 if the name (after
+appending @samp{.m}) is a function file in the path, 3 if the name is a
+@samp{.oct} file in the path, or 5 if the name is a built-in function.
+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 @var{octave-home} stands for the root directory
+where all of Octave is installed (the default is @file{@value{OCTAVEHOME}},
+@var{version} stands for the Octave version number (for example,
+@value{VERSION}) and @var{arch} stands for the type of system for which
+Octave was compiled (for example, @code{@value{TARGETHOSTTYPE}}).
+
+@vtable @code
+@item DEFAULT_LOADPATH
+@xref{Function Files}.
+
+Default value: @code{".:@var{octave-home}/lib/@var{version}"}.
+
+@item EDITOR
+@xref{Commands For History}.
+
+Default value: @code{"emacs"}.
+
+@item EXEC_PATH
+@xref{Controlling Subprocesses}.
+
+Default value: @code{":$PATH"}.
+
+@item INFO_FILE
+@xref{Getting Help}.
+
+Default value: @code{"@var{octave-home}/info/octave.info"}.
+
+@item INFO_PROGRAM
+@xref{Getting Help}.
+
+Default value: @code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"}.
+
+@item LOADPATH
+@xref{Function Files}.
+
+Default value: @code{":"}, which tells Octave to use the directories
+specified by the built-in variable @code{DEFAULT_LOADPATH}.
+
+@item OCTAVE_HOME
+
+Default value: @code{"@value{OCTAVEHOME}"}.
+
+@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 auto_unload_dot_oct_files
+@xref{Dynamically Linked Functions}.
+
+Default value: 0.
+
+@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_eval_print_flag
+@xref{Evaluation}.
+
+Default value: 1.
+
+@item default_return_value
+@xref{Multiple Return Values}.
+
+Default value: @code{[]}.
+
+@item default_save_format
+@xref{Simple File I/O}.
+
+Default value: @code{"ascii"}.
+
+@item do_fortran_indexing
+@xref{Index Expressions}.
+
+Default value: 0.
+
+@item crash_dumps_octave_core
+@xref{Simple File I/O}.
+
+Default value: 1.
+
+@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 fixed_point_format
+@xref{Matrices}.
+
+Default value: 0.
+
+@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_num_to_str_ok
+@xref{String Conversions}.
+
+Default value: 0.
+
+@item implicit_str_to_num_ok
+@xref{String Conversions}.
+
+Default value: 0.
+
+@item max_recursion_depth
+@xref{Recursion}.
+
+Default value: 256.
+
+@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: 1.
+
+@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 warn_reload_forces_clear
+@xref{Dynamically Linked Functions}.
+
+Default value: 1.
+
+@item warn_variable_switch_label
+@xref{The switch Statement}.
+
+Default value: 0.
+
+@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