octave: Function Files
11.9 Function Files
===================
Except for simple one-shot programs, it is not practical to have to
define all the functions you need each time you need them. Instead, you
will normally want to save them in a file so that you can easily edit
them, and save them for use at a later time.
Octave does not require you to load function definitions from files
before using them. You simply need to put the function definitions in a
place where Octave can find them.
When Octave encounters an identifier that is undefined, it first
looks for variables or functions that are already compiled and currently
listed in its symbol table. If it fails to find a definition there, it
searches a list of directories (the “path”) for files ending in ‘.m’
that have the same base name as the undefined identifier.(1) Once
Octave finds a file with a name that matches, the contents of the file
are read. If it defines a _single_ function, it is compiled and
executed. 
Script Files, for more information about how you can
define more than one function in a single file.
When Octave defines a function from a function file, it saves the
full name of the file it read and the time stamp on the file. If the
time stamp on the file changes, Octave may reload the file. When Octave
is running interactively, time stamp checking normally happens at most
once each time Octave prints the prompt. Searching for new function
definitions also occurs if the current working directory changes.
Checking the time stamp allows you to edit the definition of a
function while Octave is running, and automatically use the new function
definition without having to restart your Octave session.
To avoid degrading performance unnecessarily by checking the time
stamps on functions that are not likely to change, Octave assumes that
function files in the directory tree
‘OCTAVE-HOME/share/octave/VERSION/m’ will not change, so it doesn’t have
to check their time stamps every time the functions defined in those
files are used. This is normally a very good assumption and provides a
significant improvement in performance for the function files that are
distributed with Octave.
If you know that your own function files will not change while you
are running Octave, you can improve performance by calling
‘ignore_function_time_stamp ("all")’, so that Octave will ignore the
time stamps for all function files. Passing "system" to this function
resets the default behavior.
-- : edit NAME
-- : edit FIELD VALUE
-- : VALUE = edit ("get", FIELD)
-- : VALUE = edit ("get", "all")
Edit the named function, or change editor settings.
If ‘edit’ is called with the name of a file or function as its
argument it will be opened in the text editor defined by ‘EDITOR’.
• If the function NAME is available in a file on your path and
that file is modifiable, then it will be edited in place. If
it is a system function, then it will first be copied to the
directory ‘HOME’ (see below) and then edited. If no file is
found, then the m-file variant, ending with ".m", will be
considered. If still no file is found, then variants with a
leading "@" and then with both a leading "@" and trailing ".m"
will be considered.
• If NAME is the name of a function defined in the interpreter
but not in an m-file, then an m-file will be created in ‘HOME’
to contain that function along with its current definition.
• If ‘NAME.cc’ is specified, then it will search for ‘NAME.cc’
in the path and try to modify it, otherwise it will create a
new ‘.cc’ file in the current directory. If NAME happens to
be an m-file or interpreter defined function, then the text of
that function will be inserted into the .cc file as a comment.
• If ‘NAME.ext’ is on your path then it will be edited,
otherwise the editor will be started with ‘NAME.ext’ in the
current directory as the filename. If ‘NAME.ext’ is not
modifiable, it will be copied to ‘HOME’ before editing.
*Warning:* You may need to clear NAME before the new
definition is available. If you are editing a .cc file, you
will need to execute ‘mkoctfile NAME.cc’ before the definition
will be available.
If ‘edit’ is called with FIELD and VALUE variables, the value of
the control field FIELD will be set to VALUE.
If an output argument is requested and the first input argument is
‘get’ then ‘edit’ will return the value of the control field FIELD.
If the control field does not exist, edit will return a structure
containing all fields and values. Thus, ‘edit ("get", "all")’
returns a complete control structure.
The following control fields are used:
‘home’
This is the location of user local m-files. Be sure it is in
your path. The default is ‘~/octave’.
‘author’
This is the name to put after the "## Author:" field of new
functions. By default it guesses from the ‘gecos’ field of
the password database.
‘email’
This is the e-mail address to list after the name in the
author field. By default it guesses ‘<$LOGNAME@$HOSTNAME>’,
and if ‘$HOSTNAME’ is not defined it uses ‘uname -n’. You
probably want to override this. Be sure to use the format
‘<user@host>’.
‘license’
‘gpl’
GNU General Public License (default).
‘bsd’
BSD-style license without advertising clause.
‘pd’
Public domain.
‘"text"’
Your own default copyright and license.
Unless you specify ‘pd’, edit will prepend the copyright
statement with "Copyright (C) YYYY Author".
‘mode’
This value determines whether the editor should be started in
async mode (editor is started in the background and Octave
continues) or sync mode (Octave waits until the editor exits).
Set it to "sync" to start the editor in sync mode. The
default is "async" (system XREFsystem.).
‘editinplace’
Determines whether files should be edited in place, without
regard to whether they are modifiable or not. The default is
‘false’.
-- : mfilename ()
-- : mfilename ("fullpath")
-- : mfilename ("fullpathext")
Return the name of the currently executing file.
When called from outside an m-file return the empty string.
Given the argument "fullpath", include the directory part of the
filename, but not the extension.
Given the argument "fullpathext", include the directory part of the
filename and the extension.
-- : VAL = ignore_function_time_stamp ()
-- : OLD_VAL = ignore_function_time_stamp (NEW_VAL)
Query or set the internal variable that controls whether Octave
checks the time stamp on files each time it looks up functions
defined in function files.
If the internal variable is set to "system", Octave will not
automatically recompile function files in subdirectories of
‘OCTAVE-HOME/lib/VERSION’ if they have changed since they were last
compiled, but will recompile other function files in the search
path if they change.
If set to "all", Octave will not recompile any function files
unless their definitions are removed with ‘clear’.
If set to "none", Octave will always check time stamps on files to
determine whether functions defined in function files need to
recompiled.
Menu
Info Catalog
octave: Default Arguments
octave: Functions and Scripts
octave: Script Files