* Bug 14883 fixed: whereis returned [] for builtin. Page overhauled for 6.0 99/19399/6
Samuel GOUGEON [Wed, 23 Aug 2017 20:01:18 +0000 (22:01 +0200)]
 * http://bugzilla.scilab.org/14883
 * Scilab 6 changes were not yet documented
 * Added in the 6.0.1 section. Is it right? (could be < beta2)
 * Page moved, since, now, libraries AND builtin are covered.
 * Page to be retranslated from scratch (almost rewritten => too many changes)

Change-Id: Iac85a538b4c096be15551ff35b5388f5f18042c2

scilab/CHANGES.md
scilab/modules/functions/help/en_US/libraries/whereis.xml [deleted file]
scilab/modules/functions/help/en_US/whereis.xml [new file with mode: 0644]
scilab/modules/functions/help/fr_FR/libraries/whereis.xml [deleted file]
scilab/modules/functions/help/ja_JP/libraries/whereis.xml [deleted file]
scilab/modules/functions/help/pt_BR/libraries/whereis.xml [deleted file]
scilab/modules/functions_manager/src/cpp/dynamic_modules.cpp

index 6883f27..027dde2 100644 (file)
@@ -220,6 +220,11 @@ bounds selected out of the axes areas is now restored, after the Scilab 5.4 regr
 * `gcd` now accepts `int64` and `uint64` integers. The input can now be any array instead of a row.
 * `cat` has been rewritten. It is now fast and can process heavy arrays at high dimensions.
 * `fplot3d1` remove warning messages when it was called without option.
+* `whereis` has been upgraded:
+  - It can now be used for builtin functions.
+  - When the same function name is registered in several libraries, `whereis` now returns all of them instead of only the last loaded one.
+  - For unregistered user-defined macros, `"script"` is now returned instead of `[]`.
+
 
 Help pages:
 -----------
@@ -229,7 +234,7 @@ Help pages:
   `scilab|scilex`, `flipdim`, `Matplot_properties`, `meshgrid`, `ismatrix`, `xget`, `xset`, `ieee`
 * rewritten: `consolebox`, `double`, `isoview`, `pixel_drawing_mode`, `householder`, `or`, `|,||`,
 `and`, `&,&&`, `format`, `typeof`, `brackets`, `setlanguage`, `sleep`, `isinf`,
-`bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `isglobal`
+`bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `isglobal`, `whereis`
 * reorganized:
   - `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`, `numderivative`
   - `pixel_drawing_mode`, `show_window`, `twinkle`, `uigetcolor`, `winsid`, `xdel`, `xgrid`, `xname`, `xnumb`
