smuxi_hooks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d5e13abb87b2be4c8d8be22897e8b89ba0a3b363
+  data.tar.gz: 1f72953d20a1fa2b2a3043f14f21456784a44bb5
+SHA512:
+  metadata.gz: 82eaac10c2e2bb499e170f48952f64e64fdab42b9c8477669f47415145e90568ea636adb5c18fdd43ef1da6661b29d6bc17d45635c5e6d85447a8eb134fe5376
+  data.tar.gz: 3ab9ff3a2f2154ffd2f28d284e72f5817e954f67f8446f317057681fb789595dd0c70034d1c26168f2f686d6bf7e32ef681a370e1ce35aa824ebc43bc7ec54aa

data/.gitignore

@@ -0,0 +1,12 @@
+# Project metadata
+nbproject
+.idea
+
+Gemfile.lock
+
+doc/api
+coverage
+pkg
+.yardoc
+.rbx
+*.rbc

data/.yardopts

@@ -0,0 +1,9 @@
+--output-dir=doc/api
+--embed-mixins
+--protected
+--no-private
+--markup-provider=redcarpet
+--markup=markdown
+-
+HISTORY.md
+LICENSE.md

data/Gemfile

@@ -0,0 +1,23 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+source 'http://rubygems.org'
+
+# Gem dependencies are specified in the .gemspec file
+gemspec

data/HISTORY.md

@@ -0,0 +1,6 @@
+0.1.0 / 2015-01-17
+==================
+
+* 1 major enhancement
+
+  * Birthday!

data/LICENSE.md

