class GodObject::SmuxiHooks::Plugin

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.

Constants

BASE_DIRECTORY_NAME

@return [String] name of the base configuration directory

HOOKS_DIRECTORY_NAME

@return [String] name of the sub-directory containing the hook handlers

HOOK_TABLE

@return [{String => Symbol}] maps Smuxi hook names to named of the

method supposed to handle that hook
STATE_DIRECTORY_NAME

@return [String] name of the sub-directory containing plugin state

STATE_FILE_NAME

@return [String] name of the file in which the permanent state is held

VARIABLE_TABLE

@return [{String => Symbol}] maps Smuxi environment variable names to

instance variables which will inhert the value supplied by Smuxi

Attributes

state[R]

Public Class Methods

base_directory_guess() click to toggle source

@return [Pathname] path to the base directory

# File lib/god_object/smuxi_hooks/plugin.rb, line 213
def base_directory_guess
  Pathname.new('~/.local/share').expand_path + BASE_DIRECTORY_NAME
end
cli_install(executable_path) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 176
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
cli_uninstall(executable_path) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 198
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
execute(executable_path, environment = ENV, arguments = ARGV) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 106
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
execute_hook(executable_path, environment = ENV) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 125
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
install(executable_path, base_directory = base_directory_guess, &block) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 252
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
new(options = {}) click to toggle source

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

# File lib/god_object/smuxi_hooks/plugin.rb, line 304
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
uninstall(executable_path, base_directory = base_directory_guess, &block) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 273
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
used_hook_methods() click to toggle source

@return [Array<Symbol>] a list of the names of all hook handler

instance methods implemented by this class
# File lib/god_object/smuxi_hooks/plugin.rb, line 219
def used_hook_methods
  instance_methods.to_set.intersection(HOOK_TABLE.values.to_set)
end
used_hook_names() click to toggle source

@return [Array<String>] a list of the names of all hooks supported by

this class
# File lib/god_object/smuxi_hooks/plugin.rb, line 225
def used_hook_names
  inverted_hook_table = HOOK_TABLE.invert

  used_hook_methods.map do |method_name|
    inverted_hook_table[method_name]
  end
end
used_hook_paths(base_directory = base_directory_guess) click to toggle source

@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
# File lib/god_object/smuxi_hooks/plugin.rb, line 237
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

Public Instance Methods

command(type, name, data = nil) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 324
def command(type, name, data = nil)
  command = "#{type} /#{name}"
  command += " #{data}" if data
  
  STDOUT.puts(command)
end
protocol_manager_command(name, data = nil) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 345
def protocol_manager_command(name, data = nil)
  command('ProtocolManager.Command', name, data)
end
puts(message) click to toggle source

Outputs a message to the Smuxi user

@param [String] message the text message sent to the Smuxi user

# File lib/god_object/smuxi_hooks/plugin.rb, line 352
def puts(message)
  session_command(:echo, message)
end
session_command(name, data = nil) click to toggle source

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]

# File lib/god_object/smuxi_hooks/plugin.rb, line 336
def session_command(name, data = nil)
  command('Session.Command', name, data)
end