Skip to content

Commit

Permalink
Attempt to address issue #62 add types to variables and options
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndw
ndw committed Oct 3, 2014
1 parent b74810c commit 45211e3
Show file tree
Hide file tree
Showing 16 changed files with 328 additions and 221 deletions.
10 changes: 9 additions & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,15 @@ build/langreq/Overview.html: langreq/xproc-v2-req.html
cp style/xproc.css build/langreq/
curl -s -o build/langreq/base.css http://www.w3.org/StyleSheets/TR/base.css

langspec/langspec.html: langspec/langspec.xml $(STYLES)
LANGSPECSRC=langspec/conformance.xml langspec/error-codes.xml \
langspec/glossary.xml langspec/langspec.xml \
langspec/language-summary.xml langspec/mediatype.xml \
langspec/namespace-fixup.xml langspec/parallel.xml \
langspec/references.xml \
langspec/serialization-options-for-escape-markup.xml \
langspec/serialization-options.xml langspec/standard-components.xml

langspec/langspec.html: $(LANGSPECSRC) $(STYLES)
mkdir -p build/langspec build/langspec/schemas build/langspec/ns
$(MAKE) -C schema
$(MAKE) -C langspec
Expand Down
20 changes: 13 additions & 7 deletions langspec/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,14 @@ diff.html: langspec.html
langspec.html: ,langspec.xml typed-pipeline-library.xml \
../style/docbook.xsl ../style/dbspec.xsl \
../style/xprocns.xsl ../style/rngsyntax.xsl
$(CALABASH) -isource=$< -oresult=$@ \
@echo Format spec: $@
@$(CALABASH) -isource=$< -oresult=$@ \
-pschemaext.schema=../../../../../schema/dbspec.rng \
../style/formatspec.xpl

changelog.html: changelog.xml
$(CALABASH) -isource=$< -oresult=$@ ../style/formatspec.xpl
@echo Format changelog
@$(CALABASH) -isource=$< -oresult=$@ ../style/formatspec.xpl

,langspec.xml: langspec.xml conformance.xml error-codes.xml glossary.xml \
language-summary.xml mediatype.xml namespace-fixup.xml \
Expand All @@ -33,20 +35,24 @@ changelog.html: changelog.xml
serialization-options.xml serialization-options.xml \
serialization-options.xml standard-components.xml
$(MAKE) -C examples
$(CALABASH) -isource=$< -oresult=$@ \
@echo Validate spec: $<
@$(CALABASH) -isource=$< -oresult=$@ \
../style/validate.xpl \
schema=../schema/dbspec.rng \
schematron=../schema/docbook.sch

error-list.xml: ,langspec.xml
$(SAXON) -s:$< -xsl:../style/error-list.xsl -o:$@
@echo Extract error list: $@
@$(SAXON) -s:$< -xsl:../style/error-list.xsl -o:$@

pipeline-library.xml: ,langspec.xml
$(SAXON) -s:$< -xsl:../style/pipeline-library.xsl -o:$@
@echo Extract pipeline library: $@
@$(SAXON) -s:$< -xsl:../style/pipeline-library.xsl -o:$@

typed-pipeline-library.xml: ,langspec.xml
$(SAXON) -s:$< -xsl:../style/typed-pipeline-library.xsl -o:$@
$(MAKE) -C schemas
@echo Extract typed pipeline library: $@
@$(SAXON) -s:$< -xsl:../style/typed-pipeline-library.xsl -o:$@
@$(MAKE) -C schemas

clean:
rm -f $(TARGETS) ,langspec.xml
Expand Down
182 changes: 118 additions & 64 deletions langspec/langspec.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1521,41 +1521,63 @@ specified.</para>
not violate the constraints above.</para>
</note>
</section>
<section xml:id="variables">
<title>Variables</title>
<para>Variables are name/value pairs. Pipeline authors can create variables to hold computed
values.</para>
<para><termdef xml:id="dt-variable">A <firstterm>variable</firstterm> is a name/value pair
where the name is an <link xlink:href="http://www.w3.org/TR/REC-xml-names/#dt-expname"
>expanded name</link> and the value <rfc2119>must</rfc2119> be a string or
<type>xs:untypedAtomic</type>.</termdef>
</para>
<para>Variables and options share the same scope and may shadow each other. </para>
</section>
<section xml:id="options">
<title>Options</title>
<para>Some steps accept options. Options are name/value pairs, like variables. Unlike
variables, the value of an option can be changed by the caller.</para>
<para><termdef xml:id="dt-option">An <firstterm>option</firstterm> is a name/value pair where
the name is an <link xlink:href="http://www.w3.org/TR/REC-xml-names/#dt-expname">expanded
name</link> and the value <rfc2119>must</rfc2119> be a string or
<type>xs:untypedAtomic</type>.</termdef>
</para>
<para><termdef xml:id="dt-declared-options">The options declared on a step are its
<firstterm>declared options</firstterm>.</termdef> Option names are always expressed as
literal values, pipelines cannot construct option names dynamically. </para>
<para><termdef xml:id="dt-specified-options">The options on a step which have specified
values, either because a <tag>p:with-option</tag> element specifies a value or because the
declaration included a default value, are its <firstterm>specified
options</firstterm>.</termdef>
</para>
<para><impl>How outside values are specified for pipeline options on the pipeline initially
invoked by the processor is <glossterm>implementation-defined</glossterm>.</impl> In other
words, the command line options, APIs, or other mechanisms available to specify such options
values are outside the scope of this specification.</para>
</section>