@@ -379,6 +384,7 @@ the [development mailing list](dev@lists.scilab.org) for a particular toolbox.
 * [#14636](http://bugzilla.scilab.org/show_bug.cgi?id=14636): Xcos model with modelica electrical blocks (created in 5.5.2) crashed Scilab 6.
 * [#14637](http://bugzilla.scilab.org/show_bug.cgi?id=14367): Some Scilab 5.5.2 diagrams didn't simulate properly in Xcos.
 * [#14680](http://bugzilla.scilab.org/show_bug.cgi?id=14680): The `<` char in expression was not rendered in the icon of Xcos EXPRESSION block.
+* [#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 first one was set.
 * [#14910](http://bugzilla.scilab.org/show_bug.cgi?id=14910): The `plot()` example was displayed in overlay to the existing graphics.
diff --git a/scilab/modules/functions/help/en_US/libraries/whereis.xml b/scilab/modules/functions/help/en_US/libraries/whereis.xml
deleted file mode 100644 (file)
index 425eb3c..0000000
+++ /dev/null
@@ -1,35 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<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="whereis">
-    <refnamediv>
-        <refname>whereis</refname>
-        <refpurpose>name of library containing a function</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Syntax</title>
-        <synopsis>[librname]=whereis(function-name)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Description</title>
-        <para>
-            returns as a character string
-            the name of the library containing the function <literal>function-name</literal>.
-            The path of the library is returned by typing <literal>"librname"</literal>.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemples</title>
-        <programlisting role="example"><![CDATA[
-whereis("ls") // Should return fileiolib
-whereis("plot") // Should return graphicslib
- ]]></programlisting>
-    </refsection>
-
-    <refsection role="see also">
-        <title>See also</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/functions/help/en_US/whereis.xml b/scilab/modules/functions/help/en_US/whereis.xml
new file mode 100644 (file)
index 0000000..78583c6
--- /dev/null
@@ -0,0 +1,254 @@
+<?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="whereis">
+    <refnamediv>
+        <refname>whereis</refname>
+        <refpurpose>Returns the name of the loaded library/module a given function belongs to</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Syntax</title>
+        <synopsis>libmod = whereis(function)</synopsis>
+    </refsynopsisdiv>
+    <refsection role="arguments">
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>function</term>
+                <listitem>
+                    <para>
+                    Name (text) or handle of a Scilab "macro" or builtin function. Both
+                    kinds of input are equivalent.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>libmod</term>
+                <listitem>
+                    <para>If <literal>function</literal> points to
+                        <itemizedlist>
+                            <listitem>
+                                a function written in Scilab language and registered with
+                                <link linkend="genlib">genlib</link> in some loaded library:
+                                <literal>libmod</literal> returns the name of the library.
+                            </listitem>
+                            <listitem>
+                                an unregistered user-defined function written in Scilab language:
+                                <literal>libmod</literal> returns <literal>"script"</literal>.
+                            </listitem>
+                            <listitem>
+                                a builtin function (so-called Scilab primitive): the name of the
+                                module the <literal>function</literal> belongs to is returned.
+                            </listitem>
+                            <listitem>Otherwise: <literal>libmod</literal> returns <literal>[]</literal>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            <literal>whereis</literal> allows to identify the library of Scilab macros or the
+            module a given function belongs to.
+        </para>
+        <para>
+            When the function is
+            <variablelist>
+                <varlistentry>
+                    <term>a "macro" (written in Scilab language and compiled):</term>
+                    <para>
+                        it may be not loaded (not yet called), but its library must be so.
+                    </para>
+                    <para>
+                        When the same function name is registered in several loaded libraries of
+                        macros, <literal>whereis</literal> returns the name of all of them.
+                    </para>
+                    <para>
+                        <link linkend="libraryinfo">libraryinfo(..)</link> allows to retrieve the
+                        path to definition files of a library.
+                    </para>
+                    <warning>
+                        <itemizedlist>
+                            <listitem>
+                                Since Scilab 6.0: When, in the mymacro.sci file defining a public
+                                macro mymacro() registered in a library, some additional functions
+                                are defined after mymacro(), these additional functions are NOT
+                                registered in the library.
+                                So, <literal>whereis</literal> ignores them and will return
+                                <literal>[]</literal> for them. See the Examples section.
+                            </listitem>
+                            <listitem>
+                                When a module like <literal>xcos</literal> has sublibraries,
+                                these ones are often loaded in Scilab only after the first call
+                                to the main function (like <literal>xcos()</literal>).
+                                As a consequence,
+                                <literal>whereis(..)</literal> querried for a function of such a
+                                sublibrary will return <literal>[]</literal>, until the main
+                                function -- like <literal>xcos()</literal> -- is called a first time.
+                                See the Examples section.
+                            </listitem>
+                        </itemizedlist>
+                    </warning>
+                    <para></para>
+                </varlistentry>
+                <varlistentry>
+                    <term>a user-defined function registered in no library</term>
+                    <para>
+                        but defined
+                        <itemizedlist>
+                            <listitem>
+                                directly in the console by <literal>deff(..)</literal> or by
+                                <literal>function ... endfunction</literal>, or
+                            </listitem>
+                            <listitem>
+                                in a file loaded in the Scilab session with <literal>exec(functionfile.sci)</literal>
+                                or with <literal>getd(..)</literal>,
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <para>
+                        <literal>whereis</literal> returns <literal>"script"</literal>.
+                        When this function is defined in a file, there is no way to retrieve the file
+                        path and name.
+                    </para>
+                </varlistentry>
+                <varlistentry>
+                    <term>a builtin written and compiled in an external language (C, C++..):</term>
+                    <para>
+                        <literal>whereis</literal> returns the name of the module the function
+                        belongs to. More precisely, the name of the "gateway" is returned.
+                        It matches the module's name for all cases except for
+                        <literal>action_binding_gw, functions_gw, matio_gw, signal_processing_gw,
+                        statistics_gw</literal>, for which <literal>"_gw"</literal>
+                        is appended to the module name.
+                    </para>
+                    <para>
+                        The gateway file is located at
+                        <literal>SCI/modules/moduleName/gateway/moduleName_gateway.xml</literal>,
+                        where <literal>moduleName</literal> must be replaced with the actual module name.
+                    </para>
+                </varlistentry>
+            </variablelist>
+        </para>
+        <warning>
+            In the case that the function name is simultaneously defined as a unregistered function
+            ("script"), and as a registered one in a library and as a builtin,
+            <literal>whereis</literal> returns only one kind of answer with the likely priorities:
+            <literal>builtin's module > macro's library > "script" for unregistered macro</literal>.
+            However, the actual result may vary (and be []).
+        </warning>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+// Case of an unregistered macro:
+function myTest(), disp("Unregistered function"), endfunction
+whereis("myTest")               // => "script"
+
+// Case of a registered macro:
+r = whereis("ls")               // => "fileiolib"
+[?,path]= libraryinfo(r); path  // => "SCI\modules\fileio\macros\"
+
+// Let's define another ls() in another library:
+path = TMPDIR+"/myls";
+mkdir(path);
+mputl("function ls(), disp(""my other ls() in lslib""), endfunction", path+"/ls.sci");
+genlib("lslib", path);
+whereis ls                      // => ["fileiolib"; "lslib"]
+
+// Case of a builtin function
+whereis sin                     // => "elementary_functions"
+whereis conv2                   // => "signal_processing_gw"
+
+// Case of an unregistered macro defined/loaded after a registered one:
+clear ls lslib
+whereis ls                      // "fileiolib" : OK
+function ls(),  disp("my local ls()"), endfunction
+ls                              // => "my local ls()"
+whereis ls                      // => "fileiolib", still
+clear ls                        // (cleaning up)
+
+// Dependencies are ignored:
+// chfact() has some private dependency functions blkfc1(), inpnv(), etc:
+edit chfact
+// chfact() is registered:
+whereis chfact                  // => "sparselib"
+// .. but not its dependencies:
+whereis blkfc1                  // => []
+
+// Sublibraries may be loaded only after the first call to a main driving function:
+// CLR() is a public function related to the CLR Xcos block belonging to the
+//  Linear palette and declared in the Linearlib library.
+// But this sublibrary is loaded only after a first call to xcos():
+whereis xcos         // => "xcoslib"
+whereis CLR          // => [], if you never called xcos() in the session yet.
+xcos()               // => loads all its sublibraries. Please ignore the interfaces.
+                     //    You may even close them.
+whereis CLR          // => "Linearlib" non-empty answer, now
+ ]]></programlisting>
+    </refsection>
+
+    <refsection role="see also">
+        <title>See also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="genlib">genlib</link>
+            </member>
+            <member>
+                <link linkend="libraryinfo">libraryinfo</link>
+            </member>
+            <member>
+                <link linkend="lib">lib</link>
+            </member>
+            <member>
+                <link linkend="getmodules">getmodules</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <literal>whereis</literal> now supports builtin functions.
+                        </listitem>
+                        <listitem>
+                            When the same function name is registered in several libraries,
+                            <literal>whereis</literal> now returns all of them instead of only the
+                            last loaded one.
+                        </listitem>
+                        <listitem>
+                            For unregistered user-defined macros, <literal>whereis</literal>
+                            now returns <literal>"script"</literal> instead of <literal>[]</literal>.
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/functions/help/fr_FR/libraries/whereis.xml b/scilab/modules/functions/help/fr_FR/libraries/whereis.xml
deleted file mode 100644 (file)
index bf8966a..0000000
+++ /dev/null
@@ -1,35 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<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="whereis">
-    <refnamediv>
-        <refname>whereis</refname>
-        <refpurpose>nom de la bibliothèque contenant une fonction</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Séquence d'appel</title>
-        <synopsis>[librname]=whereis(function-name)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Description</title>
-        <para>
-            Renvoie une chaîne de caractères contenant le nom de la bibliothèque contenant
-            la fonction <literal>function-name</literal>.
-            Le chemin d'accès à la bibliothèque peut être obtenu avec la fonction <literal>"librname"</literal>.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Examples</title>
-        <programlisting role="example"><![CDATA[
-whereis("ls") // Devrait retourner fileiolib
-whereis("plot") // Devrait retourner graphicslib
- ]]></programlisting>
-    </refsection>
-
-    <refsection role="see also">
-        <title>Voir aussi</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/functions/help/ja_JP/libraries/whereis.xml b/scilab/modules/functions/help/ja_JP/libraries/whereis.xml
deleted file mode 100644 (file)
index 11f4313..0000000
+++ /dev/null
@@ -1,67 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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="ja" xml:id="whereis">
-
-    <refnamediv>
-
-        <refname>whereis</refname>
-
-        <refpurpose>関数が属するライブラリの名前</refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>[librname]=whereis(function-name)</synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            関数<literal>function-name</literal>が属するライブラリの名前を
-
-            文字列として返します.
-
-            ライブラリのパス名は<literal>"librname"</literal>と入力することにより
-
-            返されます.
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>例</title>
-
-        <programlisting role="example"><![CDATA[
-whereis("ls") // fileiolibを返します
-whereis("plot") // graphicslibを返します
- ]]></programlisting>
-
-    </refsection>
-
-    <refsection role="see also">
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="lib">lib</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
diff --git a/scilab/modules/functions/help/pt_BR/libraries/whereis.xml b/scilab/modules/functions/help/pt_BR/libraries/whereis.xml
deleted file mode 100644 (file)
index f69dcbd..0000000
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="whereis" xml:lang="pt">
-    <refnamediv>
-        <refname>whereis</refname>
-        <refpurpose>ome da biblioteca contendo a função</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>[librname]=whereis(function-name)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Descrição</title>
-        <para>Retorna um string correspondente ao nome da biblioteca onde a função
-            <literal>function-name</literal>. se encontra. O endereço da biblioteca é
-            retornado digitando-se <literal>"librname"</literal>.
-        </para>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="lib">lib</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index 994d460..acf0bed 100644 (file)
@@ -152,7 +152,7 @@ int FunctionsModule::Load()
 
     for (int i = 0 ; i < (int)vect.size() ; i++)
     {
-        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstModuleName));
+        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstPath));
     }
 
     FREE(pwstLibName);
@@ -173,7 +173,7 @@ int StatisticsModule::Load()
 
     for (int i = 0 ; i < (int)vect.size() ; i++)
     {
-        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstModuleName));
+        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstPath));
     }
 
     FREE(pwstLibName);
@@ -194,7 +194,7 @@ int SignalProcessingModule::Load()
 
     for (int i = 0 ; i < (int)vect.size() ; i++)
     {
-        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstModuleName));
+        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstPath));
     }
 
     FREE(pwstLibName);
@@ -247,7 +247,7 @@ int MatioModule::Load()
 
     for (int i = 0 ; i < (int)vect.size() ; i++)
     {
-        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstModuleName));
+        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstPath));
     }
 
     FREE(pwstLibName);
@@ -287,7 +287,7 @@ int ActionBindingModule::Load()
 
     for (int i = 0 ; i < (int)vect.size() ; i++)
     {
-        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstModuleName));
+        symbol::Context::getInstance()->addFunction(types::Function::createFunction(vect[i].wstFunction, vect[i].wstName, pwstLibName, vect[i].iType, NULL, wstPath));
     }
 
     FREE(pwstLibName);