Difference between revisions of "LizardIRC/Beancounter"

From LizardWiki, FastLizard4's wiki and website
Jump to: navigation, search
m (plumbum)
(Commands: Document the listchans and cfginvites commands)
Line 387: Line 387:
 
*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.
 
*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.
 
*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.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.)

Revision as of 22:07, 7 October 2015

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

Following is a list of all commands currently supported in Beancounter.

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.

The commands are listed in no particular order.

There are three ways you can give a command to a Beancounter:

  • In channel: Either using the fantasyString prefix (e.g., if the fantasyString is ?, you could give the "quit" command by saying ?quit in the channel)
  • In channel: Addressing the bot directly (e.g., if the Beancounter's nickname is PaulaBeancounter, you could give the "quit" command by saying PaulaBeancounter: quit)
  • 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 /msg PaulaBeancounter quit)

For the usage information, angle brackets are used to denote a choice between specific argument values (for example, acl <grant|revoke> means "type either 'acl grant' or 'acl revoke'"); brackets ([]) are used to denote free-form arguments; braces ({}) surround optional arguments (otherwise, arguments are required). No brackets surrounding a value means that you must enter that value verbatim.

Arguments to commands are space-delimited; however, in general, the final argument to any command may contain spaces.

quit

  • Usage: quit {[quit message]}
  • Permission needed: quit
  • Implemented by: org.lizardirc.beancounter.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: nick [nickname]
  • Permission needed: nick
  • Implemented by: org.lizardirc.beancounter.AdminHandler

Changes the bot's nickname to nickname immediately.

join

  • Usage: join [channel]
  • Permission needed: join
  • Implemented by: org.lizardirc.beancounter.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: part {[channel] {[part message]}}
    • In private message: part [channel] {[part message]}
  • Permission needed: part
  • Implemented by: org.lizardirc.beancounter.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: say {[channel]} {[message]}
    • In private message: say [user/channel] {[message]}
  • Permission needed: say
  • Implemented by: org.lizardirc.beancounter.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: act {[channel]} {[message]}
    • In private message: act [user/channel] {[message]}
  • Permission needed: say
  • Implemented by: org.lizardirc.beancounter.AdminHandler

Instructs the bot to act the message (analogous to the /me 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: raw [raw IRC line]
  • Permission needed: raw
  • Implemented by: org.lizardirc.beancounter.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: coin
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.DiceHandler

Flips a coin, and reports "heads" or "tails" back to the caller.

dice / roll

  • Usage: dice {{[N]d}[X]} {{[N]d}[X]} {...}
  • Aliases: roll
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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 NdX, 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 "Nd" 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:

  • dice 1d6 (default) - roll 1 6-sided die
  • dice 6 - roll 1 6-sided die
  • dice 1d20 - roll 1 20-sided die
  • dice 20 - roll 1 20-sided die
  • dice 5d15 - roll 5 15-sided dice
  • dice 3d20 5d7 6 3 - roll 3 20-sided dice, 5 7-sided dice, 1 6-sided die, and 1 3-sided die
  • dice 8d - 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: more
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: slap {[user]}
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: * Beancounter defenestrates FastLizard4 with a large trout

cfgslap

  • Usage:
    • cfgslap <add|remove> <actions|modifiers|items|item_mods> [what]
    • cfgslap list <actions|modifiers|items|item_mods>
  • Permission needed: cfgslap
  • Implemented by: org.lizardirc.beancounter.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 withitem

Furthermore, the item may contain format string elements for the item modifier: %s is replaced with the item modifier, and %2$s 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: roulette
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: reload {[bullets] {[chambers]}}
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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 channeluntil 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: spin
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: poulette
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: myperms
  • 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: acl list <roles|permissions> {available}
  • 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:
    • acl <grant|revoke> roles [hostmask-regex] [role]
    • acl <grant|revoke> permissions [role] [permission]
    • acl revokeAll roles [role]
    • acl revokeAll permissions [permission]
    • acl delete hostmask [hostmask-regex]
    • acl delete role [role]
  • Permission needed: acl
  • Implemented by: org.lizardirc.beancounter.security.BreadBasedAccessControl.BreadBasedAccessControlHandler

(TODO: Long-form documentation for this)

rehash

  • Usage: rehash
  • Permission needed: rehash
  • Implemented by: org.lizardirc.beancounter.Listeners

Reloads all listeners. Usually only useful when debugging after hotswapping a classfile.

seen

  • Usage: seen [nickname]
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.UserLastSeenListener.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: cfgseen istracked
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.UserLastSeenListener.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:
    • cfgseen <track|notrack> [channel]
    • cfgseen list
  • Permission needed: cfgseen
  • Implemented by: org.lizardirc.beancounter.UserLastSeenListener.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: help
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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: commands
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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 command.
  • Usage: weather {[location]}
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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 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., KCALOSAN205) 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.)

setlocation

  • Usage: setlocation {[location]}
  • Permission needed: (none)
  • Implemented by: org.lizardirc.beancounter.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:
    • cfgweather <show|enable|disable|alertsenable|alertsdisable>
    • cfgweather <apisetkey|apisetdayrate|apisetminuterate|apisetburst> [operand]
  • Permission needed: cfgweather
  • Implemented by: org.lizardirc.beancounter.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 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 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 cfgweather show 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 weather.enable 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.

cfgweather show 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: cfgweather apisetkey [apikey]
  • The daily rate limit you wish to enforce: cfgweather apisetdayrate [daily limit] (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: cfgweather apisetminuterate [minutely limit] (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 cfgweather enable, and disable it again by running cfgweather disable. If trying to run the enable command produces a "configuration incomplete" error, try using the cfgweather show 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 cfgweather alertsenable command and disable it using the cfgweather alertsdisable 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 cfgweather apisetburst [burst size] 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: listchans
  • Permission needed: listchans
  • Implemented by: org.lizardirc.beancounter.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: cfginvites
  • 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: cfginvites <accept|reject>
  • 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 /invite 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.)