<section xml:id="variables">
<title>Variables</title>

<para>Variables are name/value pairs. Pipeline authors can create
variables to hold computed values.</para>

<para><termdef xml:id="dt-variable">A <firstterm>variable</firstterm>
is a name/value pair. The name <rfc2119>must</rfc2119> be an <link
xlink:href="http://www.w3.org/TR/REC-xml-names/#dt-expname">expanded
name</link>. The value may be any XDM value.</termdef>
</para>

<para>Variables and options share the same scope and may shadow each
other.</para>
</section>

<section xml:id="options">
<title>Options</title>

<para>Some steps accept options. Options are name/value pairs, like
variables. Unlike variables, the value of an option can be changed by
the caller.</para>

<para><termdef xml:id="dt-option">An <firstterm>option</firstterm>
is a name/value pair. The name <rfc2119>must</rfc2119> be an <link
xlink:href="http://www.w3.org/TR/REC-xml-names/#dt-expname">expanded
name</link>. The value may be any XDM value.</termdef>
</para>

<para><termdef xml:id="dt-declared-options">The options declared on a
step are its <firstterm>declared options</firstterm>.</termdef> Option
names are always expressed as literal values, pipelines cannot
construct option names dynamically. </para>

<para><termdef xml:id="dt-specified-options">The options on a step
which have specified values, either because a <tag>p:with-option</tag>
element specifies a value or because the declaration included a
default value, are its <firstterm>specified options</firstterm>.</termdef>
</para>

<para><impl>How outside values are specified for pipeline options on
the pipeline initially invoked by the processor is
<glossterm>implementation-defined</glossterm>.</impl> In other words,
the command line options, APIs, or other mechanisms available to
specify such options values are outside the scope of this
specification.</para>
</section>

<section xml:id="parameters">
<title>Parameters</title>

<note><para>This draft makes no attempt to add types to parameters because
parameters as specified here are going away. Whatever proposal is adopted
to replace this parameter mechanism should address the types of
parameters.</para></note>

<para>Some steps accept parameters. Parameters are name/value pairs, like variables and
options. Unlike variables and options, which have names known in advance to the pipeline,
parameters are not declared and their names may be unknown to the pipeline author. Pipelines
Expand Down Expand Up @@ -3336,26 +3358,43 @@ pipeline. These parameters are available on the
precedence over any default value specified in the declaration.</para>
<para>Parameters, unlike options and variables, have names that can be computed at runtime.
The most common use of parameters is to pass parameter values to XSLT stylesheets.</para>
<section xml:id="p.variable"><title>p:variable</title><para>A <tag>p:variable</tag> declares a
variable and associates a value with it.</para>
<para>The name of the variable
<rfc2119>must</rfc2119> be a QName. If it does not contain a prefix then it is in no
namespace. <error code="S0028">It is a <glossterm>static error</glossterm> to declare an
option or variable in the XProc namespace.</error>
</para>
<para>The variable's value is specified with a <tag class="attribute">select</tag>
attribute. The <tag class="attribute">select</tag> attribute <rfc2119>must</rfc2119> be
specified. The content of the <tag class="attribute">select</tag> attribute is an XPath
expression which will be evaluated to provide the value of the variable.</para>
<e:rng-pattern name="VariableSelect"/>

<section xml:id="p.variable">
<title>p:variable</title>

<para>A <tag>p:variable</tag> declares a variable and associates a
value with it. Variable declarations may optionally specify the type
of the variable using an XPath Sequence Type.</para>

