選擇器

選擇器是一種機制，透過它可以根據檔案名稱以外的條件來選擇組成 <fileset> 的檔案，例如 <include> 和 <exclude> 標籤所提供的條件。

如何使用選擇器

選擇器是 FileSet 的元素，並顯示在其中。它也可以透過使用 <selector> 標籤並將其用作參考，在任何目標外部定義。

不同的選擇器有不同的屬性。有些選擇器可以包含其他選擇器，這些選擇器稱為 選擇器容器。還有一類選擇器允許使用者定義的擴充功能，稱為 自訂選擇器。內建於 Apache Ant 的選擇器稱為 核心選擇器。

核心選擇器

核心選擇器是 Ant 的標準選擇器。它們可以在檔案集中使用，也可以包含在選擇器容器中。

核心選擇器為

• <contains>—選擇包含特定文字字串的檔案
• <date>—選擇在特定日期和時間之前或之後修改的檔案
• <depend>—選擇比其他地方的等效檔案修改時間較新的檔案
• <depth>—選擇在目錄樹中出現在這麼多目錄下的檔案
• <different>—選擇與其他地方不同的檔案
• <filename>—選擇其名稱符合特定模式的檔案。等同於模式集的 include 和 exclude 元素。
• <present>—選擇在其他位置存在或不存在的檔案
• <containsregexp>—選擇符合正規表示式的檔案
• <size>—選擇大於或小於特定位元組數的檔案。
• <type>—選擇是常規檔案或目錄的檔案。
• <modified>—如果已設定演算法的回傳值與儲存在快取中的值不同，則選擇檔案。
• <signedselector>—如果檔案已簽署，且選擇性地具有特定名稱的簽署，則選取檔案。
• <scriptselector>—使用 BSF 或 JSR 223 腳本語言建立自己的選取器
• <readable>—如果檔案可讀取，則選取檔案。
• <writable>—如果檔案可寫入，則選取檔案。
• <executable>—如果檔案可執行，則選取檔案。
• <symlink>—如果檔案是符號連結，則選取檔案。
• <ownedBy>—如果檔案由特定使用者擁有，則選取檔案。
• <posixGroup>—如果檔案具有特定 POSIX 群組，則選取檔案。
• <posixPermissions>—如果檔案具有特定 POSIX 權限，則選取檔案。

包含選取器

FileSet 中的 <contains> 標籤將該檔案集定義的檔案限制為僅包含 text 屬性指定的字串的檔案。

<contains> 選取器可以用作資源選取器（請參閱 <restrict> 資源集合）。

以下是使用包含選取器的範例

<fileset dir="${doc.path}" includes="**/*.html">
    <contains text="script" casesensitive="no"/>
</fileset>

選取所有包含字串 script 的 HTML 檔案。

日期選取器

FileSet 中的 <date> 標籤將限制 include 標籤指定的檔案，因此最後修改日期不符合選取器指定的日期限制的標籤將不會被選取。

以下是日期選擇器的使用範例

<fileset dir="${jar.path}" includes="**/*.jar">
    <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

選取所有在 2001 年 1 月 1 日午夜之前最後修改的 JAR 檔案。

相依選擇器

<depend> 標籤選取最後修改日期晚於另一個位置中另一個等效檔案的檔案。

<depend> 標籤支援使用包含的 <mapper> 元素來定義要與之比較檔案的位置。如果未指定 <mapper> 元素，則會使用 identity 類型的對應器。

<depend> 選擇器區分大小寫。

以下是相依選擇器的使用範例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend targetdir="${ant.1.4.1}/src/main"/>
</fileset>

選取所有在 1.5 版中修改的 Java 原始碼檔案。

深度選擇器

<depth> 標籤會根據檔案在檔案集基礎目錄中所處的目錄層級深度來選取檔案。

以下是如何使用深度選取器的範例

<fileset dir="${doc.path}" includes="**/*">
    <depth max="1"/>
</fileset>

選取基礎目錄和其下一個目錄中的所有檔案。

不同的選取器

<different> 選取器會選取在其他位置被視為「不同」的等效檔案。判斷兩個檔案之間差異的規則如下

