# HG changeset patch # User Rik # Date 1593205024 25200 # Node ID d747d57989e2186b8c0ddb670c2f5e350bb8696c # Parent 2de2b2ddd03253daf664c8714ccd50daa24458a4 doc: Better document how global variables and clear() interact (bug #57604). * var.txi: Rewrite section on global variables. * variables.cc (Fclear): Add a Programming Note about how clear removes only the local copy of a global variable. diff -r 2de2b2ddd032 -r d747d57989e2 doc/interpreter/var.txi --- a/doc/interpreter/var.txi Mon Jun 22 21:38:39 2020 +0200 +++ b/doc/interpreter/var.txi Fri Jun 26 13:57:04 2020 -0700 @@ -85,11 +85,14 @@ @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 @dfn{global} variable is one that may be accessed anywhere within Octave. +This is in contrast to a local variable which can only be accessed outside +of its current context if it is passed explicitly, such as by including it as a +parameter when calling a function +(@code{fcn (@var{local_var1}, @var{local_var2})}). -A variable may be declared global using a @code{global} declaration -statement. The following statements are all global declarations. +A variable is declared global by using a @code{global} declaration statement. +The following statements are all global declarations. @example @group @@ -100,8 +103,17 @@ @end group @end example -A global variable may only be initialized once in a @code{global} -statement. For example, after executing the following code +Note that the @code{global} qualifier extends only to the next end-of-statement +indicator which could be a comma (@samp{,}), semicolon (@samp{;}), or newline +(@samp{'\n'}). For example, the following code declares one global variable, +@var{a}, and one local variable @var{b} to which the value 1 is assigned. + +@example +global a, b = 1 +@end example + +A global variable may only be initialized once in a @code{global} statement. +For example, after executing the following code @example @group @@ -115,8 +127,8 @@ @samp{clear gvar} command does not change the above behavior, but @samp{clear all} does. -It is necessary declare a variable as global within a function body in -order to access it. For example, +It is necessary declare a variable as global within a function body in order to +access the one universal variable. For example, @example @group @@ -129,8 +141,9 @@ @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 +does @emph{not} set the value of the global variable @code{x} to 1. Instead, +a local variable, with name @code{x}, is created and assigned the value of 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 @@ -142,9 +155,8 @@ @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 +Passing a global variable in a function parameter list will make a local copy +and @emph{not} modify the global value. For example, given the function @example @group @@ -169,9 +181,16 @@ @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. +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. + +Programming Note: While global variables occasionally are the right solution to +a coding problem, modern best practice discourages their use. Code which +relies on global variables may behave unpredictably between different users +and can be difficult to debug. This is because global variables can introduce +systemic changes so that localizing a bug to a particular function, or to a +particular loop within a function, becomes difficult. @DOCSTRING(isglobal) diff -r 2de2b2ddd032 -r d747d57989e2 libinterp/corefcn/variables.cc --- a/libinterp/corefcn/variables.cc Mon Jun 22 21:38:39 2020 +0200 +++ b/libinterp/corefcn/variables.cc Fri Jun 26 13:57:04 2020 -0700 @@ -1124,7 +1124,7 @@ @deftypefn {} {} clear @deftypefnx {} {} clear @var{pattern} @dots{} @deftypefnx {} {} clear @var{options} @var{pattern} @dots{} -Delete the names matching the given @var{pattern}s from the symbol table. +Delete the names matching the given @var{pattern}s thereby freeing memory. The @var{pattern} may contain the following special characters: @@ -1192,7 +1192,7 @@ @option{-exclusive}, only one other option may appear. All options must appear before any patterns. -Programming Note: The command @code{clear @var{name}} only clears the variable +Programming Notes: The command @code{clear @var{name}} only clears the variable @var{name} when both a variable and a (shadowed) function named @var{name} are currently defined. For example, suppose you have defined a function @code{foo}, and then hidden it by performing the assignment @code{foo = 2}. @@ -1200,7 +1200,13 @@ definition and restore the definition of @code{foo} as a function. Executing @code{clear foo} a second time will clear the function definition. -@seealso{who, whos, exist, mlock} +When a local variable name, which is linked to a global variable, is cleared +only the local copy of the variable is removed. The global copy is untouched +and can be restored with @code{global @var{global_varname}}. Conversely, +@code{clear -g @var{global_varname}} will remove both the local and global +variables. + +@seealso{clearvars, who, whos, exist, mlock} @end deftypefn */) { int argc = args.length () + 1;