ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Benson <gudnabr...@yahoo.com>
Subject Re: PropertyHelper API
Date Tue, 01 Sep 2009 12:08:29 GMT


--- On Tue, 9/1/09, Stefan Bodewig <bodewig@apache.org> wrote:

> From: Stefan Bodewig <bodewig@apache.org>
> Subject: PropertyHelper API
> To: dev@ant.apache.org
> Date: Tuesday, September 1, 2009, 4:59 AM
> 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.

Note that the props antlib does provide a NestedPropertyExpander, so you're right on track.

> 
>   * 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?)?
> 

The NullReturn thing, IIRC, was added by Peter.  But I think you're correct about it.  Everything
else sounds correct and complete as well; my proverbial hat is off to you for having compiled
this comprehensive piece of documentation.

-Matt

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


      

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


Mime
View raw message