@@ -0,0 +1,15 @@
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+Smuxi hooks API for Ruby is licensed under the following ISC-style license:
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,226 @@
+Smuxi hooks API for Ruby
+========================
+
+[![Gem Version](https://badge.fury.io/rb/smuxi_hooks.png)](https://badge.fury.io/rb/smuxi_hooks)
+[![Dependency Status](https://gemnasium.com/godobject/smuxi-hooks-ruby.png)](https://gemnasium.com/godobject/smuxi-hooks-ruby)
+[![Code Climate](https://codeclimate.com/github/godobject/smuxi-hooks-ruby.png)](https://codeclimate.com/github/godobject/smuxi-hooks-ruby)
+
+* [Documentation][docs]
+* [Project][project]
+
+   [docs]:    http://rdoc.info/github/godobject/smuxi-hooks-ruby/
+   [project]: https://github.com/godobject/smuxi-hooks-ruby/
+
+Description
+-----------
+
+Plugin framework for the multi-protocol distributed chat client Smuxi.
+
+Features / Problems
+-------------------
+
+This project tries to conform to:
+
+* [Semantic Versioning (2.0.0)][semver]
+* [Ruby Packaging Standard (0.5-draft)][rps]
+* [Ruby Style Guide][style]
+* [Gem Packaging: Best Practices][gem]
+
+   [semver]: http://semver.org/
+   [rps]:    http://chneukirchen.github.com/rps/
+   [style]:  https://github.com/bbatsov/ruby-style-guide
+   [gem]:    http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices
+
+Additional facts:
+
+* Written purely in Ruby.
+* Documented with YARD.
+* Intended to be used with Ruby 1.9.3 or higher.
+* Cryptographically signed git tags.
+
+Shortcomings and problems:
+
+* Currently, not all of the hooks that are available in Smuxi are supported.
+* This library has NOT been tested extensively yet. With high probability
+  there are errors hidden in the code, these errors might even have
+  dangerous consequences for the security of your system. Please evaluate the
+  code thoroughly before using it on a production system.
+
+If you have solved any of these feel free to submit your changes back.
+
+Requirements
+------------
+
+* Ruby 1.9.3 or higher
+
+Installation
+------------
+
+On *nix systems you may need to prefix the command with `sudo` to get root
+privileges.
+
+### Gem
+
+    gem install smuxi_hooks
+
+Usage
+-----
+
+This documentation defines the public interface of the software. Don't rely
+on elements marked as private. Those should be hidden in the documentation
+by default.
+
+This is still experimental software, even the public interface may change
+substantially in future releases.
+
+### Ruby interface
+
+#### Loading
+
+In most cases you want to load the code by using the following command:
+
+~~~~~ ruby
+require 'smuxi_hooks'
+~~~~~
+
+In a bundler Gemfile you should use the following:
+
+~~~~~ ruby
+gem 'smuxi_hooks'
+~~~~~
+
+#### Namespace
+
+This project is contained within a namespace to avoid name collisions with
+other code. If you do not want to specifiy the namespace explicitly you can
+include it into the current scope by executing the following statement:
+
+~~~~~ ruby
+include GodObject::SmuxiHooks
+~~~~~
+
+#### Further information
+
+See the `examples` directory for working plugin examples.
+
+A custom plugin constists of only one file that can reside anywhere on the
+filesystem where the Smuxi has access to it. Plugins could therefore easily
+be published as separate gems.
+
+Warning: Please make sure that Smuxi is not able to modify the plugin file.
+
+To install a plugin on a Smuxi engine, you have to log into the user account,
+the engine runs as:
+
+  sudo -u smuxi examples/chat_logger.rb install
+
+Same goes for uninstalling:
+
+  sudo -u smuxi examples/chat_logger.rb uninstall
+
+Hopefully I will find some time to write some more substantial documentation
+soon.
+
+Development
+-----------
+
+### Bug reports and feature requests
+
+Please use the [issue tracker][issues] on github.com to let me know about errors
+or ideas for improvement of this software.
+
+   [issues]: https://github.com/godobject/smuxi-hooks-ruby/issues/
+
+### Source code
+
+#### Distribution
+
+This software is developed in the source code management system Git. There are
+several synchronized mirror repositories available:
+
+* [GitHub][github] (located in California, USA)
+    
+    URL: https://github.com/godobject/smuxi-hooks-ruby.git
+
+* [Gitorious][gitorious] (located in Norway)
+    
+    URL: https://git.gitorious.org/smuxi-hooks-ruby/smuxi-hooks-ruby.git
+
+* [BitBucket][bitbucket] (located in Colorado, USA)
+    
+    URL: https://bitbucket.org/godobject/smuxi-hooks-ruby.git
+
+* [Pikacode][pikacode] (located in France)
+
+    URL: https://pikacode.com/godobject/smuxi-hooks-ruby.git
+
+   [github]:    https://github.com/godobject/smuxi-hooks-ruby/
+   [gitorious]: https://gitorious.org/smuxi-hooks-ruby/smuxi-hooks-ruby/
+   [bitbucket]: https://bitbucket.org/godobject/smuxi-hooks-ruby/
+   [pikacode]:  https://pikacode.com/godobject/smuxi-hooks-ruby/
+
+You can get the latest source code with the following command, while
+exchanging the placeholder for one of the mirror URLs:
+
+    git clone MIRROR_URL
+
+#### Tags and cryptographic verification
+
+The final commit before each released gem version will be marked by a tag
+named like the version with a prefixed lower-case "v", as required by Semantic
+Versioning. Every tag will be signed by my [OpenPGP public key][openpgp] which
+enables you to verify your copy of the code cryptographically.
+
+   [openpgp]: https://aef.name/crypto/aef-openpgp.asc
+
+Add the key to your GnuPG keyring by the following command:
+
+    gpg --import aef-openpgp.asc
+
+This command will tell you if your code is of integrity and authentic:
+
+    git tag -v [TAG NAME]
+
+#### Building gems
+
+To package your state of the source code into a gem package use the following
+command:
+
+    rake build
+
+The gem will be generated according to the .gemspec file in the project root
+directory and will be placed into the pkg/ directory.
+
+### Contribution
+
+Help on making this software better is always very appreciated. If you want
+your changes to be included in the official release, please clone the project
+on github.com, create a named branch to commit, push your changes into it and
+send a pull request afterwards.
+
+Please make sure to write tests for your changes so that no one else will break
+them when changing other things. Also notice that an inclusion of your changes
+cannot be guaranteed before reviewing them.
+
+The following people were involved in development:
+
+* Alexander E. Fischer <aef@godobject.net>
+
+License
+-------
+
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'bundler/gem_tasks'
+require 'rake'
+require 'pathname'
+require 'yard'
+
+YARD::Rake::YardocTask.new('doc')
+
+desc "Removes temporary project files"
+task :clean do
+  %w{doc/api coverage pkg .yardoc .rbx Gemfile.lock}.map{|name| Pathname.new(name) }.each do |path|
+    path.rmtree if path.exist?
+  end
+
+  Pathname.glob('*.gem').each &:delete
+  Pathname.glob('**/*.rbc').each &:delete
+end
+
+desc "Opens an interactive console with the project code loaded"
+task :console do
+  Bundler.setup
+  require 'pry'
+  require 'smuxi_hooks'
+  Pry.start(GodObject::SmuxiHooks)
+end
+
+task default: :doc

data/examples/chat_logger.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'god_object/smuxi'
+
+class ChatLogger < GodObject::Smuxi::Plugin
+
+  LOG_FILE = Pathname.new('/tmp/smuxi_message_log')
+
+  def message_received
+    LOG_FILE.open('a') do |io|
+      io.puts("#@sender: #@message (#@protocol_manager_network #@chat_name)")
+    end
+  end
+
+  alias message_sent message_received
+
+end
+
+ChatLogger.execute(__FILE__) if __FILE__ == $PROGRAM_NAME

data/examples/keyword_catcher.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'god_object/smuxi'
+
+class KeywordCatcher < GodObject::Smuxi::Plugin
+
+  def message_sent
+    if @message.include?('keyword')
+      puts 'Keyword detected!'
+    end
+  end
+
+end
+
+KeywordCatcher.execute(__FILE__) if __FILE__ == $PROGRAM_NAME

data/examples/remember.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'god_object/smuxi'
+
+class Remember < GodObject::Smuxi::Plugin
+
+  MESSAGE_PATTERN = /remember: (?<data>.+)/
+  def message_sent
+    if result = MESSAGE_PATTERN.match(@message)
+      if state[:memory]
+        puts "Previous memory: #{state[:memory]}"
+      else
+        puts "No previous memory"
+      end
+
+      state[:memory] = result[:data]
+    end
+  end
+
+end
+
+Remember.execute(__FILE__) if __FILE__ == $PROGRAM_NAME

data/lib/god_object/smuxi_hooks.rb

@@ -0,0 +1,39 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+# Namespace for projects of the GodObject team <dev@godobject.net>.
+#
+# If you want to be able to simply type Example instead of GodObject::Example
+# to address classes in this namespace simply write the following before using
+# the classes.
+#
+# @example Including the namespace
+#   include GodObject
+# @see https://www.godobject.net/
+module GodObject
+
+  # Namespace for components of the "smuxi_hooks" library
+  module SmuxiHooks
+
+  end
+
+end
+
+require 'god_object/smuxi_hooks/version'
+require 'god_object/smuxi_hooks/plugin'

data/lib/god_object/smuxi_hooks/plugin.rb

@@ -0,0 +1,359 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'pathname'
+require 'set'
+require 'yaml'
+
+module GodObject
+  module SmuxiHooks
+
+    # Base class that implements basic features of a Smuxi plugin.
+    #
+    # @note This class is supposed to be an abstract base class and is not
+    #   meant to produce instances directly.
+    class Plugin
+
+      # @return [String] name of the base configuration directory
+      BASE_DIRECTORY_NAME = 'smuxi'
+
+      # @return [String] name of the sub-directory containing the hook handlers
+      HOOKS_DIRECTORY_NAME = 'hooks'
+
+      # @return [String] name of the sub-directory containing plugin state
+      STATE_DIRECTORY_NAME = 'hook-state'
+   
+      # @return [String] name of the file in which the permanent state is held
+      STATE_FILE_NAME = 'state.yml'
+
+      # @return [{String => Symbol}] maps Smuxi hook names to named of the
+      #   method supposed to handle that hook
+      HOOK_TABLE = {
+        'engine/protocol-manager/on-connected'        => :connected,
+        'engine/protocol-manager/on-disconnected'     => :disconnected,
+        'engine/protocol-manager/on-message-received' => :message_received,
+        'engine/protocol-manager/on-message-sent'     => :message_sent,
+        'engine/protocol-manager/on-presence-status-changed' => :presence_status_changed,
+        'engine/session/on-group-chat-person-added'   => :chat_person_added,
+        'engine/session/on-group-chat-person-removed' => :chat_person_removed,
+        'engine/session/on-group-chat-person-updated' => :chat_person_updated,
+        'engine/session/on-event-message'             => :event_message 
+      }
+
+      # @return [{String => Symbol}] maps Smuxi environment variable names to
+      #   instance variables which will inhert the value supplied by Smuxi
+      VARIABLE_TABLE = {
+        'SMUXI_CHAT_ID'   => :@chat_id,
+        'SMUXI_CHAT_NAME' => :@chat_name,
+        'SMUXI_CHAT_TYPE' => :@chat_type,
+        'SMUXI_MSG'                     => :@message,
+        'SMUXI_MSG_TYPE'                => :@message_type,
+        'SMUXI_MSG_TIMESTAMP_UNIX'      => :@message_timestamp_unix,
+        'SMUXI_MSG_TIMESTAMP_ISO_UTC'   => :@message_timestamp_iso_utc,
+        'SMUXI_MSG_TIMESTAMP_ISO_LOCAL' => :@message_timestamp_iso_local,
+        'SMUXI_SENDER'   => :@sender,
+        'SMUXI_RECEIVER' => :@receiver,
+        'SMUXI_PROTOCOL_MANAGER_TYPE'            => :@protocol_manager_type,
+        'SMUXI_PROTOCOL_MANAGER_PROTOCOL'        => :@protocol_manager_protocol,
+        'SMUXI_PROTOCOL_MANAGER_NETWORK'         => :@protocol_manager_network,
+        'SMUXI_PROTOCOL_MANAGER_HOST'            => :@protocol_manager_host,
+        'SMUXI_PROTOCOL_MANAGER_PORT'            => :@protocol_manager_port,
+        'SMUXI_PROTOCOL_MANAGER_ME_ID'           => :@protocol_manager_me_id,
+        'SMUXI_PROTOCOL_MANAGER_PRESENCE_STATUS' => :@protocol_manager_presence_status,
+        'SMUXI_PRESENCE_STATUS_CHANGED_OLD_STATUS'  => :@presence_status_old,
+        'SMUXI_PRESENCE_STATUS_CHANGED_NEW_STATUS'  => :@presence_status_new,
+        'SMUXI_PRESENCE_STATUS_CHANGED_NEW_MESSAGE' => :@presence_status_new_message,
+        'SMUXI_CMD'              => :@command,
+        'SMUXI_CMD_PARAMETER'    => :@command_parameter,
+        'SMUXI_CMD_CHARACTER'    => :@command_character,
+        'SMUXI_FRONTEND_VERSION' => :@frontend_version,
+        'SMUXI_ENGINE_VERSION'   => :@engine_version 
+      }
+
+      class << self
+
+        # Decides whether to execute a plugin hook handler or plugin maintenance
+        # features.
+        #
+        # In case the first command line argument is `install` or `uninstall`,
+        # the plugin installation or uninstallation maintenance methods are
+        # executed.
+        #
+        # Otherwise, the plugin expects to be called as a hook handler by Smuxi.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @param [{String => String}] environment the environment variables
+        #   available to the plugin, defaults to the actual system environment
+        # @param [Array<String>] arguments list of command line arguments given
+        #   to the plugin, defaults to the actual command line arguments
+        # @return [void]
+        def execute(executable_path, environment = ENV, arguments = ARGV)
+          case arguments.first
+          when 'install'
+            cli_install(executable_path)
+          when 'uninstall'
+            cli_uninstall(executable_path)
+          else
+            execute_hook(executable_path, environment)
+          end
+        end
+
+        # The name of the hook executed is detected through the name of the
+        # executable called. A plugin instance will be created and the hook
+        # name is then used to decide which instance method is called on that.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @param [{String => String}] environment the environment variables
+        #   available to the plugin, defaults to the actual system environment
+        # @return [void]
+        def execute_hook(executable_path, environment = ENV)
+          split_pattern = /\/#{BASE_DIRECTORY_NAME}\/#{HOOKS_DIRECTORY_NAME}\//
+          config_directory, relative_executable = executable_path.
+                                                  split(split_pattern)
+
+          base_directory      = Pathname.new(config_directory) +
+                                BASE_DIRECTORY_NAME
+          relative_executable = Pathname.new(relative_executable)
+          script_name         = relative_executable.basename.to_s
+          hook_name           = relative_executable.dirname.to_s
+          state_directory     = base_directory +
+                                STATE_DIRECTORY_NAME +
+                                hook_name +
+                                script_name
+
+          state_file = state_directory + STATE_FILE_NAME
+
+          if state_file.exist?
+            state = YAML.load(state_file.read)
+          else
+            state = {}
+          end
+
+          instance = new(
+            environment:     environment,
+            base_directory:  base_directory,
+            script_name:     script_name,
+            hook_name:       hook_name,
+            state_directory: state_directory,
+            state:           state
+          )
+
+          if method_name = HOOK_TABLE[hook_name]
+            instance.public_send(method_name)
+
+            state_file.open('w') do |io|
+              io.write(YAML.dump(instance.state))
+            end
+          else
+            raise "Hook `#{hook_name}` unsupported"
+          end
+        end
+
+        # Installs the plugin by placing symlinks to the plugin executable into
+        # Smuxi's hook handler paths.
+        #
+        # @note This method outputs to STDOUT and exits the program after it
+        #   finishes.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @return [void]
+        def cli_install(executable_path)
+          puts "Creating symlinks at the Smuxi plugin hook locations…"
+          puts
+
+          install(executable_path) do |hook_executable_file|
+            puts "Creating `#{hook_executable_file}`"
+          end
+
+          puts
+          puts "Plugin `#{name}` installed."
+
+          exit
+        end
+
+        # Uninstalls the plugin by removing symlinks to the plugin executable
+        # from Smuxi's hook handler paths.
+        #
+        # @note This method outputs to STDOUT and exits the program after it
+        #   finishes.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @return [void]
+        def cli_uninstall(executable_path)
+          puts "Trying to remove hook symlinks…"
+          puts
+          
+          uninstall(executable_path) do |hook_executable_file|
+            puts "Removing `#{hook_executable_file}`"
+          end
+
+          puts
+          puts "Plugin `#{name}` uninstalled."
+
+          exit
+        end
+
+        # @return [Pathname] path to the base directory
+        def base_directory_guess
+          Pathname.new('~/.local/share').expand_path + BASE_DIRECTORY_NAME
+        end
+
+        # @return [Array<Symbol>] a list of the names of all hook handler
+        #   instance methods implemented by this class
+        def used_hook_methods
+          instance_methods.to_set.intersection(HOOK_TABLE.values.to_set)
+        end
+
+        # @return [Array<String>] a list of the names of all hooks supported by
+        #   this class
+        def used_hook_names
+          inverted_hook_table = HOOK_TABLE.invert
+
+          used_hook_methods.map do |method_name|
+            inverted_hook_table[method_name]
+          end
+        end
+
+        # @return [Array<String>] a list of the Smuxi hook paths this plugin
+        #   needs to be linked in
+        # @param [Pathname] base_directory the Smuxi configuration directory.
+        #   The hooks directory is expected to reside here
+        def used_hook_paths(base_directory = base_directory_guess)
+          hooks_directory = base_directory + HOOKS_DIRECTORY_NAME
+          
+          used_hook_names.map do |hook_name|
+            hooks_directory + hook_name
+          end
+        end
+
+        # Installs the plugin by placing symlinks to the plugin executable into
+        # Smuxi's hook handler paths.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @param [Pathname] base_directory the configuration directory for
+        #   Smuxi. The hooks sub-directory is expected to reside here
+        # @return [void]
+        def install(executable_path, base_directory = base_directory_guess, &block)
+          executable_file = Pathname.new(executable_path).expand_path
+          executable_name = executable_file.basename.to_s
+
+          used_hook_paths(base_directory).each do |hook_path|
+            hook_path.mkpath
+            hook_executable_file = hook_path + executable_name 
+            block.call(hook_executable_file) if block
+            hook_executable_file.unlink if hook_executable_file.symlink?
+            hook_executable_file.make_symlink(executable_file)
+          end
+        end
+
+        # Uninstalls the plugin by removing symlinks to the plugin executable
+        # from Smuxi's hook handler paths.
+        #
+        # @param [String] executable_path path of the plugin executable file
+        # @param [Pathname] base_directory the configuration directory for
+        #   Smuxi. The hooks sub-directory is expected to reside here
+        # @yield [hook_executable
+        # @return [void]
+        def uninstall(executable_path, base_directory = base_directory_guess, &block)
+          executable_file = Pathname.new(executable_path).expand_path
+          executable_name = executable_file.basename.to_s
+
+          used_hook_paths(base_directory).each do |hook_path|
+            hook_executable_file = hook_path + executable_name
+            block.call(hook_executable_file) if block
+            hook_executable_file.unlink if hook_executable_file.symlink?
+          end
+        end
+
+      end
+
+      attr_reader :state
+
+      # Initializes the plugin.
+      #
+      # Known variables' values from the supplied environment will be transferred
+      # to the respective instance variables. 
+      #
+      # @see VARIABLE_TABLE
+      #
+      # @param [Hash] options
+      # @option options [{String => String}] environment environment variables for the plugin execution
+      # @option options [Pathname] base_directory the configuration directory for
+      #   Smuxi. The hooks and hook-state sub-directories are expected to reside
+      #   here
+      # @option options [Pathname] state_directory the directory that Smuxi
+      #   reserved for this plugin to store its state.
+      # @option options [String] hook_name name of the Smuxi hook that is executed
+      # @option options [String] script_name name of plugin hook executable, without path
+      def initialize(options = {})
+        @environment     = options[:environment]
+        @base_directory  = options[:base_directory]
+        @state_directory = options[:state_directory]
+        @state           = options[:state]
+        @hook_name       = options[:hook_name]
+        @script_name     = options[:script_name]
+
+        VARIABLE_TABLE.each do |environment_variable, instance_variable|
+          instance_variable_set(instance_variable,
+                                @environment[environment_variable])
+        end
+      end
+
+      # Calls a command in Smuxi
+      #
+      # @param [String] type the command type
+      # @param [Symbol, String] name the command name
+      # @param [String] data the argument data added to the command
+      # @return [void]
+      def command(type, name, data = nil)
+        command = "#{type} /#{name}"
+        command += " #{data}" if data
+        
+        STDOUT.puts(command)
+      end
+
+      # Calls a session command in Smuxi
+      #
+      # @param [Symbol, String] name the command name
+      # @param [String] data the argument data added to the command
+      # @return [void]
+      def session_command(name, data = nil)
+        command('Session.Command', name, data)
+      end
+
+      # Calls a protocol manager command in Smuxi
+      #
+      # @param [Symbol, String] name the command name
+      # @param [String] data the argument data added to the command
+      # @return [void]
+      def protocol_manager_command(name, data = nil)
+        command('ProtocolManager.Command', name, data)
+      end
+
+      # Outputs a message to the Smuxi user
+      #
+      # @param [String] message the text message sent to the Smuxi user
+      def puts(message)
+        session_command(:echo, message)
+      end
+
+    end
+
+  end
+end

data/lib/god_object/smuxi_hooks/version.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+module GodObject
+  module SmuxiHooks
+
+    # The currently loaded version.
+    #
+    # Using Semantic Versioning (2.0.0) rules
+    # @see http://semver.org/
+    VERSION = '0.1.0'.freeze
+
+  end
+end

data/lib/smuxi_hooks.rb

@@ -0,0 +1,20 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require 'god_object/smuxi_hooks'

data/smuxi_hooks.gemspec

@@ -0,0 +1,54 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2015
+
+This file is part of Smuxi hooks API for Ruby.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+require File.expand_path('../lib/god_object/smuxi_hooks/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name    = "smuxi_hooks"
+  gem.version = GodObject::SmuxiHooks::VERSION.dup
+  gem.authors = ["Alexander E. Fischer"]
+  gem.email   = ["aef@godobject.net"]
+  gem.description = <<-DESCRIPTION
+Plugin framework for the multi-protocol distributed chat client Smuxi.
+  DESCRIPTION
+  gem.summary  = "Plugin framework for the multi-protocol distributed chat client Smuxi."
+  gem.homepage = "https://www.godobject.net/"
+  gem.license  = "ISC"
+  gem.has_rdoc = "yard"
+  gem.extra_rdoc_files  = ["HISTORY.md", "LICENSE.md"]
+  gem.rubyforge_project = nil
+
+  `git ls-files 2> /dev/null`
+
+  if $?.success?
+    gem.files         = `git ls-files`.split($\)
+  else
+    gem.files         = `ls -1`.split($\)
+  end
+
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_development_dependency('pry')
+  gem.add_development_dependency('yard')
+  gem.add_development_dependency('redcarpet')
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: smuxi_hooks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexander E. Fischer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Plugin framework for the multi-protocol distributed chat client Smuxi.
+email:
+- aef@godobject.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- HISTORY.md
+- LICENSE.md
+files:
+- ".gitignore"
+- ".yardopts"
+- Gemfile
+- HISTORY.md
+- LICENSE.md
+- README.md
+- Rakefile
+- examples/chat_logger.rb
+- examples/keyword_catcher.rb
+- examples/remember.rb
+- lib/god_object/smuxi_hooks.rb
+- lib/god_object/smuxi_hooks/plugin.rb
+- lib/god_object/smuxi_hooks/version.rb
+- lib/smuxi_hooks.rb
+- smuxi_hooks.gemspec
+homepage: https://www.godobject.net/
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Plugin framework for the multi-protocol distributed chat client Smuxi.
+test_files: []
+has_rdoc: yard