qxsldbg 4.7.0

Usage documentation

Keith Isdale

Version: 4.7.0

Abstract

qxsldbg is a provides a graphic user interface front end to xsldbg; which supports debugging of XSLT scripts via API added to the libxslt library.

For details of license and contributers see the Chapter 4, Credits and Licence section.

A good deal of effort has been put into

For details of recent changes see qxsldbg ChangeLog file.


Table of Contents

1. Introduction
Features
2. Installation
How to obtain qxsldbg
Requirements
Compilation and Installation
3. Using qxsldbg
Quick Start Guide
The Basics
Inspecting Data in found it XSLT context
Configure the files, options and parameters to use
Getting started
Working with options
Working with parameters
Apply changes
Using the main window
Working with the main window
Working with xsldbg output
Working with the tool bars
Setting and modifying breakpoints
Adding a Breakpoint
Deleting a breakpoint
Deleting all breakpoints
Enabling/disabling a breakpoint
Working with the callstack
Working with templates
Working with variables
Global variables
Local variables
Working with XSLT source files (Sources)
Working with XML data files (Entities)
Miscellenous tools
Inspector tool
Execute by walking
Execute by tracing
Lookup XML entities - SystemID
Lookup XML entities - PublicID
4. Credits and Licence
Licence
Thanks to

List of Tables

2.1. Required libraries
3.1. Tool bar icons and thier meaning

Chapter 1. Introduction

Table of Contents

Features

Features

Provides access to most of xsldbg commands to

  • Set and modify breakpoints

  • Display value of expressions

  • Display in formation about breakpoints, templates, variables, callstack, stylesheets and entities found

  • Move around XSL source and XML document via XPaths

  • Lookup PUBLIC and SYSTEM ID's in the current XML catalog

Chapter 2. Installation

How to obtain qxsldbg

See: Download qxsldbg from source forge

Requirements

The following libraries are required

Table 2.1. Required libraries

pthreadnot needed under WIN32
xsldbgsupplied by xsldbg, part of qxsldbg package 4.5.0 or later
qtnotifersupplied by xsldbg, part of qxsldbg package 4.5.0 or later
ncursesoptional, not needed under WIN32
readlineoptional, not needed under WIN32
historyoptional, not needed under WIN32
QtQT5.5 or greater
xml2supplied by libxml2
xsltsupplied by libxslt and libxslt has XSLT debuging support enable (done by default)
exsltsupplied by libexslt

Compilation and Installation

For details on compilation see the provided *README* file in the topmost directory of qxsldbg source package.

Chapter 3. Using qxsldbg

Quick Start Guide

The Basics

  • Start qxsldbg from "Development" Desktop menu or where it was compiled.

  • Click the (Configure) button in tool bar.

  • In the dialog that now is visable choose the xsldoc.xsl as the "XSL source", xsldoc.xml as the "XML data file", and dump.txt as the "Output file".

  • Click the "Apply" button on the dialog.

  • Click the (Run) button in toolbar to update qxsldbg with the new configuration.

  • Click the (Step) button on the toolbar and xsldoc.xsl will display with the cursor at the first debuggable line in xsldoc.xsl. Press the "Continue" toolbar button and xsldbg will run the stylesheet and stop at the first debuggable line in xsldoc.xsl.

  • Click the (Continue) button to contiue running XSLT transform to the end.

  • Click the (Output) button on toolbar to view result of XSLT transform.

  • To reload the current file displayed use the (Refresh) toolbar button.

  • The result of last execution of the stylesheet will be shown in Xsldbg Outut window, by default docked at the bottom of screen.

Inspecting Data in found it XSLT context

  • Once the XSLT engine has reach its first *valid* node you can enter any valid XPath expression in the field next to a "Evaluate" button

  • For example, using "XPath query" box enter $xsldbg_version and press the "Evaluate" button, after a moment the value of $xsldbg_version will be displayed.

