<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Function Files (GNU Octave (version 5.1.0))</title> <meta name="description" content="Function Files (GNU Octave (version 5.1.0))"> <meta name="keywords" content="Function Files (GNU Octave (version 5.1.0))"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="makeinfo"> <link href="index.html#Top" rel="start" title="Top"> <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Functions-and-Scripts.html#Functions-and-Scripts" rel="up" title="Functions and Scripts"> <link href="Manipulating-the-Load-Path.html#Manipulating-the-Load-Path" rel="next" title="Manipulating the Load Path"> <link href="Default-Arguments.html#Default-Arguments" rel="prev" title="Default Arguments"> <style type="text/css"> <!-- a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} blockquote.smallquotation {font-size: smaller} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} div.lisp {margin-left: 3.2em} div.smalldisplay {margin-left: 3.2em} div.smallexample {margin-left: 3.2em} div.smalllisp {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} pre.smalldisplay {font-family: inherit; font-size: smaller} pre.smallexample {font-size: smaller} pre.smallformat {font-family: inherit; font-size: smaller} pre.smalllisp {font-size: smaller} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} ul.no-bullet {list-style: none} --> </style> <link rel="stylesheet" type="text/css" href="octave.css"> </head> <body lang="en"> <a name="Function-Files"></a> <div class="header"> <p> Next: <a href="Script-Files.html#Script-Files" accesskey="n" rel="next">Script Files</a>, Previous: <a href="Default-Arguments.html#Default-Arguments" accesskey="p" rel="prev">Default Arguments</a>, Up: <a href="Functions-and-Scripts.html#Functions-and-Scripts" accesskey="u" rel="up">Functions and Scripts</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> </div> <hr> <a name="Function-Files-1"></a> <h3 class="section">11.9 Function Files</h3> <a name="index-function-file"></a> <p>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. </p> <p>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. </p> <p>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 <em>path</em>) for files ending in <samp>.m</samp> that have the same base name as the undefined identifier.<a name="DOCF5" href="#FOOT5"><sup>5</sup></a> Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a <em>single</em> function, it is compiled and executed. See <a href="Script-Files.html#Script-Files">Script Files</a>, for more information about how you can define more than one function in a single file. </p> <p>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. </p> <p>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. </p> <p>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 <samp><var>octave-home</var>/share/octave/<var>version</var>/m</samp> 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. </p> <p>If you know that your own function files will not change while you are running Octave, you can improve performance by calling <code>ignore_function_time_stamp ("all")</code>, so that Octave will ignore the time stamps for all function files. Passing <code>"system"</code> to this function resets the default behavior. </p> <a name="XREFedit"></a><dl> <dt><a name="index-edit"></a><em></em> <strong>edit</strong> <em><var>name</var></em></dt> <dt><a name="index-edit-1"></a><em></em> <strong>edit</strong> <em><var>field</var> <var>value</var></em></dt> <dt><a name="index-edit-2"></a><em><var>value</var> =</em> <strong>edit</strong> <em>("get", <var>field</var>)</em></dt> <dt><a name="index-edit-3"></a><em><var>value</var> =</em> <strong>edit</strong> <em>("get", "all")</em></dt> <dd><p>Edit the named function, or change editor settings. </p> <p>If <code>edit</code> is called with the name of a file or function as its argument it will be opened in the text editor defined by <code>EDITOR</code>. </p> <ul> <li> If the function <var>name</var> 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 <code>HOME</code> (see below) and then edited. If no file is found, then the m-file variant, ending with <code>".m"</code>, will be considered. If still no file is found, then variants with a leading <code>"@"</code> and then with both a leading <code>"@"</code> and trailing <code>".m"</code> will be considered. </li><li> If <var>name</var> is the name of a function defined in the interpreter but not in an m-file, then an m-file will be created in <code>HOME</code> to contain that function along with its current definition. </li><li> If <code><var>name</var>.cc</code> is specified, then it will search for <code><var>name</var>.cc</code> in the path and try to modify it, otherwise it will create a new <samp>.cc</samp> file in the current directory. If <var>name</var> 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. </li><li> If <samp><var>name</var>.ext</samp> is on your path then it will be edited, otherwise the editor will be started with <samp><var>name</var>.ext</samp> in the current directory as the filename. If <samp><var>name</var>.ext</samp> is not modifiable, it will be copied to <code>HOME</code> before editing. <p><strong>Warning:</strong> You may need to clear <var>name</var> before the new definition is available. If you are editing a .cc file, you will need to execute <code>mkoctfile <samp><var>name</var>.cc</samp></code> before the definition will be available. </p></li></ul> <p>If <code>edit</code> is called with <var>field</var> and <var>value</var> variables, the value of the control field <var>field</var> will be set to <var>value</var>. </p> <p>If an output argument is requested and the first input argument is <code>get</code> then <code>edit</code> will return the value of the control field <var>field</var>. If the control field does not exist, edit will return a structure containing all fields and values. Thus, <code>edit ("get", <code>"all"</code>)</code> returns a complete control structure. </p> <p>The following control fields are used: </p> <dl compact="compact"> <dt>‘<samp>home</samp>’</dt> <dd><p>This is the location of user local m-files. Be sure it is in your path. The default is <samp>~/octave</samp>. </p> </dd> <dt>‘<samp>author</samp>’</dt> <dd><p>This is the name to put after the "## Author:" field of new functions. By default it guesses from the <code>gecos</code> field of the password database. </p> </dd> <dt>‘<samp>email</samp>’</dt> <dd><p>This is the e-mail address to list after the name in the author field. By default it guesses <code><$LOGNAME@$HOSTNAME></code>, and if <code>$HOSTNAME</code> is not defined it uses <code>uname -n</code>. You probably want to override this. Be sure to use the format <code><a href="mailto:user@host">user@host</a></code>. </p> </dd> <dt>‘<samp>license</samp>’</dt> <dd> <dl compact="compact"> <dt>‘<samp>gpl</samp>’</dt> <dd><p>GNU General Public License (default). </p> </dd> <dt>‘<samp>bsd</samp>’</dt> <dd><p>BSD-style license without advertising clause. </p> </dd> <dt>‘<samp>pd</samp>’</dt> <dd><p>Public domain. </p> </dd> <dt>‘<samp>"text"</samp>’</dt> <dd><p>Your own default copyright and license. </p></dd> </dl> <p>Unless you specify ‘<samp>pd</samp>’, edit will prepend the copyright statement with "Copyright (C) YYYY Author". </p> </dd> <dt>‘<samp>mode</samp>’</dt> <dd><p>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 <code>"sync"</code> to start the editor in sync mode. The default is <code>"async"</code> (see <a href="Controlling-Subprocesses.html#XREFsystem">system</a>). </p> </dd> <dt>‘<samp>editinplace</samp>’</dt> <dd><p>Determines whether files should be edited in place, without regard to whether they are modifiable or not. The default is <code>false</code>. </p></dd> </dl> </dd></dl> <a name="XREFmfilename"></a><dl> <dt><a name="index-mfilename"></a><em></em> <strong>mfilename</strong> <em>()</em></dt> <dt><a name="index-mfilename-1"></a><em></em> <strong>mfilename</strong> <em>("fullpath")</em></dt> <dt><a name="index-mfilename-2"></a><em></em> <strong>mfilename</strong> <em>("fullpathext")</em></dt> <dd><p>Return the name of the currently executing file. </p> <p>The base name of the currently executing script or function is returned without any extension. If called from outside an m-file, such as the command line, return the empty string. </p> <p>Given the argument <code>"fullpath"</code>, include the directory part of the filename, but not the extension. </p> <p>Given the argument <code>"fullpathext"</code>, include the directory part of the filename and the extension. </p> <p><strong>See also:</strong> <a href="Defining-Functions.html#XREFinputname">inputname</a>, <a href="Call-Stack.html#XREFdbstack">dbstack</a>. </p></dd></dl> <a name="XREFignore_005ffunction_005ftime_005fstamp"></a><dl> <dt><a name="index-ignore_005ffunction_005ftime_005fstamp"></a><em><var>val</var> =</em> <strong>ignore_function_time_stamp</strong> <em>()</em></dt> <dt><a name="index-ignore_005ffunction_005ftime_005fstamp-1"></a><em><var>old_val</var> =</em> <strong>ignore_function_time_stamp</strong> <em>(<var>new_val</var>)</em></dt> <dd><p>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. </p> <p>If the internal variable is set to <code>"system"</code>, Octave will not automatically recompile function files in subdirectories of <samp><var>octave-home</var>/lib/<var>version</var></samp> if they have changed since they were last compiled, but will recompile other function files in the search path if they change. </p> <p>If set to <code>"all"</code>, Octave will not recompile any function files unless their definitions are removed with <code>clear</code>. </p> <p>If set to <code>"none"</code>, Octave will always check time stamps on files to determine whether functions defined in function files need to recompiled. </p></dd></dl> <table class="menu" border="0" cellspacing="0"> <tr><td align="left" valign="top">• <a href="Manipulating-the-Load-Path.html#Manipulating-the-Load-Path" accesskey="1">Manipulating the Load Path</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Subfunctions.html#Subfunctions" accesskey="2">Subfunctions</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Private-Functions.html#Private-Functions" accesskey="3">Private Functions</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Nested-Functions.html#Nested-Functions" accesskey="4">Nested Functions</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Overloading-and-Autoloading.html#Overloading-and-Autoloading" accesskey="5">Overloading and Autoloading</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Function-Locking.html#Function-Locking" accesskey="6">Function Locking</a>:</td><td> </td><td align="left" valign="top"> </td></tr> <tr><td align="left" valign="top">• <a href="Function-Precedence.html#Function-Precedence" accesskey="7">Function Precedence</a>:</td><td> </td><td align="left" valign="top"> </td></tr> </table> <div class="footnote"> <hr> <h4 class="footnotes-heading">Footnotes</h4> <h3><a name="FOOT5" href="#DOCF5">(5)</a></h3> <p>The ‘<samp>.m</samp>’ suffix was chosen for compatibility with <small>MATLAB</small>.</p> </div> <hr> <div class="header"> <p> Next: <a href="Script-Files.html#Script-Files" accesskey="n" rel="next">Script Files</a>, Previous: <a href="Default-Arguments.html#Default-Arguments" accesskey="p" rel="prev">Default Arguments</a>, Up: <a href="Functions-and-Scripts.html#Functions-and-Scripts" accesskey="u" rel="up">Functions and Scripts</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> </div> </body> </html>