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.

