ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Bodewig <bode...@apache.org>
Subject PropertyHelper API
Date Tue, 01 Sep 2009 09:59:52 GMT
Hi

I'm trying to grok the changes to the PropertyHelper in order to
document them for 1.8.0 - and maybe to suggest throwing in some more
built-in delegates, but that's for a different thread.

>From what I understand:

The default PropertyHelper splits its work into several steps that can
be delegated to custom implementations.  These steps are:

  * finding a property reference inside a string.

    The delegate interface is oata.property.PropertyExpander.

    There are two built-in expanders, one that finds ${foo} positions
    the parser after the '}' and says "here is property "foo"' and one
    that finds $$, positions the parser after the second $ (actually at
    the second $) and says "no property to be seen here".

    This is the interface I'd implement if I wanted a completely
    different property syntax.  I'd also need to implement it if I
    wanted to allow nested properties ${${foo}} since the default
    PropertyExpander doesn't balance braces.

  * mapping a property to a value

    The delegate interface is oata.PropertyHelper.PropertyEvaluator.

    There are two built-in implementations, one implements local
    properties and one implements the "toString: protocol",
    i.e. ${toString:some-refid} => find-reference-in-project.toString()

    This is the interface I'd implement if I

    - want to provide a different "protocol" like toString:

    - want to provide a different storage for properties, this would be
      the reading part of it.

    "Normal" project properties are not implemented via
    PropertyEvaluator but implemented via fallback mechanisms in the
    default PropertyHelper implementation.

    PropertyEvaluator can return Object but it will be turned into a
    String unless the whole string that was expanded is consumed by the
    property (i.e. "${foo}" can become an Object while "${foo} bar" van
    not).

    PropertyEvaluator can return an instance of the magical
    oata.property.NullReturn class which means "I really really mean it
    when I say the property expands to null" because simply returning
    null means "I don't know this property".

  * storing the value for a property somewhere

    The delegate interface is oata.PropertyHelper.PropertySetter.

    The only built-in implementation is for local properties.

    This is the interface I'd implement if I

    - want to provide a different storage for properties, this would be
      the writing part of it.

    "Normal" project properties are not implemented via
    PropertySetter but implemented via fallback mechanisms in the
    default PropertyHelper implementation.

    PropertySetter returns a flag indicating whether it has consumed the
    property - otherwise the other delegates are consulted and
    ultimately the fallback to project properties is used.

The <properthelper> task can be used to register custom delegates.
Delegates are used in LIFO order that is custom delegates are able to
override built-in delegates.

Is this correct and somewhat complete (Matt?)?

Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message