[doc] libraryinfo() page overhauled
[scilab.git] / scilab / modules / functions / help / pt_BR / 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:ns3="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="libraryinfo" xml:lang="pt">
20     <refnamediv>
21         <refname>libraryinfo</refname>
22         <refpurpose>retorna macros e endereço de uma biblioteca Scilab
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Seqüência de Chamamento</title>
27         <synopsis>macros = libraryinfo(libraryname)
28             [macros,path] = libraryinfo(libraryname)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Parâmetros</title>
33         <variablelist>
34             <varlistentry>
35                 <term>libraryname</term>
36                 <listitem>
37                     <para>string (nome da biblioteca)</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>macros</term>
42                 <listitem>
43                     <para>uma matriz de strings (todas as funções principais da
44                         biblioteca)
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>path</term>
50                 <listitem>
51                     <para>um string (endereço da biblioteca)</para>
52                 </listitem>
53             </varlistentry>
54         </variablelist>
55     </refsection>
56     <refsection>
57         <title>Descrição</title>
58         <para>Retorna nomes de funções e o endereço de uma biblioteca Scilab. Os
59             nomes de funções são aqueles que correspondem aos nomes de arquivo
60             associados .sci ou .bin. Os outros são funções subsidiárias.
61             <warning>
62                 Only loaded libraries can be addressed by <literal>libraryinfo()</literal>.
63             </warning>
64         </para>
65         <refsect3>
66             <title>Getting some library info from its handle</title>
67             <para>
68                 <literal>libraryinfo()</literal> works from the literal name of the library.
69                 In some cases, we may have only its handle, defined when loading the library.
70                 For instance, <literal>libraryinfo("iolib")</literal> works,
71                 <literal>libraryinfo(iolib)</literal> does not.
72                 How to use the handle to get any info? Let's go on with the <literal>iolib</literal>
73                 example:
74                 <itemizedlist>
75                     <listitem>
76                         <emphasis role="bold">Getting the path</emphasis>:
77                         <literal>libpath = string(iolib)(1)</literal>
78                     </listitem>
79                     <listitem>
80                         <emphasis role="bold">Getting the column vector of members functions</emphasis>:
81                         <literal>functions = string(iolib)(2:$)</literal>
82                     </listitem>
83                     <listitem>
84                         <emphasis role="bold">Getting the literal name of the library</emphasis>:
85                         <literal>libraryname = xmlGetValues("//scilablib", "name", libpath)</literal>
86                     </listitem>
87                 </itemizedlist>
88             </para>
89         </refsect3>
90         <refsect3>
91             <title>Unloaded library: getting info through its path</title>
92             <para>
93                 If the considered library is not loaded, neither <literal>libraryinfo()</literal>
94                 nor  <literal>string()</literal> can work.
95             </para>
96             <para>
97                 Provided that we know its libpath, we then can
98                 <itemizedlist>
99                     <listitem>
100                         <emphasis role="bold">get its literal name</emphasis>:
101                         <literal>xmlGetValues("//scilablib", "name", libpath+"/lib")</literal>
102                     </listitem>
103                     <listitem>
104                         <emphasis role="bold">get the column vector of members functions</emphasis>:
105                         <literal>functions = xmlGetValues("//scilablib/macro", "name", libpath+"/lib")</literal>
106                     </listitem>
107                 </itemizedlist>
108             </para>
109         </refsect3>
110     </refsection>
111     <refsection>
112         <title>Exemplos</title>
113         <para>
114             With libraryinfo(), from the literal library name:
115         </para>
116         <programlisting role="example"><![CDATA[
117 [f, p] = libraryinfo("iolib")
118      ]]></programlisting>
119     <screen><![CDATA[
120 --> [f, p] = libraryinfo("iolib")
121  p  =
122  SCI\modules\io\macros\
123
124  f  =
125 !input      !
126 !unix_g     !
127 !unix_w     !
128 !%_sodload  !
129 !unix_x     !
130 !unix_s     !
131 ]]></screen>
132         <para/>
133         <para>
134             From the library handle:
135         </para>
136         <programlisting role="example"><![CDATA[
137 // Just for display:
138 iolib
139
140 // Catch info into variables:
141 p = string(iolib)(1)
142 f = string(iolib)(2:$)
143 libname = xmlGetValues("//scilablib", "name", p+"/lib")
144      ]]></programlisting>
145     <screen><![CDATA[
146 --> // Just for display:
147 --> iolib
148
149  iolib  =
150 Functions files location : SCI\modules\io\macros\.
151 input  unix_g  unix_w  %_sodload  unix_x  unix_s
152
153 --> // Catch info into variables:
154 --> p = string(iolib)(1)
155  p  =
156  SCI\modules\io\macros\
157
158 --> f = string(iolib)(2:$)
159  f  =
160 !input      !
161 !unix_g     !
162 !unix_w     !
163 !%_sodload  !
164 !unix_x     !
165 !unix_s     !
166
167 --> libname = xmlGetValues("//scilablib", "name", p+"/lib")
168  libname  =
169  iolib
170 ]]></screen>
171     <para/>
172         <para>
173             For a not-loaded library, from its path:
174         </para>
175         <programlisting role="example"><![CDATA[
176 path = fullpath("SCI/modules/scicos_blocks/macros/Hydraulics");
177 libname = xmlGetValues("//scilablib", "name", path+"/lib")
178 functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
179 Hydraulicslib  // not-loaded (Xcos must have not been run)
180      ]]></programlisting>
181     <screen><![CDATA[
182 --> libname = xmlGetValues("//scilablib", "name", path+"/lib")
183  libname  =
184  Hydraulicslib
185
186 --> functions = xmlGetValues("//scilablib/macro", "name", path+"/lib")
187  functions  =
188 !Bache          !
189 !Flowmeter      !
190 !PerteDP        !
191 !PuitsP         !
192 !SourceP        !
193 !VanneReglante  !
194
195 --> Hydraulicslib
196 Undefined variable: Hydraulicslib
197 ]]></screen>
198     </refsection>
199     <refsection role="see also">
200         <title>Ver Também</title>
201         <simplelist type="inline">
202             <member>
203                 <link linkend="string">string</link>
204             </member>
205             <member>
206                 <link linkend="load">load</link>
207             </member>
208             <member>
209                 <link linkend="librarieslist">librarieslist</link>
210             </member>
211             <member>
212                 <link linkend="whereis">whereis</link>
213             </member>
214         </simplelist>
215     </refsection>
216 </refentry>