Extract the VFS stuff from user.xml

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271653 13f79535-47bb-0310-9956-ffa450edef68
23 years ago · 422e474a6d
--- a/proposal/myrmidon/src/xdocs/user.xml
+++ b/proposal/myrmidon/src/xdocs/user.xml
@@ -308,199 +308,6 @@ attributes:</p>

 </section>

 <section name="Handling Files">

 <p>Myrmidon includes a Virtual File System (VFS), which allows files from
 different sources to be treated identically.  The VFS currently supports
 the following file types:</p>

 <table>
    <tr><th>File System</th><th>Description</th><th>URL Format</th></tr>
    <tr>
        <td>Local Files</td>
        <td>Files on the local file system.</td>
        <td>Three different formats are currently supported for local file names:
            <ul>
                <li><code>file://</code> <i>absolute-file-name</i></li>
                <li>Absolute file names</li>
                <li>Relative file names.  These are resolved relative to the
                project's base directory.
                </li>
            </ul>
        </td>
    </tr>
    <tr>
        <td>Zip Files</td>
        <td>The contents of Zip files (and Jar, War, and Ear files).
        Currently, the VFS supports read-only access to Zip file contents,
        and only for local Zip files.</td>
        <td><code>zip://</code> <i>zip-file-path</i> [<code>!</code><i>absolute-path</i>]</td>
    </tr>
    <tr>
        <td>FTP</td>
        <td>Files on an FTP server.</td>
        <td><code>ftp://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
    </tr>
    <tr>
        <td>SMB</td>
        <td>Files on a CFIS server, such as Samba or Windows shares.</td>
        <td><code>smb://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
    </tr>
 </table>

 <p>Here are some example URLs:</p>

 <ul>
    <li><code>build/classes</code></li>
    <li><code>c:\program files\ant\bin</code></li>
    <li><code>file://C:/program files/ant</code></li>
    <li><code>zip://build/lib/ant.jar!/org/apache/tools</code></li>
    <li><code>ftp://adam@somehost/pub/downloads</code></li>
    <li><code>smb://password:adam@somehost/home/adam</code></li>
 </ul>

 <p>Currently, there are only a handful of VFS aware tasks.  This will grow
 as more tasks are ported to the new API, and data types.</p>

 <subsection name="File Sets">

 <p>A file set in Myrmidon is more general than Ant 1's concept of a file set.
 Firstly, there is more than one type of file set.  Secondly, they are VFS enabled.
 File sets are automatically converted to a <a href="#Paths">path</a>, and so
 can be used anywhere that a path can.</p>

 <h3><code>&lt;v-fileset&gt;</code></h3>

 <p>This is the equivalent of Ant 1's <code>&lt;fileset&gt;</code> (The name
 is temporary, it will be changed to <code>&lt;fileset&gt;</code> once more
 porting work as been completed).</p>

 <p>Rather than use a set of include and exclude patterns to choose the files
 that make up the file set, <code>&lt;v-fileset&gt;</code> takes zero or more
 <a href="#File Selectors">file selectors</a>.  File selectors can be used to
 select files based on any attribute of the file, rather than just the name.
 You can use <code>&lt;name&gt;</code> selectors to achieve the same result
 as using includes or excludes.</p>

 <p>A <code>&lt;v-fileset&gt;</code> element takes the following attributes:</p>

 <table>
    <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
    <tr>
        <td>dir</td>
        <td>The base directory for the file set.  This can be any URL that the
        VFS supports.</td>
        <td>Required</td>
    </tr>
 </table>

 <p>A <code>&lt;v-fileset&gt;</code> element takes any number of nested
 <a href="#File Selectors">file selector</a> elements.  To be included in the
 file set, a file must be selected by all the file selectors.  That is, the
 file selectors are implicitly AND-ed together.  If no file selector is provided,
 all the files and directories are included in the set.</p>

 <p>An example:</p>

 <source><![CDATA[

 <v-fileset dir="src">
    <name pattern="org/apache/tools/ant/**"/>
    <is-file/>
 </v-fileset>
 ]]></source>

 <h3><code>&lt;flat-fileset&gt;</code></h3>

 <p>This file set takes a set of nested file sets and paths, and flattens them
 into a single directory.  It can be used as a way of converting a path into a
 file set.  It can also be used as a replacement for the <code>flatten</code>
 attribute for the copy and move tasks.</p>

 <p>A <code>&lt;flat-fileset&gt;</code> element takes no attributes, and a set
 of nested paths or file sets.</p>

 <p>An example:</p>

 <source><![CDATA[

 <v-copy todir="dist/lib">
  <flat-fileset>
    <v-fileset dir="build/lib">
        <basename pattern="*.jar"/>
    <v-fileset>
    <v-path path="${classpath}"/>
  </flat-fileset>
 </v-copy>
 ]]></source>

 </subsection>

 <subsection name="Paths">

 <p>Paths are an ordered list of files.</p>

 <h3><code>&lt;v-path&gt;</code></h3>

 <p>This is the equivalent of Ant 1's <code>&lt;path&gt;</code>.</p>

 <h3><code>&lt;filtered-path&gt;</code></h3>

 <p>A path that applies file selectors to a set of nested file sets and paths.</p>

 </subsection>

 <subsection name="File Selectors">

 <p>File selectors are used to select files from file sets and paths.</p>

 <h3><code>&lt;and&gt;</code></h3>

 <p>Combines zero or more file selectors, using AND. An empty <code>&lt;and&gt;</code>
 selector accepts all files.</p>

 <h3><code>&lt;basename&gt;</code></h3>

 <p>Selects files whose base name matches an Ant 1 style pattern, or a regular
 expression.</p>

 <h3><code>&lt;exists&gt;</code></h3>

 <p>Selects files that exist.</p>

 <h3><code>&lt;is-empty&gt;</code></h3>

 <p>Selects empty folders, that is, folders that have no children.</p>

 <h3><code>&lt;is-folder&gt;</code></h3>

 <p>Selects folders, does not select regular files.</p>

 <h3><code>&lt;is-file&gt;</code></h3>

 <p>Selects regular files, does not select folders.</p>

 <h3><code>&lt;name&gt;</code></h3>

 <p>Selects files whose path in a file set matches an Ant 1 style pattern, or
 a regular expression.</p>

 <h3><code>&lt;not&gt;</code></h3>

 <p>Selects files that are not selected by a nested file selector.</p>

 <h3><code>&lt;or&gt;</code></h3>

 <p>Combines zero or more file selectors, using OR. An empty <code>&lt;or&gt;</code>
 selector accepts all files.</p>

 <h3><code>&lt;url&gt;</code></h3>

 <p>Selects files whose URL matches an Ant 1 style pattern, or a regular expression.</p>

 </subsection>

 </section>
 <section name="Tasks">

 <p>
