對應檔案名稱

有些任務會取得原始檔並建立目標檔。根據任務，目標檔的名稱可能會很明顯（使用 javac，您知道 .java 檔會有 .class 檔）—在其他情況下，您可能想要指定目標檔，以協助 Apache Ant 或取得額外的功能。

雖然原始檔通常指定為 檔案集，但您不會直接指定目標檔—相反地，您會告訴 Ant 如何為一個原始檔尋找目標檔。負責這項工作的是 org.apache.tools.ant.util.FileNameMapper 的執行個體。它會根據可以透過 from 和 to 屬性參數化的規則來建構目標檔名稱—其確切意義取決於實作。

這些執行個體在 <mapper> 元素中定義，其屬性如下

請注意，Ant 不會自動將 to 和 from 屬性中的 / 或 \ 字元轉換為您目前平台的正確目錄分隔符號。如果您需要指定此分隔符號，請改用 ${file.separator}。對於 regexp 對應器，${file.separator} 無法使用，因為在 Windows 上它是 \ 字元，而這是正規表示式的跳脫字元，您應該改用 handledirsep 屬性。

以巢狀元素指定參數

類別路徑也可以透過巢狀 <classpath> 指定，也就是類似 路徑 的結構。

自 Ant 1.7.0 起，巢狀檔案對應器可以透過 <mapper> 元素或 org.apache.tools.ant.util.FileNameMapper 的 <typedef> 實作提供。如果透過任一種方式指定巢狀檔案對應器，則對應器會被隱式設定為 複合對應器。

內建對應器類型

所有內建對應器都區分大小寫。

自 Ant 1.7.0 起，每個內建的對應程式實作類型都可以直接使用特定標籤名稱存取。這讓檔案名稱對應程式除了普遍可用的 to 和 from 之外，還能支援屬性。
<mapper type|classname="..."> 用法格式仍然有效，這是為了向後相容性。

identity

目標檔案名稱與來源檔案名稱相同。將會忽略 to 和 from。

範例

<mapper type="identity"/>
<identitymapper/>

flatten

目標檔案名稱與來源檔案名稱相同，但會移除所有前置目錄資訊。將會忽略 to 和 from。

範例

<mapper type="flatten"/>
<flattenmapper/>

merge

目標檔案名稱將永遠相同，由 to 定義，將會忽略 from。

範例

<mapper type="merge" to="archive.tar"/>
<mergemapper to="archive.tar"/>

glob

需要 to 和 from，且定義的模式最多只能包含一個 *。對於每個符合 from 模式的來源檔案，目標檔案名稱將從 to 模式建構，方法是將 to 模式中的 * 替換為與 from 模式中的 * 符合的文字。不符合 from 模式的來源檔案名稱將會被忽略。

範例

<mapper type="glob" from="*.java" to="*.java.bak"/>
<globmapper from="*.java" to="*.java.bak"/>

<mapper type="glob" from="C*ies" to="Q*y"/>
<globmapper from="C*ies" to="Q*y"/>

globmapper 對應程式可以採用下列額外屬性。

範例

<pathconvert property="x" targetos="unix">
  <path path="Aj.Java"/>
  <mapper>
  <chainedmapper>
    <flattenmapper/>
    <globmapper from="a*.java" to="*.java.bak" casesensitive="no"/>
  </chainedmapper>
  </mapper>
</pathconvert>
<echo>x is ${x}</echo>

將輸出 x is j.java.bak，而

<pathconvert property="x" targetos="unix">
  <path path="d/e/f/j.java"/>
  <mapper>
    <globmapper from="${basedir}\d/e\*" to="*" handledirsep="yes"/>
  </mapper>
</pathconvert>
<echo>x is ${x}</echo>

將輸出 x is f/j.java。

regexp

需要 to 和 from，且定義正規表示式。如果來源檔案名稱（全部或部分）符合 from 模式，目標檔案名稱將從 to 模式建構，使用 \0 到 \9 作為完整比對（\0）或括號中子表達式的比對結果的反向參照。to 模式決定整個檔案名稱，因此如果您想替換檔案的副檔名，不應使用 from="\.old$" to=".new"，而應使用 from="(.*)\.old$" to="\1.new"（或在此情況下使用 glob 對應程式）。

不符合 from 模式的來源檔案將會被忽略。

請注意，您需要在 Ant 中使用另一個美元符號 ($) 來跳脫美元符號 ($)。

有關使用 gnu.regexp 或 gnu.rex 搭配 Ant 的資訊，請參閱 這篇文章。請記住，不同的正規表示式引擎可能會有 不同的執行效率。

如果您想使用除 java.util.regex 以外的 正規表示式函式庫，您還需要使用您正在使用的 Ant 版本中的對應 ant-[apache-oro, apache-regexp].jar。請確保兩個檔案都會從同一個類別路徑載入，也就是將它們放入您的 CLASSPATH、ANT_HOME/lib 目錄或對應器的巢狀 <classpath> 元素中，您不能將 ant-[apache-oro, apache-regexp].jar 放入 ANT_HOME/lib，並將函式庫放入巢狀 <classpath> 中。

Ant 會根據下列演算法選擇正規表示式函式庫

• 如果系統屬性 ant.regexp.matcherimpl 已設定，則視為實作 org.apache.tools.ant.util.regexp.RegexpMatcher 的類別名稱，且應使用該類別。
• 如果未設定，則使用 java.util.regex 套件中的預設值。

