Mercurial > octave
changeset 31670:4058dd350ea1 stable
doc: Clarify command and function syntax binary operator handling (bug #62552)
* doc/interpreter/func.txi: Append explanation to "Command Syntax and Function
Syntax" section describing handling of ambiguous statements with binary
operators.
* doc/interpreter/expr.txi: Append note to "Arithmetic Operators" section
indicating potential ambiguity and linking to "Command Syntax and Function
Syntax" section.
author | Nicholas R. Jankowski <jankowski.nicholas@gmail.com> |
---|---|
date | Fri, 16 Dec 2022 15:56:15 -0500 |
parents | 7d36562e5571 |
children | 67770ec6f0b5 c9430c9cda2e |
files | doc/interpreter/expr.txi doc/interpreter/func.txi |
diffstat | 2 files changed, 76 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/expr.txi Fri Dec 16 15:27:45 2022 -0500 +++ b/doc/interpreter/expr.txi Fri Dec 16 15:56:15 2022 -0500 @@ -814,6 +814,11 @@ preferring the longest possible match at any given point, it is more useful in this case. +Note also that some combinations of binary operators and whitespace can +create ambiguities with Octave's Command Syntax form of calling functions. +See @ref{Command Syntax and Function Syntax} for more detail on avoiding +such issues. + @opindex @code{'} @DOCSTRING(ctranspose)
--- a/doc/interpreter/func.txi Fri Dec 16 15:27:45 2022 -0500 +++ b/doc/interpreter/func.txi Fri Dec 16 15:56:15 2022 -0500 @@ -1906,7 +1906,7 @@ @section Command Syntax and Function Syntax @cindex commands functions -Additionally to the function syntax described above (i.e., calling a function +In addition to the function syntax described above (i.e., calling a function like @code{fun (arg1, arg2, @dots{})}), a function can be called using command syntax (for example, calling a function like @code{fun arg1 arg2 @dots{}}). In that case, all arguments are passed to the function as strings. For example, @@ -1980,6 +1980,76 @@ assigned to a variable, or multiple output arguments of a function should be returned, the function syntax must be used. +It should be noted that mixing command syntax and binary operators can +create ambiguities with mathematical and logical expressions that would use +function syntax. For example, all three of the statements + +@example +arg1 - arg2 +arg1 -arg2 +arg1-arg2 +@end example + +@noindent +could be interpreted as a subtraction operation between +@code{arg1} and @code{arg2}. The first two, however, could also be taken +as a command syntax call to function @code{arg1}, in the first case with +options @code{-} and @code{arg2}, and in the second case with option +@code{-arg2}. + +Octave uses whitespace to interpret such expressions according to the +following rules: + +@itemize @bullet +@item +Statements consisting of plain symbols without any operators that are +separated only by whitespace are always treated as command syntax: + +@example +arg1 arg2 arg3 ... argn +@end example + +@item +Statements without any whitespace are always treated as function syntax: +@example +arg1+arg2 +arg1&&arg2||arg3 +arg1+=arg2*arg3 +@end example + +@item +If the first symbol is a constant (or special-valued named constant pi, i, +I, j, J, e, NaN, or Inf) followed by a binary operator, the statement is +treated as function syntax regardless of any whitespace or what follows the +second symbol: +@example +7 -arg2 +pi+ arg2 +j * arg2 -arg3 +@end example + +@item +If the first symbol is a function or variable and there is no whitespace +separating the operator and the second symbol, the statement is treated +as command syntax: +@example +arg1 -arg2 +arg1 &&arg2 ||arg3 +arg1 +=arg2*arg3 +@end example + +@item +Any other whitespace combination will result in the statement being treated +as function syntax. +@end itemize + +Note 1: If a special-valued named constant has been redefined as a +variable, the interpreter will still process the statement with function +syntax. + +Note 2: Attempting to use a variable as @code{arg1} in a command being +processed as command syntax will result in an error. + @node Organization of Functions @section Organization of Functions Distributed with Octave