1. 如果檔案只存在於套用選取器的資源集合中，但不存在於 targetdir（或套用比對器後），則選取該檔案。
2. 如果檔案只存在於 targetdir（或套用比對器後），則忽略該檔案。
3. 長度不同的檔案不同。
4. 如果將 ignoreFileTimes 關閉 (off)，則檔案時間戳記不同會導致檔案被視為不同。
5. 除非將 ignoreContents 設定為 true，否則會對兩個檔案執行逐位元組檢查。

這是與無法正確處理相依性檢查的程式和任務搭配使用的有用選取器；即使前置任務總是會建立其輸出檔案，後續任務仍可由使用不同選取器建立的副本驅動，因此其相依性會根據檔案的絕對狀態驅動，而不仅仅是時間戳記。例如：從網站擷取的任何內容或某些程式的輸出。為減少檢查數量，在 <copy> 任務中使用此任務時，將 preservelastmodified 設定為 true，以將時間戳記從來源檔案傳播到目標檔案。

<different> 選取器支援使用包含的 <mapper> 元素來定義要比對的檔案位置。如果未指定 <mapper> 元素，則使用 identity 類型比對器。

以下是使用不同選擇器的範例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <different targetdir="${ant.1.4.1}/src/main"
        ignoreFileTimes="true"/>
</fileset>

比較 1.4.1 和 1.5 版本之間的所有 Java 原始檔，並選取不同的檔案，不考慮檔案時間。

檔案名稱選擇器

<filename> 標籤的作用類似於檔案集中 <include> 和 <exclude> 標籤。不過，透過使用選擇器，可以將其與所有其他選擇器結合，使用任何想要的 選擇器容器。

<filename> 選擇器區分大小寫。

以下是使用檔案名稱選擇器的範例

<fileset dir="${doc.path}" includes="**/*">
    <filename name="**/*.css"/>
</fileset>

選取所有層疊樣式表檔案。

目前選擇器

<present> 標籤選取在另一個目錄樹中具有等效檔案的檔案。

<present> 標籤支援使用包含的 <mapper> 元素來定義要測試的檔案位置。如果未指定 <mapper> 元素，則使用 identity 類型對應器。

<present> 選擇器區分大小寫。

以下是使用目前選擇器的方法範例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <present present="srconly" targetdir="${ant.1.4.1}/src/main"/>
</fileset>

選取 1.5 版中所有新的 Java 原始檔。

正規表示式選擇器

FileSet 中的 <containsregexp> 標籤會將該檔案集定義的檔案限制為僅包含與 expression 屬性指定的正規表示式相符的內容。

<containsregexp> 選擇器可用作資源選擇器（請參閱 <restrict> 資源集合）。

以下是使用正規表示式選擇器的方法範例

<fileset dir="${doc.path}" includes="*.txt">
    <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

選取所有與正規表示式相符的文字檔（包含 4、5 或 6，後面接一個句點和 0 到 9 的數字）。

大小選擇器

FileSet 中的 <size> 標籤會對 include 標籤指定的檔案設定限制，因此不符合選擇器指定的檔案大小限制的標籤將不會被選取。

以下是使用大小選擇器的範例

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <size value="4" units="Ki" when="more"/>
</fileset>

選取所有大於 4096 位元組的 JAR 檔案。

類型選擇器

<type> 標籤選取特定類型的檔案：目錄或一般檔案。

以下是使用類型選擇器選取 ${src} 中僅目錄的範例

<fileset dir="${src}">
  <type type="dir"/>
</fileset>

類型選擇器通常與其他選擇器結合使用。例如，若要選取也存在於 template 目錄中的檔案，但避免選取空目錄，請使用

<fileset dir="${src}">
    <and>
        <present targetdir="template"/>
        <type type="file"/>
    </and>
</fileset>

已修改選擇器

<modified> 選擇器會計算檔案的值，將其與儲存在快取中的值進行比較，如果這兩個值不同，則選取該檔案。

由於此選擇器高度可設定，因此執行選取的順序為

1. 取得檔案的絕對路徑
2. 從設定的快取中取得快取值（絕對路徑為金鑰）
3. 從設定的演算法取得新值
4. 使用設定的比較器比較這兩個值
5. 視需要更新快取
6. 根據比較結果執行選取

比較、計算雜湊值和儲存是由特殊介面的實作完成。因此，它們可能會提供其他參數。

<modified> 選擇器可用作資源選擇器（請參閱 <restrict> ResourceCollection）。在這種情況下，它會將簡單的檔案資源對應到檔案並執行其工作。如果資源來自其他類型，<modified> 選擇器會嘗試（注意！）將內容複製到本地檔案以計算雜湊值。