Configure the files, options and parameters to use

You start configuration by clicking the(Configure) button in the toolbar

The dialog show below then is displayed

Getting started

To be able to run a stylesheet you need to specify the

  • XSL source

  • XML data

  • Output file

By using the ".." button to choose file desired. Be sure to check that the "Output file" is not the same as the other files.

To follow along with the examples

  • For the XSL source use <qxsldbg root>/tests/test2.xsl

  • For XML data use <qxsldbg root>/tests/test2..xml

  • For Output file use dump.txt

Working with options

You can select zero or more options from the "Options". Each option has a tool tip with a hint on what effect it has.

Working with parameters

You can add zero or more parameters via the "Libxslt parameters" section of dialog. This allows you to provide parameter values to the stylesheet

For example if you had a stylesheet like addparam.xsl you could add a parameter called myparam with a value of Hello World!. To update the value of an existing parameter just add it again with the new value desired. ( Hint: To view addparam.xsl use the right mouse button and choose a text editor to view file. )

Apply changes

For the changes you have made to take effect press the "Apply" button or press the "Cancel" button to cancel changes made.

To change the configuration again later just click the configure button

Using the main window

qxsldbg provides a text view of the current file being debugged,as seen in the image below

Working with the main window

In the text viewer the following indication are used to show execution/cursor focus

  • the next line be executed is highlighted with a green background

  • the cursor position is shown via underline text style or a flashing cursor

There are two coloured markers that are can show up on the start of a line of text

  • A red mark: Indicating an active breakpoint

  • A yellow mark: Indicating a disabled breakpoint

To set/disable/delete a breakpoint at the start of a XML node by *double* click of left mouse button.

To move the cursor arround the text use the

  • Arrow keys: left, right, up, down

  • Page keys: page up, page down

Working with xsldbg output

Most of the output from xsldbg is captured and presented either in the inspectors dialog or the xsldbg output window. The exceptions to this rule are

  • An error message that comes from xsldbg is displayed inside a message dialog.

  • The result of evaluating an expression is displayed in a message dialog

  • The output of search is sent to the file indicated in the xsldbg output window

Working with the tool bars

Table 3.1. Tool bar icons and thier meaning

Configure application see: the section called “Configure the files, options and parameters to use”
Open inspector dialog showing data obtained from xsldbg.
Restart execution applying current configuration
Continue execution stoping at next breakpoint. This will cause the debugger to stop at the start of the stylesheet if no further breakpoints are found
Step to the next XSLT instruction found.
Proceed to the next instruction at the same call stack depth. This is useful for stepping over a xsl:appply-templates or xsl:call-template
Proceed to the next instruction in a cooler stack frame. This is best used within a template at a greater depth than the root match template
Proceed to the next instruction in a warmer stack frame.
Add a breakpoint at the current cursor location
Enable or disable a breakpoint at the current cursor location
Delete a breakpoint at the current cursor location
Cause the current XSLT source file to be shown
Cause the current XML data file to be shown
Cause the current Output file to be shown
Cause the displayed file to be reloaded from disk


Setting and modifying breakpoints

The primary way to work with breakpoints is via the main window see the section called “Using the main window”

Once you have started the stylesheet you can use the Tools->Show inspectors menu item. Then click on the "Breakpoints" tab. See below for an example

Adding a Breakpoint

To add a breakpoint in Inspector dialog supply either

  1. a file and line number of *either* XSLT script being debugged *or* XML data file being transformed by XSLT script

  2. a template name

  3. a template name and a mode name

  4. a mode name

And then pressing the "Add" button

Argument details for Breakpoints
  1. A file name may be absolute path to a local file or 'basename' for file eg: test2.xsl

  2. A template or mode name supports fully Qualified Name where the non-local part is optional eg. xsl:mytemplate is matched by mytemplate

Deleting a breakpoint

