828603e44764bc51dd3322db2c67d03fe52bbd33
[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 argument <varname>paths</varname> is the name of a directory, the returned <varname>files</varname>
71             are the names relative to that directory.
72         </para>
73         <para>
74             If the input argument <varname>paths</varname> contains more than one element, or if it contains
75             a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> are the absolute paths (i.e.
76             file name prepended with the name of the directory).
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>