Project

Profile

Help

How to connect?
Download (30.8 KB) Statistics
| Branch: | Revision:

he / src / userdoc / gizmo.xml @ d9cb5c62

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="gizmo" title="The Gizmo Utility">
3
  <h1>The Gizmo Utility</h1>
4
  
5
  <p>Saxon (from 10.0) provides the Gizmo command line utility, which can be used interactively or in batch mode, 
6
    to perform simple operations such as examining the content of a document, renaming or deletion of 
7
    selected elements in the document, or performing simple XSLT transformation and XSD validation.</p>
8
  
9
    <p>The utility can be started from the command line using the Java entry-point class
10
  <code>net.sf.saxon.Gizmo</code>, and its actions are controlled by sub-commands entered one per line, either
11
      on the standard input, or in a file named in the <code>-q</code> option.</p>
12
  
13
  <aside><p>Gizmo uses a library called JLine2 to handle terminal input and output. The JLine2 library provides
14
    basic command-line editing capabilities such as copy/paste; it also maintains command history (so you can
15
    recall previous commands using the up-arrow key), and offers content completion suggestions using the
16
    tab key.</p>
17
    <p>The JLine2 library is delivered with the Saxon product, but as a separate JAR file. To run Gizmo
18
      from the command line, the classpath must contain both the standard Saxon JAR file (for example
19
      <code>saxon-pe-10.0.jar</code>), and also the JLine2 JAR file, which is named <code>jline-2.9.jar</code>.</p></aside>
20
  
21
  <h2 class="subtitle">Command Line Syntax</h2>
22
  
23
  <kbd>java net.sf.saxon.Gizmo [-s:source.xml] [-q:script.txt]</kbd>
24
  
25
  <ul>
26
    <li><code>-s:source.xml</code> defines the source document supplied as the input to the 
27
      pipeline of sub-commands. If omitted, input is taken from standard input.</li>
28
    <li><code>-q:script.txt</code>. Identifies a filename containing sub-commands to be executed, one per line.
29
      By default, sub-commands are taken from standard input.</li>
30
  </ul>
31
  
32
  <p>Each line of input is a sub-command. The various sub-commands are listed in the following sections.</p>
33
  
34
  <p>At any point in the processing, there is (or is not) a current document. 
35
    On entry, the current document is the source document
36
    identified in the <code>-s</code> option, if specified. Many of the sub-commands change the current document. The current document
37
    may be inspected using the <a class="bodylink" href="show">show</a> sub-command, and
38
    may be saved to filestore using the <a class="bodylink" href="save">save</a>
39
    sub-command.</p>
40
  
41
  <p>Most of the sub-commands select nodes within the current document using an XPath expression.
42
    If unprefixed element names appear within the expression, they match nodes in the source document
43
    by local-name alone. (That is, <code>X</code> means <code>*:X</code>). If you only want to select
44
    no-namespace names, use the form <code>Q{}X</code>.</p>
45
  
46
  <p>Within XPath expressions, content completion is available for (a) recognized XPath keywords
47
    such as "following-sibling", and (b) the names of elements and attributes appearing in the
48
    current source document when it was first loaded.</p>
49
  
50
  <p>Some of the sub-commands also have a second argument which is a query. Generally this will be
51
    an XQuery element constructor such as <code><![CDATA[<a>Title: {string(.)}<a/>]]></code>. It is
52
    evaluated with the context item set to each item selected by the first expression, in turn.</p>
53
   
54
   <nav>
55
      <ul/>
56
   </nav>
57
  
58
  <section id="copy" title="The copy command">
59
    <h1>The copy command</h1>
60
    
61
    <p><i>Syntax:</i></p>
62
    <kbd>copy <i>expression</i></kbd>
63
    
64
    <p>Deletes everything other than the nodes selected by the expression; returns a new document
65
      containing only the selected nodes. Note that if the expression selects multiple elements,
66
      the new document will not be a well-formed XML document (it will be a "fragment").</p>
67
    
68
    <p>The result of the operation can be inspected using the command 
69
      <a class="bodylink" href="../show">show</a>.</p>
70
    
71
    <h3 class="subtitle">Example</h3>
72
    
73
    <p>The command:</p> 
74
    <kbd>copy //img</kbd> 
75
    <p>returns a document containing as its children copies of all the <code>img</code> elements in
76
      the source.</p>
77
    
78
  </section>
79
  
80
  <section id="call" title="The call command">
81
    <h1>The call command</h1>
82
    
