<html lang="en">
<head>
<title>Function Files - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Functions-and-Scripts.html#Functions-and-Scripts" title="Functions and Scripts">
<link rel="prev" href="Default-Arguments.html#Default-Arguments" title="Default Arguments">
<link rel="next" href="Script-Files.html#Script-Files" title="Script Files">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Function-Files"></a>
<p>
Next: <a rel="next" accesskey="n" href="Script-Files.html#Script-Files">Script Files</a>,
Previous: <a rel="previous" accesskey="p" href="Default-Arguments.html#Default-Arguments">Default Arguments</a>,
Up: <a rel="up" accesskey="u" href="Functions-and-Scripts.html#Functions-and-Scripts">Functions and Scripts</a>
<hr>
</div>
<h3 class="section">11.7 Function Files</h3>
<p><a name="index-function-file-612"></a>
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>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>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 <dfn>path</dfn>) for files ending in
<samp><span class="file">.m</span></samp> that have the same base name as the undefined
identifier.<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</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>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>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>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><span class="file">/share/octave/</span><var>version</var><span class="file">/m</span></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>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.
<!-- FIXME - note about time stamps on files in NFS environments? -->
<!-- ./miscellaneous/edit.m -->
<p><a name="doc_002dedit"></a>
<div class="defun">
— Command: edit <var>name</var><var><a name="index-g_t_0040var_007bname_007d-613"></a></var><br>
— Command: edit <var>field</var><var> value<a name="index-g_t_0040var_007bfield_007d-614"></a></var><br>
— Command: <var>value</var> = <b>edit</b><var> get field<a name="index-edit-615"></a></var><br>
<blockquote><p>Edit the named function, or change editor settings.
<p>If <code>edit</code> is called with the name of a file or function as
its argument it will be opened in a text editor.
<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 further down) 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.
<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>If <code>name.cc</code> is specified, then it will search for <code>name.cc</code>
in the path and try to modify it, otherwise it will create a new
<samp><span class="file">.cc</span></samp> file in <code>HOME</code>. 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>If <var>name.ext</var> is on your path then it will be edited, otherwise
the editor will be started with <samp><span class="file">HOME/name.ext</span></samp> as the
filename. If <samp><span class="file">name.ext</span></samp> is not modifiable, it will be copied to
<code>HOME</code> before editing.
<p><strong>WARNING!</strong> You may need to clear name before the new definition
is available. If you are editing a .cc file, you will need
to mkoctfile <samp><span class="file">name.cc</span></samp> before the definition will be available.
</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 <var>value</var>.
If an output argument is requested and the first 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 all</code> returns
a complete control structure.
The following control fields are used:
<dl>
<dt>‘<samp><span class="samp">editor</span></samp>’<dd>This is the editor to use to modify the functions. By default it uses
Octave's <code>EDITOR</code> built-in function, which comes from
<code>getenv("EDITOR")</code> and defaults to <code>emacs</code>. Use <code>%s</code>
In place of the function name. For example,
<dl>
<dt>‘<samp><span class="samp">[EDITOR, " %s"]</span></samp>’<dd>Use the editor which Octave uses for <code>bug_report</code>.
<br><dt>‘<samp><span class="samp">"xedit %s &"</span></samp>’<dd>pop up simple X11 editor in a separate window
<br><dt>‘<samp><span class="samp">"gnudoit -q \"(find-file \\\"%s\\\")\""</span></samp>’<dd>Send it to current Emacs; must have <code>(gnuserv-start)</code> in <samp><span class="file">.emacs</span></samp>.
</dl>
<p>See also field 'mode', which controls how the editor is run by Octave.
<p>On Cygwin, you will need to convert the Cygwin path to a Windows
path if you are using a native Windows editor. For example
<!-- Set example in small font to prevent overfull line -->
<pre class="smallexample"> '"C:/Program Files/Good Editor/Editor.exe" "$(cygpath -wa %s)"'
</pre>
<br><dt>‘<samp><span class="samp">home</span></samp>’<dd>This is the location of user local m-files. Be be sure it is in your
path. The default is <samp><span class="file">~/octave</span></samp>.
<br><dt>‘<samp><span class="samp">author</span></samp>’<dd>This is the name to put after the "## Author:" field of new functions.
By default it guesses from the <code>gecos</code> field of password database.
<br><dt>‘<samp><span class="samp">email</span></samp>’<dd>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 <code><user@host></code> as your format.
<br><dt>‘<samp><span class="samp">license</span></samp>’<dd>
<dl>
<dt>‘<samp><span class="samp">gpl</span></samp>’<dd>GNU General Public License (default).
<br><dt>‘<samp><span class="samp">bsd</span></samp>’<dd>BSD-style license without advertising clause.
<br><dt>‘<samp><span class="samp">pd</span></samp>’<dd>Public domain.
<br><dt>‘<samp><span class="samp">"text"</span></samp>’<dd>Your own default copyright and license.
</dl>
<p>Unless you specify ‘<samp><span class="samp">pd</span></samp>’, edit will prepend the copyright statement
with "Copyright (C) yyyy Function Author".
<br><dt>‘<samp><span class="samp">mode</span></samp>’<dd>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 "async" to start the editor
in async mode. The default is "sync" (see also "system").
<br><dt>‘<samp><span class="samp">editinplace</span></samp>’<dd>Determines whether files should be edited in place, without regard to
whether they are modifiable or not. The default is <code>false</code>.
</dl>
</p></blockquote></div>
<!-- parse.cc -->
<p><a name="doc_002dmfilename"></a>
<div class="defun">
— Built-in Function: <b>mfilename</b> ()<var><a name="index-mfilename-616"></a></var><br>
— Built-in Function: <b>mfilename</b> (<code>"fullpath"</code>)<var><a name="index-mfilename-617"></a></var><br>
— Built-in Function: <b>mfilename</b> (<code>"fullpathext"</code>)<var><a name="index-mfilename-618"></a></var><br>
<blockquote><p>Return the name of the currently executing file. At the top-level,
return the empty string. Given the argument <code>"fullpath"</code>,
include the directory part of the file name, but not the extension.
Given the argument <code>"fullpathext"</code>, include the directory part
of the file name and the extension.
</p></blockquote></div>
<!-- symtab.cc -->
<p><a name="doc_002dignore_005ffunction_005ftime_005fstamp"></a>
<div class="defun">
— Built-in Function: <var>val</var> = <b>ignore_function_time_stamp</b> ()<var><a name="index-ignore_005ffunction_005ftime_005fstamp-619"></a></var><br>
— Built-in Function: <var>old_val</var> = <b>ignore_function_time_stamp</b> (<var>new_val</var>)<var><a name="index-ignore_005ffunction_005ftime_005fstamp-620"></a></var><br>
<blockquote><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. 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><span class="file">/lib/</span><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. If set to <code>"all"</code>, Octave will not
recompile any function files unless their definitions are removed with
<code>clear</code>. If set to "none", Octave will always check time stamps
on files to determine whether functions defined in function files
need to recompiled.
</p></blockquote></div>
<ul class="menu">
<li><a accesskey="1" href="Manipulating-the-load-path.html#Manipulating-the-load-path">Manipulating the load path</a>
<li><a accesskey="2" href="Subfunctions.html#Subfunctions">Subfunctions</a>
<li><a accesskey="3" href="Private-Functions.html#Private-Functions">Private Functions</a>
<li><a accesskey="4" href="Overloading-and-Autoloading.html#Overloading-and-Autoloading">Overloading and Autoloading</a>
<li><a accesskey="5" href="Function-Locking.html#Function-Locking">Function Locking</a>
<li><a accesskey="6" href="Function-Precedence.html#Function-Precedence">Function Precedence</a>
</ul>
<div class="footnote">
<hr>
<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> The ‘<samp><span class="samp">.m</span></samp>’ suffix was chosen for compatibility
with <span class="sc">matlab</span>.</p>
<hr></div>
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
3e60ff9d4d6f58c8fbd17208f14089fa
>
files
>
197
