Difference between revisions of "LizardIRC/Beancounter"

From LizardWiki, FastLizard4's wiki and website
Jump to: navigation, search
m (Reformat)
(Move commands listing to another page, add section for non-command feachers)
 
(13 intermediate revisions by 2 users not shown)
Line 13: Line 13:
 
'''Latest development version:'''<br />
 
'''Latest development version:'''<br />
 
<span style="font-size: smaller; color: #F00;">'''WARNING: May be buggy and largely untested!'''</span><br />
 
<span style="font-size: smaller; color: #F00;">'''WARNING: May be buggy and largely untested!'''</span><br />
<big>0.0.1-SNAPSHOT</big> [[File:Download.svg|40px|link=https://integration.fastlizard4.org:444/jenkins/job/lizardirc-beancounter/Development%20(UNSTABLE)/artifact/target/beancounter-0.0.1-SNAPSHOT.jar|Download development build]] [[File:Jenkins logo.svg|40px|link=https://integration.fastlizard4.org:444/jenkins/job/lizardirc-beancounter/Development%20(UNSTABLE)/|View build info on Jenkins]]
+
{| style="vertical-align: middle; margin: auto;"
 +
|-
 +
|| <big>0.0.1-SNAPSHOT</big> || [[File:Download.svg|40px|link=https://integration.fastlizard4.org:444/jenkins/job/lizardirc-beancounter/Development%20(UNSTABLE)/artifact/target/beancounter-0.0.1-SNAPSHOT.jar|Download development build]] || [[File:Jenkins logo.svg|40px|link=https://integration.fastlizard4.org:444/jenkins/job/lizardirc-beancounter/Development%20(UNSTABLE)/|View build info on Jenkins]]
 +
|}
 +
 
 +
----
 +
 
 +
'''Source code:'''<br />
 +
{| style="vertical-align: middle; margin: auto;"
 +
|-
 +
|| [[File:Git icon.svg|40px|link=https://git.fastlizard4.org/gitblit/summary/?r=LizardIRC/Beancounter.git|On LizardNet Code Review]] || [[File:GitHub logo 2013.svg|50px|link=https://github.com/LizardNet/LizardIRC-Beancounter|On GitHub]]
 +
|}
 
</div>
 
</div>
  
 
'''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 [[w:Uno (card game)|Uno]] and [http://inedo.com/release Release!]).
 
'''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 [[w:Uno (card game)|Uno]] and [http://inedo.com/release Release!]).
  
The project is lead 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.
+
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.
  
 
__TOC__
 
__TOC__
Line 104: 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.AdminListener
+
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.AdminListener
+
Changes the bot's nickname to ''nickname'' immediately.
+
 
+
=== join ===
+
* '''Usage:''' <code>join [''channel'']</code>
+
* '''Permission needed:''' join
+
* '''Implemented by:''' org.lizardirc.beancounter.AdminListener
+
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.AdminListener
+
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.AdminListener
+
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.AdminListener
+
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.AdminListener
+
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.DiceListener
+
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.DiceListener
+
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.DiceListener
+
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.SlapListener
+
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.SlapListener
+
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.RouletteListener
+
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 RouletteListener 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 individaully.
+
 
+
=== reload ===
+
* '''Usage: In channel only:''' <code>reload {[''bullets''] {[''chambers'']<nowiki>}}</nowiki></code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.RouletteListener
+
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 RouletteListener 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 individaully.
+
 
+
=== spin ===
+
* '''Usage: In channel only:''' <code>spin</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.RouletteListener
+
Beancounter spins the barrel in its Russian Roulette gun. This may delay the inevitable, but it never prevents it.
+
 
+
Note that RouletteListener 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 individaully.
+
 
+
=== poulette ===
+
* '''Usage: In channel only:''' <code>poulette</code>
+
* '''Permission needed:''' ''(none)''
+
* '''Implemented by:''' org.lizardirc.beancounter.RouletteListener
+
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.BreadBasedAccessControlListener
+
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.BreadBasedAccessControlListener
+
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 specifieda s 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 specicial 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.BreadBasedAccessControlListener
+
(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.UserLastSeenListener.UserLastSeenCommandListener
+
* '''Note: The commit that provides this command is still awaiting review and has not yet been merged.'''
+
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.UserLastSeenListener.UserLastSeenCommandListener
+
* '''Note: The commit that provides this command is still awaiting review and has not yet been merged.'''
+
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.UserLastSeenListener.UserLastSeenCommandListener
+
* '''Note: The commit that provides this command is still awaiting review and has not yet been merged.'''
+
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.
+

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!