83
    <p><i>Syntax:</i></p>
84
    <kbd>call {filename}</kbd>
85
    
86
    <p>Executes the script contained in the specified file.</p>
87
    <p>The script shares the context with the calling script. It has access to the variables and namespaces
88
    declared in the calling script, and any variables and namespaces that it declared are available to the
89
    caller on return.</p>
90
    
91
  </section>
92
   
93
   <section id="delete" title="The delete command">
94
     <h1>The delete command</h1>
95
     
96
      <p><i>Syntax:</i></p>
97
      <kbd>delete <i>expression</i></kbd>
98
      
99
      <p>The selected nodes (elements, attributes, or namespaces) are deleted, along with their children and descendants.</p>
100
     
101
     <p>The result of the operation can be inspected using the command 
102
       <a class="bodylink" href="../show">show</a>.</p>
103
     
104
     <h3 class="subtitle">Example</h3>
105
     
106
     <p>Given a source document:</p>
107
     <samp><![CDATA[<cities>
108
  <city name="Berlin" country="DE"/>
109
  <city name="Paris" country="FR"/>
110
  <city name="Rome" country="IT"/>
111
</cities>]]></samp>
112
     
113
     <p>The command:</p>
114
     <kbd>delete //city[@name='Rome']</kbd>
115
     <p>produces the document:</p>
116
     <samp><![CDATA[<cities>
117
  <city name="Berlin" country="DE"/>
118
  <city name="Paris" country="FR"/>
119
</cities>]]></samp>
120
     
121
   </section>
122
  
123
  <section id="follow" title="The follow command">
124
    <h1>The follow command</h1>
125
    
126
    <p><i>Syntax:</i></p>
127
    <kbd>follow <i>expression</i> with <i>query</i></kbd>
128
    
129
    <p>After each node <i>N</i> selected by the expression, the query is evaluated (with <i>N</i> as the context item), and its result is 
130
      inserted as an immediate following sibling of <i>N</i>. Both the expression and the query must return nodes that are capable of having
131
    siblings: that is, element, text, comment, or processing instruction nodes. But if the query returns an atomic value,
132
    it is treated as a text node with the same string value.</p>
133
    
134
    <p>The result of the operation can be inspected using the command 
135
      <a class="bodylink" href="../show">show</a>.</p>
136
    
137
    <h3 class="subtitle">Examples</h3>
138
    
139
    <p>The command:</p> 
140
    <kbd>follow //img with &lt;caption/></kbd> 
141
    <p>inserts an empty <code>&lt;caption/></code> element
142
      after every <code>img</code> element in the document.</p>
143
    
144
    <p>Given a source document:</p>
145
    <samp><![CDATA[<cities>
146
  <city name="Berlin" country="DE"/>
147
  <city name="Paris" country="FR"/>
148
  <city name="Rome" country="IT"/>
149
</cities>]]></samp>
150
    
151
    <p>The command:</p>
152
    <kbd>follow //city[@name='Paris'] with &lt;city name="Lyon" country="{@country}"/></kbd>
153
    <p>produces the document:</p>
154
    <samp><![CDATA[<cities>
155
  <city name="Berlin" country="DE"/>
156
  <city name="Paris" country="FR"/>
157
  <city name="Lyon" country="FR"/>
158
  <city name="Rome" country="IT"/>
159
</cities>]]></samp>
160
    
161
  </section>
162
  
163
  <section id="help" title="The help command">
164
    <h1>The help command</h1>
165
    
166
    <p><i>Syntax:</i></p>
167
    <kbd>help <i>keyword</i></kbd>
168
    
169
    <p>If the keyword is the name of a command, a brief summary of the syntax and purpose of the command is displayed.</p>
170
    <p>If the keyword is omitted, a list of available commands is displayed.</p>
171
    
172
  </section>
173
   
174
  <section id="list" title="The list command">
175
    <h1>The list command</h1>
176
    
177
    <p><i>Syntax:</i></p>
178
    <kbd>list <i>expression</i></kbd>
179
    
180
    <p>Outputs a representation of the result of the expression.</p>
181
    <p>If a node is selected, it is shown as a path (for example <code>DOC/SECTION[3]/PARA[2]</code>), preceded
182
    by a line number if one is available.</p>
183
    <p>If an atomic value is selected, its string value is displayed.</p>
184
    
185
    <p>Line numbers are available in documents loaded directly from filestore, but not
186
      in documents constructed using commands such as <code>rename</code> or <code>delete</code>.</p>
