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

     x
     x15
     __foo_bar_baz__
     fucnrdthsucngtagdjb

However, names like __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 a and 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 assignment operators and increment operators. See Assignment Expressions.

A number of variables have special built-in meanings.  For example, PWD holds the current working directory, and pi names the ratio of the circumference of a circle to its diameter. See 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.

Global Variables
================

A variable that has been declared 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 global declaration statement.  The following statements are all global declarations.

     global a
     global b = 2
     global c = 3, d, e = 5

It is necessary declare a variable as global within a function body in order to access it.  For example,

     global x
     function f ()
       x = 1;
     endfunction
     f ()

does not set the value of the global variable x to 1.  In order to change the value of the global variable x, you must also declare it to be global within the function body, like this

     function f ()
       global x;
       x = 1;
     endfunction

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

     function f (x)
       x = 0
     endfunction

and the definition of x as a global variable at the top level,

     global x = 13

the expression

     f (x)

will display the value of x from inside the function as 0, but the value of x at the top level remains unchanged, because the function works with a copy of its argument.

 -- Built-in Variable: warn_comma_in_global_decl
     If the value of warn_comma_in_global_decl is nonzero, a warning is issued for statements like

          global a = 1, b

     which makes the variables a and b global and assigns the value 1 to the variable a, because in this context, the comma is not interpreted as a statement separator.

     The default value of warn_comma_in_global_decl is nonzero.

 -- initialize_global_variables:
     if the value of initialize_global_variables is nonzero, global variables are initialized to the value of the built-in variable default_global_variable_value.

     the default value of initialize_global_variables is zero.

 -- default_global_variable_value:
     if initialize_global_variables is nonzero, the value of default_glbaol_variable_value is used as the initial value of global variables that are not explicitly initialized.  for example,

          initialize_global_variables = 1;
          default_global_variable_value = 13;
          global foo;
          foo
               => 13

     the variable default_global_variable_value is initially undefined.

 -- Built-in Function: is_global (NAME)
     Return 1 if NAME is globally visible.  Otherwise, return 0.  For example,

          global x
          is_global ("x")
               => 1

