You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Stefan Bodewig <bo...@apache.org> on 2009/09/01 11:59:52 UTC
PropertyHelper API
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
Re: PropertyHelper API
Posted by Dominique Devienne <dd...@gmail.com>.
On Tue, Sep 1, 2009 at 9:42 AM, Stefan Bodewig<bo...@apache.org> wrote:
> On 2009-09-01, Dominique Devienne <dd...@gmail.com> wrote:
>
>> What I don't get is how NestedPropertyExpander can be enabled.
>> Given how DEFAULT_EXPANDER works, if one tries to add
>> NestedPropertyExpander after it, the first expander will not allow
>> the second to work.
>
> You missed the "delegates get used in LIFO order" bit. add() adds to
> the front of the list.
Ah yes, thank you Stefan. --DD
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: PropertyHelper API
Posted by Stefan Bodewig <bo...@apache.org>.
On 2009-09-01, Dominique Devienne <dd...@gmail.com> wrote:
> What I don't get is how NestedPropertyExpander can be enabled.
> Given how DEFAULT_EXPANDER works, if one tries to add
> NestedPropertyExpander after it, the first expander will not allow
> the second to work.
You missed the "delegates get used in LIFO order" bit. add() adds to
the front of the list.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: PropertyHelper API
Posted by Dominique Devienne <dd...@gmail.com>.
On Tue, Sep 1, 2009 at 7:08 AM, Matt Benson<gu...@yahoo.com> wrote:
>> From: Stefan Bodewig <bo...@apache.org>
>> 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.
protected PropertyHelper() {
add(TO_STRING);
add(SKIP_DOUBLE_DOLLAR);
add(DEFAULT_EXPANDER);
}
What I don't get is how NestedPropertyExpander can be enabled.
Given how DEFAULT_EXPANDER works, if one tries to add
NestedPropertyExpander after it, the first expander will not allow
the second to work.
So one's supposed to extend PropertyHelper and do different adds?
Given that the 3 default expanders are private, one can't reuse them.
On a side note, I find it a bit non-symetrical to have PropertyExpander
in oata.property, while PropertyEvaluator & PropertySetter has nested
interfaces in PropertyHelper.
Finally, I'm not sure I understand PropertyExpander and its
ParseNextProperty arg. The interface gives me the impression that to
do nested property parsing, one must mix the parsing and evaluation
phases since parsePropertyName has to return a property name; thus
${foo${bar}} must evaluate ${bar} during parsing to be able to return
"foo1" if bar is "1".
I would have preferred the parsing to perform more akin to a compilation
phase, returning a little "program" (kinda like a little executable AST) which
is fully "un-evaluated", and can be evaluated fully given a particular execution
context.
Maybe that's useless in the context of Ant, where almost everything
happens dynamically at runtime, but it somehow bothers me that we
don't clearly separate parsing from evaluation. Just my $0.02. --DD
PS: Note that it's entirely possible I missed something. I had a quick
look only.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: PropertyHelper API
Posted by Peter Reilly <pe...@gmail.com>.
Yes, I think that I added the null return to allow local properties.
Peter
On Tue, Sep 1, 2009 at 1:08 PM, Matt Benson<gu...@yahoo.com> wrote:
>
>
> --- On Tue, 9/1/09, Stefan Bodewig <bo...@apache.org> wrote:
>
>> From: Stefan Bodewig <bo...@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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: PropertyHelper API
Posted by Stefan Bodewig <bo...@apache.org>.
On 2009-09-01, Matt Benson <gu...@yahoo.com> wrote:
> Note that the props antlib does provide a NestedPropertyExpander, so
> you're right on track.
Thanks, I've modified the documentation to link to it.
> The NullReturn thing, IIRC, was added by Peter.
Now documented explicitly.
Thanks for checking
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: PropertyHelper API
Posted by Matt Benson <gu...@yahoo.com>.
--- On Tue, 9/1/09, Stefan Bodewig <bo...@apache.org> wrote:
> From: Stefan Bodewig <bo...@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