Evaluate Mode

www.altova.com Expand/Collapse All Print this Topic Previous Page Up One Level Next page

Home >  User Guide and Reference > Interface and Environment > The Graphical User Interface (GUI) > Output Window: XPath/XQuery >

Evaluate Mode

The XPath/XQuery Window enables you to build and evaluate up to nine XPath or XQuery expressions during one session, each within its own evaluation scope (which is specified in the Where option; see screenshot below). The expression can be evaluated on the current file, as well as on the following sets of multiple files: (i) all currently open documents; (ii) files of the currently active XMLSpy project; or (iii) files of a selected folder.

 

OutputBarXPathOview

 

 

Click to expand/collapseButtons in this section

icDebugMode

Debug Mode

Switches between Debug and Evaluate Modes

icHorizontalVerticalLayout

Horizontal/Vertical Layout

Switches between horizontal and vertical layouts

XMLJSONEvalMode

XML/JSON Evaluation Mode (toggles between XML and JSON evaluation modes)

The highlighted part indicates which evaluation mode is active. When evaluation scope is multiple files, they are both enabled and one can be selected; otherwise, they are disabled. When disabled, evaluation mode is auto-detected according to file type

 

About Evaluate Mode

 

To switch to Evaluate Mode, deselect the Debug Mode button, which is located at the far left of the window's toolbar (see screenshot above).
You can switch between a horizontal and vertical layout by clicking the Horizontal/Vertical Layout button, which is located at the far right of the window's toolbar (see screenshot above).
Select the evaluation scope: either the current file, or a set of multiple files (open documents, files of a project, files of a folder). If the evaluation scope is the current file, evaluation mode (XML or JSON) is automatically determined by the conformance type of the document's file type (JSON mode for JSON-conformant files, XML mode for non-JSON files); the auto-detected mode cannot be changed and the buttons are disabled. If the evaluation scope is a multiple-file option, then the default evaluation mode is XML, but both buttons are enabled and you can select the evaluation mode you want; see Evaluating expressions below.
Evaluate Mode has: (i) a Builder tab, which has entry helpers to aid in building the expression, and (ii) an Evaluator tab, which shows the results of evaluating the expression (see screenshot above).
If the bottom pane is too short to display the names of the two tabs, the names are hidden and only the tabs' icons are displayed. Hovering over an icon displays the name of the tab.
The XPath/XQuery Window in Evaluate Mode has nine tabs. After an expression is entered in one of these tabs, the tab's settings are saved. So, if you return to a tab after switching to other tabs, the settings for that tab will be unchanged. If you switch to a new tab, the settings of the previous tab are passed to the new tab.
If the expression is evaluated in the context of multiple XML documents (see the description of the Where option below), clicking on the filename in the results list opens the file in XMLSpy and makes it the active file.

 

XPath evaluations are described below. For a description of XQuery evaluations, see the section, XQuery Evaluation. (The XQ icons are for XQuery evaluation; the XQU icons are for XQuery Update executions.) For information about writing XPath/XQuery expressions in the XPath/XQuery Window, see XPath and XQuery Specification Information.

 

XPath/XQuery Expression Builder

The Builder tab (screenshot below) has two entry-helper panes: (i) for operators and expressions; and (ii) for functions. Note that, if more than one signature exists for a single function name, each signature is listed as a separate function. (These variants are known as overloads of that function name.) The items in both panes can be shown either grouped hierarchically or as a flat list. Select the option you want in the dropdown list at the top right of each pane (circled in red in the screenshot below). In the screenshot, both panes show their items in hierarchical groups.

 

XPXQWindowBuilder01

 

Features of the Builder:

 