--- a/proposal/myrmidon/src/xdocs/vfs.xml
+++ b/proposal/myrmidon/src/xdocs/vfs.xml
@@ -0,0 +1,205 @@
 <document>

    <properties>
        <author email="adammurdoch@apache.org">Adam Murdoch</author>
        <title>VFS User Guide</title>
    </properties>

    <body>

        <section name="Handling Files">

            <p>Myrmidon includes a Virtual File System (VFS), which allows files from
            different sources to be treated identically.  The VFS currently supports
            the following file types:</p>

            <table>
                <tr><th>File System</th><th>Description</th><th>URL Format</th></tr>
                <tr>
                    <td>Local Files</td>
                    <td>Files on the local file system.</td>
                    <td>Three different formats are currently supported for local file names:
                        <ul>
                            <li><code>file://</code> <i>absolute-file-name</i></li>
                            <li>Absolute file names</li>
                            <li>Relative file names.  These are resolved relative to the
                            project's base directory.
                            </li>
                        </ul>
                    </td>
                </tr>
                <tr>
                    <td>Zip Files</td>
                    <td>The contents of Zip files (and Jar, War, and Ear files).
                    Currently, the VFS supports read-only access to Zip file contents,
                    and only for local Zip files.</td>
                    <td><code>zip://</code> <i>zip-file-path</i> [<code>!</code><i>absolute-path</i>]</td>
                </tr>
                <tr>
                    <td>FTP</td>
                    <td>Files on an FTP server.</td>
                    <td><code>ftp://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
                </tr>
                <tr>
                    <td>SMB</td>
                    <td>Files on a CFIS server, such as Samba or Windows shares.</td>
                    <td><code>smb://</code> [[<i>password</i><code>:</code>] <i>username</i><code>@</code>] <i>hostname</i> [<code>:</code><i>port</i>] [<i>absolute-path</i>]</td>
                </tr>
            </table>

            <p>Here are some example URLs:</p>

            <ul>
                <li><code>build/classes</code></li>
                <li><code>c:\program files\ant\bin</code></li>
                <li><code>file://C:/program files/ant</code></li>
                <li><code>zip://build/lib/ant.jar!/org/apache/tools</code></li>
                <li><code>ftp://adam@somehost/pub/downloads</code></li>
                <li><code>smb://password:adam@somehost/home/adam</code></li>
            </ul>

            <p>Currently, there are only a handful of VFS aware tasks.  This will grow
            as more tasks are ported to the new API, and data types.</p>

            <subsection name="File Sets">

                <p>A file set in Myrmidon is more general than Ant 1's concept of a file set.
                Firstly, there is more than one type of file set.  Secondly, they are VFS enabled.
                File sets are automatically converted to a <a href="#Paths">path</a>, and so
                can be used anywhere that a path can.</p>

                <h3><code>&lt;v-fileset&gt;</code></h3>

                <p>This is the equivalent of Ant 1's <code>&lt;fileset&gt;</code> (The name
                is temporary, it will be changed to <code>&lt;fileset&gt;</code> once more
                porting work as been completed).</p>

                <p>Rather than use a set of include and exclude patterns to choose the files
                that make up the file set, <code>&lt;v-fileset&gt;</code> takes zero or more
                <a href="#File Selectors">file selectors</a>.  File selectors can be used to
                select files based on any attribute of the file, rather than just the name.
                You can use <code>&lt;name&gt;</code> selectors to achieve the same result
                as using includes or excludes.</p>

                <p>A <code>&lt;v-fileset&gt;</code> element takes the following attributes:</p>

                <table>
                    <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
                    <tr>
                        <td>dir</td>
                        <td>The base directory for the file set.  This can be any URL that the
                        VFS supports.</td>
                        <td>Required</td>
                    </tr>
                </table>

                <p>A <code>&lt;v-fileset&gt;</code> element takes any number of nested
                <a href="#File Selectors">file selector</a> elements.  To be included in the
                file set, a file must be selected by all the file selectors.  That is, the
                file selectors are implicitly AND-ed together.  If no file selector is provided,
                all the files and directories are included in the set.</p>

                <p>An example:</p>

                <source><![CDATA[

                <v-fileset dir="src">
                    <name pattern="org/apache/tools/ant/**"/>
                    <is-file/>
                </v-fileset>
                ]]></source>

                <h3><code>&lt;flat-fileset&gt;</code></h3>

                <p>This file set takes a set of nested file sets and paths, and flattens them
                into a single directory.  It can be used as a way of converting a path into a
                file set.  It can also be used as a replacement for the <code>flatten</code>
                attribute for the copy and move tasks.</p>

                <p>A <code>&lt;flat-fileset&gt;</code> element takes no attributes, and a set
                of nested paths or file sets.</p>

                <p>An example:</p>

                <source><![CDATA[

 <v-copy todir="dist/lib">
  <flat-fileset>
    <v-fileset dir="build/lib">
      <basename pattern="*.jar"/>
    <v-fileset>
    <v-path path="${classpath}"/>
  </flat-fileset>
 </v-copy>
 ]]></source>

            </subsection>

            <subsection name="Paths">

                <p>Paths are an ordered list of files.</p>

                <h3><code>&lt;v-path&gt;</code></h3>

                <p>This is the equivalent of Ant 1's <code>&lt;path&gt;</code>.</p>

                <h3><code>&lt;filtered-path&gt;</code></h3>

                <p>A path that applies file selectors to a set of nested file sets and paths.</p>

            </subsection>

            <subsection name="File Selectors">

                <p>File selectors are used to select files from file sets and paths.</p>

                <h3><code>&lt;and&gt;</code></h3>

                <p>Combines zero or more file selectors, using AND. An empty <code>&lt;and&gt;</code>
                selector accepts all files.</p>

                <h3><code>&lt;basename&gt;</code></h3>

                <p>Selects files whose base name matches an Ant 1 style pattern, or a regular
                expression.</p>

                <h3><code>&lt;exists&gt;</code></h3>

                <p>Selects files that exist.</p>

                <h3><code>&lt;is-empty&gt;</code></h3>

                <p>Selects empty folders, that is, folders that have no children.</p>

                <h3><code>&lt;is-folder&gt;</code></h3>

                <p>Selects folders, does not select regular files.</p>

                <h3><code>&lt;is-file&gt;</code></h3>

                <p>Selects regular files, does not select folders.</p>

                <h3><code>&lt;name&gt;</code></h3>

                <p>Selects files whose path in a file set matches an Ant 1 style pattern, or
                a regular expression.</p>

                <h3><code>&lt;not&gt;</code></h3>

                <p>Selects files that are not selected by a nested file selector.</p>

                <h3><code>&lt;or&gt;</code></h3>

                <p>Combines zero or more file selectors, using OR. An empty <code>&lt;or&gt;</code>
                selector accepts all files.</p>

                <h3><code>&lt;url&gt;</code></h3>

                <p>Selects files whose URL matches an Ant 1 style pattern, or a regular expression.</p>

            </subsection>

        </section>
    </body>

 </document>