XML_GREP(1)

📦
version 3.530.0 · 7 versions
, in opensuse-leap 16.0

🦋 XML_GREP(1) 🦋

okay bestie, so this is xml_grep — a User Contributed Perl Documentation page, and honestly? it's giving "tiny tool, huge slay". it's a grep for XML files and i'm obsessed. let's get into it 💅

✨ NAME ✨

xml_grep — grep XML files looking for specific elements

like, you know how grep hunts through text? this does that but for XML elements, which is so much more iconic ✨

🌸 SYNOPSYS 🌸

(no i did not fix the spelling, it's staying, it's canon 💀)

xml_grep [options] <file list>

or

xml_grep <xpath expression> <file list>

okay so by default you can literally just hand xml_grep an XPath expression and a list of files, and it gives you back an XML file with the result. easy. 🎀

and that's exactly the same as writing:

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

periodt. no cap. 🫶

🎀 OPTIONS 🎀

  • --help — brief help message
  • --man — the full documentation (the whole thing, the director's cut)
  • --Version — shows you the tool version
  • --root <cond> — look for and return xml chunks matching <cond>

lowkey the rules here: if neither --root nor --file are used, then the element(s) that trigger the --cond option is (are) used. and if --cond isn't used either, then all elements matching the <cond> are returned.

you can hand it several --root options, no problem 🫶

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

several --cond can be provided too — and in that case they're OR'ed together, iykyk 💖

  • --files — return only file names, no XML output at all
heads up bestie: using this option precludes using any of the options that define the XML output: --roots, --encoding, --wrap, --group_by_file or --pretty_print. it's one or the other, choose your fighter 💀
  • --count — return only the number of matches in each file
same warning, same energy: using 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 is skipped 🙈 (with it? you get to be strict about it. main character behavior.)
  • --date — when on (and it is on by default) the wrapping element gets a "date" attribute that gives the date the tool was run. super handy.

with --nodate this attribute is not added — which is genuinely useful if you need to compare 2 runs and don't want the date spoiling the diff 💅

  • --encoding <enc> — encoding of the xml output (and it's utf-8 by default)
  • --nb_results <nb> — output only <nb> results. that's it. that's the whole thing. 🔥
  • --by_file — output only <nb> results by file
  • --wrap <tag> — wrap the xml result in the provided tag (defaults to 'xml_grep')

and if you set wrap to an empty string (--wrap '') then the xml result is not wrapped at all. naked xml. bold. 🎀

  • --nowrap — same as using --wrap '': the xml result is not wrapped. twins fr fr.
  • --descr <string> — attributes of the wrap tag (defaults to version="<VERSION>" date="<date>") ⭐
  • --group_by_file <optional_tag> — wrap results for each file 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. bestie this is the organizational slay.

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. literally grep -v energy.

the short form of this option is -v 💅

  • --pretty_print <optional_style> — pretty print the output using XML::Twig styles ('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. clean, simple, iconic.
  • --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 basically you're speaking XML::Twig's love language.

examples, bestie, so you can copy-paste and feel powerful:

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

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

and real quick: options are processed by Getopt::Long, so they can start with - or -- and can be abbreviated — -r instead of --root, for example. so you can be lazy and it still works, we love that for us 💖

🔥 DESCRIPTION 🔥

xml_grep does a grep on XML files. but instead of using regular expressions (so last season), it uses XPath expressions — well, actually, the subset of XPath supported by XML::Twig. still slay though 💅

and the results? they can be the names of the files, or XML elements containing matching elements. your choice, your vibe.

🌈 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. (yes legend, go off, remix it, it's free 🫶)

⭐ AUTHOR ⭐

Michel Rodriguez <mirod@xmltwig.com> — thank you for this gift, king 🙏

and that's the whole page bestie, no cap, nothing skipped, nothing dropped 💖

signing off with all the deets: this was perl v5.42.0, dated 2025-01-16, and the page itself is XML_GREP(1) — catch you on the next grep 🎀✨

📦 where this page comes from