187
    
188
    <h3 class="subtitle">Example</h3>
189
    
190
    <p>Given a source document:</p>
191
    <samp><![CDATA[<cities>
192
  <city name="Berlin" country="DE"/>
193
  <city name="Paris" country="FR"/>
194
  <city name="Rome" country="IT"/>
195
</cities>]]></samp>
196
    
197
    <p>The command:</p>
198
    <kbd>list //city[@name='Paris']</kbd>
199
    <p>displays:</p>
200
    <samp>Line 3: /cities/city[2]</samp>
201
    
202
  </section> 
203
  
204
  <section id="load" title="The load command">
205
    <h1>The load command</h1>
206
    
207
    <p><i>Syntax:</i></p>
208
    <kbd>load <i>filename</i></kbd>
209
    
210
    <p>The current document is discarded, and a new current document is loaded from the specified file.</p>
211
    
212
    <p>If the filename is relative, it is taken as being relative to the current working directory.</p>
213
    
214
    <p>The user's home directory can be referred to as <code>~</code>.</p>
215
    
216
    <p>Content completion is available: use the tab key to suggest possible names at each level.</p>
217
      
218
  </section> 
219
  
220
  <section id="namespace" title="The namespace command">
221
    <h1>The namespace command</h1>
222
    
223
    <p><i>Syntax:</i></p>
224
    <kbd>namespace {prefix} {uri}</kbd>
225
    
226
    <p>Binds a namespace prefix to a URI. QNames using this prefix may be used in subsequent
227
    XPath expressions within the script.</p>
228
    <p>Note that the conventional prefixes <code>xml</code>, <code>xsl</code>, <code>saxon</code>, <code>xs</code>, 
229
      <code>xsi</code>, <code>fn</code>, <code>math</code>, <code>map</code>, and <code>array</code> are
230
    already bound to the conventional namespace URIs.</p>
231
    
232
    <p>In path expressions, unprefixed names match by local name only, so it is usually possible
233
    to select elements without binding a namespace prefix.</p>
234
    
235
  </section>
236
  
237
  <section id="paths" title="The paths command">
238
    <h1>The paths command</h1>
239
    
240
    <p><i>Syntax:</i></p>
241
    <kbd>paths</kbd>
242
    
243
    <p>Outputs a list of the distinct element paths that exist in the current source document. They are output
244
    in order of first appearance, when scanning the tree in document order.</p>
245
    
246
    <p>This command is useful to get an overview of the structure of the source document, especially if it is
247
    too large to display comfortably.</p>
248
    
249
    <h3 class="subtitle">Example</h3>
250
    
251
    <p>For example, given the <code>books.xml</code> data file included with the Saxon resources
252
    download, the output would be:</p>
253
    
254
    <samp>
255
      Found 16 items
256
      /BOOKLIST
257
      /BOOKLIST/BOOKS
258
      /BOOKLIST/BOOKS/ITEM
259
      /BOOKLIST/BOOKS/ITEM/TITLE
260
      /BOOKLIST/BOOKS/ITEM/AUTHOR
261
      /BOOKLIST/BOOKS/ITEM/PUBLISHER
262
      /BOOKLIST/BOOKS/ITEM/PUB-DATE
263
      /BOOKLIST/BOOKS/ITEM/LANGUAGE
264
      /BOOKLIST/BOOKS/ITEM/PRICE
265
      /BOOKLIST/BOOKS/ITEM/QUANTITY
266
      /BOOKLIST/BOOKS/ITEM/ISBN
267
      /BOOKLIST/BOOKS/ITEM/PAGES
268
      /BOOKLIST/BOOKS/ITEM/DIMENSIONS
269
      /BOOKLIST/BOOKS/ITEM/WEIGHT
270
      /BOOKLIST/CATEGORIES
271
      /BOOKLIST/CATEGORIES/CATEGORY      
272
    </samp>
273
    
274
  </section>
275
  
276
  <section id="precede" title="The precede command">
277
    <h1>The precede command</h1>
278
    
279
    <p><i>Syntax:</i></p>
280
    <kbd>precede <i>expression</i> with <i>query</i></kbd>
281
    
282
    <p>Before each node <i>N</i> selected by the expression, the query is evaluated (with <i>N</i> as the context item), and its result is 
283
      inserted as an immediate preceding sibling of <i>N</i>. Both the expression and the query must return nodes that are capable of having
284
      siblings: that is, element, text, comment, or processing instruction nodes. But if the query returns an atomic value,
