[doc] libraryinfo() page overhauled
[scilab.git] / scilab / modules / functions / help / en_US / libraries / libraryinfo.xml
index cc9fc3b..d686637 100644 (file)
 <?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="libraryinfo">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) DIGITEO - Scilab Consortium
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2019 - Samuel GOUGEON
+ *
+ * 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="libraryinfo">
     <refnamediv>
         <refname>libraryinfo</refname>
-        <refpurpose>get macros and path of a scilab library</refpurpose>
+        <refpurpose>gets the path and the set of primary functions of a loaded library</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>macros = libraryinfo(libraryname)
-            [macros,path] = libraryinfo(libraryname)
+        <synopsis>
+            macros = libraryinfo(libraryname)
+            [macros, libpath] = libraryinfo(libraryname)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>macros</term>
+                <term>libraryname</term>
                 <listitem>
-                    <para>a string matrix (all main functions of the library)</para>
+                    <para>string: name of the loaded library.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
         <variablelist>
             <varlistentry>
-                <term>path</term>
+                <term>macros</term>
                 <listitem>
-                    <para>a string (path of library)</para>
+                    <para>column of strings: names of main functions belonging to the library.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
         <variablelist>
             <varlistentry>
-                <term>libraryname</term>
+                <term>libpath</term>
                 <listitem>
-                    <para>a string (library name)</para>
+                    <para>string: path to the lib file of the library.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>Description</title>
-        <para>get functions names  and path of a scilab library.The function names
-            returned correspond to those which correspond to the associated .sci or .bin
-            file names. The other ones are subsidiary functions.
+        <para>
+            gets the names of the functions (written in Scilab language) belonging to the given
+            library, and the path of the directory where their *.sci files and the lib file
+            are stored. Subsidiary functions that may follow the main ones in .sci files
+            are private and are not returned.
+            <warning>
+                Only loaded libraries can be addressed by <literal>libraryinfo()</literal>.
+            </warning>
         </para>
+        <refsect3>
+            <title>Getting some library info from its handle</title>
+            <para>
+                <literal>libraryinfo()</literal> works from the literal name of the library.
+                In some cases, we may have only its handle, defined when loading the library.
+                For instance, <literal>libraryinfo("iolib")</literal> works,
+                <literal>libraryinfo(iolib)</literal> does not.
+                How to use the handle to get any info? Let's go on with the <literal>iolib</literal>
+                example:
+                <itemizedlist>
+                    <listitem>
+                        <emphasis role="bold">Getting the path</emphasis>:
+                        <literal>libpath = string(iolib)(1)</literal>
+                    </listitem>
+                    <listitem>
+                        <emphasis role="bold">Getting the column vector of members functions</emphasis>:
+                        <literal>functions = string(iolib)(2:$)</literal>
+                    </listitem>
+                    <listitem>
+                        <emphasis role="bold">Getting the literal name of the library</emphasis>:
+                        <literal>libraryname = xmlGetValues("//scilablib", "name", libpath)</literal>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Unloaded library: getting info through its path</title>
+            <para>
+                If the considered library is not loaded, neither <literal>libraryinfo()</literal>
+                nor  <literal>string()</literal> can work.
+            </para>
+            <para>
+                Provided that we know its libpath, we then can
+                <itemizedlist>
+                    <listitem>
+                        <emphasis role="bold">get its literal name</emphasis>:
+                        <literal>xmlGetValues("//scilablib", "name", libpath+"/lib")</literal>
+                    </listitem>
+                    <listitem>
+                        <emphasis role="bold">get the column vector of members functions</emphasis>:
+                        <literal>functions = xmlGetValues("//scilablib/macro", "name", libpath+"/lib")</literal>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>
+            With libraryinfo(), from the literal library name:
+        </para>
+        <programlisting role="example"><![CDATA[
+[f, p] = libraryinfo("iolib")
+     ]]></programlisting>
+    <screen><![CDATA[
+--> [f, p] = libraryinfo("iolib")
+ p  =
+ SCI\modules\io\macros\
+
+ f  =
+!input      !
+!unix_g     !
+!unix_w     !
+!%_sodload  !
+!unix_x     !
+!unix_s     !
+]]></screen>
+        <para/>
+        <para>
+            From the library handle:
+        </para>
         <programlisting role="example"><![CDATA[
-[m,p]=libraryinfo('corelib')
- ]]></programlisting>
+// Just for display:
+iolib
+
+// Catch info into variables:
+p = string(iolib)(1)
+f = string(iolib)(2:$)
+libname = xmlGetValues("//scilablib", "name", p+"/lib")
+     ]]></programlisting>
+    <screen><![CDATA[
+--> // Just for display:
+--> iolib
+
+ iolib  =
+Functions files location : SCI\modules\io\macros\.
+input  unix_g  unix_w  %_sodload  unix_x  unix_s
+
+--> // Catch info into variables:
+--> p = string(iolib)(1)
+ p  =
+ SCI\modules\io\macros\
+
+--> f = string(iolib)(2:$)
+ f  =
+!input      !
+!unix_g     !
+!unix_w     !
+!%_sodload  !
+!unix_x     !
+!unix_s     !
+
+--> libname = xmlGetValues("//scilablib", "name", p+"/lib")
+ libname  =
+ iolib
+]]></screen>
+    <para/>
+        <para>
+            For a not-loaded library, from its path:
+        </para>
+        <programlisting role="example"><![CDATA[
+path = fullpath("SCI/modules/scicos_blocks/macros/Hydraulics");
+libname = xmlGetValues("//scilablib", "name", path+"/lib")
+functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
+Hydraulicslib  // not-loaded (Xcos must have not been run)
+     ]]></programlisting>
+    <screen><![CDATA[
+--> libname = xmlGetValues("//scilablib", "name", path+"/lib")
+ libname  =
+ Hydraulicslib
+
+--> functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
+ functions  =
+!Bache          !
+!Flowmeter      !
+!PerteDP        !
+!PuitsP         !
+!SourceP        !
+!VanneReglante  !
+
+--> Hydraulicslib
+Undefined variable: Hydraulicslib
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="string">string</link>
+            </member>
+            <member>
+                <link linkend="load">load</link>
+            </member>
+            <member>
                 <link linkend="librarieslist">librarieslist</link>
             </member>
             <member>