Showtitle Irssi Bot Script

Showtitle is an Irssi script that scans the current private, public or action message for a string matching a URL specification. If it finds one, it then tries to get the beginning of the URL contents in order to parse out the <title></title> tag, and then attempts to show it either to the channel, or to the script user.

Showtitle is an active bot script, i.e, it responds to certain types of text on channels it is listening on.

The channel text to invoke showtitle commands is "!st" at the beginning of the line.

!st subcommands:

listen (on|off|list)

Determines whether showtitle will be listening to a particular channel.

• on - turn listening on for this chatnet/channel
• off - turn listening off for this chatnet/channel
• list - show current channels listened to on this chatnet
• help - send help info about listen command to nick that entered the !st command

filter (add|delete|list|help)

Modifies the filters for the current chatnet/channel. If no filters are specified, and listening is on for this chatnet/channel, then all URL title are sent to the channel. Filters are pass filters, rather than no-pass filters, i.e. they determine what is allowed to send to the channel.

• add <regex> -- add the regex to the filter list
• delete <regex> -- remove the regex from the filter list
• list -- show current set of filters on this chatnet/channel
• help -- display help info to the calling nick

user (add|delete|request [address]|list|help)

Deal with eligible users for managing the showtitle bot. Eligible users are determined by the address part of their hostmask.

• add -- add a user to the showtitle bot's user list
• delete -- delete a user from showtitle bot's user list
• request [address] -- make a request to the bot owner to add someone to the list. If address is not specified, then the calling user's address is used.
• list -- list the current users
• help -- send a help message to calling nick

help

send general help to calling user.

UI Commands

These commands are available to the user running the showtitle script.

/stuser (add|delete|list)

modify user list

/stfilter (add|delete|list)

modify filter list

/stlisten (on|off|list)

modify listening list

/stignore (on|off|list)

Completely ignore any ^! input from the channel. This has the effect of essentially hiding showtitle from anyone attempting to determine if there are any bots listening

• on - turn on ignore on this chatnet/channel
• off - turn off ignore on this chatnet/channel
• list - show ignored channels on this chatnet

/stsave

save current configuration

/ststatus

show current status across all chatnets/channels

/stdebug [on|off]

turns debugging for showtitle script on or off, or reports status

Internal Documentation

Global Declarations

The following globals are used to enable useful error messages from deep inside some of the functions.

• $current_chatnet - stores the name of the current chatnet that the signal was triggered from..
• $current_channel - stores the name of the current channel that the signal was triggered from.
• $current_url - the matching URL in the signal's data, if any
• $empty_re - a regular expression that matches an empty line
• $debug - flag used to check if debugging output should be sent or not
• $line_prefix - the text shown by showtitle when it writes to the channel before the title is given
• $line_prefix_re - regular expression needed to match $line_prefix
• %listen_on - determines where we are listening = (chatnet => {channel => listening,})
• %filters - filters to apply on a per-channel basis = (chatnet => {channel => (filter_regexp)})
• %validusers - which users are allowed to do certain commands = (chatnet => {channel => (address)})
• %ignores - enforces ignore on specific chatnet channels = (chatnet => {channel => ignoring (on/off)})
• $major, $minor, and $subminor
• $database_basename - the name of the data base used to store information, suffixed by major version number
• $irssi_dir - the directory containing current irssi session's parameters, set by --home command line paramter
• $database - full database path name
• $database_tmp - full temporary database path name
• $database_old - full backup database path name

Utility Routines

DebugPrint

Print a message to the current window with some debugging information if $debug is true.

• param string $debugmsg - message to print
• global boolean $debug - test whether debug is on or off
• returns void

irssi_safe

Prepare a message for output to Irssi by making sure anything needed is escaped. Currently, that's only the percent sign (%).

• param string $s - message to clean
• returns string - cleaned up string

shownotice

Nicely format a string to show up on the user's current window

• param string $s - message to show
• returns void

showerror

Nicely format an error messge string to show up on the user's current window

• param string $s - message to show
• returns void

say_message

Say a message to the specified server/channel

• param object $server - current server object
• param string $target - current channel/query window name
• param string $msg - message to send
• returns void

me_action

send an action message to the current chatnet/channel

• param object $server - current server object
• param string $target - name of current channel
• param string $msg - message to send
• returns void

printOnThisWindow

send a string to the current window

• param object $server - current server object
• param string $target - name of current channel
• param string $msg - message to send
• returns void

lc_irc

convert the passed string to lower case, special for irc

• param string $str - string to convert
• returns string - convert string

uc_irc

convert the passed string to upper case, special for irc

