NAME¶
tv_grep - Filter programmes and channels from an XMLTV listings file.
SYNOPSIS¶
"tv_grep [--help] [--output FILE] [--ignore-case|-i] (EXPR | REGEXP)
[FILE...]"
DESCRIPTION¶
Reads XMLTV listings data and writes out data containing some of the programmes
and channels from the original. Which programmes and channels are left in the
output is controlled by the regexp or Boolean expression given.
Simple usage is
tv_grep REGEXP [FILE...], where
REGEXP is a Perl 5
regular expression (see
perlre(1)). This finds all <programme>
elements containing text matching the regexp. The channels are left unchanged,
that is, all the <channel> elements are output.
For more advanced searches, you can specify a Boolean expression (which loosely
follows the style of
find(1)). There are many tests for matching
programme content against a regular expression, a few for matching channels
and programmes on those channels, and a few special tests.
OPTIONS¶
--output FILE write to FILE rather than standard output.
--ignore-case,
-i treat all regular expression matches as case
insensitive.
EXPRESSIONS¶
PROGRAMME CONTENT TESTS¶
The tests for programme content match against particular attributes or
subelements of the <programme> element in the XML data. Each test is
named the same as the attribute or element it matches. Those which take a
regexp as an argument match if the programme contains at least one attribute
or element of the same name whose content matches the regexp. Those which do
not take a regexp match if the programme simply contains one or more
attributes or elements of that name.
Some elements may or may not have content - they may just be empty. The regular
expression '' (the empty string) matches any element, even one with empty
content, while a nonempty regular expression matches only those with content.
For example,
--desc Racing matches a programme if the programme has at
least one <desc> element whose content contains 'Racing'.
--stop
'' (the second argument is the empty string) matches a programme if the
programme gives a stop time.
There are some elements where only yes/no matching is possible, where you cannot
give a regexp to query the element's content. For these 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 additional empty-string argument is to leave room for
future expansion.
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 ''
--language REGEXP
--last-chance REGEXP
--length ''
--new
--orig-language REGEXP
--pdc-start REGEXP
--premiere REGEXP
--previously-shown ''
--rating ''
--showview REGEXP
--star-rating ''
--start REGEXP
--stop REGEXP
--sub-title REGEXP
--subtitles ''
--title REGEXP
--url REGEXP
--video ''
--videoplus REGEXP
--vps-start REGEXP
While every attribute and subelement of <programme> elements is included
in the above list, for some of them it is normally more convenient to use the
special tests described below.
CHANNEL TESTS¶
There are two tests for channels. These filter both <programme> and
<channel> elements: if a channel is filtered out then all programmes on
that channel are too.
--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.
TIME TESTS¶
Normally you don't want to test time strings with a regular expression but
rather compare them with some other time. 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.
Another way of thinking about these two tests is that
--on-after
now gives 'all programmes you could possibly still watch, although
perhaps only catching the end'.
--on-before now gives 'all programmes
you could possibly have seen, even if only the start'.
--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.
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.
SEE ALSO¶
xmltv(5),
perl(1),
XMLTV(3).
AUTHOR¶
Ed Avis, ed@membled.com
BUGS¶
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.
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.
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.
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.
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.