11.13 Command Syntax and Function Syntax

In addition to the function syntax described above (i.e., calling a function like fun (arg1, arg2, …)), a function can be called using command syntax (for example, calling a function like fun arg1 arg2 …). In that case, all arguments are passed to the function as strings. For example,

my_command hello world

is equivalent to

my_command ("hello", "world")

The general form of a command call is

cmdname arg1 arg2 …

which translates directly to

cmdname ("arg1", "arg2", …)

If an argument including spaces should be passed to a function in command syntax, (double-)quotes can be used. For example,

my_command "first argument" "second argument"

is equivalent to

my_command ("first argument", "second argument")

Any function can be used as a command if it accepts string input arguments. For example:

toupper lower_case_arg
   ⇒ ans = LOWER_CASE_ARG

Since the arguments are passed as strings to the corresponding function, it is not possible to pass input arguments that are stored in variables. In that case, a command must be called using the function syntax. For example:

strvar = "hello world";
toupper strvar
   ⇒ ans = STRVAR
toupper (strvar)
   ⇒ ans = HELLO WORLD

Additionally, the return values of functions cannot be assigned to variables using the command syntax. Only the first return argument is assigned to the built-in variable ans. If the output argument of a command should be 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 apparent ambiguities with mathematical and logical expressions that use function syntax. For example, all three of the statements

arg1 - arg2
arg1 -arg2
arg1-arg2

could be intended by a user to be subtraction operations between arg1 and arg2. The first two, however, could also have been meant as a command syntax call to function arg1, in the first case with options - and arg2, and in the second case with option -arg2.

Octave uses whitespace to interpret such expressions according to the following rules:

• Statements consisting of plain symbols without any operators that are separated only by whitespace are always treated as command syntax:

  arg1 arg2 arg3 ... argn
  

• Statements without any whitespace are always treated as function syntax:

  arg1+arg2
  arg1&&arg2||arg3
  arg1+=arg2*arg3
  

• 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:

  7 -arg2
  pi+ arg2
  j * arg2 -arg3
  

• 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:

  arg1 -arg2
  arg1 &&arg2 ||arg3
  arg1 +=arg2*arg3
  

• Any other whitespace combination will result in the statement being treated as function syntax.

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 arg1 in a command being processed as command syntax will result in an error.