1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Function Files (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Function Files (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Function Files (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Functions-and-Scripts.html" rel="up" title="Functions and Scripts">
<link href="Script-Files.html" rel="next" title="Script Files">
<link href="Validating-Arguments.html" rel="prev" title="Validating Arguments">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
ul.mark-bullet {list-style-type: disc}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section-level-extent" id="Function-Files">
<div class="nav-panel">
<p>
Next: <a href="Script-Files.html" accesskey="n" rel="next">Script Files</a>, Previous: <a href="Validating-Arguments.html" accesskey="p" rel="prev">Validating Arguments</a>, Up: <a href="Functions-and-Scripts.html" 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" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Function-Files-1"><span>11.10 Function Files<a class="copiable-link" href="#Function-Files-1"> ¶</a></span></h3>
<a class="index-entry-id" id="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 class="dfn">path</em>) for files ending in
<samp class="file">.m</samp> that have the same base name as the undefined
identifier.<a class="footnote" id="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 class="emph">single</em>
function, it is compiled and executed. See <a class="xref" href="Script-Files.html">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 class="file"><var class="var">octave-home</var>/share/octave/<var class="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 class="code">ignore_function_time_stamp ("all")</code>, so that Octave will
ignore the time stamps for all function files. Passing
<code class="code">"system"</code> to this function resets the default behavior.
</p>
<a class="anchor" id="XREFedit"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-edit"><span><strong class="def-name">edit</strong> <code class="def-code-arguments"><var class="var">name</var></code><a class="copiable-link" href="#index-edit"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-edit-1"><span><strong class="def-name">edit</strong> <code class="def-code-arguments"><var class="var">field</var> <var class="var">value</var></code><a class="copiable-link" href="#index-edit-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-edit-2"><span><code class="def-type"><var class="var">value</var> =</code> <strong class="def-name">edit</strong> <code class="def-code-arguments">("get", <var class="var">field</var>)</code><a class="copiable-link" href="#index-edit-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-edit-3"><span><code class="def-type"><var class="var">value</var> =</code> <strong class="def-name">edit</strong> <code class="def-code-arguments">("get", "all")</code><a class="copiable-link" href="#index-edit-3"> ¶</a></span></dt>
<dd><p>Edit the named function, or change editor settings.
</p>
<p>If <code class="code">edit</code> is called with the name of a file or function as its
argument it will be opened in the default text editor. The default editor
for the Octave GUI is specified in the Editor tab of Preferences. The
default editor for the CLI is specified by the <code class="code">EDITOR</code> function.
</p>
<ul class="itemize mark-bullet">
<li>If the function <var class="var">name</var> is available in a file on your path, then it
will be opened in the editor. If no file is found, then the m-file
variant, ending with <code class="code">".m"</code>, will be considered. If still no file is
found, then variants with a leading <code class="code">"@"</code> and then with both a
leading <code class="code">"@"</code> and trailing <code class="code">".m"</code> will be considered.
</li><li>If <var class="var">name</var> is the name of a command-line function, then an m-file will
be created to contain that function along with its current definition.
</li><li>If <code class="code"><var class="var">name</var>.cc</code> is specified, then it will search for
<samp class="file"><var class="var">name</var>.cc</samp> in the path and open it in the editor. If the file is
not found, then a new <samp class="file">.cc</samp> file will be created. If <var class="var">name</var>
happens to be an m-file or command-line function, then the text of that
function will be inserted into the .cc file as a comment.
</li><li>If <samp class="file"><var class="var">name</var>.ext</samp> is on your path then it will be edited, otherwise
the editor will be started with <samp class="file"><var class="var">name</var>.ext</samp> in the current
directory as the filename.
<p><strong class="strong">Warning:</strong> You may need to clear <var class="var">name</var> before the new definition
is available. If you are editing a .cc file, you will need to execute
<code class="code">mkoctfile <samp class="file"><var class="var">name</var>.cc</samp></code> before the definition will be
available.
</p></li></ul>
<p>If <code class="code">edit</code> is called with <var class="var">field</var> and <var class="var">value</var> variables, the
value of the control field <var class="var">field</var> will be set to <var class="var">value</var>.
</p>
<p>If an output argument is requested and the first input argument is
<code class="code">get</code> then <code class="code">edit</code> will return the value of the control field
<var class="var">field</var>. If the control field does not exist, edit will return a
structure containing all fields and values. Thus, <code class="code">edit ("get",
<code class="code">"all"</code>)</code> returns a complete control structure.
</p>
<p>The following control fields are used:
</p>
<dl class="table">
<dt>‘<samp class="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 class="code">gecos</code> field of the password database.
</p>
</dd>
<dt>‘<samp class="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 class="code"><$LOGNAME@$HOSTNAME></code>, and if <code class="code">$HOSTNAME</code>
is not defined it uses <code class="code">uname -n</code>. You probably want to override
this. Be sure to use the format <code class="code"><a class="email" href="mailto:user@host">user@host</a></code>.
</p>
</dd>
<dt>‘<samp class="samp">license</samp>’</dt>
<dd>
<dl class="table">
<dt>‘<samp class="samp">gpl</samp>’</dt>
<dd><p>GNU General Public License (default).
</p>
</dd>
<dt>‘<samp class="samp">bsd</samp>’</dt>
<dd><p>BSD-style license without advertising clause.
</p>
</dd>
<dt>‘<samp class="samp">pd</samp>’</dt>
<dd><p>Public domain.
</p>
</dd>
<dt>‘<samp class="samp">"text"</samp>’</dt>
<dd><p>Your own default copyright and license.
</p></dd>
</dl>
<p>Unless you specify ‘<samp class="samp">pd</samp>’, edit will prepend the copyright statement
with "Copyright (C) YYYY Author".
</p>
</dd>
<dt>‘<samp class="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 class="code">"sync"</code> to start
the editor in sync mode. The default is <code class="code">"async"</code>
(see <a class="pxref" href="Controlling-Subprocesses.html#XREFsystem"><code class="code">system</code></a>).
</p>
</dd>
<dt>‘<samp class="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 class="code">true</code>.
Set it to <code class="code">false</code> to have read-only function files automatically
copied to ‘<samp class="samp">home</samp>’, if it exists, when editing them.
</p>
</dd>
<dt>‘<samp class="samp">home</samp>’</dt>
<dd><p>This value indicates a directory that system m-files should be copied into
before opening them in the editor. The intent is that this directory is
also in the path, so that the edited copy of a system function file shadows
the original. This setting only has an effect when ‘<samp class="samp">editinplace</samp>’ is
set to <code class="code">false</code>. The default is the empty matrix (<code class="code">[]</code>), which
means it is not used. The default in previous versions of Octave was
<samp class="file">~/octave</samp>.
</p></dd>
</dl>
<p><strong class="strong">See also:</strong> <a class="ref" href="Commands-for-History.html#XREFEDITOR">EDITOR</a>, <a class="ref" href="Manipulating-the-Load-Path.html#XREFpath">path</a>.
</p></dd></dl>
<a class="anchor" id="XREFmfilename"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-mfilename"><span><strong class="def-name">mfilename</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-mfilename"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-mfilename-1"><span><strong class="def-name">mfilename</strong> <code class="def-code-arguments">("fullpath")</code><a class="copiable-link" href="#index-mfilename-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-mfilename-2"><span><strong class="def-name">mfilename</strong> <code class="def-code-arguments">("fullpathext")</code><a class="copiable-link" href="#index-mfilename-2"> ¶</a></span></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 class="code">"fullpath"</code>, include the directory part of the
filename, but not the extension.
</p>
<p>Given the argument <code class="code">"fullpathext"</code>, include the directory part of
the filename and the extension.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Defining-Functions.html#XREFinputname">inputname</a>, <a class="ref" href="Call-Stack.html#XREFdbstack">dbstack</a>.
</p></dd></dl>
<a class="anchor" id="XREFignore_005ffunction_005ftime_005fstamp"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-ignore_005ffunction_005ftime_005fstamp"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">ignore_function_time_stamp</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-ignore_005ffunction_005ftime_005fstamp"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-ignore_005ffunction_005ftime_005fstamp-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">ignore_function_time_stamp</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-ignore_005ffunction_005ftime_005fstamp-1"> ¶</a></span></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 class="code">"system"</code>, Octave will not
automatically recompile function files in subdirectories of
<samp class="file"><var class="var">octave-home</var>/share/<var class="var">version</var>/m</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 class="code">"all"</code>, Octave will not recompile any function files
unless their definitions are removed with <code class="code">clear</code>.
</p>
<p>If set to <code class="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>
<ul class="mini-toc">
<li><a href="Manipulating-the-Load-Path.html" accesskey="1">Manipulating the Load Path</a></li>
<li><a href="Subfunctions.html" accesskey="2">Subfunctions</a></li>
<li><a href="Private-Functions.html" accesskey="3">Private Functions</a></li>
<li><a href="Nested-Functions.html" accesskey="4">Nested Functions</a></li>
<li><a href="Overloading-and-Autoloading.html" accesskey="5">Overloading and Autoloading</a></li>
<li><a href="Function-Locking.html" accesskey="6">Function Locking</a></li>
<li><a href="Function-Precedence.html" accesskey="7">Function Precedence</a></li>
</ul>
</div>
<div class="footnotes-segment">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h5 class="footnote-body-heading"><a id="FOOT5" href="#DOCF5">(5)</a></h5>
<p>The ‘<samp class="samp">.m</samp>’ suffix was chosen for compatibility
with <small class="sc">MATLAB</small>.</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Script-Files.html">Script Files</a>, Previous: <a href="Validating-Arguments.html">Validating Arguments</a>, Up: <a href="Functions-and-Scripts.html">Functions and Scripts</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
