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 ''

       --keyword REGEXP

       --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.