1653e781484966cf7a5533defa1a3b657645d422
[scilab.git] / scilab / modules / fileio / help / en_US / listfiles.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) 2008 - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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" 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="listfiles">
17     <refnamediv>
18         <refname>listfiles</refname>
19         <refpurpose>list of files</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>files = listfiles(paths [, flag, flagexpand])</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>paths</term>
30                 <listitem>
31                     <para>
32                         a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>flag, flagexpand</term>
38                 <listitem>
39                     <para>
40                         boolean optional parameters (default value is <constant>%t</constant>).
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>files</term>
46                 <listitem>
47                     <para>a string matrix.</para>
48                 </listitem>
49             </varlistentry>
50         </variablelist>
51     </refsection>
52     <refsection>
53         <title>Description</title>
54         <para>
55             <function>listfiles</function> can be used to list the files which match
56             the patterns given by one of the paths entries.
57             Patterns are given to the Unix <command>ls</command> or to the Windows
58             <command>dir</command> commands in order to get information about files.
59             Thus in order to write portable Scilab script valid wildcard patterns
60             for both OS are to be given. Note that pathname conversion is
61             performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
62             pattern for both Unix and Windows.
63         </para>
64         <para>
65             If <varname>flag</varname> is true the pathnames given by
66             <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
67             value (see also <link linkend="pathconvert">pathconvert</link>).
68             Moreover, if <varname>flagexpand</varname> is true leading strings like
69             <literal>SCIHOME</literal>, <literal>SCI</literal> or
70             <literal>~</literal> are expanded using environment variables.
71         </para>
72         <para>
73             If the input argument <varname>paths</varname> is the name of a directory, the returned <varname>files</varname>
74             are the names relative to that directory.
75         </para>
76         <para>
77             If the input argument <varname>paths</varname> contains more than one element, or if it contains
78             a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> are the absolute paths (i.e.
79             file name prepended with the name of the directory).
80         </para>
81     </refsection>
82     <refsection>
83         <title>Examples</title>
84         <programlisting role="example">
85             <![CDATA[
86 files=listfiles(['SCI/modules/core/macros/*.sci';'SCI/modules/core/macros/*.bin']);
87  ]]>
88         </programlisting>
89     </refsection>
90     <refsection>
91         <title>History</title>
92         <revhistory>
93             <revision>
94                 <revnumber>5.4.0</revnumber>
95                 <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
96             </revision>
97         </revhistory>
98     </refsection>
99     <refsection role="see also">
100         <title>See also</title>
101         <simplelist type="inline">
102             <member>
103                 <link linkend="findfiles">findfiles</link>
104             </member>
105             <member>
106                 <link linkend="basename">basename</link>
107             </member>
108             <member>
109                 <link linkend="pathconvert">pathconvert</link>
110             </member>
111         </simplelist>
112     </refsection>
113 </refentry>