<para>The name of the variable <rfc2119>must</rfc2119> be a QName. If
it does not contain a prefix then it is in no namespace. <error
code="S0028">It is a <glossterm>static error</glossterm> to declare an
option or variable in the XProc namespace.</error>
</para>

<para>The variable's value is specified with a <tag
class="attribute">select</tag> attribute. The <tag
class="attribute">select</tag> attribute <rfc2119>must</rfc2119> be
specified. The content of the <tag class="attribute">select</tag>
attribute is an XPath expression which will be evaluated to provide
the value of the variable.</para>

<e:rng-pattern name="VariableSelect"/>

<para>If a <tag class="attribute">select</tag> expression is given, it
is evaluated as an XPath expression using the appropriate context as
described in <xref linkend="xpath-context"/>, for the enclosing
<glossterm>container</glossterm>, with the addition of bindings for
all preceding-sibling <tag>p:variable</tag> and <tag>p:option</tag>
elements. Regardless of the implicit type of the expression, the type
is treated as an <type>xs:untypedAtomic</type>.</para>
elements.</para>

<para>The type of the value may be specified in the <tag
class="attribute">as</tag> attribute using an XPath Sequence
Type<superscript>[citation needed]</superscript>. If an atomic type,
or sequence of atomic types, is specified, the value provided for the
option will be atomized according to the standard XPath rules. It is
an error, err:FIXME, if the computed value does not match the
specified sequence type.</para>

<para>Since all <glossterm>in-scope bindings</glossterm> are present
in the Processor XPath Context as variable bindings, <tag
Expand All @@ -3365,25 +3404,24 @@ variable reference uses a QName that is not the name of an <glossterm
baseform="in-scope bindings">in-scope binding</glossterm>, an XPath
evaluation error will occur.</para>

<para>If a <tag
class="attribute">select</tag> expression is given, the <glossterm>readable
ports</glossterm> available for document connections are the <glossterm>readable
ports</glossterm> in the environment inherited by the first step in the surrounding
<glossterm>container</glossterm>'s <glossterm>contained steps</glossterm>. However, in
order to avoid ordering paradoxes, <error code="S0019">it is a <glossterm>static
error</glossterm> for a variable's document connection to refer to the output port of
any step in the surrounding <glossterm>container</glossterm>'s <glossterm>contained
steps</glossterm></error>.</para>
<para>If a <tag class="attribute">select</tag> expression is given,
the <glossterm>readable ports</glossterm> available for document
connections are the <glossterm>readable ports</glossterm> in the
environment inherited by the first step in the surrounding
<glossterm>container</glossterm>'s <glossterm>contained
steps</glossterm>. However, in order to avoid ordering paradoxes,
<error code="S0019">it is a <glossterm>static error</glossterm> for a
variable's document connection to refer to the output port of any step
in the surrounding <glossterm>container</glossterm>'s
<glossterm>contained steps</glossterm></error>.</para>

<para>If a <tag class="attribute">select</tag> expression is given but
no document connection is provided, the implicit connection is to the
<glossterm>default readable port</glossterm> in the environment
inherited by the first step in the surrounding
<glossterm>container</glossterm>'s <glossterm>contained
steps</glossterm>.
If there is no default
readable port, the connection is treated as if <tag>p:empty</tag> was
specified.</para>
steps</glossterm>. If there is no default readable port, the
connection is treated as if <tag>p:empty</tag> was specified.</para>

<para><error code="D0008">It is a <glossterm>dynamic error</glossterm>
if a sequence of more than one document appears on the connection for
Expand All @@ -3394,8 +3432,6 @@ the <tag class="attribute">select</tag> expression makes reference to
the context node, size, or position when the context item is
undefined.</error>
</para>


</section>

<!-- ============================================================ -->
Expand All @@ -3419,6 +3455,14 @@ name.</error></para>

<e:rng-pattern name="OptionDeclaration"/>

<para>An option may declare its type. The type is specified in the
<tag class="attribute">as</tag> attribute using an XPath Sequence
Type<superscript>[citation needed]</superscript>. If an atomic type,
or sequence of atomic types, is specified, the value provided for the
option will be atomized according to the standard XPath rules. It is
an error, err:FIXME, if the computed value does not match the
specified sequence type</para>

<para>An option may be declared as <tag
class="attribute">required</tag>. <error code="S0018">If an option is
required, it is a <glossterm>static error</glossterm> to invoke the
Expand Down Expand Up @@ -3499,8 +3543,13 @@ the value of the variable.</para>

<e:rng-pattern name="WithOptionSelect"/>

