libsablot/doc/misc/DEBUGGER

   1 -*- mode: outline -*-
   2
   3 * Introduction
   4
   5 Since the version number of 0.96 Sablotron supports a debugging of
   6 stylesheets. Although it is just an experimental state, it works quite
   7 fine, and may be found useful by many XSLT developers.
   8
   9 * License
  10
  11 !!! Important change, read this !!!
  12
  13 The Sablotron library is dual-licensed. You may choose either of MPL
  14 or GPL.
  15
  16 Optionally the debugger command line interface uses a great GNU library
  17 'readline'. This library may not be linked to non GPL'ed programs, so
  18 if you want to use the debugger, you have to choose the GPL from
  19 Sablotron license model.
  20
  21 See the *Building* section, how to do it.
  22
  23 * Building
  24
  25 For short, all you need is to pass the --enable-debugger to the
  26 configure script. If you want to use the readline library (what is
  27 great), read the detailed description.
  28
  29 To enable the debugger, you need meed following:
  30
  31 1. Optionally you may install ``readline'' and ``ncurses'' libraries
  32    of GNU. (nice systems have it by default) and make it available to
  33    the compiler and linker (you may use CPLUS_INCLUDE_PATH and
  34    LIBRARY_PATH environment).
  35
  36 2. If you want to use the readline library, you have to confirm, that
  37    you accept the GPL license terms. You do it with setting the
  38    SABLOT_GPL environment to whatever else then empty string. You need
  39    set this variable when the configure script is ran (later it is not
  40    needed).
  41
  42 3. You have to add the --enable-debugger to the configure script.
  43
  44 4. Optionally you may set the --with-readline too.
  45
  46 That should be enough.
  47
  48 * Invocation
  49
  50 Run 'sabcmd --debugger'. That's all.
  51
  52 * Features
  53
  54 You may trace, how your templates are executing. The only point, where
  55 the debugger may stop the execution is the element start.
  56
  57 ** Setting the Data
  58
  59 The first thing, you need to do is to specify the stylesheet and the
  60 data file. Use the `sheet' and `data' commands for it.
  61
  62 If you want to set external parameters (for top level <xsl:param>
  63 elements) use the `param' command.
  64
  65 ** Running the Transformation
  66
  67 Use the `run' command to fire the processor. A new processor instance
  68 is created for any new round.
  69
  70 If the debugger stooped at the breakpoint, you may use the `cont'
  71 command to run further.
  72
  73 You may use the `templ' command to run the processor and stop in the
  74 first template called.
  75
  76 If you want to kill currently running transformation, use the `kill'
  77 command.
  78
  79 ** Setting Breakpoints
  80
  81 You may use the `break' command to set the breakpoint. Processor then
  82 stops on marked line every time it hits it.
  83
  84 There are some issues:
  85
  86   - breakpoint must be set at the line with the element start
  87
  88 Another command are `B' - list all breakpoints and `D' delete all
  89 breakpoints.
  90
  91 You may toggle a breakpoint enabled/disabled with the `disable'
  92 command.
  93
  94 You may set a XPath expression for the breakpoint, what is evaluated
  95 each time the breakpoint is met. The breakpoint takes an effect only
  96 if this expression is true.
  97
  98 ** Walking Trough the Source
  99
 100 You may use the `step' command to move to the next element start.
 101
 102 You may use the `next` command to move to the next sibling of the
 103 current element.
 104
 105 You may use the `finish' command to move to the next sibling of the
 106 parent of the current element.
 107
 108 Suppose:
 109
 110 <xsl:template>
 111   <a>
 112 ->  <b>
 113       <c/>
 114       <d/>
 115     <b>
 116     <d/>
 117   <a>
 118   <x/>
 119 </xsl:template>
 120
 121 The arrow marks, where you are. In this case
 122
 123 `step'   - goes to <c>
 124 `next'   - goes to <d>
 125 `finish' - goes to <x>
 126
 127 The very special (and very useful) command id the `templ'
 128 command. This one continues the execution, until any template is
 129 executed. It may be used to run the transformation as well as to resume
 130 stopped execution.
 131
 132 ** XPath Evaluation
 133
 134 You may evaluate any XPath expression using the `eval' command. It
 135 evaluates in the current context and displays the result and its type.
 136
 137 ** Examinig the Context
 138
 139 You may examine the current context with the `x' command.
 140
 141 x     - shows brief info
 142 x all - list all context nodes
 143 x n   -  detailed info on the n-th context node (n is an integer)
 144
 145 ** Batches
 146
 147 You may create files containing the sequences of you favorite commands
 148 (one per line) and execute them with the `batch' command
 149
 150 ** Abbreviations
 151
 152 You need to type as few letters to specify the command as is needed to
 153 recognize, what you mean. The most frequent command may be run with
 154 single command not caring, whether another command starts with this
 155 letter. The `s' abbrev runs the `step' command rather the `sheet'.
 156
 157 * Emacs Integration
 158
 159 There is an Emacs library available. You may use it, if you want to
 160 debug your stylesheets and see, what is happening.
 161
 162 You need to grab the sabdbg.el from the Sablotron source tree.
 163
 164 Next you need to put something like this into your .emacs file:
 165
 166 (load "sabdbg.el")
 167 (sabdbg-set-keys)
 168
 169 The sabdbg-set-keys function should be called the best from some hook
 170 for your favorite xsl mode.
 171
 172 We use the xml-mode (part of psgml-mode). My .emacs looks like this:
 173
 174 (add-hook 'xml-mode-hook
 175           (function (lambda ()
 176                       ;;set debugger staff
 177                       (when (string-match "\\.xsl$" buffer-file-name))
 178                       (sabdbg-init))))
 179
 180 As the result several keys should be mapped locally in you buffers for
 181 the XSL files.
 182
 183 (local-set-key [(control c)(control g)(control x)] 'sabdbg-debug-current)
 184 (local-set-key [(control c)(control g)(control s)] 'sabdbg-step)
 185 (local-set-key [(control c)(control g)(control n)] 'sabdbg-next)
 186 (local-set-key [(control c)(control g)(control t)] 'sabdbg-step-template)
 187 (local-set-key [(control c)(control g)(control c)] 'sabdbg-continue)
 188 (local-set-key [(control c)(control g)(control p)] 'sabdbg-show-point)
 189 (local-set-key [(control c)(control g)(control b)] 'sabdbg-set-breakpoint)
 190 (local-set-key [(control c)(control g)(control r)] 'sabdbg-run)
 191
 192 E.g. while you are in the buffer holding the XSL file, you may press
 193 and hold control and press `c' `g' `x' sequence to execute the
 194 debugger and set the current buffer file name as the stylesheet.
 195
 196 Next you need to use the `data' command in the debugger buffer, switch
 197 back to the stylesheet and continue debugging using mapped keys.
 198
 199 sabdbg-debug-current
 200   opens debugger for current buffer (only one debugger may be ran at once
 201
 202 sabdbg-step
 203   steps the debugger
 204
 205 sabdbg-next
 206   preform the `next' command
 207
 208 sabdbg-step-template
 209   perform the `templ' command
 210
 211 sabdbg-continue
 212   continues the execution
 213
 214 sabdbg-show-point
 215   synchronize file displayed with debugger
 216
 217 sabdbg-set-breakpoint
 218   sets breakpoint to file and line, where currently the point is
 219
 220 sabdbg-run
 221   runs processor