<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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">
    <refnamediv>
        <refname>listfiles</refname>
        <refpurpose>list of files</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>files = listfiles(paths [, flag, flagexpand])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>paths</term>
                <listitem>
                    <para>
                        a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag, flagexpand</term>
                <listitem>
                    <para>
                        boolean optional parameters (default value is <constant>%t</constant>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>files</term>
                <listitem>
                    <para>a string matrix.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <function>listfiles</function> can be used to list the files which match
            the patterns given by one of the paths entries.
            Patterns are given to the Unix <command>ls</command> or to the Windows
            <command>dir</command> commands in order to get information about files.
            Thus in order to write portable Scilab script valid wildcard patterns
            for both OS are to be given. Note that pathname conversion is
            performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
            pattern for both Unix and Windows.
        </para>
        <para>
            If <varname>flag</varname> is true the pathnames given by
            <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
            value (see also <link linkend="pathconvert">pathconvert</link>).
            Moreover, if <varname>flagexpand</varname> is true leading strings like
            <literal>SCIHOME</literal>, <literal>SCI</literal> or
            <literal>~</literal> are expanded using environment variables.
        </para>
        <para>
            If the input argument <varname>paths</varname> is the name of a directory, the returned <varname>files</varname>
            are the names relative to that directory.
        </para>
        <para>
            If the input argument <varname>paths</varname> contains more than one element, or if it contains
            a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> are the absolute paths (i.e.
            file name prepended with the name of the directory).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example">
            <![CDATA[
files=listfiles(['SCI/modules/core/macros/*.sci';'SCI/modules/core/macros/*.bin']);
 ]]>
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="findfiles">findfiles</link>
            </member>
            <member>
                <link linkend="basename">basename</link>
            </member>
            <member>
                <link linkend="pathconvert">pathconvert</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
            </revision>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revremark>
                    Under Windows, up to 6.0.1, <literal>listfile("test")</literal> actually
                    performed <literal>listfile("test.*")</literal>. It is no longer the case.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
