3294
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
2 @c This is part of the Octave manual. |
|
3 @c For copying conditions, see the file gpl.texi. |
|
4 |
|
5 @node Variables, Expressions, Data Structures, Top |
|
6 @chapter Variables |
|
7 @cindex variables, user-defined |
|
8 @cindex user-defined variables |
|
9 |
|
10 Variables let you give names to values and refer to them later. You have |
|
11 already seen variables in many of the examples. The name of a variable |
|
12 must be a sequence of letters, digits and underscores, but it may not begin |
|
13 with a digit. Octave does not enforce a limit on the length of variable |
|
14 names, but it is seldom useful to have variables with names longer than |
|
15 about 30 characters. The following are all valid variable names |
|
16 |
|
17 @cindex job hunting |
|
18 @cindex getting a good job |
|
19 @cindex flying high and fast |
|
20 @example |
|
21 @group |
|
22 x |
|
23 x15 |
|
24 __foo_bar_baz__ |
|
25 fucnrdthsucngtagdjb |
|
26 @end group |
|
27 @end example |
|
28 |
|
29 @noindent |
|
30 However, names like @code{__foo_bar_baz__} that begin and end with two |
|
31 underscores are understood to be reserved for internal use by Octave. |
|
32 You should not use them in code you write, except to access Octave's |
|
33 documented internal variables and built-in symbolic constants. |
|
34 |
|
35 Case is significant in variable names. The symbols @code{a} and |
|
36 @code{A} are distinct variables. |
|
37 |
|
38 A variable name is a valid expression by itself. It represents the |
|
39 variable's current value. Variables are given new values with |
|
40 @dfn{assignment operators} and @dfn{increment operators}. |
|
41 @xref{Assignment Ops, ,Assignment Expressions}. |
|
42 |
|
43 A number of variables have special built-in meanings. For example, |
|
44 @code{ans} holds the current working directory, and @code{pi} names the |
|
45 ratio of the circumference of a circle to its diameter. @xref{Summary of |
|
46 Built-in Variables}, for a list of all the predefined variables. Some |
|
47 of these built-in symbols are constants and may not be changed. Others |
|
48 can be used and assigned just like all other variables, but their values |
|
49 are also used or changed automatically by Octave. |
|
50 |
|
51 Variables in Octave do not have fixed types, so it is possible to first |
|
52 store a numeric value in a variable and then to later use the same name |
|
53 to hold a string value in the same program. Variables may not be used |
|
54 before they have been given a value. Doing so results in an error. |
|
55 |
|
56 @menu |
|
57 * Global Variables:: |
|
58 * Status of Variables:: |
|
59 * Summary of Built-in Variables:: |
|
60 * Defaults from the Environment:: |
|
61 @end menu |
|
62 |
|
63 @node Global Variables, Status of Variables, Variables, Variables |
|
64 @section Global Variables |
|
65 @cindex global variables |
|
66 @cindex @code{global} statement |
|
67 @cindex variables, global |
|
68 |
|
69 A variable that has been declared @dfn{global} may be accessed from |
|
70 within a function body without having to pass it as a formal parameter. |
|
71 |
|
72 A variable may be declared global using a @code{global} declaration |
|
73 statement. The following statements are all global declarations. |
|
74 |
|
75 @example |
|
76 @group |
|
77 global a |
|
78 global b = 2 |
|
79 global c = 3, d, e = 5 |
|
80 @end group |
|
81 @end example |
|
82 |
|
83 It is necessary declare a variable as global within a function body in |
|
84 order to access it. For example, |
|
85 |
|
86 @example |
|
87 @group |
|
88 global x |
|
89 function f () |
|
90 x = 1; |
|
91 endfunction |
|
92 f () |
|
93 @end group |
|
94 @end example |
|
95 |
|
96 @noindent |
|
97 does @emph{not} set the value of the global variable @code{x} to 1. In |
|
98 order to change the value of the global variable @code{x}, you must also |
|
99 declare it to be global within the function body, like this |
|
100 |
|
101 @example |
|
102 @group |
|
103 function f () |
|
104 global x; |
|
105 x = 1; |
|
106 endfunction |
|
107 @end group |
|
108 @end example |
|
109 |
|
110 Passing a global variable in a function parameter list will |
|
111 make a local copy and not modify the global value. For example, given |
|
112 the function |
|
113 |
|
114 @example |
|
115 @group |
|
116 function f (x) |
|
117 x = 0 |
|
118 endfunction |
|
119 @end group |
|
120 @end example |
|
121 |
|
122 @noindent |
|
123 and the definition of @code{x} as a global variable at the top level, |
|
124 |
|
125 @example |
|
126 global x = 13 |
|
127 @end example |
|
128 |
|
129 @noindent |
|
130 the expression |
|
131 |
|
132 @example |
|
133 f (x) |
|
134 @end example |
|
135 |
|
136 @noindent |
|
137 will display the value of @code{x} from inside the function as 0, |
|
138 but the value of @code{x} at the top level remains unchanged, because |
|
139 the function works with a @emph{copy} of its argument. |
|
140 |
|
141 @defvr {Built-in Variable} warn_comma_in_global_decl |
|
142 If the value of @code{warn_comma_in_global_decl} is nonzero, a |
|
143 warning is issued for statements like |
|
144 |
|
145 @example |
|
146 global a = 1, b |
|
147 @end example |
|
148 |
|
149 @noindent |
|
150 which makes the variables @code{a} and @code{b} global and assigns the |
|
151 value 1 to the variable @code{a}, because in this context, the comma is |
|
152 not interpreted as a statement separator. |
|
153 |
|
154 The default value of @code{warn_comma_in_global_decl} is nonzero. |
|
155 @end defvr |
|
156 |
|
157 @defvr default_global_variable_value |
|
158 if @code{initialize_global_variables} is nonzero, the value of |
|
159 @code{default_glbaol_variable_value} is used as the initial value of |
|
160 global variables that are not explicitly initialized. for example, |
|
161 |
|
162 @example |
|
163 @group |
|
164 initialize_global_variables = 1; |
|
165 default_global_variable_value = 13; |
|
166 global foo; |
|
167 foo |
|
168 @result{} 13 |
|
169 @end group |
|
170 @end example |
|
171 |
|
172 the variable @code{default_global_variable_value} is initially undefined. |
|
173 @end defvr |
|
174 |
|
175 @deftypefn {Built-in Function} {} is_global (@var{name}) |
|
176 Return 1 if @var{name} is globally visible. Otherwise, return 0. For |
|
177 example, |
|
178 |
|
179 @example |
|
180 @group |
|
181 global x |
|
182 is_global ("x") |
|
183 @result{} 1 |
|
184 @end group |
|
185 @end example |
|
186 @end deftypefn |
|
187 |
|
188 @node Status of Variables, Summary of Built-in Variables, Global Variables, Variables |
|
189 @section Status of Variables |
|
190 |
|
191 @deffn {Command} clear options pattern @dots{} |
|
192 Delete the names matching the given patterns from the symbol table. The |
|
193 pattern may contain the following special characters: |
|
194 @table @code |
|
195 @item ? |
|
196 Match any single character. |
|
197 |
|
198 @item * |
|
199 Match zero or more characters. |
|
200 |
|
201 @item [ @var{list} ] |
|
202 Match the list of characters specified by @var{list}. If the first |
|
203 character is @code{!} or @code{^}, match all characters except those |
|
204 specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will |
|
205 match all lower and upper case alphabetic characters. |
|
206 @end table |
|
207 |
|
208 For example, the command |
|
209 |
|
210 @example |
|
211 clear foo b*r |
|
212 @end example |
|
213 |
|
214 @noindent |
|
215 clears the name @code{foo} and all names that begin with the letter |
|
216 @code{b} and end with the letter @code{r}. |
|
217 |
|
218 If @code{clear} is called without any arguments, all user-defined |
|
219 variables (local and global) are cleared from the symbol table. If |
|
220 @code{clear} is called with at least one argument, only the visible |
|
221 names matching the arguments are cleared. For example, suppose you have |
|
222 defined a function @code{foo}, and then hidden it by performing the |
|
223 assignment @code{foo = 2}. Executing the command @kbd{clear foo} once |
|
224 will clear the variable definition and restore the definition of |
|
225 @code{foo} as a function. Executing @kbd{clear foo} a second time will |
|
226 clear the function definition. |
|
227 |
|
228 This command may not be used within a function body. |
|
229 @end deffn |
|
230 |
|
231 @deffn {Command} who options pattern @dots{} |
|
232 @deffnx {Command} whos options pattern @dots{} |
|
233 List currently defined symbols matching the given patterns. The |
|
234 following are valid options. They may be shortened to one character but |
|
235 may not be combined. |
|
236 |
|
237 @table @code |
|
238 @item -all |
|
239 List all currently defined symbols. |
|
240 |
|
241 @item -builtins |
|
242 List built-in variables and functions. This includes all currently |
|
243 compiled function files, but does not include all function files that |
|
244 are in the @code{LOADPATH}. |
|
245 |
|
246 @item -functions |
|
247 List user-defined functions. |
|
248 |
|
249 @item -long |
|
250 Print a long listing including the type and dimensions of any symbols. |
|
251 The symbols in the first column of output indicate whether it is |
|
252 possible to redefine the symbol, and whether it is possible for it to be |
|
253 cleared. |
|
254 |
|
255 @item -variables |
|
256 List user-defined variables. |
|
257 @end table |
|
258 |
|
259 Valid patterns are the same as described for the @code{clear} command |
|
260 above. If no patterns are supplied, all symbols from the given category |
|
261 are listed. By default, only user defined functions and variables |
|
262 visible in the local scope are displayed. |
|
263 |
|
264 The command @kbd{whos} is equivalent to @kbd{who -long}. |
|
265 @end deffn |
|
266 |
|
267 @deftypefn {Built-in Function} {} exist (@var{name}) |
|
268 Return 1 if the name exists as a variable, 2 if the name (after |
|
269 appending @samp{.m}) is a function file in the path, 3 if the name is a |
|
270 @samp{.oct} file in the path, or 5 if the name is a built-in function. |
|
271 Otherwise, return 0. |
|
272 @end deftypefn |
|
273 |
|
274 @deftypefn {Built-in Function} {} document (@var{symbol}, @var{text}) |
|
275 Set the documentation string for @var{symbol} to @var{text}. |
|
276 @end deftypefn |
|
277 |
|
278 @deffn {Command} type options name @dots{} |
|
279 Display the definition of each @var{name} that refers to a function. |
|
280 |
|
281 Normally also displays if each @var{name} is user-defined or builtin; |
|
282 the @code{-q} option suppresses this behaviour. |
|
283 |
|
284 Currently, Octave can only display functions that can be compiled |
|
285 cleanly, because it uses its internal representation of the function to |
|
286 recreate the program text. |
|
287 |
|
288 Comments are not displayed because Octave's parser currently discards |
|
289 them as it converts the text of a function file to its internal |
|
290 representation. This problem may be fixed in a future release. |
|
291 @end deffn |
|
292 |
|
293 @deffn {Command} which name @dots{} |
|
294 Display the type of each @var{name}. If @var{name} is defined from a |
|
295 function file, the full name of the file is also displayed. |
|
296 @end deffn |
|
297 |
|
298 @node Summary of Built-in Variables, Defaults from the Environment, Status of Variables, Variables |
|
299 @section Summary of Built-in Variables |
|
300 |
|
301 Here is a summary of all of Octave's built-in variables along with |
|
302 cross references to additional information and their default values. In |
|
303 the following table @var{octave-home} stands for the root directory |
|
304 where all of Octave is installed (the default is @file{@value{OCTAVEHOME}}, |
|
305 @var{version} stands for the Octave version number (for example, |
|
306 @value{VERSION}) and @var{arch} stands for the type of system for which |
|
307 Octave was compiled (for example, @code{@value{TARGETHOSTTYPE}}). |
|
308 |
|
309 @vtable @code |
|
310 @item DEFAULT_LOADPATH |
|
311 @xref{Function Files}. |
|
312 |
|
313 Default value: @code{".:@var{octave-home}/lib/@var{version}"}. |
|
314 |
|
315 @item EDITOR |
|
316 @xref{Commands For History}. |
|
317 |
|
318 Default value: @code{"emacs"}. |
|
319 |
|
320 @item EXEC_PATH |
|
321 @xref{Controlling Subprocesses}. |
|
322 |
|
323 Default value: @code{":$PATH"}. |
|
324 |
|
325 @item INFO_FILE |
|
326 @xref{Getting Help}. |
|
327 |
|
328 Default value: @code{"@var{octave-home}/info/octave.info"}. |
|
329 |
|
330 @item INFO_PROGRAM |
|
331 @xref{Getting Help}. |
|
332 |
|
333 Default value: @code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"}. |
|
334 |
|
335 @item LOADPATH |
|
336 @xref{Function Files}. |
|
337 |
|
338 Default value: @code{":"}, which tells Octave to use the directories |
|
339 specified by the built-in variable @code{DEFAULT_LOADPATH}. |
|
340 |
|
341 @item OCTAVE_HOME |
|
342 |
|
343 Default value: @code{"@value{OCTAVEHOME}"}. |
|
344 |
|
345 @item PAGER |
|
346 @xref{Input and Output}. |
|
347 |
|
348 Default value: @code{"less", or "more"}. |
|
349 |
|
350 @item PS1 |
|
351 @xref{Customizing the Prompt}. |
|
352 |
|
353 Default value: @code{"\s:\#> "}. |
|
354 |
|
355 @item PS2 |
|
356 @xref{Customizing the Prompt}. |
|
357 |
|
358 Default value: @code{"> "}. |
|
359 |
|
360 @item PS4 |
|
361 @xref{Customizing the Prompt}. |
|
362 |
|
363 Default value: @code{"+ "}. |
|
364 |
|
365 @item auto_unload_dot_oct_files |
|
366 @xref{Dynamically Linked Functions}. |
|
367 |
|
368 Default value: 0. |
|
369 |
|
370 @item automatic_replot |
|
371 @xref{Two-Dimensional Plotting}. |
|
372 |
|
373 Default value: 0. |
|
374 |
|
375 @item beep_on_error |
|
376 @xref{Error Handling}. |
|
377 |
|
378 Default value: 0. |
|
379 |
|
380 @item completion_append_char |
|
381 @xref{Commands For Completion}. |
|
382 |
|
383 Default value: @code{" "}. |
|
384 |
|
385 @item default_eval_print_flag |
|
386 @xref{Evaluation}. |
|
387 |
|
388 Default value: 1. |
|
389 |
|
390 @item default_return_value |
|
391 @xref{Multiple Return Values}. |
|
392 |
|
393 Default value: @code{[]}. |
|
394 |
|
395 @item default_save_format |
|
396 @xref{Simple File I/O}. |
|
397 |
|
398 Default value: @code{"ascii"}. |
|
399 |
|
400 @item do_fortran_indexing |
|
401 @xref{Index Expressions}. |
|
402 |
|
403 Default value: 0. |
|
404 |
|
405 @item crash_dumps_octave_core |
|
406 @xref{Simple File I/O}. |
|
407 |
|
408 Default value: 1. |
|
409 |
|
410 @item define_all_return_values |
|
411 @xref{Multiple Return Values}. |
|
412 |
|
413 Default value: 0. |
|
414 |
|
415 @item empty_list_elements_ok |
|
416 @xref{Empty Matrices}. |
|
417 |
|
418 Default value: @code{"warn"}. |
|
419 |
|
420 @item fixed_point_format |
|
421 @xref{Matrices}. |
|
422 |
|
423 Default value: 0. |
|
424 |
|
425 @item gnuplot_binary |
|
426 @xref{Three-Dimensional Plotting}. |
|
427 |
|
428 Default value: @code{"gnuplot"}. |
|
429 |
|
430 @item history_file |
|
431 @xref{Commands For History}. |
|
432 |
|
433 Default value: @code{"~/.octave_hist"}. |
|
434 |
|
435 @item history_size |
|
436 @xref{Commands For History}. |
|
437 |
|
438 Default value: 1024. |
|
439 |
|
440 @item ignore_function_time_stamp |
|
441 @xref{Function Files}. |
|
442 |
|
443 Default value: @code{"system"}. |
|
444 |
|
445 @item implicit_num_to_str_ok |
|
446 @xref{String Conversions}. |
|
447 |
|
448 Default value: 0. |
|
449 |
|
450 @item implicit_str_to_num_ok |
|
451 @xref{String Conversions}. |
|
452 |
|
453 Default value: 0. |
|
454 |
|
455 @item max_recursion_depth |
|
456 @xref{Recursion}. |
|
457 |
|
458 Default value: 256. |
|
459 |
|
460 @item ok_to_lose_imaginary_part |
|
461 @xref{Special Utility Matrices}. |
|
462 |
|
463 Default value: @code{"warn"}. |
|
464 |
|
465 @item output_max_field_width |
|
466 @xref{Matrices}. |
|
467 |
|
468 Default value: 10. |
|
469 |
|
470 @item output_precision |
|
471 @xref{Matrices}. |
|
472 |
|
473 Default value: 5. |
|
474 |
|
475 @item page_screen_output |
|
476 @xref{Input and Output}. |
|
477 |
|
478 Default value: 1. |
|
479 |
|
480 @item prefer_column_vectors |
|
481 @xref{Index Expressions}. |
|
482 |
|
483 Default value: 1. |
|
484 |
|
485 @item print_answer_id_name |
|
486 @xref{Terminal Output}. |
|
487 |
|
488 Default value: 1. |
|
489 |
|
490 @item print_empty_dimensions |
|
491 @xref{Empty Matrices}. |
|
492 |
|
493 Default value: 1. |
|
494 |
|
495 @item resize_on_range_error |
|
496 @xref{Index Expressions}. |
|
497 |
|
498 Default value: 1. |
|
499 |
|
500 @item return_last_computed_value |
|
501 @xref{Returning From a Function}. |
|
502 |
|
503 Default value: 0. |
|
504 |
|
505 @item save_precision |
|
506 @xref{Simple File I/O}. |
|
507 |
|
508 Default value: 17. |
|
509 |
|
510 @item saving_history |
|
511 @xref{Commands For History}. |
|
512 |
|
513 Default value: 1. |
|
514 |
|
515 @item silent_functions |
|
516 @xref{Defining Functions}. |
|
517 |
|
518 Default value: 0. |
|
519 |
|
520 @item split_long_rows |
|
521 @xref{Matrices}. |
|
522 |
|
523 Default value: 1. |
|
524 |
|
525 @item struct_levels_to_print |
|
526 @xref{Data Structures}. |
|
527 |
|
528 Default value: 2. |
|
529 |
|
530 @item suppress_verbose_help_message |
|
531 @xref{Getting Help}. |
|
532 |
|
533 Default value: 1. |
|
534 |
|
535 @item treat_neg_dim_as_zero |
|
536 @xref{Special Utility Matrices}. |
|
537 |
|
538 Default value: 0. |
|
539 |
|
540 @item warn_assign_as_truth_value |
|
541 @xref{The if Statement}. |
|
542 |
|
543 Default value: 1. |
|
544 |
|
545 @item warn_comma_in_global_decl |
|
546 @xref{Global Variables}. |
|
547 |
|
548 Default value: 1. |
|
549 |
|
550 @item warn_divide_by_zero |
|
551 @xref{Arithmetic Ops}. |
|
552 |
|
553 Default value: 1. |
|
554 |
|
555 @item warn_function_name_clash |
|
556 @xref{Function Files}. |
|
557 |
|
558 Default value: 1. |
|
559 |
|
560 @item warn_reload_forces_clear |
|
561 @xref{Dynamically Linked Functions}. |
|
562 |
|
563 Default value: 1. |
|
564 |
|
565 @item warn_variable_switch_label |
|
566 @xref{The switch Statement}. |
|
567 |
|
568 Default value: 0. |
|
569 |
|
570 @item whitespace_in_literal_matrix |
|
571 @xref{Matrices}. |
|
572 |
|
573 Default value: @code{""}. |
|
574 @end vtable |
|
575 |
|
576 |
|
577 @node Defaults from the Environment, , Summary of Built-in Variables, Variables |
|
578 @section Defaults from the Environment |
|
579 |
|
580 Octave uses the values of the following environment variables to set the |
|
581 default values for the corresponding built-in variables. In addition, |
|
582 the values from the environment may be overridden by command-line |
|
583 arguments. @xref{Command Line Options}. |
|
584 |
|
585 @vtable @code |
|
586 @item EDITOR |
|
587 @xref{Commands For History}. |
|
588 |
|
589 Built-in variable: @code{EDITOR}. |
|
590 |
|
591 @item OCTAVE_EXEC_PATH |
|
592 @xref{Controlling Subprocesses}. |
|
593 |
|
594 Built-in variable: @code{EXEC_PATH}. |
|
595 Command-line argument: @code{--exec-path}. |
|
596 |
|
597 @item OCTAVE_PATH |
|
598 @xref{Function Files}. |
|
599 |
|
600 Built-in variable: @code{LOADPATH}. |
|
601 Command-line argument: @code{--path}. |
|
602 |
|
603 @item OCTAVE_INFO_FILE |
|
604 @xref{Getting Help}. |
|
605 |
|
606 Built-in variable: @code{INFO_FILE}. |
|
607 Command-line argument: @code{--info-file}. |
|
608 |
|
609 @item OCTAVE_INFO_PROGRAM |
|
610 @xref{Getting Help}. |
|
611 |
|
612 Built-in variable: @code{INFO_PROGRAM}. |
|
613 Command-line argument: @code{--info-program}. |
|
614 |
|
615 @item OCTAVE_HISTSIZE |
|
616 @xref{Commands For History}. |
|
617 |
|
618 Built-in variable: @code{history_size}. |
|
619 |
|
620 @item OCTAVE_HISTFILE |
|
621 @xref{Commands For History}. |
|
622 |
|
623 Built-in variable: @code{history_file}. |
|
624 @end vtable |