(return to the Hazelnut "Getting Started")

A sample config file is show below, this is similar to what's included in the default Hazelnut download:

The above is sometimes called a "properties" file. The idea behind using it is that it provides an easy way to store configuration for Hazelnut in format that is very easy to understand. Below we'll break down the various parts of the format followed by the sections in the default config file.

Contents 1 Syntax 1.1 Blank Lines 1.2 Comments 1.3 Entries 1.3.1 List Entries 2 Sections 2.1 IRC information 2.1.1 Name 2.1.2 Password 2.1.3 Prefix 2.1.4 Server 2.1.5 Channels 2.1.6 ChanKeys 2.2 Hazelnut Framework Information 2.2.1 Logging 2.2.2 Auth 2.2.3 AuthTest 2.2.4 AuthCode 2.2.5 Plugins 2.3 Plugin Information

Syntax

The basic format is very easy. It has the following syntax elements:

Blank Lines

Blank lines will always be ignored and can be used as spacers.

Comments

Any line that starts with a pound/number sign is ignored:

Otherwise valid properties syntax can be put in a comment line and it will still be ignored.

Entries

An entry consists of a "key" and a "value". The key is a case-sensitive* name for an entry and it is what the program will look up. They work as follows:

For these type of properties, there is only one value per key.

* Be careful of this, as "thisThat" is not the same as "thisthat". However the default properties used by Hazelnut are loaded case-insensitively, so in the previous example the keys "thisThat" and "thisthat" would loaded as "thisthat".

List Entries

Some entries may require a list of items. Properties doesn't have a built in list syntax, however, separating values with commas is common (and easy) enough:

There's a problem if the comma separated values need to contain commas themselves, so it is up the code using a specific property to handle this appropriately (if necessary). Using CSV format is one option (quoting values with commas) but no built-in support is provided for this.

Sections

This is a break down of the various sections of the config file, what they're for, and how they're used.

IRC information

This is information pertaining to the framework and IRC. Most of the information in this section is required, but some is optional.

Name

This is the name the bot is known as on the server it joins. This is subject to change if someone is already using that name. If the name is in use, the bot will keep adding the next number in a sequence to name specified in this file until a name not in use is found.

There are certain characters which cannot be contained in names, however it is just easier (and shorter) to list those which can be used: `^_[]{} and a to z This list may vary from server to server, so it's generally best to avoid using characters in name.

This field is required.

Password

Some IRC networks allow ownership of names, and people can register them to password protect their name. If a bot is set up to use a registered name, filling in this field will tell the framework to tell IRC that we really are the owner of this name.

Using a registered name without setting this field can have some consequences on IRC. Freenode, for example, will automatically change your name for you after a set amount of time if you do not log into the account for that name.

This field is optional.

Prefix

Prefix is the character or characters that can be used to tell the bot you are talking to him. A bot can always be addressed using his name, this is just a shorter way of doing so, mainly for convenience.

This field is required, as not having a prefix may allow the bot to unintentionally respond to anything.

Server

This is the server to which the framework will connect. No protocol is required, just the server name. Ex: irc.mozilla.org or irc.freenode.net

This field is required.

Channels

Channels is a list of channels the framework should join once it connects to the server. Channels can be listed in any order.

This field is optional, as the framework could join the server only to be talked to in private chats.

ChanKeys

This is a list of keys to to the previous channels. Some channels are password protected such that only those who know the password (or key) can join it. For those channels, the framework needs to know what the key is. The channel keys need to be listed in the same order as the channels above. Any channel that doesn't have a key needs to be skipped with an empty entry. It may just be easier to put all the channels with keys first in the channel list.

This field is optional.

Hazelnut Framework Information

This is information related to the framework and features provided by it.

Logging

Logging refers to what the bot "logs" or outputs and how much it outputs. There is no support for saving this output to a file built into Hazelnut, however, piping can be employed by the operating system to do so.

Example of running the bot and sending the output to a file on Windows, then Linux/Unix variants:

When logging to a file, it doesn't matter which launch file is used ("-debug" or normal) as all output is redirected to the file. Normally, the non-"-debug" launch file runs in the background which doesn't send any output to the console.

Hazelnut (for the moment) has three levels of logging: all, err, none. Leaving the property empty is the same as specifying none, but it is better to specify it in case this behavior changes in later releases.

• all - All output from IRC and exceptions thrown by any code being run are printed
• err - Only exceptions are printed (simple useful for debugging)
• none - no/minimal output

Auth

Auth is short for "authority" and it is a list names considered to be an administrator for the bot. Any people listed here have ability to add others to the framework's built in auth system, and manage other functions such as forcing the bot to quit the network. The people listed in this field must have a registered name with the network the framework is currently on, and they must be identified with services.

If this field is left blank, any auth-dependent features and default will be disabled, with one exception. The default "quit" plugin will work even with no names listed. This is to allow for easy testing of the framework. If auth names are specified, the quit plugin will behave as normal.

This field is optional.

AuthTest

AuthTest is short for "authority test" and it the string that is used to figure out if someone is identified with the network services. If the network has no "nickserv" or other similar services, just leave this line blank and no checking will be done. This value is simply matched against lines returned from a standard WHOIS to the server. If text matching isn't flexible enough, the value can be wrapped in forward slashes and it will be treated as a regular expression.

Text matching example:

Regular expressions example:

Regex flags can be used here, shown here with the case-insensitive flag.

This field is optional, but recommended.

AuthCode

AuthCode is short for "authority codes" and it is a comma separated list of "codes" which correspond to those assigned to various types of replies from the server. The codes listed here are specifically those which specifically correspond to responses containing information on a user's identification status with network services. Server responses with any of these codes will be matched against the previous value.

This field is manditorially optional. It is necessary only if there is an auth-test value provided, but it won't hurt to leave it if there isn't one.

Plugins

This field is a list of all plugins to load by default when the bot starts up. This list is not mutable, and any plugins which are removed or added while the bot is running will not be remembered.

This field is optional, but if no plugins are loaded, only default framework-based plugins will be available.

Plugin Information

Some plugins may have options or other configuration items they require. This is a place to specify those items so they can be retrieved when the plugin is loaded.

The various plugins should mention what fields are required versus optional ones.