TV_GREP(1p)

📦
version 1.4.0 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 TV_GREP(1p) 💖

okay bestie, gather round, because we're talking about tv_grep from the User Contributed Perl Documentation — and no, it's not a Perl thing you need to fear, it's literally just "grep but for your TV listings" and it ATE. 💅

✨ NAME ✨

tv_grep — filter programmes and channels from an XMLTV listings file. yes she filters. she's a filterer. 🎀

🌸 SYNOPSIS 🌸

tv_grep [--help] [--output FILE] [--ignore-case|-i] (EXPR | REGEXP)
[FILE...]

🦋 DESCRIPTION 🦋

So here's the vibe: tv_grep reads XMLTV listings data and writes back out only some of the programmes and channels from the original. Which ones survive the cut? That's entirely up to the regexp or Boolean expression you hand her. She's not making decisions, you are. 👑

The easy-peasy version is tv_grep REGEXP [FILE...], where REGEXP is a Perl 5 regular expression (go peek at perlre(1) if you need a refresher, iykyk). This finds every <programme> element that has text matching the regexp. And the channels? Untouched. All the <channel> elements get output, no notes. ✨

But if you want the advanced lore, you can throw a whole Boolean expression at her (it loosely follows the style of find(1) — yes, that find(1)). There are tons of tests for matching programme content against a regular expression, a few for matching channels and programmes on those channels, and a few special ones that are just their own little thing. 🫶

💜 OPTIONS 💜

  • --output FILE — write to FILE instead of standard output. redirecting but make it fashion. 📝
  • --ignore-case, -i — treat all regular expression matches as case insensitive. so RACING and racing and RaCiNg are all the same girlie fr fr. 🙈

🌈 EXPRESSIONS 🌈

🍓 PROGRAMME CONTENT TESTS

These tests match against specific attributes or subelements of the <programme> element in the XML data. Each test is named the same as the attribute or element it matches — no secret identities here.

Here's the rules of the game:

  • If the test takes a regexp as an argument, it matches when the programme contains at least one attribute or element of that same name whose content matches the regexp.
  • If the test does not take a regexp, it matches when the programme simply contains one or more attributes or elements of that name.

Some elements may or may not have content — they could just be empty, no thoughts head empty. The regular expression '' (the empty string) matches any element, even one with empty content. But a nonempty regular expression matches only the ones that actually have content. slay 💅

For example: --desc Racing matches a programme if the programme has at least one <desc> element whose content contains 'Racing'. And --stop '' (yep, the second argument is the empty string) matches a programme if the programme gives a stop time.

Now — there are some elements where only yes/no matching is possible, where you cannot give a regexp to query the element's content. For those, the second '' argument is mandatory. For example --previously-shown '' will match programmes which have that element, but a test of --previously-shown foo will give an error, because querying the content of previously-shown is not implemented. The extra empty-string argument is there to leave room for future expansion. it's giving "placeholder, but make it intentional". 🧚

The content tests are generated from the XMLTV file format. The current set of programme content tests is:

  • --audio ''
  • --category REGEXP
  • --channel REGEXP
  • --clumpidx REGEXP
  • --country REGEXP
  • --credits ''
  • --date REGEXP
  • --desc REGEXP
  • --episode-num ''
  • --icon ''
  • --image ''
  • --keyword REGEXP
  • --language REGEXP
  • --last-chance REGEXP
  • --length ''
  • --new
  • --orig-language REGEXP
  • --pdc-start REGEXP
  • --premiere REGEXP
  • --previously-shown ''
  • --rating ''
  • --review ''
  • --showview REGEXP
  • --star-rating ''
  • --start REGEXP
  • --stop REGEXP
  • --sub-title REGEXP
  • --subtitles ''
  • --title REGEXP
  • --url ''
  • --video ''
  • --videoplus REGEXP
  • --vps-start REGEXP

And while every attribute and subelement of <programme> elements is included in that list above, for some of them it's normally way more convenient to use the special tests described below. because why do it the hard way when there's a shortcut. 👑

🎀 CHANNEL TESTS

There are three tests for channels. These filter both <programme> and <channel> elements — so if a channel gets filtered out, all programmes on that channel are going down with her. no survivors. 💀

  • --channel-name REGEXP — True if the channel has a <name> whose content matches REGEXP.
  • --channel-id CHANNEL_ID — True if the channel's XMLTV id is exactly equal to CHANNEL_ID.
  • --channel-id-exp REGEXP — True if the channel has a <id> whose content matches REGEXP.

⏰ TIME TESTS

Normally you don't want to test time strings with a regular expression — you want to compare them with some other time. different activity entirely. There are two tests for this. 🔥

  • --on-after DATE — True if the programme will be broadcast at or after DATE, or will be part of the way through broadcasting at DATE. (Note: a programme is considered to be broadcasting from its start time, up to but not including its stop time.) DATE can be given in any sane date format; but if you don't specify the timezone then UTC is assumed. To remove all the programmes you have already missed, try --on-after now.
  • --on-before DATE — True if the programme will be broadcast wholly before DATE, or if it will be part of the way through broadcasting at DATE. To remove all the programmes that haven't yet begun broadcasting, try --on-before now. You can use --on-before and --on-after together to find all programmes which are broadcasting at a certain time. iconic combo honestly. ✨

Another way of thinking about these two tests: --on-after now gives you 'all programmes you could possibly still watch, although perhaps only catching the end'. And --on-before now gives you 'all programmes you could possibly have seen, even if only the start'. so basically the past and the future, but make it TV. 🦋

  • --eval CODE — Evaluate CODE as Perl code, use the return value to decide whether to keep the programme. The Perl code will be given the programme data in $_ in XMLTV.pm hash format (see XMLTV). The code can actually modify the programme passed in, which can be used for quick fixups. This option is not intended for normal use, but as an escape in case none of the existing tests is what you want. If you develop any useful bits of code, please submit them to be included as new tests. be the change you want to see in the test suite bestie 💜

🧚 LOGICAL OPERATORS

EXPR1 --and EXPR2, EXPR1 -and EXPR2, EXPR1 EXPR2

EXPR1 --or EXPR2, EXPR1 -or EXPR2

--not EXPR, -not EXPR, ! EXPR

Of these, 'not' binds tightest, affecting the following predicate only. 'and' is next, and 'or' binds loosest. order of operations but make it chaotic. 💅

🌸 SEE ALSO 🌸

xmltv(5), perl(1), XMLTV(3).

🎀 AUTHOR 🎀

Ed Avis, ed@membled.com

💀 BUGS 💀

okay so listen, we need to talk about the quirks, and there are a few. no cap.

The --on-after test cannot be totally accurate when the input data did not give a stop time for a programme. In this case we assume the stop time is equal to the start time. This filters out more programmes than if the stop time were given. There will be a warning if this happens more than once on any single channel. It could be worthwhile to filter the listings data through tv_sort(1) beforehand to add stop times. forewarned is forearmed fr fr. 😭

Similar remarks apply to --on-before: if the stop time is missing we assume it is equal to the start time, and this can mean leaving in a programme which, if it had a stop time, would be removed. awkward.

The assumption of UTC for dates without timezones could be considered a bug. Perhaps the user input should be interpreted according to the local timezone. OTOH, if the data has no timezones and neither does the user input, then things will work as expected. so... situationally fine? 🙈

The simple usage is the only way to match against all a programme's content, because some things (like <credits>) do not have programme content tests defined. It actually works by stringifying the whole programme and regexp matching that, which means that it could give wrong results for regular expressions containing quote characters or some punctuation symbols. This is not particularly likely to happen in practice. lowkey rare, but it's real. ⚠️

Some listings sources generate timeslots containing two or more programmes in succession. This is represented in XMLTV with the 'clumpidx' attribute. If tv_grep selects only some of the programmes from a clump, then it will alter the clumpidx of those remaining to make it consistent. This is maybe not ideal — perhaps the clumpidx should be left unchanged so it's obvious that something is missing — but at least it prevents complaints from other XMLTV tools about badly formed clumps. The clumpidx handling does mean that tv_grep is not always idempotent. yeah. she's not a fixed point. 🫶

and that's the whole page bestie!! go forth and filter your listings, you absolute main character 👑

perl v5.40.1 🌈 2025-04-19 🎀 — mwah, that's the source and version and date, love u, bye!! 💖✨🌸🦋

📦 where this page comes from