ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-ant/proposal/myrmidon/src/xdocs vfs.xml
Date Sat, 02 Mar 2002 01:32:11 GMT
donaldp     02/03/01 17:32:11

  Added:       proposal/myrmidon/src/xdocs vfs.xml
  Log:
  Extract the VFS stuff from user.xml
  
  Revision  Changes    Path
  1.1                  jakarta-ant/proposal/myrmidon/src/xdocs/vfs.xml
  
  Index: vfs.xml
  ===================================================================
  <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>
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message