Firstly left mouse click the breakpoint you want to delete in the list of current breakpoints. Then click the "Delete" button.

Deleting all breakpoints

Click the "Delete all" button.

Enabling/disabling a breakpoint

Firstly left mouse click the breakpoint you want to delete in the list of current breakpoints. Then click the "Enable" button.

Working with the callstack

All call stack items found are listed here. The older the callstack entry the lower the frame number it will have.

Note that clicking on a callstack entry in the list shown will cause the cursor in the main window to move to the file and line number indicated.

See below for an example of "Call Stack" tab

Working with templates

If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with templates click on the templates tab of dialog shown

All templates found are listed here. Please note that the export rules of XSLT apply. So only there may be more than one template with the same match and mode details. xsl:param. Clicking on a template entry in the list shown will cause the cursor in the main window to move to the file and line number indicated.

To find a the template enter a partial *or* full name of template into the "Template name" field then click the "Search" button. To reset template view to defaults clear value from the "Template name" field.

See below for an example of templates page within Inspector

Working with variables

Local and global XSLT variables are show in separate tabs on the inspector dialog.

If the inspector dialog is not showing use the Tools->Show inspectors menu item.

Note that clicking on a variable entry with known file name/line number will cause the cursor in the main window to move to the file and line number indicated.

To see value of expression

  • Enter XPath expression in "Expression" field

  • Click "Evaluate" button

Global variables

The Global variables tab shows XSLT variables that are global in scope (defined outside of a template).

See below for an example the "Global Variables" tab

Local variables

The Local variables tab shows XSLT variables that are local in scope (available within a template).

Some variables can be edited via

  • Selecting variable in list

  • Enter new value in "Variable expression" field

  • Clicking "Set Expression" button

See below for an example the "Local Variables" tab

Working with XSLT source files (Sources)

If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with sources click on the sources tab of dialog shown

All XSLT source files that are included by the XSLT file or one of its simblings are listed here. See below for an example

Clicking on a source entry in the list shown will cause the cursor in the main window to move to the start of file indicated.

Working with XML data files (Entities)

If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with entities click on the Entities tab of dialog shown

All external XML entities included via the DATA file or one of its siblings are listed here. For this example I have run qxsldbg on test14.xsl with test14.xml (found in the tests directory of xsldbg source distribution) so that you can see some entities. See below for an example

Clicking on a entity entry in the list shown will cause the cursor in the main window to move to the start of the file indicated.

Miscellenous tools

Several tools are available via the tools menu, the main tool is the inspector tool.

Inspector tool

The inspector tool is the contains all the individual dialogs for working with

  • Breakpoints

  • Global Variables

  • Local Variables

  • Callstack entries

  • Templates

  • Source files

  • XML Enties

Execute by walking

By clicking on "Start execution with walking" menu a dialog is shown to allow the walk speed to be chosen

To stop walking either use the "W" key or select the "Stop execution with walking" menu item

Execute by tracing

By clicking on "Start execution with tracing" this will cause XSLT transformation to run completely with resulting output shown in "Xsldbg Output" window. See also the section called “Working with xsldbg output”

To tracing select the "Stop execution with walking" menu item

Lookup XML entities - SystemID

To lookup a System ID in the current XML catalog use the "Lookup System ID" menu then enter path of entity to find such as "notemessage2.xml"

Lookup XML entities - PublicID

To lookup a PUBLIC ID use the "Lookup Public ID" menu then enter path of entity to find such as "-//xsldbg//tests notemessage2 XML V1.0//EN"

Chapter 4. Credits and Licence

Table of Contents

Licence
Thanks to

Licence

qxsldbg is under the GPL 2 or later at your choiceGPL License text

Thanks to

  • The writers of libxml and libxslt for their support in adding debugging to libxslt.

  • Robert JACOLIN for feedback on earlier version of qxsldbg

  • Igor Zlatkovic for creating WIN32 binaries of libxml/xslt and xsldbg