285
      it is treated as a text node with the same string value.</p>
286
    
287
    <p>The result of the operation can be inspected using the command 
288
      <a class="bodylink" href="../show">show</a>.</p>
289
    
290
    <h3 class="subtitle">Examples</h3>
291
    
292
    <p>The command:</p> 
293
    <kbd>precede //img with &lt;caption/></kbd> 
294
    <p>inserts an empty <code>&lt;caption/></code> element
295
      before every <code>img</code> element in the document.</p>
296
    
297
    <p>Given a source document:</p>
298
    <samp><![CDATA[<cities>
299
  <city name="Berlin" country="DE"/>
300
  <city name="Munich" country="DE"/>
301
  <city name="Paris" country="FR"/>
302
  <city name="Lyon" country="FR"/>
303
  <city name="Rome" country="IT"/>
304
</cities>]]></samp>
305
    
306
    <p>The command:</p>
307
    <kbd>precede //city[not(@country=preceding-sibling::*[1]/@country)] with &lt;country name="{@country}"/></kbd>
308
    <p>produces the document:</p>
309
    <samp><![CDATA[<cities>
310
  <country name="DE"/>
311
  <city name="Berlin" country="DE"/>
312
  <city name="Munich" country="DE"/>
313
  <country name="FR"/>
314
  <city name="Paris" country="FR"/>
315
  <city name="Lyon" country="FR"/>
316
  <country name="IT"/>
317
  <city name="Rome" country="IT"/>
318
</cities>]]></samp>
319
    
320
  </section>
321
  
322
  <section id="prefix" title="The prefix command">
323
    <h1>The prefix command</h1>
324
    
325
    <p><i>Syntax:</i></p>
326
    <kbd>prefix <i>expression</i> with <i>query</i></kbd>
327
    
328
    <p>For every node <i>N</i> selected by the expression, the query is evaluated (with <i>N</i> as the context item), and its result is 
329
      inserted as the first child of <i>N</i>. The expression must return nodes that are capable of having children (that is document
330
      or element nodes). The query must return nodes that are capable of having
331
      siblings (that is, element, text, comment, or processing instruction nodes). But if the query returns an atomic value,
332
      it is treated as a text node with the same string value.</p>
333
    <p>As a special case, if the query returns an attribute node, it is added as an attribute of the selected element,
334
      replacing any existing attribute with the same name.</p>
335
    
336
    <p>The result of the operation can be inspected using the command 
337
      <a class="bodylink" href="../show">show</a>.</p>
338
    
339
    <h3 class="subtitle">Examples</h3>
340
    
341
    <p>The command:</p> 
342
    <kbd>prefix //section with &lt;head>{data(@title)}&lt;/head></kbd> 
343
    <p>copies the value of the
344
      <code>title</code> attribute of every <code>section</code> element into a new <code>head</code> element appearing
345
      as the first child of the <code>section</code>.</p>
346
    
347
    <p>Given a source document:</p>
348
    <samp><![CDATA[<cities>
349
  <city name="Berlin" country="DE"/>
350
  <city name="Munich" country="DE"/>
351
  <city name="Paris" country="FR"/>
352
  <city name="Lyon" country="FR"/>
353
  <city name="Rome" country="IT"/>
354
</cities>]]></samp>
355
    
356
    <p>The command:</p>
357
    <kbd>prefix //city with &lt;country name="{@country}"/></kbd>
358
    <p>produces the document:</p>
359
    <samp><![CDATA[<cities>
360
  <city name="Berlin" country="DE">
361
    <country name="DE"/>
362
  </city>  
363
  <city name="Munich" country="DE">
364
    <country name="DE"/>
365
  </city>  
366
  <city name="Paris" country="FR">
367
    <country name="FR"/>
368
  </city>  
369
  <city name="Lyon" country="FR">
370
    <country name="FR"/>
371
  </city>  
372
  <city name="Rome" country="IT">
373
    <country name="FR"/>
374
  </city>  
375
</cities>]]></samp>
376
    
377
    <p>With the same document, the command:</p>
378
    
379
    <kbd>prefix //city with attribute{'id'}{count(preceding-sibling::*)+1}</kbd>
380
    
381
    <p>produces:</p>
382
    
383
    <samp><![CDATA[<cities>
384
  <city name="Berlin" country="DE" id="1"/>
385
  <city name="Munich" country="DE" id="2"/>
386
  <city name="Paris" country="FR" id="3"/>
387
  <city name="Lyon" country="FR" id="4"/>
388
  <city name="Rome" country="IT" id="5"/>
389
</cities>]]></samp>
390
    
