scilab/modules/functions/help/en_US/libraries/libraryinfo.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) DIGITEO - Scilab Consortium
   5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   6  * Copyright (C) 2019 - 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="libraryinfo">
  20     <refnamediv>
  21         <refname>libraryinfo</refname>
  22         <refpurpose>gets the path and the set of primary functions of a loaded library</refpurpose>
  23     </refnamediv>
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             macros = libraryinfo(libraryname)
  28             [macros, libpath] = libraryinfo(libraryname)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Arguments</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>libraryname</term>
  36                 <listitem>
  37                     <para>string: name of the loaded library.</para>
  38                 </listitem>
  39             </varlistentry>
  40         </variablelist>
  41         <variablelist>
  42             <varlistentry>
  43                 <term>macros</term>
  44                 <listitem>
  45                     <para>column of strings: names of main functions belonging to the library.</para>
  46                 </listitem>
  47             </varlistentry>
  48         </variablelist>
  49         <variablelist>
  50             <varlistentry>
  51                 <term>libpath</term>
  52                 <listitem>
  53                     <para>string: path to the lib file of the library.</para>
  54                 </listitem>
  55             </varlistentry>
  56         </variablelist>
  57     </refsection>
  58     <refsection>
  59         <title>Description</title>
  60         <para>
  61             gets the names of the functions (written in Scilab language) belonging to the given
  62             library, and the path of the directory where their *.sci files and the lib file
  63             are stored. Subsidiary functions that may follow the main ones in .sci files
  64             are private and are not returned.
  65             <warning>
  66                 Only loaded libraries can be addressed by <literal>libraryinfo()</literal>.
  67             </warning>
  68         </para>
  69         <refsect3>
  70             <title>Getting some library info from its handle</title>
  71             <para>
  72                 <literal>libraryinfo()</literal> works from the literal name of the library.
  73                 In some cases, we may have only its handle, defined when loading the library.
  74                 For instance, <literal>libraryinfo("iolib")</literal> works,
  75                 <literal>libraryinfo(iolib)</literal> does not.
  76                 How to use the handle to get any info? Let's go on with the <literal>iolib</literal>
  77                 example:
  78                 <itemizedlist>
  79                     <listitem>
  80                         <emphasis role="bold">Getting the path</emphasis>:
  81                         <literal>libpath = string(iolib)(1)</literal>
  82                     </listitem>
  83                     <listitem>
  84                         <emphasis role="bold">Getting the column vector of members functions</emphasis>:
  85                         <literal>functions = string(iolib)(2:$)</literal>
  86                     </listitem>
  87                     <listitem>
  88                         <emphasis role="bold">Getting the literal name of the library</emphasis>:
  89                         <literal>libraryname = xmlGetValues("//scilablib", "name", libpath)</literal>
  90                     </listitem>
  91                 </itemizedlist>
  92             </para>
  93         </refsect3>
  94         <refsect3>
  95             <title>Unloaded library: getting info through its path</title>
  96             <para>
  97                 If the considered library is not loaded, neither <literal>libraryinfo()</literal>
  98                 nor  <literal>string()</literal> can work.
  99             </para>
 100             <para>
 101                 Provided that we know its libpath, we then can
 102                 <itemizedlist>
 103                     <listitem>
 104                         <emphasis role="bold">get its literal name</emphasis>:
 105                         <literal>xmlGetValues("//scilablib", "name", libpath+"/lib")</literal>
 106                     </listitem>
 107                     <listitem>
 108                         <emphasis role="bold">get the column vector of members functions</emphasis>:
 109                         <literal>functions = xmlGetValues("//scilablib/macro", "name", libpath+"/lib")</literal>
 110                     </listitem>
 111                 </itemizedlist>
 112             </para>
 113         </refsect3>
 114     </refsection>
 115     <refsection>
 116         <title>Examples</title>
 117         <para>
 118             With libraryinfo(), from the literal library name:
 119         </para>
 120         <programlisting role="example"><![CDATA[
 121 [f, p] = libraryinfo("iolib")
 122      ]]></programlisting>
 123     <screen><![CDATA[
 124 --> [f, p] = libraryinfo("iolib")
 125  p  =
 126  SCI\modules\io\macros\
 127
 128  f  =
 129 !input      !
 130 !unix_g     !
 131 !unix_w     !
 132 !%_sodload  !
 133 !unix_x     !
 134 !unix_s     !
 135 ]]></screen>
 136         <para/>
 137         <para>
 138             From the library handle:
 139         </para>
 140         <programlisting role="example"><![CDATA[
 141 // Just for display:
 142 iolib
 143
 144 // Catch info into variables:
 145 p = string(iolib)(1)
 146 f = string(iolib)(2:$)
 147 libname = xmlGetValues("//scilablib", "name", p+"/lib")
 148      ]]></programlisting>
 149     <screen><![CDATA[
 150 --> // Just for display:
 151 --> iolib
 152
 153  iolib  =
 154 Functions files location : SCI\modules\io\macros\.
 155 input  unix_g  unix_w  %_sodload  unix_x  unix_s
 156
 157 --> // Catch info into variables:
 158 --> p = string(iolib)(1)
 159  p  =
 160  SCI\modules\io\macros\
 161
 162 --> f = string(iolib)(2:$)
 163  f  =
 164 !input      !
 165 !unix_g     !
 166 !unix_w     !
 167 !%_sodload  !
 168 !unix_x     !
 169 !unix_s     !
 170
 171 --> libname = xmlGetValues("//scilablib", "name", p+"/lib")
 172  libname  =
 173  iolib
 174 ]]></screen>
 175     <para/>
 176         <para>
 177             For a not-loaded library, from its path:
 178         </para>
 179         <programlisting role="example"><![CDATA[
 180 path = fullpath("SCI/modules/scicos_blocks/macros/Hydraulics");
 181 libname = xmlGetValues("//scilablib", "name", path+"/lib")
 182 functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
 183 Hydraulicslib  // not-loaded (Xcos must have not been run)
 184      ]]></programlisting>
 185     <screen><![CDATA[
 186 --> libname = xmlGetValues("//scilablib", "name", path+"/lib")
 187  libname  =
 188  Hydraulicslib
 189
 190 --> functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
 191  functions  =
 192 !Bache          !
 193 !Flowmeter      !
 194 !PerteDP        !
 195 !PuitsP         !
 196 !SourceP        !
 197 !VanneReglante  !
 198
 199 --> Hydraulicslib
 200 Undefined variable: Hydraulicslib
 201 ]]></screen>
 202     </refsection>
 203     <refsection role="see also">
 204         <title>See also</title>
 205         <simplelist type="inline">
 206             <member>
 207                 <link linkend="string">string</link>
 208             </member>
 209             <member>
 210                 <link linkend="load">load</link>
 211             </member>
 212             <member>
 213                 <link linkend="librarieslist">librarieslist</link>
 214             </member>
 215             <member>
 216                 <link linkend="whereis">whereis</link>
 217             </member>
 218         </simplelist>
 219     </refsection>
 220 </refentry>