Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Augment(3)	      User Contributed Perl Documentation	    Augment(3)

NAME
       XMLTV::Augment -	Augment	XMLTV listings files with automatic and
       user-defined rules.

DESCRIPTION
       Augment an XMLTV	xml file by applying corrections ("fixups") to
       programmes matching defined criteria ("rules").

       Two types of rules are actioned:	(i) automatic, (ii) user-defined.

       Automatic rules use pre-programmed input	and output to modify the input
       programmes. E.g.	removing a "title" where it is repeated	in a "sub-
       title" (e.g. "Horizon" /	"Horizon: Star Wars"), or trying to identify
       and extract series/episode numbers from the programme"s title, sub-
       title or	description.

       User-defined rules use the content of a "rules" file which allows
       programmes matching certain user-defined	criteria to be
       corrected/enhanced with the user	data supplied (e.g. adding/changing
       categories for all episodes of "Horizon", or fixing misspellings	in
       titles, etc.)

       By setting appropriate options in the "config" file, the	"rules"	file
       can be automatically downloaded using XMLTV::Supplement.

EXPORTED FUNCTIONS
       setEncoding
	   Set the assumed encoding of the rules file.

       inputChannel
	   Store each channel found in the input programmes file for later
	   processing by "stats".

       augmentProgramme
	   Augment a programme using (i) pre-determined	rules and (ii) user-
	   defined rules.  Which rules are processed is	determined by the
	   options set in the "config" file.

       printInfo
	   Print the lists of actions taken and	suggestions for	further
	   fixups.

       end Do any final	processing before exit (e.g. close the log file).

INSTANTIATION
	   new XMLTV::Augment( { ...parameters...} );

       Possible	parameters:
	     rule	=> filename of file containing fixup rules (if omitted
       then no user-defined rules will be actioned) (overrides auto-fetch
       Supplement if that is defined; see sample options file)
	     config	=> filename of config file to read (if omitted then no
       config file will	be used)
	     encoding	=> assumed encoding of the rules file (default =
       UTF-8)
	     stats	=> whether to print the	audit stats in the log (values
       = 0,1) (default = 1)
	     log	=> filename of output log (default = augment.log)
	     debug	=> debug level (values 0-10) (default =	no debug)
			       note debug level	> 3 is not likely to be	of
       much use	unless you are developing code

TYPICAL	USAGE
	1) Create the XMLTV::Augment object
	2) Pass	each channel to	inputChannel()
	3) Pass	each programme to augmentProgramme()
	4) Tidy	up using printInfo() & end()

	       #instantiate the	object
	       my $augment = new XMLTV::Augment(
			 "rule"	      => "myrules.txt",
			 "config"     => "myconfig.txt",
			 "log"	      => "augment.log",
			 );
	       die "failed to create XMLTV::Augment object" if !$augment;

	       for each	channel... {
		 # store the channel details
		 $augment->inputChannel( $ch );
	       }

	       for each	programme... {
		 # augmentProgramme will now do	any requested processing of the	input xml
		 $prog = $augment->augmentProgramme( $prog );
	       }

	       # log the stats
	       $augment->printInfo();

	       # close the log file
	       $augment->end();

       Note: you are responsible for reading/writing to	the XMLTV .xml file;
       the package will	not do that for	you.

