Parameters redux

Jeni once wrote (http://www.w3.org/mid/45EE7802.4030706@jenitennison.com)
that we needed 'parameter sets' to adequately support parameters.

The more I think about it, the more I think she's right.

Our current story is just broken. I concede that the story is simpler to
explain and easy to implement, but it's just too fragile. Richard's
analogy with the environment in shell scripts is apt, but we don't use
the environment to pass information between shell scripts (except in
very limited circumstances) because it just doesn't work very well.

Imagine the case where someone imports a couple of libraries that
contain useful pipelines. They're happily using them for several months,
then they decide that they want to parameterize their pipeline. They add
a parameter and suddenly, because of some name collision deep in the
guts of something they imported, the output is totally wrong. (Or worse:
only very subtly wrong.)

I also think that while Alex has convinced me (mostly) that
p:http-request needs to take structured inputs, it makes sense to
support parameters for headers in the simple cases. And obviously having
every parameter appear as a header is just wrong.

Plus, we're severely limiting the design of any future component that
might want to use parameters.

In our previous design, there was the possibility of attacking this
problem with namespaces, but I'm not sure that's really going to be the
easiest thing to explain to users.

Instead, I suggest we go with Jeni's parameter-set suggestion, though
defined just a little differently.

I'm thinking parameter sets are something like XSLT attribute sets.

A parameter set defines a named collection of parameters.

  <p:pipeline>
    <p:parameter-set name="param1">
      <p:parameter name="foo" value="p1"/>
      <p:parameter name="bar" value="p1"/>
    </p:parameter-set>

A step can import those parameters by reference to their name:

    <p:xslt use-parameters="param1"/>

Parameter set are scoped. It's an error to define two parameter sets
with the same name in the same scope. If we decide that you can't refer
to other options and parameters in the same scope, then we can make it
possible for a parameter set to be extended:

    <p:group>
      <p:parameter-set name="param1" use-parameters="param1">
        <p:parameter name="bar" value="p1b"/>
        <p:parameter name="baz" value="p1"/>
      </p:parameter-set>
      <!-- now param1 has: foo=p1, bar=p1b, baz=p1 -->

      <p:parameter-set name="param2">
        <p:parameter name="foo" value="p2"/>
      </p:parameter-set>

If a step refers to more than one parameter set and those sets contain
definitions for the same parameter, the last one wins:

      <p:xslt use-parameters="param1 param2"/>
      <!-- XSLT gets foo=p2, bar=p1b, baz=p1 -->

If a step specifies both a parameter and a parameter set, the parameter
wins:

      <p:xslt use-parameters="param1 param2">
        <p:parameter name="baz" value="local"/>
      </p:xslt>
      <!-- XSLT gets foo=p2, bar=p1b, baz=local -->

I suggest that parameter set names are QNames to avoid name collisions.

The parameter sets are just a grouping convention for pipeline authors;
the pipeline processor still has a set of in-scope parameters and those
are available too. This keeps the simple case simple, at the expense of
a little complexity when they're mixed with parameter sets.

Consider:

  <p:pipeline>
    <p:xslt use-parameters="#default"/>
  </p:parameter>

That XSLT step will get all the parameters passed to the pipeline.

  <p:pipeline>
    <p:option name="format" value="html"/>
    <p:parameter-set name="params">
      <p:parameter name="output-format" select="$format"/>
    </p:parameter-set>

    <p:xslt use-parameters="params">
      <!-- this step gets the output-format parameter, but nothing else -->
    </p:xslt>

    <p:xslt use-parameters="#default">
      <!-- this step gets the pipeline parameters, but not output-format
           (at least, not from the parameter set) -->
    </p:xslt>

    <p:xslt use-parameters="#default params">
      <!-- this step gets both -->
    </p:xslt>
  </p:pipeline>

Maybe I've overlooked some corners, but this seems better to me
than the current status-quo.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Man's sensitivity to little things and
http://nwalsh.com/            | insensitivity to the greatest are the
                              | signs of a strange disorder.-- Pascal