d686637f4544d43fa052d5f052c29e81c8ff184a
[scilab.git] / 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>