====== Overview ======
{{indexmenu_n>1}}

<hi #cc00ff>~~SP~~~~SP~~</hi> //<color blue>J</color>//Ware/AntXtras Properties Editor for Ant (PEd4Ant) is a collection of components for creating and manipulating standard Java properties files from within Ant script. If you need to do lots of custom properties manipulation, while preserving the original source as much as possible, you will find PEd4Ant very useful.

To use PEd4Ant you just load its antlib into your Ant runtime. PEd4Ant depends on the standard Ant and AntXtras libraries only. The recommended namespace URI and prefix for PEd4Ant is “jwaresoftware.ped4ant” and “ped:” respectively. Read the “[[.:download#Loading PEd4Ant Antlib|Loading PEd4Ant antlib]]” instructions for additional information.

===== Main Features =====

  - 100% Ant, 100% Java Properties-- information manipulated as objects not text.
  - Preserves structure //including whitespace and comments// so that `diff` shows only edits.
  - Has a full suite of property operations: insert, delete, test, replace, [un]comment, copy, diff.
  - Can read local or remote properties sources using any URL format your Ant runtime supports.
  - Supports editing in place with auto-backup on load and auto-save per edit.
  - Supports ‘bulk’ or set versions of operations using standard Ant filter chains and mappers.
  - Support properties in both standard format as well as the newer XML format (JRE 1.5+).
  - Supports Ant filter chains on properties load to transform incoming keys and values with ease.
  - Works the same on both transient in-memory content or externally sourced content.
  - Lets you create custom Ant <propertyset> data from processed property file contents.

====== Component Summary ======
The [[#Installing PEd4Ant Antlib|recommended namespace prefix]] for PEd4Ant is “ped:”; this prefix is assumed in our table below. If you’re a developer looking to extend or use PEd4Ant in your own Ant components, you will find additional implementation details in the [[/apis/ped4ant/latest/|PEd4Ant Javadoc API]] reference.

^ Task/Type  ^ General Description  ^
| [[#Creating New Properties|ped:makeproperties]]  | Lets you create a new Properties object in memory. |
| [[#Loading Existing Properties|ped:loadproperties]]  | Lets you load a pre-existing Properties source into memory. |
| [[#Load-Merging Existing Properties|ped:mergeloadproperties]]  | Lets you load-and-merge multiple pre-existing Properties sources into memory{{shared:10x10-wrench.png|In progress}}. |
| [[#Editing Properties (inserts)|ped:editproperties]]  | Lets you performs a multitude of operations on loaded Properties.  |
| [[#Copying Loaded Properties|ped:readproperties]]  | Lets you copy in-memory Properties to Ant fixture or other Properties.  |
| [[#Saving Edited Properties|ped:saveproperties]]  | Lets you save in-memory Properties to a file.  |
| [[#Finding Changed Properties|ped:diffproperties]]  | Lets you capture differences between two Properties as objects (not text).  |
| [[#Testing Loaded Properties|ped:testproperties]]  | Lets you apply a test condition to a Properties’ contents or keys. |


====== Quick Start Examples ======
All PEd4Ant manipulation operations require that you either create a new memory-based Properties object or load one from an external source. The following examples show you how to manipulate a Properties object created from scratch or loaded from an external definition file (standard or XML). Once you’re done with your edits you can: save the in-memory object back to a file, create some other Ant data structure like a property set or other resource collection, or apply the properties into the current Ant fixture so you can use them like regular Ant properties via ‘${…}’ semantics.

:!: Not all of the features described below were available in the initial beta release of PEd4Ant with AntXtras v2; however, all of these components and operations exist in the latest PEd4Ant 1.0.0 release that works with AntXtras v3. Any example that describes future functionality is marked with an “in progress” icon ({{shared:10x10-wrench.png|In progress}}) at its start. You can read the [[/wiki-include/ped4ant/latest/WHATSNEW.txt|Release Notes]] for the list of features implemented in the latest distribution and then the [[:ped4ant:ourplans|Future Plans]] for the general PEd4Ant release schedule.


===== Installing PEd4Ant Antlib =====

You can install the PEd4Ant extension directly into your <ANT_HOME>/lib directory or more typically into its own location. This example assumes the latter case: it loads the PEd4Ant antlib into the Ant runtime from a location defined by the ‘PED4ANT_HOME’ property and then links its components to the “ped:” namespace prefix.
<code xml 1>
<project name="example" xmlns:ped="jwaresoftware.ped4ant"…>
  <property name="PED4ANT_HOME" value="..."/>
  …
  <taskdef uri="jwaresoftware.ped4ant"
      resource="org/jwaresoftware/ped4ant/antlib.xml">
    <classpath>
      <fileset dir="${PED4ANT_HOME}"
         includes="lib/*.jar"/>
    </classpath>
  </taskdef>
  …
</code>

~~UP~~

===== Creating New Properties =====

• Example: creates a new empty Properties object “myconf” in memory, overwriting //unconditionally// any object currently stored with that id. After creation, the new object is ready to accept key-value data from other PEd4Ant commands.
<code xml 1>
<ped:makeproperties under="myconf"/>
</code>
\\
• Example: creates a new empty Properties object “myconf” that is automatically linked to a file ‘autogen.properties’ for saving. Note that the file not created until the first actual call to save the “myconf” object:
<code xml 1>
<ped:makeproperties under="myconf" 
     filelink="${my.d}/autogen.properties"/>
</code>
\\
• Example: creates a new Properties object “myconf” that is automatically pre-filled with some inlined property values including comments. You can also seed a new Properties object from a standard Ant <propertyset>, or a <string> resources collection, or an AntXtras <properties> object.
<code xml 1>
<ped:makeproperties under="myconf">
  <string value="#TOP-OF-FILE (created:${$iso:})"/>
  <string value="my-key=my-value"/>
  <string value="#END-OF-FILE"/>
</ped:makeproperties>
</code>
\\
• Example: creates a new Properties object “runconf” that is pre-filled with a subset of properties in the current Ant fixture (properties starting with “test.”). The new Properties is also automatically linked to an output file for auto-save operations after more editing.
<code xml 1>
<propertyset id="testproperties">
  <property prefix="test."/>
</propertyset>
…
<ped:makeproperties under="runconf" from="testproperties"
     filelink="${run.d}/run.properties"/>
</code>
~~UP~~

===== Loading Existing Properties =====

• Example: loads a new Properties object “myconf” from an existing external source, in this case a local file ‘template.properties’. Note that the file is not backed up, so any subsequent saves will overwrite the original file.
<code xml 1>
<ped:loadproperties under="myconf"
     file="${my.d}/template.properties"/>
</code>
\\
• Example: loads a new Properties object “myconf” from an existing external source that is using the standard XML format for Java Properties. If you want to load an XML formatted source that does not use the standard “.xml” extension set the ‘format=xml’ parameter explicitly.
<code xml 1>
<ped:loadproperties under="myconf"
     file="${my.d}/template.xml"/>
</code>
\\
• Example: loads a new Properties object “myconf” from information stored at remote location ‘${my.url}’ and saves a local baseline //file// version ‘original.properties’ with which we can create a patch file after editing the in-memory copy.
<code xml 1>
<ped:loadproperties under="myconf"
     url="${my.url}/template.properties" 
     backup="${tmp.d}/original.properties"/>
</code>
\\
• Example: loads a new //readonly// Properties object “myconf” from information stored at location ‘${my.properties}’. No edits of any kind will be allowed to the memory based “myconf” data.
<code xml 1>
<ped:loadproperties under="myconf"
     file="${my.properties}" readonly="yes"/>
</code>
\\
• Example: loads a new Properties object “myconf” from a information stored at remote location ‘${my.url}’ then replaces all ‘${…}’ //value// references with their current runtime values (including properties defined within the loaded Properties source itself). The ‘baseline=off’ parameter tells PEd4Ant not to consider the initial in-memory copy as a baseline, aka pristine, copy of the original source.
<code xml 1>
<ped:loadproperties under="myconf"
     url="${my.url}/template.properties" baseline="off"
     expandpropertyrefs="yes"/>
</code>
\\
• Example: loads a new Properties object “myconf” from a local file but does some pre-processing of the file's contents before storing it to memory. In particular, we remove all blank and comment lines and load only items whose keys begin with “deploy.”. Note that the PEd4Ant’s load tasks support all standard Ant filter readers and token filters when loading a Properties object.
<code xml 1>
<ped:loadproperties under="myconf" 
     file="${my.d}/build.properties" baseline="off">
  <filterchain>
    <striplinecomments>
      <comment value="#"/>
      <comment value="!"/>
    </striplinecomments>
    <tokenfilter>
      <ignoreblank/>
    </tokenfilter>
    <linecontainsregexp>
      <regexp pattern="^deploy\."/>
    </linecontainsregexp>
  </filterchain>
</ped:loadproperties>
</code>
\\
• Example: creates a new Properties object “myconf” by loading a combination of three other local files into memory. Note that the loading of the files is part of the filtering process; additional filters are //not// applied to each loaded file (see next example).
<code xml 1>
<ped:loadproperties under="myconf"
     file="${my.d}/empty.properties" baseline="off">
  <filterchain>
    <concatfilter append="${conf.d}/defaults.properties"/>
    <concatfilter append="${conf.d}/${deploy.env}.properties"/>
    <concatfilter append="${conf.d}/fixed.properties"/>
  </filterchain>
</ped:loadproperties>
</code>
\\
• Example: {{shared:10x10-wrench.png|In progress}} two ways to create and //merge load// a series of files into a single in-memory Properties object “myconf”. Note that the order in which source files are loaded, depends on how you define your inclusion criteria. For an ordered sequence of local files you can use a <filelist>; otherwise, you can use any filesystem based Ant resource set like a <fileset>, <zipresource>, or <tarresource>. You can even include remote sources by using the standard Ant <url> resource. Also, if you do a merged load of multiple sources, any filtering is applied to //each source’s contents// before it is merged; this differs from how filters are applied if the merging is done via filters too (previous examples).
<code xml 1>
<ped:mergeloadproperties under="myconf">        <ped:mergeloadproperties under="myconf">
  <filelist dir="${conf.d}">                      <file file="${conf.d}/defaults.properties"/>
    <file name="defaults.properties"/>            <javaresource name="conf/${env}.properties"/>
    <file name="${deploy.env}.properties"/>       <url url="${my.url}/company.properties"/>
    <file name="fixed.properties"/>             </ped:mergeloadproperties>
  </filelist>
</ped:mergeloadproperties>
</code>

~~UP~~

===== Editing Properties (inserts) =====

• Example: appends a set of new properties into an existing Properties object “myconf” using the <insert> action. You can insert comments, blank lines, empty values (value is the empty string), regular single key-value pairs, or property sets (sorted-by-key or unsorted).

<code xml 1>
<ped:editproperties under="myconf">
  <insert value="#A comment goes here..."/>
  <insert key="a-key" value="its-value"/>
  <insert properties="refid-properties" ordering="key"/>
  <insert properties="refid-other-properties"/>
  <insert key="key.with.empty.value"/>
</ped:editproperties>
</code>
\\
• Example: appends a blank line to an existing Properties object “myconf”.
<code xml 1>
<ped:editproperties under="myconf">
  <insert/>
</ped:editproperties>
</code>
\\
• Example: inserts a line into an existing Properties object “myconf” before a specific comment line by using the ‘before’ parameter. The new comment, that contains a dynamically generated time stamp, will be inserted just before the comment line that //equals// “#EOF”.
<code xml 1>
<ped:editproperties under="myconf">
  <insert value="#Deployed on: ${DATETIME}" before="#EOF"/>
</ped:editproperties>
</code>
\\
• Example: inserts a line with a value that can itself contain quotes or restricted XML or special Ant characters. The line’s contents will be encoded according to the standard Java Properties specification (ISO 8859 and unicode escaping).
<code xml 1>
<ped:editproperties under="myconf">
  <insert key="arguments">
    <value><![CDATA[this includes <xml> and other ${special} values]]></value>
  </insert>
  <insert key="synopsis">
    <value>${$loadfile:synopsis.txt}</value>
  </insert>
</ped:editproperties>
</code>

~~UP~~

===== Editing Properties (deletes) =====

• Example: removes a set of properties from an existing Properties object “myconf”. You can remove a single property by key or by value, or you can remove a set of properties based on some key or value selecting regular expression. You can even remove specific //comments// if needed. If you do not specify the ‘selector’ parameter, PEd4Ant assumes the operation applies to the properties’ keys.

<code xml 1>
<ped:editproperties under="myconf">
  <remove like="^disabled\..*"/>
  <remove equals="@@FIXME@@" selector="values"/>
  <remove key="java.naming.factory.initial"/>
  <remove like="^#INSTR:.*$" selector="comments"/>
</ped:editproperties>
</code>
\\
• Example: removes all blank lines from an existing Properties object “myconf”. You cannot use the generic value match for blank lines (e.g. like=“^$”) as that would also match empty-valued properties.

<code xml 1>
<ped:editproperties under="myconf">
  <remove blanks="yes"/>
</ped:editproperties>
</code>

\\
• Example: removes all lines from an existing Properties object “myconf”. Note that this can be //different// from removing all keys from a properties definition as it also removes all comment lines and blanks lines.

<code xml 1>
<ped:editproperties under="myconf">
  <clear/>
</ped:editproperties>
</code>

~~UP~~

===== Editing Properties (updates) =====
The update operations are the main workhorses for the PEd4Ant package. You can change existing property keys, values, and comments in a variety of ways.
== ==
\\
• Example: updates the value of the ‘version’ property in an existing Properties object “myconf”. The property's value is replaced unconditionally with the new value and if the key does not exist, update does nothing; it will **not** insert a new key.
<code xml 1>
<ped:editproperties under="my.conf">
  <update key="version" value="${build.version}"/>
</ped:editproperties>
</code>
\\
• Example: updates the value of the ‘notice’ item with text that contains quotes or restricted XML or special Ant characters. The line’s contents will be encoded according to the standard Java Properties specification (ISO 8859 and unicode escaping).
<code xml 1>
<ped:editproperties under="my.conf">
  <update key="notice">
    <value><![CDATA[Illegal characters include "<>${}![]&#.""]]></value>
  </update>
</ped:editproperties>
</code>
\\
• Example: updates all properties that have a value that equals “FIXXME” to instead have the value “UNRESOLVED!”.
<code xml 1>
<ped:editproperties under="my.conf">
  <update equals="FIXXME" selector="values" value="UNRESOLVED!"/>
</ped:editproperties>
</code>
\\
• Example: updates the property with the key ‘version’ to use a totally different //key//; the property’s value is left as-is.
<code xml 1>
<ped:editproperties under="my.conf">
  <update like="^version$" selector="key" replace="${environ}.version"/>
</ped:editproperties>
</code>
\\
• Example: updates all properties whose values are in a custom property selector format (like “@a://propertyname//”) with the current value of that property in the Ant runtime. If the property does not exist in the current Ant fixture, the script replaces the property selector with the value “UNRESOLVED!”.
<code xml 1>
<ped:editproperties under="my.conf">
  <update like="^\@a\:(.*)" selector="values" 
          replace="%{$property:\1?UNRESOLVED!}"/>
</ped:editproperties>
</code>
\\
• Example: flips two sets of specific properties (disable one set by prefixing key with “disabled.” and enable other set by dropping environment specific prefix) using the shortcut rename update. Because renaming keys is such a common use for the general update operation, PEd4ant supplies a predefined variant <rename> for this common use. 
<code xml 1>
<ped:editproperties under="my.conf">
   <rename like="^throttle\.(.*)" to="disabled.throttle.\1"/>
   <rename like="^${env}\.throttle\.(.*)" to="throttle.\1"/>
</ped:editproperties>
</code>

~~UP~~

===== Editing Properties (toggles) =====

• Example: uncomments a set of specific properties masked as a comments. All of the comments that begin with the expanded value of the ‘if.${env}.’ string will be uncommented and become active properties //without// the ‘if.${env}.’ part.
<code xml 1>
<ped:editproperties under="myconf">
  <enable like="^if\.${env}\.(.*)" replace="\1"/>
</ped:editproperties>
</code>
\\
• Example: comments out any property whose key begins with ‘java.naming’. The <toggle> operation can flip a value on or off; but in this instance, because we select only keys (i.e. non-comments), the toggle acts as a comment or disable request.
<code xml 1>
<ped:editproperties under="myconf">
  <toggle like="^java\.naming\." selector="key"/>
</ped:editproperties>
</code>

~~UP~~

===== Saving Edited Properties =====

• Example: saves a file-sourced Properties object “myconf” if there have been any changes to the original loaded information (from within Ant). The file is actually rewritten only if there was an actual change to the properties.
<code xml 1>
<ped:saveproperties under="myconf"/>
</code>
\\
• Example: saves a file-sourced Properties object “myconf” unconditionally. The file is always re-written even if there have been no changes since the properties where loaded or if the file has changed on the file system.
<code xml 1>
<ped:saveproperties under="myconf" when="always"/>
</code>
\\
• Example: saves a memory-sourced Properties object “myconf” to a local file “run.properties”. Because in-memory properties are not automatically linked to a source file, you must supply the target output file for each save (a file is not linked by the save operation).
<code xml 1>
<ped:makeproperties under="myconf"/>
[edit edit…]
<ped:saveproperties under="myconf" tofile="${out.d}/run.properties"/>
[edit edit…]
<ped:saveproperties under="myconf" tofile="${out.d}/run.properties"/>
</code>
\\
• Example: saves an existing Properties object “myconf” to a new (different) file with a custom header and timestamp. This save operation does not change the file to which the loaded properties is linked (its source file).
<code xml 1>
<ped:loadproperties under="myconf" 
     file="${ini.d}/test.properties,in"/>
[edit edit…]
<ped:saveproperties under="myconf"
     header="Generated by build process. Do NOT edit."
     datetime="$isodatetime:"
     tofile="${out.d}/test.properties"/>
</code>
\\
• Example: immediately saves results of a set of edit operations to an existing file-sourced Properties object “myconf” back to the original file.
<code xml 1>
<ped:editproperties under="myconf" save="yes">
  [edit actions here…]
</ped:editproperties>
</code>
\\
• Example: saves a copy of the Properties object under “myconf” to a different file that uses the JRE5 XML properties format. Note that any comments and blank lines are omitted in the output to the new file because these are not supported in the standard JRE functions.
<code xml 1>
<ped:loadproperties under="myconf" 
     file="${ini.d}/test.properties,in"/>
[edit edit…]
<ped:saveproperties under="myconf" 
     tofile="${out.d}/test.conf" 
     format="xml"/>
</code>

~~UP~~

===== Finding Changed Properties =====

• Example: sets a property “something.changed” if the two named in-memory Properties objects contain different property sets. Note that the comparison does not consider non-property items like blanks, comments, and declaration order!
<code xml 1>
<ped:diffproperties source="production" target="newrelease" 
    format="none" diffproperty="something.changed"/>
</code>
\\
• Example: displays the differences between two in-memory Properties objects as simple (aka //brief//) edit instructions. Only property names along with shorthand operation indicators are shown on Ant console.

<code xml 1>
<ped:diffproperties source="production" target="newrelease"
    format="brief"/>
</code>

Output sent to Ant console might look like:
<code text>
+ p: env.strict.list
~ p: env.name
~ p: env.version
+ p: reports.layouts.default
- p: layouts.default
</code>

Which means to get from “production” to “newrelease” the following changes were done:
  * Added  new property ‘env.strict.list’
  * Changed old property ‘env.name’
  * Changed old property ‘env.version’
  * Added  new property ‘reports.layouts.default’
  * Removed old property ‘layouts.default’
\\
• Example: captures the differences between two in-memory Properties objects as a set of JSON formatted edit instructions including old, new, and updated values as well as property names.

<code xml 1>
<ped:diffproperties source="production" target="newrelease" 
    format="json" tofile="${logs.d}/changed-properties.json"/>
</code>

Output sent to “changed-properties.json” file might look like (just a snippet):
<code json>
[
 {"op": "+",
  "type": "p",
  "name": "env.strict.list",
  "+": "CAT,PUB,BAK"
 },
 {"op": "~",
  "type": "p",
  "name": "env.name",
  "-": "PROD",
  "+": "PUB"
 },
 {"op": "-",
  "type": "p",
  "name": "layouts.default",
  "-": "excel-strict"
 }
]
</code>

~~UP~~

===== Copying Loaded Properties =====

• Example: copies all properties in the Properties object “myconf” that begin with ‘project.’ to the current Ant fixture as regular properties. Before copying, the item’s key is stripped of the prefix so something like “project.label” becomes just “label”.

<code xml 1>
<ped:readproperties under="myconf">
  <select like="^project\..*" to="ant.project">
    <keymapper type="glob" from="project.*" to="*"/>
  </select>
</ped:readproperties>
</code>
\\
• Example: copies all properties that begin with ‘throttle.conf.’ to an existing properties set and all properties that begin with ‘test.conf.’ to another properties set. The properties are copied as-is without modification. If any throttle properties were copied the property ‘throttle.edited’ is created and set to “true”.

<code xml 1>
<ped:readproperties under="myconf">
  <select like="^throttle\.conf\..*"
     to="throttle.properties"
     hitproperty="throttle.edited"/>
  <select like="^test\.conf\..*"
     to="test.properties"
     hitproperty="testdata.edited"/>
</ped:readproperties>
</code>
\\
• Example: reviews a set of configuration Property files defined by the “conf.files” fileset to see if there are any unresolved property values (identified by ‘${’ anywhere in value) or missing property values (identified by marker values like ‘FIXXME’ or ‘TODO’). The result of the checks are reported in another file “broken.properties” also constructed using PEd4Ant components.

<code xml 1>
<ped:makeproperties under="badd.conf" haltifexists="yes"
     filelink="${logs.d}/broken.properties"/>

<doforeach i="conf.loc" files="conf.files" tryeach="yes">
  <isolate>
    <ped:loadproperties under="next.conf" file="${conf.loc}"/>
    <ped:editproperties under="badd.conf">
      <insert value="FILE: ${conf.loc}"/>
    </ped:editproperties>
    <ped:readproperties under="next.conf" hitproperty="badd.found">
      <select like="(FIXXME|TODO)" selector="value" to="badd.conf">
        <keymapper type="glob" from="*" to="badd_*"/>
      </select>
      <select like="\$\{" selector="value" to="badd.conf">
        <keymapper type="glob" from="*" to="badd_*"/>
      </select>
    </ped:readproperties>
    <unassign reference="next.conf"/>
    <show if="badd.found" level="warning"
        message="!! Missing properties found in ${conf.loc}"/>
  </isolate>
</doforeach>

<ped:saveproperties under="badd.conf"
     header="BROKEN CONFIGURATION REPORT"
     datetime="$isodatetime:"/>

<unassign reference="badd.conf"/>
</code>

~~UP~~

===== Testing Loaded Properties =====

This example checks whether a set of properties, masked as comments, exist in a loaded Properties object “myconf”.

<code xml 1>
<ped:testproperties under="myconf"
     like="^${env}\.throttle\..*" selector="comments"
     trueproperty="throttle.enabled"/>
</code>

~~UP~~