• param string $str - string to convert
• returns string - convert string

Database handling functions

do_listen

Process a listen database entry

• param string $chatnet - the chat network to apply the listen item to
• param string $channel - the channel to apply the listen item to
• param string $status - which status to apply (on or off)

do_filter

process the filter database entry

• param string $chatnet - chatnet to apply the filter string to
• param string $channel - channel to apply the filter string to
• param string $filter - filter to apply

do_user

process a user database entry

• param string $chatnet - chatnet to apply the user string to
• param string $channel - channel to apply the user string to
• param string $user - user string to apply

do_ignore

process an ignore database entry

• param string $chatnet - chatnet to apply the ignore directive to
• param string $channel - channel to apply the ignore directive to
• param string $status - ignore directive (or or off)

syntax_error

Report a syntax error reading and processing the database

%parse_database

An associative array containing a jump table to handle each database entry type. Structure is:

• %parse_database[entrytype] = &function;> - jump table

read_database

reads and processes the various entries in the database

write_database

Writing the database to file

append_to_database

Append an entry to the database

• param array @_ - elements to add to the database

URL Processing

is_html

Retrieve the header of the given URL to see if it contains HTML code

• param string $url - the url to check
• returns boolean - true if url contains HTML, false if not

grab_page

get the page for the specified URL -- possibly only a fragment

• param string $url - the url to grab
• returns string - contents of page

description:

Uses curl (command line version) to pull over the contents of the specified URL. The curl command is set to be silent, unless the command fails. Other parameters to the curl command include the output file name, the user agent string, a connect timeout and a max timeout, and to follow relocation headers (302s) from the web server.

get_title

Pull the title from the contents and clean it up

• param string $content -- the contents of the web page
• returns string -- the cleaned up and presentable title

find_url

Extract the url from the message text

• param string $text - the contents of the IRC message we're processing
• return string - the URL extracted, or undef otherwise

find_url will match on the text for various URL schemes (currently only supporting FTP and HTTP). In addition, if the bareword "www" precedes a triple-word, it is treated as an HTTP URL and modified accordingly.

pass_filter

Check to see if the url passes various filters

• param object $server - current server object
• param string $target - name of current channel/query
• param string $url - current url
• returns boolean - true if it passes filters, false if not

showtitle

Main logic of the script -- display the title of a given URL on either the target's channel, or to the user's screen

• param object $server - the server where the URL was shown
• param string $msg - the data from the current irc message
• param string $target - the current window

showtitle checks the message to see if it contains a valid URL string (currently only ftp: and http: are supported). showtitle will also match if the string begins with "www". It then checks to see if the URL contains an HTML content type.

Command Processing

is_validuser

Checks to see if calling user is in the list of valid users

• param string $user - user to validate
• param string $chatnet - current chatnet
• param string $channel - current channel
• returns boolean - whether user is valid or not

process_listen

Process an !st listen on/off request

• param string $status - whether to turn listening on or off
• param object $server
• param string $nick - user sending request
• param string $address - address of nick sending request
• param string $target - channel or query originating request
• returns void

show_listen

List the current channels being listened to for urls

• param object $server
• param string $nick
• param string $address
• param string $target

listen_help

    Provide help to the calling user, sent as private message.

• param object $server
• param string $nick
• param string $address
• param string $target

show_listen_status

Show whether the current chatnet/channel is being listened to

• param object $server
• param string $nick
• param string $address
• param string $target

add_filter

Add a filter to the current channel. Filters are treated as regexes. If a filter is specified as "qr/.../", then it will be evaled as is, if it isn't, then "qr/" and "/" will be wrapped around what ever is given.

• param string $filter -- the filter to add
• param object $server
• param string $nick
• param string $address
• param string $target

delete_filter

Deletes a given filter. Filters are regexes. If a filter is specifed with "qr/.../" then it is used as is. Otherwise "qr/" and "/" are wrapped around teh filter text and it is evaled.

• param string $filter -- the filter to delete
• param object $server
• param string $nick
• param string $address
• param string $target

show_filters

Give a list of filters on the current channel

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

filter_help

Send help messages to calling nick as private messages

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

show_filter_status

Show what the current filter status is on channel (on or off)

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

add_user

Add a user to the authorized users list for this channel

• param string $user -- user to add to authorized user's list (currently is host part of their hostmask)
• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

delete_user

Remove a user to the authorized users list for this channel

• param string $user -- user to remove to authorized user's list (currently is host part of their hostmask)
• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

list_users

Show the current set of authorized users for the chatnet/channel

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

user_request

Send a user request to the owner of the bot to add to authorized users