RULES
       remove_duplicated_new_title_in_ep
	   Rule	#A1

	   Remove "New $title :" from <sub-title>

	     If	sub-title starts with "New" + <title> +	separator, then	it will	be removed from	the sub-title
	     "separator" can be	any of .,:;-

	     in	: "Antiques Roadshow / New Antiques Roadshow: Doncaster"
	     out: "Antiques Roadshow / Doncaster"

       remove_duplicated_title_and_ep_in_ep
	   Rule	#A2

	   Remove duplicated programme title *and* episode from	<sub-title>

	     If	sub-title starts with <title> +	separator + <episode> +	separator + <episode>, then it will be removed from the	sub-title
	     "separator" can be	any of .,:;-

	     in	: "Antiques Roadshow / Antiques	Roadshow: Doncaster: Doncaster"
	     out: "Antiques Roadshow / Doncaster"

       remove_duplicated_title_in_ep
	   Rule	#A3

	   Remove duplicated programme title from <sub-title>

	     i)	If sub-title starts with <title> + separator, then it will be removed from the sub-title
	     ii) If sub-title ends with	separator + <title>, then it will be removed from the sub-title
	     iii) If sub-title starts with <title>(...), then the sub-title will be set	to the text in brackets
	     iv) If sub-title equals <title>, then the sub-title will be removed
	     "separator" can be	any of .,:;-

	     in	: "Antiques Roadshow / Antiques	Roadshow: Doncaster"
	     out: "Antiques Roadshow / Doncaster"

	     in	: "Antiques Roadshow / Antiques	Roadshow (Doncaster)"
	     out: "Antiques Roadshow / Doncaster"

	     in	: "Antiques Roadshow / Antiques	Roadshow"
	     out: "Antiques Roadshow / "

       update_premiere_repeat_flags_from_desc
	   Rule	#A4

	   Set the <premiere> element and remove any <previously-shown>
	   element if <desc> starts with "Premiere." or	"New series". Remove
	   the "Premiere." text.  Set the <previously-shown> element and
	   remove any <premiere> element if <desc> starts with "Another
	   chance" or "Rerun" or "Repeat"

       check_potential_numbering_in_text
	   Rule	#A5

	   Check for potential series, episode and part	numbering in the
	   title, episode and description fields.

       extract_numbering_from_title
	   Rule	#A5.1

	   Extract series/episode numbering found in <title>.

       extract_numbering_from_episode
	   Rule	#A5.2

	   Extract series/episode numbering found in <sub-title>.

       extract_numbering_from_desc
	   Rule	#A5.3

	   Extract series/episode numbering found in <desc>.

       make_episode_from_part_numbers
	   Rule	#A6

	   If no <sub-title> then make one from	"part" numbers.

	     in	: "Panorama / "	 desc =	"Part 1/2..."
	     out: "Panorama / Part 1 of	2"

       process_user_rules
	   Rule	#user

	   Process programme against user-defined fixups

	   The individual rules	each have their	own option to run or not;
	   consider this like an on/off	switch for all of them.	I.e. if	this
	   option is off then no user rules will be run	(irrespective of any
	   other option	flags).

       process_non_title_info
	   Rule	#1

	   Remove specified non-title text from	<title>.

	     If	title starts with text + separator, then it will be removed from the title
	     "separator" can be	any of :;-

	     rule: 1|Python Night
	     in	: "Python Night: Monty Python -	Live at	the Hollywood Bowl / "
	     out: "Monty Python	- Live at the Hollywood	Bowl / "

       process_demoted_titles
	   Rule	#11

	   Promote demoted title from <sub-title> to <title>.

	     If	title matches, and sub-title starts with text then remove matching text	from sub-title and move	it into	the title.
	     Any text after 'separator'	in the sub-title is preserved. 'separator' can be any of .,:;-

	     rule: 11|Blackadder~Blackadder II
	     in	: "Blackadder /	Blackadder II: Potato"
	     out: "Blackadder II / Potato"

       process_replacement_titles_desc
	   Rule	#10

	   Replace specified <title> / <sub-title> with	title/episode pair
	   supplied using <desc>.

	     If	title &	sub-title match	supplied data, then replace <title> and	<sub-title> with new data supplied.

	     rule: 10|Which Doctor~~Gunsmoke~Which Doctor~Festus and Doc go fishing, but are captured by a family that is feuding with the Haggens.
	     in	: "Which Doctor	/ " desc> = "  Festus and Doc go fishing, but are captured by a	family that is feuding with the	Haggens. ..."
	     out: "Gunsmoke / Which Doctor"

       process_replacement_titles_episodes
	   Rule	#8

	   Replace specified <title> / <sub-title> with	title/episode pair
	   supplied.

	     If	title &	sub-title match	supplied data, then replace <title> and	<sub-title> with new data supplied.

	     rule: 8|Top Gear USA Special~Detroit~Top Gear~USA Special
	     in	: "Top Gear USA	Special	/ Detroit"
	     out: "Top Gear / USA Special"

	     rule: 8|Top Gear USA Special~~Top Gear~USA	Special
	     in	: "Top Gear USA	Special	/ "
	     out: "Top Gear / USA Special"
	       or
	     in	: "Top Gear USA	Special	/ 1/6."
	     out: "Top Gear / 1/6. USA Special"

       process_mixed_title_subtitle
	   Rule	#2

	   Extract sub-title from <title>.

	     If	title starts with text + separator, then the text after	it will	be moved into the sub-title
	     "separator" can be	any of :;-

	     rule: 2|Blackadder	II
	     in	: "Blackadder II: Potato / "
	     out: "Blackadder II / Potato"

       process_mixed_subtitle_title
	   Rule	#3

	   Extract sub-title from <title>.

	     If	title ends with	separator + text, then the text	before it will be moved	into the sub-title
	     "separator" can be	any of :;-

	     rule: 3|Storyville
	     in	: "Kings of Pastry :Storyville / "
	     out: "Storyville /	Kings of Pastry"

       process_reversed_title_subtitle
	   Rule	#4

	   Reverse <title> and <sub-title>

	     If	sub-title matches the rule's text, then	swap the title and sub-title

	     rule: 4|Storyville
	     in	: "Kings of Pastry / Storyville"
	     out: "Storyville /	Kings of Pastry"

       process_replacement_titles
	   Rule	#5

	   Replace <title> with	supplied text.

	     If	title matches the rule's text, then use	the replacement	text supplied

	     rule: 5|A Time Team Special~Time Team
	     in	: "A Time Team Special / Doncaster"
	     out: "Time	Team / Doncaster"

	   This	is the one which you will probably use most. It	can be used to
	   fix most incorrect titles - e.g. spelling mistakes; punctuation;
	   character case; etc.

       process_subtitle_remove_text
	   Rule	#13

	   Remove specified text from <sub-title> for a	given <title>.

	     If	sub-title starts with text + separator,	or ends	with separator + text,
	     then it will be removed from the sub-title.
	     "separator" can be	any of .,:;- and is optional.

	     rule: 13|Time Team~A Time Team Special
	     in	: "Time	Team / Doncaster : A Time Team Special "
	     out: "Time	Team / Doncaster"

       process_replacement_episodes
	   Rule	#7

	   Replace <sub-title> with supplied text.

	     If	sub-title matches the rule's text, then	use the	replacement text supplied

	     rule: 7|Time Team~Time Team Special: Doncaster~Doncaster
	     in	: "Time	Team / Time Team Special: Doncaster"
	     out: "Time	Team / Doncaster"

       process_replacement_ep_from_desc
	   Rule	#9

	   Replace <sub-title> with supplied text when the <desc> matches that
	   given.

	     If	sub-title matches the rule's text, then	use the	replacement text supplied

	     rule: 9|Heroes of Comedy~The Goons~The series celebrating great British comics pays tribute to the	Goons.
	     in	: "Heroes of Comedy / "
	     out: "Heroes of Comedy / The Goons"
	       or
	     in	: "Heroes of Comedy / Spike Milligan"
	     out: "Heroes of Comedy / The Goons"

       process_replacement_genres
	   Rule	#6

	   Replace <category> with supplied text.

	     If	title matches the rule's text, then use	the replacement	category(-ies) supplied
	     (note ALL existing	categories are replaced)

	     rule: 6|Antiques Roadshow~Entertainment~Arts~Shopping
	     in	: "Antiques Roadshow / " category "Reality"
	     out: "Antiques Roadshow / " category "Entertainment" + "Arts" + "Shopping"

	   You can specify a wildcard with the title by	using %% which
	   represents any number of characters.	 So for	example	"News%%" will
	   match "News", "News and Weather", "Newsnight", etc.	But be
	   careful; "%%News%%" will also match "John Craven's Newsround",
	   "Eurosport News", "Election Newsroom	Live", "Have I Got News	For
	   You", "Scuzz	Meets Jason Newsted", etc.

       process_replacement_film_genres
	   Rule	#12

	   Replace "Film"/"Films" <category> with supplied text.

	     If	title matches the rule's text and the prog has category	"Film" or "Films", then	use the	replacement category(-ies) supplied
	     (note ALL categories are replaced,	not just "Film")

	     rule: 12|The Hobbit Special~Entertainment~Interview
	     in	: "The Hobbit Special /	" category "Film" + "Drama"
	     out: "The Hobbit Special /	" category "Entertainment" + "Interview"

       process_translate_genres
	   Rule	#14

	   Replace <category> with supplied value(s).

	     If	category matches one found in the prog,	then replace it	with the category(-ies)	supplied
	     (note any other categories	are left alone)

	     rule: 14|Soccer~Football
	     in	: "Leeds v Arsenal" category "Soccer"
	     out: "Leeds v Arsenal" category "Soccer"

	     rule: 14|Adventure/War~Action Adventure~War
	     in	: "Leeds v Arsenal" category "Adventure/War"
	     out: "Leeds v Arsenal" category "Action Adventure"	+ "War"

       process_add_genres_to_channel
	   Rule	#15

	   Add a category to all programmes on a specified channel.

	     If	channel	matches	this prog, the add the supplied	category(-ies) to the programme
	     (note any other categories	are left alone)

	     rule: 15|travelchannel.co.uk~Travel
	     in	: "World's Greatest Motorcycle Rides" category "Motoring"
	     out: "World's Greatest Motorcycle Rides" category "Motoring" + "Travel"

	     rule: 15|cnbc.com~News~Business
	     in	: "Investing in	India" category	""
	     out: "Investing in	India" category	"News" + "Business"

	   You should be very careful with this	one as it will add the
	   category you	specify	to EVERY programme broadcast on	that channel.
	   This	may not	be what	you always want	(e.g. Teleshopping isn't
	   really "music" even if it is	on MTV!)

AUTHOR
       Geoff Westcott, honir.at.gmail.dot.com, Dec. 2014.

       This code is based on the "fixup" method/code defined in	tv_grab_uk_rt
       grabber and credit is given to the author Nick Morrott.

perl v5.24.1			  2017-07-02			    Augment(3)

NAME | DESCRIPTION | EXPORTED FUNCTIONS | INSTANTIATION | TYPICAL USAGE | RULES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XMLTV::Augment&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help