<para>Regardless of the implicit type of the expression, the value is
an <type>xs:untypedAtomic</type>.</para>
<para>The type of the value may be specified in the <tag
class="attribute">as</tag> attribute using an XPath Sequence
Type<superscript>[citation needed]</superscript>. If an atomic type,
or sequence of atomic types, is specified, the value provided for the
option will be atomized according to the standard XPath rules. It is
an error, err:FIXME, if the computed value does not match the
specified sequence type</para>

<para>All <glossterm>in-scope bindings</glossterm> for the step
instance itself are present in the Processor XPath Context as variable
Expand Down Expand Up @@ -3535,6 +3584,11 @@ undefined.</error>
<section xml:id="p.with-param">
<title>p:with-param</title>

<note><para>This draft makes no attempt to add types to parameters because
parameters as specified here are going away. Whatever proposal is adopted
to replace this parameter mechanism should address the types of
parameters.</para></note>

<para>The <tag>p:with-param</tag> element is used to establish the
value of a parameter. The parameter <rfc2119>must</rfc2119> be given a
value when it is used. (Parameter names aren't known in advance;
Expand Down
9 changes: 6 additions & 3 deletions langspec/ns-c/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,19 @@ TARGETS=xproc-step.html ns-xproc-c-incl.xml
all: $(TARGETS)

xproc-step.html: ,xproc-step.xml
$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@
@echo Format spec: $@
@$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@

,xproc-step.xml: xproc-step.xml ns-xproc-c-incl.xml \
../../style/docbook.xsl ../../style/dbspec.xsl \
../../style/xprocns.xsl ../../style/rngsyntax.xsl
$(CALABASH) -isource=$< -oresult=$@ \
@echo Validate spec: $<
@$(CALABASH) -isource=$< -oresult=$@ \
../../style/validate.xpl schema=../../schema/dbspec.rng

ns-xproc-c-incl.xml: ../,langspec.xml ../../style/ns-extract.xsl
$(SAXON) -s:$< -xsl:../../style/ns-extract.xsl -o:$@ prefix=c:
@echo Extract names from $<
@$(SAXON) -s:$< -xsl:../../style/ns-extract.xsl -o:$@ prefix=c:

clean:
rm -f $(TARGETS) ,xproc-step.xml
9 changes: 6 additions & 3 deletions langspec/ns-err/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,22 @@ TARGETS=xproc-error.html error-list.xml
all: $(TARGETS)

xproc-error.html: ,xproc-error.xml
$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@
@echo Format spec: $@
@$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@

# Cannot validate schema=../../schema/dbspec.rng
# Fix it so that it validates!
,xproc-error.xml: xproc-error.xml error-list.xml \
../../style/docbook.xsl ../../style/dbspec.xsl \
../../style/xprocns.xsl ../../style/rngsyntax.xsl
@echo Validate spec: $<
@echo FIXME: make this validate
$(CALABASH) -isource=$< -oresult=$@ \
@$(CALABASH) -isource=$< -oresult=$@ \
../../style/validate.xpl schema=../../schema/dbspec.rng

error-list.xml: ../,langspec.xml ../../style/error-list.xsl
$(SAXON) -s:$< -xsl:../../style/error-list.xsl -o:$@
@echo Extract names from $<
@$(SAXON) -s:$< -xsl:../../style/error-list.xsl -o:$@

clean:
rm -f $(TARGETS) ,xproc-error.xml
9 changes: 6 additions & 3 deletions langspec/ns-p/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,19 @@ TARGETS=xproc.html ns-xproc-p-incl.xml
all: $(TARGETS)

xproc.html: ,xproc.xml
$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@
@echo Format spec: $@
@$(SAXON) -s:$< -xsl:../../style/dbspec.xsl -o:$@

,xproc.xml: xproc.xml ns-xproc-p-incl.xml \
../../style/docbook.xsl ../../style/dbspec.xsl \
../../style/xprocns.xsl ../../style/rngsyntax.xsl
$(CALABASH) -isource=$< -oresult=$@ \
@echo Validate spec: $<
@$(CALABASH) -isource=$< -oresult=$@ \
../../style/validate.xpl schema=../../schema/dbspec.rng

ns-xproc-p-incl.xml: ../,langspec.xml ../../style/ns-extract.xsl
$(SAXON) -s:$< -xsl:../../style/ns-extract.xsl -o:$@
@echo Extract names from $<
@$(SAXON) -s:$< -xsl:../../style/ns-extract.xsl -o:$@

clean:
rm -f $(TARGETS) ,xproc.xml
Expand Down
Loading

0 comments on commit 45211e3

Please sign in to comment.