範例

<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
<regexpmapper from="^(.*)\.java$$" to="\1.java.bak"/>

<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
<regexpmapper from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>

<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
<regexpmapper from="^(.*)\.(.*)$$" to="\2.\1"/>

<mapper type="regexp" from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/>
<regexpmapper from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/>

正規表示式對應器可以接受下列額外屬性。

範例

<pathconvert property="x" targetos="unix">
  <path path="Aj.Java"/>
  <chainedmapper>
    <flattenmapper/>
    <regexpmapper from="a(.*)\.java" to="\1.java.bak" casesensitive="no"/>
  </chainedmapper>
</pathconvert>
<echo>x is ${x}</echo>

將輸出 x is j.java.bak，而

<pathconvert property="hd.prop" targetos="windows">
  <path path="d\e/f\j.java"/>
  <chainedmapper>
    <regexpmapper from="${basedir}/d/e/(.*)" to="\1" handledirsep="yes"/>
  </chainedmapper>
</pathconvert>

會將 hd.prop 設定為 f\j.java。

package

package 對應器與 glob 對應器 共用相同的語法，它會將比對的來源樣式中找到的目錄分隔符號替換為目標樣式佔位符中的點。此對應器特別適用於與 <uptodate> 和 <junit> 輸出搭配使用。

to 和 from 屬性都是必要的。

範例

<mapper type="package" from="*Test.java" to="TEST-*Test.xml"/>
<packagemapper from="*Test.java" to="TEST-*Test.xml"/>

解壓縮

自 Ant 1.6.0 起

此對應器為 封裝 對應器的反向。它會將封裝名稱中的點替換為目錄分隔符號。這對於比對 XML 格式化結果與其 JUnit 測試案例很有用。此對應器共用與 glob 對應器 相同的範例語法。

to 和 from 屬性都是必要的。

範例

<mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java">
<unpackagemapper from="TEST-*Test.xml" to="${test.src.dir}/*Test.java">

複合

自 Ant 1.7.0 起

此對應器實作可以包含多個巢狀對應器。檔案對應是透過將來源檔名傳遞給每個巢狀的 <mapper> 來執行，並傳回所有結果。to 和 from 屬性會被忽略。

自 Ant 1.8.0 起，對應結果的順序與巢狀對應器的順序相同；在 Ant 1.8.0 之前，順序是不確定的。

範例

<compositemapper>
  <identitymapper/>
  <packagemapper from="*.java" to="*"/>
</compositemapper>

複合對應器沒有對應的 <mapper> type 屬性。

鏈結

自 Ant 1.7.0 起

此對應器實作可以包含多個巢狀對應器。檔案對應是透過將來源檔名傳遞給第一個巢狀對應器，將其結果傳遞給第二個巢狀對應器，以此類推。由最後一個巢狀對應器產生的目標檔名組成對應作業的最終結果。to 和 from 屬性會被忽略。

範例

<chainedmapper>
  <flattenmapper/>
  <globmapper from="*" to="new/path/*"/>
  <mapper>
    <globmapper from="*" to="*1"/>
    <globmapper from="*" to="*2"/>
  </mapper>
</chainedmapper>

鏈結對應器沒有對應的 <mapper> type 屬性。

filtermapper

自 Ant 1.6.3 起

此對應器實作會將 filterchain 套用至來源檔名。

範例

<filtermapper>
  <replacestring from="\" to="/"/>
</filtermapper>

<filtermapper>
  <scriptfilter language="beanshell">
    self.setToken(self.getToken().toUpperCase());
  </scriptfilter>
</filtermapper>

filtermapper 沒有對應的 <mapper> type 屬性。

scriptmapper

自 Ant 1.7 起

此對應器會執行以 Apache BSF 或 JSR 223 支援的語言撰寫的腳本，每次對應一個檔案。

腳本可以在內嵌或指定的檔案中宣告。

請參閱 Script 作業，以了解腳本和相依性的說明。

此檔案名稱對應器可以採用巢狀 <classpath> 元素。請參閱 script 任務以了解如何使用此元素。

範例

<scriptmapper language="javascript">
  self.addMappedName(source.toUpperCase());
  self.addMappedName(source.toLowerCase());
</scriptmapper>

要使用此對應器，腳本需要存取原始檔案，並具有傳回多個對應項的能力。以下是相關 bean 及其方法。腳本會針對每個原始檔案呼叫一次，並在每次呼叫後重設對應名稱清單。

腳本對應器沒有對應的 <mapper> type 屬性。

firstmatchmapper

自 Ant 1.8.0 起

此對應器支援任意數量的巢狀對應器，並傳回第一個符合條件的對應器的結果。這與 複合對應器 不同，後者會收集所有符合條件的子項目的結果。

範例

<firstmatchmapper>
  <globmapper from="*.txt" to="*.bak"/>
  <globmapper from="*A.*" to="*B.*"/>
</firstmatchmapper>

firstmatchmapper 沒有對應的 <mapper> type 屬性。

cutdirsmapper

自 Ant 1.8.2 起

此對應器會從原始檔案名稱中移除設定數量的開頭目錄。

範例

<cutdirsmapper dirs="1"/>

cutdirsmapper 沒有對應的 <mapper> type 屬性。