XPathError class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 42: Line 42:
<h4>Syntax terms</h4>
<h4>Syntax terms</h4>
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%num</th>
<tr><th>%number</th>
<td>The position of the character at which the exception was thrown.
<td>The position of the character at which the exception was thrown.
</td></tr>
</td></tr>
<tr><th>%XPathErr</th>
<tr><th>xPathError</th>
<td>An <var>XPathError</var> object.
<td>An <var>XPathError</var> object.
</td></tr></table>
</td></tr></table>
Line 57: Line 57:
<h4>Syntax terms</h4>
<h4>Syntax terms</h4>
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%str</th>
<tr><th>%string</th>
<td>A string to receive the description of the exception.
<td>A string to receive the description of the exception.
</td></tr>
</td></tr>
<tr><th>%XPathErr</th>
<tr><th>xPathError</th>
<td>An <var>XPathError</var> object.
<td>An <var>XPathError</var> object.
</td></tr></table>
</td></tr></table>
Line 73: Line 73:
<h4>Syntax terms</h4>
<h4>Syntax terms</h4>
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%XPathErr</th>
<tr><th>%xPathError</th><td>A reference to an instance of an <var>XPathError</var> object.
<td>An <var>XPathError</var> object.
<tr><th><var>%(XPathError)</var></th><td>The class name in parentheses denotes a shared method.</td></tr>
</td></tr>
<tr><th><var>Reason</var></th>
<tr><th><b>Reason=</b>reasonEnum</th>
<td>This [[Methods#Named parameters|name required]] parameter is an <var>[[#Usage notes|XmlParseErrorReason enumeration]]</var> which specifies the value to be assigned to the exception object's <var>[[Reason (XPathError property)|Reason]]</var> property.
<td>This name required parameter specifies the value to be assigned to the exception object's <var>[[Reason (XPathError property)|Reason]]</var> property.
The <var>Reason parameter</var> is '''not''' optional.
The Reason parameter is '''not''' optional.
</td></tr>
</td></tr>
<tr><th><b>CharacterPosition=</b>num</th>
<tr><th><var>Description</var></th>
<td>This name required parameter specifies the numeric value (''num'') to be assigned to the object's <var>[[CharacterPosition (XPathError property)|CharacterPosition]]</var> property.
<td>This name required parameter specifies the string value (<var class="term">string</var>) to be assigned to the object's <var>[[Description (XPathError property)|Description]]</var> property.
</td></tr>
</td></tr>
<tr><th><b>Description=</b>string</th>
<tr><th><var>CharacterPosition</var></th>
<td>This name required parameter specifies the string value (''string'') to be assigned to the object's <var>[[Description (XPathError property)|Description]]</var> property.
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[CharacterPosition (XPathError property)|CharacterPosition]]</var> property.
</td></tr></table>
</td></tr></table>


Line 95: Line 94:
<h4>Syntax terms</h4>
<h4>Syntax terms</h4>
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%reason</th>
<tr><th>%xPathErrorReason</th>
<td>This <var>XPathErrorReason</var> enumeration value describes the reason for the translation failure.
<td>This <var>[[#Usage notes|XmlParseErrorReason enumeration]]</var> value describes the reason for the translation failure.
</td></tr>
</td></tr>
<tr><th>%XPathErr</th>
<tr><th>xPathError</th>
<td>An <var>XPathError</var> object.
<td>An <var>XPathError</var> object.


</td></tr></table>
</td></tr></table>
<h4>Usage notes</h4>
<h4>Usage notes</h4>
<ul>
An <var>XPathErrorReason</var> enumeration may have one of the following values:
<li>An <var>XPathErrorReason</var> enumeration may have one of the following values:
<dl>
<dl>
<dt>SyntaxError
<dt>SyntaxError
Line 112: Line 110:
requires at least one matching node.
requires at least one matching node.
</dl>
</dl>
<li>As with all enumerations, you use
As with all enumerations, you use
the <code>ToString</code> method to convert an enumeration value to a
the <code>ToString</code> method to convert an enumeration value to a
character string whose value is the name of the enumeration value.
character string whose value is the name of the enumeration value.
</ul>




[[Category:System exception classes]]
[[Category:System exception classes]]

Revision as of 18:08, 11 May 2011


An XPathError exception can be thrown by various methods in the XmlDoc API. It indicates an error either in the syntax of an XPath argument to the method, or in the results returned by that XPath expression. The various read-only properties of an XPathError object (which can be set by the Catch statement) provide information about the failed operation.

An example of using the XPathError exception is:

%err Object XPathError Try %d:Print('a b c') Catch XPathError To %err PrintText {~} = {%err:Reason} PrintText {~} = {%err:Description} PrintText {~} = {%err:CharacterPosition} End Try

Since the expression in the above invocation of the Print method (a b c) is not a valid XPath expression, the above fragment will result in the following:

%err:Reason = SyntaxError %err:Description = Expect "/" for new step or "[" for predicate %err:CharacterPosition = 3

This class is new in version 7.8 of the Sirius Mods.


The XPathError methods

The following are the available XPathError class methods.

MethodDescription
CharacterPositionPosition of character at of before which the error occurred
DescriptionBrief description of the exception
NewCreate a new XPathError object
ReasonEnumerated cause of the exception

The methods in the class are described in the subsections that follow. In addition:


CharacterPosition property

Position of character at of before which the error occurred (XPathError class)

[Introduced in Sirius Mods 7.8]

Syntax

%number = xPathError:CharacterPosition

Syntax terms

%number The position of the character at which the exception was thrown.
xPathError An XPathError object.


Description property

Brief description of the exception (XPathError class)

[Introduced in Sirius Mods 7.8]

Syntax

%string = xPathError:Description

Syntax terms

%string A string to receive the description of the exception.
xPathError An XPathError object.


New constructor

Create a new XPathError object (XPathError class)

[Introduced in Sirius Mods 7.8]

Each argument to New sets the value of the corresponding property of the newly constructed XPathError object.

Syntax

%xPathError = [%(XPathError):]New( Reason= xPathErrorReason, - [Description= string], - [CharacterPosition= number])

Syntax terms

%xPathErrorA reference to an instance of an XPathError object.
%(XPathError)The class name in parentheses denotes a shared method.
Reason This name required parameter is an XmlParseErrorReason enumeration which specifies the value to be assigned to the exception object's Reason property.

The Reason parameter is not optional.

Description This name required parameter specifies the string value (string) to be assigned to the object's Description property.
CharacterPosition This name required parameter specifies the numeric value (number) to be assigned to the object's CharacterPosition property.


Reason property

Enumerated cause of the exception (XPathError class)

[Introduced in Sirius Mods 7.8]

Syntax

%xPathErrorReason = xPathError:Reason

Syntax terms

%xPathErrorReason This XmlParseErrorReason enumeration value describes the reason for the translation failure.
xPathError An XPathError object.

Usage notes

An XPathErrorReason enumeration may have one of the following values:

SyntaxError
A violation of the syntax of an XPath expression.
EmptyResult
There are no nodes matched by the XPath expression, and the method requires at least one matching node.

As with all enumerations, you use the ToString method to convert an enumeration value to a character string whose value is the name of the enumeration value.