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.
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).
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.
- Clone with Git (recommended):
git clone https://gerrit.fastlizard4.org/r/p/LizardIRC/Beancounter.git
- 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:
- GitHub Mirror: LizardNet/LizardIRC-Beancounter
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.
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.
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.
For a list of all commands the bot supports, please see here.
Other Non-Command Feachers
- 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
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!