391
  </section>
392
  
393
  <section id="quit" title="The quit command">
394
    <h1>The quit command</h1>
395
    
396
    <p><i>Syntax:</i></p>
397
    <kbd>quit [now]</kbd>
398
    
399
    <p>Quits the application.</p>
400
    
401
    <p>If "now" is specified, the command exits immediately. Otherwise, if the current document has been modified since
402
    it was read from filestore, the command prompts the user asking whether the document should first be saved. (See the
403
      <a class="bodylink" href="../save">save</a> command).</p>
404
    
405
  </section>
406
   
407
   
408
   
409
   <section id="rename" title="The rename command">
410
      <h1>The rename command</h1>
411
     
412
      <p><i>Syntax:</i></p>
413
     <kbd>rename <i>expression</i> as <i>expression</i> </kbd>
414
     
415
      <p>Nodes (elements or attributes) selected by the first expression are renamed; the new name is given by 
416
        computing the expression in the second argument. </p>
417

    
418
      <p>The second expression is evaluated with the existing node as the context item. If the result
419
      of the expression is a string, then this string is used as the new name of the node (if it contains a prefix,
420
      this must first be declared using the <a class="bodylink" href="../namespace">namespace</a> command). 
421
        If the result of the expression is a QName, then it defines the expanded name of the new element or attribute in its
422
      entirety. New namespace declarations will be added to the output document if required; existing namespace declarations are not
423
      removed, unless new bindings are defined for existing prefixes.</p>
424
      
425
     <h3 class="subtitle">Examples</h3>
426
     
427
      <kbd>rename //NOTE as "COMMENT"</kbd> 
428
     <p>renames all <code>NOTE</code> elements as <code>COMMENT</code> elements.</p>
429
     <kbd>rename //@* as lower-case(name())</kbd>
430
      <p>renames all attributes by converting the existing name to lower-case.</p>
431
     
432
   </section>
433
  
434
  <section id="replace" title="The replace command">
435
    <h1>The replace command</h1>
436
    
437
    <p><i>Syntax:</i></p>
438
    <kbd>replace <i>expression</i> with <i>query</i> </kbd>
439
    
440
    <p>The nodes (elements or attributes) selected by the given expression are
441
      replaced by the result of evaluating the query.</p>
442
    
443
    <p>Note that it is the entire node that is replaced, not just its content. To replace the
444
      content of an element or attribute node, rather than replacing the entire
445
      node, use the command <a class="bodylink" href="../update">update</a>.</p>
446
    
447
    <p>The result of the operation can be inspected using the command 
448
      <a class="bodylink" href="../show">show</a>.</p>
449
    
450
    <h3 class="subtitle">Examples</h3>
451
    
452
    <p>Given a source document:</p>
453
    <samp><![CDATA[<cities>
454
  <city name="Berlin" country="DE"/>
455
  <city name="Munich" country="DE"/>
456
  <city name="Paris" country="FR"/>
457
  <city name="Lyon" country="FR"/>
458
  <city name="Rome" country="IT"/>
459
</cities>]]></samp>
460
    
461
    <p>The command:</p>
462
    <kbd>replace //city[@country="DE"] with &lt;stadt @Name="{@name}"/></kbd>
463
    <p>produces the document:</p>
464
    
465
    <samp><![CDATA[<cities>
466
  <stadt Name="Berlin"/>
467
  <stadt Name="Munich"/>
468
  <city name="Paris" country="FR"/>
469
  <city name="Lyon" country="FR"/>
470
  <city name="Rome" country="IT"/>
471
</cities>]]></samp>
472
    
473
    <p>Given a source document:</p>
474
    <samp><![CDATA[<cities>
475
  <city><name>Berlin</name><country>DE</country></city>
476
  <city><name>Munich</name><country>DE</country></city>
477
  <city><name>Paris</name><country>FR</country></city>
478
  <city><name>Lyon</name><country>FR</country></city>
479
  <city><name>Rome</name><country>IT</country></city>
480
</cities>]]></samp>
481
    
482
    <p>The command:</p>
483
    <kbd>replace //city/name[.="Munich"]/text() with "München"</kbd>
484
    <p>produces the document:</p>
485
    
