IRC:exec

IRC Script Executive

"exec" is a bot that runs in a CLI that connects to the Soylent IRC server (irc.sylnt.us:6697) and executes other programs and facilitates their interaction with IRC.

Quick start

/invite exec (must be channel op)
~sed on|off
[nick[:] ]s/old/new[/[g]] (similar to SedBot, regex not supported)
~part (bot leaves channel)
~list (lists available commands)
~list-auth (lists available commands requiring NickServ account authorization)
~define term
~define-add term, meaning
~isup host[:port] (checks connection, returns http status if found)
~rainbow text
~translate tolang text (auto-detects source lang, eg: ~translate en prueba)
~translate-sl fromlang tolang text (eg: ~translate-sl es en prueba)
~time location
~weather location
~weather-add name location (enables storing a short name to refer to a longer location description when using ~weather)
~queue (returns number of SN submissions in the queue)
~lock alias|~unlock (treats all lines entered as being prefixed with alias, channel-specific)

Commands requiring NickServ account authorization

~wiki login
~wiki title[|section] (gets [section] content)
~wiki edit title|section|text
~wiki edit title|section| (deletes section)
~wiki logout

~suggest text (currently appends to a section in the [[SoylentNews:Sandbox]] page)

~q
~rehash
~ps
~kill
~dest-override
~dest-clear
~buckets-dump
~buckets-save
~buckets-load
~buckets-flush
~buckets-list
~restart
~say
~bucket

~define-source-edit
~define-source-param

