Print (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (xpath arg)
 
(37 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Print selected subtree</b></span>
{{Template:XmlDoc/XmlNode:Print subtitle}}
[[Category:XmlDoc methods|Print subroutine]]
The <var>Print</var> subroutine displays an <var>XmlDoc</var> subtree in a readable form, useful for debugging, for example.
[[Category:XmlNode methods|Print subroutine]]
[[Category:XmlDoc API methods]]
<!--DPL?? Category:XmlDoc methods|Print subroutine: Print selected subtree-->
<!--DPL?? Category:XmlNode methods|Print subroutine: Print selected subtree-->
<!--DPL?? Category:XmlDoc API methods|Print (XmlDoc/XmlNode subroutine): Print selected subtree-->
<!--DPL?? Category:System methods|Print (XmlDoc/XmlNode subroutine): Print selected subtree-->
<p>
Print is a member of the [[XmlDoc class|XmlDoc]] and [[XmlNode class|XmlNode]] classes.
</p>
 
This subroutine displays an XmlDoc subtree in a readable form,
useful for debugging, for example.
===Syntax===
  Call nr:Print([Xpath], [options])


====Syntax Terms====
==Syntax==
<dl>
{{Template:XmlDoc/XmlNode:Print syntax}}
<dt>nr
<dd>An XmlDoc or XmlNode, used as the context node for the
<i>XPath</i> expression.
If an XmlDoc, the Root node is the context node.
<dt>XPath
<dd>A Unicode string that is an XPath expression that results in a nodelist,
the head of which is the top of the subtree to print.
An optional argument, its default is a period (.), that is,
the node referenced by the method object (<i>nr</i>).
<dt>options
<dd>A blank delimited string that can contain one or more of the
following options.
No option may be repeated.
<ul>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>


Whether or not the XML declaration (<?xml&thinsp.version=...?>)
===Syntax terms===
is produced &mdash; if the XML version number (as returned by the
<table class="syntaxTable">
[[Version (XmlDoc property)|Version]]
<tr><th>nr</th>
is not the null string, and the node selected by <i>XPath</i> is the Root.
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the [[XPath#XPath_syntax|XPath expression]].  If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>
AllowXmlDecl is the default.
AllowXmlDecl and NoXmlDecl may not both be specified.
<li><b>CharacterEncodeAll</b>


Use character encoding in all contexts to display
<tr><th>xpath</th>
Unicode characters that do not translate to EBCDIC.
<td>A <var>Unicode</var> string that is an XPath expression that results in a nodelist, the head of which is the top of the subtree to print. Any other nodes in the nodelist are ignored.
If this option is not specified (as of ''Sirius Mods'' 7.6), only
<p>
non-translatable Unicode characters in Attribute or Element
This is an optional argument, and its default is a period (<code>.</code>), that is, the node referenced by the method object (<var class="term">nr</var>).</p></td></tr>
values are displayed as character references.


For more information about this option, see
<tr><th>options</th>
the &ldquo;Usage Notes&rdquo; item [[??]] reftxt=* refid=ucharef..
<td>A blank delimited string that can contain one or more of the following options. <p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options]]. </p>
<ul>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
Whether or not the serialization will contain the "XML Declaration" (<code><?xml version=...?></code>), if the value of the <var>[[Version (XmlDoc property)|Version]]</var> property is a non-null string, if the <var>XmlDoc</var> is not empty, and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.  


The CharacterEncodeAll option is available as of ''Sirius Mods'' version 7.6.
<li><b>CharacterEncodeAll</b><br>
<li><b>Indent</b> <i><b>n</b></i>
Use character encoding in all contexts (that is, not only in <var>Attribute</var> or <var>Element</var> values) to display Unicode characters that do not translate to EBCDIC.


Element children (and, depending on the compaction option, below, in effect,
<li><b>Compact</b>, <b>Expanded</b>, <b>AttributeCompact</b>, <b>ElementCompact</b>, or <b>BothCompact</b> <br>
attributes and the closing characters &ldquo;/>&rdquo; of an
One of these mutually exclusive [[XmlDoc API serialization options#outformat|output formats]], which control the degree of expansion or compression of the display of a serialized element's content.  
empty Element) are indented ''n'' spaces from the beginning
of the Element's Start-Tag.


If the Indent option is omitted, the default indent is 3 spaces.
<li><b>Indent <i>n</i></b><br>
<i>n</i> is non-negative, and its maximum (as of ''Sirius Mods'' version 7.0) is 254.
Indent <var>Element</var> children (and, depending on the compaction option, above, in effect, attributes and the closing characters "/>" of an empty <var>Element</var>) ''n'' spaces (default 3) from the beginning of the <var>Element</var>'s Start-Tag.
<br>
<li><b>NoEmptyElt</b>


An empty element is serialized with a start tag
<li><b>NoEmptyElt</b><br>
followed by an end tag.
This deprecated option serializes all empty elements with a start tag followed by an end tag. The default is to serialize an empty element with an empty element tag (as in <code><middleName/></code>).
For example:
<p>
<pre>
<var>NoEmptyElt</var> is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the <var>[[NoEmptyElement (XmlNode property)#browserExample|NoEmptyElement]]</var> property page &mdash; some tags (<code>&#x3c;div></code>) <b>require</b> separate start and end tags, while other tags (<code>&#x3c;br></code>) <b>do not allow</b> separate start and end tags. </p></li>
    <middleName>
    </middleName>
</pre>
If NoEmptyElt is not specified, the default is to serialize an empty
element with an empty element tag:
<pre>
    <middleName/>
</pre>
<li><b>OmitNullElement</b>


An Element node that has no children and
<li><b>OmitNullElement</b><br>
no Attributes will not be serialized, unless it is the top level Element in
An <var>Element</var> node that has no children and no <var>Attributes</var> will not be serialized, unless it is the top level <var>Element</var> in the subtree being serialized.  
the subtree being serialized.
The serialization of a child-less and Attribute-less Element is omitted,
even if the Element's serialization would contain
Namespace declarations in its start tag.


If an Element node has no Attributes, but has (only) Element children
<li><b>SortCanonical</b><br>
(one or more), and all of its children are Attribute-less and child-less,
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).
then that parent Element is serialized, even though its content in the
</ul></td></tr>
serialization is empty.
</table>
That parent is serialized with a start tag and an end tag
(and an inserted line separator, if called for by the serializing
method's parameter options).


For example, if the Print method display of a particular XmlDoc is the following
==Usage notes==
when no Print options are specified:
<pre>
    <top>
      <middle>
          <empty/>
          <p:empty2 xmlns:p="uri:stuff"/>
      </middle>
    </top>
</pre>
 
Here is the display of the XmlDoc with the OmitNullElement option specified:
<pre>
    <top>
      <middle>
      </middle>
    </top>
</pre>
 
But if you attempt to display only the <tt>empty</tt> subtree of the XmlDoc
using OmitNullElement, the <tt>empty</tt> node
is not suppressed, and the result is:
<pre>
    <empty/>
</pre>
 
The OmitNullElement option is available as of ''Sirius Mods'' version 7.3.
<li>One of the following mutually exclusive '''output formats''':
<ul>
<ul>
<li><b>Compact</b>
<li>Options may be specified in any case. For example, you can use either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
 
<li>As a debugging aide, <var>Print</var> may be issued for the root node of an <var>XmlDoc</var> that is not well-formed, that is, does not contain an <var>Element</var>.
This is the default.
<li>As of <var class="product">Sirius Mods</var> Version 7.6, <var>Attribute</var> values are always serialized within double-quotation-mark (<code>"</code>) delimiters, and a double-quotation mark character in an attribute value is serialized as <code>&amp;quot;</code>.  Prior to <var class="product">Sirius Mods</var> Version 7.6, this convention was not strictly observed.
An element's entire start tag is printed on a single line, which
includes attributes and namespace declarations.
If it has no children or has a single Text child,
and does '''not''' have attributes nor namespace declarations, then the
Text child is serialized on the same line as the start and end tags.
For example:
<pre>
    <top>
      <in1 a="xyz" b="foo">
        content1
      </in1>
      <in2>content2</in2>
    </top>
</pre>
<li><b>Expanded</b>
 
A new line is started for each attribute,
namespace declaration, and child.
For example:
<pre>
    <top>
      <in1
        a="xyz"
        b="foo"
      >
        content1
      </in1>
      <in2>
        content2
      </in2>
    </top>
</pre>
<li><b>AttributeCompact</b>
 
Attributes and namespace declarations
are printed on the same line as the start tag.
For example:
<pre>
    <top>
      <in1 a="xyz" b="foo">
        content1
      </in1>
      <in2>
          content2
      </in2>
    </top>
</pre>
<li><b>ElementCompact</b>
 
An entire element is printed on one line, if it has
no attributes nor namespace declarations and has
no children other than possibly a Text child.
For example:
<pre>
    <top>
      <in1
          a="xyz"
          b="foo"
          >
        content1
      </in1>
      <in2>content2</in2>
    </top>
</pre>
<li><b>BothCompact</b>
 
The most compacted format, this combines the effect of AttributeCompact and
ElementCompact.
It displays on one line an element that has no children or that
has a single Text child.
For example:
<pre>
    <top>
      <in1 a="xyz" b="foo">content1</in1>
      <in2>content2</in2>
    </top>
</pre>
</ul>
</ul>
<li><b>SortCanonical</b>


This indicates that
==Examples==
namespace declarations (based on the prefix being declared) and
<ol>
attributes (based on the namespace URI followed by the local
<li>In the following example, the <var>Print</var> method is called first in its default form with no arguments, then with explicit values for its options:
name) are serialized in sorted order.
<p class="code">begin
This can be useful, for instance,
  print 'Print method'
to serialize a portion of an XML document for a signature.
  print '***********'
  %doc is object xmlDoc
  %doc = new
  [[Notation_conventions_for_methods#Callable_methods|call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a><a2/></top>')</nowiki>
  %doc:[[Version (XmlDoc property)|Version]] ='1.0'
  call %doc:print
  print 'Non-default display:'
  call %doc:print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
end
</p>
The example results follow:
<p class="output"> <nowiki><?xml version="1.0"?>
<top>
    <a>
      <b>05</b>
    </a>
    <a2/>
</top></nowiki>
Non-default display:
<nowiki><top>
    <a>
      <b>
            05
      </b>
    </a>
    <a2>
    </a2>
</top></nowiki>
</p>
<li>In the following fragment, the <var>Print</var> result for a document with untranslatable Unicode is shown:
<p class="code">%doc2:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('circumference', '2 * &amp;#x3C0; * r':U)
%doc2:print
</p>
The result follows (the Unicode codepoint for the Greek letter &#x03c0; has the hexadecimal value 03C0):
<p class="output"><circumference>2 * &amp;#x03C0; * r</circumference>
</p>
</ol>


The sort order for namespace declarations and attributes is from
==Request-cancellation errors==
lowest to highest, and it uses the Unicode code ordering (for example,
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
numbers are lower than letters).
<ul>
 
<li>The <var class="term">xpath</var> expression is invalid.
Added in ''Sirius Mods'' version 6.9 as a step towards support for canonicalization,
<li>The result of <var class="term">xpath</var> is empty.
this option is superseded by the Serial method ExclCanonical
<li><var class="term">options</var> values are invalid.
option ([[??]] refid=exclcan.), which provides full support for
<li>Insufficient free space exists in CCATEMP.
canonicalized serialization.
</ul>
</ul>


</dl>
==See also==
 
===Usage Notes===
<ul>
<ul>
<li>Options may be specified in any case.
<li>For more information about using XPath expressions, see [[XPath]]. </li>
For example, you can use
either <tt>NoXmlDecl</tt> or <tt>noxmldecl</tt>, interchangeably.
<li>As a debugging aide, Print may be issued for the root node of an
XmlDoc that is not well-formed, that is, does not contain an Element.
<li>The Print method output is '''not''' affected if one of the output
format options or
<tt>Indent</tt> is specified, and an element to be serialized has the
<tt>xml:space="preserve"</tt> or <tt>xml:space="default"</tt> attribute.
<li>As of version 6.7, the Print method uses the hexadecimal
character references specified in the XML Canonicalization specification
(:hp0 color=SirLink.http://www.w3.org/TR/xml-c14n:ehp0.) to
display the tab, carriage return, and linefeed characters
for the following XML document node types:
<ul>
<li>Attribute
<li>Text
</ul>


These character references are used:
<li>To more accurately serialize an <var>XmlDoc</var>, as opposed to providing a "displayable" form, use the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> function. The <var>Print</var> subroutine, like its analogs <var>[[Audit (XmlDoc/XmlNode subroutine)|Audit]]</var> and <var>[[Trace (XmlDoc/XmlNode subroutine)|Trace]]</var>, inserts line breaks and performs indentation. </li>
<dl>
<dt>tab
<dd>&amp;#x9;
<dt>CR
<dd>&amp;#xD;
<dt>LF
<dd>&amp;#xA;
</dl>


The EBCDIC and corresponding ASCII encodings of the characters is:
<li>See the description of [[XmlDoc_API_serialization_options#EBCDIC_serialization_of_untranslatable_Unicode_characters|Unicode to EBCDIC conversion]] performed by <var>Print</var>. </li>
<dl>
<dt>&thinsp.
<dd>EBCDIC     ASCII
<dt>tab
<dd>X'05'          X'09'
<dt>CR
<dd>X'0D'          X'0D'
<dt>LF
<dd>X'25'          X'0A'
</dl>
<li>As of ''Sirius Mods'' version 7.6, Attribute values are always serialized
within double-quotation-mark (<tt>"</tt>) delimiters,
and a double-quotation mark character in an attribute value is serialized
as <tt>&amp;quot;</tt>.
Prior to version 7.6, this convention was not strictly observed.
<li>As of ''Sirius Mods'' version 7.6, XmlDoc content is stored in Unicode.
To serialize to EBCDIC, the Print method uses the Unicode tables
(described further in [[??]] refid=u80.) to convert the XmlDoc content.


One feature of the conversion from Unicode is that
<li>For additional discussion about serialization, see [[XmlDoc API#Transport: receiving and sending XML|Transport: receiving and sending XML]]. </li>
the Print method displays non-translatable Unicode characters
stored in Attribute or Element values as character references.
For example:
<pre>
    %doc:AddElement('top', '&amp;#x2122;':U)
    %doc:Print
</pre>


The result of this fragment is:
<li>Additional serializing methods include:
<pre>
    <top>&amp;#x2122;</top>
</pre>
 
However, with default serialization options, when an untranslatable
Unicode character occurs in a context other than Element or Attribute value
(that is, a name, comment, or PI), character encoding is '''not''' used.
Because it is an element name, for example, the following statements result in a
request cancellation:
<pre>
    %doc:AddElement('&amp;#x2122;':U)
    %doc:Print
</pre>
 
The Print method fails, attempting
to translate the element name, the U+2122 character, to EBCDIC.
This request cancellation can be prevented by using
the <tt>CharacterEncodeAll</tt> option:
<pre>
    %doc:AddElement('&amp;#x2122;':U)
    %doc:Print(, 'CharacterEncodeAll')
</pre>
 
The result of the above fragment is:
<pre>
    <&amp;#x2122;/>
</pre>
'''Note:'''
The result of a Print with CharacterEncodeAll can be misleading.
Request cancellation is avoided, but it produces multiple EBCDIC characters
where only a single Unicode character is stored.
 
The XmlDoc, <tt>%doc</tt>, above is not a legal XML document,
because the ampersand (<tt>&</tt>) is not a legal name character.
Similarly, for
an untranslatable Unicode character added to a document
with AddComment or AddPI: printing with <tt>CharacterEncodeAll</tt>
produces a stream of characters that informs about
a single character reference but, if deserialized, would result in multiple
stored characters.
The standard XML syntax does not recognize character references as such in
names, Comments, and PIs.
</ul>
===Example===
 
In the following example, the Print method is called first
in its default form with no arguments,
then with explicit values for its options:
<pre>
    Begin
    Print 'Print method'
    Print '***********'
    %doc is Object XmlDoc
    %doc = New
    Call %doc:LoadXml('<top><a><b>05</b></a><a2/></top>')
    %doc:Version ='1.0'
    Call %doc:Print
    Print 'Non-default display:'
    Call %doc:Print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
    End
</pre>
 
The example results follow:
<pre>
    <?xml version="1.0"?>
    <top>
      <a>
          <b>05</b>
      </a>
      <a2/>
    </top>
    Non-default display:
    <top>
          <a>
                <b>
                      05
                </b>
          </a>
          <a2>
          </a2>
    </top>
</pre>
===Request-Cancellation Errors===
<ul>
<ul>
<li><i>XPath</i> is invalid.
<li><var>[[WebSend (XmlDoc subroutine)|WebSend]]</var> </li>
<li>Result of (<i>XPath</i>) is empty.
<li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) </li>
<li><i>Options</i> are invalid.
</ul></li>
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


 
{{Template:XmlDoc/XmlNode:Print footer}}
===See Also===
<ul>
<li>For more information about using XPath expressions, see [[XPath]].
<li>To more accurately serialize an XmlDoc, as opposed to providing
a &ldquo;displayable&rdquo; form, use the [[Serial (XmlDoc/XmlNode function)|Serial]] function.
The Print subroutine, like its analogs [[??]] reftxt=Audit refid=audit.
and [[??]] reftxt=Trace refid=trace.,
inserts line breaks and performs indentation.
<li>Additional serializing methods include:
<ul>
<li>[[WebSend (XmlDoc subroutine)|WebSend]]
<li>AddXml (HttpRequest class, described in the [[Janus Sockets]]R.)
</ul>
</ul>

Latest revision as of 17:26, 18 February 2015

Print selected subtree (XmlDoc and XmlNode classes)

The Print subroutine displays an XmlDoc subtree in a readable form, useful for debugging, for example.

Syntax

nr:Print[( [xpath], [options])] Throws XPathError

Syntax terms

nr An XmlDoc or XmlNode, used as the context node for the XPath expression. If an XmlDoc, the Root node is the context node.
xpath A Unicode string that is an XPath expression that results in a nodelist, the head of which is the top of the subtree to print. Any other nodes in the nodelist are ignored.

This is an optional argument, and its default is a period (.), that is, the node referenced by the method object (nr).

options A blank delimited string that can contain one or more of the following options.

Note: These options are described in greater detail in XmlDoc API serialization options.

  • AllowXmlDecl or NoXmlDecl
    Whether or not the serialization will contain the "XML Declaration" (<?xml version=...?>), if the value of the Version property is a non-null string, if the XmlDoc is not empty, and if the node selected by xpath is the Root node. AllowXmlDecl is the default.
  • CharacterEncodeAll
    Use character encoding in all contexts (that is, not only in Attribute or Element values) to display Unicode characters that do not translate to EBCDIC.
  • Compact, Expanded, AttributeCompact, ElementCompact, or BothCompact
    One of these mutually exclusive output formats, which control the degree of expansion or compression of the display of a serialized element's content.
  • Indent n
    Indent Element children (and, depending on the compaction option, above, in effect, attributes and the closing characters "/>" of an empty Element) n spaces (default 3) from the beginning of the Element's Start-Tag.
  • NoEmptyElt
    This deprecated option serializes all empty elements with a start tag followed by an end tag. The default is to serialize an empty element with an empty element tag (as in <middleName/>).

    NoEmptyElt is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the NoEmptyElement property page — some tags (<div>) require separate start and end tags, while other tags (<br>) do not allow separate start and end tags.

  • OmitNullElement
    An Element node that has no children and no Attributes will not be serialized, unless it is the top level Element in the subtree being serialized.
  • SortCanonical
    This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).

Usage notes

  • Options may be specified in any case. For example, you can use either NoXmlDecl or noxmldecl, interchangeably.
  • As a debugging aide, Print may be issued for the root node of an XmlDoc that is not well-formed, that is, does not contain an Element.
  • As of Sirius Mods Version 7.6, Attribute values are always serialized within double-quotation-mark (") delimiters, and a double-quotation mark character in an attribute value is serialized as &quot;. Prior to Sirius Mods Version 7.6, this convention was not strictly observed.

Examples

  1. In the following example, the Print method is called first in its default form with no arguments, then with explicit values for its options:

    begin print 'Print method' print '***********' %doc is object xmlDoc %doc = new call %doc:loadXml('<top><a><b>05</b></a><a2/></top>') %doc:Version ='1.0' call %doc:print print 'Non-default display:' call %doc:print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded') end

    The example results follow:

    <?xml version="1.0"?> <top> <a> <b>05</b> </a> <a2/> </top> Non-default display: <top> <a> <b> 05 </b> </a> <a2> </a2> </top>

  2. In the following fragment, the Print result for a document with untranslatable Unicode is shown:

    %doc2:addElement('circumference', '2 * &#x3C0; * r':U) %doc2:print

    The result follows (the Unicode codepoint for the Greek letter π has the hexadecimal value 03C0):

    <circumference>2 * &#x03C0; * r</circumference>

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • The xpath expression is invalid.
  • The result of xpath is empty.
  • options values are invalid.
  • Insufficient free space exists in CCATEMP.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Print_(XmlDoc/XmlNode_subroutine)&oldid=75142"