Manual Reference Pages - TV_GREP (1)
tv_grep - Filter programmes and channels from an XMLTV listings file.
tv_grep [--help] [--output FILE] [--ignore-case|-i] (EXPR | REGEXP) [FILE...]
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
Simple usage is <B>tv_grep REGEXP [FILE...]B>, where <B>REGEXPB> 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
<B>--output FILEB> write to FILE rather than standard output.
<B>--ignore-caseB>, <B>-iB> treat all regular expression matches as case insensitive.
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, <B>--desc RacingB> matches a programme if the programme has
at least one <desc> element whose content contains Racing. <B>--stop B>
(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 elements content. For
these the second <B>B> argument is mandatory. For example
<B>--previously-shown B> will match programmes which have that
element, but a test of <B>--previously-shown fooB> 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
The content tests are generated from the XMLTV file format. The
current set of programme content tests is:
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.
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.
<B>--channel-name REGEXPB> True if the channel has a <name> whose content matches REGEXP.
<B>--channel-id CHANNEL_IDB> True if the channels XMLTV id is exactly equal to CHANNEL_ID.
Normally you dont want to test time strings with a regular
expression but rather compare them with some other time. There are
two tests for this.
<B>--on-after DATEB> 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 dont specify the timezone then UTC is
assumed. To remove all the programmes you have already missed, try
<B>--on-before DATEB> 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 havent yet begun
broadcasting, try <B>--on-before nowB>. You can use <B>--on-beforeB> and
<B>--on-afterB> together to find all programmes which are broadcasting
at a certain time.
Another way of thinking about these two tests is that <B>--on-after
nowB> gives all programmes you could possibly still watch, although
perhaps only catching the end. <B>--on-before nowB> gives all
programmes you could possibly have seen, even if only the start.
<B>--eval CODEB> 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
<B>EXPR1 --and EXPR2B>, <B>EXPR1 -and EXPR2B>, <B>EXPR1 EXPR2B>
<B>EXPR1 --or EXPR2B>, <B>EXPR1 -or EXPR2B>
<B>--not EXPRB>, <B>-not EXPRB>, <B>! EXPRB>
Of these, not binds tightest, affecting the following predicate
only. and is next, and or binds loosest.
xmltv(5), perl(1), XMLTV(3).
Ed Avis, email@example.com
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
programmes 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 its 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.
|perl v5.20.3 ||TV_GREP (1) ||2016-04-03 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.