* Bugs 2441 & 14922 fixed: %onprompt() fixed & documented 93/19593/6
Samuel GOUGEON [Fri, 8 Dec 2017 23:55:31 +0000 (00:55 +0100)]
  http://bugzilla.scilab.org/2441
  http://bugzilla.scilab.org/14922

Change-Id: I770ad0503fad28ff561996448067c21c53a6f585

scilab/CHANGES.md
scilab/modules/console/help/en_US/onprompt.xml [new file with mode: 0644]
scilab/modules/console/help/fr_FR/onprompt.xml [new file with mode: 0644]

index ff355c1..d2bb09c 100644 (file)
@@ -240,7 +240,8 @@ Help pages:
   `uigetfont`, `uigetdir`, `uigetfile`, `uiputfile`, `cat`, `makecell`, `xstring`, `norm`, `barhomogenize`
 * rewritten: `consolebox`, `double`, `isoview`, `pixel_drawing_mode`, `householder`, `or`, `|,||`,
  `and`, `&,&&`, `format`, `typeof`, `brackets`, `setlanguage`, `sleep`, `isinf`, `unique`,
- `bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `isglobal`, `whereis`, `mode`
+ `bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `isglobal`,
+ `whereis`, `mode`, `%onprompt`
 * reorganized:
   - `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`, `numderivative`
   - `pixel_drawing_mode`, `show_window`, `twinkle`, `uigetcolor`, `winsid`, `xdel`, `xgrid`, `xname`, `xnumb`
@@ -377,6 +378,7 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 
 
 ### Bugs fixed in 6.0.1:
