@c Copyright (C) 1996 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Built-in Variables, Input and Output, Functions and Scripts, Top
@chapter Built-in Variables
@cindex variables
@cindex built-in variables
@cindex variables, built-in

Most Octave variables are available for you to use for your own
purposes; they never change except when your program assigns values to
them, and never affect anything except when your program examines them.

A number of variables have special built-in meanings.  Some of them,
like @code{pi} and @code{eps} provide useful predefined constant values.
Others, like @code{do_fortran_indexing} and @code{page_screen_output}
are examined automatically by Octave, so that you can to tell Octave how
to do certain things.  There are also two special variables, @code{ans}
and @code{PWD}, that are set automatically and carry information from
the internal workings of Octave to your program.

This chapter documents the built-in variables of Octave that don't seem
to belong anywhere else.  Many more of Octave's built-in variables are
documented in the chapters that describe functions that use them, or are
affected by their values.

@menu
* Miscellaneous Built-in Variables::  
* Summary of Preference Variables::  
@end menu

@node Miscellaneous Built-in Variables, Summary of Preference Variables, Built-in Variables, Built-in Variables
@section Miscellaneous Built-in Variables

This section describes the variables that you can use to customize
Octave's behavior.

Normally, preferences are set in the file @file{~/.octaverc}, so that
you can customize your environment in the same way each time you use
Octave without having to remember and retype all the necessary commands.
@xref{Startup Files} for more information.

@defvr {Built-in Variable} OCTAVE_VERSION
The version number of Octave, as a string.
@end defvr

@defvr {Built-in Variable} ok_to_lose_imaginary_part
If the value of @code{ok_to_lose_imaginary_part} is nonzero,
implicit conversions of complex numbers to real numbers are allowed (for
example, by fsolve).  If the value is @code{"warn"}, the conversion is allowed,
but a warning is printed.  Otherwise, an error message is printed and
control is returned to the top level.  The default value is @code{"warn"}.
@end defvr

@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.
@xref{Empty Matrices}.
@end defvr

@node Summary of Preference Variables,  , Miscellaneous Built-in Variables, Built-in Variables
@section Summary of Preference Variables

Here is a summary of all of Octave's preference variables and their
default values.  In the following table @code{OCT_HOME} stands for
the root directory where Octave is installed, @code{VERSION} stands
for the Octave version number, and @code{SYS} stands for the type of
system for which Octave was compiled (for example,
@code{alpha-dec-osf3.2}).

@table @code
@item EDITOR
Default value: @code{"vi"}.

@item EXEC_PATH
Default value: @code{":$PATH"}.

@item INFO_FILE
Default value: @code{"OCT_HOME/info/octave.info"}.

@item INFO_PROGRAM
Default value: @code{"OCT_HOME/libexec/octave/VERSION/exec/SYS/info"}.

@item LOADPATH
Default value: @code{".:OCT_HOME/lib/VERSION"}.

@item PAGER
Default value: @code{"less", or "more"}.

@item PS1
Default value: @code{"\s:\#> "}.

@item PS2
Default value: @code{"> "}.

@item PS4
Default value: @code{"+ "}.

@item automatic_replot
Default value: 0.

@item beep_on_error
Default value: 0.

@item completion_append_char
Default value: @code{" "}.

@item default_return_value
Default value: @code{[]}.

@item do_fortran_indexing
Default value: 0.

@item define_all_return_values
Default value: 0.

@item empty_list_elements_ok
Default value: @code{"warn"}.

@item gnuplot_binary
Default value: @code{"gnuplot"}.

@item history_file
Default value: @code{"~/.octave_hist"}.

@item history_size
Default value: 1024.

@item ignore_function_time_stamp
Default value: @code{"system"}.

@item implicit_str_to_num_ok
Default value: 0.

@item ok_to_lose_imaginary_part
Default value: @code{"warn"}.

@item output_max_field_width
Default value: 10.

@item output_precision
Default value: 5.

@item page_screen_output
Default value: 1.

@item prefer_column_vectors
Default value: 0.

@item prefer_zero_one_indexing
Default value: 0.

@item print_answer_id_name
Default value: 1.

@item print_empty_dimensions
Default value: 1.

@item resize_on_range_error
Default value: 1.

@item return_last_computed_value
Default value: 0.

@item save_precision
Default value: 17.

@item saving_history
Default value: 1.

@item silent_functions
Default value: 0.

@item split_long_rows
Default value: 1.

@item struct_levels_to_print
Default value: 2.

@item suppress_verbose_help_message
Default value: 1.

@item treat_neg_dim_as_zero
Default value: 0.

@item warn_assign_as_truth_value
Default value: 1.

@item warn_comma_in_global_decl
Default value: 1.

@item warn_divide_by_zero
Default value: 1.

@item warn_function_name_clash
Default value: 1.

@item whitespace_in_literal_matrix
Default value: @code{""}.
@end table

The following variables may be set from the environment or by a command
line option.

@smallexample
Variable        Environment Variable    Option 
--------        --------------------    ------
EDITOR          EDITOR
EXEC_PATH       OCTAVE_EXEC_PATH        --exec-path PATH    
LOADPATH        OCTAVE_PATH             --path PATH
INFO_FILE       OCTAVE_INFO_FILE        --info-file FILE
INFO_PROGRAM    OCTAVE_INFO_PROGRAM     --info-program PROGRAM
history_size    OCTAVE_HISTSIZE
history_file    OCTAVE_HISTFILE
@end smallexample

@c XXX FIXME XXX Might be nice to have a list of the settings required
@c to have Octave behave as much like @sc{Matlab} as is possible.