[augeas-devel] [PATCH 1/2] Add doc about square lens

[David Lutterkort]

On Mon, 2011-02-21 at 23:08 -0500, Francis Giraldeau wrote:
> ---
>  pages/docs/lenses.txt |   10 ++++++++--
>  1 files changed, 8 insertions(+), 2 deletions(-)

ACK - committed with a bit of rewording (see below) But kudos for making
your way through how the website is generated (which is in desparate
need of improvement)

The changes will be pushed live with the next release.

> @@ -90,6 +90,12 @@ are either regular expressions, indicated by ``RE`` or strings indicated by
>    subtree.
>  ``label STR``
>    Use the string ``STR`` as the label of the enclosing subtree.
> +``square RE LENS``
> +  Match the concatenation of ``RE . LENS . RE`` in the *get* direction. The
> +  first ``RE`` is used as the label of the enclosing subtree, while the ending
> +  ``RE`` doesn't appear in the tree. In the *put* direction, the node's label
> +  is copied to both sides of ``LENS``. This lens generates palindrome strings
> +  and is intended for tag based configurations like XML.

Strictly speaking, square is a combinator, since it takes a lens and
produces another lens - I moved it into the combinator section. I also
reworded this as:

        Produce the same effect as key RE . LENS . del STR STR with the
        constraint that STR is the string matched by key RE. This lens
        makes it possible to process (generalized) squares, words of the
        form uvu; a matching square lens would transform uvu into a tree
        with a root labelled with u and children produced by processing
        v with LENS. This lens makes it possible to process SGML-style
        languages like XML in a very general fashion; in particular, it
        is possible to write lenses that accept an infinte number of
        different tags.
        
I am sure this can be improved further - let me know,
David