Merge branch 'plugins' of http://git.louiz.org/poezio into plugins

doc/en/plugins.txt

@@ -0,0 +1,132 @@
+Plugins
+=======
+
+Currently, the plugins are in a plugin branch on the git repo.
+
+Location
+--------
+
+The plugins have to be present in '$XDG_DATA_HOME/poezio/plugins/plugin_name.py'
+(or '~/.local/share' if not defined)
+
+Structure
+---------
+
+A plugin must always be a class named Plugin that inherits the
+plugin.BasePlugin class defined into the *plugin* poezio module.
+
+Methods
+-------
+
+Overridden methods
+~~~~~~~~~~~~~~~~~~
+The *Plugin* class has several method that you can override for your own convenience
+
+[[init]]
+*init*:: +self+ +
+This method is called when the plugin is loaded, this is where you call
+the other methods, for example <<add-command,add_command>>, and initialize
+everything to make your plugin actually do something. <<example-1,ex 1>>, <<example-2,ex 2>>
+
+*cleanup*:: +self+ +
+Called when the plugin is unloaded (or when poezio is exited). Clean everything
+that needs to be cleaned here.
+
+Callable methods
+~~~~~~~~~~~~~~~~
+The BasePlugin has several methods that can be used. Here is a list of
+all its methods that you could use in your plugin, describing what they
+do, their arguments, and giving some example for each of them.
+
+[[add-command]]
+*add_command*:: +self+, +name+, +handler+, +help+, +completion=None+ + 
+This method adds a global command to poezio. For example you can add a /foo
+command that the user could call when the plugin is loaded, by calling this
+method with _foo_ as its _name_ argument. <<example-1,ex 1>>
+
+* _name_: (string) the name of the command (for example, if it is 'plugintest', it can
+add a /plugintest command)
+* _handler_: (function) the function to be called when the command is executed.
+the handler takes *args* as a parameter, which is a string of what
+is entered after the command. Split *args* (with _common.shell_split_) to use
+that as command arguments.
+* _help_: (string) the help message available for that command through the _/help_
+command.
+* _completion_: (function) the completion for the args of that command. It takes
+an input object as its only argument. This function should call the
+_auto_completion()_ method on the input object, passing a list of possible strings
+for the completion and returning the value of that call directly.
+Everything else is handled by that _auto_completion()_ method (checking what strings
+match, how to cycle between matches, etc). If you don’t want any special completion
+for that command, just pass None (the default value).
+
+*add_event_handler**: +self+, +event_name+, +handler+ +
+This methods adds a callback that will be called whenever the given event
+occurs. <<example-2,ex 2>>
+
+* _event_name_: (string) The name of the event you want to ``monitor''.
+This can be a sleekxmpp event, or a poezio event. See the list of
+<<events-list,all available events>>.
+* _handler_: The method that will be called whenever the event occurs.
+It must accept the arguments specified for that event in the <<events-list,events list>>.
+
+Attributes
+----------
+
+Config
+~~~~~~
+By default, each plugin has a PluginConfig object accessible with *self.config*.
+
+*PluginConfig.read*:: +self+ + 
+Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it is called upon initialization, so you should not need it.
+
+*PluginConfig.write*:: +self+ +
+Writes the config to the same file mentioned previously.
+
+Core
+~~~~
+Each plugin has a reference to the Core object accessible with *self.core*, that allows you to do about anything with poezio. Remember to use it only when you need it, and to use the functions described in this documentation only, even if much more is available. If your plugin needs to do something not available with these methods, please do a feature request instead of doing some dirty hacks with some other methods.
+
+Core methods
+^^^^^^^^^^^^
+CAUTION: TODO
+
+
+[[events-list]]
+Events list
+-----------
+CAUTION: TODO
+
+Examples
+--------
+
+[[example-1]]
+.Add a simple command that sends "Hello World!" into the conversation
+=====================================================================
+[source,python]
+---------------
+class Plugin(BasePlugin):
+    def init(self):
+    	self.add_command('hello', self.command_hello, "Usage: /hello\nHello: Send 'Hello World!'", None)
+
+    def command_hello(self, args):
+        self.core.send_message('Hello World!')
+---------------
+=====================================================================
+
+[[example-2]]
+
+.Adds an event handler that sends ``tg'' to a groupchat when a message is received from someone named ``Partauch''
+=====================================================================
+[source,python]
+---------------
+class Plugin(BasePlugin):
+    def init(self):
+    	self.add_event_handler('groupchat_message', self.on_groupchat_message)
+
+    def on_groupchat_message(self, message):
+        if message['mucnick'] == "Partauche":
+            self.core.send_message('tg', to=message.getMucroom())
+---------------
+=====================================================================
+

