-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
3905 lines (3736 loc) · 331 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-GB" xml:lang="en-GB">
<head>
<meta charset="utf-8"/>
<title>xmlstarlet usage notes</title>
<link rel="stylesheet" href="index.css"/>
</head>
<body>
<section id="sec-xmlstarlet-usage-notes">
<h1 id="xmlstarlet-usage-notes" class="shew-tgt"><code>xmlstarlet</code> usage notes<a href="#xmlstarlet-usage-notes" class="permalink shew-hover"></a><div class="toolbar shew-hover h1"/></h1>
<div id="doc-version" title="15 August 2023">
version 2023-08-15 | <a href="news.html" title="Release news">news</a>
</div>
<div id="toc-short" class="nav">
<p><em>Short table of contents</em></p>
<ul>
<li><a href="#introduction">Introduction</a> | <a href="#documentation">Documentation</a> | <a href="#general-notes">General notes</a><sup><strong>*</strong></sup> | <a href="#global-options">Global options</a></li>
<li><a href="#elements"><code>elements</code></a> | <a href="#select"><code>select</code></a><sup><strong>*</strong></sup> | <a href="#edit"><code>edit</code></a><sup><strong>*</strong></sup> | <a href="#format"><code>format</code></a> | <a href="#c14n"><code>c14n</code></a> | <a href="#validate"><code>validate</code></a> | <a href="#pyx"><code>pyx</code>, <code>depyx</code></a> | <a href="#escape"><code>escape</code>, <code>unescape</code></a> | <a href="#list"><code>list</code></a> | <a href="#transform"><code>transform</code></a></li>
<li><a href="#namespaces">Namespaces</a> | <a href="#error-messages">Error messages</a> | <a href="#exslt">EXSLT</a><sup><strong>*</strong></sup> | <a href="#code-generation">Code generation</a><sup><strong>*</strong></sup><br/>
</li>
<li><a href="#appendix-a-xmlstarlet-xslt-extensions">A: XSLT extensions</a> | <a href="#appendix-b-xmlstarlet-news-summary">B: news summary</a> | <a href="#appendix-c-xmlstarlet-wishlist-ad-2003">C: wishlist AD 2003</a></li>
<li><a href="#toc">Table of contents</a> <span class="in-toc-cloud">[ <a href="#in-toc-select">sel</a> <a href="#in-toc-edit">ed</a> <a href="#in-toc-format">fo</a> <a href="#in-toc-c14n">c14n</a> <a href="#in-toc-validate">val</a> <a href="#in-toc-pyx">pyx</a> <a href="#in-toc-transform">tr</a> <a href="#in-toc-namespaces">xmlns</a> <a href="#in-toc-exslt">exslt</a>]</span></li>
</ul>
</div>
<section id="sec-introduction">
<h2 id="introduction" class="shew-tgt">Introduction<a href="#introduction" class="permalink shew-hover"></a><div class="toolbar shew-hover h2"><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span><a class="relup shew-hover" href="#xmlstarlet-usage-notes"></a><a class="relnext shew-hover" href="#documentation"></a><a class="rellast shew-hover" href="#toc"></a></div></h2>
<p><code>xmlstarlet</code> (<a href="https://xmlstar.sourceforge.net/" title="xmlstarlet on SourceForge">xmlstar.sf.net</a>) is the no-nonsense XML multitool that lets you write simple queries or edits on the command line, avoids most of the stylesheet formal stuff, and gives your <code><o/><o/></code>-looking eyes a moment of relief. It’s also a cranky minimalist tool which targets the 1.0 versions of XPath / XSLT / EXSLT still widely used and, it seems, users with little need for documentation.</p>
<p>This is an edited version of my personal notes on <code>xmlstarlet</code> with worked examples – knowledge gained as an outsider through use, trial and error – focusing on the <code>select</code> and <code>edit</code> commands and EXSLT. It’s not a tutorial or a FAQ, it requires a grasp of XML tools and the POSIX shell. Copyright is retained.</p>
<h4 id="xmlstarlet-features" class="shew-tgt"><code>xmlstarlet</code> features<a href="#xmlstarlet-features" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#introduction"></a><span class="relnop shew-hover"></span></div></h4>
<ul>
<li><code>xmlstarlet</code> relies on <code>libxml2</code> and <code>libxslt</code> which are limited to XPath 1.0 and XSLT 1.0, plus a number of EXSLT and extension functions</li>
<li><code>xmlstarlet</code> is currently at version 1.6.1 which appeared in 2014 (that’s more or less a century ago in internet years); a number of <code>FIXME</code>s and <code>TODO</code>s remain in the source code</li>
<li><code>xmlstarlet select</code> supports XPath 1.0, a subset of XSLT 1.0 (but not <code>xsl:apply-templates</code>, <code>xsl:key</code> a.o.), and EXSLT</li>
<li><code>xmlstarlet edit</code> supports XPath 1.0 – plus some EXSLT but no XSLT – functions in its <code>xpath</code> arguments</li>
<li><code>xmlstarlet transform</code> is a regular XSLT 1.0 processor with extensions, like <code>xsltproc</code></li>
<li>additional <code>xmlstarlet</code> commands do document formatting, canonicalization, validation, structure display, conversion of PYX and special characters, and file directory listing</li>
<li>string handling is an XPath 1.0 weakness, not improved by the lack of EXSLT regular expressions</li>
<li>memory requirements: <q>There should be no limit on input XML (apart from available memory on your system)</q> – forum <a href="https://sourceforge.net/p/xmlstar/discussion/226076/thread/1c0bb811/">posting</a> by the original <code>xmlstarlet</code> developer</li>
<li>rights: <code>xmlstarlet</code> is <q>Copyright (c) 2002-2004 Mikhail Grushinskiy. All Rights Reserved.</q> (cf. <a href="https://sourceforge.net/p/xmlstar/code/ci/master/tree/COPYING" title="`xmlstarlet` on SourceForge">SourceForge</a> or <a href="https://fossies.org/linux/xmlstarlet/COPYING" title="Fossies - the Fresh Open Source Software Archive">Fossies</a>)</li>
</ul>
<h4 id="notation-used-in-this-document" class="shew-tgt">Notation used in this document<a href="#notation-used-in-this-document" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#introduction"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-q (--quiet)</code> means either short option <code>-q</code> or long option <code>--quiet</code> can be used.</p>
<p><code>«name»</code> in a command or message is a placeholder for the actual name used, e.g. <code>xmlXPathCompOpEval: function «name» not found</code>.</p>
<p>Links look like this: <a href="https://xmlstar.sourceforge.net/doc/UG/">external</a>, <a href="#notation-used-in-this-document">internal</a>, internal <a class="link-cloud-ref" href="#toc-short">link</a> appearing in a navigation link cloud, <a class="link-cloud-ref" href="#toc-edit">ditto</a><sup><strong>*</strong></sup> linking to a larger section with a local link cloud, <span class="in-toc-cloud">[ <a href="#in-toc-select">sel</a> ]</span> linking into the table of contents. On mouseover headers display a permalink icon, on level 2 and 3 also navigation link icons, on level 4 a section link icon.</p>
<p>Code looks like this: <code>test -s file.xml || log …</code>, occasionally with an <code>…</code> (ellipsis) inside for brevity. For readability longer commands are usually <a href="#one-lining">split</a> across lines and indented.</p>
<p>Admonitions look like this: <span class="caution"><strong>Caution</strong></span>.</p>
<p>All shell code samples were made for a POSIX shell (<code>dash</code> 0.5.10) with <code>xmlstarlet</code> 1.6.1 (linked with libxml2 20913, libxslt 10134, and libexslt 820) from the <a href="https://packages.debian.org/unstable/text/xmlstarlet">Debian</a> distribution.</p>
<h4 id="a-word-about-stylesheet-syntax" class="shew-tgt">A word about stylesheet syntax<a href="#a-word-about-stylesheet-syntax" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#introduction"></a><span class="relnop shew-hover"></span></div></h4>
<blockquote>
<p>[T]he use of SGML syntax for stylesheets was proposed as long ago as 1994, and it seems that this idea gradually became the accepted wisdom. It’s difficult to trace exactly what the overriding arguments were, and when you find yourself writing something like:</p>
<pre class="lang-xsl"><code> <xsl:variable name="y">
<xsl:call-template name="f">
<xsl:with-param name="x"/>
</xsl:call-template>
</xsl:variable></code></pre>
<p>to express what in other languages would be written as <code>y = f(x);</code>, then you may find yourself wondering how such a decision came to be made.</p>
</blockquote>
<p>– Michael Kay, <em>XSLT Programmer’s Reference</em>, Ch.1, ISBN 1861005067</p>
</section>
<section id="sec-documentation">
<h2 id="documentation" class="shew-tgt">Documentation<a href="#documentation" class="permalink shew-hover"></a><div class="toolbar shew-hover h2"><span class="relnop shew-hover"></span><a class="relprev shew-hover" href="#introduction"></a><a class="relup shew-hover" href="#xmlstarlet-usage-notes"></a><a class="relnext shew-hover" href="#xmlstarlet-commands"></a><a class="rellast shew-hover" href="#toc"></a></div></h2>
<h4 id="users-guide-examples-source-code-forums" class="shew-tgt">User’s guide, examples, source code, forums<a href="#users-guide-examples-source-code-forums" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#documentation"></a><span class="relnop shew-hover"></span></div></h4>
<ul>
<li><code>man xmlstarlet</code><br/>
<code>xmlstarlet --help</code><br/>
<code>xmlstarlet «command-name» --help</code></li>
<li><code>xmlstarlet</code> on SourceForge: <a href="https://xmlstar.sourceforge.net/">homepage</a> | <a href="https://xmlstar.sourceforge.net/docs.php">docs</a> | <a href="https://xmlstar.sourceforge.net/doc/UG/">user’s guide</a> | <a href="https://sourceforge.net/p/xmlstar/news/">news</a> | <a href="https://xmlstar.sourceforge.net/source.php">source</a> | <a href="https://sourceforge.net/projects/xmlstar/files/xmlstarlet/">files</a> | <a href="https://sourceforge.net/p/xmlstar/discussion/">discussion</a> | <a href="https://sourceforge.net/p/xmlstar/bugs/">bugs</a><br/>
<span class="caution"><strong>Caution</strong></span>: the <a href="https://xmlstar.sourceforge.net/doc/xmlstarlet.txt"><code>doc/xmlstarlet.txt</code></a> there is not the latest version as it doesn’t mention <a href="#edit-prev"><code>$prev</code></a>, <a href="#edit-opt-var"><code>--var</code></a>, <a href="#edit-opt-inplace"><code>-L (--inplace)</code></a>, and <a href="#transform-opt-embed"><code>-E (--embed)</code></a> – the user’s guide is still silent on these</li>
<li><code>xmlstarlet</code> on <a href="https://fossies.org/about.html" title="Fossies - Fresh Open Source Software mainly for Internet, Engineering and Science">Fossies</a> – an accessible presentation of source, examples, and more:<br/>
<a href="https://fossies.org/linux/www/xmlstarlet"><code>xmlstarlet-1.6.1.tar.gz</code></a> contents | <a href="https://fossies.org/linux/xmlstarlet/doc/xmlstarlet-ug.html"><code>xmlstarlet</code> user’s guide</a> (1-page) | <a href="https://fossies.org/linux/xmlstarlet/doc/xmlstarlet.txt"><code>doc/xmlstarlet.txt</code></a> (latest version)</li>
<li><code>xmlstarlet</code> forums on StackExchange: <a href="https://stackoverflow.com/questions/tagged/xmlstarlet">stackoverflow.com</a> | <a href="https://unix.stackexchange.com/questions/tagged/xmlstarlet">unix.stackexchange.com</a></li>
</ul>
<h4 id="selected-resources" class="shew-tgt">Selected resources<a href="#selected-resources" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#documentation"></a><span class="relnop shew-hover"></span></div></h4>
<ul>
<li>W3C: <a href="https://www.w3.org/TR/xpath/">XPath cover page</a> | <a href="https://www.w3.org/TR/xslt/">XSLT cover page</a></li>
<li><code>github.io</code>: <a href="https://exslt.github.io/">EXSLT docs</a></li>
<li><code>gnome.org</code>: <a href="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home" title="'libxml2 Wiki Home' on gitlab.gnome.org">libxml2 Wiki Home</a> (with links to standards, API, utilities a.o.) | <a href="https://gitlab.gnome.org/GNOME/libxml2" title="libxml2 'XML parser and toolkit' source code on gitlab.gnome.org">libxml2 source</a> | <a href="https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home" title="'libxslt Wiki Home' on gitlab.gnome.org">libxslt Wiki Home</a> (with links to XSLT + EXSLT API a.o.) | <a href="https://gitlab.gnome.org/GNOME/libxslt" title="libxslt 'XSLT processor' source code on gitlab.gnome.org">libxslt+libexslt source</a> | <a href="https://gitlab.gnome.org/GNOME/libxslt/-/wikis/Writing-extensions" title="Writing extensions">libxslt extensions</a><br/>
(<code>xmlsoft.org</code> now redirects to <code>gnome.org</code>)</li>
<li><code>packages.debian.org</code>: <a href="https://packages.debian.org/bullseye/xmlstarlet" title="command line XML toolkit">text/xmlstarlet</a> | <a href="https://packages.debian.org/bullseye/xsltproc" title="XSLT 1.0 command line processor">text/xsltproc</a> | <a href="https://packages.debian.org/bullseye/libxml2-utils" title="GNOME XML library - utilities">text/libxml2-utils</a> (<code>xmllint</code>) | <a href="https://packages.debian.org/bullseye/html-xml-utils" title="HTML and XML manipulation utilities">text/html-xml-utils</a> | <a href="https://packages.debian.org/bullseye/xml2" title="Convert between XML, HTML, CSV and a line-oriented format">utils/xml2</a> | <a href="https://packages.debian.org/bullseye/tidy" title="HTML/XML syntax checker and reformatter">web/tidy</a></li>
<li><code>stackoverflow.com</code> forums: <a href="https://stackoverflow.com/tags/xpath">XPath</a> | <a href="https://stackoverflow.com/tags/xslt-1.0">XSLT 1.0</a> | <a href="https://stackoverflow.com/tags/exslt">EXSLT</a> | <a href="https://stackoverflow.com/tags/xml">XML</a></li>
</ul>
<h4 id="list-the-generated-xslt-xmlstarlet-select--c" class="shew-tgt">List the generated XSLT: <code>xmlstarlet select -C</code><a href="#list-the-generated-xslt-xmlstarlet-select--c" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#documentation"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>select</code>’s <a href="#select-opt-comp"><code>-C (--comp)</code></a> option lists the stylesheet the current command line will generate – it requires no input file – e.g. </p>
<pre class="lang-sh"><code>xmlstarlet select -T -C -t -m 'str:tokenize("Hello, world",",o")' -v '.' -n</code></pre>
<p>Output:</p>
<pre class="lang-xsl"><code><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" version="1.0" extension-element-prefixes="exslt str">
<xsl:output omit-xml-declaration="yes" indent="no" method="text"/>
<xsl:template match="/">
<xsl:for-each select="str:tokenize(&quot;Hello, world&quot;,&quot;,o&quot;)">
<xsl:call-template name="value-of-template">
<xsl:with-param name="select" select="."/>
</xsl:call-template>
<xsl:value-of select="'&#10;'"/>
</xsl:for-each>
</xsl:template>
<xsl:template name="value-of-template">
<xsl:param name="select"/>
<xsl:value-of select="$select"/>
<xsl:for-each select="exslt:node-set($select)[position()&gt;1]">
<xsl:value-of select="'&#10;'"/>
<xsl:value-of select="."/>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet></code></pre>
</section>
<section id="sec-commands">
<h2 id="xmlstarlet-commands" class="shew-tgt"><code>xmlstarlet</code> commands<a href="#xmlstarlet-commands" class="permalink shew-hover"></a><div class="toolbar shew-hover h2"><a class="relfirst shew-hover" href="#introduction"></a><a class="relprev shew-hover" href="#documentation"></a><a class="relup shew-hover" href="#xmlstarlet-usage-notes"></a><a class="relnext shew-hover" href="#elements"></a><a class="rellast shew-hover" href="#toc"></a></div></h2>
<h3 id="general-notes" class="shew-tgt">General notes<a href="#general-notes" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span><a class="relup shew-hover" href="#xmlstarlet-commands"></a><a class="relnext shew-hover" href="#global-options"></a><span class="relnop shew-hover"></span></div></h3>
<p><span class="caution"><strong>Caution</strong></span>: <q>Other features need some work too</q> warns the <a href="https://xmlstar.sourceforge.net/doc/UG/ch01.html">user’s guide</a>.</p>
<p>Perhaps they’re thinking of these:</p>
<ul>
<li><code>edit</code>’s <a href="#no-kidding-issue">“no kidding” issue</a></li>
<li><a href="#xml-external-entities">external entity</a> issues</li>
<li><code>select</code>’s <a href="#select-exslt-namespace-issue">EXSLT namespace issue</a></li>
<li><code>pyx</code> and <code>depyx</code>’ <a href="#pyx">several issues</a></li>
<li>invalid command-line options are not flagged for <a href="#select"><code>select</code></a>, <a href="#c14n"><code>c14n</code></a>, and <a href="#transform"><code>transform</code></a> while <a href="#edit"><code>edit</code></a> returns non-zero printing nothing but its lengthy usage reminder</li>
<li>the user’s guide</li>
</ul>
<div class="dinkus1">
</div>
<div id="toc-general-notes" class="nav">
<ul>
<li><a href="#special-characters">Special characters</a> | <a href="#xml-declaration">XML declaration</a> | <a href="#xml-parsing-and-serialization">XML parsing and serialization</a> | <a href="#xml-external-entities">XML external entities</a><br/>
| <a href="#exit-values">Exit values</a> | <a href="#numeric-representation">Numeric representation</a> | <a href="#one-lining">One-lining</a> | <a href="#makefile-notes-gnu-make">makefile notes</a></li>
</ul>
</div>
<h4 id="special-characters" class="shew-tgt">Special characters<a href="#special-characters" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>The special XML characters are <code>&<>'"</code> or – as references to <em>predefined general entities</em> – <code>&amp;</code> <code>&lt;</code> <code>&gt;</code> <code>&apos;</code> <code>&quot;</code>. With few exceptions<sup>[1]</sup> they are never entered as entity references in an <code>xmlstarlet</code> command, and they are output as literals when <code>xmlstarlet select</code>’s <a href="#select-opt-text"><code>-T (--text)</code></a> option is in effect.</p>
<p>For example, in XPath predicates <code>xmlstarlet</code> wants <code><</code> (less-than) on the command line, as in <code>factor[. < 2.19]</code>, whereas XSLT stylesheets require <code>&lt;</code> inside attribute values, or <code>></code> (greater-than) with operands swopped. Likewise, a numeric character reference such as <code>&#9;</code> for a tab character belongs in an XML file, not on the <code>xmlstarlet</code> command line.</p>
<div class="enhanced">
<p><sup>[1]</sup> <em>Exceptions</em></p>
<p>The predefined entity ref:s – as well as character ref:s below <code>&#x100;</code> – are recognized in the following which therefore require <code>&amp;</code> to represent an <code>&</code> (ampersand) character:</p>
<ul>
<li>the <code>-v (--value)</code> clause of <code>xmlstarlet edit</code>’s <a href="#edit-opt-insert"><code>-i (--insert)</code></a>, <a href="#edit-opt-append"><code>-a (--append)</code></a>, and <a href="#edit-opt-subnode"><code>-s (--subnode)</code></a> options <em>when used with</em> <code>-t (--type) elem</code></li>
<li>the input to the <a href="#escape"><code>xmlstarlet unescape</code></a> conversion utility</li>
</ul>
</div>
<p><span class="caution"><strong>Caution</strong></span>: The example in the user’s guide section <a href="https://xmlstar.sourceforge.net/doc/UG/ch04.html#idm47989546279904">4.1</a> meant to convert newlines to blanks using a character reference for the newline – <code>xml sel … -v "translate(. , '&#10;', ' ')" …</code> – in fact converts <code>&</code> (ampersand) characters to blanks, and strips <code>#</code>, <code>1</code>, <code>0</code>, and <code>;</code> characters. The <code>translate(…)</code> expression would work as intended in an XSLT stylesheet but <em>means something rather different</em> on the <code>xmlstarlet select</code> command line.</p>
<p><em>See also</em>: <a href="#escape"><code>xmlstarlet esc</code> / <code>xmlstarlet unesc</code></a> | <a href="#replace-text">Replace text</a> sample</p>
<div class="dinkus2">
</div>
<p><code>xmlstarlet edit</code> handling special characters:</p>
<pre class="lang-sh"><code>printf '%s' '<e/>'|
xmlstarlet edit -O \
-s '*' -t elem -n esuv -v '' -u '$prev' -v '&Save as <.oona>' \
-a '$prev' -t elem -n eaux -v '' -u '$prev' -x '"&Save as <.oona>"' \
-s '*' -t elem -n esv1 -v '&amp;Save as <.oona>' \
-a '$prev' -t elem -n eav1 -v '&amp;Save&#x20;&#x61;&#x73;&#x20;&lt;.oona&gt;' \
-i '$prev' -t elem -n eiv1 -v "$(xmlstarlet escape '&Save as <.oona>')"</code></pre>
<ul>
<li><a href="#edit-opt-update-value"><code>-u (--update)</code></a> follows <code>xmlstarlet</code>’s general rule for a literal (<code>esuv</code>) or an XPath expression (<code>eaux</code>): special characters are encoded behind the scenes</li>
<li><a href="#edit-opt-insert"><code>-i (--insert)</code></a>, <a href="#edit-opt-append"><code>-a (--append)</code></a>, and <a href="#edit-opt-subnode"><code>-s (--subnode)</code></a> used with <code>-t (--type) elem</code> are special: certain entity/character ref:s are recognized so <code>&amp;</code> is required for <code>&</code> (<code>esv1</code>, <code>eav1</code>, <code>eiv1</code>) whereas <code><>'"</code> may be used to represent themselves</li>
<li><code>-i</code>, <code>-a</code>, <code>-s</code>, and <a href="#edit-opt-rename"><code>-r (--rename)</code></a> accept their name argument without modification</li>
</ul>
<p>Output:</p>
<pre class="lang-none"><code><e>
<esuv>&amp;Save as &lt;.oona&gt;</esuv>
<eaux>&amp;Save as &lt;.oona&gt;</eaux>
<esv1>&amp;Save as &lt;.oona&gt;</esv1>
<eiv1>&amp;Save as &lt;.oona&gt;</eiv1>
<eav1>&amp;Save as &lt;.oona&gt;</eav1>
</e></code></pre>
<div class="dinkus2">
</div>
<p>Using variables with <code>xmlstarlet select</code>, e.g. </p>
<ul>
<li><code>--var newline -n -b</code></li>
<li><code>--var tab -o "$(printf '\t')" -b</code></li>
<li><code>--var sq -o "'" -b</code> … <code>-v 'concat($sq,"//_:",local-name(),$sq)'</code></li>
<li><code>--var eurosign='"€"'</code></li>
<li><code>--var eurosign -o "$(python3 -c 'print("{0:c}".format(0x20ac))')" -b</code></li>
</ul>
<p>Using variables with <code>xmlstarlet edit</code>, e.g.</p>
<ul>
<li><code>--var sq '"'\''"'</code></li>
<li><code>--var dq "'\"'"</code></li>
<li>outer double quotes to delimit tab and enable <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06" title="Shell command language at Open Group (POSIX)"><em>shell word expansions</em></a>, single quotes to delimit the <code>printf</code> argument, and inner double quotes to make an XPath string expression<br/>
<code>--var tab "$(printf '"\t"')"</code></li>
<li>a literal tab works too but is easily lost in translation<br/>
<code>--var tab '" "'</code></li>
<li>newline<br/>
<code>--var nl 'substring-before('"$(printf '"\nA"')"',"A")'</code></li>
</ul>
<p><em>See also</em>: <a href="#select-opt-var-equals"><code>select</code> <code>--var</code></a> | <a href="#edit-opt-var"><code>edit</code> <code>--var</code></a></p>
<h4 id="xml-declaration" class="shew-tgt">XML declaration<a href="#xml-declaration" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>The various <code>xmlstarlet</code> commands each handle the XML declaration in their own way but all print it with a trailing newline if requested:</p>
<ul>
<li><code>xmlstarlet edit … -O (--omit-decl) …</code></li>
<li><code>xmlstarlet format … -o (--omit-decl) …</code></li>
<li><code>xmlstarlet list</code> never outputs an XML declaration</li>
<li><code>xmlstarlet pyx</code> always strips the XML declaration if present</li>
<li><code>xmlstarlet select … -D (--xml-decl) …</code> outputs an XML declaration</li>
<li><code>xmlstarlet transform … --omit-decl …</code></li>
</ul>
<p>Adding an XML declaration using <code>select</code>:</p>
<pre class="lang-shell"><code>$ printf '<v w="x"/>' |
xmlstarlet select -D -E 'ISO-8859-2' -t -c '/'
<?xml version="1.0" encoding="ISO-8859-2"?>
<v w="x"/></code></pre>
<h4 id="xml-parsing-and-serialization" class="shew-tgt">XML parsing and serialization<a href="#xml-parsing-and-serialization" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>Several <code>xmlstarlet</code> commands allow selected options to be passed to the <a href="#selected-resources"><code>libxml2</code></a> XML parser (cf. <a href="https://gnome.pages.gitlab.gnome.org/libxml2/devhelp/libxml2-parser.html">API reference</a> and <a href="https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/parser.c">source code</a>) or the <a href="#selected-resources"><code>libxml2</code></a> XML serializer (cf. <a href="https://gnome.pages.gitlab.gnome.org/libxml2/devhelp/libxml2-xmlsave.html">API reference</a> and <a href="https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/xmlsave.c">source code</a>).</p>
<ul>
<li><a href="#select"><code>select</code></a>
<ul>
<li><a href="#select-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
<li><a href="#select-opt-noblanks"><code>-B (--noblanks)</code></a>: sets <code>XML_PARSE_NOBLANKS</code></li>
<li><a href="#select-opt-xml-decl"><code>-D (--xml-decl)</code></a>: clears <code>XML_SAVE_NO_DECL</code>; sets <code>omit-xml-declaration="no"</code> on <code>xsl:output</code></li>
<li><a href="#select-opt-indent"><code>-I (--indent)</code></a>: sets <code>XML_SAVE_FORMAT</code>; sets <code>indent="yes"</code> on <code>xsl:output</code></li>
<li><a href="#select-opt-text"><code>-T (--text)</code></a>: sets <code>method="text"</code> on <code>xsl:output</code></li>
</ul></li>
<li><a href="#edit"><code>edit</code></a>
<ul>
<li><a href="#edit-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
<li><a href="#edit-opt-omit-decl"><code>-O (--omit-decl)</code></a>: sets <code>XML_SAVE_NO_DECL</code></li>
<li><a href="#edit-opt-pf"><code>-P (--pf)</code></a>: sets <code>XML_SAVE_FORMAT</code></li>
<li><a href="#edit-opt-ps"><code>-S (--ps)</code></a>: sets <code>XML_SAVE_WSNONSIG</code> (requires <code>libxml2</code> 2.7.8+)</li>
</ul></li>
<li><a href="#format"><code>format</code></a>
<ul>
<li><a href="#format-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
<li><a href="#format-opt-nocdata"><code>-C (--nocdata)</code></a>: sets <code>XML_PARSE_NOCDATA</code></li>
<li><a href="#format-opt-nsclean"><code>-N (--nsclean)</code></a>: sets <code>XML_PARSE_NSCLEAN</code></li>
<li><a href="#format-opt-recover"><code>-R (--recover)</code></a>: sets <code>XML_PARSE_RECOVER</code></li>
<li><a href="#format-opt-omit-decl"><code>-o (--omit-decl)</code></a>: sets <code>XML_SAVE_NO_DECL</code></li>
<li><a href="#format-opt-noindent"><code>-n (--noindent)</code></a>, <a href="#format-opt-indent-spaces"><code>-s (--indent-spaces)</code></a>, and <a href="#format-opt-indent-tab"><code>-t (--indent-tab)</code></a> offer an alternative to the default indentation</li>
</ul></li>
<li><a href="#c14n"><code>c14n</code></a>
<ul>
<li><a href="#c14n-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
</ul></li>
<li><a href="#validate"><code>validate</code></a>
<ul>
<li><a href="#validate-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
<li><a href="#validate-opt-embed"><code>-E (--embed)</code></a>: sets <code>XML_PARSE_DTDVALID</code></li>
<li><code>XML_PARSE_DTDLOAD</code> and <code>XML_PARSE_DTDATTR</code> are set by default (<a href="https://fossies.org/linux/xmlstarlet/src/xml_validate.c#l_292">src/validate.c#valMain()</a>)</li>
</ul></li>
<li><a href="#transform"><code>transform</code></a>
<ul>
<li><a href="#transform-opt-net"><code>--net</code></a>: clears <code>XML_PARSE_NONET</code></li>
<li><a href="#transform-opt-omit-decl"><code>--omit-decl</code></a>: sets <code>XML_SAVE_NO_DECL</code></li>
</ul></li>
</ul>
<p><code>format</code>’s <a href="#format-opt-html"><code>-H (--html)</code></a> and <code>transform</code>’s <a href="#transform-opt-html"><code>--html</code></a> options substitute the <a href="#selected-resources"><code>libxml2</code></a> HTML 4.0 parser.</p>
<p>The <a href="#c14n"><code>c14n</code></a> command converts an XML document to a normal format.</p>
<p>To expand empty-element tags, changing <code><p/></code> to <code><p></p></code>, for example:</p>
<pre class="lang-sh"><code>xmlstarlet edit --pf -s '//*[not(node())]' -t text -n ignored -v '' file.xml</code></pre>
<p><em>See also</em>: <a href="#global-opt-net">network access</a> | <a href="#try-out-xmlstarlet-edits-formatting-options">Try out <code>edit</code>’s formatting options</a> example</p>
<div class="dinkus2">
</div>
<p>The <code>xmlEscapeEntities</code> function in <a href="#selected-resources"><code>libxml2</code></a>’s <a href="https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/xmlsave.c#L165"><code>xmlsave.c</code></a> serialization module gives special treatment to characters <code>&<></code> (output as <code>&amp;</code>, <code>&lt;</code>, and <code>&gt;</code>) but neither apostrophe nor double quote (<code>'"</code>). <code>xmlstarlet</code> has no option to override this.</p>
<div class="dinkus2">
</div>
<p>Using a CDATA section to keep the serializer from applying default rules:</p>
<pre class="lang-shell"><code>$ printf '%s\n' '<v><w>x</w><x>🧩</x></v>' |
xmlstarlet edit -O -P -d '*/w'
<v><x>&#x1F9E9;</x></v>
$ :
$ printf '%s\n' '<v><w>x</w><x><![CDATA[🧩]]></x></v>' |
xmlstarlet edit -O -P -d '*/w'
<v><x><![CDATA[🧩]]></x></v></code></pre>
<h4 id="xml-external-entities" class="shew-tgt">XML external entities<a href="#xml-external-entities" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p><span class="caution"><strong>Caution</strong></span>: Of <code>xmlstarlet</code>’s commands only <a href="#c14n"><code>c14n</code></a>, <a href="#select"><code>select</code></a>, and <a href="#transform"><code>transform</code></a> seem to understand an entity reference like <code><doc>&e;</doc></code>, according to the following test script. This makes pre/post-processing a requirement if using <code>xmlstarlet</code>’s other commands to handle external entities.</p>
<pre class="lang-sh"><code>#!/bin/sh
# Test xmlstarlet commands with external general parsed entity.
# - ${xdata} holds data file contents, defaults to a few <e>N</e>
# - ${keepf} non-empty to keep temporary files in $TMPDIR
# - ${dryrun} non-empty to print but not execute commands
# - ${doecho} non-empty to also print commands before executing
skelf=$(mktemp -t "xsskel-$$-XXXXXXXXXX.xml")
dataf=$(mktemp -t "xsdata-$$-XXXXXXXXXX.xml")
idxff=$(mktemp -t "xsidxf-$$-XXXXXXXXXX.xsl")
test "${keepf}" ||
trap "rm '${skelf}' '${dataf}' '${idxff}'" INT EXIT
printf '%s\n' \
'<!DOCTYPE skel [<!ENTITY e SYSTEM "'"${dataf}"'">]><doc>&e;</doc>' \
> "${skelf}"
printf '%s' \
"${xdata:-<e>1</e><e>2</e><e>3</e><e>4</e>}" \
> "${dataf}"
printf '<v/>' | xmlstarlet select -t \
-e xsl:transform -a version -o 1.0 -b \
-e xsl:template -a match -o '@*|node()' -b \
-e xsl:copy -e xsl:apply-templates -a select -o '@*|node()' \
> "${idxff}" ## identity transform
for cmd in c14n ed el fo pyx sel tr val
do
case ${cmd} in
(c14n|el|fo|pyx|val)
set -- ;;
(ed) set -- -d '*/*[3]' ;;
(sel) set -- -T -t -c / -n ;;
(tr) set -- "${idxff}" ;;
(*) break ;;
esac
set -- xmlstarlet "${cmd}" "$@" "${skelf}"
if test "${dryrun}${doecho}"; then
printf '\n\n# command:'; printf " '%s'" "$@"; printf '\n'
fi
if ! test "${dryrun}"; then
"$@"; printf '\n## %s returned %d\n\n' "${cmd}" "$?"
fi
done</code></pre>
<p>Given a data file containing <code><e>1</e><e>2</e><e>3</e><e>4</e></code> (making it well-formed XML) <code>pyx</code> returns 4 (outputs the doctype but says <code>Entity 'e' not defined</code>) while <code>c14n</code>, <code>ed</code>, <code>el</code>, <code>fo</code>, <code>sel</code>, <code>tr</code>, and <code>val</code> all return zero. But <code>ed</code>, <code>el</code>, and <code>fo</code> (plus <code>val</code>, presumably) fail to expand the entity reference.</p>
<p>Given a data file containing <code><a>B</c></code> (clearly making it non-XML) the <code>ed</code>, <code>el</code>, and <code>val</code> commands all return zero – and <code>val</code> even pronouncing <code>«datafile» - valid</code> – while <code>c14n</code>, <code>fo</code>, <code>pyx</code>, <code>sel</code>, and <code>tr</code> <a href="#exit-values">return</a> 3, 2, 4, 3, and 6, respectively.</p>
<p><code>xmllint</code> from the <a href="#selected-resources"><code>libxml2-utils</code></a> package has a <code>--noent</code> option to substitute entity values for entity references (e.g. <code>xmllint --noent --dropdtd file.xml</code>).</p>
<h4 id="exit-values" class="shew-tgt">Exit values<a href="#exit-values" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p><a href="https://fossies.org/linux/xmlstarlet/src/xmlstar.h#l_19">src/xmlstar.h</a> defines the following exit values for <code>xmlstarlet</code>:</p>
<ul>
<li>0 <code>EXIT_SUCCESS</code></li>
<li>1 <code>EXIT_FAILURE</code></li>
<li>2 <code>EXIT_BAD_ARGS</code></li>
<li>3 <code>EXIT_BAD_FILE</code></li>
<li>4 <code>EXIT_LIB_ERROR</code></li>
<li>5 <code>EXIT_INTERNAL_ERROR</code></li>
</ul>
<p>but mind these:</p>
<ul>
<li><code>xmlstarlet select</code> <a href="#select">exits</a> <code>grep</code>-style returning the query result as 0 or 1</li>
<li><code>xmlstarlet format</code>’s <a href="#format-opt-omit-decl"><code>--omit-decl</code></a> option exits, er, <code>shuf</code>-style</li>
<li>handling <a href="#xml-external-entities">external entities</a></li>
<li>exit value zero doesn’t mean there were no errors (e.g. <a href="#use-the-document-function"><code>document()</code></a> failure, <a href="#escape">unescape</a> – both producing <code>stderr</code> output)</li>
</ul>
<h4 id="numeric-representation" class="shew-tgt">Numeric representation<a href="#numeric-representation" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>XPath 1.0 does not support numbers expressed in <a href="https://en.wikipedia.org/wiki/Scientific_notation" title="Article on Wikipedia">scientific notation</a>, cf. <a href="https://www.w3.org/TR/1999/REC-xpath-19991116#NT-Number" title="NT-Number - W3C XPath 1.0 recommendation">W3C recommendation</a> (<code>Number ::= Digits ('.' Digits?)? | '.' Digits</code> and <code>Digits ::= [0-9]+</code>).</p>
<p>Tools based on <a href="#selected-resources"><code>libxml2</code></a> do support it, however, cf. <a href="https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/xpath.c#L3158" title="xpath.c on gitlab.gnome.org"><code>xmlXPathFormatNumber()</code></a> (<code>snprintf(work, sizeof(work),"%*.*e", integer_place, fraction_place, number);</code>).</p>
<p>Here are a few examples of <code>libxml2</code> handling XPath computations – and <code>libxslt</code> handling the XSLT <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#function-format-number" title="W3C XSLT 1.0 recommendation"><code>format-number()</code></a> function.</p>
<pre class="lang-xml"><code>printf '%s\n' '<v>1240057409536</v>' |
xmlstarlet select -T -t \
-v '*' -n \
-v '0 + *' -n \
-v '* div 1' -n \
-v '* div 1000 * 1E3' -n \
-v '* div 1.240057409536e+12' -n \
-o '---' -n \
-v 'round(* div 1)' -n \
-v 'round(* div 10)' -n \
-v 'round(* div 100)' -n \
-v 'round(* div 1000)' -n \
-o '---' -n \
-v 'format-number(* div 1,"#")' -n \
-v 'format-number(* div 1,"#,###")' -n</code></pre>
<p>Output:</p>
<pre class="lang-xml"><code>1240057409536
1.240057409536e+12
1.240057409536e+12
1.240057409536e+12
1
---
1.240057409536e+12
1.24005740954e+11
1.2400574095e+10
1240057410
---
1240057409536
1,240,057,409,536</code></pre>
<h4 id="one-lining" class="shew-tgt">One-lining<a href="#one-lining" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>In this document longer commands are usually split across lines and indented, like this:</p>
<pre class="lang-sh"><code>xmlstarlet select -T -t \
--var sq -o "'" -b \
-o 'xmlstarlet edit --omit-decl '\\ -n \
-o " --var N 'Names/Name' \\" -n \
-m '*/*' \
-o ' -r ' -v 'concat($sq,"$N[",position(),"]",$sq)' \
-o ' -v ' -v 'concat($sq,name(),format-number(position(),"0000"),$sq)' -o ' '\\ -n \
-b \
-f -n \
"${infile:-file.xml}"</code></pre>
<p>To strip such a command of line continuation characters and leading whitespace pipe it through following <code>sed</code> command (changing one line, not an entire shell script),</p>
<pre class="lang-sh"><code>sed -e ':1' -e 's/^[[:blank:]]*//' -e '/\\$/!b' -e '$b' -e 'N' -e 's/\\\n[[:blank:]]*//' -e 'b1'</code></pre>
<p>or, as an alias, silently using <a href="https://packages.debian.org/sid/xsel" title="XSel - command-line tool to access X clipboard and selection buffers"><code>xsel</code></a> to paste from the clipboard, call <code>sed</code>, have <code>paste</code> add a trailing newline if needed, and return the result to the clipboard:</p>
<pre class="lang-sh"><code>alias mfyoi="xsel -b -o |
sed -e 's/^[[:blank:]]*//' -e ':1' -e '/\\\\\$/!b' \
-e '\$b' -e 'N' -e 's/\\\\\\n[[:blank:]]*//' -e 'b1' |
paste -s -d '\\n' |
xsel -b -i"</code></pre>
<p>Thus minified:</p>
<pre class="lang-sh"><code>xmlstarlet select -T -t --var sq -o "'" -b -o 'xmlstarlet edit --omit-decl '\\ -n -o " --var N 'Names/Name' \\" -n -m '*/*' -o ' -r ' -v 'concat($sq,"$N[",position(),"]",$sq)' -o ' -v ' -v 'concat($sq,name(),format-number(position(),"0000"),$sq)' -o ' '\\ -n -b -f -n "${infile:-file.xml}"</code></pre>
<h4 id="makefile-notes-gnu-make" class="shew-tgt"><code>makefile</code> notes (GNU Make)<a href="#makefile-notes-gnu-make" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<ul>
<li>special characters
<ul>
<li><code>$</code> (dollar sign) starts expansion of a variable / parameter
<ul>
<li>in <code>make</code>, e.g. <code>$< $T $(mvar) ${mvar}</code>, use <code>$$</code> for a literal</li>
<li>in the shell, e.g. <code>$# $$ $svar ${svar}</code></li>
<li>in XSLT, e.g. <code>$xvar</code></li>
</ul></li>
<li><code>\</code> (backslash) is <code>make</code>’s (and the shell’s) escape character, it has no special meaning in XPath or XSLT</li>
<li>an unescaped newline ends a makefile statement or a recipe line</li>
</ul></li>
<li>all <code>make</code> functions and variables are expanded before the shell is invoked to execute a recipe</li>
<li><code>xmlstarlet</code>’s <a href="#exit-values">exit values</a> aren’t all orthodox</li>
</ul>
<p><em>Links</em>: <a href="https://www.gnu.org/software/make/manual/">GNU Make manual</a> | <a href="https://www.cmcrossroads.com/article/gnu-make-escaping-walk-wild-side" title="'GNU Make Escaping: A Walk on the Wild Side' on cmcrossroads.com">Ask Mr. Make article</a> on GNU Make escaping</p>
<div class="dinkus2">
</div>
<p>Sample <code>makefile</code>:</p>
<pre class="lang-makefile"><code>SHELL := /bin/sh
space := $(info) $(info)
tab := $(shell printf '\t')
define newline =
endef
# next line defines U+0023 NUMBER SIGN (aka \043, pound sign, hashtag, …)
\H := \#
.RECIPEPREFIX = >
.PHONY: all
all:
> printf '%s' '<v a="fee" b="fi" c="fo" d="fum"/>' | \
xmlstarlet select -T -t --var x='*/@*' -v '$$x' -n | \
paste -s -d '$$ ' -
> printf '%s\n' '$(space)x$(tab)\$(newline)'"$${OLDPWD$(\H)$(\H)*/}" \
"process $$$$ exiting"</code></pre>
<p>Output from <code>make -s</code>:</p>
<pre class="lang-none"><code>fee$fi fo$fum
x \
incubator
process 20965 exiting</code></pre>
<h3 id="global-options" class="shew-tgt">Global options and parameters<a href="#global-options" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><a class="relprev shew-hover" href="#general-notes"></a><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span></div></h3>
<p>Global options go before the command, as in <code>xmlstarlet -q format file</code>.</p>
<p>An input filename starting with <code>-</code> (dash) – unless it’s short for <code>stdin</code> – must be prefixed with <code>./</code> (dot slash) otherwise it will be parsed as an option, possibly causing <a href="#select"><code>select</code></a> (<span class="caution"><strong>Caution</strong></span>) to ignore the file.</p>
<p>Beware of known bugs for filenames containing (<a href="https://sourceforge.net/p/xmlstar/bugs/123/" title="Invalid expression: '/tmp/foo's.nfo'">#123</a> ) <code>'</code> (single quote), or (<a href="https://sourceforge.net/p/xmlstar/bugs/110/" title="ed --inplace 'foo%20bar.xml' writes to 'foo bar.xml'">#110</a>) urlencoded characters, e.g. <code>%20</code>.</p>
<p><em>See also</em>: <a href="#couldnt-read-file">couldn’t read file</a> | <a href="#failed-to-load-external-entity">failed to load external entity</a></p>
<h4 id="global-opt-help" class="shew-tgt"><code>--help</code><a href="#global-opt-help" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>xmlstarlet --help</code> shows the general usage reminder, <code>xmlstarlet «command» -h (--help)</code> the command-specific ditto.</p>
<h4 id="global-opt-version" class="shew-tgt"><code>--version</code><a href="#global-opt-version" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>Prints version information and terminates.</p>
<p>Sample output from <code>xmlstarlet --version</code>:</p>
<pre class="lang-none"><code>1.6.1
compiled against libxml2 2.9.4, linked with 20910
compiled against libxslt 1.1.33, linked with 10134</code></pre>
<h4 id="global-opt-quiet" class="shew-tgt"><code>-q (--quiet)</code>: suppress error output<a href="#global-opt-quiet" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>Error messages from <a href="#selected-resources"><code>libxml2</code></a> or <a href="#selected-resources"><code>libxslt</code></a> are suppressed by this option.</p>
<p><span class="caution"><strong>Caution</strong></span>: this option also suppresses ordinary output (to <code>stdout</code>) from <code>xmlstarlet select</code>.</p>
<p><em>See also</em>: <a href="#select-opt-quiet">select <code>-Q (--quiet)</code></a> local option | <a href="#format-opt-quiet">format <code>-Q (--quiet)</code></a> local option</p>
<h4 id="global-opt-no-doc-namespace" class="shew-tgt"><code>--no-doc-namespace</code>: don’t use namespace bindings from input’s root element<a href="#global-opt-no-doc-namespace" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="global-opt-doc-namespace" class="shew-tgt"><code>--doc-namespace</code>: extract namespace bindings from input’s root element (<em>default</em>)<a href="#global-opt-doc-namespace" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>By default (<code>--doc-namespace</code> being in effect) namespaces declared in input’s <strong>root element</strong> (aka document element) can be referred to without explicit <code>-N</code> options; if the default namespace is declared there it is bound to the <code>_</code> (underscore) (aka <code>DEFAULT</code>) prefix.</p>
<p>Although <code>--no-doc-namespace</code> and <code>--doc-namespace</code> are global options only <code>xmlstarlet select</code> and <code>xmlstarlet edit</code> use them.</p>
<p><em>See also</em>: User’s guide <a href="https://xmlstar.sourceforge.net/doc/UG/ch05.html#idm47989546158480">ch. 5</a> | <a href="#namespaces-use">Use a namespace</a> | <a href="#select-opt-n"><code>select -N</code></a> | <a href="#edit-opt-n"><code>edit -N</code></a></p>
<h4 id="global-opt-net" class="shew-tgt">Network access (<code>--net</code>)<a href="#global-opt-net" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p>Several <code>xmlstarlet</code> commands - <code>select</code>, <code>edit</code>, <code>format</code>, <code>c14n</code>, <code>validate</code>, and <code>transform</code> - have a <code>--net</code> option to allow network access, to fetch remote DTDs and entities. <code>--net</code> clears the <code>XML_PARSE_NONET</code> flag for the <code>libxml2</code> XML parser (<a href="https://gnome.pages.gitlab.gnome.org/libxml2/devhelp/libxml2-parser.html">API ref</a>).</p>
<p>For security, network access is disallowed by default, cf. article on <a href="https://en.wikipedia.org/wiki/XML_external_entity_attack" title="'XML external entity attack' on Wikipedia">XML external entity attack</a>.</p>
<h4 id="global-param-uri" class="shew-tgt"><code>uri</code> replacing input file<a href="#global-param-uri" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#xmlstarlet-commands"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>xmlstarlet --help</code> says,</p>
<blockquote>
Wherever file name mentioned in command help it is assumed that URL can be used instead as well.
</blockquote>
<p>Should work with HTTP and FTP protocols, not HTTPS (due to <a href="#selected-resources">libxml2</a> limitations). (Distribution-dependent?)</p>
<p><em>See also</em>: <a href="#global-opt-net"><code>--net</code></a></p>
<div class="dinkus1">
</div>
</section>
<section id="sec-elements">
<h2 id="elements" class="shew-tgt">Display structure: <code>xmlstarlet elements</code><a href="#elements" class="permalink shew-hover"></a><div class="toolbar shew-hover h2"><a class="relfirst shew-hover" href="#introduction"></a><a class="relprev shew-hover" href="#xmlstarlet-commands"></a><a class="relup shew-hover" href="#xmlstarlet-usage-notes"></a><a class="relnext shew-hover" href="#select"></a><a class="rellast shew-hover" href="#toc"></a></div></h2>
<p><code>xmlstarlet elements</code> (aka <code>el</code>) displays the structure of an XML document by listing the paths of elements and optionally attributes and attribute values.</p>
<h4 id="elements-usage" class="shew-tgt">Usage: <code>elments [option] [«xml-file»]</code><a href="#elements-usage" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<p>At most one option and one input file is accepted.</p>
<h3 id="elements-local-options" class="shew-tgt">Local options<a href="#elements-local-options" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span><a class="relup shew-hover" href="#elements"></a><a class="relnext shew-hover" href="#elements-examples"></a><span class="relnop shew-hover"></span></div></h3>
<h4 id="elements-opt-a" class="shew-tgt"><code>-a</code> - include attributes<a href="#elements-opt-a" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="elements-opt-v" class="shew-tgt"><code>-v</code> - include attribute values<a href="#elements-opt-v" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="elements-opt-u" class="shew-tgt"><code>-u</code> - sorted unique lines<a href="#elements-opt-u" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="elements-opt-d" class="shew-tgt"><code>-dN</code> - sorted unique lines to depth N<a href="#elements-opt-d" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<h3 id="elements-examples" class="shew-tgt">Examples<a href="#elements-examples" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><a class="relprev shew-hover" href="#elements-local-options"></a><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span></div></h3>
<h4 id="elements-sample-session" class="shew-tgt">Sample session<a href="#elements-sample-session" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#elements"></a><span class="relnop shew-hover"></span></div></h4>
<pre class="lang-shell"><code>$ : "${infile=recently-used.xbel}"
$ :
$ xmlstarlet elements -u "${infile}"
xbel
xbel/bookmark
xbel/bookmark/info
xbel/bookmark/info/metadata
xbel/bookmark/info/metadata/bookmark:applications
xbel/bookmark/info/metadata/bookmark:applications/bookmark:application
xbel/bookmark/info/metadata/bookmark:groups
xbel/bookmark/info/metadata/bookmark:groups/bookmark:group
xbel/bookmark/info/metadata/mime:mime-type
$ :
$ xmlstarlet el -d3 "${infile}"
xbel
xbel/bookmark
xbel/bookmark/info
$ :
$ # Skip repetitions
$ xmlstarlet el -a "${infile}" | awk '!seen[$1]++' | head -n 10
xbel
xbel/@xmlns:bookmark
xbel/@xmlns:mime
xbel/@version
xbel/bookmark
xbel/bookmark/@href
xbel/bookmark/@added
xbel/bookmark/@modified
xbel/bookmark/@visited
xbel/bookmark/info
$ :
$ xmlstarlet el -v "${infile}" | sed '2d;9q'
xbel[@xmlns:bookmark='http://www.freedesktop.org/standards/desktop-bookmarks' and @xmlns:mime='http://www.freedesktop.org/standards/shared-mime-info' and @version='1.0']
xbel/bookmark/info
xbel/bookmark/info/metadata[@owner='http://freedesktop.org']
xbel/bookmark/info/metadata/mime:mime-type[@type='image/jpeg']
xbel/bookmark/info/metadata/bookmark:groups
xbel/bookmark/info/metadata/bookmark:groups/bookmark:group
xbel/bookmark/info/metadata/bookmark:applications
xbel/bookmark/info/metadata/bookmark:applications/bookmark:application[@name='Image Viewer' and @exec="'eog %u'" and @modified='2022-03-28T07:27:27Z' and @count='1']
$ :
$ # Compute tree height as maximum branch node depth
$ xmlstarlet el -u "${infile}" | awk -F / '{d=NF-1;if(d>h)h=d}END{print 0+h}'
5</code></pre>
<p><em>See also</em>: <a href="#print-xpath-of-selected-elements-or-attributes">Print XPath of selected elements or attributes</a> example</p>
<div class="dinkus1">
</div>
</section>
<section id="sec-select">
<h2 id="select" class="shew-tgt">Query: <code>xmlstarlet select</code><a href="#select" class="permalink shew-hover"></a><div class="toolbar shew-hover h2"><a class="relfirst shew-hover" href="#introduction"></a><a class="relprev shew-hover" href="#elements"></a><a class="relup shew-hover" href="#xmlstarlet-usage-notes"></a><a class="relnext shew-hover" href="#edit"></a><a class="rellast shew-hover" href="#toc"></a></div></h2>
<p><code>xmlstarlet select</code> (aka <code>sel</code>) is basically a shorthand XSLT generator that can either process or print the stylesheet it generates. Typically used to extract and format data it supports a subset of XSLT 1.0 elements, all XPath 1.0 and XSLT 1.0 functions, plus the <a href="#exslt">EXSLT</a> functions offered by <code>libexslt</code>.</p>
<p><code>select</code> implements 7 XSLT instruction elements – <code>xsl:attribute</code>, <code>xsl:choose</code>, <code>xsl:copy-of</code>, <code>xsl:element</code>, <code>xsl:for-each</code>, <code>xsl:text</code>, <code>xsl:value-of</code> – plus <code>xsl:variable</code> (and <code>xsl:stylesheet</code>, <code>xsl:template</code>, <code>xsl:output</code> partially) but note the absence of <code>xsl:apply-templates</code>, <code>xsl:key</code> a.o. This means recursion and <em>identity transform</em>s are off-limits (unless resorting to <a href="#code-generation">code generation</a>).</p>
<p><code>xmlstarlet select</code> returns the same <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#function-system-property" title="W3C XSLT 1.0 recommendation"><code>system-property()</code></a> values as <a href="#transform"><code>xmlstarlet transform</code></a>. A stylesheet generated by <code>select</code> appears as located in the current directory.</p>
<p>Like <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html#tag_20_55_14" title="'grep - search a file for a pattern' utility at Open Group (POSIX)"><code>grep</code></a> <code>xmlstarlet select</code> returns an <a href="#exit-values">exit value</a> of 1 if no nodes were selected, e.g. <code>xmlstarlet select -T -t -m '(//xsl:document)[1]' -f *.xsl</code> returns 0 if at least one input file matches the XPath expression, otherwise 1 (with or without the <a href="#select-opt-quiet"><code>-Q (--quiet)</code></a> option).</p>
<p><em>See also</em>: <a href="#xml-parsing-and-serialization">XML parsing and serialization</a></p>
<div class="dinkus3">
</div>
<p><span class="caution"><strong>Caution</strong></span>: <code>xmlstarlet select</code> does not flag invalid non-template options (<a href="https://fossies.org/linux/xmlstarlet/src/xml_select.c#l_191">src/xml_select.c#selParseOptions()</a>) and ignores characters following the first letter in short template options (<a href="https://fossies.org/linux/xmlstarlet/src/xml_select.c#l_334">src/xml_select.c#selGenTemplate()</a>). Next command outputs:</p>
<pre class="lang-none"><code>optfuscation</code></pre>
<pre class="lang-sh"><code>xmlstarlet select --nonet --rsn -:=% -C -t -i\*r 2=2 -eR_W- x -a'!e'ee y -omit z -bar -b:rrrf -newln | {
xmlstarlet select -C -t -i 2=2 -e x -a y -o z -b -b -n |
cmp -s - /dev/fd/3
} 3<&0 && echo 'optfuscation' || echo 'returned non-zero'</code></pre>
<h4 id="select-usage" class="shew-tgt">Usage: <code>select</code> [option …] template … [«xml-file» …]<a href="#select-usage" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<div id="toc-select" class="nav">
<ul>
<li><a href="#select-non-template-options">Non-template options</a><br/>
<a href="#select-opt-help"><code>-h (--help)</code></a> | <a href="#select-opt-quiet"><code>-Q (--quiet)</code></a> | <a href="#select-opt-comp"><code>-C (--comp)</code></a> | <a href="#select-opt-root"><code>-R (--root)</code></a> | <a href="#select-opt-text"><code>-T (--text)</code></a> | <a href="#select-opt-indent"><code>-I (--indent)</code></a> | <a href="#select-opt-xml-decl"><code>-D (--xml-decl)</code></a> | <a href="#select-opt-noblanks"><code>-B (--noblanks)</code></a> | <a href="#select-opt-encode"><code>-E (--encode)</code></a> | <a href="#select-opt-n"><code>-N «prefix»=«value»</code></a> | <a href="#select-opt-net"><code>--net</code></a></li>
<li><a href="#select-template-options">Template options</a><br/>
<a href="#select-opt-template"><code>-t (--template)</code></a> | <a href="#select-opt-match"><code>-m (--match)</code></a> | <a href="#select-opt-sort"><code>-s (--sort)</code></a> | <a href="#select-opt-var-break"><code>--var «name» «value» --break</code></a> | <a href="#select-opt-var-equals"><code>--var «name»=«value»</code></a> | <a href="#select-exslt-namespace-issue"><code>--var «name»=«value»</code> namespace issue</a> | <a href="#select-opt-output"><code>-o (--output)</code></a> | <a href="#select-opt-elem"><code>-e (--elem)</code></a> | <a href="#select-opt-attr"><code>-a (--attr)</code></a> | <a href="#select-opt-copy-of"><code>-c (--copy-of)</code></a> | <a href="#select-opt-value-of"><code>-v (--value-of)</code></a> | <a href="#select-opt-if"><code>-i (--if)</code></a> | <a href="#select-opt-break"><code>-b (--break)</code></a> | <a href="#select-opt-nl"><code>-n (--nl)</code></a> | <a href="#select-opt-inp-name"><code>-f (--inp-name)</code></a></li>
<li><a href="#select-examples">Examples</a><br/>
<a href="#query-euro-rates">Query Euro rates</a> | <a href="#list-xml-files-matching-xpath-expression">List XML files matching XPath expression</a> | <a href="#print-xpath-of-selected-elements-or-attributes">Print XPath of selected elements or attributes</a> | <a href="#mark-up-plaintext">Mark up plaintext</a> | <a href="#use-the-document-function">Use the <code>document()</code> function</a> | <a href="#extract-subtree-to-depth-n-removing-namespaces">Extract subtree to depth N removing namespaces</a></li>
</ul>
</div>
<h3 id="select-non-template-options" class="shew-tgt">Non-template options<a href="#select-non-template-options" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span><a class="relup shew-hover" href="#select"></a><a class="relnext shew-hover" href="#select-template-options"></a><a class="rellast shew-hover" href="#select-examples"></a></div></h3>
<h4 id="select-opt-help" class="shew-tgt"><code>-h (--help)</code> - display help<a href="#select-opt-help" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="select-opt-quiet" class="shew-tgt"><code>-Q (--quiet)</code> - do not write anything to standard output<a href="#select-opt-quiet" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><em>See also</em>: global option <a href="#global-opt-quiet"><code>-q (--quiet)</code></a> (lowercase <code>-q</code>)</p>
<h4 id="select-opt-comp" class="shew-tgt"><code>-C (--comp)</code> - display generated XSLT<a href="#select-opt-comp" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Lists the XSLT stylesheet that will be generated from the current template options. No input file is required for this option. It produces no output other than a stylesheet or an error message.</p>
<p>Usage samples: <a href="#list-the-generated-xslt-xmlstarlet-select--c"><code>-t -m …</code></a> | <a href="#select-opt-output"><code>--output …</code></a> | <a href="#select-opt-value-of"><code>--value-of …</code></a> | <a href="#transform-opt-xinclude"><code>--xinclude</code></a></p>
<p><em>See also</em>: <a href="#ex3-introspection">Introspection</a> example</p>
<h4 id="select-opt-root" class="shew-tgt"><code>-R (--root)</code> - print root element <code><xsl-select></code><a href="#select-opt-root" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Wraps a container element named <code>xsl-select</code> around output. It includes any namespace nodes declared with <a href="#select-opt-n"><code>-N «prefix»=«value»</code></a> except the <a href="#namespaces-use">predefined</a> namespaces.</p>
<h4 id="select-opt-text" class="shew-tgt"><code>-T (--text)</code> - output is text (default is XML)<a href="#select-opt-text" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Sets <code>method="text"</code> on the <code>xsl:output</code> element.</p>
<pre class="lang-shell"><code>$ cat file.xml
<v><w>a&amp;</w><w>l&lt;</w><w>q&quot;</w><w>g&gt;</w></v>
$ :
$ xmlstarlet select -t -c '*/*[position()>2]' -n file.xml
<w>q"</w><w>g&gt;</w>
$ :
$ xmlstarlet select --text -t -c '*/*[position()<3]' -n file.xml
a&l<</code></pre>
<p><em>See also</em>: <a href="#special-characters">Special characters</a> | <a href="#select-opt-output"><code>-o (--output)</code></a></p>
<h4 id="select-opt-indent" class="shew-tgt"><code>-I (--indent)</code> - indent output<a href="#select-opt-indent" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Sets <code>indent="yes"</code> on the <code>xsl:output</code> element.</p>
<p>To re-indent, for example:</p>
<pre class="lang-sh"><code>xmlstarlet select -B -I -t -c / in.xml > out.xml</code></pre>
<p><em>See also</em>: <a href="#xml-parsing-and-serialization">XML parsing and serialization</a> | <a href="#select-opt-noblanks"><code>-B (--noblanks)</code></a></p>
<h4 id="select-opt-xml-decl" class="shew-tgt"><code>-D (--xml-decl)</code> - do not omit XML declaration line<a href="#select-opt-xml-decl" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Sets <code>omit-xml-declaration="no"</code> on the <code>xsl:output</code> element.</p>
<p>Use with <code>-E (--encode)</code> to specify encoding.</p>
<p><em>See also</em>: <a href="#xml-declaration">XML declaration</a></p>
<h4 id="select-opt-noblanks" class="shew-tgt"><code>-B (--noblanks)</code> - remove nonsignificant whitespace from XML tree<a href="#select-opt-noblanks" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>To strip nonsignificant whitespace, for example:</p>
<pre class="lang-sh"><code>xmlstarlet select -B -t -c / in.xml > out.xml</code></pre>
<p><em>See also</em>: <a href="#xml-parsing-and-serialization">XML parsing and serialization</a></p>
<h4 id="select-opt-encode" class="shew-tgt"><code>-E (--encode) «encoding»</code> - output in the given encoding<a href="#select-opt-encode" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Encoding value for the XML declaration, e.g. <code>UTF-8</code>, <code>ISO-8859-2</code>. Use with <code>-D (--xml-decl)</code>.</p>
<p><em>See also</em>: <a href="#xml-declaration">XML declaration</a></p>
<h4 id="select-opt-n" class="shew-tgt"><code>-N «prefix»=«value»</code> - declare namespaces<a href="#select-opt-n" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>This option is repeatable. E.g. <code>-N xsql='urn:oracle-xsql' -N X='http://www.w3.org/1999/xhtml'</code>. Either side of the equal sign may be empty<sup>[1]</sup>, e.g. <code>-N ''=''</code> (or <code>-N =</code>) for <code>xmlns=""</code>.</p>
<p>Not needed for <a href="#namespaces-use">predefined namespaces</a> or those declared in input’s root element (see <a href="#global-opt-doc-namespace"><code>--doc-namespace</code></a>) but required</p>
<ul>
<li>for namespaces not declared in input’s root element (e.g. if read by the <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#document" title="W3C XSLT 1.0 recommendation"><code>document()</code></a> function)</li>
<li>when the <a href="#global-opt-no-doc-namespace"><code>--no-doc-namespace</code></a> global option is in effect</li>
<li>to work around <code>select</code>’s <a href="#select-exslt-namespace-issue"><code>--var «name»=«value»</code> namespace issue</a></li>
<li>when referencing certain extensions such as <code>crypto</code> (see <a href="#exslt">EXSLT</a>)</li>
<li>to <a href="#namespaces-create">create</a> a namespace</li>
</ul>
<p><em>See also</em>: <a href="#namespaces-use">Use a namespace</a> | <a href="#select-opt-root"><code>-R (--root)</code></a> | <a href="#edit-opt-n"><code>edit -N</code></a></p>
<p><sup>[1]</sup> <code>-N foo=''</code> is <a href="https://web.archive.org/web/20180305021934/http://www.dpawson.co.uk/xsl/sect2/N5536.html#d7042e22">not</a> allowed; <code>echo '<v/>' | xmlstarlet sel -N foo= -t -e a -e foo:k</code> outputs <code><a><k/></a></code>.</p>
<h4 id="select-opt-net" class="shew-tgt"><code>--net</code> - allow fetch DTDs or entities over network<a href="#select-opt-net" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><em>See also</em>: <a href="#global-opt-net">network access</a></p>
<h3 id="select-template-options" class="shew-tgt">Template options<a href="#select-template-options" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><span class="relnop shew-hover"></span><a class="relprev shew-hover" href="#select-non-template-options"></a><a class="relup shew-hover" href="#select"></a><a class="relnext shew-hover" href="#select-examples"></a><span class="relnop shew-hover"></span></div></h3>
<h4 id="select-opt-template" class="shew-tgt"><code>-t (--template)</code> is <code><xsl:template match="/"></code><a href="#select-opt-template" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>The <code>-t (--template)</code> option marks the beginning of an <code>xsl:template</code> element which ends at a following <code>-t</code> option (i.e. non-nestable) or at the last option after <code>-t</code>. <code>-t</code> must be followed by at least one template option. <strong>NB</strong>: <code><xsl:template match="expression"></code> <em>cannot</em> be generated by combining <code>-t</code> and <code>-m</code> options.</p>
<p><code>-t (--template)</code> makes the root node (<code>/</code>, not the root element <code>/*</code>) the <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#dt-current-node" title="W3C XSLT 1.0 recommendation">current node</a> so XPath expressions can be relative,</p>
<pre class="lang-sh"><code>xmlstarlet select -t -m '*/*/r' -v '@id' -n file</code></pre>
<p>even obscure,</p>
<pre class="lang-sh"><code>echo '<q>2</q>' | xmlstarlet sel -t -v '*******************'</code></pre>
<p>with thanks to Michael Kay for his original Christmas <a href="https://web.archive.org/web/20180305021934/http://www.dpawson.co.uk/xsl/sect2/N3773.html#d5234e19">cracker</a> the output of which is <code>1024</code>.</p>
<div class="dinkus3">
</div>
<p>As <code>xmlstarlet select --help</code> shows, two or more <code>--template</code>s are implemented as:</p>
<pre class="lang-xml"><code><xsl:template match="/">
<xsl:call-template name="t1"/>
<xsl:call-template name="t2"/>
…
</xsl:template></code></pre>
<p><em>See also</em>: List the generated XSLT <a href="#select-opt-comp"><code>-C (--comp)</code></a></p>
<h4 id="select-opt-match" class="shew-tgt"><code>-m (--match)</code> is <code><xsl:for-each select="xpath-expr"></code><a href="#select-opt-match" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-m (--match)</code> is a rare misnomer among <code>xmlstarlet</code>’s option names: it translates to the <code>xsl:for-each</code> element and has nothing to do with an <code>xsl:template</code> pattern. <code>-m (--match)</code> is nestable and can be explicitly terminated with <a href="#select-opt-break"><code>-b (--break)</code></a>.</p>
<p><em>Links</em>: XSLT <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#dt-current-node" title="W3C XSLT 1.0 recommendation">current node</a> | XSLT <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#for-each" title="W3C XSLT 1.0 recommendation"><code>xsl:for-each</code></a> | XSLT <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#function-current" title="W3C XSLT 1.0 recommendation"><code>current()</code></a> | XPath <a href="https://www.w3.org/TR/1999/REC-xpath-19991116#dt-context-node" title="W3C XPath 1.0 recommendation">context node</a></p>
<div class="dinkus3">
</div>
<p><code>xsl:for-each</code> changes the current node. The XPath functions <a href="https://www.w3.org/TR/1999/REC-xpath-19991116##section-Node-Set-Functions" title="W3C XPath 1.0 recommendation"><code>position()</code></a> and <a href="https://www.w3.org/TR/1999/REC-xpath-19991116##section-Node-Set-Functions" title="W3C XPath 1.0 recommendation"><code>last()</code></a> return the context position and context size, respectively.</p>
<pre class="lang-shell"><code>$ printf '<v w="a:b:c:d:e:f:g:h:i:j"/>' |
xmlstarlet select --text -t \
-m 'str:split(v/@w,":")' \
--if 'position() mod 3 = 0' \
-v 'concat(position()," ",.," ")'
3 c 6 f 9 i </code></pre>
<p>whereas <code>-m 'str:split(v/@w,":")[position() mod 3 = 0]' -v 'concat(…)'</code> outputs <code>1 c 2 f 3 i</code>.</p>
<div class="dinkus3">
</div>
<p>Keeping a reference to root for node changes.</p>
<pre class="lang-shell"><code>$ cat file.xml
<r><e id="a">fee</e><e id="b">fi</e><e id="c">fo</e><e id="d">fum</e></r>
$ :
$ xmlstarlet select -T -t \
-m 'str:split("a b c d")' \
-v 'concat(//e[@id=current()],". ")' \
-b -n \
file.xml
. . . .
$ :
$ xmlstarlet select -T -t \
--var R='/' \
-m 'str:split("a b c d")' \
-v 'concat($R//e[@id=current()],". ")' \
-b -n \
file.xml
fee. fi. fo. fum. </code></pre>
<h4 id="select-opt-sort" class="shew-tgt"><code>-s (--sort)</code> is <code><xsl:sort …/></code><a href="#select-opt-sort" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>To process a nodeset in sorted order add one or more <code>-s (--sort) 'X:Y:Z' 'xpath'</code> options immediately after <code>-m (--match)</code>.</p>
<ul>
<li><code>X</code> is one of <code>A | D | -</code> to set <code>order</code> ascending | descending | unspecified</li>
<li><code>Y</code> is one of <code>N | T | -</code> to set <code>data-type</code> number | text | unspecified</li>
<li><code>Z</code> is one of <code>U | L | -</code> to set <code>case-order</code> upper-first | lower-first | unspecified</li>
<li><span class="caution"><strong>Caution</strong></span>: invalid sort options are silently treated as <code>-</code> (unspecified)</li>
</ul>
<p>For example:</p>
<ul>
<li>ascending numerical order: <code>-s 'A:N:-' '.'</code></li>
<li>reverse document order: <code>-s 'D:N:-' 'position()'</code></li>
<li><code>DD.MM.YYYY</code> dates by year, month, date:<br/>
<code>-s 'A:T:-' 'concat(substring(.,7,4), substring(.,4,2), substring(.,1,2))'</code></li>
</ul>
<p><em>See also</em>: <a href="https://fossies.org/linux/www/xmlstarlet-1.6.1.tar.gz/" title="Fossies - the Fresh Open Source Software Archive">examples/sort*</a> | <a href="#query-euro-rates">Query Euro rates</a> | <a href="#remove-all-but-the-latest-member-of-each-group">Remove all but the latest member of each group</a></p>
<h4 id="select-opt-var-break" class="shew-tgt"><code>--var «name» «value» --break</code> is <code><xsl:variable name="…">«value»</xsl:variable</code>><a href="#select-opt-var-break" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="select-opt-var-equals" class="shew-tgt"><code>--var «name»=«value»</code> is <code><xsl:variable name="…"/></code><a href="#select-opt-var-equals" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>xmlstarlet select</code> has 2 forms of <code>--var</code>, cf. <code>xsl:variable</code>:</p>
<ol type="1">
<li><code>--var name=value</code>, e.g.
<ul>
<li><code>--var n='5'</code></li>
<li><code>--var s='"fee fi fo fum"'</code></li>
<li><code>--var f='true()'</code></li>
<li><code>--var V='//_:abc[@class="def"]'</code></li>
<li><code>--var W='$V/_:ghi[boolean(@jkl)]'</code></li>
<li><code>-m 'str:split($ws)' --var w='.' …</code></li>
<li><code>--var lut='document("")//xsl:variable[@name="rtf"]/*'</code></li>
</ul></li>
<li><code>--var name value --break</code><br/>
defining string content and terminated with <a href="#select-opt-break"><code>-b (--break)</code></a>, e.g.
<ul>
<li><code>--var nl -n -b</code></li>
<li><code>--var s -o '<f&g>' -b</code></li>
<li><code>--var stuff -e doranc -c 'a[c] | d[c]' -b -b</code></li>
<li><code>--var lines -m '$expr' -v '…' -n -b -b</code></li>
<li><code>--var reply --if '$v > 4' -o 'yes' --elif '$v < 2' -o 'no' --else -o 'maybe' -b -b</code></li>
</ul></li>
</ol>
<p>(<code>xmlstarlet edit</code> has 1 form: <a href="#edit-opt-var"><code>--var name xpath</code></a>.)</p>
<p><em>See also</em>: <a href="#select-exslt-namespace-issue"><code>--var «name»=«value»</code> namespace issue</a></p>
<div class="dinkus3">
</div>
<p>Result tree fragment (RTF) demo:</p>
<pre class="lang-sh"><code>printf '<v/>\n' |
xmlstarlet select -t \
--var rtf \
-e x -a k -o 1st -b -o First. -b \
-e x -a k -o 2nd -b -o Second. -b \
-e x -a k -o 3rd -b -o Third. -b \
-b \
--var tbl='exslt:node-set($rtf)' \
-v 'exslt:object-type($rtf)' -o ' rtf ' -v '$rtf' -n -c '$rtf' -n \
-v 'exslt:object-type($tbl)' -o ' tbl ' -v '$tbl' -n -c '$tbl' -n</code></pre>
<p>Output:</p>
<pre class="lang-none"><code>RTF rtf First.Second.Third.
<x k="1st">First.</x><x k="2nd">Second.</x><x k="3rd">Third.</x>
node-set tbl First.Second.Third.
<x k="1st">First.</x><x k="2nd">Second.</x><x k="3rd">Third.</x></code></pre>
<p><code>$tbl/x[@k="2nd"]</code> is a valid XPath expression, <code>$rtf/x[@k="2nd"]</code> is not and triggers an <code>Invalid type</code> run-time error.</p>
<p><em>See also</em>: RTF examples <a href="#ex2-extract-and-merge-records">file list</a> | <a href="#ex4-external-lookup-table">accumulation</a></p>
<p><em>Links</em>: <a href="https://exslt.github.io/exsl/functions/node-set/index.html"><code>exslt:node-set</code></a> | <a href="https://web.archive.org/web/20180305021934/http://www.dpawson.co.uk/xsl/sect2/nodeset.html">nodeset vs. RTF</a> by David Carlisle, Jörg Pietschmann | <a href="https://stackoverflow.com/a/53026101">RTF background</a> by Michael Kay</p>
<h4 id="select-exslt-namespace-issue" class="shew-tgt"><code>--var «name»=«value»</code> namespace issue<a href="#select-exslt-namespace-issue" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><span class="caution"><strong>Caution</strong></span>: An <a href="#exslt">EXSLT</a> namespace prefix (other than <code>exslt</code> (?)) used only inside <code>xmlstarlet select</code>’s <code>--var name='…'</code> triggers runtime error <code>xmlXPathCompOpEval: function «func» bound to undefined prefix «ns»</code> unless option <a href="#select-opt-n"><code>-N ns=…</code></a> is given. Workaround: use <code>-N ns=…</code> or use the prefix outside <code>--var name='…'</code>, e.g. in <code>-v</code> or <code>-m</code> or (for string content) <code>--var name … -b</code>.</p>
<pre class="lang-shell"><code>$ printf '%s\n' '<v s="a b c"/>' |
xmlstarlet select -t \
--var d='str:split(v/@s)' \
-v '$d' -n
xmlXPathCompOpEval: function split bound to undefined prefix str
runtime error: element variable
Failed to evaluate the expression of variable 'd'.
no result for -
$ :
$ printf '%s\n' '<v s="a b c"/>' |
xmlstarlet select -t \
-m 'str:split(v/@s)' \
-v . -b -n
abc</code></pre>
<h4 id="select-opt-output" class="shew-tgt"><code>-o (--output)</code> is <code><xsl:text>«value»</xsl:text></code><a href="#select-opt-output" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<pre class="lang-shell"><code>$ xmlstarlet select -T -C -t -o 'A<&'\''">z'
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output omit-xml-declaration="yes" indent="no" method="text"/>
<xsl:template match="/">
<xsl:text>A&lt;&amp;'"&gt;z</xsl:text>
</xsl:template>
</xsl:stylesheet></code></pre>
<p><code>-o ''</code> translates to an empty <code><xsl:text/></code> element.</p>
<p><em>See also</em>: <a href="#special-characters">Special characters</a></p>
<p>To manage parameters of the <code>xsl:output</code> element, see <a href="#xml-parsing-and-serialization">XML parsing and serialization</a>.</p>
<h4 id="select-opt-elem" class="shew-tgt"><code>-e (--elem)</code> is <code><xsl:element name="…"></code><a href="#select-opt-elem" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-e</code> is nestable and can be explicitly terminated with <a href="#select-opt-break"><code>-b (--break)</code></a>.</p>
<p><em>See also</em>: <a href="#namespaces-create">Create a namespace</a> | <a href="#create-a-soap-envelope">Create a SOAP envelope</a> example</p>
<h4 id="select-opt-attr" class="shew-tgt"><code>-a (--attr)</code> is <code><xsl:attribute name="…"></code><a href="#select-opt-attr" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-a</code> can be explicitly terminated with <a href="#select-opt-break"><code>-b (--break)</code></a>.</p>
<p>In XSLT, the latter of two same-named attributes is accepted, e.g.</p>
<pre class="lang-shell"><code>$ echo '<v/>' |
xmlstarlet select -t -e doc -a f -o n -b -a f -o y
<doc f="y"/></code></pre>
<h4 id="select-opt-copy-of" class="shew-tgt"><code>-c (--copy-of)</code> is <code><xsl:copy-of select="xpath-expr"/></code><a href="#select-opt-copy-of" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>See examples at: <a href="#select-opt-text"><code>-T (--text)</code></a> | <a href="#select-opt-indent"><code>-I (--indent)</code></a></p>
<h4 id="select-opt-value-of" class="shew-tgt"><code>-v (--value-of)</code> is <code>string-join((xpath-expr),newline)</code><a href="#select-opt-value-of" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>With zero or one nodeset members in <code>xpath-expr</code> <code>-v (--value-of)</code> works exactly as XSLT 1.0’s <code><xsl:value-of select="xpath-expr"/></code>, otherwise (like <code>string-join()</code> in XSLT 2.0) all members are output, stringified and separated by newlines.</p>
<pre class="lang-shell"><code>$ echo '<v><w>fee</w><w>fi</w><w>fo</w><w>fum</w></v>' |
xmlstarlet select -T -t -v '*/*' -t -n
fee
fi
fo
fum</code></pre>
<p>Adding <a href="#select-opt-comp"><code>-C (--comp)</code></a> option to list the XSLT code for the <code>value-of-template</code>:</p>
<pre class="lang-xsl"><code><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:exslt="http://exslt.org/common" version="1.0" extension-element-prefixes="exslt">
<xsl:output omit-xml-declaration="yes" indent="no" method="text"/>
<xsl:template match="/">
<xsl:call-template name="t1"/>
<xsl:call-template name="t2"/>
</xsl:template>
<xsl:template name="t1">
<xsl:call-template name="value-of-template">
<xsl:with-param name="select" select="*/*"/>
</xsl:call-template>
</xsl:template>
<xsl:template name="t2">
<xsl:value-of select="'&#10;'"/>
</xsl:template>
<xsl:template name="value-of-template">
<xsl:param name="select"/>
<xsl:value-of select="$select"/>
<xsl:for-each select="exslt:node-set($select)[position()&gt;1]">
<xsl:value-of select="'&#10;'"/>
<xsl:value-of select="."/>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet></code></pre>
<h4 id="select-opt-if" class="shew-tgt"><code>-i (--if) [--elif …] [--else]</code> is <code><xsl:when> … [<xsl:otherwise>]</code><a href="#select-opt-if" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-i (--if)</code> is nestable and can be explicitly terminated with <a href="#select-opt-break"><code>-b (--break)</code></a>. It translates to an <code>xsl:choose</code> element.</p>
<h4 id="select-opt-break" class="shew-tgt"><code>-b (--break)</code> ends current container element<a href="#select-opt-break" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><code>-b (--break)</code> closes the currently open container element, one of:</p>
<ul>
<li><code>-m (--match)</code> (nestable)</li>
<li><code>-i (--if, --elif, --else)</code> (nestable)</li>
<li><code>-e (--elem)</code> (nestable)</li>
<li><code>-a (--attr)</code><br/>
e.g. <code>-a 'data-dec' -o 'pre' -v '.' -o 'suf' -b</code></li>
<li><code>--var</code> without <code>=</code> (nestable)<br/>
e.g. <code>--var idls -m 'was[not(was)]' -v 'concat(@id,$sep,@class)' -n -b -b</code><br/>
any nested <code>--var</code>s are local to the enclosing <code>--var</code> but must have unique variable names.</li>
<li><code>-t (--template)</code></li>
</ul>
<p>These can be followed by a variable number of options and so must be terminated explicitly unless followed by one of:</p>
<ul>
<li>a <code>-t (--template)</code> option</li>
<li>an input filename</li>
<li>end of <code>xmlstarlet</code> command</li>
</ul>
<p>closing all open elements. In other words, trailing <code>-b</code>s may be omitted if they’re the last options in the current template.</p>
<p>A <code>-b (--break)</code> too many can trigger compilation error: <code>xsltParseStylesheetTop: unknown «name» element</code>.</p>
<h4 id="select-opt-nl" class="shew-tgt"><code>-n (--nl)</code> prints a newline<a href="#select-opt-nl" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<h4 id="select-opt-inp-name" class="shew-tgt"><code>-f (--inp-name)</code> prints pathname / URI of current input<a href="#select-opt-inp-name" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Shorthand for <code>-v '$inputFile'</code> (a predefined variable). Outputs <code>-</code> (dash) for standard input (<code>stdin</code>).</p>
<h3 id="select-examples" class="shew-tgt">Examples<a href="#select-examples" class="permalink shew-hover"></a><div class="toolbar shew-hover h3"><a class="relfirst shew-hover" href="#select-non-template-options"></a><a class="relprev shew-hover" href="#select-template-options"></a><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span><span class="relnop shew-hover"></span></div></h3>
<h4 id="query-euro-rates" class="shew-tgt">Query Euro rates<a href="#query-euro-rates" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>Download (< 2K) and convert the European Central Bank’s Euro rates sorted by currency in <code>A</code>scending order as <code>T</code>ext, <code>U</code>pper-first:</p>
<pre class="lang-sh"><code>wget -qO- 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml' |
xmlstarlet select --text -t \
-m '//_:Cube[@currency]' \
-s 'A:T:U' '@currency' \
-v 'concat(@currency," ",@rate)' -n</code></pre>
<p><em>See also</em>: <a href="#select-opt-sort"><code>-s (--sort)</code></a></p>
<h4 id="list-xml-files-matching-xpath-expression" class="shew-tgt">List XML files matching XPath expression<a href="#list-xml-files-matching-xpath-expression" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>List files in current dir and subdirs containing at least one <code>milk</code> element (returns non-zero if no match):</p>
<pre class="lang-sh"><code>find . -type f -name '*.xml' -exec \
xmlstarlet select -T -t -m '(//*[local-name()="milk"])[1]' -f -n {} +</code></pre>
<p>Return zero if at least one XML element text exactly matches <code>milk</code>, otherwise non-zero (no output is produced):</p>
<pre class="lang-sh"><code>find . -type f -name '*.xml' -exec \
xmlstarlet select -Q -T -t -m '(//*[text()="milk"])[1]' -f -n {} +</code></pre>
<p><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/find.html#tag_20_47_05" title="'find files' utility at Open Group (POSIX)"><code>find</code></a>’s <code>{} +</code> fills up the command line with pathnames.</p>
<p><em>See also</em>: <a href="#select-opt-inp-name"><code>-f (--inp-name)</code></a> | <a href="#select-opt-quiet"><code>-Q (--quiet)</code></a> | <a href="#exit-values">exit values</a></p>
<h4 id="print-xpath-of-selected-elements-or-attributes" class="shew-tgt">Print XPath of selected elements or attributes<a href="#print-xpath-of-selected-elements-or-attributes" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><em>Note</em>: This handles element or attribute nodes but no other node types.</p>
<pre class="lang-sh"><code>: ${fileglob:=/usr/share/*/xslt/docbook/common/db-common.xsl}
: ${target:='//xsl:param[string(@select)]'}
xmlstarlet select --text -t \
-m "${target}" \
-m 'ancestor-or-self::*' \
--var pos='1+count(preceding-sibling::*[name() = name(current())])' \
-v 'concat("/",name(),"[",$pos,"]")' \
-b \
--if 'count(. | ../@*) = count(../@*)' \
-v 'concat("/@",name())' \
-b \
-n \
${fileglob}</code></pre>
<p>where:</p>
<ul>
<li><code>${varname:=…}</code> assigns a default value by <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02" title="Shell command language at Open Group (POSIX)"><em>shell parameter expansion</em></a> via the built-in <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_16_01" title="'colon - null utility' at Open Group (POSIX)">colon</a> utility</li>
<li>the outer <a href="#select-opt-match"><code>-m (--match)</code></a> option specifies the target, with optional search conditions given as XPath <a href="https://www.w3.org/TR/1999/REC-xpath-19991116#predicates" title="W3C XPath 1.0 recommendation">predicates</a></li>
<li>the inner <code>-m (--match)</code> builds the XPath of elements from root to target, calculating position by counting siblings using the XSLT 1.0 <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#function-current" title="W3C XSLT 1.0 recommendation"><code>current()</code></a> function</li>
<li>for an attribute node target – which doesn’t match <code>ancestor-or-self::*</code> – the <a href="#select-opt-if"><code>-i (--if)</code></a> clause adjusts the XPath</li>
</ul>
<p>Output:</p>
<pre class="lang-none"><code>/xsl:stylesheet[1]/xsl:template[1]/xsl:param[1]
/xsl:stylesheet[1]/xsl:template[4]/xsl:param[1]
/xsl:stylesheet[1]/xsl:template[5]/xsl:param[1]
/xsl:stylesheet[1]/xsl:template[5]/xsl:param[2]
/xsl:stylesheet[1]/xsl:template[6]/xsl:param[1]</code></pre>
<p>Output if called with <code>target='//xsl:*/@test[contains(.,"position")]'</code>:</p>
<pre class="lang-none"><code>/xsl:stylesheet[1]/xsl:template[2]/xsl:for-each[1]/xsl:if[1]/@test
/xsl:stylesheet[1]/xsl:template[3]/xsl:for-each[1]/xsl:if[1]/@test
/xsl:stylesheet[1]/xsl:template[7]/xsl:for-each[1]/xsl:choose[1]/xsl:when[1]/@test
/xsl:stylesheet[1]/xsl:template[7]/xsl:for-each[1]/xsl:choose[1]/xsl:when[3]/@test</code></pre>
<p><em>See also</em>: <a href="#elements"><code>xmlstarlet elements</code></a></p>
<h4 id="mark-up-plaintext" class="shew-tgt">Mark up plaintext<a href="#mark-up-plaintext" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p>If the plaintext input is uncomplicated perhaps <a href="#exslt">EXSLT</a>’s <a href="https://exslt.github.io/str/index.html"><code>string</code></a> functions can do the conversion. Note that <a href="https://exslt.github.io/str/functions/replace/index.html"><code>str:replace</code></a>, <a href="https://exslt.github.io/str/functions/split/index.html"><code>str:split</code></a>, and <a href="https://exslt.github.io/str/functions/tokenize/index.html"><code>str:tokenize</code></a> are <a href="#exslt">available</a> for <code>xmlstarlet select</code> (and <code>transform</code>), but not for <a href="#edit-exslt-in-xpath-arguments"><code>edit</code></a>.</p>
<pre class="lang-xml"><code><root>
A;2022-08-10;db #1
B;sortie bidon;50.0
A;2022-08-12;db Cth
B;mali climber;40.0
C;fray illumine;9.75
</root></code></pre>
<ul>
<li>define input’s field, sub-record, and record separators as <code>ifs</code>, <code>iss</code>, and <code>irs</code>, respectively</li>
<li>split input by record, then by sub-record and by field using the EXSLT <a href="https://exslt.github.io/str/functions/split/index.html"><code>str:split</code></a> function, while applying XML markup</li>
<li>note the newline before the first <code>A</code> in input</li>
</ul>
<pre class="lang-sh"><code>xmlstarlet select --indent -t \
--var ifs -o ';' -b \
--var iss -n -b \
--var irs='concat($iss,"A")' \
-e recs \
-m 'str:split(*,$irs)' \
-e rec \
--var sr='str:split(.,$iss)' \
--var hd='str:split($sr[1],$ifs)' \
-e hd \
-e dt -v '$hd[1]' -b \
-e wd -v '$hd[2]' -b \
-b \
-e bd \
-m '$sr[position()!=1]' \
--var f='str:split(.,$ifs)' \
-e fld \
-a typ -v '$f[1]' -b \
-e dsc -v '$f[2]' -b \
-e amt -v '$f[3]' -b \
"${infile:-file.xml}"</code></pre>
<p><em>See also</em>: <a href="#select-opt-var-break"><code>--var</code></a> | <a href="#select-opt-match"><code>-m (--match)</code></a> | <a href="#select-opt-elem"><code>-e (--elem)</code></a> | <a href="#select-opt-break"><code>-b (--break)</code></a></p>
<p>Output:</p>
<pre class="lang-xml"><code><recs>
<rec>
<hd>
<dt>2022-08-10</dt>
<wd>db #1</wd>
</hd>
<bd>
<fld typ="B">
<dsc>sortie bidon</dsc>
<amt>50.0</amt>
</fld>
</bd>
</rec>
<rec>
<hd>
<dt>2022-08-12</dt>
<wd>db Cth</wd>
</hd>
<bd>
<fld typ="B">
<dsc>mali climber</dsc>
<amt>40.0</amt>
</fld>
<fld typ="C">
<dsc>fray illumine</dsc>
<amt>9.75</amt>
</fld>
</bd>
</rec>
</recs></code></pre>
<h4 id="use-the-document-function" class="shew-tgt">Use the <code>document()</code> function<a href="#use-the-document-function" class="permalink shew-hover"></a><div class="toolbar shew-hover h4"><a class="relup shew-hover" href="#select"></a><span class="relnop shew-hover"></span></div></h4>
<p><em>Links</em>: <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#document" title="W3C XSLT 1.0 recommendation"><code>document()</code></a> in W3C rec</p>
<p>The XSLT <code>document()</code> function</p>
<ul>
<li>resolves relative URIs using a base URI (cf. <a href="#select-as-xslt-stylesheet-generator">code generation</a> example), the default base being the stylesheet’s location (which is the current directory if generated by <a href="#select"><code>xmlstarlet select</code></a>)</li>
<li>requires XML document(s) as input, not <a href="https://www.w3.org/TR/xml-fragment" title="XML Fragment Interchange - W3C Candidate Recommendation">fragments</a> (even if they’re well-balanced); otherwise <code>xmlstarlet</code> abends with an error message such as <code>Extra content at the end of the document</code> and (<span class="caution"><strong>Caution</strong></span>) exit value 0</li>
<li>returns the root node of the stylesheet when invoked as <code>document("")</code></li>
</ul>
<p><em>Examples</em>: <a href="#ex1-merge-2-xml-files">merge 2 XML files</a> | <a href="#ex2-extract-and-merge-records">extract and merge records</a> | <a href="#ex3-introspection">introspection</a> | <a href="#ex4-external-lookup-table">external lookup table</a></p>
<div class="dinkus2">
</div>
<h5 id="ex1-merge-2-xml-files" class="shew-tgt">ex1: merge 2 XML files<a href="#ex1-merge-2-xml-files" class="permalink shew-hover"></a></h5>
<p>Insert child nodes of <code>${partfile}</code>’s root element into <code>${infile}</code>’s <code>${destination}</code> element – using a 3-stage pipeline:</p>
<pre class="lang-sh"><code>xmlstarlet select -R -t \
--var part -o "${partfile:-file2.xml}" -b \
-c ' / | document($part)' "${infile:-file.xml}" |
xmlstarlet edit -m '/xsl-select/*[2]/node()' '/xsl-select'"${destination:-/..}" |
xmlstarlet select -B -I -t -c '/xsl-select/*[1]'</code></pre>
<ul>
<li><strong>assuming</strong> namespaces agree</li>
<li>invoke <code>select</code> to copy the 2 documents and wrap them (<code>-R</code>) as <code>/xsl-select/*[1]</code> and <code>/xsl-select/*[2]</code>, using <a href="https://www.w3.org/TR/1999/REC-xslt-19991116#document" title="W3C XSLT 1.0 recommendation"><code>document()</code></a> to access the <code>${partfile}</code> – either <code>${infile}</code> or <code>${partfile}</code> can be <code>/dev/stdin</code></li>
<li>call <code>edit</code> to <a href="#edit-opt-move"><code>-m (--move)</code></a> children of <code>${partfile}</code>’s root element to <code>${destination}</code> – an XPath expression locating an element in <code>${infile}</code> – incoming nodes will be appended as last nodes there</li>
<li>default <code>${destination}</code> (<code>/..</code>) causes an error to be generated and must be <strong>overridden</strong></li>
<li>invoke <code>select</code> to extract and format the merged document</li>
</ul>
<p><em>See also</em>: <a href="#select-opt-root"><code>-R (--root)</code></a> | <a href="#select-opt-var-break"><code>--var … -b</code></a> | <a href="#select-opt-noblanks"><code>-B (--noblanks)</code></a> | <a href="#select-opt-indent"><code>-I (--indent)</code></a> | <a href="#select-opt-copy-of"><code>-c (--copy-of)</code></a></p>
<p>If called with this <code>${partfile}</code></p>
<pre class="lang-xml"><code><items>
<item>1</item><item>2</item><item>3</item>
</items></code></pre>
<p>and this <code>${infile}</code></p>
<pre class="lang-xml"><code><doc><g><g1/><g2/><g3/></g></doc></code></pre>
<p>and <code>destination=/doc//g1</code>, then output becomes:</p>
<pre class="lang-xml"><code><doc>
<g>
<g1>
<item>1</item>
<item>2</item>
<item>3</item>
</g1>
<g2/>
<g3/>
</g>
</doc></code></pre>
<p><em>See also</em>: <a href="#transform-opt-xinclude"><code>transform --xinclude</code></a></p>
<h5 id="ex2-extract-and-merge-records" class="shew-tgt">ex2: extract and merge records<a href="#ex2-extract-and-merge-records" class="permalink shew-hover"></a></h5>
<p>Given a number of similar XML input files each containing a simple record set,</p>
<pre class="lang-sh"><code>echo '<v/>' |
xmlstarlet select -R -I -t \
--var fls \
-e f -o 'data/rs1.xml' -b \
-e f -o 'data/rs2.xml' -b \
-e f -o 'data/rs3.xml' -b \
-b \
-c 'document(exslt:node-set($fls)/f) /*/r'</code></pre>
<ul>
<li>collects a file list in a <em>result tree fragment</em> (RTF, cf. <a href="#select-opt-var-equals"><code>select --var</code></a>)</li>
<li>converts the RTF to a nodeset using the <a href="#exslt">EXSLT</a> <a href="https://exslt.github.io/exsl/functions/node-set/index.html"><code>exslt:node-set()</code></a> function</li>
<li>passes the pathnames as a nodeset ( <code>…/f</code>) to <code>document()</code></li>