RE: Parameters

> Let's consider the requirement for parameters and some use cases.
> 
> The requirement: in the simple case where the pipeline author does
> nothing with (may even be entirely ignorant of) parameters, users can
> still pass parameters to steps in the pipeline.
> 
> In other words, given this pipeline:
> 
> <p:declare-step version="1.0" name="main" type="ex:simple"
>                 xmlns:p="http://www.w3.org/ns/xproc">
>   <p:input port="source"/>
>   <p:output port="result"/>
> 
>   <p:xinclude/>
> 
>   <p:xslt>
>     <p:input port="stylesheet">
>       <p:document href="style.xsl"/>
>     </p:input>
>   </p:xslt>
> </p:declare-step>
> 
> It must be possible for users to pass parameters to the contained XSLT
> step. This is the requirement that forces us to indulge in some sort of
> magic. The whole magic binding of parameter input ports in V1 is based
> on this requirement.

OK. I have not been with the WG since the very beginning, so if this has always been a hard requirement, then I give up.

(Btw, do we all agree that the above pipeline is invalid (the primary parameter port of p:xslt is unconnected) - but even if it were valid, that the user cannot pass any parameters to the pipeline, because it has no parameter ports?)

The way I see the above example is this (and it actually feels natural to me): ex:simple has no parameter input port, therefore the user cannot pass any parameters to it (nor to the stylesheet). However, if I - as the pipeline author - am aware that the stylesheet takes parameters AND I DO WANT to give the user the ability to pass parameters to the stylesheet, I may decide to add a parameter input port to the main pipeline. On the other hand, if the stylesheet takes parameters BUT I DON'T WANT the user to pass any parameters to it, I simply don't add a parameter port to the pipeline.

> If we abandon this requirement, then a solution like the one that
> Vojtech proposes becomes the only option available to the pipeline
> author and there is no magic.

There would still remain enough magic in the world.

> It also means that the vast majority of pipelines will *not* accept
> *any* parameters because the pipeline author will never have thought of
> it.

I prefer a situation where pipelines accept parameters because the pipeline author has thought about it.

> 
> <aside>
>   There are are some things that bother me about Vojtech's proposal,
>   including one substantive error. Vojtech proposes:
> 
>   <p:declare-step>
>     <p:input port="source"/>
>     <p:output port="source"/>
>     <p:option name="xquery-params" as="map:map(xs:QName, item()*)?"/>
>     <p:option name="xslt-params" as="map:map(xs:QName, item()*)?"/>
> 
>   All well and good so far, but analyzing that pipeline and working
>   out what the valid command line options may be looks pretty
>   daunting. Made even more daunting by the fact that option names are
>   QNames. I don't doubt that it could be done, but it looks pretty
>   ugly.

Maybe. But we use QNames for regular options already. And besides, I think that in most cases, these QNames aren't in a namespace anyway.

>From the processor perspective, a V2 processor will probably have to inspect the declared pipeline options and their types anyway before it can pass the user-provided option values to the pipeline. So it will know that option 'foo' is actually a map, and it will fail if the user supplies a value that the processor cannot represent as a map. But this is completely impl-defined area in my view.

> 
>   The Edinburgh proposal says that there are named hashmaps that come
>   from the outside environment. No pipeline inspection is required to
>   determine what a valid command line (or API) would be.
> 
>     <p:xquery parameters="$xquery-params">
> 
>   And you can't do that. Even assuming the AVT "{$xquery-params}" was
>   intended, it doesn't work. AVTs have to produce single
> (untypedAtomic)
>   value. If you want to pass a map to a step, you have to do it the
>   long way:
> 
>     <p:xquery>
>       <p:with-option name="parameters" select="$xquery-params"/>
> </aside>

Fair enough. I didn't know that.

> The only thing you don't get, really, is the ability to control the
> parameters used by a third party pipeline that was written without
> thinking about parameters.

Yes. I am just worried that we are being a bit too optimistic here (in the "it will work out somehow" sense) about what can go wrong with this setup.

> 
> In fact, that is, I think, the only thing we've lost.
> 
> Going back to the ex:simple pipeline above, there's nothing the caller
> can do to change which parameters are used by that pipeline.

Well, the user cannot pass any parameters to ex:simple in V1.

> 
> I think the 80% case, maybe the 95% case, is that no parameters are
> passed to the pipeline *at all*. In which case, it doesn't matter what
> control we could have had.

All the more reason to make "no support for parameters by default" the default :)

> You might think that we've also lost the ability to distinguish which
> parameters go to which steps. If pipeline authors don't think about
> parameters, then all steps that accept parameters get the same
> parameters.
> 
> That's actually the case even in V1.0. The single primary parameter
> port feeds all the steps by default. As above, most of the time there
> are no parameters and it doesn't matter.

Yes. But is it right?

> 
> In fact, it only matters in the single case where there are two or more
> steps that accept parameters in the pipeline and they have parameter
> names that collide, *and*, someone has, in practice, specified a value
> for one of the colliding parameters.
> 
> On balance, and considering the *enormous* syntactic and semantic
> simplifications it carries with it, I think the Edinburgh proposal is
> "good enough".

Having no magic for parameters makes things even simpler :)

But honestly, I see the benefits of the proposal, I am just worried about three things:

1. The maintainability if you depend on 3rd-party pipelines
2. That we may be trading one complex/confusing V1 concept (parameter input ports) for another (named parameter maps, and  p:parameter-map() lurking in the option declarations)
3. Do we really need all of this?

So for my part, I still give it +0

Regards,
Vojtech

--
Vojtech Toman
Consultant Software Engineer
EMC | Information Intelligence Group
vojtech.toman@emc.com
http://developer.emc.com/xmltech

Received on Thursday, 6 March 2014 14:04:14 UTC