Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvements to p:ixml #604

Merged
merged 4 commits into from
Aug 1, 2024
Merged

Improvements to p:ixml #604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7a6c0ce
Integrate step-ixml into the build process
ndw Aug 1, 2024
69b233f
Fix #547 by adding new error codes
ndw Aug 1, 2024
26bd76a
Clarify grammar content types (per new errors)
ndw Aug 1, 2024
ce0c9d3
Attempt to resolve #494
ndw Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@ task make_etc() {

["steps", "step-file", "step-os", "step-paged-media",
"step-run", "step-text", "step-mail", "step-rdf", "step-validation",
"step-ixml"
].each { spec ->
Task t = task "copy_${spec}_build"(dependsOn: [ "buildspecs" ], type: Copy) {
from "$spec/build/"
Expand Down Expand Up @@ -653,6 +654,58 @@ task step_mail_xpl(dependsOn: ["step-mail:library"], type: Copy) {
rename ("library.xml", "steps.xpl")
}

// ======================================================================
// step-ixml

task step_ixml(type: DocBookTask,
dependsOn: [ "download_xproc_toc",
"steps", "xproc_schemas", "spec_schemas",
"step-ixml:specification",
"step_ixml_assets",
"step_ixml_src", "step_ixml_xpl" ]) {
inputs.files fileTree(dir: "tools/xsl/")
inputs.files fileTree(dir: "tools/xpl/")
inputs.file "build/xproc/toc.xml"
input("source", "step-ixml/build/source.xml")
output("result", "build/dist/ixml/index.html")

param("schemaext.schema", file("build/schema/dbspec.rng"))
param("ci", getenv("CIWORKFLOW"))
param("ci-commit", getenv("CI_SHA1"))
param("ci-build-number", getenv("CI_BUILD_NUM"))
param("ci-user", getenv("CI_PROJECT_USERNAME"))
param("ci-repo", getenv("CI_PROJECT_REPONAME"))
param("ci-branch", getenv("CI_BRANCH"))
param("ci-tag", getenv("CI_TAG"))

option("style", file("tools/xsl/xproc-specs.xsl"))
option("diff", deltaxml())
option("specid", "ixml")
option("diffloc", buildAbsDir + "/ixml/diff.html")

pipeline "tools/xpl/formatspec.xpl"
}
buildspecs.dependsOn "step_ixml"

task step_ixml_assets(type: Copy) {
from "src/main/resources"
into "build/dist/ixml/"
}

task step_ixml_src(dependsOn: ["step-ixml:source"], type: Copy) {
from "step-ixml/build/"
into "build/dist/ixml/"
include "source.xml"
rename ("source.xml", "specification.xml")
}

task step_ixml_xpl(dependsOn: ["step-ixml:library"], type: Copy) {
from "step-ixml/build/"
into "build/dist/ixml/"
include "library.xml"
rename ("library.xml", "steps.xpl")
}

// ======================================================================
// Clean up

Expand Down
2 changes: 1 addition & 1 deletion settings.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
include 'steps', 'step-validation', 'step-os', 'step-paged-media', 'step-run',
'step-file', 'step-text', 'step-mail'
'step-file', 'step-text', 'step-mail', 'step-ixml'
44 changes: 27 additions & 17 deletions step-ixml/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ repositories {

configurations {
tools {
description = "ixml tools"
description = "Run tools"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume this is just a human-processible info without any technical implication? (My first thought was that it was erroneously copied from p:run but now I think that it just says what it says.)

transitive = true
}
}
Expand Down Expand Up @@ -56,27 +56,37 @@ task glossary(dependsOn: ["xinclude"], type: XMLCalabashTask) {
pipeline "../tools/xpl/makeglossary.xpl"
}

task specification(dependsOn: [ "source" ]) {
// nop
task library(dependsOn: ["source"], type: XMLCalabashTask) {
inputs.file "build/source.xml"
inputs.file "../tools/xpl/typed-pipeline-library.xpl"
inputs.file "../tools/xsl/typed-pipeline-library.xsl"
outputs.file "build/library.xml"
input("source", "build/source.xml")
output("result", "build/library.xml")
pipeline "../tools/xpl/typed-pipeline-library.xpl"
}

// ================================================================================
// Process the examples

def stripFiles = [ ]

stripFiles.each { String name ->
String newname = name.substring(0, name.lastIndexOf(".")) + ".txt"
task rnc(dependsOn: ["library"], type: XMLCalabashTask) {
inputs.file "build/library.xml"
inputs.file "../tools/xpl/library-to-rnc.xpl"
inputs.file "../tools/xsl/library-to-rnc.xsl"
outputs.file "build/steps.rnc"
input("source", "build/library.xml")
output("result", "build/steps.rnc")
pipeline "../tools/xpl/library-to-rnc.xpl"
}

task "process_$name"(type: StripAmblesTask) {
input = file("src/main/examples/$name")
output = file("$buildDir/examples/$newname")
}
xinclude.dependsOn "process_$name"
task rng(dependsOn: ["rnc"], type: JavaExec) {
inputs.file "build/steps.rnc"
outputs.file "build/steps.rng"
classpath = configurations.tools
mainClass = 'com.thaiopensource.relaxng.translate.Driver'
args = ["build/steps.rnc", "build/steps.rng"]
}

// ================================================================================
// Process the examples
task specification(dependsOn: [ "source", "library", "rng" ]) {
// nop
}

task clean() {
doFirst {
Expand Down
96 changes: 53 additions & 43 deletions step-ixml/src/main/xml/specification.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,18 +75,20 @@ steps is assumed; for background details, see
the specified Invisible XML grammar.</para>

<p:declare-step type="p:ixml">
<p:input port="grammar" sequence="true" content-types="any"/>
<p:input port="grammar" sequence="true" content-types="text xml"/>
<p:input port="source" primary="true" content-types="any -xml -html"/>
<p:output port="result" content-types="any"/>
<p:output port="result" sequence="true" content-types="any"/>
<p:option name="parameters" as="map(xs:QName, item()*)?"/>
<p:option name="fail-on-error" as="xs:boolean" select="true()"/>
</p:declare-step>

<para>If no grammar is provided on the <port>grammar</port> port, the grammar for
Invisible XML is assumed. If an XML or text grammar is provided it
<rfc2119>should</rfc2119> be an Invisible XML grammar.
<impl>If any other grammar format is provided, its interpretation is
<glossterm>implementation-defined</glossterm>.</impl></para>
<rfc2119>must</rfc2119> be an Invisible XML grammar.
<error code="C0212">It is a <glossterm>dynamic error</glossterm> if the grammar
provided is not a valid Invisible XML grammar.</error>
<error code="C0211">It is a <glossterm>dynamic error</glossterm> if more than one
document appears on the <port>grammar</port> port.</error></para>

<para>The <port>source</port> to be processed is usually text, but
there’s nothing in principle that prevents an Invisible XML grammar
Expand Down Expand Up @@ -118,16 +120,19 @@ in the output.</para>
</itemizedlist>

<section xml:id="example-ixml">
<title>Example</title>
<title>Examples</title>

<para>The following pipeline parses an Invisible XML grammar and returns
its XML representation:</para>
<para>Several examples demonstrate features of the step.</para>

<section xml:id="example-parse-ixml">
<title>Parsing an Invisible XML grammar</title>

<para>In this first example, no grammar is provided, so the pipeline parses the
Invisible XML grammar on the <port>source</port> port and returns its XML
representation:</para>

<example xml:id="addr-1">
<title>Parsing an ixml grammar</title>
<programlisting language="xml"
><xi:include href="../examples/dates-1.xml" parse="text"/></programlisting>
</example>

<para>This would produce an XML version of the grammar:</para>

Expand All @@ -153,32 +158,35 @@ its XML representation:</para>
<!-- … remaining rules elided for brevity … -->
</ixml>]]></programlisting>

<para>Providing the “date” grammar allows the step to parse dates:</para>
</section>
<section xml:id="example-parse-date">
<title>Parsing a date</title>

<para>If the grammar is provided on the <port>grammar</port> port, it can be
used to parse input, the string “31 December 2021” in this case:</para>

<example xml:id="addr-2">
<title>Parsing a date with ixml</title>
<programlisting language="xml"
><xi:include href="../examples/dates-2.xml" parse="text"/></programlisting>
</example>

<para>This would produce an XML version of the date:</para>

<programlisting language="xml"><![CDATA[<date><day>31</day><month>December</month><year>2021</year></date>]]></programlisting>

</section>
<section xml:id="example-parse-fail">
<title>Failed parses</title>

<para>If a parse fails, the implementation <rfc2119>must</rfc2119> indicate
this, but it may also provide information about where the processing failed.</para>

<example xml:id="addr-3">
<title>Failing to parse a date with ixml</title>
<programlisting language="xml"
><xi:include href="../examples/dates-3.xml" parse="text"/></programlisting>
</example>

<para>Here the output might be something like this:</para>

<programlisting language="xml"><![CDATA[<ixml xmlns:ixml="http://invisiblexml.org/NS"
xmlns:ex="http://example.com/NS"
ixml:state="failed" ex:lastChar="4">
<programlisting language="xml"><![CDATA[<error xmlns:ixml="http://invisiblexml.org/NS"
xmlns:ex="http://example.com/NS"
ixml:state="failed" ex:lastChar="4">
<parse>
month -> • M a r c h
month -> M • a r c h
Expand All @@ -187,21 +195,24 @@ month -> M • a r c h
month -> • M a y
month -> M • a y
</parse>
</ixml>]]></programlisting>
</error>]]></programlisting>

<para>There is <emphasis>nothing</emphasis> standard about this markup
except the <tag class="attribute">ixml:state</tag> attribute with the
value “<code>failed</code>”.</para>
<para>In the case of failure, Invisible XML requires that the <tag
class="attribute">ixml:state</tag> attribute appear on the root element
containing the token “<code>failed</code>”. It doesn’t constrain the implementation’s
choice of the root element or the content of the document.
</para>

</section>
<section xml:id="example-parse-ambiguous-1">
<title>Ambiguous parses</title>

<para>An ixml grammar may be ambiguous. In the grammar below, there are three
different possible ways to parse the input. By default, one of them is returned.
</para>

<example xml:id="ambig-1">
<title>Parsing an ambiguous grammar</title>
<programlisting language="xml"
><xi:include href="../examples/ambig-1.xml" parse="text"/></programlisting>
</example>

<para>This might return any one of these parses:</para>

Expand All @@ -219,41 +230,40 @@ different possible ways to parse the input. By default, one of them is returned.
><![CDATA[<letters ixml:state="ambiguous" xmlns:ixml="http://invisiblexml.org/NS"><X>a</X><B><digits>123</digits></B></letters>]]></programlisting>

<para>All are equally correct.</para>
</section>

<section xml:id="example-parse-ambiguous-2">
<title>Ambiguous parse selection</title>

<para>An implementation might provide a parameter to allow the author to
select a particular parse:
</para>

<example xml:id="ambig-2">
<title>Selecting a particular parse</title>
<programlisting language="xml"
><xi:include href="../examples/ambig-2.xml" parse="text"/></programlisting>
</example>

<para>This might return:</para>

<programlisting language="xml"
><![CDATA[<letters><X>a</X><A><digits>123</digits></A></letters>]]></programlisting>
><![CDATA[<letters ixml:state="ambiguous"><X>a</X><A><digits>123</digits></A></letters>]]></programlisting>
</section>

<section xml:id="example-parse-ambiguous-3">
<title>Multiple ambiguous outputs</title>

<para>Or a processor might provide a parameter to return all of the parses.</para>

<example xml:id="ambig-3">
<title>Selecting a particular parse</title>
<programlisting language="xml"
><xi:include href="../examples/ambig-3.xml" parse="text"/></programlisting>
</example>

<para>This might return:</para>
<para>This might return three documents:</para>

<programlisting language="xml"
><![CDATA[<ixml parseCount='3'>
<letters><X>a</X><C><digits>123</digits></C></letters>
<letters><X>a</X><B><digits>123</digits></B></letters>
<letters><X>a</X><A><digits>123</digits></A></letters>
</ixml>]]></programlisting>
<programlisting language="xml"><![CDATA[<letters ixml:state="ambiguous"><X>a</X><C><digits>123</digits></C></letters>
<letters ixml:state="ambiguous"><X>a</X><B><digits>123</digits></B></letters>
<letters ixml:state="ambiguous"><X>a</X><A><digits>123</digits></A></letters>]]></programlisting>

<para>As before, there is nothing standardized about the results in this case.</para>

</section>
</section>

<section>
Expand Down