Difference between revisions of "LizardIRC/Beancounter"

From LizardWiki, FastLizard4's wiki and website
Jump to: navigation, search
(Commands: Document new commands, update package/class names)
(Move commands listing to another page, add section for non-command feachers)
 
Line 115: Line 115:
  
 
== Commands ==
 
== Commands ==
Following is a list of all commands currently supported in Beancounter.
+
For a list of all commands the bot supports, please see [https://www.lizardirc.org/index.php?page=beancounterCommands here].
  
Unless otherwise noted, all commands on this page are available in master branch. Releases that introduce a given command will probably be noted when we have releases.
+
== Other Non-Command Feachers ==
 +
=== SedListener ===
 +
*'''Provided by:''' org.lizardirc.beancounter.commands.sed.SedListener
 +
SedListener allows users to use <code>[[w:sed|sed]]</code>-like replacement sequences to make corrections to the messages they and others have sent to a channel.  The bot maintains a queue of 5 most recent messages per user per channel that can be corrected using <code>sed</code>'s <code>s</code> (regular expression replacement) and <code>y</code> (transliteration) operators. Example usage:
  
The commands are listed in no particular order.
+
<pre>
 
+
19:47:45 <~FastLizard4> Hello world!
There are three ways you can give a command to a Beancounter:
+
19:47:49 <+hubot> Hello human!
* In channel: Either using the fantasyString prefix (e.g., if the fantasyString is <code>?</code>, you could give the "quit" command by saying <code>?quit</code> in the channel)
+
19:47:52 <~FastLizard4> s/world/bot/
* In channel: Addressing the bot directly (e.g., if the Beancounter's nickname is PaulaBeancounter, you could give the "quit" command by saying <code>PaulaBeancounter: quit</code>)
+
19:47:52 <+Beancounter> FastLizard4 meant to say: Hello bot!
* In private message: Simply lead your message with the command (e.g., if the Beancounter's nickname is PaulaBeancounter, you would give the "quit" command by doing <code>/msg PaulaBeancounter quit</code>)
+
19:48:07 <~FastLizard4> hubot: y/l/1/
 
+
19:48:07 <+Beancounter> FastLizard4 thinks hubot meant to say: He11o human!
For the usage information, angle brackets are used to denote a choice between specific argument values (for example, <code>acl <grant|revoke></code> means "type either 'acl grant' or 'acl revoke'"); brackets (<code>[]</code>) are used to denote free-form arguments; braces (<code>{}</code>) surround optional arguments (otherwise, arguments are required). No brackets surrounding a value means that you must enter that value verbatim.
+
</pre>
 
+
Arguments to commands are space-delimited; however, in general, the final argument to any command may contain spaces.
+
 
+
=== quit ===
+
* '''Usage:''' <code>quit {[''quit message'']}</code>
+
* '''Permission needed:''' quit
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Disconnects the bot from the IRC network. The ''quit message'', if provided, is given to the IRC server as the quit message, otherwise the default of "Tear in salami" is used.
+
 
+
=== nick ===
+
* '''Usage:''' <code>nick [''nickname'']</code>
+
* '''Permission needed:''' nick
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Changes the bot's nickname to ''nickname'' immediately.
+
 
+
=== join ===
+
* '''Usage:''' <code>join [''channel'']</code>
+
* '''Permission needed:''' join
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Instructs the bot to join the channel ''channel'' immediately. The bot will message the channel, indicating who asked it to join. The bot will remember the channel to be rejoined on next connect (unless it is kicked or parted from the channel).
+
 
+
=== part ===
+
* '''Usage:'''
+
** '''In channel:''' <code>part {[''channel''] {[''part message'']<nowiki>}}</nowiki></code>
+
** '''In private message:''' <code>part [''channel''] {[''part message'']}</code>
+
* '''Permission needed:''' part
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Instructs the bot to part the channel ''channel'' immediately. If the command is given in a channel with no arguments, it will part the channel the command was given in. Note that if given in a channel, you still must specify the channel name always if you want the bot to part with a custom message. The part message will always indicate who instructed the bot to part the channel. The bot will forget the channel from the list of channels to be rejoined on next connect (also happens if the bot is kicked from the channel).
+
 
+
=== say ===
+
* '''Usage:'''
+
** '''In channel:''' <code>say {[''channel'']} {[''message'']}</code>
+
** '''In private message:''' <code>say [''user/channel''] {[''message'']}</code>
+
* '''Permission needed:''' say
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Instructs the bot to send the ''message'' to the given ''user'' or ''channel''. If the command is given in a channel, the command may only target another channel, and if the first argument doesn't appear to be a valid channel name, the bot will target the channel the command was given in. If you wish to target a user directly (i.e., make the bot send a private message), you must give the command in a private message. When given in private message, the first argument (user or channel to target) is not optional.
+
 
+
=== act ===
+
* '''Usage:'''
+
** '''In channel:''' <code>act {[''channel'']} {[''message'']}</code>
+
** '''In private message:''' <code>act [''user/channel''] {[''message'']}</code>
+
* '''Permission needed:''' say
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Instructs the bot to act the ''message'' (analogous to the <code>/me</code> command in most IRC clients) to the given ''user'' or ''channel''. If the command is given in a channel, the command may only target another channel, and if the first argument doesn't appear to be a valid channel name, the bot will target the channel the command was given in. If you wish to target a user directly (i.e., make the bot send a private action), you must give the command in a private message. When given in private message, the first argument (user or channel to target) is not optional.
+
 
+
=== raw ===
+
* '''''WARNING: DANGEROUS COMMAND - USE WITH CAUTION!'''''
+
* '''Usage:''' <code>raw [''raw IRC line'']</code>
+
* '''Permission needed:''' raw
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Instructs the bot to pass the ''raw IRC line'' exactly as is to the IRC server. Proper usage of this command requires knowledge of the raw IRC protocol. Caution is advised; misuse of this command can cause undefined behavior in the bot.
+
 
+
=== coin ===
+
* '''Usage:''' <code>coin</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.dice.DiceHandler
+
Flips a coin, and reports "heads" or "tails" back to the caller.
+
 
+
=== dice / roll ===
+
* '''Usage:''' <code>dice <nowiki>{{</nowiki>[''N'']d}[''X'']} <nowiki>{{</nowiki>[''N'']d}[''X'']} {...}</code>
+
* '''Aliases:''' roll
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.dice.DiceHandler
+
Rolls ''N'' ''X''-sided dice and reports their sum back to the caller. For clarity, you specify the number of dice to roll and how many sides the die have in the format ''N''d''X'', where ''X'' is the number of sides the dice should have and ''N'' is how many dice with ''X'' sides you want to roll. You can leave off the "''N''d" and the bot will assume that you only want to roll one die, with ''X'' sides. You can chain multiple of these dice specs together. If there are no arguments, the bot assumes 1d6 (i.e., roll 1 6-sided die). Here are some concrete examples:
+
* <code>dice 1d6</code> (default) - roll 1 6-sided die
+
* <code>dice 6</code> - roll 1 6-sided die
+
* <code>dice 1d20</code> - roll 1 20-sided die
+
* <code>dice 20</code> - roll 1 20-sided die
+
* <code>dice 5d15</code> - roll 5 15-sided dice
+
* <code>dice 3d20 5d7 6 3</code> - roll 3 20-sided dice, 5 7-sided dice, 1 6-sided die, and 1 3-sided die
+
* <code>dice 8d</code> - Invalid syntax
+
Note that if multiple dice are thrown, the bot will only report their total. If you want to see the result of each throw, immediately follow your dice command with the "more" command (see below).
+
 
+
=== more ===
+
* '''Usage:''' <code>more</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.dice.DiceHandler
+
Shows more detail about the last time the dice command was used - i.e., shows the exact values that were rolled. Use with caution, as the bot might flood you out if you rolled a lot of dice!
+
 
+
=== slap ===
+
* '''Usage:''' <code>slap {[''user'']}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.slap.SlapHandler
+
Instructs the bot to viciously attack the given ''user''. ''user'' must be present in the channel the command is given in; if you specify a user that doesn't exist (or give the command in a private message), the bot will slap you! The output of the slap command is always given in the channel it was called in; if called in private message, the response will be in a private message back to you. Authorized users can configure the slap command; see the "cfgslap" command below.
+
 
+
Example output: <code>* Beancounter defenestrates FastLizard4 with a large trout</code>
+
 
+
=== cfgslap ===
+
* '''Usage:'''
+
** <code>cfgslap <add|remove> <actions|modifiers|items|item_mods> [''what'']</code>
+
** <code>cfgslap list <actions|modifiers|items|item_mods></code>
+
* '''Permission needed:''' cfgslap
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.slap.SlapHandler
+
The cfgslap command allows an authorized user to modify the responses given by the slap command.
+
 
+
A slap consists of the following four elements: an action, a modifier, an item, and an item modifier. The bot is guaranteed to always randomly choose both an action and an item from the list; however, for modifiers and item modifiers, it may randomly choose one or choose not to include one.
+
 
+
The slap is constructed in the following format: Beancounter ''action'' ''target'' ''modifier'' with''item''
+
 
+
Furthermore, the item may contain format string elements for the item modifier: <code>%s</code> is replaced with the item modifier, and <code>%2$s</code> is replaced with "n" if the item modifier starts with a vowel (useful for "a"/"an"). Here are some example items that demonstrate this: "a%2$s %s minnow", "Donald Trump's %s combover".
+
 
+
"cfgslap add" adds the given ''what'' to the appropriate list (actions, modifiers, items, or item modifiers), while "cfgslap remove" removes the given ''what'' from the appropriate list (must be an exact match). "cfgslap list" lists all items in the given list.
+
 
+
=== roulette ===
+
* '''Usage: In channel only:''' <code>roulette</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.roulette.RouletteHandler
+
Play a game of Russian Roulette with the bot. Beancounter hands you a gun; you pick it up, point it at your head, pull the trigger, and....
+
 
+
This command only works if given in a channel. If the bot has ops in the channel, it will kick you if you die. Either way, it reports back the result as a message too.
+
 
+
Beancounter has a variety of guns at its disposal; you can use the "reload" command (see below) to configure the gun. You can also use the "spin" command (see below) to instruct Beancounter to spin the barrel. Be advised, though, that spinning the barrel only delays the inevitable at best, and at worst....
+
 
+
Note that RouletteHandler is per-channel; that is, the gun's state (number of bullets, number of chambers, chamber position, etc.) is remembered for each channel the bot is in individually.
+
 
+
=== reload ===
+
* '''Usage: In channel only:''' <code>reload {[''bullets''] {[''chambers'']<nowiki>}}</nowiki></code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.roulette.RouletteHandler
+
Instructs Beancounter to empty then reload the gun for Russian Roulette. By default, Beancounter puts one bullet in a six-chamber gun; however, that can be changed by specifying the ''bullets'' and ''chambers'' arguments. Note that ''bullets'' must always be specified if you want to specify ''chambers'', and that these values persist ''for the channel''until the bot is restarted. That is to say, if in a channel you tell the bot to put six bullets in a 20-chamber gun ("reload 6 20") and then tell the bot to put 3 bullets in the gun ("reload 3"), it will still use a 20-chamber gun in response to "reload 3"; further, if after this you call "reload" with no arguments, it will once again put 3 bullets in a 20-chamber gun.
+
 
+
Note that RouletteHandler is per-channel; that is, the gun's state (number of bullets, number of chambers, chamber position, etc.) is remembered for each channel the bot is in individually.
+
 
+
=== spin ===
+
* '''Usage: In channel only:''' <code>spin</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.roulette.RouletteHandler
+
Beancounter spins the barrel in its Russian Roulette gun. This may delay the inevitable, but it never prevents it.
+
 
+
Note that RouletteHandler is per-channel; that is, the gun's state (number of bullets, number of chambers, chamber position, etc.) is remembered for each channel the bot is in individually.
+
 
+
=== poulette ===
+
* '''Usage: In channel only:''' <code>poulette</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.roulette.RouletteHandler
+
You want to play Russian Roulette with Beancounter, but you're drunk, so you accidentally pick up a chicken instead of Beancounter's gun, and pluck a feather instead of pulling the trigger.
+
 
+
=== myperms ===
+
* '''Usage:''' <code>myperms</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.security.BreadBasedAccessControl.BreadBasedAccessControlHandler
+
Gets the list of permissions you have currently granted to you. The permissions returned by this command are the same permissions noted in this documentation by the "permission needed" lines.
+
 
+
=== acl ===
+
 
+
==== acl list ====
+
* '''Usage:''' <code>acl list <roles|permissions> {available}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.security.BreadBasedAccessControl.BreadBasedAccessControlHandler
+
If the second argument is "roles", lists the complete mapping of hostmask regexes to the roles they are granted, or if the "available" flag is specified as the third parameter, lists all available roles. If the second argument is "permissions", lists the complete mapping of roles to the permissions each role is granted, or if the "available" flag is specified as the third parameters, lists all permissions the bot has seen used (though note that this list is only populated during permissions checks, so it may not include all available permissions; this documentation is the definitive list of all available permissions).
+
 
+
Unlike the other acl subcommands, "acl list" requires no special permissions to run.
+
 
+
==== acl grant/revoke/revokeall/delete ====
+
* '''Usage:'''
+
** <code>acl <grant|revoke> roles [''hostmask-regex''] [''role'']</code>
+
** <code>acl <grant|revoke> permissions [''role''] [''permission'']</code>
+
** <code>acl revokeAll roles [''role'']</code>
+
** <code>acl revokeAll permissions [''permission'']</code>
+
** <code>acl delete hostmask [''hostmask-regex'']</code>
+
** <code>acl delete role [''role'']</code>
+
* '''Permission needed:''' acl
+
* '''Implemented by:''' org.lizardirc.beancounter.security.BreadBasedAccessControl.BreadBasedAccessControlHandler
+
(TODO: Long-form documentation for this)
+
 
+
=== rehash ===
+
* '''Usage:''' <code>rehash</code>
+
* '''Permission needed:''' rehash
+
* '''Implemented by:''' org.lizardirc.beancounter.Listeners
+
Reloads all listeners. Usually only useful when debugging after hotswapping a classfile.
+
 
+
=== seen ===
+
* '''Usage:''' <code>seen [''nickname'']</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.seen.UserLastSeenCommandHandler
+
Queries the bot to ask when is the last time it saw ''nickname'' speak in a channel the bot tracks. Tracked channels include all public channels (i.e., without the "secret" channel mode, usually +s, set) that haven't been explicitly untracked using the "cfgseen" command (see below).
+
 
+
=== cfgseen ===
+
 
+
==== cfgseen istracked ====
+
* '''Usage: In channel only:''' <code>cfgseen istracked</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.seen.UserLastSeenCommandHandler
+
The "cfgseen istracked" command allows anyone to determine if the channel the command was issued in is tracked for the purposes of the "seen" command. The command will tell you if the channel is listed on the "do not track" list, and/or if it is untracked because it is marked secret (usually channel mode +s). Note that this command does not work in private messages, and will only tell you the status of the channel the command is given in; in this way, the bot protects secret/untracked channels from being exposed.
+
 
+
==== cfgseen track/notrack/list ====
+
* '''Usage:'''
+
** <code>cfgseen <track|notrack> [''channel'']</code>
+
** <code>cfgseen list</code>
+
* '''Permission needed:''' cfgseen
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.seen.UserLastSeenCommandHandler
+
These commands allow an authorized user to add ("cfgseen notrack") or remove ("cfgseen track") a channel from the "do not track" list for the "seen" command. They also allow an authorized user to get the entire list of untracked channels. The list action is limited to authorized users to protect the privacy of channels on the list; likewise, caution is advised when using these commands in a channel, but they may be used in a channel or in private message. Note that the "cfgseen list" command will ''not'' list channels that are untracked because they are marked as secret (channel mode +s usually); it only lists channels added using the "cfgseen notrack" command.
+
 
+
=== help ===
+
* '''Usage:''' <code>help</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.help.HelpHandler
+
Shows some basic help text, with a link to this page, the GitHub repository, and some information on the "commands" command (see below).
+
 
+
=== commands ===
+
* '''Usage:''' <code>commands</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.help.HelpHandler
+
Shows an alphabetical list of commands the bot is aware of.  Note that this may not be a complete list; the bot may have other commands and functionalities that are not listed here for a variety of reasons (technical, contextual, etc.).
+
 
+
=== weather ===
+
* '''''IMPORTANT: Special configuration is required to use this command in your own Beancounter.  Please read the documentation for the [[#cfgweather|cfgweather command]].'''''
+
* '''Usage:''' <code>weather {[''location'']}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.weather.WeatherHandler
+
* '''Note: This command may not be available or recognized depending on Beancounter configuration.'''
+
Displays the current weather at the given location.  The weather data is provided by [http://wunderground.com Weather Underground].  To use this feature on your own Beancounter bot, you'll need to purchase (free tiers are available) a Weather Underground API key (see documentation for the "cfgweather" command below).  ''Location'' can be almost anything; a city, an airport code, a ZIP code (or other postal code outside the U.S.), or a Weather Underground Personal Weather Station (PWS) identifier.  PWD IDs are useful for finding very-local results - for instance, you can go to the Weather Underground website and find the PWS closest to you, then pass its PWS ID (e.g., <code>KCALOSAN205</code>) as the argument to the weather command.  The ''location'' parameter is optional if you set a default location for yourself using the "setlocation" command (documented below).  If the ''location'' you provide can't be found in the Weather Underground location database, or if multiple matches are found for a given ''location'', the bot will ask you to clarify.
+
 
+
Note: Retrieving weather data counts against your Weather Underground API limits, one call per command usage that returns weather data.  Checking a location against the Location API does not, however.  (For example, if a location is not found or is ambiguous, there is no API cost as the bot only queries the Location API, not the actual weather data API.)
+
 
+
=== userweather ===
+
* '''''IMPORTANT: Special configuration is required to use this command in your own Beancounter.  Please read the documentation for the [[#cfgweather|cfgweather command]].'''''
+
* '''Usage: In channel only:''' <code>userweather [''nickname'']</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.weather.WeatherHandler
+
* '''Note: This command may not be available or recognized depending on Beancounter configuration.'''
+
 
+
Displays the current weather at the location of another IRC user given by ''nickname''.  The user must have used the "setlocation" command (see [[#setlocation|below]]) to set their default location for the userweather command to work on them.  In addition, since this command uses the same nickname fuzzy matching system used by the "slap" command, you can use abbreviations for ''nickname'', but as a consequence, this command must be run in a channel, and the user whose weather you want to query must also be in that channel.
+
 
+
Note: Retrieving weather data counts against your Weather Underground API limits, one call per command usage that returns weather data.
+
 
+
=== setlocation ===
+
* '''Usage:''' <code>setlocation {[''location'']}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.weather.WeatherHandler
+
* '''Note: This command may not be available or recognized depending on Beancounter configuration.'''
+
When the optional ''location'' parameter is provided, sets your default location to ''location''.  Like with the "weather" command (see above), ''location'' can be anything the Weather Underground Location API understands, including city names, airport codes, ZIP codes (and other postal codes outside the U.S.), and Weather Underground Personal Weather Station (PWS) identifiers.  Also as with the "weather" command, if the ''location'' you provide can't be resolved by the Weather Underground Location API, the bot will ask you to clarify instead of saving your default location choice.
+
 
+
When run without the ''location'' parameter, your default location is deleted.
+
 
+
Note: The setlocation command never counts against your Weather Underground API limits, as the Location API is not rate limited.
+
 
+
=== cfgweather ===
+
* '''Usage:'''
+
** <code>cfgweather <show|enable|disable|alertsenable|alertsdisable></code>
+
** <code>cfgweather <apisetkey|apisetdayrate|apisetminuterate|apisetburst> [''operand'']</code>
+
* '''Permission needed:''' cfgweather
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.weather.WeatherHandler
+
* '''Note: This command may not be available or recognized depending on Beancounter configuration.'''
+
This command is used to configure WeatherHandler, which must be done before you can use the "weather" command.
+
 
+
Before beginning, you should be advised of the following:
+
*Using WeatherHandler requires you to purchase a Weather Underground API key (free service tiers are available).  You can do so [http://www.wunderground.com/weather/api/d/pricing.html here], but be aware of the following caveats:
+
**You will need to create a Weather Underground user account if you don't already have one (requires you to provide your email address)
+
**To get an API key, you will need to provide information including your name, your country of residence, a contact email address, and a description of what you will be using your API key for.
+
**Beancounter's WeatherHandler is designed to use a Cumulus Plan API key, but will work with a Stratus Plan key with certain features unavailable.
+
**Beancounter does not require historical data access.
+
**Beancounter's WeatherHandler contains internal rate limiting logic to allow you to more finely control your API usage (or simply limit usage to the maximum provided by your API key.
+
**By acquiring an API key and enabling WeatherHandler in your Beancounter configuration, you are agreeing to the Weather Underground API's [http://www.wunderground.com/weather/api/d/terms.html Terms of Service], which include the following important provisions:
+
***You must not share your API keys with anyone (which is why none is provided with the bot's source code) - use caution when assigning the "cfgweather" permission since the <code>cfgweather show</code> command reveals the API key.
+
***You must not alter the bot's source code to remove the attribution of data to Weather Underground
+
 
+
By default, the WeatherHandler module is not loaded on bot startup, so the bot will not recognize the "weather", "setlocation", or "cfgweather" commands.  To use any of these commands, you must first enable the WeatherHandler by setting the <code>weather.enable</code> option to "true" in your Beancounter startup configuration file.  Be advised, though, that enabling WeatherHandler may constitute implicit agreement to the Terms of Service of the Weather Underground API.
+
 
+
Once WeatherHandler is enabled, the "weather" command will still be unavailable as you must complete setup on IRC.  To do so, you'll need to use the cfgweather command.
+
 
+
<code>cfgweather show</code> can be used to show the current WeatherHandler configuration, as well as the status of the WeatherHandler rate limiter.  To enable the "weather" command, the following information must be provided:
+
*Your Weather Underground API key: <code>cfgweather apisetkey [''apikey'']</code>
+
*The daily rate limit you wish to enforce: <code>cfgweather apisetdayrate [''daily limit'']</code> (note that ''daily limit'' must be an integer, and should not be greater than the number of daily calls the service level of your API key provides).
+
*The per-minute rate limit you wish to enforce: <code>cfgweather apisetminuterate [''minutely limit'']</code> (note that ''minutely limit'' must be an integer, and should not be greater than the number of calls-per-minute the service level of your API key provides).
+
 
+
Once you have provided these three configuration values, you can freely enable the "weather" command by running <code>cfgweather enable</code>, and disable it again by running <code>cfgweather disable</code>.  If trying to run the enable command produces a "configuration incomplete" error, try using the <code>cfgweather show</code> command to get a configuration dump and see what's missing.
+
 
+
There are other optional configuration values you can change using the cfgweather command:
+
*If your API key is on the Cumulus Plan or higher, you can enable the output of current severe weather alerts in addition to the current conditions data; enable this functionality using the <code>cfgweather alertsenable</code> command and disable it using the <code>cfgweather alertsdisable</code> command.  Changing this setting does not affect your API call usage (only one call is used per "weather" command usage, ever).  Note that enabling alerts when your API plan doesn't support it may result in undefined behavior at worst (and misleading information at best)! Alerts display defaults to disabled.
+
*The bot employs, in addition to the hard per-day and per-minute rate limits, a progressive rate limiter that fairly divides up unused API calls throughout the remainder of the day.  By default, the progressive rate limiter uses a burst size of 1 - that is, it allows for 1 API call before enforcing a progressive rate limit.  This effectively means that if there are, for example, 6000 seconds remaining until the end of the API day and you have 60 API calls remaining, you will be able to use the "weather" command once every 100 seconds.  You can, however, increase the burst size to allow for more API calls before the progressive rate limit is enforced by using the <code>cfgweather apisetburst [''burst size'']</code> command, where ''burst size'' is an integer greater than or equal to 1.  For example, if you set the burst size to 10 and have 6000 seconds remaining until the end of the API day with 60 API calls remaining, the bot will allow the "weather" command to be used 10 times before enforcing a 1000-second standoff (measured from the time of the first command in the "burst").  Setting the burst size to be equal to your daily API limit effectively disables the progressive rate limiter.  A recommended value for burst size is 5% to 10% of your daily API call allotment.
+
 
+
=== listchans ===
+
* '''Usage:''' <code>listchans</code>
+
* '''Permission needed:''' listchans
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.admin.AdminHandler
+
Returns a list of all channels the bot is currently in.  Restricted to authorized users as this command may expose secret/private channels.
+
 
+
=== cfginvites ===
+
==== cfginvites (no arguments) ====
+
* '''Usage:''' <code>cfginvites</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.InviteAcceptor.InviteAcceptorHandler
+
With no arguments, the cfginvites command allows any user to check if the bot will accept invitations to join channels.
+
 
+
==== cfginvites accept/reject ====
+
* '''Usage:''' <code>cfginvites <accept|reject></code>
+
* '''Permission needed:''' cfginvites
+
* '''Implemented by:''' org.lizardirc.beancounter.InviteAcceptor.InviteAcceptorHandler
+
In this form, the cfginvites command allows an authorized user to change whether or not the bot will accept invitations to join a channel.  When set to "accept", the bot will automatically join any channel it receives an invite (sent using the <code>/invite</code> IRC command).  When set to "reject", the bot will ignore invites.  Remember that the bot will remember channels it joins (including by accepting invites), and automatically rejoin them in the future on connect.  (Conversely, if the bot is kicked from a channel, it will be removed from the list of channels to automatically rejoin on connect.)
+
 
+
=== remind ===
+
* '''Usage:''' <code>remind [''nickname''] {in: [''time'']} [''message'']</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.remind.ReminderCommandHandler
+
*'''Note: Even though this command is included in current development releases of the bot, its syntax is not yet final and subject to change (in particular the syntax for scheduling a reminder to be delivered after a period of time).'''
+
This command allows you to send a reminder to another IRC user (to send a reminder to yourself, use the [[#remindme|remindme command]].  By default, the reminder will be delievered as soon as the target user joins or talks in a channel the bot is in.  To make the reminder deliver after a time delay, specify a time by including "in: ''time''" before the ''message'' but after the ''nickname''.  The colon (<code>:</code>) after "in" is important - without the colon, the bot will consider it part of the message.  The ''time'' delay is given in this format: 1y2d3h4m5s, meaning 1 year, 2 days, 3 hours, 4 minutes, and 5 seconds.  All fields of a ''time'' specification are optional; for example, "5h" is equivalent to "0y0d5h0m0s".  If when a timed reminder is scheduled to be delivered the target ''nickname'' is offline, the reminder will be retained until the user joins or talks in a channel the bot is in.  Timed reminders will never be delivered before their scheduled delivery time.  Reminders will always be delivered in the channel the remind command was given in; if the reminder was scheduled by private message, or the target user is not in that channel, the reminder will be delivered by private message.
+
 
+
Note that if the target ''nickname'' is online when the reminder is scheduled, their user@host will be recorded instead of their nickname and will be used for delivery of the reminder - this means that even if they change their nickname, they will still receive the reminder.
+
 
+
=== remindme ===
+
* '''Usage:''' <code>remindme {in: [''time'']} [''message'']</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.remind.ReminderCommandHandler
+
*'''Note: Even though this command is included in current development releases of the bot, its syntax is not yet final and subject to change (in particular the syntax for scheduling a reminder to be delivered after a period of time).'''
+
This command allows you to schedule a reminder for yourself.  It omits the ''nickname'' parameter (since it always targets yourself); but otherwise, it functions similarly to the [[#remind|remind command]].
+
 
+
=== cfgquakes ===
+
==== cfgquakes get ====
+
* '''Usage:''' <code>cfgquakes get {[''channel'']}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.earthquake.EarthquakeCommandHandler
+
This command allows you to see if the bot is reporting global earthquakes from one of the USGS's [http://earthquake.usgs.gov/earthquakes/ realtime earthquake feeds].  The ''channel'' argument is mandatory in PM, but optional when the command is given in a channel; when the argument is omitted in channel, the command defaults to the command the channel is given in.  If reporting is enabled, this command will also indicate which feed is driving the reporting for that channel.
+
 
+
==== cfgquakes getall/setchan/delchan ====
+
* '''Usage:'''
+
** <code>cfgquakes getall</code>
+
** <code>cfgquakes setchan <all|M1.0|M2.5|M4.5|significant> {[''channel'']}</code>
+
** <code>cfgquakes delchan {[''channel'']}</code>
+
* '''Permission needed:''' cfgquakes
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.earthquake.EarthquakeCommandHandler
+
The <code>cfgquakes getall</code> command allows an authorized user to view a list of all channels that have enabled earthquake reporting with Beancounter, and what feed they are using to drive reporting.  This is a privileged command to prevent exposure of private/secret channels to unauthorized users.
+
 
+
The <code>cfgquakes setchan</code> command allows one to enable earthquake reporting in a channel, or change the driving data source to a different feed for a channel that already has earthquake reporting enabled.  The first argument is an identifier for one the five USGS feeds the bot supports, in order: all earthquakes, earthquakes magnitude 1.0+, earthquakes magnitude 2.5+, earthquakes magnitude 4.5+, and significant earthquakes.  The second argument is an optional channel argument, which is mandatory when the command is used in PM but optional when the command is used in channel; in this case, it defaults to the channel the command is being given in.  Note that all feeds except the significant quakes feed can be quite spammy, the "all" and "M1.0" feeds especially so.
+
 
+
Finally, the <code>cfgquakes delchan</code> command allows one to completely disable earthquake reporting in a channel.  Its only argument, ''channel'', is the name of the channel to disable reporting in, and is mandatory in PM but optional when the command is given in-channel; in this case, it defaults to the channel the command is being given in.  Note that the bot will not remember which feed you were previously using.
+
 
+
For channels that have earthquake reporting enabled, the feeds are checked every five minutes.  Feed checks are global for the entire bot; that is, every five minutes, all feeds to be checked are checked and all channels with reporting enabled get updates together, regardless of when reporting was enabled in that channel.
+
 
+
=== lastquake ===
+
* '''Usage:''' <code>lastquake <all|M1.0|M2.5|M4.5|significant></code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.earthquake.EarthquakeCommandHandler
+
This command causes the bot to list the most recent earthquake given in the indicated feed.  The only argument to the command is the feed to be checked for earthquake data, with the five values representing the five different feeds available.  Those feeds are, in order, all earthquakes, earthquakes magnitude 1.0+, earthquakes magnitude 2.5+, earthquakes magnitude 4.5+, and significant earthquakes.  This command can be used in PM or any channel, regardless of whether automatic earthquake feed reporting is enabled with the <code>[[#cfgquakes|cfgquakes]]</code> command and independent of any such reporting.  Note that the feeds the bot uses are "last day" feeds, so if no applicable events have occurred within the last 24 hours, the command will report no data (this usually only happens with the "significant earthquakes" feed).  In addition, note that the bot bases "last earthquake" on the time of the earthquake itself, not the time of any updates issued for the earthquake information by the USGS.
+
 
+
All data is sourced from feeds [http://earthquake.usgs.gov/earthquakes/ provided by the United States Geological Survey].
+
 
+
=== LookOfDisapproval ===
+
* '''Usage:''' <code>lookofdisapproval {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs a look of disapproval (<tt>ಠ_ಠ</tt>), optionally directed at the given ''thing''.
+
 
+
=== Lenny ===
+
* '''Usage:''' <code>lenny {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs a Lenny face (<tt>( ͡° ͜ʖ ͡°)</tt>), optionally directed at the given ''thing''.
+
 
+
=== AngryLenny ===
+
* '''Usage:''' <code>angrylenny {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs an angry Lenny face (<tt>( ͠° ͟ʖ ͡°)</tt>), optionally directed at the given ''thing''.
+
 
+
=== LookOfLenny ===
+
* '''Usage:''' <code>lookoflenny {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs a Look of Lenny face (<tt>( ͡ಠ ʖ̯ ͡ಠ)</tt>), optionally directed at the given ''thing''.
+
 
+
=== TableFLIP ===
+
* '''Usage:''' <code>tableflip {[thing]}</code>
+
** '''Alternate usage:''' <code>fliptable {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs a flipped table, optionally also flipping the specified ''thing''.  Example: <tt>(╯°□°)╯︵ɹǝʇunoɔuɐǝq</tt>
+
 
+
=== Raise ===
+
* '''Usage:''' <code>raise {[thing]}</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.commands.faces.FaceHandler
+
Outputs <tt>ヽ༼ຈل͜ຈ༽ノ raise ''thing'' ヽ༼ຈل͜ຈ༽ノ</tt>; or if no ''thing'' is specified, raises dongers instead.
+

Latest revision as of 02:50, 6 May 2016

Latest stable release version:
Recommended download
(none)


Latest beta release version:
(none)


Latest development version:
WARNING: May be buggy and largely untested!

0.0.1-SNAPSHOT Download development build View build info on Jenkins

Source code:

On LizardNet Code Review On GitHub

Beancounter is LizardIRC's own custom bot. It is intended to have general purpose features, as well as eventually serve various games over IRC (planned such games include Uno and Release!).

The project is led by LizardIRC staffers FastLizard4 and TLUL, and though it was designed for use on the LizardIRC network, Beancounter is an open-source project licensed under the GNU GPL v3+ and will work on any IRC network. The bot is written in Java 8 and uses PircBotX as its IRC library. Primary development happens on LizardNet Code Review, but you can also find a read-only mirror of the project on GitHub.

Basic information

The latest version of the bot is 0.0.1-SNAPSHOT. The bot has no stable releases as it is still in alpha development. In general, running the tip of the bot's master Git branch should work, as we try to keep that working, though you should be prepared to update the bot rapidly should bug fixes be released.

A production instance of this bot runs as "Beancounter" on the LizardIRC network. Testing instances may also be running on the network under various names. Feel free to experiment with and play around with the bot!

Download your own

If you'd like to run your own Beancounter, perhaps for your own IRC network, please feel free to do so. Downloading your own is also the first step to contributing to the project!

There are two ways to run Beancounter: By grabbing a pre-built jarfile (easiest, but doesn't allow for modification of the source code), or by grabbing the source code and building your own (more difficult, but allows modification of the source code and contributing to the project).

Since the bot is written in Java, it is platform independent. It will run on Linux, Windows, Mac OS X, just about anything (provided that the Java SE Runtime Environment is available for your platform, which it probably is).

Pre-built JAR

To run Beancounter from a pre-built Jarfile, you'll need

  • The Java Standard Edition Runtime Environment 8 or greater (Oracle version can be downloaded from here) or Java Standard Edition Development Kit 8 or greater (Oracle version can be downloaded from here)
  • A copy of the bot.

Beancounter will not run in Java 7, Java 6, or earlier! (And if you only have Java 6 or 7, you really ought to upgrade anyway.)

The box in the upper-right corner of this page has links to the latest stable, beta, and development downloads of Beancounter (as of this writing, there have not yet been any stable or beta releases). The difference between the three are:

  • Stable versions have been thoroughly tested and reviewed and are the most likely to be free of bugs or serious defects; however, they are less likely to have recent additions to the bot for this reason.
  • Beta versions are more up-to-date with development of the bot, but likewise may be buggier and less thoroughly tested. That being said, they should work just fine.
  • Development versions are essentially the most up-to-date copies of the bot. They are the most up-to-date but also minimally tested - or possibly untested, and are likely to contain bugs. Note that development versions are not "bleeding edge" - that is, all development versions have gone through a review and tests of some kind.

As such, stable builds are probably the ones you will want to download. If you're interested in testing out new features, though, feel free to try the beta or development builds.

A full list of builds can be found on Jenkins here. In the build list, development builds are marked with a red star, beta builds are marked with a red star and an orange star, and stable builds have a red, orange, and green star. Builds without stars are bleeding builds, usually built automatically as a result of a patch submission, and should *not* be downloaded and run unless you know what you're doing!

Finally, stable builds will also be listed on our GitHub repository's Releases page.

Source code (build-your-own)

To build Beancounter from its source code, you'll need:

  • The Java Standard Edition Development Kit 8 (Oracle version can be downloaded from here; Linux users can also see here)
  • Apache Maven, version 3.0 or later recommended, or a Maven-compatible IDE (such as IntelliJ IDEA or Eclipse)
  • A copy of the bot's source code.

There are several ways you can download the bot's source code. If you have Git (the recommended way), you can clone the repository from LizardNet Code Review or GitHub; or you can download the source code in an archive file.

  • Git icon.svg Clone with Git (recommended): git clone https://gerrit.fastlizard4.org/r/p/LizardIRC/Beancounter.git
  • Download.svg Latest stable version direct download: ZIP archive | .tar.gz | .tar.bz2 | .tar.xz

We also maintain a read-only mirror of the project on GitHub:

However you grab the source code, you can then build a copy of the bot by using Maven with this command in the root folder of the bot's source code:

$ mvn package

This will automatically resolve and download the bot's dependencies and produce a file beancounter-VERSION.jar in the target folder, which you can then run.

Running the bot

Once you have the bot's jarfile (see above), running your own Beancounter is just a matter of passing the jarfile to java and following the prompts:

$ java -jar beancounter-0.0.1-SNAPSHOT.jar

Note for Windows users: Make sure you are using java.exe to run the bot, not javaw.exe, as the bot runs in a command line window. This means that you have to start the bot through a command prompt, not by double-clicking its .jar file icon!

The first time you run the bot, it will create a default configuration file and then exit. You should edit the configuration file to your needs (this is where you tell the bot what IRC network you want it to connect to, for example), then start the bot again.

You can specify a configuration file at a location other than the default (config.props in the same folder as the jarfile) by specifying it as a command line argument; for example:

$ java -jar beancounter-0.0.1-SNAPSHOT.jar myotherconfig.props

Once the bot has connected to IRC, all control functions are handled through IRC.

Contributing

Bug reports/feature requests/issues

If you found a bug and would like to report it, would like to request a feature, or have some other issue you'd like to bring up, you may do so in the Issues section of our GitHub repository.

Code

If you could like to contribute code yourself, there are a couple ways you could go about doing this.

If you are familiar with Gerrit Code Review, you can use LizardNet Code Review to directly submit patchsets to us for review. Note, though, that you'll need a LizardWiki account to submit code to LizardNet Code Review (if you don't have one, you can easily request one be created for you); see here for more information.

Alternatively, you can also fork the GitHub repository and submit a pull request; a Beancounter developer will copy your pull request to Gerrit for you if your pull request is approved.

Commands

For a list of all commands the bot supports, please see here.

Other Non-Command Feachers

SedListener

  • Provided by: org.lizardirc.beancounter.commands.sed.SedListener

SedListener allows users to use sed-like replacement sequences to make corrections to the messages they and others have sent to a channel. The bot maintains a queue of 5 most recent messages per user per channel that can be corrected using sed's s (regular expression replacement) and y (transliteration) operators. Example usage:

19:47:45 <~FastLizard4> Hello world!
19:47:49 <+hubot> Hello human!
19:47:52 <~FastLizard4> s/world/bot/
19:47:52 <+Beancounter> FastLizard4 meant to say: Hello bot!
19:48:07 <~FastLizard4> hubot: y/l/1/
19:48:07 <+Beancounter> FastLizard4 thinks hubot meant to say: He11o human!