XML_GREP(1p)

📦
version 3.54 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

xml_grep — bestie, it's grep but for XML files, and it hunts down the specific elements you're looking for ✨

This one lives in section 1p of the manual, and it's a User Contributed Perl thing, so you know it's got main character energy 👑

🌸 SYNOPSYS 🌸

okay so here's the whole vibe, exactly as written:

xml_grep [options] <file list>

or, the other flavor:

xml_grep <xpath expression> <file list>

By default you can just hand xml_grep an XPath expression and a list of files, and it hands you back an XML file with the result. Like, that's it. That's the whole job 💅

And that shortcut is literally equivalent to writing:

xml_grep --group_by_file file --pretty_print indented --cond <file list>

🎀 OPTIONS 🎀

  • --help — a lil brief help message, just the appetizer 🍓
  • --man — the full documentation, the whole meal
  • --Version — shows you the tool version, no cap
  • --root <cond> — looks for and returns xml chunks matching <cond>

okay so if you use neither --root nor --file, then the element(s) that trigger the --cond option is (are) used instead. And if --cond isn't used at all? Then every element matching the <cond> gets returned 🌈

and yes, you can pass several --roots, stack 'em up 💖

  • --cond <cond> — returns the chunks (or file names) only if they contain elements matching <cond>

several --conds can be provided, and in that case they're OR'ed together, bestie 🫶

  • --files — returns only file names, no XML output generated, we're keeping it minimal ✨
heads up: using this option precludes using any of the options that define the XML output — that's --roots, --encoding, --wrap, --group_by_file or --pretty_print. Pick a lane, queen.
  • --count — returns only the number of matches in each file, the receipts 📊
same deal: this option precludes using any of the options that define the XML output: --roots, --encoding, --wrap, --group_by_file or --pretty_print
  • --strict — without this option, parsing errors are reported to STDOUT and the file gets skipped. With it? No more casual skipping, we're being strict 💀
  • --date — when on (and it's on by default), the wrapping element gets a date attribute giving the date the tool was run 📅

with --nodate this attribute is not added, which is lowkey useful if you need to compare 2 runs. Iconic for diffing ✨

  • --encoding <enc> — the encoding of the xml output, and it's utf-8 by default
  • --nb_results <nb> — outputs only <nb> results, we're capping it
  • --by_file — outputs only <nb> results by file, one per file energy 🦋
  • --wrap <tag> — wraps the xml result in the tag you provide, and it defaults to 'xml_grep'

and if you set wrap to an empty string like --wrap '', then the xml result is not wrapped at all. Naked. Free. Periodt 💅

  • --nowrap — same as using --wrap '': the xml result is not wrapped. That's it, that's the option.
  • --descr <string> — the attributes of the wrap tag, and it defaults to version="<VERSION>" date="<date>" 🎀
  • --group_by_file <optional_tag> — wraps results for each files into a separate element. By default that element is named file, and it has an attribute named filename that gives the name of the file 📁

the short version of this option is -g

  • --exclude <condition> — same as using -v in grep: the elements that match the condition are excluded from the result, and the input file(s) is (are) otherwise unchanged 🚫

the short form of this option is -v

  • --pretty_print <optional_style> — pretty prints the output using XML::Twig styles, and "indented", "record" or "record_c" are probably what you are looking for 💖

if the option is used but no style is given, then "indented" is used

short form for this argument is -s

  • --text_only — Displays the text of the results, one by line. Just the words, no drama 📝
  • --html — Allow HTML input, files are converted using HTML::TreeBuilder 🌐
  • --Tidy — Allow HTML input, files are converted using HTML::Tidy 🧹

🌟 Condition Syntax 🌟

<cond> is an XPath-like expression, as allowed by XML::Twig to trigger handlers. So it's XPath-ish, not full XPath, iykyk 👑

examples, verbatim, no notes:

'para'
'para[@compact="compact"]'
'*[@urgent]'
'*[@urgent="1"]'
'para[string()="WARNING"]'

see XML::Twig for a more complete description of the <cond> syntax 📚

oh and also — options are processed by Getopt::Long so they can start with - or -- and can be abbreviated (-r instead of --root for example). Shortcuts, we love her ✨

💜 DESCRIPTION 💜

xml_grep does a grep on XML files. But instead of using regular expressions it uses XPath expressions — specifically, the subset of XPath supported by XML::Twig. Not regex, bestie, XPath. Different beast entirely 🦋

and the results can be either the names of the files, or the XML elements containing matching elements. Your call 💖

🫶 SEE ALSO 🫶

XML::Twig Getopt::Long

👑 LICENSE 👑

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Free as in, go off, do your thing 🌈

🎀 AUTHOR 🎀

Michel Rodriguez <mirod@xmltwig.com> — thank you for your service, legend 💐

okay that's the whole page, bestie!! this one was generated by perl v5.40.1 and it's dated 2025-12-18, so go forth and grep your XML, you absolute icon 💅✨🦋💖

📦 where this page comes from