486
    <samp><![CDATA[<cities>
487
  <city><name>Berlin</name><country>DE</country></city>
488
  <city><name>München</name><country>DE</country></city>
489
  <city><name>Paris</name><country>FR</country></city>
490
  <city><name>Lyon</name><country>FR</country></city>
491
  <city><name>Rome</name><country>IT</country></city>
492
</cities>]]></samp>
493
    
494
    <p>With the same source document, the command:</p>
495
    <kbd>replace //name with <cityName>{.}</cityName></kbd>
496
    <p>produces the document:</p>
497
    
498
    <samp><![CDATA[<cities>
499
  <city><cityName><name>Berlin</name></cityName><country>DE</country></city>
500
  <city><cityName><name>Munich</name></cityName><country>DE</country></city>
501
  <city><cityName><name>Paris</name></cityName><country>FR</country></city>
502
  <city><cityName><name>Lyon</name></cityName><country>FR</country></city>
503
  <city><cityName><name>Rome</name></cityName><country>IT</country></city>
504
</cities>]]></samp>
505
    
506
    <p>Note that in this expression, <code>{.}</code> follows the XQuery rules rather than
507
    the XSLT rules: it copies the whole element, rather than extract its string value.</p>
508
    
509
  </section>
510
  
511
  <section id="save" title="The save command">
512
    <h1>The save command</h1>
513
    
514
    <p><i>Syntax:</i></p>
515
    <kbd>save <i>filename</i> [<i>output-param</i>=<i>value</i>]...</kbd>
516
    
517
    <p>Saves the current document to filestore, with the serialization parameters specified.</p>
518
    
519
    <p>If the file already exists, Gizmo asks "Overwrite existing file? (Y|N)" and proceeds
520
      only if the answer is "Y" or "y".</p>
521
    
522
    <p>If the filename is relative, it is taken as being relative to the current working directory.</p>
523
    
524
    <p>The user's home directory can be referred to as <code>~</code>.</p>
525
    
526
    <p>Content completion is available: use the tab key to suggest possible names at each level.</p>
527
    
528
    <h3 class="subtitle">Examples</h3>
529
    
530
    <p>The command:</p> 
531
    <kbd>save updated-data.xml method=xml indent=yes</kbd> 
532
    <p>saves the document to filestore using the XML output method with indentation.</p>
533
    
534
  </section>
535
  
536
  <section id="schema" title="The schema command">
537
    <h1>The schema command</h1>
538
    
539
    <p><i>Syntax:</i></p>
540
    <kbd>schema <i>filename</i></kbd>
541
    
542
    <aside>Requires Saxon-EE</aside>
543
    
544
    <p>Loads an XSD schema from the specified location.</p>
545
    <p>The filename is handled in the same way as the <a class="bodylink" href="../load">load</a> command.</p>
546
    <p>The schema definitions are available for use in <a class="bodylink"
547
      href="../validate">validate</a> commands issued subsequently in the session.
548
    The command is additive; the schema components are added to the collection of schema components that are already
549
    loaded, which means an error will be reported if the definitions conflict. It is not possible to unload
550
    schema definitions once loaded, except by closing the session and starting a new one.</p>
551
    
552
  </section>
553
   
554
  <section id="set" title="The set command">
555
    <h1>The set command</h1>
556
    
557
    <p><i>Syntax:</i></p>
558
    <kbd>set <i>name</i> = <i>expression</i></kbd>
559
    <kbd>set . = <i>expression</i></kbd>
560
    
561
    <p>The first form binds a variable to the value of the expression. The variable name may be written as a simple
562
    NCName, or as a lexical QName, or as an EQName in <code>Q{uri}local</code> format; it may
563
    also be preceded by a "$" sign (which is ignored).</p>
564
    <p>The variable may be used in XPath expressions and queries appearing later in the script.</p>
565
    <p>The second form:</p> 
566
    <kbd>set . = <i>expression</i></kbd>
567
    <p>may be used to set the current document. In this case the expression must evaluate to a
568
      single document node. For example:</p> 
569
    <kbd>set . = doc('books.xml')</kbd>
570
    <p>achieves the same effect as:</p>
571
    <kbd>load books.xml</kbd>
572
    
573
    <p>Note that all updating commands (such as <code>delete</code>, <code>rename</code> etc.) create
574
    a new copy of the current document. Variables that were set before the updating command continue to
575
    reference the document in the state it was in before the update.</p>
576
    <aside>To display the value of a variable, use the <a class="bodylink" href="../show">show</a>
577
      or <a class="bodylink" href="../list">list</a> commands.</aside>
