xmlstarlet-notes/index.html at main · martin7th/xmlstarlet-notes · GitHub

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="12 March 2025">
version 2025-03-12 | <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>&lt;o/&gt;&lt;o/&gt;</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.12) with <code>xmlstarlet</code> 1.6.1 (linked with libxml2 20914
and libxslt 10139) from the <a href="https://packages.debian.org/sid/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>    &lt;xsl:variable name="y"&gt;
      &lt;xsl:call-template name="f"&gt;
        &lt;xsl:with-param name="x"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:variable&gt;</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/sid/xmlstarlet" title="command line XML toolkit">xmlstarlet</a> | <a href="https://packages.debian.org/sid/xsltproc" title="XSLT 1.0 command line processor">xsltproc</a> | <a href="https://packages.debian.org/sid/libxml2-utils" title="GNOME XML library - utilities">libxml2-utils</a>
(<code>xmllint</code>) | <a href="https://packages.debian.org/sid/html-xml-utils" title="HTML and XML manipulation utilities">html-xml-utils</a> | <a href="https://packages.debian.org/sid/xml2" title="Convert between XML, HTML, CSV and a line-oriented format">xml2</a>
| <a href="https://packages.debian.org/sid/tidy" title="HTML/XML syntax checker and reformatter">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>
<li><code>repology.org</code> versions pages for <a href="https://repology.org/project/xmlstarlet/versions"><code>xmlstarlet</code></a>
| <a href="https://repology.org/project/libxml2/versions"><code>libxml2</code></a>
| <a href="https://repology.org/project/libxslt/versions"><code>libxslt</code></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>&lt;?xml version="1.0"?&gt;
&lt;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"&gt;
  &lt;xsl:output omit-xml-declaration="yes" indent="no" method="text"/&gt;
  &lt;xsl:template match="/"&gt;
    &lt;xsl:for-each select="str:tokenize(&amp;quot;Hello, world&amp;quot;,&amp;quot;,o&amp;quot;)"&gt;
      &lt;xsl:call-template name="value-of-template"&gt;
        &lt;xsl:with-param name="select" select="."/&gt;
      &lt;/xsl:call-template&gt;
      &lt;xsl:value-of select="'&amp;#10;'"/&gt;
    &lt;/xsl:for-each&gt;
  &lt;/xsl:template&gt;
  &lt;xsl:template name="value-of-template"&gt;
    &lt;xsl:param name="select"/&gt;
    &lt;xsl:value-of select="$select"/&gt;
    &lt;xsl:for-each select="exslt:node-set($select)[position()&amp;gt;1]"&gt;
      &lt;xsl:value-of select="'&amp;#10;'"/&gt;
      &lt;xsl:value-of select="."/&gt;
    &lt;/xsl:for-each&gt;
  &lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</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>&amp;&lt;&gt;'"</code> or – as
references to <em>predefined general entities</em> –
<code>&amp;amp;</code> <code>&amp;lt;</code> <code>&amp;gt;</code>
<code>&amp;apos;</code> <code>&amp;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>&lt;</code> (less-than) on the command line, as in
<code>factor[. &lt; 2.19]</code>, whereas XSLT stylesheets require
<code>&amp;lt;</code> inside attribute values, or <code>&gt;</code>
(greater-than) with operands swopped. Likewise, a numeric character
reference such as <code>&amp;#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>&amp;#x100;</code> – are recognized in the following which
therefore require <code>&amp;amp;</code> to represent an
<code>&amp;</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(. , '&amp;#10;', ' ')" …</code>
– in fact converts <code>&amp;</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' '&lt;e/&gt;'|
xmlstarlet edit -O \
  -s     '*' -t elem -n esuv -v '' -u '$prev' -v '&amp;Save as &lt;.oona&gt;' \
  -a '$prev' -t elem -n eaux -v '' -u '$prev' -x '"&amp;Save as &lt;.oona&gt;"' \
  -s     '*' -t elem -n esv1 -v '&amp;amp;Save as &lt;.oona&gt;' \
  -a '$prev' -t elem -n eav1 -v '&amp;amp;Save&amp;#x20;&amp;#x61;&amp;#x73;&amp;#x20;&amp;lt;.oona&amp;gt;' \
  -i '$prev' -t elem -n eiv1 -v "$(xmlstarlet escape '&amp;Save as &lt;.oona&gt;')"</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;amp;</code> is required for
