LizardIRC/Beancounter

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

0.0.1-SNAPSHOT

Source code:

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!

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!

Source code (build-your-own)

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.

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

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

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: