Parameters

Hello world,

Notwithstanding the fact that there is considerable discussion
occurring right now about how XProc should deal with a variety of
large issues, at the Edinburgh face-to-face, those assembled settled
on the following proposal for simplifying parameters.

Parameters

The following proposal attempts to address the use case for parameters
in the simplest way possible.

Anticipated pre-conditions:

  a. The XProc expression language adopts the XSLT 3.0 extensions
     for maps.
  b. The XProc vocabulary adopts the XSLT 3.0 convention of specifying
     option (and variable) types with an "as" attribute.
  c. The XProc language extends the value of shortcut options to include
     AVTs. AVTs return a string value.

In this proposal, there are no parameter ports, there are no special
rules associated with parameters.

1. There is a new function, p:parameters. It takes a single string
   argument and returns a map from QNames to XDM item values.

   p:parameters() as map:map(xs:Qname, item()*)
   p:parameters($name as xs:string) as map:map(xs:QName, item()*)

   The function p:parameters() is a shortcut for p:parameters('')

   The map returned by the p:parameters function is
   implementation-defined. An implementation can initialize the XProc
   environment with any number of such named maps through APIs that
   are out the scope of the XProc specification.

   An implementation that is invoked from the command line, for
   example, might provide command line switches for setting values in
   the parameter maps. For example:

       calabash -p foo=bar -p other:foo=baz -p struct=@foo.xml

   might create two maps. One, named '', containing two keys, 'foo'
   and 'struct' initialized respectively to the values "bar" and the
   XML document in foo.xml. The second, named 'other' containing a
   single key mapping 'foo' to "baz".

2. Steps, like XSLT, that use parameters declare a parameters option
   for this purpose:

   <p:declare-step type="p:xslt">
     <p:option name="parameters" select="p:parameters()"
               as="map:map(xs:QName, item()*)?"/>

   Because the default value of the parameters option is the p:parameters()
   function, options specified to the pipeline will still, by defualt,
   pass through to the step.

   Authors who wish to block this behavior, can do so by setting the
   value of the parameters option explicitly.

     <p:xslt>
       <p:with-option name="parameters" select="()"/>

   Authors can construct new maps using XPath. XPath provides sufficient
   expressive power to encompass the current ability to control map
   behavior.

   You can, for example, override the value of a parameter:

     <p:xslt>
       <p:with-option name="parameters"
                      select="map:new((p:parameters(),
                                       map:entry('root.path', '/tmp/x')))"/>

   or allow a parameter passed from the environment to override a
   default value:

     <p:xslt>
       <p:with-option name="parameters"
                      select="map:new((map:entry('root.path', '/tmp/x'),
                                       p:parameters()))

   Authors have complete freedom to adjust the value of the parameters
   option in any way that they like.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh
Lead Engineer
MarkLogic Corporation
Phone: +1 512 761 6676
www.marklogic.com