(octave.info)Function Files

---

Next: Script Files Prev: Default Arguments Up: Functions and Scripts

---

Enter node , (file) or (file)node

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.  Note: 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" (Note: system.).

     ‘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.

Manipulating the Load Path

Subfunctions

Private Functions

Nested Functions

Overloading and Autoloading

Function Locking

Function Precedence

   ---------- Footnotes ----------

   (1) The ‘.m’ suffix was chosen for compatibility with MATLAB.