class Birdwatcher::Module
Constants
- MODULE_PATH
Path to modules directory @private
Public Class Methods
Get the module’s file path @private
# File lib/birdwatcher/module.rb, line 22 def self._file_path @_file_path end
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
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
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
Automatically set the module file path @private
# File lib/birdwatcher/module.rb, line 36 def self.inherited(k) k._file_path = caller.first[/^[^:]+/] end
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
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 tonil
if none) -
:description
: A short description of the option setting -
:required
: Set totrue
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
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
Get module short paths @private
# File lib/birdwatcher/module.rb, line 108 def self.module_paths modules.keys end
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
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 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 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 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
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
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
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 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