Autumn methods

The Autumn::Leaf and Autumn::Stem classes have a lot of methods; however, that’s no need to get intimidated! Here’s the full list of methods you should care about:

Stem Actions

These methods allow your leaf to perform IRC tasks, such as joining and leaving a channel or promoting a user to operator. Due to the nature of IRC, all of these actions fail silently on error. The only way to tell if your action was successful is to override a hook method (see below).

You can call these methods on any Autumn::Stem instance. Generally, the stem instance is provided to you, as a parameter for a hook method, for instance. You can also access all of a leaf’s stems with the stems attribute.

Performing actions

message	Sends a message to a channel or person (or list thereof). The most basic and most important IRC action.
set_topic	Sets the topic of a channel.
join_channel	Joins an IRC channel.
leave_channel	Leaves an IRC channel.
change_nick	Changes the leaf’s IRC nickname.
grant_user_privilege	Grants a privilege (such as voice or operator) to a channel member.
remove_user_privilege	Revokes a privilege from a channel member.
grant_usermode	Grants a usermode (such as invisible or wallops) to a nick.
remove_usermode	Revokes a usermode.
set_channel_property	Sets a channel property (such as moderated or password-protected).
unset_channel_property	Removes a channel property.

Getting information

users	Returns a list of users in a channel.
privilege	Returns the privilege level (operator, voiced, etc.) for a channel member.

Other methods

channel?	Returns true if a string is a valid channel name.
nick?	Returns true if a string is a valid nickname.
ready?	Returns true if the stem has fully initialized, logged into the IRC server, and joined all its channels.

Invoked (Hook) Methods

These Autumn::Leaf methods are for you to override. They are called when certain IRC events occur. If you need your leaf to respond to an IRC event, you override this method and specify your leaf’s response. Unless otherwise indicated in the API, the default behavior for each of these methods is to do nothing. Therefore, it isn’t necessary to call super when you override these methods.

Leaf events

will_start_up	Called just before the leaf is run.
did_start_up	Called just after the leaf has finished starting up and is ready to accept commands.
will_quit	Called just before the leaf begins shutting down.

IRC events

did_receive_private_message	Called when the leaf receives a private message.
did_receive_channel_message	Called when a message is sent to a channel the leaf is in.
someone_did_join_channel	Called when someone joins a channel the leaf is in.
someone_did_leave_channel	Called when someone leaves a channel the leaf is in.
someone_did_gain_privilege	Called when someone is promoted in a channel the leaf is in.
someone_did_lose_privilege	Called when someone is demoted in a channel the leaf is in.
channel_did_gain_property	Called when a channel mode is added to a channel the leaf is in.
channel_did_lose_property	Called when a channel mode is removed from a channel the leaf is in.
someone_did_gain_usermode	Called when a nick gains a usermode.
someone_did_lose_usermode	Called when a nick loses a usermode.
someone_did_change_topic	Called when a topic is changed for a channel the leaf is in.
someone_did_invite	Called when someone (generally the leaf itself) is invited into a channel.
someone_did_kick	Called when someone is kicked from a channel the leaf is in.
did_receive_notice	Called when the leaf receives a server notice.
nick_did_change	Called when someone in a channel with the leaf changes his nick.
someone_did_quit	Called when someone in a channel with the leaf exits from the server.

IRC errors

IRC errors are handled by the stem. You should see the Autumn::Stem#add_listener documentation for full details, but there are a number of IRC responses and errors, as well as server messages and errors, that you can trap if you need to.

As an example, if you wanted to trap NAMES responses, you would implement a method in your leaf like so:

irc_rpl_namreply_response(stem, sender, recipient, arguments, msg)

The phrase “rpl_namreply” is defined in the resources/daemons/RFC1459.yml file. You can implement a method named after any such IRC reply.

Errors are handled similarly; to be alerted in the event that your nickname is in use:

irc_err_nicknameinuse_response(stem, sender, recipient, arguments, msg)

Note that Stem already has a system for claiming stolen nicks, so there’s no need to handle this situation. You could implement this method if there were something else you wanted to do in addition, however.

This is just the tip of the iceberg; please see the add_listener method docs for complete details.

CTCP requests and responses

The Autumn::CTCP class is a listener plugin that gives other listeners the ability to send CTCP requests, listen for CTCP requests, and send CTCP replies. It is included by default to all stems, so its features are available to your leaf.

To receive a CTCP request, implement a method like so:

ctcp_version_request(handler, stem, sender, arguments)

You can then send a response with a call like:

stem.ctcp_reply_version sender, 'My Awesome Bot v2.0'

To send your own CTCP request, you simply call a stem method like so:

stem.ctcp_time 'Sancho'

And listen for his response by implementing:

ctcp_time_response(handler, stem, sender, arguments)

For full details, see the Autumn::CTCP class docs.

Helper and Utility Methods

These methods are included for your convenience. They will help make writing your leaf easier.

Persistent store

For more information, see Storing persistent data.

database

Executes the block in the context of your leaf’s database. See the class docs for details — normally this is not necessary, however, in some situations it may be.

Filters

For more information, see the README.

before_filter	Adds a filter to be run before each IRC command.
after_filter	Adds a filter to be run after each IRC command.

Leaf configuration

options	Returns a hash of options configured for this leaf. See the README for a complete list of options.
stems	Returns an array of Stem instances this leaf is listening to. You can call methods on this array as if it were one Stem instance; all stems will receive the method, and their responses will be collected into an array, passed back to you. If you only have one stem for your leaf (as is generally the case), you can call Stem methods directly, as if they were methods of your Leaf instance.

IRC Commands

These methods are IRC commands that are included in all leaves by default. If there are commands you wish to remove from your leaf, you can use the remove_method method. If you want alternate behavior from your leaf, simply override these methods with your own.

quit_command	The leaf responds to !quit by exiting the stem.
reload_command	The leaf responds to !reload by reloading the source code in the leaves and support directories.
autumn_command	The leaf responds to !autumn by displaying information about the version of Autumn running the leaf.
commands_command	The leaf responds to !commands by displaying a list of commands the leaf will listen for.

New leaves, by default, are configured to restrict the !quit and !reload commands to channel ops and higher. See the README for more information.