2002-2005
Sven Ehrke
Sven
Ehrke
ericb@gobosoft.com 7 July 2005

# Fileset

## Description

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.

## Details

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: 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.

## Parameters

include

  Description: Pattern for names of files to be included in fileset

  Domain: Valid LX DFA Wildcard (see below)

  Default: -

exclude

  Description: Pattern for names of files to be excluded from fileset

  Domain: Valid LX DFA Wildcard (see below)

  Default: -

force

  Description: Include matched filenames even when the matched file is not out of date. See section 'Details' for more information.

  Domain: Boolean (true|false)

  Default: true

filename_directory

  Description: Prepend value of this attribute before determined `filename' which is used for the entry in the fileset (['filename', 'mapped_filename']).

  Domain: Valid directoryname

  Default: -

mapped_filename_directory

  Description: Prepend value of this attribute before determined `mapped_filename' which is used for the entry in the fileset (['filename', 'mapped_filename']).

  Domain: Valid directoryname

  Default: -

## Parameters specified as nested elements

include

  Description: Name of individual file to be included in fileset

  Domain: Valid filename pointing to existing file

  Default: -

exclude

  Description: Name of individual file to be excluded from fileset

  Domain: Valid filename

  Default: -

map

  Description: Map element used to determine 'mapped_filename'. See section 'Details' for more information.

  Domain: Valid map element

  Default: -

## RNG Specification

      <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>

## Examples

      <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>

## LX DFA Wildcards

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 '|'.

## Obsolete (GOBO 3.1) Fileset format

To alleviate the migration of the former fileset format to the current one the following list describes the old format.

## Parameters

directory

  Description: The directory taken as root to find files matching the given criteria `include' and `exclude'

  Domain: Valid directoryname

  Default: -

include

  Description: Pattern for names of files to be included in fileset

  Domain: Valid LX DFA Wildcard (see below)

  Default: -

exclude

  Description: Pattern for names of files to be excluded from fileset

  Domain: Valid LX DFA Wildcard (see below)

  Default: -

force

  Description: Include matched filenames even when the matched file is not out of date.

  Domain: Boolean (true|false)

  Default: true

concat

  Description: Prepend value of attribute `directory' before determined `mapped_filename'

  Domain: Boolean (true|false)

  Default: false

## Parameters specified as nested elements

include

  Description: Name of individual file to be included in fileset

  Domain: Valid filename pointing to existing file

  Default: -

exclude

  Description: Name of individual file to be excluded from fileset

  Domain: Valid filename

  Default: -

map

  Description: Map element used to determine 'mapped_filename'. See section 'Detailes' for more information.

  Domain: Valid map element

  Default: -

## Obsolete (GOBO 3.1) RNG Specification

      <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>