~sedbot-ii (manually start ii for SedBot2)
~sedbot-cmd (manually perform ii command for SedBot2, such as /j #channel)
~sedbot-awk1 (manually start SedBot2 awk script for #soylent)
~sedbot-awk2 (manually start SedBot2 awk script for ##)
~sedbot-awk3 (manually start SedBot2 awk script for #test)
~sedbot-tail0 (manually start logging ii non-channel-specific messages, no output to IRC)
~sedbot-tail1 (manually start logging ii #soylent messages, no output to IRC)
~sedbot-tail2 (manually start logging ii ## messages, no output to IRC)
~sedbot-tail3 (manually start logging ii #test messages, no output to IRC)
~sedbot-talk1 (say something as SedBot2 in #soylent)
~sedbot-talk2 (say something as SedBot2 in ##)
~sedbot-talk3 (say something as SedBot2 in #test)

Bot details

Input to a script/program is via command line arguments only. Communication with a program through stdin is supported, but only using a similar syntax to IRC messages and currently stdin is used only to respond to bucket get messages (php scripts can use the lib.php get_bucket function).

stdout of an executed script/program may be passed to an IRC channel or output to exec's stdout (terminal), depending on the value of auto-privmsg in the exec line. If auto-privmsg=0, stdout from the script/program must begin with IRC_MSG or IRC_RAW for it to be sent to IRC. If auto-privmsg=1, all stdout from the script/program is assumed to be prefixed with IRC_MSG and is sent to IRC; this is generally required for programs that can't be easily edited, such as shell binaries (cowsay, fortune, etc).

Programs executed may be anything accessible from the CLI of the machine running the exec script. They may be shell programs (such as cowsay and fortune), php scripts (executed using the CLI php command) or scripts in any other language executable by their respective CLI interpreters (python, perl, haskell, etc).

Bot development

Developer(s): crutchy

Source: https://github.com/crutchy-/test

Files:

• https://github.com/crutchy-/test/blob/master/irc.php
• https://github.com/crutchy-/test/blob/master/exec.txt

Download above files from github, open a terminal and change to that directory, and run "php irc.php".

Scripts may be stored anywhere that is accessible to the bot script for CLI execution. If stored in a different location, the script path must be included in the exec file line.

Buckets

"Buckets" are a feature of exec that allow scripts to store data in a common location which is accessible from any script and is retained/persistent between script executions. Each bucket consists of an array element in the main bot program that is read, written and cleared using IRC-like commands (see below) passed through stdout/stdin pipes from/to executed scripts - buckets are filled by pipes hahaha :-P

Complex data in array form may be stored using php's serialize/unserialize (or equivalent in other languages).

Buckets are referenced by an index string.

:exec BUCKET_GET :index
:exec BUCKET_SET :index data
:exec BUCKET_UNSET :index

For PHP scripts, there are get_bucket, set_bucket and unset_bucket functions available in lib.php, which can be found here: https://github.com/crutchy-/test/blob/master/scripts/lib.php

Administration commands

A whois command is issued to verify the account name of a user identified with NickServ for authentication purposes.

Some functions are restricted for use by accounts in a hardcoded admin account list.

exec.txt

The exec.txt file resides in the same directory as the bot script (irc.php) file and links aliases (triggers typed in IRC) to scripts to be executed, and contains usage parameters and restrictions.

Syntax

alias|timeout|repeat|auto-privmsg|empty-trailing-allowed|account-list|cmd-list|dest-list|shell-cmd

Parameters

alias is the trigger typed in IRC at the start of a message that will trigger a script to be executed.

• All aliases should start with a common trigger character (such as ~).
• Aliases must be unique, but multiple scripts may be executed per alias by separating shell commands with &&.
• The aliases *, <init> and <quit> are reserved and have special meanings to the bot.
• The * reserved alias occurs on every IRC message received. The exec bot in Soylent IRC uses a single script for this alias. cmd.php is executed on every line and contains a switch statement to dispatch internal trigger messages on various IRC events (such as numerics, PRIVMSG, NOTICE, JOIN, PART, NICK, etc). The bot then parses these internal messages to further trigger other scripts.
• The <<init>> reserved alias is triggered on bot startup before the IRC connection is made. It is useful for initializing data buckets for particular scripts. Buckets and internal trigger messages may be called at this point, but IRC functionality is not yet available.
• The <<quit>> reserved alias is triggered on bot shutdown and restart. IRC functionality is still available to this alias script. It is useful for saving data buckets to file so that data can persist when the bot is restarted.

A non-zero timeout is the number of seconds a script is allowed to run for before being terminated by the bot.

• If a script times out a message is sent to the destination from which the alias was triggered to inform the user.
• It is always a good idea to set a timeout to prevent infinite loops in scripts from chewing up bot host resources.
• A timeout of 5 seconds is typical except for http-enabled scripts which sometimes require more time to complete.

A non-zero repeat is the number of seconds between each automated alias trigger.

• Aliases with repeats may still be triggered manually.
• The first trigger will occur after the repeat has elapsed on startup (repeat triggers don't trigger immediately on startup).

auto-privmsg may be 0 or 1.

• A value of 1 will automatically privmsg every line of text output to a script's stdout or stderr so must be used with caution.
• This is useful for running programs that aren't scripted, such as compiled binaries that can't be changed (apt-get, fortune, etc).
• A value of 0 won't privmsg stdout/stderr and is required if a script needs to triggger other commands, send customized messages to IRC or use buckets.

empty-trailing-allowed may be 0 or 1.

• A value of 1 will allow an alias to trigger if there is no text following the alias.
• A value of 0 will require more text after the alias.
• If an alias requires more text and a user enters only the alias itself with no other text, a privmsg is sent to inform the user.
• If there is a chance that an alias may be entered without further text without intending to trigger the bot, this should be set to 0 and if need be handled silently within the triggered script.

account-list is a comma-delimited list of NickServ account names permitted to trigger the alias.

• If a user attempts to trigger an account-restricted alias and their account isn't listed or they aren't identified with NickServ, a message is output to the terminal but not to IRC.
• An empty list is unrestricted.

cmd-list is a comma-delimited list of commands that the alias may be triggered on, including IRC commands (PRIVMSG, NOTICE, NICK, etc) but also internal and bucket commands intercepted by the bot (INTERNAL, BUCKET_GET, etc).

• Attempts to trigger a cmd-restricted alias on an unspecified cmd fail silently.
• An empty list is unrestricted.

dest-list is a comma-delimited list of destinations that the alias may be triggered from, including channel names and nicks.

• Attempts to trigger a dest-restricted alias from an unspecified destination fail silently.
• An empty list is unrestricted.

shell-cmd is the cli command executed in a separate process by the bot when the assocated alias is triggered and all requirements are met.

Notes

• %%trailing%% excludes alias
• aliases here must be all lower case letters
• cmd list and dest list is not case sensitive, but conventionally use uppercase for cmd
• account, cmd and dest lists are all comma-separated
• set cmd list to PRIVMSG to enable alias to only be called by PRIVMSG cmd (NOTICE etc won't trigger)
• set dest list to #soylent to restrict triggering of alias to the #soylent channel (can also use a nick to restrict to PM)

Available exec templates

• %%trailing%% = the message string visible in an IRC client
• %%dest%% = the channel/pm nick where the message originated
• %%nick%% = the nickname of the sender
• %%start%% = microtime(True) result when bot was started
• %%alias%% = the command alias that triggered the script
• %%cmd%% = the IRC command (PRIVMSG,NOTICE,QUIT,PART,NICK,JOIN,numeric,etc)
• %%data%% = the entire IRC line (refer below)
• %%exec%% = the exec line for the trigger alias
• %%params%% = the params part of the IRC line (refer below; usually same as %%dest%% except when %%cmd%% is a numeric)

IRC line syntax:

:<prefix> <command> <params> :<trailing>

Script development

PHP script template

https://github.com/crutchy-/test/blob/master/script_template.php

If anyone is interested in adding their own script, talk to crutchy (usually hangs out in #soylent and #test) who will be happy to help as best he can.

IRC commands

IRC commands maybe manually constructed by echoing a string to stdout using the ":<prefix> <command> <params> :<trailing>" syntax, but there is also a selection of shortcuts available to make scripting easier. The following commands may be called using a "/command <trailing>" syntax.

Usage in IRC

To invoke a script in IRC client:

alias [trailing]

Example:

<crutchy> ~define atlantic ocean
  <exec> 1 | noun | the 2nd largest ocean; separates North and South America on the west from Europe and Africa on the east\n2 | adjective | relating to or bordering the Atlantic Ocean

In the above example, "~define" is the alias, "atlantic ocean" is passed to the script as %%trailing%% and can be accessed in PHP scripts using the $argv global array variable.

Feeds Feed sources

IRCiv

See IRCiv.

Weather script

Developer(s): crutchy

Source: https://github.com/crutchy-/test/blob/master/scripts/weather.php

Available commands:

• ~weather location
• ~weather-add code location

note: ~weather-add code location will change the location of the code if the code has already been entered. Currently, codes cannot be deleted.

A few thousand ICAO and IATA/FAA airport codes have been imported into the codes file thanks to OpenFlights.

Usage examples

<crutchy> ~weather
<exec> IRC WEATHER INFORMATION BOT
<exec>   usage: "~weather location" (visit http://wiki.soylentnews.org/wiki/IRC:exec#Weather_script for more info)
<exec>   data courtesy of the APRS Citizen Weather Observer Program (CWOP) @ http://weather.gladstonefamily.net/
<exec>   by crutchy: https://github.com/crutchy-/test/blob/master/scripts/weather.php

<crutchy> ~weather JFK
<exec> Weather for Brooklyn, NY US at 2014-04-14 03:36:00 (UTC) ~ 0.8 hrs ago:
<exec>     temperature = 66°F (18.9°C)    dewpoint = 56.3°F (13.5°C)
<exec>     barometric pressure = 1017.3 mb ~ change of 0 mb over past 0.2 hrs    relative humdity = 71%
<exec>     wind speed = 1 mph (1.6 km/h)    wind direction = 336°

<kobach> ~weather vostok, aq
<exec> Weather for Vostok Station (RUS), -, Antarctica (the territory South of 60 deg S) at 2014-04-14 12:00:00 (UTC) ~ 0.8 hrs ago:
<exec>     temperature = -83.7°F (-64.3°C)    dewpoint = -90.9°F (-68.3°C)
<exec>     barometric pressure = 948.9 mb ~ change of 1.6 mb over past 6 hrs    relative humdity = 57%
<exec>     wind speed = 10 mph (16 km/h)    wind direction = 200°

<crutchy> ~weather-add crutchy melbourne australia
<exec> code "crutchy" set for location "melbourne australia"

<crutchy> ~weather crutchy
<exec> Weather for Melbourne Regional Office, VIC, Australia at 2014-04-14 11:00:00 (UTC) ~ 0.8 hrs ago:
<exec>     temperature = 60.4°F (15.8°C)    dewpoint = 50.2°F (10.1°C)
<exec>     barometric pressure = 1023.5 mb ~ change of -1.4 mb over past 3 hrs    relative humdity = 68%
<exec>     wind speed = (no data)    wind direction = 0°

exec in irc.sylnt.us

exec is running in a screen terminal on a debian squeeze box in crutchy's home (so not high bandwidth or availability).

development mostly happens using gedit in a debian virtual box on a laptop, with changes being pushed to github from there and also rsync'ed to the squeeze box running the bot.