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="[EMAIL PROTECTED]">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://[EMAIL PROTECTED]/pub/downloads</code></li>
<li><code>smb://password:[EMAIL
PROTECTED]/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><v-fileset></code></h3>
<p>This is the equivalent of Ant 1's
<code><fileset></code> (The name
is temporary, it will be changed to
<code><fileset></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><v-fileset></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><name></code> selectors to achieve
the same result
as using includes or excludes.</p>
<p>A <code><v-fileset></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><v-fileset></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><flat-fileset></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><flat-fileset></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><v-path></code></h3>
<p>This is the equivalent of Ant 1's
<code><path></code>.</p>
<h3><code><filtered-path></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><and></code></h3>
<p>Combines zero or more file selectors, using AND. An empty
<code><and></code>
selector accepts all files.</p>
<h3><code><basename></code></h3>
<p>Selects files whose base name matches an Ant 1 style
pattern, or a regular
expression.</p>
<h3><code><exists></code></h3>
<p>Selects files that exist.</p>
<h3><code><is-empty></code></h3>
<p>Selects empty folders, that is, folders that have no
children.</p>
<h3><code><is-folder></code></h3>
<p>Selects folders, does not select regular files.</p>
<h3><code><is-file></code></h3>
<p>Selects regular files, does not select folders.</p>
<h3><code><name></code></h3>
<p>Selects files whose path in a file set matches an Ant 1
style pattern, or
a regular expression.</p>
<h3><code><not></code></h3>
<p>Selects files that are not selected by a nested file
selector.</p>
<h3><code><or></code></h3>
<p>Combines zero or more file selectors, using OR. An empty
<code><or></code>
selector accepts all files.</p>
<h3><code><url></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:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
