Skip to content

Commit

Permalink
Merge pull request qt4cg#1575 from michaelhkay/528bis-element-to-map
Browse files Browse the repository at this point in the history 
528bis element to map
  • Loading branch information
@ndw
ndw authored Nov 19, 2024
2 parents 8b573f3 + c601932 commit 7604122
Show file tree
Hide file tree
Showing 2 changed files with 1,354 additions and 4 deletions.
184 changes: 184 additions & 0 deletions specifications/xpath-functions-40/src/function-catalog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25440,6 +25440,190 @@ return json-to-xml($json, $options)]]></eg>
any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).</p></fos:change>
</fos:changes>
</fos:function>


<fos:function name="elements-to-maps" prefix="fn">
<fos:signatures>
<fos:proto name="elements-to-maps" return-type="map(*)*">
<fos:arg name="elements" type="element()*"/>
<fos:arg name="options" type="map(*)" usage="inspection" default="map{}"/>
</fos:proto>
</fos:signatures>
<fos:properties>
<fos:property>deterministic</fos:property>
<fos:property>context-independent</fos:property>
<fos:property>focus-independent</fos:property>
</fos:properties>
<fos:summary>
<p>Converts a sequence of element nodes into maps that are suitable for
JSON serialization.</p>
</fos:summary>
<fos:rules>
<p>This function returns a sequence of maps corresponding one to one with
the element nodes supplied in <code>$elements</code>. Each map is in a form
that is suitable for JSON serialization, thus providing a mechanism for conversion
of arbitrary XML to JSON.</p>


<p>The entries that may appear in the <code>$options</code> map are as follows.
The <termref def="option-parameter-conventions">option parameter conventions</termref> apply.</p>

<fos:options>

<fos:option key="uniform">
<fos:meaning>Indicates that all elements with the same name, at any level in any of the
input trees should use the same conversion rules (known as a layout).
Setting this option requires the processor to analyze the entire input
before deciding what layout to use for each element; but by ensuring consistency across elements, it may
make the resulting maps easier to process.</fos:meaning>
<fos:type>xs:boolean</fos:type>
<fos:default>false</fos:default>
<fos:values>
<fos:value value="false">
The layout for each element node is decided independently, based on its individual content.
</fos:value>
<fos:value value="true">
In the absence of schema type information, and in the absence of an explicit entry in the <code>layouts</code>
property, the layout chosen for a given element node must be the same as that for all other
elements of the same name.
</fos:value>
</fos:values>
</fos:option>
<fos:option key="attribute-marker">
<fos:meaning>A string that is prefixed to any key value in the output that represents
an XDM attribute node in the input. The string may be empty. If, after applying the requested
prefix (or no prefix) there is a conflict between the names of attributes and child elements,
then the requested prefix (or lack thereof) is ignored and the default prefix <code>"@"</code>
is used.</fos:meaning>
<fos:type>xs:string</fos:type>
<fos:default>"@"</fos:default>
</fos:option>
<fos:option key="name-format">
<fos:meaning>Indicates how the names of element and attribute nodes are handled.</fos:meaning>
<fos:type>xs:string</fos:type>
<fos:default>"default"</fos:default>
<fos:values>
<fos:value value="lexical">Names are output in the form produced by the <code>fn:name</code> function.</fos:value>
<fos:value value="local">Names are output in the form produced by the <code>fn:local-name</code> function.</fos:value>
<fos:value value="eqname">Names in a namespace are output in the form <code>"Q{uri}local"</code>.
Names in no namespace are output using the local name alone.</fos:value>
<fos:value value="default">An element name is output as a local name alone if either (a) it is
a top-level element and is in no namespace, or (b) it is in the same namespace as its
parent element. An attribute name is output as a local name alone if it is in no namespace.
All other names are output in the format <code>"Q{uri}local"</code> if in a namespace,
or <code>"Q{}local"</code> if in no namespace. "Top-level" here means that the element
is one that appears explicitly in the sequence of elements passed in the <code>$elements</code> argument,
as distinct from a descendant of such an element.</fos:value>
</fos:values>
</fos:option>
<fos:option key="layouts">
<fos:meaning>A mapping from element names to layout names, used to override the default
formatting rules for a particular element name.</fos:meaning>
<fos:type>map(xs:QName, enum("empty", "empty-plus", "simple", "simple-plus", "list", "list-plus",
"record", "sequence", "mixed", "xml"))</fos:type>
<fos:default>map{}</fos:default>
</fos:option>
</fos:options>