如果來源資源不是檔案系統資源，已修改選擇器會將其下載到 暫存目錄。

以巢狀元素指定參數

<modified> 選取器支援巢狀 <classpath> 元素，表示用於尋找自訂介面實作的 類似路徑的結構。

<modified> 選取器的所有屬性都可以使用巢狀 <param/> 標籤設定。可以根據下列規則使用 <param/> 標籤設定其他值。

演算法

與 algorithm 屬性相同，並具有下列其他值

快取

與 cache 屬性相同，並具有下列其他值

比較器

與 comparator 屬性相同。

algorithmclass

與 algorithmclass 屬性相同。

comparatorclass

與 comparatorclass 屬性相同。

cacheclass

與 cacheclass 屬性相同。

update

與 update 屬性相同。

seldirs

與 comparatorclass 屬性相同。

範例

以下是一些使用 Modified Selector 的範例

<copy todir="dest">
    <fileset dir="src">
        <modified/>
    </fileset>
</copy>

這會將所有檔案從 src 複製到 dest，其中內容已變更。使用更新的 PropertyfileCache 與 cache.properties 和 MD5-DigestAlgorithm。

<copy todir="dest">
    <fileset dir="src">
        <modified update="true"
                  seldirs="true"
                  cache="propertyfile"
                  algorithm="digest"
                  comparator="equal">
            <param name="cache.cachefile"     value="cache.properties"/>
            <param name="algorithm.algorithm" value="MD5"/>
        </modified>
    </fileset>
</copy>

這是相同的範例，改寫為 CoreSelector，設定所有值（與預設值相同）。

<copy todir="dest">
    <fileset dir="src">
        <custom class="org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector">
            <param name="update"     value="true"/>
            <param name="seldirs"    value="true"/>
            <param name="cache"      value="propertyfile"/>
            <param name="algorithm"  value="digest"/>
            <param name="comparator" value="equal"/>
            <param name="cache.cachefile"     value="cache.properties"/>
            <param name="algorithm.algorithm" value="MD5"/>
        </custom>
    </fileset>
</copy>

這是相同的範例，改寫為 CustomSelector。

<target name="generate-and-upload-site">
    <echo> generate the site using forrest </echo>
    <antcall target="site"/>

    <echo> upload the changed file </echo>
    <ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}">
        <fileset dir="htdocs/manual">
            <modified/>
        </fileset>
    </ftp>
</target>

在建置環境中，此選擇器對於首頁產生（例如使用 Apache Forrest）的實用場景。在此，所有已變更的檔案都會上傳到伺服器。因此，CacheSelector 可節省許多上傳時間。

<modified cacheclassname="com.mycompany.MyCache">
    <classpath>
        <pathelement location="lib/mycompany-antutil.jar"/>
    </classpath>
</modified>

使用 com.mycompany.MyCache，從 Ant 自己的類別路徑外部的 jar 檔案作為快取實作

關於 RuleBasedCollator 的注意事項

RuleBasedCollator 需要一種格式來執行其工作，但在建立實例時需要。初始化演算法在此情況下存在問題。因此，您不應使用此方法（或告訴我解決方法 :-）。

已簽署的選擇器

<signedselector> 標籤會選擇已簽署的檔案，並選擇性地選擇以特定名稱簽署的檔案。

自 Apache Ant 1.7 起

可讀取選擇器

<readable> 選擇器只會選擇可讀取的檔案。Ant 只會呼叫 java.io.File#canRead，因此如果檔案不可讀取，但 JVM 無法偵測此狀態，此選擇器仍會選擇該檔案。

可寫入選擇器

<writable> 選擇器只會選擇可寫入的檔案。Ant 只會呼叫 java.io.File#canWrite，因此如果檔案不可寫入，但 JVM 無法偵測此狀態，此選擇器仍會選擇該檔案。

可執行選擇器

<executable> 選擇器只會選擇可執行的檔案。Ant 只會呼叫 java.nio.file.Files#isExecutable，因此如果檔案不可執行，但 JVM 無法偵測此狀態，此選擇器仍會選擇該檔案。

自 Ant 1.10.0 起

符號連結選擇器

<symlink> 選擇器只會選擇為符號連結的檔案。Ant 只會呼叫 java.nio.file.Files#isSymbolicLink，因此如果檔案為符號連結，但 JVM 無法偵測此狀態，此選擇器將不會選擇該檔案。

