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:
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.
| 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. |
| users | Returns a list of users in a channel. |
| privilege | Returns the privilege level (operator, voiced, etc.) for a channel member. |
| 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. |
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.
| 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. |
| 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 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.
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.
These methods are included for your convenience. They will help make writing your leaf easier.
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. |
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. |
| 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. |
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.