Tutorial: Your first bot

Making your own leaf using Autumn is easy. In this tutorial, I’ll show you how to make a simple Fortune bot that responds to a few basic commands.

Step 1: Subclass Leaf

Create a new leaf by typing script/generate leaf fortune. This will create a fortune.rb file in the leaves directory. Edit this file. First we’ll create an array to hold our fortunes:

FORTUNES = [
  "You will make someone happy today.",
  "Someone you don't expect will be important to you today.",
  "Today will bring unexpected hardships."
]

As you can see, our 3 meager fortunes are stored in the FORTUNES class constant. Now, we’ll want it to respond to the “!fortune” command, and all you have to do is create a method called fortune_command to make it work:

def fortune_command(stem, sender, reply_to, msg)
  FORTUNES.at_rand
end

The at_rand method is provided by Facets, so you’ll need to add a require 'facets/random' line at the top of your file. Our method returns a fortune at random, which is automatically transmitted to the channel or nick where the command was received.

Of course, any self-respecting fortune bot announces its presence when it starts up, so, in your Fortune class, override the did_start_up method to display a cheerful greeting:

def did_start_up
  stems.message 'FortuneBot at your service! Type "!fortune" to get your fortune!'
end

…and that’s it! You now have a fully functional fortune bot featuring — not two — but three unique and exciting fortunes!

(For more on that stems.message bit, see the README.)

Step 2: Add the Leaf to Your Season

If you want, you can add the fortune bot to your leaves.yml and stems.yml files to try it out. Adding a leaf is easy; simply duplicate the structure used for Scorekeeper’s entry and change the values as appropriate. A typical two-leaf configuration will look like:

Scorekeeper:
  class: Scorekeeper
  respond_to_private_messages: false
Fortune:
  class: Fortune
  respond_to_private_messages: true

As you notice, each leaf is given a name. In this example the name happens to be the same as the leaf’s class name, but you could run two copies of a leaf like so:

Fortune1:
  class: Fortune
Fortune2:
  class: Fortune
</code

We’ve created the leaf, but we have to add it to the stem for it to work. (Remember, a stem is an IRC connection and a leaf is a bot.) So, in your stems.yml file, add an entry for this leaf. Your new config will appear something like:

Example:
  nick: Scorekeeper
  leaves:
    - Scorekeeper
    - Fortune
  rejoin: true
  channel: somechannel
  server: irc.someserver.com

When you restart the server, Scorekeeper will come back online but will now
also respond to the “!fortune” command. This is a helpful tutorial on how stems
and leaves are separate. One leaf can have many stems, and one stem can have
many leaves. You can combine these two entities however you need.