diff options
Diffstat (limited to 'doc/xmlstarlet-ug.xml')
| -rw-r--r-- | doc/xmlstarlet-ug.xml | 1741 |
1 files changed, 1741 insertions, 0 deletions
diff --git a/doc/xmlstarlet-ug.xml b/doc/xmlstarlet-ug.xml new file mode 100644 index 0000000..95a2baa --- /dev/null +++ b/doc/xmlstarlet-ug.xml @@ -0,0 +1,1741 @@ +<?xml version="1.0" encoding="UTF-8"?> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:db="http://docbook.org/ns/docbook" + version="5.0" + xml:lang="en"> + <title>XmlStarlet Command Line XML Toolkit User's Guide</title> + + <info> + <date>June 17, 2012</date> + + <author> + <personname> + <firstname>Mikhail</firstname> + <surname>Grushinskiy</surname> + </personname> + </author> + </info> + + <chapter> + <title xml:id="s.1">Introduction</title> + + <sect1> + <title xml:id="s.1.1">About XmlStarlet</title> + + <para><link xlink:href="http://xmlstar.sourceforge.net/">XMLStarlet</link> is + a set of command line utilities (tools) which can be used to transform, + query, validate, and edit XML documents and files using simple set of + shell commands in similar way it is done for plain text files using UNIX + grep, sed, awk, diff, patch, join, etc commands.</para> + + <para>This set of command line utilities can be used by those who deal + with many XML documents on UNIX shell command prompt as well as for + automated XML processing with shell scripts.</para> + + <para>XMLStarlet command line utility is written in C and uses libxml2 + and libxslt from <link + xlink:href="http://xmlsoft.org/">http://xmlsoft.org/</link>. Implementation of + extensive choice of options for XMLStarlet utility was only possible + because of rich feature set of libxml2 and libxslt (many thanks to the + developers of those libraries for great work).</para> + + <para>'diff' and 'patch' options are not currently implemented. Other + features need some work too. Please, send an email to the project + administrator (see <link + xlink:href="http://sourceforge.net/projects/xmlstar/">http://sourceforge.net/projects/xmlstar/</link>) + if you wish to help.</para> + + <para>XMLStarlet is linked statically to both libxml2 and libxslt, so + generally all you need to process XML documents is one executable file. + To run XmlStarlet utility you can simple type '<phrase role="PROG"/>' on command line and + see list of options available.</para> + + <para>XMLStarlet is open source freeware under MIT license which allows + free use and distribution for both commercial and non-commercial + projects.</para> + + <para>We welcome any user's feedback on this project which would greatly + help us to improve its quality. Comments, suggestions, feature requests, + bug reports can be done via SourceForge project web site (see <link + xlink:href="http://sourceforge.net/forum/?group_id=66612">XMLStarlet + Sourceforge forums</link>, or <link + xlink:href="http://lists.sourceforge.net/lists/listinfo/xmlstar-devel/">XMLStarlet + mailing list</link>)</para> + </sect1> + + <sect1> + <title xml:id="s.1.2">Main Features</title> + + <para>The toolkit's feature set includes options to:</para> + + <itemizedlist> + <listitem> + <para>Check or validate XML files (simple well-formedness check, + DTD, XSD, RelaxNG)</para> + </listitem> + + <listitem> + <para>Calculate values of XPath expressions on XML files (such as + running sums, etc)</para> + </listitem> + + <listitem> + <para>Search XML files for matches to given XPath expressions</para> + </listitem> + + <listitem> + <para>Apply XSLT stylesheets to XML documents (including EXSLT + support, and passing parameters to stylesheets)</para> + </listitem> + + <listitem> + <para>Query XML documents (ex. query for value of some elements of + attributes, sorting, etc)</para> + </listitem> + + <listitem> + <para>Modify or edit XML documents (ex. delete some elements)</para> + </listitem> + + <listitem> + <para>Format or "beautify" XML documents (as changing indentation, + etc)</para> + </listitem> + + <listitem> + <para>Fetch XML documents using http:// or ftp:// URLs</para> + </listitem> + + <listitem> + <para>Browse tree structure of XML documents (in similar way to 'ls' + command for directories)</para> + </listitem> + + <listitem> + <para>Include one XML document into another using XInclude</para> + </listitem> + + <listitem> + <para>XML c14n canonicalization</para> + </listitem> + + <listitem> + <para>Escape/unescape special XML characters in input text</para> + </listitem> + + <listitem> + <para>Print directory as XML document</para> + </listitem> + + <listitem> + <para>Convert XML into PYX format (based on ESIS - ISO 8879), and + vice versa</para> + </listitem> + </itemizedlist> + + <para></para> + </sect1> + + <sect1> + <title xml:id="s.1.3">Supported Platforms</title> + + <para>Here is a list of platforms on which XmlStarlet is known to + work.</para> + + <itemizedlist> + <listitem> + <para>Linux</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>Solaris</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>Windows</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>MacOS X</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>FreeBSD/NetBSD</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>HP-UX</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>AIX</para> + </listitem> + </itemizedlist> + + <para>You might be able to compile and make it on others too.</para> + </sect1> + + <sect1> + <title xml:id="s.1.4">Finding binary packages</title> + + <para>Here is a list of sites where you can also find XmlStarlet binary + packages.</para> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://www.suse.com/us/private/products/suse_linux/prof/packages_professional/xmlstarlet.html">SuSE + Packages</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=%2FUtilities%2Fxmlstarlet/">SuSE + Guru's RPM Site</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://www.freebsd.org/cgi/ports.cgi?query=xmlstarlet&stype=all">FreeBSD + Ports</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://www.freshports.org/textproc/xmlstarlet/">FreeBSD Fresh + Ports</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://fink.sourceforge.net/pdb/package.php/xmlstarlet">Mac OS + Fink</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://rpms.mandrakeclub.com/linux/rpm2html/search.php?query=xmlstarlet">Mandrake + RPMs</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://gentoo-portage.com/app-text/xmlstarlet">Gentoo + Portage</link></para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://packages.debian.org/stable/text/xmlstarlet">Debian</link></para> + </listitem> + </itemizedlist> + </sect1> + </chapter> + + <chapter> + <title xml:id="s.2">Installation</title> + + <sect1> + <title xml:id="s.2.1">Installation on Linux</title> + + <para>Execute the following command as root<programlisting>rpm -i xmlstarlet-x.x.x-1.i386.rpm</programlisting></para> + + <para>where x.x.x indicates package version.</para> + + <para>You can use <link + xlink:href="http://fr2.rpmfind.net/linux/rpm2html/search.php?query=xmlstarlet&system=&arch=">http://rpmfind.net</link> + to search for RPM appropriate for your distribution.</para> + </sect1> + + <sect1> + <title xml:id="s.2.2">Installation on Solaris</title> + + <para>Execute the following commands as root<programlisting>gunzip xmlstarlet-x.x.x-sol8-sparc-local.gz +pkgadd -d xmlstarlet-x.x.x-sol8-sparc-local all</programlisting></para> + </sect1> + + <sect1> + <title xml:id="s.2.3">Installation on MacOS X</title> + + <para>XmlStarlet is available on MacOS in Fink. <link + xlink:href="http://fink.sourceforge.net/pdb/package.php/xmlstarlet">See + fink.sourceforge.net</link></para> + </sect1> + + <sect1> + <title xml:id="s.2.4">Installation on Windows</title> + + <para>Unzip the file xmlstarlet-x.x.x-win32.zip to some directory. To + take advantage of UNIX shell scripting you might want to run XmlStarlet + from Cygwin. Consider installing <link + xlink:href="http://www.cygwin.com/">Cygwin</link> on your Windows + machine.</para> + </sect1> + </chapter> + + <chapter> + <title xml:id="s.3">Getting Started</title> + + <sect1> + <title xml:id="s.3.1">Basic Command-Line Options</title> + + <para>Basic command line syntax: <programlisting>bash-2.03$ <phrase role="PROG"/> +XMLStarlet Toolkit: Command line utilities for XML +Usage: <phrase role="PROG"/> [<options>] <command> [<cmd-options>] +where <command> is one of: + ed (or edit) - Edit/Update XML document(s) + sel (or select) - Select data or query XML document(s) (XPATH, etc) + tr (or transform) - Transform XML document(s) using XSLT + val (or validate) - Validate XML document(s) (well-formed/DTD/XSD/RelaxNG) + fo (or format) - Format XML document(s) + el (or elements) - Display element structure of XML document + c14n (or canonic) - XML canonicalization + ls (or list) - List directory as XML + esc (or escape) - Escape special XML characters + unesc (or unescape) - Unescape special XML characters + pyx (or xmln) - Convert XML into PYX format (based on ESIS - ISO 8879) + p2x (or depyx) - Convert PYX into XML +<options> are: + --version - show version + --help - show help +Wherever file name mentioned in command help it is assumed +that URL can be used instead as well. + +Type: <phrase role="PROG"/> <command> --help <ENTER> for command help + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/)</programlisting></para> + </sect1> + + <sect1> + <title xml:id="s.3.2">Studying Structure of XML Document</title> + + <para>Before you do anything with your XML document you probably would + like to know its structure at first. 'el' option could be used for this + purpose.</para> + + <para>Let's say you have the following XML document (table.xml)</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + </rec> + <rec id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml></programlisting> + + <programlisting><phrase role="PROG"/> el table.xml</programlisting> + + <para>would produce the following output.</para> + + <programlisting>xml +xml/table +xml/table/rec +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec +xml/table/rec/numField +xml/table/rec/stringField</programlisting> + + <para>Every line in this output is an XPath expression which indicates a + 'path' to elements in XML document. You would use these XPath + expressions to navigate through your XML documents in other XmlStarlet + options.</para> + + <para>XML documents can be pretty large but with a very simple + structure. (This is espesially true for data driven XML documents ex: + XML formatted result of select from SQL table). If you just interested + in structure but not order of the elements you can use -u switch + combined with 'el' option.</para> + + <para>EXAMPLE:</para> + + <programlisting><phrase role="PROG"/> el -u table.xml</programlisting> + + <para>Output:</para> + + <programlisting>xml +xml/table +xml/table/rec +xml/table/rec/numField +xml/table/rec/stringField</programlisting> + + <para>If you are interested not just in elements of your XML document, + but you want to see attributes as well you can use -a switch with 'el' + option. And every line of the output will still be a valid XPath + expression.</para> + + <para>EXAMPLE:</para> + + <programlisting><phrase role="PROG"/> el -a table.xml</programlisting> + + <para>Output:</para> + + <programlisting>xml +xml/table +xml/table/rec +xml/table/rec/@id +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec +xml/table/rec/@id +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec +xml/table/rec/@id +xml/table/rec/numField +xml/table/rec/stringField</programlisting> + + <para>If you are looking for attribute values as well use -v switch of + 'el' option. And again - every line of output is a valid XPath + expression.</para> + + <para>EXAMPLE:</para> + + <programlisting><phrase role="PROG"/> el -v table.xml</programlisting> + + <para>Output:</para> + + <programlisting>xml +xml/table +xml/table/rec[@id='1'] +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec[@id='2'] +xml/table/rec/numField +xml/table/rec/stringField +xml/table/rec[@id='3'] +xml/table/rec/numField +xml/table/rec/stringField</programlisting> + </sect1> + </chapter> + + <chapter> + <title>XmlStarlet Reference</title> + + <para></para> + + <sect1> + <title>Querying XML documents</title> + + <para>XmlStarlet 'select' or 'sel' option can be used to query or search + XML documents. Here is synopsis for '<phrase role="PROG"/> sel' command:</para> + + <programlisting>XMLStarlet Toolkit: Select from XML document(s) +Usage: <phrase role="PROG"/> sel <global-options> {<template>} [ <xml-file> ... ] +where + <global-options> - global options for selecting + <xml-file> - input XML document file name/uri (stdin is used if missing) + <template> - template for querying XML document with following syntax: + +<global-options> are: + -C or --comp - display generated XSLT + -R or --root - print root element <xsl-select> + -T or --text - output is text (default is XML) + -I or --indent - indent output + -D or --xml-decl - do not omit xml declaration line + -B or --noblanks - remove insignificant spaces from XML tree + -N <name>=<value> - predefine namespaces (name without 'xmlns:') + ex: xsql=urn:oracle-xsql + Multiple -N options are allowed. + --net - allow fetch DTDs or entities over network + --help - display help + +Syntax for templates: -t|--template <options> +where <options> + -c or --copy-of <xpath> - print copy of XPATH expression + -v or --value-of <xpath> - print value of XPATH expression + -o or --output <string> - output string literal + -n or --nl - print new line + -f or --inp-name - print input file name (or URL) + -m or --match <xpath> - match XPATH expression + -i or --if <test-xpath> - check condition <xsl:if test="test-xpath"> + -e or --elem <name> - print out element <xsl:element name="name"> + -a or --attr <name> - add attribute <xsl:attribute name="name"> + -b or --break - break nesting + -s or --sort op xpath - sort in order (used after -m) where + op is X:Y:Z, + X is A - for order="ascending" + X is D - for order="descending" + Y is N - for data-type="numeric" + Y is T - for data-type="text" + Z is U - for case-order="upper-first" + Z is L - for case-order="lower-first" + +There can be multiple --match, --copy-of, --value-of, etc options +in a single template. The effect of applying command line templates +can be illustrated with the following XSLT analogue + +<phrase role="PROG"/> sel -t -c "xpath0" -m "xpath1" -m "xpath2" -v "xpath3" \ + -t -m "xpath4" -c "xpath5" + +is equivalent to applying the following XSLT + +<?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:template match="/"> + <xsl:call-template name="t1"/> + <xsl:call-template name="t2"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:copy-of select="xpath0"/> + <xsl:for-each select="xpath1"> + <xsl:for-each select="xpath2"> + <xsl:value-of select="xpath3"/> + </xsl:for-each> + </xsl:for-each> +</xsl:template> +<xsl:template name="t2"> + <xsl:for-each select="xpath4"> + <xsl:copy-of select="xpath5"/> + </xsl:for-each> +</xsl:template> +</xsl:stylesheet> + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) + +Current implementation uses libxslt from GNOME codebase as XSLT processor +(see http://xmlsoft.org/ for more details) +</programlisting> + + <para>'select' option allows you basically avoid writting XSLT + stylesheet to perform some queries on XML documents. I.e. various + combinations of command line parameters will let you to generate XSLT + stylesheet and apply in to XML documents with a single command line. + Very often you do not really care what XSLT was created for you 'select' + command, but in those cases when you do; you can always use -C or --comp + switch which will let you see exactly which XSLT is applied to your + input.</para> + + <para>'select' option supports many EXSLT functions in XPath + expressions.</para> + + <para>Here are few examples which will help to understand how '<phrase role="PROG"/> + select' works:</para> + + <para>EXAMPLE:</para> + + <para>Count elements matching XPath expression:</para> + + <para></para> + + <programlisting><phrase role="PROG"/> sel -t -v "count(/xml/table/rec/numField)" table.xml</programlisting> + + <para>Input (table.xml):</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + </rec> + <rec id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml></programlisting> + + <para>Output:</para> + + <programlisting>3 +</programlisting> + + <para>Let's take a close look what it did internally. For that we will + use '-C' option</para> + + <programlisting>$ <phrase role="PROG"/> sel -C -t -v "count(/xml/table/rec/numField)" +<?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exslt="http://exslt.org/common" + xmlns:math="http://exslt.org/math" + xmlns:date="http://exslt.org/dates-and-times" + xmlns:func="http://exslt.org/functions" + xmlns:set="http://exslt.org/sets" + xmlns:str="http://exslt.org/strings" + xmlns:dyn="http://exslt.org/dynamic" + xmlns:saxon="http://icl.com/saxon" + xmlns:xalanredirect="org.apache.xalan.xslt.extensions.Redirect" + xmlns:xt="http://www.jclark.com/xt" + xmlns:libxslt="http://xmlsoft.org/XSLT/namespace" + xmlns:test="http://xmlsoft.org/XSLT/" + extension-element-prefixes= + "exslt math date func set str dyn saxon xalanredirect xt libxslt test" + exclude-result-prefixes="math str"> +<xsl:output omit-xml-declaration="yes" indent="no"/> +<xsl:param name="inputFile">-</xsl:param> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:value-of select="count(/xml/table/rec/numField)"/> +</xsl:template> +</xsl:stylesheet></programlisting> + + <para>Ignoring some XSLT stuff to make it brief:</para> + + <programlisting><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output omit-xml-declaration="yes" indent="no"/> +<xsl:param name="inputFile">-</xsl:param> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:value-of select="count(/xml/table/rec/numField)"/> +</xsl:template> +</xsl:stylesheet></programlisting> + + <para>Every -t option is mapped into XSLT template. Options after '-t' + are mapped into XSLT elements:</para> + + <itemizedlist> + <listitem> + <para>-v to <xsl:value-of></para> + </listitem> + + <listitem> + <para>-c to <xsl:copy-of></para> + </listitem> + + <listitem> + <para>-e to <xsl:element></para> + </listitem> + + <listitem> + <para>-a to <xsl:attribute></para> + </listitem> + + <listitem> + <para>-s to <xsl:sort></para> + </listitem> + + <listitem> + <para>-m to <xsl:for-each></para> + </listitem> + + <listitem> + <para>-i to <xsl:if></para> + </listitem> + + <listitem> + <para>and so on</para> + </listitem> + </itemizedlist> + + <para>By default subsequent options (for instance: -m) will result in + nested corresponding XSLT elements (<xsl:for-each> for '-m'). To + break this nesting you would have to put '-b' or '--break' after first + '-m'.</para> + + <para>Below are few more examples:</para> + + <para>EXAMPLE</para> + + <para>Count all nodes in XML documents. Print input name and node count + after it.</para> + + <programlisting><phrase role="PROG"/> sel -t -f -o " " -v "count(//node())" xml/table.xml xml/tab-obj.xml</programlisting> + + <para>Output:</para> + + <programlisting>xml/table.xml 32 +xml/tab-obj.xml 41</programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Find XML files matching XPath expression (containing 'object' + element)</para> + + <programlisting><phrase role="PROG"/> sel -t -m //object -f xml/table.xml xml/tab-obj.xml</programlisting> + + <para>Result output:</para> + + <programlisting>xml/tab-obj.xml</programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Calculate EXSLT (XSLT extentions) XPath value</para> + + <programlisting>echo "<x/>" | <phrase role="PROG"/> sel -t -v "math:abs(-1000)"</programlisting> + + <para>Result output:</para> + + <programlisting>1000</programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Adding elements and attributes using command line '<phrase role="PROG"/> sel'</para> + + <programlisting>echo "<x/>" | <phrase role="PROG"/> sel -t -m / -e xml -e child -a data -o value</programlisting> + + <para>Result Output:</para> + + <programlisting><xml><child data="value"/></xml></programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Query XML document and produce sorted text table</para> + + <programlisting><phrase role="PROG"/> sel -T -t -m /xml/table/rec -s D:N:- "@id" \ + -v "concat(@id,'|',numField,'|',stringField)" -n xml/table.xml</programlisting> + + <para>Result Output:</para> + + <programlisting>3|-23|stringValue +2|346|Text Value +1|123|String Value</programlisting> + + <para>Equivalent stylesheet</para> + + <programlisting><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output omit-xml-declaration="yes" indent="no" method="text"/> +<xsl:param name="inputFile">-</xsl:param> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:for-each select="/xml/table/rec"> + <xsl:sort order="descending" data-type="number" + case-order="upper-first" select="@id"/> + <xsl:value-of select="concat(@id,'|',numField,'|',stringField)"/> + <xsl:value-of select="'&#10;'"/> + </xsl:for-each> +</xsl:template> +</xsl:stylesheet></programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Predefine namespaces for XPath expressions</para> + + <programlisting><phrase role="PROG"/> sel -N xsql=urn:oracle-xsql -t -v /xsql:query xsql/jobserve.xsql</programlisting> + + <para>Input (xsql/jobserve.xsql)</para> + + <programlisting>$ cat xsql/jobserve.xsql +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="jobserve.xsl"?> +<xsql:query connection="jobs" xmlns:xsql="urn:oracle-xsql" max-rows="5"> + SELECT substr(title,1,26) short_title, title, location, skills + FROM job + WHERE UPPER(title) LIKE '%ORACLE%' + ORDER BY first_posted DESC +</xsql:query></programlisting> + + <para>Result output</para> + + <programlisting> SELECT substr(title,1,26) short_title, title, location, skills + FROM job + WHERE UPPER(title) LIKE '%ORACLE%' + ORDER BY first_posted DESC +</programlisting> + + <para></para> + + <para>EXAMPLE</para> + + <para>Print structure of XML element using <phrase role="PROG"/> sel (advanced XPath + expressions and <phrase role="PROG"/> sel command usage)</para> + + <programlisting><phrase role="PROG"/> sel -T -t -m '//*' \ +-m 'ancestor-or-self::*' -v 'name()' -i 'not(position()=last())' -o . -b -b -n \ +xml/structure.xml</programlisting> + + <para>Input (xml/structure.xml)</para> + + <programlisting><a1> + <a11> + <a111> + <a1111/> + </a111> + <a112> + <a1121/> + </a112> + </a11> + <a12/> + <a13> + <a131/> + </a13> +</a1></programlisting> + + <para>Result Output:</para> + + <programlisting>a1 +a1.a11 +a1.a11.a111 +a1.a11.a111.a1111 +a1.a11.a112 +a1.a11.a112.a1121 +a1.a12 +a1.a13 +a1.a13.a131</programlisting> + + <para>This example is a good demonstration of nesting control. Here is + corresponding XSLT:</para> + + <programlisting><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output omit-xml-declaration="yes" indent="no" method="text"/> +<xsl:param name="inputFile">-</xsl:param> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:for-each select="//*"> + <xsl:for-each select="ancestor-or-self::*"> + <xsl:value-of select="name()"/> + <xsl:if test="not(position()=last())"> + <xsl:value-of select="'.'"/> + </xsl:if> + </xsl:for-each> + <xsl:value-of select="'&#10;'"/> + </xsl:for-each> +</xsl:template> +</xsl:stylesheet></programlisting> + + <para></para> + + <para></para> + + <para>EXAMPLE</para> + + <para>Print all links of xhtml document</para> + + <programlisting><phrase role="PROG"/> sel --net --html -T -t -m "//*[local-name()='a']" \ + -o 'NAME: ' -v "translate(. , '&#10;', ' ')" -n \ + -o 'LINK: ' -v @href -n -n \ + http://xmlstar.sourceforge.net/</programlisting> + + <para>Sample output</para> + + <programlisting>NAME: XmlStarlet SourceForge Site +LINK: http://sourceforge.net/projects/xmlstar/ + +NAME: XmlStarlet CVS Source +LINK: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/xmlstar/ + +NAME: XmlStarlet on Freshmeat.Net +LINK: http://freshmeat.net/projects/xmlstarlet/ + +NAME: XMLStarlet Sourceforge forums +LINK: http://sourceforge.net/forum/?group_id=66612 + +NAME: XMLStarlet mailing list +LINK: http://lists.sourceforge.net/lists/listinfo/xmlstar-devel +</programlisting> + + <para></para> + </sect1> + + <sect1> + <title>Transforming XML documents</title> + + <para>Here is synopsis for '<phrase role="PROG"/> tr' command:</para> + + <programlisting>XMLStarlet Toolkit: Transform XML document(s) using XSLT +Usage: <phrase role="PROG"/> tr [<options>] <xsl-file> {-p|-s <name>=<value>} [ <xml-file-or-uri> ... ] +where + <xsl-file> - main XSLT stylesheet for transformation + <xml-file> - input XML document file name (stdin is used if missing) + <name>=<value> - name and value of the parameter passed to XSLT processor + -p - parameter is XPATH expression ("'string'" to quote string) + -s - parameter is a string literal +<options> are: + --omit-decl - omit xml declaration <?xml version="1.0"?> + --show-ext - show list of extensions + --val - allow validate against DTDs or schemas + --net - allow fetch DTDs or entities over network + --xinclude - do XInclude processing on document input + --maxdepth val - increase the maximum depth + --html - input document(s) is(are) in HTML format + --catalogs - use SGML catalogs from $SGML_CATALOG_FILES + otherwise XML catalogs starting from + file:///etc/xml/catalog are activated by default + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) + +Current implementation uses libxslt from GNOME codebase as XSLT processor +(see http://xmlsoft.org/ for more details) +</programlisting> + + <para>EXAMPLE:</para> + + <programlisting># Transform passing parameters to XSLT stylesheet +<phrase role="PROG"/> tr xsl/param1.xsl -p Count='count(/xml/table/rec)' -s Text="Count=" xml/table.xml +</programlisting> + + <para>Input xsl/params1.xsl</para> + + <programlisting><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output method="text"/> +<xsl:param name="Text"/> +<xsl:param name="Count"/> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:for-each select="/xml"> + <xsl:value-of select="$Text"/> + <xsl:value-of select="$Count"/> + <xsl:value-of select="'&#10;'"/> + </xsl:for-each> +</xsl:template> +</xsl:stylesheet></programlisting> + + <para>Output</para> + + <programlisting>Count=3 +</programlisting> + </sect1> + + <sect1> + <title>Editing XML documents</title> + + <para>Here is the synopsis for '<phrase role="PROG"/> ed' command:</para> + + <programlisting>XMLStarlet Toolkit: Edit XML document(s) +Usage: <phrase role="PROG"/> ed <global-options> {<action>} [ <xml-file-or-uri> ... ] +where + <global-options> - global options for editing + <xml-file-or-uri> - input XML document file name/uri (stdin is used if missing) + +<global-options> are: + -P (or --pf) - preserve original formatting + -S (or --ps) - preserve non-significant spaces + -O (or --omit-decl) - omit XML declaration (<?xml ...?>) + -N <name>=<value> - predefine namespaces (name without 'xmlns:') + ex: xsql=urn:oracle-xsql + Multiple -N options are allowed. + -N options must be last global options. + --help or -h - display help + +where <action> + -d or --delete <xpath> + -i or --insert <xpath> -t (--type) elem|text|attr -n <name> -v (--value) <value> + -a or --append <xpath> -t (--type) elem|text|attr -n <name> -v (--value) <value> + -s or --subnode <xpath> -t (--type) elem|text|attr -n <name> -v (--value) <value> + -m or --move <xpath1> <xpath2> + -r or --rename <xpath1> -v <new-name> + -u or --update <xpath> -v (--value) <value> + -x (--expr) <xpath> (-x is not implemented yet) + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE:</para> + + <programlisting># Delete elements matching XPath expression +<phrase role="PROG"/> ed -d "/xml/table/rec[@id='2']" xml/table.xml +</programlisting> + + <para>Input</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + </rec> + <rec id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml> +</programlisting> + + <para>Output</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + </rec> + <rec id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Move element node +echo '<x id="1"><a/><b/></x>' | <phrase role="PROG"/> ed -m "//b" "//a" +</programlisting> + + <para>Output</para> + + <programlisting><x id="1"> + <a> + <b/> + </a> +</x> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Rename attributes +<phrase role="PROG"/> ed -r "//*/@id" -v ID xml/tab-obj.xml +</programlisting> + + <para>Output:</para> + + <programlisting><xml> + <table> + <rec ID="1"> + <numField>123</numField> + <stringField>String Value</stringField> + <object name="Obj1"> + <property name="size">10</property> + <property name="type">Data</property> + </object> + </rec> + <rec ID="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec ID="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Rename elements +<phrase role="PROG"/> ed -r "/xml/table/rec" -v record xml/tab-obj.xml +</programlisting> + + <para>Output:</para> + + <programlisting><xml> + <table> + <record id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + <object name="Obj1"> + <property name="size">10</property> + <property name="type">Data</property> + </object> + </record> + <record id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </record> + <record id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </record> + </table> +</xml> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Update value of an attribute +<phrase role="PROG"/> ed -u "/xml/table/rec[@id=3]/@id" -v 5 xml/tab-obj.xml +</programlisting> + + <para>Output:</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>123</numField> + <stringField>String Value</stringField> + <object name="Obj1"> + <property name="size">10</property> + <property name="type">Data</property> + </object> + </rec> + <rec id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec id="5"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Update value of an element +<phrase role="PROG"/> ed -u "/xml/table/rec[@id=1]/numField" -v 0 xml/tab-obj.xml +</programlisting> + + <para>Output:</para> + + <programlisting><xml> + <table> + <rec id="1"> + <numField>0</numField> + <stringField>String Value</stringField> + <object name="Obj1"> + <property name="size">10</property> + <property name="type">Data</property> + </object> + </rec> + <rec id="2"> + <numField>346</numField> + <stringField>Text Value</stringField> + </rec> + <rec id="3"> + <numField>-23</numField> + <stringField>stringValue</stringField> + </rec> + </table> +</xml> +</programlisting> + </sect1> + + <sect1> + <title>Validating XML documents</title> + + <para>Here is synopsis for '<phrase role="PROG"/> val' command:</para> + + <programlisting>XMLStarlet Toolkit: Validate XML document(s) +Usage: <phrase role="PROG"/> val <options> [ <xml-file-or-uri> ... ] +where <options> + -w or --well-formed - validate well-formedness only (default) + -d or --dtd <dtd-file> - validate against DTD + -s or --xsd <xsd-file> - validate against XSD schema + -r or --relaxng <rng-file> - validate against Relax-NG schema + -e or --err - print verbose error messages on stderr + -b or --list-bad - list only files which do not validate + -g or --list-good - list only files which validate + -q or --quiet - do not list files (return result code only) + +NOTE: XML Schemas are not fully supported yet due to its incomplete + support in libxml (see http://xmlsoft.org) + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Validate XML document against DTD +<phrase role="PROG"/> val --dtd dtd/table.dtd xml/tab-obj.xml >/dev/null 2>&1; echo $? +</programlisting> + + <para>Output:</para> + + <programlisting>1 +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Validate against XSD schema +<phrase role="PROG"/> val -b -s xsd/table.xsd xml/table.xml xml/tab-obj.xml 2>/dev/null; echo $? +</programlisting> + + <para>Output:</para> + + <programlisting>xml/tab-obj.xml +1 +</programlisting> + </sect1> + + <sect1> + <title>Formatting XML documents</title> + + <para>Here is synopsis for '<phrase role="PROG"/> fo' command:</para> + + <programlisting>XMLStarlet Toolkit: Format XML document +Usage: <phrase role="PROG"/> fo [<options>] <xml-file> +where <options> are + -n or --noindent - do not indent + -t or --indent-tab - indent output with tabulation + -s or --indent-spaces <num> - indent output with <num> spaces + -o or --omit-decl - omit xml declaration <?xml version="1.0"?> + -R or --recover - try to recover what is parsable + -D or --dropdtd - remove the DOCTYPE of the input docs + -C or --nocdata - replace cdata section with text nodes + -N or --nsclean - remove redundant namespace declarations + -e or --encode <encoding> - output in the given encoding (utf-8, unicode...) + -H or --html - input is HTML + -h or --help - print help + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Format XML document disabling indent +cat xml/tab-obj.xml | <phrase role="PROG"/> fo --noindent +</programlisting> + + <para>Output:</para> + + <programlisting><xml> +<table> +<rec id="1"> +<numField>123</numField> +<stringField>String Value</stringField> +<object name="Obj1"> +<property name="size">10</property> +<property name="type">Data</property> +</object> +</rec> +<rec id="2"> +<numField>346</numField> +<stringField>Text Value</stringField> +</rec> +<rec id="3"> +<numField>-23</numField> +<stringField>stringValue</stringField> +</rec> +</table> +</xml> +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Recover malformed XML document +<phrase role="PROG"/> fo -R xml/malformed.xml 2>/dev/null +</programlisting> + + <para>Input:</para> + + <programlisting><test_output> + <test_name>foo</testname> + <subtest>...</subtest> +</test_output> +</programlisting> + + <para>Output:</para> + + <programlisting><test_output> + <test_name>foo</test_name> + <subtest>...</subtest> +</test_output> +</programlisting> + </sect1> + + <sect1> + <title>Canonicalization of XML documents</title> + + <para>Here is synopsis for '<phrase role="PROG"/> c14n' command:</para> + + <programlisting>XMLStarlet Toolkit: XML canonicalization +Usage: <phrase role="PROG"/> c14n <mode> <xml-file> [<xpath-file>] [<inclusive-ns-list>] +where + <xml-file> - input XML document file name (stdin is used if '-') + <xpath-file> - XML file containing XPath expression for + c14n XML canonicalization + Example: + <?xml version="1.0"?> + <XPath xmlns:n0="http://a.example.com" xmlns:n1="http://b.example"> + (//. | //@* | //namespace::*)[ancestor-or-self::n1:elem1] + </XPath> + + <inclusive-ns-list> - the list of inclusive namespace prefixes + (only for exclusive canonicalization) + Example: 'n1 n2' + + <mode> is one of following: + --with-comments XML file canonicalization w comments (default) + --without-comments XML file canonicalization w/o comments + --exc-with-comments Exclusive XML file canonicalization w comments + --exc-without-comments Exclusive XML file canonicalization w/o comments + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># XML canonicalization +<phrase role="PROG"/> c14n --with-comments ../examples/xml/structure.xml ; echo $? +</programlisting> + + <para>Input ../examples/xml/structure.xml</para> + + <programlisting><a1> + <a11> + <a111> + <a1111/> + </a111> + <a112> + <a1121/> + </a112> + </a11> + <a12/> + <a13> + <a131/> + </a13> +</a1></programlisting> + + <para>Output</para> + + <programlisting><a1> + <a11> + <a111> + <a1111></a1111> + </a111> + <a112> + <a1121></a1121> + </a112> + </a11> + <a12></a12> + <a13> + <a131></a131> + </a13> +</a1> +0 +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># XML exclusive canonicalization +<phrase role="PROG"/> c14n --exc-with-comments ../examples/xml/c14n.xml ../examples/xml/c14n.xpath +</programlisting> + + <para>Input</para> + + <programlisting>../examples/xml/c14n.xml + +<n0:pdu xmlns:n0='http://a.example.com'> +<n1:elem1 xmlns:n1='http://b.example'> +content +</n1:elem1> +</n0:pdu> + +../examples/xml/c14n.xpath + +<XPath xmlns:n0="http://a.example.com" xmlns:n1="http://b.example"> +(//. | //@* | //namespace::*)[ancestor-or-self::n1:elem1] +</XPath> + +</programlisting> + + <para>Output</para> + + <programlisting><n1:elem1 xmlns:n1="http://b.example"> +content +</n1:elem1> +</programlisting> + </sect1> + + <sect1> + <title>XML and PYX format</title> + + <para>Here is synopsis for '<phrase role="PROG"/> pyx' command:</para> + + <programlisting>XMLStarlet Toolkit: Convert XML into PYX format (based on ESIS - ISO 8879) +Usage: <phrase role="PROG"/> pyx {<xml-file>} +where + <xml-file> - input XML document file name (stdin is used if missing) + +The PYX format is a line-oriented representation of +XML documents that is derived from the SGML ESIS format. +(see ESIS - ISO 8879 Element Structure Information Set spec, +ISO/IEC JTC1/SC18/WG8 N931 (ESIS)) + +A non-validating, ESIS generating tool originally developed for +pyxie project (see http://pyxie.sourceforge.net/) +ESIS Generation by Sean Mc Grath http://www.digitome.com/sean.html + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting><phrase role="PROG"/> pyx input.xml +</programlisting> + + <para>Input (input.xml)</para> + + <programlisting><books> +<book type='hardback'> +<title>Atlas Shrugged</title> +<author>Ayn Rand</author> +<isbn id='1'>0525934189</isbn> +</book> +</books></programlisting> + + <para>Output</para> + + <programlisting>(books +-\n +(book +Atype hardback +-\n +(title +-Atlas Shrugged +)title +-\n +(author +-Ayn Rand +)author +-\n +(isbn +Aid 1 +-0525934189 +)isbn +-\n +)book +-\n +)books</programlisting> + + <para>PYX is a line oriented format for XML files which can be helpful + (and very efficient) when used in combination with regular line oriented + UNIX command such as sed, grep, awk.</para> + + <para>'depyx' option is used for conversion back from PYX into + XML.</para> + + <para>EXAMPLE (Delete all attributes). This should work really fast for + very large XML documents.</para> + + <programlisting><phrase role="PROG"/> pyx input.xml | grep -v "^A" | <phrase role="PROG"/> depyx</programlisting> + + <para>Output</para> + + <programlisting><books> +<book> +<title>Atlas Shrugged</title> +<author>Ayn Rand</author> +<isbn>0525934189</isbn> +</book> +</books></programlisting> + + <para>Here is an article which describes how PYX format can be used to + grep XML. <link + xlink:href="http://www-106.ibm.com/developerworks/xml/library/x-matters17.html">http://www-106.ibm.com/developerworks/xml/library/x-matters17.html</link></para> + </sect1> + + <sect1> + <title>Escape/Unescape special XML characters</title> + + <para>Here is synopsis for '<phrase role="PROG"/> esc' command:</para> + + <programlisting><phrase role="PROG"/> esc --help +XMLStarlet Toolkit: Escape special XML characters +Usage: <phrase role="PROG"/> esc [<options>] [<string>] +where <options> are + --help - print usage + (TODO: more to be added in future) +if <string> is missing stdin is used instead. + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting># Escape special XML characters +cat xml/structure.xml | <phrase role="PROG"/> esc +</programlisting> + + <para>Input</para> + + <programlisting><a1> + <a11> + <a111> + <a1111/> + </a111> + <a112> + <a1121/> + </a112> + </a11> + <a12/> + <a13> + <a131/> + </a13> +</a1></programlisting> + + <para>Output</para> + + <programlisting>&lt;a1&gt; + &lt;a11&gt; + &lt;a111&gt; + &lt;a1111/&gt; + &lt;/a111&gt; + &lt;a112&gt; + &lt;a1121/&gt; + &lt;/a112&gt; + &lt;/a11&gt; + &lt;a12/&gt; + &lt;a13&gt; + &lt;a131/&gt; + &lt;/a13&gt; +&lt;/a1&gt; +</programlisting> + </sect1> + + <sect1> + <title>List directory as XML</title> + + <para>Here is synopsis for '<phrase role="PROG"/> ls' command:</para> + + <programlisting>XMLStarlet Toolkit: List directory as XML +Usage: <phrase role="PROG"/> ls +Lists current directory in XML format. + +XMLStarlet is a command line toolkit to query/edit/check/transform +XML documents (for more information see http://xmlstar.sourceforge.net/) +</programlisting> + + <para>EXAMPLE</para> + + <programlisting><phrase role="PROG"/> ls +</programlisting> + + <para>Output</para> + + <programlisting><xml> +<d p="rwxrwxrwx" a="20050107T050740Z" m="20050107T050740Z" s="0" n="old-resume"/> +<f p="rw-rw-rw-" a="20050107T045941Z" m="20050107T045941Z" s="12" n="resume.2old"/> +<f p="rw-rw-rw-" a="20050107T045924Z" m="20050107T045924Z" s="81" n="resume.xml"/> +</xml> +</programlisting> + </sect1> + </chapter> + + <chapter> + <title xml:id="s.5">Common problems</title> + + <sect1> + <title xml:id="s.5.1">Namespaces and default namespace</title> + + <para>One of the commonly asked questions about XmlStarlet 'select' or + 'edit' options is: "Why nothing matched for my XPath expression which + seems right to me?". Common cause of these problems is not properly + defining a namespace for XPath. This chapter will show several examples + to illustrate these issues you might encounter.</para> + + <para>For example the following XHTML document has a default namespace + declaration</para> + + <para><programlisting><html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Query Page</title> +<meta http-equiv="Content-Style-Type" content="text/css" /> +<meta http-equiv="Content-Script-Type" content="text/javascript" /> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> +<meta name="robots" content="noindex,nofollow" /> +</head> +<body> +... +</body> +</html> +</programlisting></para> + + <para>And the following (initially looking correct) query to print all + links</para> + + <para><programlisting><phrase role="PROG"/> sel -t -m "//a" -c . -n </programlisting></para> + + <para>would return nothing. The issue with this query is that it is not + addressing element <a> in the right namespace. XPath requires all + namespaces used in XPath expression be defined. So for declared + namespace <html xmlns="http://www.w3.org/1999/xhtml"> in input + XML, you have to do same for XPath (or XSLT). There is another important + detail: namespace equivalency is determined not by namespace prefix, but + by URI. See query below, which would return expected result</para> + + <para><programlisting><phrase role="PROG"/> sel -N x="http://www.w3.org/1999/xhtml" -t -m "//x:a" -c . -n</programlisting></para> + + <para>Example of deleting namespace declarations.</para> + + <para>Delete namespace declarations and all elements from non default + namespace from the following XML document:</para> + + <para>Input (file ns2.xml)<programlisting><doc xmlns="http://www.a.com/xyz" xmlns:ns="http://www.c.com/xyz"> + <A>test</A> + <B> + <ns:C>xyz</ns:C> + </B> +</doc> +</programlisting></para> + + <para>Command:<programlisting><phrase role="PROG"/> ed -N N="http://www.c.com/xyz" -d '//N:*' ns2.xml | \ + sed -e 's/ xmlns.*=".*"//g'</programlisting></para> + + <para>Output<programlisting><doc> + <A>test</A> + <B/> +</doc> +</programlisting></para> + </sect1> + + <sect1> + <title xml:id="s.5.2">Special characters</title> + + <para>Sometimes issues appear with handling of special characters, where + 'special' means in XML sence as well as in 'shell' terms. Examples below + should clear at least some of the confusions.</para> + + <para>You should not forget about the fact that your command lines are + executed by shell and shell does substitutions of its special characters + too. So for example, one may ask:</para> + + <para>"Why does the following query return nothing?" + <programlisting>echo '<X name="foo">EEE</X>' | <phrase role="PROG"/> sel -t -m /X[@name='foo'] -v .</programlisting></para> + + <para>The answer lies in the way shell substitues 'foo', which simply + becomes foo before the command is run. So the correct way to write that + would be</para> + + <para><programlisting>echo '<X name="foo">EEE</X>' | <phrase role="PROG"/> sel -t -m "/X[@name='foo']" -v .</programlisting></para> + + <para>Another example involves XML special characters. Question: How to + search for &apos; in text nodes?</para> + + <para>The following should help<programlisting><phrase role="PROG"/> sel -t -m "//line[contains(text(),&quot;'&quot;)]" -c . +</programlisting></para> + </sect1> + + <sect1> + <title xml:id="s.5.3">Sorting</title> + + <para>Let's take a look at XSLT produced by the following '<phrase role="PROG"/> sel' + command:</para> + + <para><programlisting># Query XML document and produce sorted text table +<phrase role="PROG"/> sel -T -t -m /xml/table/rec -s D:N:- "@id" \ + -v "concat(@id,'|',numField,'|',stringField)" -n xml/table.xml +</programlisting></para> + + <para><programlisting><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output omit-xml-declaration="yes" indent="no" method="text"/> +<xsl:param name="inputFile">-</xsl:param> +<xsl:template match="/"> + <xsl:call-template name="t1"/> +</xsl:template> +<xsl:template name="t1"> + <xsl:for-each select="/xml/table/rec"> + <xsl:sort order="descending" data-type="number" + case-order="upper-first" select="@id"/> + <xsl:value-of select="concat(@id,'|',numField,'|',stringField)"/> + <xsl:value-of select="'&#10;'"/> + </xsl:for-each> +</xsl:template> +</xsl:stylesheet> +</programlisting></para> + + <para>-s option of '<phrase role="PROG"/> sel' command controls 'order', 'data-type', and + 'case-order' attributes of <xsl:sort/> element .</para> + </sect1> + + <sect1> + <title xml:id="s.5.4">Validation</title> + + <para>Many questions are asked about XSD (XML schema) validation. Well, + XmlStarlet relies on libxml2 which has incomplete support for XML + schemas. Untill it is done in libxml2 it will not be in + XmlStarlet.</para> + + <para></para> + + <para></para> + </sect1> + </chapter> + + <chapter> + <title>Other XmlStarlet Resources</title> + + <para>Here are few articles on the Internet.</para> + + <itemizedlist> + <listitem> + <para><link + xlink:href="http://www.freesoftwaremagazine.com/free_issues/issue_06/xml_starlet/">XMLStarlet: + a Unix toolkit for XML</link></para> + </listitem> + + <listitem> + <para><link + xlink:href="http://www-128.ibm.com/developerworks/xml/library/x-starlet.html">Start + working with XMLStarlet</link></para> + </listitem> + + <listitem> + <para><link + xlink:href="http://blogicblog.blogspot.com/2004/09/xmlstarlet-gentle-introduction-into.html">XMLStarlet: + A gentle introduction into XSLT </link></para> + </listitem> + + <listitem> + <para><link + xlink:href="http://blogs.applibase.net/pramod/index.php/archives/command-line-xml-with-xmlstarlet ">Command + line XML with XMLStarlet </link></para> + </listitem> + + <listitem> + <para><link + xlink:href="http://www.pinkjuice.com/howto/vimxml/moresetup.xml#xmlstarlet">Using + vi as XML editor</link></para> + </listitem> + </itemizedlist> + </chapter> +</book> |