octave 3 vs 4 script compatibility; where's REAL documentation of Executable-Octave-Programs

Question

Part-1: In octave 3.4.3 (on centos 6.6) following script file "joe.m" (but for 3.x minus --no-gui):

#!/bin/bash
# for-bash:
#{
  exec octave -q --no-gui --no-init-file "$0" ${1+"$@"}
#}
# for-octave:
function jim ()
  printf ("program_name: '%s'\n", program_name ());
endfunction
printf ("calling jim\n")
jim

produces output:

calling jim
program_name: 'joe.m'

But in octave 4.2.1 it gives a warning, and appears to auto-call(!?) jim, and does NOT run top-level immediate code(!?), no output line "calling jim":

warning: function name 'jim' does not agree with function filename '/tmp/joe.m'
program_name: 'joe.m'

Part-2: If I rename same file to "jim.m", then in octave 3.4.4 the output is:

calling jim
program_name: 'jim.m'

in octave 4.2.1 now warning is avoided, but still missing "calling jim" line.

Part-3: With zero functions defined, the top-level code will execute in both versions.

Where are these behaviors (and this change of behavior from version 3 to 4) documented or controlled? Nothing of the sort is mentioned in:

https://octave.org/doc/v4.2.1/Command-Line-Options.html

https://octave.org/doc/v4.2.1/Executable-Octave-Programs.html

How can one write an octave file compatible with both version 3.x and 4.x, or how to invoke 4.x with an extra option to behave compatibly with 3.x? How to execute top-level code in 4.x even when functions are defined?

How can one deterministically know (without trial and error) what function will be auto-called (and with what arguments) in 4.x without documentation of same? This example not enough to nail it down, since there's one and only one function: if there are multiple functions (joe and jim), does the order matter, relative to whether either or none matches the file name?

Edit: I include the shebang (self-contained script) in attempt to not "ask the wrong question" or prematurely optimize the question towards my own "attempted solution", yet behaviors are same with or without it. I need script to: not use absolute path to octave, and accept extra separate options (I could not combine --no-gui into -qf in 4.2.1). Your simplifications are welcome.

If the shebang line is not relevant to the question, please remove it. It took me a while to parse that. Let people focus on what is important. See minimal reproducible example (especially the minimal part!). — Cris Luengo
Thanks. I made an edit to explain. Maybe I better split-out the shebang to an afterword. — bk-se

rahnema1 rahnema1 · Accepted Answer · 2018-11-19T12:43:34

There are different .m file types including (according to Octave 4.2.1):

Function files: A file that contains definition of one or more functions. The name of a function file often matches the name of the first function defined in the file.
Script files: A file that contain lines of code including definition of functions.

Unlike a function file, a script file must not begin with the keyword function . If it does, Octave will assume that it is a function file, and that it defines a single function that should be evaluated as soon as it is defined.
Class definition files.

The behavior of Octave when is executed as:

$octave File

is documented in one of source files (oct-parse.yy) of Octave:

Execute the contents of a script file. For compatibility with Matlab, also execute a function file by calling the function it defines with no arguments and nargout = 0.

Here because your file begins with the keyword function it is considered as a function file so the function jim is automatically called regardless of if you invoke jim or not. So you can remove the expression jim from the end of file and see that the function is automatically called. In version 3.4.3 I think it is assumed as a script file.

To solve the problem you need to add an expression,other than the function keyword, to the beginning of the file to convert it to a script file:

#!/bin/bash
# for-bash:
#{
  exec octave -q --no-init-file "$0" ${1+"$@"}
#}
# for-octave:
1;
function jim ()
  printf ("program_name: '%s'\n", program_name ());
endfunction
printf ("calling jim\n")
jim

octave 3 vs 4 script compatibility; where's REAL documentation of Executable-Octave-Programs

1 Answers