class Birdwatcher::Module

Constants

MODULE_PATH

Path to modules directory @private

Public Class Methods

_file_path() click to toggle source

Get the module’s file path @private

# File lib/birdwatcher/module.rb, line 22
def self._file_path
  @_file_path
end
_file_path=(path) click to toggle source

Set the module’s file path @private

@param path [String] file path

# File lib/birdwatcher/module.rb, line 30
def self._file_path=(path)
  @_file_path = path
end
descendants() click to toggle source

Get all Birdwatcher::Module descendants @private

@return [Array] module classes

# File lib/birdwatcher/module.rb, line 135
def self.descendants
  ObjectSpace.each_object(Class).select { |klass| klass < self }
end
info() click to toggle source

The module’s detailed information and usage

@abstract

This method can be overwritten by modules to provide additional information and usage to the user. The method will be called when the user envokes the +show info+ on the module.

The method must return a string.

@return [String] additional module information

# File lib/birdwatcher/module.rb, line 129
def self.info; end
inherited(k) click to toggle source

Automatically set the module file path @private

# File lib/birdwatcher/module.rb, line 36
def self.inherited(k)
  k._file_path = caller.first[/^[^:]+/]
end
meta() click to toggle source

Get the module’s meta data @private

@return [Hash] meta data @raise [Birdwatcher::Model::MetadataNotSetError] if meta data has not been set

# File lib/birdwatcher/module.rb, line 45
def self.meta
  @meta || fail(MetadataNotSetError, "Metadata has not been set")
end
meta=(meta) click to toggle source

Set the module’s meta data

@param meta [Hash] meta data

The module’s meta data is used by Birdwatcher to provide the user with useful information such as name, a short description of what it does as well as the author of the module in case they have any questions, etc.

The meta data MUST be a hash and MUST contain at least the following keys:

  • :name: The module’s name (e.g. User Importer)

  • :description: A short description of what the module can do

  • :author: Your name and email (e.g. John Doe <john@doe.com>)

  • :options: A hash of options for the module

The :options meta data key MUST be a Hash where each key is the option name in UPPERCASE. The value MUST be a Hash and MUST contain at least the following keys:

  • :value: The default value of the option setting (set to nil if none)

  • :description: A short description of the option setting

  • :required: Set to true if the option setting is required to be set

If the option setting is a boolean flag, the :boolean key can be set to true to have Birdwatcher automatically parse “truthy” and “falsy” values (e.g. “true”, “1”, “yes”, “no”, “0”, etc) into boolean true or false

If an option setting’s :required key is set to true, Birdwatcher will automatically prevent running of the module if any of those option settings contain nil (have not been set).

@example Example meta data:

self.meta = {
  :name        => "User Importer",
  :description => "Import users from a file containing screen names",
  :author      => "Michael Henriksen <michenriksen@neomailbox.ch>",
  :options     => {
    "FILE" => {
      :value       => nil,
      :description => "File to read screen names from.",
      :required    => true
    }
  }
}
# File lib/birdwatcher/module.rb, line 91
def self.meta=(meta)
  validate_metadata(meta)
  @meta = meta
end
module_by_path(path) click to toggle source

Get a module by it’s path @private

@param path [String] Module’s short path

@return [Birdwatcher::Module] descendant

# File lib/birdwatcher/module.rb, line 102
def self.module_by_path(path)
  modules[path]
end
module_paths() click to toggle source

Get module short paths @private

# File lib/birdwatcher/module.rb, line 108
def self.module_paths
  modules.keys
end
modules() click to toggle source

Get all Birdwatcher modules sorted by their short path @private

@return [Hash] module classes where the key is the module’s short path

# File lib/birdwatcher/module.rb, line 143
def self.modules
  if !@modules
    @modules = {}
    descendants.each do |descendant|
      @modules[descendant.path] = descendant
    end
  end
  @modules
end
path() click to toggle source

Get the module’s short path @private

