* Bug 15357 fixed: atomsGetInstalledPath() softer wrt name & version
[scilab.git] / scilab / modules / atoms / help / en_US / atomsGetInstalledPath.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) 2012 - Scilab Enterprises - Simon GARESTE <simon.gareste@scilab-enterprises.com>
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:ns4="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="atomsGetInstalledPath" xml:lang="en">
20     <refnamediv>
21         <refname>atomsGetInstalledPath</refname>
22         <refpurpose>Gets the install path of some installed external modules</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             paths = atomsGetInstalledPath(modules)
28             paths = atomsGetInstalledPath(modules, section)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>modules</term>
36                 <listitem>
37                     <para>m x 1, m x 2, or m x 3 Matrix of strings:</para>
38                     <informaltable border="1">
39                         <tr>
40                             <td>
41                                 <emphasis>1st Col.</emphasis>
42                             </td>
43                             <td>
44                                 <emphasis role="strong">Technical name</emphasis>
45                             </td>
46                             <td>
47                                 Mandatory
48                             </td>
49                             <td/>
50                         </tr>
51                         <tr>
52                             <td>
53                                 <emphasis>2nd Col.</emphasis>
54                             </td>
55                             <td>
56                                 <emphasis role="strong">Version</emphasis>
57                             </td>
58                             <td>
59                                 Optional
60                             </td>
61                             <td>
62                                 If this column is missing or this value is "", the first
63                                 (and possibly only installed) version found is considered.
64                             </td>
65                         </tr>
66                         <tr>
67                             <td>
68                                 <emphasis>3nd Col.</emphasis>
69                             </td>
70                             <td>
71                                 <emphasis role="strong">Section</emphasis>
72                             </td>
73                             <td>
74                                 Optional
75                             </td>
76                             <td>
77                                 If this column is missing or this value is "", the "all" section is
78                                 used. Possible values are "user", "allusers", and "all".
79                             </td>
80                         </tr>
81                     </informaltable>
82                 </listitem>
83             </varlistentry>
84             <varlistentry>
85                 <term>section</term>
86                 <para>single string among "user", "allusers", "all". It is used ony if
87                     <varname>modules</varname> has less than 3 columns. It is equivalent to
88                     <literal>modules(:,3)=section</literal>.
89                 </para>
90             </varlistentry>
91             <varlistentry>
92                 <term>paths</term>
93                 <para>
94                     the paths of the given modules (starting with SCI or SCIHOME),
95                     or "" for any unfound module, such that always size(paths,1)==size(modules,1).
96                 </para>
97             </varlistentry>
98         </variablelist>
99     </refsection>
100     <refsection>
101         <title>Description</title>
102         <para>
103             <literal>atomsGetInstalledPath</literal> returns the installation path of given
104             external modules, or "" for any unfound module.
105         </para>
106         <para>
107             If no module with the given exact case-sensitive technical name is found among installed
108             modules, the search is rerun in a case-insensitive way. If still no match is found, the
109             search is rerun in a case-insensitive way considering the provided technical name
110             as a fragment of the true name. In case of
111         </para>
112         <para>
113             If for a <literal>modules(i,:)</literal> several matches are found, only the first one
114             is considered.
115         </para>
116     </refsection>
117     <refsection>
118         <title>Examples</title>
119         <programlisting role="example"><![CDATA[
120 atomsInstall SCI/modules/atoms/tests/unit_tests/toolbox_7V6_1.0-1.bin.zip user
121
122 atomsGetInstalledPath toolbox_7V6       // exact name,                  no version
123 atomsGetInstalledPath ToolBox_7v6       // else: case-insensitive name, no version
124 atomsGetInstalledPath TOOLBOX_7         // else: fragment of name,      no version
125 atomsGetInstalledPath toolbox_7 allusers  // + wrong section => "" (not found)
126 atomsGetInstalledPath toolbox_7 all
127 atomsGetInstalledPath(["toolbox_7", "2"])   // not this version => "" (not found)
128 atomsGetInstalledPath(["toolbox_7", "1"])   // not this version => "" (not found)
129 atomsGetInstalledPath(["toolbox_7", "1.0"]) // version found
130
131 atomsRemove("toolbox_7V6");
132  ]]></programlisting>
133     </refsection>
134     <refsection role="see also">
135         <title>See also</title>
136         <simplelist type="inline">
137             <member>
138                 <link linkend="atomsGetLoadedPath">atomsGetLoadedPath</link>
139             </member>
140             <member>
141                 <link linkend="atomsGetLoaded">atomsGetLoaded</link>
142             </member>
143             <member>
144                 <link linkend="atomsGetInstalled">atomsGetInstalled</link>
145             </member>
146             <member>
147                 <link linkend="atomsAutoloadList">atomsAutoloadList</link>
148             </member>
149         </simplelist>
150     </refsection>
151     <refsection role="history">
152         <title>History</title>
153         <revhistory>
154             <revision>
155                 <revnumber>6.1.0</revnumber>
156                 <revdescription>
157                     <itemizedlist>
158                         <listitem>
159                             The technical name can now be case-insensitive, or a case-insensitive
160                             fragment of the full true technical name of each searched module.
161                         </listitem>
162                         <listitem>
163                             The version is now optional (use "" to accept any version).
164                         </listitem>
165                     </itemizedlist>
166                 </revdescription>
167             </revision>
168         </revhistory>
169     </refsection>
170 </refentry>