+* [#2441](http://bugzilla.scilab.org/show_bug.cgi?id=2441): `%onprompt()` could be defined only at the top execution level.
 * [#4276](http://bugzilla.scilab.org/show_bug.cgi?id=4276): `strsubst` replaced the first occurence in regex mode.
 * [#5248](http://bugzilla.scilab.org/show_bug.cgi?id=5248): The graphical entity picker was out of work.
 * [#5278](http://bugzilla.scilab.org/show_bug.cgi?id=5278): obsolete `xset()` was still used in scripts, macros, tests and help pages.
@@ -413,7 +415,6 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 * [#13592](http://bugzilla.scilab.org/show_bug.cgi?id=13592): In an axes in a uicontrol frame, setting a `legend` interactively might not follow the mouse accurately.
 * [#13900](http://bugzilla.scilab.org/show_bug.cgi?id=13900): `nanmin` and `nanmax` were useless duplicates of `min` and `max`
 * [#13979](http://bugzilla.scilab.org/show_bug.cgi?id=13979): A variable whose name is longer than 24 characters could not be cleared.
-* [#14901](http://bugzilla.scilab.org/show_bug.cgi?id=14901): WScilex.exe was stopped immediately when launched from Java.
 * [#14254](http://bugzilla.scilab.org/show_bug.cgi?id=14254): When installing an ATOMS module that is not locally registered and available, the error message was unclear.
 * [#14376](http://bugzilla.scilab.org/show_bug.cgi?id=14376): `input()` was broken: \n was introduced before prompting; multiple prompts occurred; the output value could be missing; "%" "\n" "\t" were no longer supported in messages...
 * [#14399](http://bugzilla.scilab.org/show_bug.cgi?id=14399): `whereami`: wrong information (line numbers).
@@ -433,7 +434,9 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 * [#14883](http://bugzilla.scilab.org/show_bug.cgi?id=14883): `whereis` did not support builtin functions.
 * [#14886](http://bugzilla.scilab.org/show_bug.cgi?id=14886): `Matplot` save/load failed.
 * [#14896](http://bugzilla.scilab.org/show_bug.cgi?id=15272): Using `set` with multiple properties, only the first one was set.
+* [#14901](http://bugzilla.scilab.org/show_bug.cgi?id=14901): WScilex.exe was stopped immediately when launched from Java.
 * [#14910](http://bugzilla.scilab.org/show_bug.cgi?id=14910): The `plot()` example was displayed in overlay to the existing graphics.
+* [#14922](http://bugzilla.scilab.org/show_bug.cgi?id=14922): The `%onprompt()` special function was not documented.
 * [#14925](http://bugzilla.scilab.org/show_bug.cgi?id=14925): `jdeff`: `invoke_lu()` deleted/corrupted the called java method after an error occured.
 * [#14981](http://bugzilla.scilab.org/show_bug.cgi?id=14981): Some vertical concatenations of cells and further cells extractions crash Scilab.
 * [#15006](http://bugzilla.scilab.org/show_bug.cgi?id=15006): `ode` help page still contained 'root' which has been replaced by 'roots'.
diff --git a/scilab/modules/console/help/en_US/onprompt.xml b/scilab/modules/console/help/en_US/onprompt.xml
new file mode 100644 (file)
index 0000000..52a9dbf
--- /dev/null
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2017 - Samuel GOUGEON
+ *
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en"
+        xml:id="percentonprompt">
+    <refnamediv>
+        <refname>%onprompt</refname>
+        <refpurpose>special custom function called after each line execution in console</refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Description</title>
+        <para>
+            If it is defined, the function <literal>%onprompt()</literal>
+            <itemizedlist>
+                <listitem>
+                    must be written in Scilab language.
+                </listitem>
+                <listitem>
+                    expects no explicit input argument.
+                </listitem>
+                <listitem>
+                    assigns to <literal>ans</literal> its first explicit output argument (if any).
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            Then, <literal>%onprompt()</literal> is automatically executed after the historization
+            and the execution of each row of instructions entered in the console (even if it is
+            only a comment).
+        </para>
+        <para>
+            If an output argument is defined, <literal>ans</literal> is displayed even if a
+            semi-colon is appended to the row of instructions.
+            Other explicit output arguments (if any) are ignored.
+        </para>
+        <note>
+            <itemizedlist>
+                <listitem>
+                    <literal>%onprompt()</literal> may be (re)defined at any execution level.
+                </listitem>
+                <listitem>
+                    If some diaries are open and <literal>%onprompt()</literal> displays some
+                    contents in the console, these ones are recorded in the diaries with all other
+                    console outputs.
+                </listitem>
+            </itemizedlist>
+        </note>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example">
+            <![CDATA[
+// Redisplaying the last line of instructions after its execution:
+function %onprompt()
+    mprintf("%s\n", gethistory()($));
+endfunction
+a = grand(3,5,"uin",-9,9), b = %pi;
+// This is a comment
+ ]]>
+        </programlisting>
+        <screen><![CDATA[
+--> a = grand(3,5,"uin",-9,9), b = %pi
+ a  =
+   0.  -5.  -9.   5.   3.
+  -9.   5.  -9.  -4.   8.
+   2.  -5.  -6.   6.   0.
+
+ b  =
+   3.1415927
+
+a = grand(3,5,"uin",-9,9), b = %pi
+
+--> // This is a comment
+// This is a comment
+
+--> ]]></screen>
+    </refsection>
+    <refsection role="see also">
+        <title>See also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="prompt">prompt</link>
+            </member>
+            <member>
+                <link linkend="ans">ans</link>
+            </member>
+            <member>
+                <link linkend="gethistory">gethistory</link>
+            </member>
+            <member>
+                <link linkend="startup">startup files</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/console/help/fr_FR/onprompt.xml b/scilab/modules/console/help/fr_FR/onprompt.xml
new file mode 100644 (file)
index 0000000..d6f75b1
--- /dev/null
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2017 - Samuel GOUGEON
+ *
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="fr"
+        xml:id="percentonprompt">
+    <refnamediv>
+        <refname>%onprompt</refname>
+        <refpurpose>fonction spéciale appelée après chaque ligne d'instructions en console</refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Si elle est définie, la fonction <literal>%onprompt()</literal>
+            <itemizedlist>
+                <listitem>
+                    peut être écrite en langage Scilab
+                </listitem>
+                <listitem>
+                    attend aucun argument d'entrée explicite
+                </listitem>
+                <listitem>
+                    affecte à <literal>ans</literal> le contenu de son 1er argument de sortie
+                    (s'il y en un au moins un).
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            <literal>%onprompt()</literal> est alors automatiquement exécutée après l'historisation
+            et l'éxécution de chaque ligne d'instructions entrée en console (même s'il s'agit
+            uniquement d'un commentaire).
+        </para>
+        <para>
+            Si un argument de sortie est défini, <literal>ans</literal> est affichée, même si un
+            point-virgule suit la dernière instruction (il neutralise l'affichage du résultat
+            de celle-ci, non de celui de <literal>%onprompt()</literal>). Tout autre éventuel
+            argument de sortie supplémentaire est ignoré.
+        </para>
+        <note>
+            <itemizedlist>
+                <listitem>
+                    <literal>%onprompt()</literal> peut être (re)définie à chaque niveau d'exécution.
+                </listitem>
+                <listitem>
+                    Si un journal est ouvert (avec <literal>diary()</literal>), tout affichage
+                    réalisé par <literal>%onprompt()</literal> en console est enregistré avec tous
+                    les autres contenus affichés.
+                </listitem>
+            </itemizedlist>
+        </note>
+    </refsection>
+    <refsection>
+        <title>Exemples</title>
+        <programlisting role="example">
+            <![CDATA[
+// Reaffichage de la dernière ligne d'instruction après son exécution :
+function %onprompt()
+    mprintf("%s\n", gethistory()($));
+endfunction
+a = grand(3,5,"uin",-9,9), b = %pi;
+// Ceci est un commentaire
+ ]]>
+        </programlisting>
+        <screen><![CDATA[
+--> a = grand(3,5,"uin",-9,9), b = %pi
+ a  =
+   0.  -5.  -9.   5.   3.
+  -9.   5.  -9.  -4.   8.
+   2.  -5.  -6.   6.   0.
+
+ b  =
+   3.1415927
+
+a = grand(3,5,"uin",-9,9), b = %pi
+
+--> // Ceci est un commentaire
+// Ceci est un commentaire
+
+--> ]]></screen>
+    </refsection>
+    <refsection role="see also">
+        <title>Voir aussi</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="prompt">prompt</link>
+            </member>
+            <member>
+                <link linkend="ans">ans</link>
+            </member>
+            <member>
+                <link linkend="gethistory">gethistory</link>
+            </member>
+            <member>
+                <link linkend="startup">startup files</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>