自 Ant 1.10.0 起

OwnedBy 選擇器

<ownedBy> 選擇器僅選取由指定使用者擁有的檔案。Ant 僅呼叫 java.nio.file.Files#getOwner，因此如果檔案系統不支援此作業，此選擇器不會選取檔案。

自 Ant 1.10.0 起

POSIX 群組選擇器

<posixGroup> 選擇器僅選取由指定 POSIX 群組擁有的檔案。Ant 僅呼叫 java.nio.file.Files#readAttributes，因此如果檔案系統不支援此作業或 POSIX 屬性，此選擇器不會選取檔案。

自 Ant 1.10.4 起

POSIX 權限選擇器

<posixPermissions> 選擇器僅選取具有指定 POSIX 權限的檔案。Ant 僅呼叫 java.nio.file.Files#getPosixFilePermissions，因此如果檔案系統不支援此作業，此選擇器不會選取檔案。

自 Ant 1.10.4 起

指令碼選擇器

<scriptselector> 元素讓您可以在任何 Apache BSF 或 JSR 223 支援的語言中撰寫複雜的選取演算法。請參閱 Script 任務，以了解指令碼和相依性的說明。

自 Apache Ant 1.7 起

此選擇器可以採用巢狀的 <classpath> 元素。請參閱 script 任務，以了解如何使用此元素。

如果未提供 src 屬性，則必須將指令碼巢狀在選擇器宣告內。

會針對每個測試呼叫嵌入式指令碼，其中 bean self 與選擇器繫結。它有一個屬性 selected，可以使用 setSelected(boolean) 設定，以選取檔案。

除了專案、屬性和目標的經典組之外，還會為每個指令碼設定下列 bean。

self bean 對應到選取器，它有下列屬性。只有 selected 旗標可寫入，其餘只能透過 getter 方法讀取。

範例

<scriptselector language="javascript">
  self.setSelected(true);
</scriptselector>

選取所有檔案。

<scriptselector language="javascript">
  self.setSelected((filename.length%2)==0);
</scriptselector>

選取檔案名稱長度為偶數的檔案。

選取器容器

若要建立更複雜的選取，可以使用各種包含其他選取器的選取器。它們會以各種方式結合其子選取器的選取。

選取器容器有

• <and>—只有當所有包含的選取器都選取檔案時，才會選取該檔案。
• <majority>—如果其選取器中的大多數選取檔案，則選取該檔案。
• <none>—只有當沒有任何包含的選取器選取檔案時，才會選取該檔案。
• <not>—只能包含一個選取器，並反轉其選取和不選取的項目。
• <or>—如果任何一個包含的選取器選取檔案，則選取該檔案。
• <selector>—只包含一個選取器，並在符合任何 "if" 或 "unless" 條件的情況下，將所有要求轉發給它，而不做任何變更。如果您要定義參考，則可以使用這個選取器。它可用作 <project> 的元素。如果您要讓檔案選取依賴於 Ant 屬性設定，則也可以使用這個選取器。

所有選取器容器都可以包含任何其他選取器（包括其他容器）作為元素。使用容器，選取器標籤可以任意深入。以下是容器中允許的選取器元素的完整清單

• <and>
• <contains>
• <custom>
• <date>
• <depend>
• <depth>
• <filename>
• <majority>
• <none>
• <not>
• <or>
• <present>
• <selector>
• <size>

And 選取器

<and> 標籤會選取所有包含元素所選取的檔案。它會在找到未選取檔案的選取器後立即傳回，因此無法保證會檢查每個選取器。

以下是 And 選取器的使用範例

<fileset dir="${dist}" includes="**/*.jar">
    <and>
        <size value="4" units="Ki" when="more"/>
        <date datetime="01/01/2001 12:00 AM" when="before"/>
    </and>
</fileset>

選取所有大於 4096 位元組且自從上個千禧年以來未更新的 JAR 檔案。

Majority 選取器

<majority> 標籤會選取檔案，前提是大部分包含的元素也選取它。平手時，會依照 allowtie 屬性所指定的內容處理。

以下是 Majority 選取器的使用範例

<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="IntrospectionHelper" casesensitive="true"/>
    </majority>
</fileset>