plugins/status.py

@@ -0,0 +1,21 @@
+from plugin import BasePlugin
+
+class Plugin(BasePlugin):
+    """
+    Adds several convenient aliases to /status command
+    """
+    def init(self):
+        self.add_command('dnd', lambda line: self.core.command_status('dnd '+line),
+                '/dnd [status message]\nDnd: Set your status as dnd (do not disturb).')
+        self.add_command('busy', lambda line: self.core.command_status('busy '+line),
+                '/busy [status message]\nBusy: Set your status as busy.')
+        self.add_command('chat', lambda line: self.core.command_status('chat '+line),
+                '/chat [status message]\nChat: Set your status as chatty.')
+        self.add_command('xa', lambda line: self.core.command_status('xa '+line),
+                '/xa [status message]\nXa: Set your status as xa (eXtended away).')
+        self.add_command('afk', lambda line: self.core.command_status('afk '+line),
+                '/afk [status message]\nAfk: Set your status as afk (away from keyboard).')
+        self.add_command('away', lambda line: self.core.command_status('away '+line),
+                '/away [status message]\nAway: Set your status as away.')
+        self.add_command('away', lambda line: self.core.command_status('away '+line),
+                '/available [status message]\nAvailable: Set your status as available.')

src/core.py

@@ -123,11 +123,7 @@ class Core(object):
             'prev': (self.rotate_rooms_left, _("Usage: /prev\nPrev: Go to the previous room."), None),
             'win': (self.command_win, _("Usage: /win <number>\nWin: Go to the specified room."), self.completion_win),
             'w': (self.command_win, _("Usage: /w <number>\nW: Go to the specified room."), self.completion_win),
-            'show': (self.command_status, _('Usage: /show <availability> [status message]\nShow: Sets your availability and (optionaly) your status message. The <availability> argument is one of \"available, chat, away, afk, dnd, busy, xa\" and the optional [status] argument will be your status message.'), self.completion_status),
             'status': (self.command_status, _('Usage: /status <availability> [status message]\nStatus: Sets your availability and (optionaly) your status message. The <availability> argument is one of \"available, chat, away, afk, dnd, busy, xa\" and the optional [status] argument will be your status message.'), self.completion_status),
-            'away': (self.command_away, _("Usage: /away [message]\nAway: Sets your availability to away and (optionaly) your status message. This is equivalent to '/status away [message]'"), None),
-            'busy': (self.command_busy, _("Usage: /busy [message]\nBusy: Sets your availability to busy and (optionaly) your status message. This is equivalent to '/status busy [message]'"), None),
-            'available': (self.command_avail, _("Usage: /available [message]\nAvailable: Sets your availability to available and (optionaly) your status message. This is equivalent to '/status available [message]'"), None),
            'bookmark': (self.command_bookmark, _("Usage: /bookmark [roomname][/nick]\nBookmark: Bookmark the specified room (you will then auto-join it on each poezio start). This commands uses the same syntaxe as /join. Type /help join for syntaxe examples. Note that when typing \"/bookmark\" on its own, the room will be bookmarked with the nickname you\'re currently using in this room (instead of default_nick)"), None),
             'set': (self.command_set, _("Usage: /set <option> [value]\nSet: Sets the value to the option in your configuration file. You can, for example, change your default nickname by doing `/set default_nick toto` or your resource with `/set resource blabla`. You can also set an empty value (nothing) by providing no [value] after <option>."), None),
             'theme': (self.command_theme, _('Usage: /theme\nTheme: Reload the theme defined in the config file.'), None),
@@ -1478,24 +1474,6 @@ class Core(object):
         msg = "%s=%s" % (option, value)
         self.information(msg, 'Info')
 
-    def command_away(self, arg):
-        """
-        /away [msg]
-        """
-        self.command_status("away "+arg)
-
-    def command_busy(self, arg):
-        """
-        /busy [msg]
-        """
-        self.command_status("busy "+arg)
-
-    def command_avail(self, arg):
-        """
-        /avail [msg]
-        """
-        self.command_status("available "+arg)
-
     def close_tab(self, tab=None):
         """
         Close the given tab. If None, close the current one