<code>&amp;</code> (<code>esv1</code>, <code>eav1</code>,
<code>eiv1</code>) whereas <code>&lt;&gt;'"</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>&lt;e&gt;
  &lt;esuv&gt;&amp;amp;Save as &amp;lt;.oona&amp;gt;&lt;/esuv&gt;
  &lt;eaux&gt;&amp;amp;Save as &amp;lt;.oona&amp;gt;&lt;/eaux&gt;
  &lt;esv1&gt;&amp;amp;Save as &amp;lt;.oona&amp;gt;&lt;/esv1&gt;
  &lt;eiv1&gt;&amp;amp;Save as &amp;lt;.oona&amp;gt;&lt;/eiv1&gt;
  &lt;eav1&gt;&amp;amp;Save as &amp;lt;.oona&amp;gt;&lt;/eav1&gt;
&lt;/e&gt;</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 'Word Expansions' - 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 '&lt;v w="x"/&gt;' |
  xmlstarlet select -D -E 'ISO-8859-2' -t -c '/'
&lt;?xml version="1.0" encoding="ISO-8859-2"?&gt;
&lt;v w="x"/&gt;</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-encode"><code>-E (--encode)</code></a>: sets
<code>encoding="«encoding»"</code> on <code>xsl:output</code>, with
<code>-D (--xml-decl)</code> also in the XML declaration</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>&lt;p/&gt;</code> to
<code>&lt;p&gt;&lt;/p&gt;</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>&amp;&lt;&gt;</code> (output as <code>&amp;amp;</code>,
<code>&amp;lt;</code>, and <code>&amp;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' '&lt;v&gt;&lt;w&gt;x&lt;/w&gt;&lt;x&gt;🧩&lt;/x&gt;&lt;/v&gt;' |
  xmlstarlet edit -O -P -d '*/w'
&lt;v&gt;&lt;x&gt;&amp;#x1F9E9;&lt;/x&gt;&lt;/v&gt;
$ :
$ printf '%s\n' '&lt;v&gt;&lt;w&gt;x&lt;/w&gt;&lt;x&gt;&lt;![CDATA[🧩]]&gt;&lt;/x&gt;&lt;/v&gt;' |
  xmlstarlet edit -O -P -d '*/w'
&lt;v&gt;&lt;x&gt;&lt;![CDATA[🧩]]&gt;&lt;/x&gt;&lt;/v&gt;</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>&lt;doc&gt;&amp;e;&lt;/doc&gt;</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 &lt;e&gt;N&lt;/e&gt;
# - ${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' \
  '&lt;!DOCTYPE skel [&lt;!ENTITY e SYSTEM "'"${dataf}"'"&gt;]&gt;&lt;doc&gt;&amp;e;&lt;/doc&gt;' \
&gt; "${skelf}"
printf '%s' \
  "${xdata:-&lt;e&gt;1&lt;/e&gt;&lt;e&gt;2&lt;/e&gt;&lt;e&gt;3&lt;/e&gt;&lt;e&gt;4&lt;/e&gt;}" \
&gt; "${dataf}"
printf '&lt;v/&gt;' | 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()' \
&gt; "${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>&lt;e&gt;1&lt;/e&gt;&lt;e&gt;2&lt;/e&gt;&lt;e&gt;3&lt;/e&gt;&lt;e&gt;4&lt;/e&gt;</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>&lt;a&gt;B&lt;/c&gt;</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="string format-number(number, string, string?) - W3C XSLT 1.0 recommendation"><code>format-number()</code></a>
function.</p>
<pre class="lang-xml"><code>printf '%s\n' '&lt;v&gt;1240057409536&lt;/v&gt;' |
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>$&lt; $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 = &gt;
.PHONY: all
all:
&gt; printf '%s' '&lt;v a="fee" b="fi" c="fo" d="fum"/&gt;' | \
  xmlstarlet select -T -t --var x='*/@*' -v '$$x' -n | \
  paste -s -d '$$ ' -
&gt; 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> | <a href="#error-invalid-expression-pathname">invalid expression:
‘«pathname»’</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 the <strong>root element</strong> (the outermost element aka
the document element) of the first input file 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. <code>select</code> and <code>edit</code> both support multiple
input files.</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&gt;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>
<h4 id="elements-visualize-xml-document-structure" class="shew-tgt">Visualize XML
document structure<a href="#elements-visualize-xml-document-structure" 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>Using <code>awk</code> to indent the output from
<code>elements -u</code>:</p>
<pre class="lang-sh"><code>xmlstarlet elements -u "${infile}" |
awk -v FS='/' -v indent=2 '
{ for ( i = 0; ++i &lt;= NF; )
    if ( i &gt; prevlen || $(i) != prev[i] )
      printf("%*s%s\n",(i-1)*indent,"",$(i))
  prevlen = split($0,prev,FS)
}'</code></pre>
<p>Output:</p>
<pre class="lang-none"><code>xbel
  bookmark
    info
      metadata
        bookmark:applications
          bookmark:application
        bookmark:groups
          bookmark:group
        mime:mime-type</code></pre>
<div class="dinkus3">

</div>
<p>With <a href="https://graphviz.org"><code>graphviz</code></a>
installed use <code>awk</code> and <code>dot</code> to make a
diagram:</p>
<pre class="lang-sh"><code>xmlstarlet elements -u "${infile}" |
awk -F/ 'BEGIN{print "digraph{rankdir=\"TB\";"}END{print "}"}
  NF!=1{printf("\"%s\" -&gt; \"%s\"\n",$(NF-1),$NF)}' |
dot -Tsvg -Nshape=plain -o "${outfile}"</code></pre>
<p><code>TB</code> is for top-bottom, <code>LR</code> left-right;
there’s also <code>BT</code> and <code>RL</code> plus a generous amount
of options.</p>
<div class="svgobject">
<object type="image/svg+xml" data="data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20xmlns:xlink=%22http://www.w3.org/1999/xlink%22%20width=%22453pt%22%20height=%22278pt%22%20viewBox=%220.00%200.00%20452.50%20278.00%22%3E%3Cg%20id=%22graph0%22%20class=%22graph%22%20transform=%22scale(1%201)%20rotate(0)%20translate(4%20274)%22%3E%3Ctitle%3E%253%3C/title%3E%3Cpolygon%20fill=%22white%22%20stroke=%22transparent%22%20points=%22-4,4%20-4,-274%20448.5,-274%20448.5,4%20-4,4%22/%3E%3Cg%20id=%22node1%22%20class=%22node%22%3E%3Ctitle%3Exbel%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-258.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Exbel%3C/text%3E%3C/g%3E%3Cg%20id=%22node2%22%20class=%22node%22%3E%3Ctitle%3Ebookmark%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-207.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Ebookmark%3C/text%3E%3C/g%3E%3Cg%20id=%22edge1%22%20class=%22edge%22%3E%3Ctitle%3Exbel-&amp;gt;bookmark%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M243,-254.69C243,-248.18%20243,-238.1%20243,-229.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22246.5,-229.26%20243,-219.26%20239.5,-229.26%20246.5,-229.26%22/%3E%3C/g%3E%3Cg%20id=%22node3%22%20class=%22node%22%3E%3Ctitle%3Einfo%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-156.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Einfo%3C/text%3E%3C/g%3E%3Cg%20id=%22edge2%22%20class=%22edge%22%3E%3Ctitle%3Ebookmark-&amp;gt;info%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M243,-203.69C243,-197.18%20243,-187.1%20243,-178.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22246.5,-178.26%20243,-168.26%20239.5,-178.26%20246.5,-178.26%22/%3E%3C/g%3E%3Cg%20id=%22node4%22%20class=%22node%22%3E%3Ctitle%3Emetadata%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-105.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Emetadata%3C/text%3E%3C/g%3E%3Cg%20id=%22edge3%22%20class=%22edge%22%3E%3Ctitle%3Einfo-&amp;gt;metadata%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M243,-152.69C243,-146.18%20243,-136.1%20243,-127.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22246.5,-127.26%20243,-117.26%20239.5,-127.26%20246.5,-127.26%22/%3E%3C/g%3E%3Cg%20id=%22node5%22%20class=%22node%22%3E%3Ctitle%3Ebookmark:applications%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%2281%22%20y=%22-54.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Ebookmark:applications%3C/text%3E%3C/g%3E%3Cg%20id=%22edge4%22%20class=%22edge%22%3E%3Ctitle%3Emetadata-&amp;gt;bookmark:applications%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M221.49,-101.99C193.53,-93.54%20144.5,-78.71%20112.38,-68.99%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22113.19,-65.58%20102.6,-66.03%20111.16,-72.28%20113.19,-65.58%22/%3E%3C/g%3E%3Cg%20id=%22node7%22%20class=%22node%22%3E%3Ctitle%3Ebookmark:groups%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-54.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Ebookmark:groups%3C/text%3E%3C/g%3E%3Cg%20id=%22edge6%22%20class=%22edge%22%3E%3Ctitle%3Emetadata-&amp;gt;bookmark:groups%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M243,-101.69C243,-95.18%20243,-85.1%20243,-76.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22246.5,-76.26%20243,-66.26%20239.5,-76.26%20246.5,-76.26%22/%3E%3C/g%3E%3Cg%20id=%22node9%22%20class=%22node%22%3E%3Ctitle%3Emime:mime-type%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22384%22%20y=%22-54.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Emime:mime-type%3C/text%3E%3C/g%3E%3Cg%20id=%22edge8%22%20class=%22edge%22%3E%3Ctitle%3Emetadata-&amp;gt;mime:mime-type%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M261.72,-101.99C285.74,-93.65%20327.63,-79.09%20355.59,-69.37%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22356.9,-72.62%20365.2,-66.03%20354.6,-66.01%20356.9,-72.62%22/%3E%3C/g%3E%3Cg%20id=%22node6%22%20class=%22node%22%3E%3Ctitle%3Ebookmark:application%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%2281%22%20y=%22-3.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Ebookmark:application%3C/text%3E%3C/g%3E%3Cg%20id=%22edge5%22%20class=%22edge%22%3E%3Ctitle%3Ebookmark:applications-&amp;gt;bookmark:application%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M81,-50.69C81,-44.18%2081,-34.1%2081,-25.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%2284.5,-25.26%2081,-15.26%2077.5,-25.26%2084.5,-25.26%22/%3E%3C/g%3E%3Cg%20id=%22node8%22%20class=%22node%22%3E%3Ctitle%3Ebookmark:group%3C/title%3E%3Ctext%20text-anchor=%22middle%22%20x=%22243%22%20y=%22-3.8%22%20font-family=%22Times,serif%22%20font-size=%2214.00%22%3Ebookmark:group%3C/text%3E%3C/g%3E%3Cg%20id=%22edge7%22%20class=%22edge%22%3E%3Ctitle%3Ebookmark:groups-&amp;gt;bookmark:group%3C/title%3E%3Cpath%20fill=%22none%22%20stroke=%22black%22%20d=%22M243,-50.69C243,-44.18%20243,-34.1%20243,-25.43%22/%3E%3Cpolygon%20fill=%22black%22%20stroke=%22black%22%20points=%22246.5,-25.26%20243,-15.26%20239.5,-25.26%20246.5,-25.26%22/%3E%3C/g%3E%3C/g%3E%3C/svg%3E">
</object>
</div>
<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 8 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:sort</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="object system-property(string) - 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&lt;&amp;0 &amp;&amp; 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></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>&lt;xsl-select&gt;</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 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
&lt;v&gt;&lt;w&gt;a&amp;amp;&lt;/w&gt;&lt;w&gt;l&amp;lt;&lt;/w&gt;&lt;w&gt;q&amp;quot;&lt;/w&gt;&lt;w&gt;g&amp;gt;&lt;/w&gt;&lt;/v&gt;
$ :
$ xmlstarlet select -t -c '*/*[position()&gt;2]' -n file.xml
&lt;w&gt;q"&lt;/w&gt;&lt;w&gt;g&amp;gt;&lt;/w&gt;
$ :
$ xmlstarlet select --text -t -c '*/*[position()&lt;3]' -n file.xml
a&amp;l&lt;</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 &gt; 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 &gt; 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>Sets <code>encoding="«encoding»"</code> (e.g. <code>UTF-8</code>,
<code>ISO-8859-2</code>) on the <code>xsl:output</code> element, with <a href="#select-opt-xml-decl"><code>-D (--xml-decl)</code></a> also in the
XML declaration.</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 the root element (see <a href="#global-opt-doc-namespace"><code>--doc-namespace</code></a>) of
the first input file 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="12.1 Multiple Source Documents - 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 '&lt;v/&gt;' | xmlstarlet sel -N foo= -t -e a -e foo:k</code>
outputs <code>&lt;a&gt;&lt;k/&gt;&lt;/a&gt;</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>&lt;xsl:template match="/"&gt;</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>&lt;xsl:template match="pattern"&gt;</code> <em>cannot</em> be
generated by combining <code>-t</code> and <code>-m</code> options.</p>