選取至少包含三個詞組 project、taskdef 和 IntrospectionHelper 中兩個的 HTML 檔案（最後一個詞組必須完全符合大小寫）。

None 選取器

<none> 標籤會選取所有包含元素未選取的檔案。它會在找到選取檔案的選取器後立即傳回，因此無法保證會檢查每個選取器。

以下是 None 選取器的使用範例

<fileset dir="${src}" includes="**/*.java">
    <none>
        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </present>
    </none>
</fileset>

只選取 .java 檔案，而 dest 目錄中沒有等效的 .java 或 .class 檔案。

Not 選取器

<not> 標籤會反轉其包含的單一選取器的意義。

以下是 Not 選取器的使用範例

<fileset dir="${src}" includes="**/*.java">
    <not>
        <contains text="test"/>
    </not>
</fileset>

選取 src 目錄中不包含字串 test 的所有檔案。

Or 選取器

<or> 標籤會選取所有包含元素所選取的檔案。它會在找到選取檔案的選取器後立即傳回，因此無法保證會檢查每個選取器。

以下是 Or 選取器的使用範例

<fileset dir="${basedir}">
    <or>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>

選取頂層目錄中的所有檔案以及其下方的所有影像檔案。

選取器參考

<selector> 標籤用於建立可透過參考重複使用的選取器。它是唯一可以在任何目標之外使用的選取器，作為 <project> 標籤的元素。它只能包含一個其他選取器，但當然那個選取器可以是容器。

<selector> 標籤也可以根據 Ant 屬性是否存在有條件地選取檔案。此功能是使用 if 和 unless 屬性實現的，其使用方式與在目標或 <patternset> 中的 <include> 和 <exclude> 標籤上完全相同。

以下是 Selector Reference 使用範例

<project default="all" basedir="./ant">

    <selector id="completed">
        <none>
            <depend targetdir="build/classes">
                <mapper type="glob" from="*.java" to="*.class"/>
            </depend>
            <depend targetdir="docs/manual/api">
                <mapper type="glob" from="*.java" to="*.html"/>
            </depend>
        </none>
    </selector>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">
                <selector refid="completed"/>
            </fileset>
        </zip>
    </target>

</project>

壓縮所有 java 檔案，這些檔案具有最新的等效類別檔案和 javadoc 檔案。

以下是根據屬性是否設定，有條件選取檔案的範例

<fileset dir="${working.copy}">
    <or>
        <selector if="include.tests">
            <filename name="**/*Test.class">
        </selector>
        <selector if="include.source">
            <and>
                <filename name="**/*.java">
                <not>
                    <selector unless="include.tests">
                        <filename name="**/*Test.java">
                    </selector>
                </not>
            </and>
        </selector>
    </or>
</fileset>

有條件包含 Java 來源檔案、測試來源檔案和類別檔案的檔案集。

自訂選擇器

您可以在 <custom> 標籤中指定自訂選擇器，並在選擇器容器中使用它們。

首先，您必須使用 Java 編寫您的選擇器類別。它必須符合的唯一條件是實作 org.apache.tools.ant.types.selectors.FileSelector 介面，其中包含一個方法。如需詳細資訊，請參閱 在 Ant 中編寫程式選擇器。

撰寫完畢後，請使用 <custom> 標籤將它包含在您的建置檔案中。

以下是使用 <custom> 將您的類別用作選擇器的範例

<fileset dir="${mydir}" includes="**/*">
    <custom classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>
    </custom>
</fileset>

也可以透過使用 <param> 元素指定其屬性，將許多核心選擇器用作自訂選擇器。這些選擇器包括

• 包含選擇器，其類別名稱為 org.apache.tools.ant.types.selectors.ContainsSelector
• 日期選擇器，其類別名稱為 org.apache.tools.ant.types.selectors.DateSelector
• 深度選擇器，其類別名稱為 org.apache.tools.ant.types.selectors.DepthSelector
• 檔案名稱選擇器，其類別名稱為 org.apache.tools.ant.types.selectors.FilenameSelector
• 大小選擇器，其類別名稱為 org.apache.tools.ant.types.selectors.SizeSelector

以下是深度選擇器區段的範例，已改寫為透過 <custom> 使用選擇器。

<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>
    </custom>
</fileset>

選取基礎目錄和其下一個目錄中的所有檔案。

如需撰寫自訂選擇器的詳細資訊，請參閱 在 Ant 中編寫程式選擇器。