To view a text description of an item in either entry-helper pane, hover over the item.
Each function is listed with its signature (that is, with its arguments, the datatypes of the arguments, and the datatype of the function's output).
Arguments are listed by their names (if any) or by their datatypes. Select the option you want from the dropdown list in the title bar of the Functions pane (circled in green in the screenshot above).
Double-clicking an item in any of the panes (operator, expression, or function), inserts that item at the cursor location in the expression. Functions are inserted with their arguments indicated by placeholders (the # symbol).
If (i) text is selected in the expression's edit field, and (ii) an operator, expression or function that contains a placeholder is double-clicked to insert it, then the text that was selected is inserted instead of the placeholder. This is a quick way to insert long text (such as a path expression) into an operator, expression, or function.

 

After you have entered a function in the expression, hovering over the function name displays the function's signature and a text description of the function. If more than one signature exists for a function, these are indicated with an overload factor at the bottom of the display. If you place the cursor within the parentheses of the function and press Ctrl+Shift+Spacebar, you can view the signatures of the various overloads of that function name.  

 

Evaluating expressions

Given below are the main steps for evaluating an XPath expression. The steps for XQuery expression evaluation are the same. For a dedicated description of XQuery evaluations, see the section, XQuery Evaluation. (The XQ icons are for XQuery evaluation; the XQU icons are for XQuery Update executions.) For a description of querying JSON documents, see JSON Transformations with XSLT/XQuery.

 

1.Depending on where the XPath expression is to be evaluated, select from one of the options in the Where options list (screenshot below): Current file; Open files; (XMLSpy) Project; or Folder.

xpath_where

If Current file is selected, the file that is currently active is used. Selecting Open files causes the XPath expression to be evaluated against all the files currently open in XMLSpy. Project refers to the currently active XMLSpy project. The external folders in an XMLSpy project can be excluded by checking the Skip external folders check box. The Folder option enables you to browse for the required folder; the XPath expression will be evaluated against XML files in this folder.

2.Select the XPath version you wish to use (1.0, 2.0, or 3.1) by clicking the appropriate icon in the toolbar of the output window (see screenshot below).
3.Select the type of XPath expression from the dropdown list. Allow Complete XPath is the usually required option. The other options of this combo box are XML Schema Selector and XML Schema Field, which can be used for a narrow subset of specific XPath 1.0 cases and are useful when unique identity constraints have been defined in the XML Schema. When either of these options is selected, only name tests (and the wildcard *) are allowed in the XPath expression, and predicates and XPath functions may not be used. Furthermore, for the XML Schema Selector option, only expressions on the child axis are allowed; for the XML Schema Field option, expressions on the child axis and attribute axis are allowed. For more information, see the W3C's XML Schema: Structures Recommendation. When the XPath version you select is not XPath 1.0, then the combo box is disabled: Allow Complete XPath is selected by default and cannot be changed.
4.Toggle the Evaluate XPath Expression On Typing icon ic_xpath_dynamiceval on if you want the XPath expression to be evaluated while you are typing it in. If this icon is toggled off, the expression will be evaluated only when you click the Evaluate XPath Expression icon ic_xpath_evaluate.
5.Toggle the Show Header In Output icon ic_xpath_showheader on if, in the output, you wish to show the XPath expression and the location of the XML file (as in the screenshot below).
6.If the XPath expression returns nodessuch as elements or attributesyou can select whether the entire contents of the selected nodes should be shown. This is done by switching the Show Complete Result icon ic_xpath_complete result on.

 

OutputBarXPathFullResult

 

7.To set an XPath expression relative to a selection in the XML document, toggle the Set Current Selection As Origin icon ic_xpath_relative on.
8.Click the Validate XML files icon XPWinValidateXML to validate the XML files being evaluated for the XPath/XQuery expression. By default, the option is selected. Errors are treated as warnings and evaluation continues.
9.Enter the XPath expression. If you wish to create the expression over multiple lines (for easier readability), use the Return key.
10.You can increase/decrease the size of text in the expression field. Do this by clicking in the expression field, then pressing Ctrl and turning the scroll wheel.
11.Instead of manually entering the locator path expression of a node, you can let XMLSpy enter it for you. Do this as follows: (i) Place the cursor at the point in the XPath expression where you want to enter the locator path; (ii) Place the cursor in the start tag of the node you want to target; (iii) In the XPath/XQuery Window, click the Copies the XPath of the Current Selection to the Edit Field icon XPWinCreateXPFromSelLoc to enter the locator path of the selected node into the expression. The locator path will be entered as an absolute path starting at the root node of the document.
12.If the Show XPath Auto-completion icon ic_ShowXPathAutoComplete has been toggled on, a popup will show a list of XPath functions and axes, and document elements and attributes that can be validly inserted at this point, and from which you can choose.
13.To evaluate the expression (if Evaluate on Typing is toggled off or when a new XML document is made active), click the Evaluate XPath Expression icon.

 

Results pane of the Evaluator tab

The Evaluator tab has a Results Pane (see screenshot above). The pane has the following functionality:

 

If the evaluation is carried out on multiple files (specified in the Where option), then the results of each file are listed separately under the path of that file (see screenshot above).
If the evaluation mode is XML, then XML conformant files are evaluated, other types are skipped (see screenshot above). If the evaluation mode is JSON, then JSON conformant files are evaluated, other types are skipped. See JSON Transformations with XSLT/XQuery for information about querying JSON documents.
When the result contains a node (including a text node)as opposed to expression-generated literalsclicking on that node in the Result Pane highlights the corresponding node in the XML document in the Main Window.
The result list consists of two columns: (i) a node name or a datatype; (ii) the value of the node. You can copy both columns of a result sub-line, or only the value column. Right-click a sub-line and toggle on/off Copying Includes All Columns. (Alternatively you can toggle the command on/off via its icon in the toolbar.) Then right-click the sub-line you want to copy and select either Copy Subline or Copy All.

 

The toolbar of the Evaluator tab contains icons that provide navigation, search, and copy functionality. These icons, starting from the left, are described in the table below. The corresponding commands are also available in the context menu of result list items.

 

Icon

What it does

Next, Previous

Selects, respectively, the next and previous item in the result list

Copy the selected text line to the clipboard

Copies the value column of the selected result item to the clipboard. To copy all columns, toggle on the Copying includes all columns command (see below)

Copy all messages to the clipboard

Copies the value column of all result items to the clipboard, including empty values. Each item is copied as a separate line

Copying includes all columns

Switches between copying (i) all columns, or (ii) only the value column. The column separator is a single space

Find

Opens a Find dialog to search for any string, including special characters, in the result list

Find previous

Finds the previous occurrence of the term that was last entered in the Find dialog

Find next

Finds the next occurrence of the term that was last entered in the Find dialog

Clear

Clears the result list

Collapse multi-line results to a single line

If the value column of a result item contains multi-line text (text that includes newline character/s), you can toggle between a multi-line and single-line display

 


© 2019 Altova GmbH