mod_substitute docs

Hullo,

I'm attempting to document this module but can't figure out
what the f
(flatten) flag does (bucket brigade munging makes my eyes
cross). Any
clues?

Here's a start anyway:

ht
tp://people.apache.org/~noodl/mod_substitute.xml

-- 
noodl

On Oct 20, 2007, at 4:59 PM, Vincent Bray wrote:

> Hullo,
>
> I'm attempting to document this module but can't figure
out what the f
> (flatten) flag does (bucket brigade munging makes my
eyes cross). Any
> clues?
>

Say you are looking for 'foo' and have a bucket that
contains 'jimfoojag'. The fast way to handle this would
be to split off 3 buckets from this, one containing
'jim', the other containing 'jag' and the middle one that
contains the substitute for 'foo' (say it's 'bar'). The rub
is that the pattern matching looks at buckets only, so you
wouldn't see a full bucket that contains 'jimbarjag' and
so if you had a search for 'mbarj', it would be missed
using
the "fast way". In the slow way (flattening),
instead
of creating the 3 buckets, you go ahead and smash them all
together resulting in the single bucket that now contains
'jimbarjag'. Now the search for 'mbarj' would succeed.

> Here's a start anyway:
>
> ht
tp://people.apache.org/~noodl/mod_substitute.xml
>
> -- 
> noodl
>

On 22/10/2007, Jim Jagielski <jimjagunet.com> wrote:
> Say you are looking for 'foo' and have a bucket that
> contains 'jimfoojag'. The fast way to handle this
would
> be to split off 3 buckets from this, one containing
> 'jim', the other containing 'jag' and the middle one
that
> contains the substitute for 'foo' (say it's 'bar'). The
rub
> is that the pattern matching looks at buckets only, so
you
> wouldn't see a full bucket that contains 'jimbarjag'
and
> so if you had a search for 'mbarj', it would be missed
using
> the "fast way". In the slow way (flattening),
instead
> of creating the 3 buckets, you go ahead and smash them
all
> together resulting in the single bucket that now
contains
> 'jimbarjag'. Now the search for 'mbarj' would succeed.

That's much clearer now, thanks. I've committed my first
shot, so
please give it a critical eye. Is there a need to add
further
explaination of 'f' here? Also, surely there's a less
contrived
example than s/foo/bar/..

-- 
noodl

On Oct 22, 2007, at 12:57 PM, Vincent Bray wrote:

> On 22/10/2007, Jim Jagielski <jimjagunet.com> wrote:
>> Say you are looking for 'foo' and have a bucket
that
>> contains 'jimfoojag'. The fast way to handle this
would
>> be to split off 3 buckets from this, one
containing
>> 'jim', the other containing 'jag' and the middle
one that
>> contains the substitute for 'foo' (say it's 'bar').
The rub
>> is that the pattern matching looks at buckets only,
so you
>> wouldn't see a full bucket that contains
'jimbarjag' and
>> so if you had a search for 'mbarj', it would be
missed using
>> the "fast way". In the slow way
(flattening), instead
>> of creating the 3 buckets, you go ahead and smash
them all
>> together resulting in the single bucket that now
contains
>> 'jimbarjag'. Now the search for 'mbarj' would
succeed.
>
> That's much clearer now, thanks. I've committed my
first shot, so
> please give it a critical eye. Is there a need to add
further
> explaination of 'f' here? Also, surely there's a less
contrived
> example than s/foo/bar/..
>

I guess the big issue is that if one expects to
substitute previously substituted items, then one
should use flatten, but it results in much slower behavior.
If the substitutions are self-contained, and can't
"overlap" each other, then the default is fine and
fast.

So:

     s/foo/bur/
     s/burp/belch/

and you want 'I fooped' to be changed
to 'I burped' -> 'I belched' then you need
flatten.

Jim Jagielski wrote:
> 
> Say you are looking for 'foo' and have a bucket that
> contains 'jimfoojag'. The fast way to handle this
would
> be to split off 3 buckets from this, one containing
> 'jim', the other containing 'jag' and the middle one
that
> contains the substitute for 'foo' (say it's 'bar'). The
rub
> is that the pattern matching looks at buckets only, so
you
> wouldn't see a full bucket that contains 'jimbarjag'
and
> so if you had a search for 'mbarj', it would be missed
using
> the "fast way". In the slow way (flattening),
instead
> of creating the 3 buckets, you go ahead and smash them
all
> together resulting in the single bucket that now
contains
> 'jimbarjag'. Now the search for 'mbarj' would succeed.

I'm a little concerned if the module ships /without/ the
'f'latten flag
triggered by default.  I'd rather the module offered the
inverse option.

This is truly a 'bug' users won't understand (my text
contains 'jimfoojag',
why isn't it translating to 'jimbarjag'?!?)

And it's an implementation detail that should be kept from
the user 99% of
the time.  So what if we offer a 'f'ast or 'o'ptimized
bucket-only flag
for users who want to get it trouble (works with one
generator and not some
other, or works until a filter is inserted, or whatever)?

Bill

On Oct 22, 2007, at 1:42 PM, William A. Rowe, Jr. wrote:

> Jim Jagielski wrote:
>> Say you are looking for 'foo' and have a bucket
that
>> contains 'jimfoojag'. The fast way to handle this
would
>> be to split off 3 buckets from this, one
containing
>> 'jim', the other containing 'jag' and the middle
one that
>> contains the substitute for 'foo' (say it's 'bar').
The rub
>> is that the pattern matching looks at buckets only,
so you
>> wouldn't see a full bucket that contains
'jimbarjag' and
>> so if you had a search for 'mbarj', it would be
missed using
>> the "fast way". In the slow way
(flattening), instead
>> of creating the 3 buckets, you go ahead and smash
them all
>> together resulting in the single bucket that now
contains
>> 'jimbarjag'. Now the search for 'mbarj' would
succeed.
>
> I'm a little concerned if the module ships /without/
the 'f'latten  
> flag
> triggered by default.  I'd rather the module offered
the inverse  
> option.
>
> This is truly a 'bug' users won't understand (my text
contains  
> 'jimfoojag',
> why isn't it translating to 'jimbarjag'?!?)
>

It would... it's only an issue really if there are
subsequent
substitutions *and* a previous substitution would result in
a string that would also be affected by a latter one.

> And it's an implementation detail that should be kept
from the user  
> 99% of
> the time.  So what if we offer a 'f'ast or 'o'ptimized
bucket-only  
> flag
> for users who want to get it trouble (works with one
generator and  
> not some
> other, or works until a filter is inserted, or
whatever)?
>
> Bill
>

Den Saturday 20 October 2007 22.59.58 skrev Vincent Bray:
> Hullo,
>
> I'm attempting to document this module but can't figure
out what the f
> (flatten) flag does (bucket brigade munging makes my
eyes cross). Any
> clues?
>
> Here's a start anyway:
>
> ht
tp://people.apache.org/~noodl/mod_substitute.xml

It never made it for 2.2.x?

-- 
Regards // Oden Eriksson