Print (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (xpath expression)
m (xpath arg)
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:Print subtitle}}
{{Template:XmlDoc/XmlNode:Print subtitle}}
The <var>Print</var> subroutine displays an <var>XmlDoc</var> subtree in a readable form, useful for debugging, for example.


This subroutine displays an <var>XmlDoc</var> subtree in a readable form,
useful for debugging, for example.
==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:Print syntax}}
{{Template:XmlDoc/XmlNode:Print syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>nr</th>
<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <i>XPath</i> expression. If an <var>XmlDoc</var>, the Root node is the context node. </td></tr>
<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>
 
<tr><th>xpath</th>
<tr><th>xpath</th>
<td>A <var>Unicode</var> string that is an <var>[[XPath#XPath_syntax|Xpath expression]]</var> 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 (<tt>.</tt>), that is, the node referenced by the method object (<i>nr</i>). </td></tr>
<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.
<p>
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>
 
<tr><th>options</th>
<tr><th>options</th>
<td>A blank delimited string that can contain one or more of the following options, which are identified below and described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]:
<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>  
<ul>  
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
<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,
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.  
and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.  


<li><b>CharacterEncodeAll</b><br>
<li><b>CharacterEncodeAll</b><br>
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.  
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.  


<li><b>Compact</b>, <b>Expanded</b>, <b>AttributeCompact</b>, <b>ElementCompact</b>, or <b>BothCompact</b> <br>
<li><b>Compact</b>, <b>Expanded</b>, <b>AttributeCompact</b>, <b>ElementCompact</b>, or <b>BothCompact</b> <br>
Line 26: Line 28:


<li><b>Indent <i>n</i></b><br>
<li><b>Indent <i>n</i></b><br>
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.
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.


<li><b>NoEmptyElt</b><br>
<li><b>NoEmptyElt</b><br>
Deprecated as of ''Sirius Mods'' version 7.0, 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>).
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>).  
<p>
<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>


<li><b>OmitNullElement</b><br>
<li><b>OmitNullElement</b><br>
Line 36: Line 40:
<li><b>SortCanonical</b><br>  
<li><b>SortCanonical</b><br>  
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).   
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).   
</ul></td></tr>
</ul></td></tr>
</table>
</table>
Line 42: Line 45:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Options may be specified in any case.
<li>Options may be specified in any case. For example, you can use either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
For example, you can use
<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>.
either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
<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.
<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>.
 
<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 <code>&amp;quot;</code>.
Prior to version 7.6, this convention was not strictly observed.
</ul>
</ul>


==Example==
==Examples==
 
<ol>
In the following example, the <var>Print</var> method is called first
<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:
in its default form with no arguments,
<p class="code">begin
then with explicit values for its options:
  print 'Print method'
<p class="code"> Begin
  print '***********'
Print 'Print method'
  %doc is object xmlDoc
Print '***********'
  %doc = new
%doc is Object XmlDoc
  [[Notation_conventions_for_methods#Callable_methods|call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a><a2/></top>')</nowiki>
%doc = New
  %doc:[[Version (XmlDoc property)|Version]] ='1.0'
Call %doc:LoadXml<nowiki>('<top><a><b>05</b></a><a2/></top>')</nowiki>
  call %doc:print
%doc:Version ='1.0'
  print 'Non-default display:'
Call %doc:Print
  call %doc:print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
Print 'Non-default display:'
end
Call %doc:Print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
End
</p>
</p>
The example results follow:
The example results follow:
<p class="code"> <nowiki><?xml version="1.0"?>
<p class="output"> <nowiki><?xml version="1.0"?>
  <top>
  <top>
     <a>
     <a>
Line 92: Line 84:
  </top></nowiki>
  </top></nowiki>
</p>
</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>
==Request-cancellation errors==
==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<ul>
<li><var class="term">xpath</var> is invalid.
<li>The <var class="term">xpath</var> expression is invalid.
<li>Result of <var class="term">xpath</var> is empty.
<li>The result of <var class="term">xpath</var> is empty.
<li><var class="term">options</var> values are invalid.
<li><var class="term">options</var> values are invalid.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


==See also==
==See also==
{{Template:XmlDoc/XmlNode:Print footer}}
<ul>
<ul>
<li>For more information about using XPath expressions, see [[XPath|"XPath"]].
<li>For more information about using XPath expressions, see [[XPath]]. </li>
<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.
<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>
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>See the description of [[XmlDoc_API_serialization_options#EBCDIC_serialization_of_untranslatable_Unicode_characters|Unicode to EBCDIC conversion]] performed by <var>Print</var>. </li>
 
<li>For additional discussion about serialization, see [[XmlDoc API#Transport: receiving and sending XML|Transport: receiving and sending XML]]. </li>
 
<li>Additional serializing methods include:
<li>Additional serializing methods include:
<ul>
<ul>
<li><var>[[WebSend (XmlDoc subroutine)|WebSend]]</var>
<li><var>[[WebSend (XmlDoc subroutine)|WebSend]]</var> </li>
<li><var>[[AddXml]]</var> (<var>[[HttpRequest]]</var> class)
<li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) </li>
</ul>
</ul></li>
</ul>
</ul>
{{Template:XmlDoc/XmlNode:Print footer}}

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