| Fileset | |
A fileset is a group of files. The files included in the fileset are defined through a directory representing the start point in a filesystem and patterns describing which files in or underneath that directory should be included in the fileset respectively excluded from the fileset. As a fileset is not a task but a general element it cannot be used on its own. It can only be used by tasks supporting filesets as nested element.
By default all files with names matching the inclusion criteria and not matching the exclusion criteria are included in the fileset. From the matched filenames a list of filename pairs is constructed. Each entry in the list consists of the 'filename' and a 'mapped_filename': ['filename', 'mapped_filename']. When this element does not contain a nested 'map' element 'filename' and 'mapped_filename' are the same. If it contains a map 'mapped_filename' is constructed by passing 'filename' to the 'map' element which will construct a 'mapped_filename' based on the type of map.
Example: Say file 'a.ge' matches the filesets criteria. When the fileset does not contain a nested 'map' element its list will contain one entry ['a.ge', 'a.ge']. However if it contains a nested map element of type 'glob' mapping '*.ge' to '*.e' then the entry will be ['a.ge', 'a.e'].
Filesets are used in combination with other tasks. Tasks 'copy', 'delete', 'move', 'exec' and 'geant' are tasks making use of filesets as nested elements. Some of these tasks like 'copy' are very specific in what they do and others like 'exec' or 'geant' are very general.
If we look at 'copy' for example in most situation we only want to copy the files in the fileset if the target files ('mapped_filename': 'a.e') are older than their corresponding source files ('filename': 'a.ge'). Therefore the 'copy' task checks whether it is necessary to copy the file or not.
The general task 'exec' does not know what the value of it's attribute 'executable' contains. Say it invokes some commandline tool taking the filenames included in the fileset and generates some other files from them. But what if we want to generate only those files necessary? Then we need the intlligence which is built in into task copy in the 'fileset' element itself (it cannot be built into task 'exec' since it is too general). The 'fileset' element provides an attribute 'force' which you can set to 'false'. If that is the case only filenames are included where the source file is newer than the target file.
Since the fileset itself is able to perform these checks (when attribute 'force' is set to 'false') it can be a bit confusing when it is used in combination with a specific task. You could for example use a 'fileset' element having set attribute 'force' to false inside a 'copy' task. As already described this is not necessary and not recommended since the 'copy' task checks itself whether it is necessary to copy the file or not. Since a fileset is used within such specific tasks this is also the reason why the default value for attribute 'force' is 'true'.
The comparison works as follows: For a filename pair [filename, mapped_filename] (e.g. ['a.ge', 'a.ge']) the file named 'filename' is compared to the file named 'mapped_filename'. If the file named 'filename' for example is newer than the file named 'mapped_filename' or the file named 'mapped_filename' does not exist at all the filename pair is added to the fileset. Note that the comparison is is looking for files related to the current working directory. Use fileset's attribute 'dir' if you have to change the current working directory for the time constructing the fileset.
Note again that setting the attribute 'force' to 'true' or not specifying it at all turns the checking off so that for each matched filename a filename pair ['filename', 'mapped_filename'] is added to the fileset.
Domain: Valid LX DFA Wildcard (see below)
Default: -
Domain: Valid LX DFA Wildcard (see below)
Default: -
Domain: Boolean (true|false)
Default: true
Domain: Valid directoryname
Default: -
Domain: Valid directoryname
Default: -
Domain: Valid filename pointing to existing file
Default: -
Domain: Valid filename
Default: -
Domain: Valid map element
Default: -
<define name="fileset">
<element name="fileset">
<ref name="dir_if_unless"/>
<attribute name="include"/>
<optional>
<attribute name="exclude"/>
</optional>
<optional>
<attribute name="force">
<!-- runtime evaluation
<choice>
<value>true</value>
<value>false</value>
</choice>
-->
</attribute>
</optional>
<optional>
<attribute name="filename_directory"/>
</optional>
<optional>
<attribute name="mapped_filename_directory"/>
</optional>
<zeroOrMore>
<element name="include">
<attribute name="name"/>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="exclude">
<attribute name="name"/>
</element>
</zeroOrMore>
<optional>
<ref name="map"/>
</optional>
</element>
</define>
<fileset include="@(**/*.ge|**/*.?ace)"/>
<fileset dir="kernel" include="@(**/*.ge|**/*.?ace)"/>
<fileset include="@(**/*.ge|**/*.?ace)" mapped_filename_directory="kernel"/>
<fileset include="@(**/*.ge)">
<map type="glob" from="*.ge" to="*.e"/>
</fileset>
<fileset include="@(**/*.ge)" force="false">
<map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e">
<map type="flat"/>
</map>
</fileset>
To specify the attributes `include' and `exclude' you have to use special wildcard expressions which are very close to the wildcards used by Linux' bash. In addition it provides the means to match filenames in any directory depth by using the '**' wildcard.
Here is the pattern syntax of LX DFA Wildcards (implemented in GOBO's class LX_DFA_WILDCARD):
x match the character 'x'.
? any character except '/'.
* zero or more occurrences of any character except '/'.
**/ zero or more occurrences of (one or more characters other
than '/', followed by '/').
\X if 'X' is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', then
the ANSI-C interpretation of \X. Otherwise, a literal 'X'
(used to escape operators such as '*').
\0 a null character (ASCII code 0).
\123 the character with octal value 123.
\x2a the character with hexadecimal value 2a.
[xyz] a character class; in this case, the pattern matches
either an 'x', a 'y' or a 'z'.
[abj-oZ] a character class with a range in it; matches an 'a', a
'b', any letter from 'j' through 'o', or a 'Z'.
[^A-Z] a negated character class, i.e., any character but those
in the class. In this case, any character except an
uppercase letter.
[^A-Z\n] any character except an uppercase letter or a newline.
wv the wildcard w followed by the wildcard v; called
concatenation.
%"[xyz]\%"foo%" the literal string: '[xyz]%"foo'.
?(pattern-list) zero or one occurrence of the given patterns.
*(pattern-list) zero or more occurrences of the given patterns.
+(pattern-list) one or more occurrences of the given patterns.
@(pattern-list) exactly one of the given patterns.
where pattern-list is a list of one or more
patterns separated by a '|'.
To alleviate the migration of the former fileset format to the current one the following list describes the old format.
Domain: Valid directoryname
Default: -
Domain: Valid LX DFA Wildcard (see below)
Default: -
Domain: Valid LX DFA Wildcard (see below)
Default: -
Domain: Boolean (true|false)
Default: true
Domain: Boolean (true|false)
Default: false
Domain: Valid filename pointing to existing file
Default: -
Domain: Valid filename
Default: -
Domain: Valid map element
Default: -
<define name="fileset">
<element name="fileset">
<attribute name="directory"/>
<attribute name="include"/>
<optional>
<attribute name="exclude"/>
</optional>
<optional>
<attribute name="force">
<!-- runtime evaluation
<choice>
<value>true</value>
<value>false</value>
</choice>
-->
</attribute>
</optional>
<optional>
<attribute name="filename_directory"/>
</optional>
<optional>
<attribute name="concat"/>
</optional>
<zeroOrMore>
<element name="include">
<attribute name="name"/>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="exclude">
<attribute name="name"/>
</element>
</zeroOrMore>
<optional>
<ref name="map"/>
</optional>
</element>
</define>
|
Copyright © 2002-2005, Sven Ehrke mailto:ericb@gobosoft.com http://www.gobosoft.com Last Updated: 7 July 2005 |
  |