• param string $user -- user to remove to authorized user's list (currently is host part of their hostmask)
• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

user_help

Send help info to requesting user as private messages

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

show_user_status

Say whether the requesting user is an authorized user or not

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

showtitle_help

Send help info to requesting user as private messages

• param object $server - current server object
• param string $nick - nick of person making request
• param string $address - address of person making request
• param string $target - channel/query to send to

parse_command jump table

A jump table to determine which subroutine to use to process the command

process_command

process the command given with the st trigger

• param object $server - current server object
• param string $msg - command from channel
• param string $nick - requesting user
• param string $address - address of requesting user
• param string $target - name of channel/query
• returns void

ignored

returns true if the current chatnet/channel is being ignored

• param object $server - current server object
• param string $target - name of current channel/query
• returns boolean

sig_showtitle

Process the signals from a channel for showtitle requests and URLs

• param object $server - current server object
• param string $msg - message received
• param string $nick - user who send the message
• param string $address - address of user
• param string $target - name of channel/query sending message
• returns void

sig_own_showtitle

Process the signals from self for showtitle requests and URLs

• param object $server - current server object
• param string $msg - message sent
• param string $target - name of channel/query sending message to
• returns void

UI commands

cmd_stuser

Dispatch the appropriate user command.

• param string $data - data from the command
• param object $server - current server object
• param object $witem - current window item
• returns void

cmd_stuser uses the Irssi::command_runsub to dispatch the appropriate subcommand based on the first word in the $data string. Commands include:

• add -- add a user
• delete -- remove a user
• list -- list users

cmd_stuser_add

Add a user to the authorized user list for a given channel and chatnet

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the user to add as:

/stuser add [[[chatnet] channel] hostmask]

cmd_stuser_delete

Delete a user based on chatnet, channel and/or hostmask

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the user to delete as:

/stuser delete [[[chatnet] channel] hostmask]

cmd_stuser_list

List the current set of users

• param string $data - command line data
• param object $server - current server object
• param object $witem - current window object

cmd_stfilter

Dispatch the appropriate filter command.

• param string $data - data from the command
• param object $server - current server object
• param object $witem - current window item
• returns void

cmd_stfilter uses the Irssi::command_runsub to dispatch the appropriate subcommand based on the first word in the $data string. Commands include:

• add -- add a filter
• delete -- remove a filter
• list -- list filters

cmd_stfilter_add

Add a filter to the authorized filter list for a given channel and chatnet

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the filter to add as:

/stfilter add [[[chatnet] channel] hostmask] [qr/]regex[/]

cmd_stfilter_delete

Delete a filter to the authorized filter list for a given channel and chatnet

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the filter to delete as:

/stfilter delete [[[chatnet] channel] hostmask] [qr/]regex[/]

cmd_stfilter_list

List the current set of filters

• param string $data - command line data
• param object $server - current server object
• param object $witem - current window object

cmd_stlisten

Dispatch the appropriate listen command.

• param string $data - data from the command
• param object $server - current server object
• param object $witem - current window item
• returns void

cmd_stlisten uses the Irssi::command_runsub to dispatch the appropriate subcommand based on the first word in the $data string. Commands include:

• on -- add a channel to listen on
• off -- remove a channel from listening
• list -- list channels listened to

cmd_stlisten_on

Turn on listening for the specified chatnet/channel

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the listen channel as:

/stlisten on [[chatnet] channel]

cmd_stlisten_off

Turn off listening on the specified chatnet/channel

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the filter to delete as:

/stlisten off [[chatnet] channel]

cmd_stlisten_list

List the channels being listened to

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

cmd_stignore

Dispatch the appropriate ignore command.

• param string $data - data from the command
• param object $server - current server object
• param object $witem - current window item
• returns void

cmd_stignore uses the Irssi::command_runsub to dispatch the appropriate subcommand based on the first word in the $data string. Commands include:

• on -- add a filter
• off -- remove a filter
• list -- list filters

cmd_stignore_on

Turn on ignore for a given chatnet/channel

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the filter to delete as:

/stignore on [[chatnet] channel]

cmd_stignore_off

Stop ignoring a given chatnet/channel

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

The user can specify the filter to delete as:

/stignore off [[chatnet] channel]

cmd_stignore_list

Show the channels being ignored

• param string $data - data string from command line
• param object $server - current server object
• param object $witem - current window object

cmd_save

Save the database

cmd_ststatus

Give a current status of everything.

cmd_debug

Turn debugging on or off

Usage: /stdebug [on|off]

on - turn on debugging

off - turn off debugging

omitted - show current debugging status