<p>The principles for conversion from elements to maps are described
in <specref ref="element-layouts"/>.</p>


<p>In general, an element node maps to a key-value pair in which the key represents the element name, and the
corresponding value represents the attributes and children of the element. In the case of a top-level element
(a node directly supplied in <code>$nodes</code>), the result will be a singleton map containing this key-value
pair as its only entry. In the case of a descendant element, the key-value pair for a child element will be added
to the content representing its parent element, in a way that depends on the parent element's layout.</p>

<p>The representation of other kinds of node depends on the layout chosen for its parent element.</p>


</fos:rules>
<fos:errors>
<p>A dynamic error is raised if the selected layout rules require atomization of an element that does not have a typed
value (typically because it has been validated against an element-only content model): <errorref
class="TY" code="0012"/>.</p>
</fos:errors>
<!--<fos:notes>
<p>The namespace URI and local name of all elements and attributes is available in the JSON output.
Prefixes are not retained, and namespaces that are declared but not used are not retained.</p>

</fos:notes>-->
<fos:examples>
<fos:example>
<fos:test>
<fos:expression>elements-to-maps(())</fos:expression>
<fos:result>()</fos:result>
</fos:test>
<fos:test>
<fos:expression><![CDATA[elements-to-maps(parse-xml("<foo>bar</foo>")/*)]]></fos:expression>
<fos:result>{ "foo": "bar" }</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[elements-to-maps(parse-xml("
<list>
<item value='1'/>
<item value='2'/>
</foo>
")/*)]]></eg></fos:expression>
<fos:result><eg>{ "list": [
{ "@value": "1" },
{ "@value": "2" }
] }</eg></fos:result>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[elements-to-maps(parse-xml("
<name>
<first>Jane</first>
<last>Smith</last>
</foo>
")/*)]]></eg></fos:expression>
<fos:result><eg>{ "name": {
"first": "Jane",
"last": "Smith"
}
}</eg></fos:result>
</fos:test>
<!--<fos:test>

<fos:expression>items-to-json(map{"a":1,"b":number('NaN'),"c":(1,2,3)})</fos:expression>

<fos:result>'{"a":1,"b":"NaN","c":[1,2,3]}'</fos:result>
<fos:postamble>(or some permutation thereof)</fos:postamble>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[items-to-json(<a x="2">banana</a>)]]></eg></fos:expression>
<fos:result>'{"a":{"@x":"2","#content":"banana"}}'</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[items-to-json(<a><b/><c>2</c></a>)]]></eg></fos:expression>
<fos:result>'{"a":{"#content":{"b":"","c":"2"}}'</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[items-to-json(<a>A <i>nice</i> one!</a>)]]></eg></fos:expression>
<fos:result>'{"a":{"#content":["A ",{"i":"nice"}," one!"]}}'</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg><![CDATA[items-to-json(<a>A <i>nice</i> one!</a>,
map{'layouts':map{QName('', 'a'): 'xml'}, 'escape-solidus':false()})]]></eg></fos:expression>
<fos:result>'{"a":"<a>A <i>nice</i> one!</a>"}'</fos:result>
</fos:test>-->
</fos:example>
</fos:examples>
<fos:history>
<fos:version version="4.0">Proposed for 4.0; initial review on 2023-06-27.</fos:version>
</fos:history>
</fos:function>







<fos:function name="parse-csv" prefix="fn">
<fos:signatures>
Expand Down
Loading

0 comments on commit 7604122

Please sign in to comment.