
<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="fileset_element">
<chapterinfo>
	<copyright>
		<year>2002-2005</year>
		<holder>Sven Ehrke</holder>
	</copyright>
	<author>
		<firstname>Sven</firstname><surname>Ehrke</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>7 July 2005</date>
</chapterinfo>

<title>Fileset</title>

<section id="fileset_description">
<title>Description</title>
<para>
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.
</para>
</section>

<section id="fileset_detailes">
<title>Details</title>
<para>
	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.
</para>
<para>
	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'].
</para>
<para>
	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.
</para>
<para>
	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.
</para>
<para>
	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.
</para>
<para>
	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'.
</para>
<para>
	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.
</para>
<para>
	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.
</para>

</section>

	<section id="fileset_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>include</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Pattern for names of files to be included in fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid LX DFA Wildcard (see below)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>exclude</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Pattern for names of files to be excluded from fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid LX DFA Wildcard (see below)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>force</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Include matched filenames even when the
						matched file is not out of date. See section 'Details' for
						more information.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>true</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>filename_directory</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Prepend value of this attribute
					before determined `filename' which is used for the entry in the
					fileset (['filename', 'mapped_filename']).
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid directoryname</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>mapped_filename_directory</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Prepend value of this attribute
					before determined `mapped_filename' which is used for the entry in the
					fileset (['filename', 'mapped_filename']).
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid directoryname</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</section>

	<section id="fileset_nested_parameters">
		<title>Parameters specified as nested elements</title>

		<variablelist>
			<varlistentry>
				<term>include</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of individual file to be included in fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>exclude</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of individual file to be excluded from fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>map</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Map element used to determine 'mapped_filename'.
					See section 'Details' for more information.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid map element</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

	<section id="fileset_specification">
		<title>RNG Specification</title>

		<programlisting><![CDATA[
  <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>
		        ]]>

	</programlisting>
	</section>

	<section id="fileset_examples">
		<title>Examples</title>
	<programlisting><![CDATA[
  <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>
]]>
	</programlisting>
	</section>

	<section id="lx_dfa_wildcard">
		<title>LX DFA Wildcards</title>
		<para>
			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.
		</para>
		<para>
			Here is the pattern syntax of LX DFA Wildcards (implemented in GOBO's class LX_DFA_WILDCARD):
		</para>
	<programlisting>
    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 '|'.
	</programlisting>
	</section>

<section id="obsolete_fileset_element">
<title>Obsolete (GOBO 3.1) Fileset format</title>
<para>
To alleviate the migration of the former fileset format to the current one the
following list describes the old format.
</para>
</section>

	<section id="fileset_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>directory</term>
				<listitem>
					<para><emphasis>Description: </emphasis>
						The directory taken as root to find files matching the given criteria `include'
						and `exclude'
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid directoryname</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>include</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Pattern for names of files to be included in fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid LX DFA Wildcard (see below)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>exclude</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Pattern for names of files to be excluded from fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid LX DFA Wildcard (see below)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>force</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Include matched filenames even when the
						matched file is not out of date.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>true</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>concat</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Prepend value of attribute `directory' before determined `mapped_filename'</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</section>

	<section id="fileset_nested_parameters">
		<title>Parameters specified as nested elements</title>

		<variablelist>
			<varlistentry>
				<term>include</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of individual file to be included in fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>exclude</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of individual file to be excluded from fileset</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>map</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Map element used to determine 'mapped_filename'.
					See section 'Detailes' for more information.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid map element</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

	<section id="fileset_specification">
		<title>Obsolete (GOBO 3.1) RNG Specification</title>

		<programlisting><![CDATA[
  <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>
		        ]]>

	</programlisting>
	</section>
</chapter>