# File lib/birdwatcher/module.rb, line 114
def self.path
  @_file_path.gsub("#{MODULE_PATH}/", "").gsub(".rb", "")
end

Protected Class Methods

validate_metadata(meta) click to toggle source

Validate module meta data @private

@param meta [Hash] meta data

@raise [Birdwatcher::Module::InvalidMetadataError] if meta data is not valid.

# File lib/birdwatcher/module.rb, line 200
def self.validate_metadata(meta)
  fail InvalidMetadataError, "Metadata is not a hash" unless meta.is_a?(Hash)
  fail InvalidMetadataError, "Metadata is empty" if meta.empty?
  fail InvalidMetadataError, "Metadata is missing key: name" unless meta.key?(:name)
  fail InvalidMetadataError, "Metadata is missing key: description" unless meta.key?(:description)
  fail InvalidMetadataError, "Metadata is missing key: author" unless meta.key?(:author)
  fail InvalidMetadataError, "Metadata is missing key: options" unless meta.key?(:options)
  fail InvalidMetadataError, "Metadata name is not a string" unless meta[:name].is_a?(String)
  fail InvalidMetadataError, "Metadata description is not a string" unless meta[:description].is_a?(String)
  fail InvalidMetadataError, "Metadata author is not a string" unless meta[:author].is_a?(String)
  validate_metadata_options(meta[:options])
end
validate_metadata_options(options) click to toggle source

Validate meta data module options @private

@param options [Hash] options

Automatically called by {validate_metadata}

@raise [Birdwatcher::Module::InvalidMetadataError] if options hash is not valid.

# File lib/birdwatcher/module.rb, line 221
def self.validate_metadata_options(options)
  fail InvalidMetadataError, "Metadata options is not a hash" unless options.is_a?(Hash)
  options.each_pair do |key, value|
    fail("Option key #{key} must be all uppercase") unless (key == key.upcase)
    fail("Option value for #{key} is not a hash") unless value.is_a?(Hash)
    fail("Option value for #{key} is missing key: value") unless value.key?(:value)
    fail("Option value for #{key} is missing key: description") unless value.key?(:description)
    fail("Option value for #{key} is missing key: required") unless value.key?(:required)
  end
end

Public Instance Methods

execute() click to toggle source

Execute a module and catch any exceptions raised @private

Calls the module’s {run} method if options are valid and catches any exceptions raised to display an error to the user.

# File lib/birdwatcher/module.rb, line 158
def execute
  validate_options && run
rescue => e
  error("#{e.class}".bold + ": #{e.message}")
  puts e.backtrace.join("\n")
end
run() click to toggle source

The module’s run method

@abstract

The run method must be overwritten by modules to perform the actual work. The method is called when the user envokes the run command in the Birdwatcher console.

If the module fails to run for whatever reason, e.g. insufficient data, the method should return false.

# File lib/birdwatcher/module.rb, line 175
def run
  fail NotImplementedError, "Modules must implement #run method"
end

Protected Instance Methods

option_setting(option) click to toggle source

Get an option setting

@example getting option settings

option_setting("DEST")
option_setting("USERS")

@return option setting @raise [Birdwatcher::Module::UnknownOptionError] if option is unknown

# File lib/birdwatcher/module.rb, line 248
def option_setting(option)
  option = option.to_s.upcase
  fail UnknownOptionError, "Unknown module option: #{option}" unless options.keys.include?(option)
  options[option][:value]
end
options() click to toggle source

Get the module’s options hash @private

@return [Hash] options meta data hash.

# File lib/birdwatcher/module.rb, line 236
def options
  self.class.meta[:options]
end
validate_options() click to toggle source

Validate option settings @private

@return [Boolean] true if meta data is valid and false otherwise

# File lib/birdwatcher/module.rb, line 185
def validate_options
  options.each_pair do |key, value|
    if value[:required] && value[:value].nil?
      error("Setting for required option has not been set: #{key.bold}")
      return false
    end
  end
end