6d12f7d0362e459272eee5396b8102cc8fe31691
[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  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="listfiles">
14   <refnamediv>
15     <refname>listfiles</refname>
16     <refpurpose>list of files</refpurpose>
17   </refnamediv>
18   <refsynopsisdiv>
19     <title>Calling Sequence</title>
20     <synopsis>files = listfiles(paths [,flag,flagexpand])</synopsis>
21   </refsynopsisdiv>
22   <refsection>
23     <title>Arguments</title>
24     <variablelist>
25       <varlistentry>
26         <term>paths</term>
27         <listitem>
28           <para>
29             a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
30           </para>
31         </listitem>
32       </varlistentry>
33       <varlistentry>
34         <term>flag, flagexpand</term>
35         <listitem>
36           <para>
37             boolean optional parameters (default value is <constant>%t</constant>).
38           </para>
39         </listitem>
40       </varlistentry>
41       <varlistentry>
42         <term>files</term>
43         <listitem>
44           <para>a string matrix.</para>
45         </listitem>
46       </varlistentry>
47     </variablelist>
48   </refsection>
49   <refsection>
50     <title>Description</title>
51     <para>
52       <function>listfiles</function> can be used to list the files which match
53       the patterns given by one of the paths entries.
54       Patterns are given to the Unix <command>ls</command> or to the Windows
55       <command>dir</command> commands in order to get information about files.
56       Thus in order to write portable Scilab script valid wildcard patterns
57       for both OS are to be given. Note that pathname conversion is
58       performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
59       pattern for both Unix and Windows.
60     </para>
61     <para>
62       If <varname>flag</varname> is true the pathnames given by
63       <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
64       value (see also <link linkend="pathconvert">pathconvert</link>).
65       Moreover, if <varname>flagexpand</varname> is true leading strings like
66       <varname>SCIHOME</varname>, <varname>SCI</varname> or
67       <literal>~</literal> are expanded using environment variables.
68     </para>
69     <para>
70       If the input path is the name of a directory, the returned 
71       <varname>files</varname> names are the
72       relative to that directory.
73     </para>
74     <para>
75       If the input path contains a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> names
76       are prepended with the input path.
77     </para>
78   </refsection>
79   <refsection>
80     <title>Examples</title>
81     <programlisting role="example">
82       <![CDATA[
83 files=listfiles(['SCI/modules/core/macros/*.sci';'SCI/modules/core/macros/*.bin']);
84  ]]>
85     </programlisting>
86   </refsection>
87   <refsection>
88     <title>History</title>
89     <revhistory>
90       <revision>
91         <revnumber>5.4.0</revnumber>
92         <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
93       </revision>
94     </revhistory>
95   </refsection>
96   <refsection role="see also">
97     <title>See Also</title>
98     <simplelist type="inline">
99       <member>
100         <link linkend="findfiles">findfiles</link>
101       </member>
102       <member>
103         <link linkend="basename">basename</link>
104       </member>
105       <member>
106         <link linkend="pathconvert">pathconvert</link>
107       </member>
108     </simplelist>
109   </refsection>
110 </refentry>