--- On Tue, 9/1/09, Stefan Bodewig <bode...@apache.org> wrote:
> From: Stefan Bodewig <bode...@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-unsubscr...@ant.apache.org
> For additional commands, e-mail: dev-h...@ant.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@ant.apache.org
For additional commands, e-mail: dev-h...@ant.apache.org
