PropertyHelper API

[Stefan Bodewig]

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@...
For additional commands, e-mail: dev-help@...

[Matt Benson]

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

> From: Stefan Bodewig <bodewig@...>
> Subject: PropertyHelper API
> To: dev@...
> 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@...
> For additional commands, e-mail: dev-help@...
>
>




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

[ddevienne]

On Tue, Sep 1, 2009 at 7:08 AM, Matt Benson<gudnabrsam@...> wrote:
>> From: Stefan Bodewig <bodewig@...>
>>     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@...
For additional commands, e-mail: dev-help@...

[Stefan Bodewig]

On 2009-09-01, Dominique Devienne <ddevienne@...> 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@...
For additional commands, e-mail: dev-help@...

[ddevienne]

On Tue, Sep 1, 2009 at 9:42 AM, Stefan Bodewig<bodewig@...> wrote:
> On 2009-09-01, Dominique Devienne <ddevienne@...> 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@...
For additional commands, e-mail: dev-help@...

[Peter Reilly-2]

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<gudnabrsam@...> wrote:

>
>
> --- On Tue, 9/1/09, Stefan Bodewig <bodewig@...> wrote:
>
>> From: Stefan Bodewig <bodewig@...>
>> Subject: PropertyHelper API
>> To: dev@...
>> 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@...
>> For additional commands, e-mail: dev-help@...
>>
>>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@...
> For additional commands, e-mail: dev-help@...
>
>

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

[Stefan Bodewig]

On 2009-09-01, Matt Benson <gudnabrsam@...> 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@...
For additional commands, e-mail: dev-help@...