Status of Variables
===================

 -- Command: clear options pattern ...
     Delete the names matching the given patterns from the symbol table.  The pattern may contain the following special characters:

     ?
          Match any single character.

     *
          Match zero or more characters.

     [ LIST ]
          Match the list of characters specified by LIST.  If the first character is ! or ^, match all characters except those specified by LIST.  For example, the pattern [a-zA-Z] will match all lower and upper case alphabetic characters.

     For example, the command

          clear foo b*r

     clears the name foo and all names that begin with the letter b and end with the letter r.

     If clear is called without any arguments, all user-defined variables (local and global) are cleared from the symbol table.  If 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 foo, and then hidden it by performing the assignment foo = 2.  Executing the command clear foo once will clear the variable definition and restore the definition of foo as a function.  Executing clear foo a second time will clear the function definition.

     This command may not be used within a function body.

 -- Command: who options pattern ...
 -- Command: whos options pattern ...
     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.

     -all
          List all currently defined symbols.

     -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 LOADPATH.

     -functions
          List user-defined functions.

     -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.

     -variables
          List user-defined variables.

     Valid patterns are the same as described for the 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 whos is equivalent to who -long.

 -- Built-in Function: exist (NAME)
     Return 1 if the name exists as a variable, 2 if the name (after appending .m) is a function file in the path, 3 if the name is a .oct file in the path, or 5 if the name is a built-in function. Otherwise, return 0.

 -- Built-in Function: document (SYMBOL, TEXT)
     Set the documentation string for SYMBOL to TEXT.

 -- Command: type options name ...
     Display the definition of each NAME that refers to a function.

     Normally also displays if each NAME is user-defined or builtin; the -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.

 -- Command: which name ...
     Display the type of each NAME.  If NAME is defined from a function file, the full name of the file is also displayed.

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 OCTAVE-HOME stands for the root directory where all of Octave is installed (the default is OCTAVEHOME, VERSION stands for the Octave version number (for example, VERSION) and ARCH stands for the type of system for which Octave was compiled (for example, TARGETHOSTTYPE).

EDITOR
     See Commands For History.

     Default value: "emacs".

EXEC_PATH
     See Controlling Subprocesses.

     Default value: ":$PATH".

INFO_FILE
     See Getting Help.

     Default value: "OCTAVE-HOME/info/octave.info".

INFO_PROGRAM
     See Getting Help.

     Default value: "OCTAVE-HOME/libexec/octave/VERSION/exec/ARCH/info".

LOADPATH
     See Function Files.

     Default value: ".:OCTAVE-HOME/lib/VERSION".

OCTAVE_HOME

     Default value: "OCTAVEHOME".

PAGER
     See Input and Output.

     Default value: "less", or "more".

PS1
     See Customizing the Prompt.

     Default value: "\s:\#> ".

PS2
     See Customizing the Prompt.

     Default value: "> ".

PS4
     See Customizing the Prompt.

     Default value: "+ ".

auto_unload_dot_oct_files
     See Dynamically Linked Functions.

     Default value: 0.

automatic_replot
     See Two-Dimensional Plotting.

     Default value: 0.

beep_on_error
     See Error Handling.

     Default value: 0.

completion_append_char
     See Commands For Completion.

     Default value: " ".

default_eval_print_flag
     See Evaluation.

     Default value: 1.

default_return_value
     See Multiple Return Values.

     Default value: [].

default_save_format
     See Simple File I/O.

     Default value: "ascii".

do_fortran_indexing
     See Index Expressions.

     Default value: 0.

define_all_return_values
     See Multiple Return Values.

     Default value: 0.

empty_list_elements_ok
     See Empty Matrices.

     Default value: "warn".

fixed_point_format
     See Matrices

     Default value: 0.

gnuplot_binary
     See Three-Dimensional Plotting.

     Default value: "gnuplot".

history_file
     See Commands For History.

     Default value: "~/.octave_hist".

history_size
     See Commands For History.

     Default value: 1024.

ignore_function_time_stamp
     See Function Files.

     Default value: "system".

implicit_num_to_str_ok
     See String Conversions.

     Default value: 0.

implicit_str_to_num_ok
     See String Conversions.

     Default value: 0.

max_recursion_depth
     See Recursion.

     Default value: 256.

ok_to_lose_imaginary_part
     See Special Utility Matrices.

     Default value: "warn".

output_max_field_width
     See Matrices.

     Default value: 10.

output_precision
     See Matrices.

     Default value: 5.

page_screen_output
     See Input and Output.

     Default value: 1.

prefer_column_vectors
     See Index Expressions.

     Default value: 1.

print_answer_id_name
     See Terminal Output.

     Default value: 1.

print_empty_dimensions
     See Empty Matrices.

     Default value: 1.

resize_on_range_error
     See Index Expressions.

     Default value: 1.

return_last_computed_value
     See Returning From a Function.

     Default value: 0.

save_precision
     See Simple File I/O.

     Default value: 17.

saving_history
     See Commands For History.

     Default value: 1.

silent_functions
     See Defining Functions.

     Default value: 0.

split_long_rows
     See Matrices.

     Default value: 1.

struct_levels_to_print
     See Data Structures.

     Default value: 2.

suppress_verbose_help_message
     See Getting Help.

     Default value: 1.

treat_neg_dim_as_zero
     See Special Utility Matrices.

     Default value: 0.

warn_assign_as_truth_value
     See The if Statement.

     Default value: 1.

warn_comma_in_global_decl
     See Global Variables.

     Default value: 1.

warn_divide_by_zero
     See Arithmetic Ops.

     Default value: 1.

warn_function_name_clash
     See Function Files.

     Default value: 1.

warn_reload_forces_clear
     See Dynamically Linked Functions.

     Default value: 1.

warn_variable_switch_label
     See The switch Statement.

     Default value: 0.

whitespace_in_literal_matrix
     See Matrices.

     Default value: "".

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.  See Command Line Options.

EDITOR
     See Commands For History.

     Built-in variable: EDITOR.

OCTAVE_EXEC_PATH
     See Controlling Subprocesses.

     Built-in variable: EXEC_PATH. Command-line argument: --exec-path.

OCTAVE_PATH
     See Function Files.

     Built-in variable: LOADPATH. Command-line argument: --path.

OCTAVE_INFO_FILE
     See Getting Help.

     Built-in variable: INFO_FILE. Command-line argument: --info-file.

OCTAVE_INFO_PROGRAM
     See Getting Help.

     Built-in variable: INFO_PROGRAM. Command-line argument: --info-program.

OCTAVE_HISTSIZE
     See Commands For History.

     Built-in variable: history_size.

OCTAVE_HISTFILE
     See Commands For History.

     Built-in variable: history_file.