578
    
579
  </section>
580

    
581
  <section id="show" title="The show command">
582
    <h1>The show command</h1>
583
    
584
    <p><i>Syntax:</i></p>
585
    <kbd>show [<i>expression</i>]</kbd>
586
    
587
    <p>Outputs a representation of the result of the expression.</p>
588
    <p>If a node is selected, it is shown as an XML serialization of the content of the node.</p>
589
    <p>If an atomic value is selected, its string value is displayed.</p>
590
    <p>The expression may be omitted, and defaults to <code>/</code>, which displays
591
    the current document.</p>
592
    
593
    <p>The document is always shown with indentation enabled, so it is not necessarily the same as the
594
      document that will be written to filestore by the <a class="bodylink" href="../save">save</a>
595
    command.</p>
596
    
597
    <h3 class="subtitle">Examples</h3>
598
    
599
    <kbd>show</kbd>
600
    
601
    <p>Displays the current document, with indentation.</p>
602
    
603
    <kbd>show //TITLE</kbd>
604
    
605
    <p>Displays selected elements, for example:</p>
606
    
607
    <samp><![CDATA[  <title>Pride and Prejudice</title>
608
  <title>Sense and Sensibility</title>
609
  <title>Emma</title>
610
  <title>Northanger Abbey</title>]]></samp>
611
    
