* Bug 16529 fixed: deff() upgraded: output arg added, one-string def, etc
[scilab.git] / scilab / modules / functions / help / en_US / deff.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) XXXX-2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="deff">
20     <refnamediv>
21         <refname>deff</refname>
22         <refpurpose>in-line definition of a (anonymous) function in Scilab language</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             deff(funcHeadline, funcBody)
28             deff(definition)
29             deff("[r1, r2, ...] = myFunc(in1, in2, ...)", funcBody)
30             deff "r = myFunc(x,y) r = x^2 - y"
31             deff "r = myFunc(x,y) x^2 - y"
32             deff("r = @(x,y) x^2 - y")      // as anonymous container's element
33
34             myFunc = deff(funcHeadline, funcBody)
35             myFunc = deff(definition)
36             myFunc = deff("[r1, r2, ...] = fakeName(in1, in2, ...)", funcBody)
37             myFunc = deff("r = fakeName(x,y) r = x^2 - y")
38             myFunc = deff("r = fakeName(x,y) x^2 - y")
39             myFunc = deff("r = @(x,y) x^2 - y")
40         </synopsis>
41     </refsynopsisdiv>
42     <refsection>
43         <title>Arguments</title>
44         <variablelist>
45             <varlistentry>
46                 <term>x, y, in1, in2, ...</term>
47                 <listitem>
48                     input arguments of the defined function. This one can have any number
49                     of input arguments, from 0 to any N.
50                     <para/>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>r, r1, r2, ...</term>
55                 <listitem>
56                     Output results of the defined function. This one can have any number
57                     of output results, from 0 to any M. If any, all output arguments
58                     must be explicit = written on the left-hand-side of the function name.
59                     <para/>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>funcHeadline</term>
64                 <listitem>
65                     Single string: Function's headline = its first line giving the local
66                     function's name and the lists of its right-hand-side input arguments
67                     and left-hand-side output arguments. Examples:
68                     <itemizedlist>
69                         <listitem>
70                             <literal>"myFunction(x,y)"</literal> : no output
71                         </listitem>
72                         <listitem>
73                             <literal>"r = myFunction(x,y)"</literal> : single output
74                         </listitem>
75                         <listitem>
76                             <literal>"[a,b] = myFunction(x,y)"</literal> : two outputs. Etc..
77                         </listitem>
78                     </itemizedlist>
79                     Please note that a) the <literal>function</literal> keyword
80                     must not be provided. b) If any, writting output arguments in the
81                     left-hand-side part of the headline is mandatory.
82                     <para/>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>funcBody</term>
87                 <listitem>
88                     a vector of texts = Scilab instructions of the function's body, in the order
89                     they must be executed. These instructions must define and assign the value
90                     of all output arguments. No trailing "endfunction" keyword is expected.
91                     <para/>
92                     This vector is expected when deff(…) is called with two input arguments.
93                     <para/>
94                     <warning>
95                         Single or double quotes included in instructions must be doubled to be
96                         protected.
97                     </warning>
98                     <para/>
99                 </listitem>
100             </varlistentry>
101             <varlistentry>
102                 <term>definition</term>
103                 <listitem>
104                     Single text or vector of texts, including both the function's headline and body.
105                     <itemizedlist>
106                         <listitem>
107                             If it's a vector, it is equivalent to
108                             <literal>definition = [funcHeadline ; funcBody]</literal>.
109                         </listitem>
110                         <listitem>
111                             Otherwise, the one-string definition is equivalent to
112                             <literal>funcHeadline + " " + strcat(funcBody,"; ")</literal>.
113                         </listitem>
114                     </itemizedlist>
115                     Please see the Description and Examples sections.
116                     <para/>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>myFunc</term>
121                 <listitem>
122                     Public name and identifier of the defined function, as implicitly
123                     returned in the current environment, or explicitly assigned to the
124                     deff(…)'s output variable.
125                     <para/>
126                     <note>
127                         When deff(…) is called without explicit output argument but
128                         as an element of a container or as input argument of another function,
129                         it is implicitly assigned to this element or argument,
130                         which is anonymous. It is then an
131                         <emphasis role="bold">anonymous function</emphasis>. Example:
132                         <para/>
133                         <literal>L = list(3, deff("r=noName(x) x.^2+1"), "Hello");</literal>.
134                         The result of deff(…) is assigned to L(2). Then,
135                         <literal>L(2)(3.5) // ➜ 13.25</literal>.
136                     </note>
137                     <para/>
138                 </listitem>
139             </varlistentry>
140         </variablelist>
141     </refsection>
142     <refsection>
143         <title>Description</title>
144         <para>
145             deff(…) can be used to define a <emphasis>single</emphasis> function from Scilab
146             instructions provided through a matrix of text, instead of through any external
147             text file of instructions written in a <literal>function … endfunction</literal>
148             block to be executed.
149         </para>
150         <para>
151             A source file of Scilab code can include the definition of several public functions.
152             This is not possible with deff(…): Only one public function can be defined.
153             However, as with a file, the body of the defined function can include one
154             or several <literal>function … endfunction</literal> blocks defining
155             some nested private functions.
156         </para>
157         <para>
158             Whatever is the deff(…) syntax used to provide the source code (see below), if this one
159             includes a syntax error, deff(…) will yield a compilation error and stop.
160         </para>
161         <refsect3>
162             <title>Providing the source code</title>
163             <para>
164                 <emphasis role="bold">deff(funcHeadline, funcBody)</emphasis> (2 inputs) and
165                 <emphasis role="bold">deff([funcHeadline ; funcBody])</emphasis>
166                 (single concatenated input) are equivalent.
167             </para>
168             <para>
169                 When <varname>funcBody</varname> is made of only one (short) string, it may be glued
170                 to and passed with the <varname>funcHeadline</varname>, as a one-line function
171                 definition. Examples:
172                 <table cellpadding="0" cellspacing="0">
173                     <tr><td><literal>deff("[a,b] = myFunction(x,y) a = x.^2; b = x-y;")</literal></td>
174                     </tr>
175                     <tr><td>
176                             <literal>deff("r = myFunction(x,y) r = (x-y).^2")</literal>.
177                             This can even be simplified into
178                         </td>
179                     </tr>
180                     <tr><td>
181                             <literal>deff("r = myFunction(x,y) (x-y).^2")</literal>
182                         </td>
183                     </tr>
184                     <tr><td><literal>deff("myFunction(x,y) disp(x.^2 - b)")</literal></td>
185                     </tr>
186                 </table>
187             </para>
188             <para>
189                 When the result of deff(…) is assigned to or inserted into any anonymous element
190                 of a container, then it comes that the pseudo-name <varname>fakeName</varname>
191                 defined in the <varname>funcHeadline</varname>
192                 has no role at all, and could in no way be used to call the function.
193                 This name can then be replaced with the "@" character in the <varname>funcHeadline</varname>,
194                 to highlight that the defined function becomes <emphasis>anonymous</emphasis>.
195             </para>
196         </refsect3>
197         <refsect3>
198             <title>Identifier of the defined function</title>
199             <para>
200                 The identifier is the actual word (name) to use to call the defined function.
201                 The 3 following cases are illustrated in examples.
202             </para>
203             <para>
204                 When the defined function is not expected as a assignable result, its identifier
205                 is returned directly in the calling environment. Its public name is then the name
206                 used in the headline of the provided source code.
207             </para>
208             <para>
209                 Otherwise, when deff(…) is called with an explicit output argument, the name
210                 of this one becomes the only actual public function's identifier. As a consequence,
211                 the function name used in the source code can't be used to call it. It becomes
212                 a pseudo-name. For this reason, the "@" symbol (standing for "anonymous") can then
213                 be used in the function code's headline, instead of any valid function's name.
214                 Of course, nothing prevents to use an output name identical to any valid
215                 function name defined in the headline. But it's not mandatory.
216             </para>
217             <para>
218                 The last case is using deff(…) as an element of a container, for instance
219                 when defining or inserting into a list, or as input argument of another function.
220                 Then deff(…) works in an assignable way. It returns the identifier of the defined
221                 function and assigns it to the considered list element or input argument.
222                 These ones are nameless, since the <literal>deff(…)</literal> call is an expression.
223                 The defined function then becomes really <emphasis>anonymous</emphasis>.
224             </para>
225         </refsect3>
226     </refsection>
227     <refsection>
228         <title>Examples</title>
229         <refsect3>
230             <title>Unassigned functions</title>
231             <para/>
232             <programlisting role="example"><![CDATA[
233                 deff('x = myplus(y,z)', 'x = y+z')
234                 myplus(1,%i)
235
236                 deff('[y, z] = mymacro(x)', ['y = 3*x+1'; 'z = a*x + x.^2'])
237                 a = 3;
238                 [u, v] = mymacro(2)
239          ]]></programlisting>
240             <screen><![CDATA[
241 --> deff('x = myplus(y,z)', 'x = y+z')
242 --> myplus(1,%i)
243  ans  =
244    1. + i
245
246 --> deff('[y, z] = mymacro(x)', ['y = 3*x+1'; 'z = a*x + x.^2'])
247 --> a = 3;
248 --> [u, v] = mymacro(2)
249  v  =
250    10.
251
252  u  =
253    7.
254 ]]></screen>
255             <para>
256                 With some single input and output:
257             </para>
258             <programlisting role="example"><![CDATA[
259                 clear myFunc
260                 source = ["r = myFunc(x,y)" ; "r = x.*(x-y)"]
261                 deff(source)
262                 myFunc(3, -2)
263          ]]></programlisting>
264             <screen><![CDATA[
265 --> source = ["r = myFunc(x,y)" ; "r = x.*(x-y)"]
266  source  =
267   "r = myFunc(x,y)"
268   "r = x.*(x-y)"
269
270 --> deff(source)
271 --> myFunc(3, -2)
272  ans  =
273    15.
274 ]]></screen>
275             <para>
276                 Same example with a one-line definition, that then allows a console-oriented
277                 syntax (without optional deff parentheses, but with still mandatory delimiting quotes):
278             </para>
279             <programlisting role="example"><![CDATA[
280                 clear myFunc
281                 deff "r = myFunc(x,y) r = x.*(x-y)"
282                 myFunc(1:3, -2)
283          ]]></programlisting>
284             <screen><![CDATA[
285 --> deff "r = myFunc(x,y) r = x.*(x-y)"
286 --> myFunc(1:3, -2)
287  ans  =
288    3.   8.   15.
289 ]]></screen>
290             <para>
291                 For a one-line direct definition with a single output, we can even omit the "r = " duplicate in the body:
292             </para>
293             <programlisting role="example"><![CDATA[
294                 clear myFunc
295                 deff "r = myFunc(x,y) x.*(x-y)"
296                 myFunc(1:3, -2)
297          ]]></programlisting>
298             <screen><![CDATA[
299 --> deff "r = myFunc(x,y) x.*(x-y)"
300 --> myFunc(1:3, -2)
301  ans  =
302    3.   8.   15.
303 ]]></screen>
304             <para>
305                 Function with no assignable output: Note also the usage of doubled quotes to protect
306                 them in the definition string:
307             </para>
308             <programlisting role="example"><![CDATA[
309                 clear myFunc
310                 deff("myFunc(x, y) messagebox(prettyprint(x.*(x-y), ""html"",""""))")
311                 myFunc([1 2 ; 3 4], -2)
312          ]]></programlisting>
313         </refsect3>
314         <refsect3>
315             <title>Defined function assigned to a recipient</title>
316             <para>
317                 Let's keep similar examples as above:
318             </para>
319             <programlisting role="example"><![CDATA[
320                 clear myFunc actualName
321                 actualName = deff("r = myFunc(x,y) x.*(x-y)")
322                 isdef(["myFunc" "actualName"])
323                 actualName(1:3, -2)
324                 myFunc(1:3, -2)
325          ]]></programlisting>
326             <screen><![CDATA[
327 --> actualName = deff("r = myFunc(x,y) x.*(x-y)")
328  actualName  =
329 [r]=actualName(x,y)
330
331 --> isdef(["myFunc" "actualName"])
332  ans  =
333   F T
334
335 --> actualName(1:3, -2)
336  ans  =
337    3.   8.   15.
338
339 --> myFunc(1:3, -2)
340 Undefined variable: myFunc
341 ]]></screen>
342             <para>
343                 Since the "internal" function name is fake, we can use "@" instead
344                 (the "@" character is not allowed in actual function names):
345             </para>
346             <programlisting role="example"><![CDATA[
347                 clear actualName
348                 actualName = deff("r = @(x,y) x.*(x-y)");
349                 actualName(1:3, -2)
350          ]]></programlisting>
351             <screen><![CDATA[
352 --> actualName = deff("r = @(x,y) x.*(x-y)");
353 --> actualName(1:3, -2)
354  ans  =
355    3.   8.   15.
356 ]]></screen>
357             <para>
358                 Now, let's directly assign the created function to a nameless recipient.
359                 Although the function becomes anonymous, we can still call it:
360             </para>
361             <programlisting role="example"><![CDATA[
362                 L = list("abc", deff("r = @(x,y) x.*(x-y)"), %z);
363                 L(2)(1.1:4, -2.1)
364                 // We can extract and set a name to the anonymous function:
365                 Abc = L(2)
366                 Abc(1.1:4, -2.1)
367          ]]></programlisting>
368             <screen><![CDATA[
369 --> L = list("abc", deff("r = @(x,y) x.*(x-y)"), %z);
370 --> L(2)(1.1:4, -2.1)
371  ans  =
372    3.52   8.82   16.12
373
374 --> Abc = L(2)
375  Abc  =
376 [r]=Abc(x,y)
377
378 --> Abc(1.1:4, -2.1)
379  ans  =
380    3.52   8.82   16.12
381 ]]></screen>
382             <para>
383                 Finally, let's use deff() to directly define and pass a function
384                 as an input argument of another function:
385             </para>
386             <programlisting role="example"><![CDATA[
387                 function r = test(txt, x, theFunc)
388                     r = x + theFunc(txt)
389                 endfunction
390
391                 test(rand(2,3), 0.7, deff("r = @(M) sum(size(M).^2)"))
392          ]]></programlisting>
393             <screen><![CDATA[
394 --> test(rand(2,3), 0.7, deff("r = @(M) sum(size(M).^2)"))
395  ans  =
396    13.7
397 ]]></screen>
398         <para>
399             In this example, the passed function is anonymous in the calling environment,
400             but is assigned and gets its "theFunct" name from inside the called function.
401         </para>
402         </refsect3>
403     </refsection>
404     <refsection role="see also">
405         <title>See also</title>
406         <simplelist type="inline">
407             <member>
408                 <link linkend="function">function</link>
409             </member>
410             <member>
411                 <link linkend="exec">exec</link>
412             </member>
413             <member>
414                 <link linkend="getd">getd</link>
415             </member>
416             <member>
417                 <link linkend="genlib">genlib</link>
418             </member>
419             <member>
420                 <link linkend="jdeff">jdeff</link>
421             </member>
422             <member>
423                 <link linkend="jcompile">jcompile</link>
424             </member>
425         </simplelist>
426     </refsection>
427     <refsection role="history">
428         <title>History</title>
429         <revhistory>
430             <revision>
431                 <revnumber>6.0.0</revnumber>
432                 <revdescription>
433                    <itemizedlist>
434                      <listitem>
435                        The input option
436                        <ulink url="https://help.scilab.org/docs/5.5.2/en_US/deff.html">
437                          <varname>opt="c"|"p"|"n"</varname>
438                        </ulink> is no longer available.
439                      </listitem>
440                      <listitem>
441                         The defined <varname>newfunction</varname> is now of type 13 (instead of 11).
442                      </listitem>
443                   </itemizedlist>
444                 </revdescription>
445             </revision>
446             <revision>
447                 <revnumber>6.1.1</revnumber>
448                 <revdescription>
449                    <itemizedlist>
450                      <listitem>
451                         Output optional argument added. Anonymous functions can be defined.
452                      </listitem>
453                      <listitem>
454                         Single input argument supported, concatenating the function headline and body.
455                      </listitem>
456                      <listitem>
457                         Single string syntax supported, like <literal>deff "r = myFun(x,y) x.^2-y"</literal>
458                      </listitem>
459                      <listitem>
460                         "@" function's pseudo-name supported.
461                      </listitem>
462                   </itemizedlist>
463                 </revdescription>
464             </revision>
465         </revhistory>
466     </refsection>
467 </refentry>