612
    <kbd>show count(//TITLE), sort(//TITLE)</kbd>
613
    
614
    <p>Displays the result of an arbitrary XPath expression.</p>
615
    
616
    
617
  </section> 
618
   
619
   <section id="strip" title="The strip command">
620
      <h1>The strip command</h1>
621
     
622
      <p><i>Syntax:</i></p>
623
     <kbd>strip</kbd>
624
     
625
     <p>The effect is the same as:</p> 
626
     <kbd>delete //text()[not(normalize-space())]</kbd>
627
     <p>That is, all text nodes consisting entirely of whitespace are removed from the document.</p>
628
     
629
   </section>
630
 
631
  <section id="suffix" title="The suffix command">
632
    <h1>The suffix command</h1>
633
    
634
    <p><i>Syntax:</i></p>
635
    <kbd>suffix <i>expression</i> with <i>query</i></kbd>
636
    
637
    <p>For every node <i>N</i> selected by the expression, the query is evaluated (with <i>N</i> as the context item), and its result is 
638
      inserted as the last child of <i>N</i>. The expression must return nodes that are capable of having children (that is document
639
      or element nodes). The query must return nodes that are capable of having
640
      siblings (that is, element, text, comment, or processing instruction nodes). But if the query returns an atomic value,
641
      it is treated as a text node with the same string value.</p>
642
    
643
    <h3 class="subtitle">Example</h3>
644
    
645
    <p>The command:</p> 
646
    <kbd>suffix //page with &lt;copyright>Copyright (c) Saxonica 2020&lt;/page></kbd> 
647
    <p>injects a <code>copyright</code> element at the end of every <code>page</code>.</p>
648
    
649
  </section>
650
  
651
  <section id="transform" title="The transform command">
652
    <h1>The transform command</h1>
653
    
654
    <p><i>Syntax:</i></p>
655
    <kbd>transform <i>filename</i></kbd>
656
    
657
    <p>Transforms the current document using the XSLT stylesheet contained in the specified file.</p>
658
    
659
    <p>The filename is handled in the same way as the <a class="bodylink" href="../load">load</a> command.</p>
660
    
661
    <p>On completion, the result of the transformation becomes the new current document.</p>
662
    <p>Note: it is not currently possible to specify parameters to the transformation.</p>
663
    
664
  </section> 
665
  
666
  <section id="undo" title="The undo command">
667
    <h1>The undo command</h1>
668
    
669
    <p><i>Syntax:</i></p>
670
    <kbd>undo</kbd>
671
    
672
    <p>Reverts the most recent changes.</p>
673
    
674
    <p>The current document is returned to the state it was in before the most recent <code>copy</code>,
675
      <code>delete</code>,
676
      <code>follow</code>,
677
      <code>load</code>,
678
      <code>precede</code>,
679
      <code>prefix</code>,
680
      <code>rename</code>,
681
      <code>replace</code>,
682
      <code>strip</code>,
683
      <code>suffix</code>,
684
      <code>transform</code>,
685
      <code>update</code>, or
686
      <code>validate</code> command.</p>
687
    
688
    <p>It will also undo the effect of:</p> 
689
    <kbd>set . = <i>expression</i></kbd>
690
    <p>that is, it reverts to the previous current document.</p>
691
    
692
    <p>It is not possible to undo the effect of <a class="bodylink" href="../save">save</a> or
693
      <a class="bodylink" href="../schema">schema</a> commands.</p>
694
    
695
  </section> 
696
  
697
  <section id="update" title="The update command">
698
    <h1>The update command</h1>
699
    
700
    <p><i>Syntax:</i></p>
701
    <kbd>update <i>expression</i> with <i>query</i> </kbd>
702
    
703
    <p>The content of the nodes selected by the given expression is
704
      replaced by the result of evaluating the query:</p>
705
    <ul>
706
      <li><p>When an element or document node is selected, the existing children are deleted, and
707
        replaced with the result of the expression.</p></li>
708
      <li><p>When the selected element is a node kind that cannot have children, for example
709
        a comment, text node, or attribute, then its content is replaced with the string value of the
710
        query result.</p></li>
711
    </ul>
712
    
713
    <h3 class="subtitle">Examples</h3>
714
    
715
    <p>Given the source document:</p>
716
    
717
    <samp><![CDATA[<cities>
718
  <city name="Berlin" country="DE"/>
719
  <city name="Munich" country="DE"/>
720
  <city name="Paris" country="FR"/>
721
  <city name="Lyon" country="FR"/>
722
  <city name="Rome" country="IT"/>
723
</cities>]]></samp>
724
    
725
    <p>The command:</p>
726
    
727
    <kbd>update //@country[.='IT'] with "ITALIA"</kbd>
728
    
729
    <p>produces:</p>
730
    
731
    <samp><![CDATA[<cities>
732
  <city name="Berlin" country="DE"/>
733
  <city name="Munich" country="DE"/>
734
  <city name="Paris" country="FR"/>
735
  <city name="Lyon" country="FR"/>
736
  <city name="Rome" country="ITALIA"/>
737
</cities>]]></samp>
738
    
739
    <p>Given a source document:</p>
740
    <samp><![CDATA[<cities>
741
  <city><name>Berlin</name><country>DE</country></city>
742
  <city><name>Munich</name><country>DE</country></city>
743
  <city><name>Paris</name><country>FR</country></city>
744
  <city><name>Lyon</name><country>FR</country></city>
745
  <city><name>Rome</name><country>IT</country></city>
746
</cities>]]></samp>
747
    
748
    <p>The command:</p>
749
    <kbd>update //city/name[.="Munich"] with "München"</kbd>
750
    <p>produces the document:</p>
751
    
752
    <samp><![CDATA[<cities>
753
  <city><name>Berlin</name><country>DE</country></city>
754
  <city><name>München</name><country>DE</country></city>
755
  <city><name>Paris</name><country>FR</country></city>
756
  <city><name>Lyon</name><country>FR</country></city>
757
  <city><name>Rome</name><country>IT</country></city>
758
</cities>]]></samp>
759
    
760
    <p>With the same source document, the command:</p>
761
    
762
    <kbd>update //@country with lower-case(.)</kbd>
763
    
764
    <p>produces:</p>
765
    
766
    <samp><![CDATA[<cities>
767
  <city><name>Berlin</name><country>de</country></city>
768
  <city><name>Munich</name><country>de</country></city>
769
  <city><name>Paris</name><country>fr</country></city>
770
  <city><name>Lyon</name><country>fr</country></city>
771
  <city><name>Rome</name><country>it</country></city>
772
</cities>]]></samp>
773
    
774
  </section>
775
  
776
  <section id="validate" title="The validate command">
777
    <h1>The validate command</h1>
778
    
779
    <p><i>Syntax:</i></p>
780
    <kbd>validate</kbd>
781
    
782
    <aside>Requires Saxon-EE</aside>
783
    
784
    <p>Validates the current document using the XSD schema(s) previously loaded using the
785
      <a class="bodylink" href="../schema">schema</a>
786
      command, supplemented with any schema found via an <code>xsi:schemaLocation</code> or 
787
      <code>xsi:noNamespaceSchemaLocation</code> attribute in the source document.</p>
788
    <p>On completion, the validated result (complete with type annotations) becomes the new current document.
789
    Any expressions and queries executed against a typed document are treated as schema-aware.</p>
790
    <p>If validation fails, the validation error messages are output, and the current document remains unchanged.</p>
791
    
792
  </section> 
793
  
794
 
795
</article>
(14-14/21)