Class: Birdwatcher::Module

Inherits:
Object
  • Object
show all
Includes:
Concerns::Concurrency, Concerns::Core, Concerns::Outputting, Concerns::Persistence, Concerns::Presentation, Concerns::Util
Defined in:
lib/birdwatcher/module.rb

Defined Under Namespace

Classes: Error, InvalidMetadataError, MetadataNotSetError, UnknownOptionError

Constant Summary collapse

MODULE_PATH =

Path to modules directory

File.join(File.dirname(__FILE__), "modules").freeze

Constants included from Concerns::Concurrency

Concerns::Concurrency::DEFAULT_THREAD_POOL_SIZE

Constants included from Concerns::Core

Concerns::Core::DATA_DIRECTORY

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Concerns::Concurrency

included, #thread_pool

Methods included from Concerns::Persistence

included, #save_status, #save_user

Methods included from Concerns::Presentation

included, #make_status_summary_output, #make_url_summary_output, #make_user_details_output, #make_user_summary_output, #output_status_summary, #output_user_details, #output_user_summary, #page_text

Methods included from Concerns::Outputting

#confirm, #error, #fatal, included, #info, #line_separator, #newline, #output, #output_formatted, #task, #warn

Methods included from Concerns::Util

#escape_html, #excerpt, included, #parse_time, #pluralize, #strip_control_characters, #strip_html, #suppress_output, #suppress_warnings, #time_ago_in_words, #unescape_html

Methods included from Concerns::Core

#console, #current_workspace, #current_workspace=, #database, included, #klout_client, #read_data_file, #twitter_client

Class Method Details

._file_pathObject

Get the module’s file path



21
22
23
# File 'lib/birdwatcher/module.rb', line 21

def self._file_path
  @_file_path
end

._file_path=(path) ⇒ Object

Set the module’s file path

Parameters:

  • path (String)

    file path



29
30
31
# File 'lib/birdwatcher/module.rb', line 29

def self._file_path=(path)
  @_file_path = path
end

.descendantsArray

Get all Birdwatcher::Module descendants

Returns:

  • (Array)

    module classes



134
135
136
# File 'lib/birdwatcher/module.rb', line 134

def self.descendants
  ObjectSpace.each_object(Class).select { |klass| klass < self }
end

.infoString

This method is abstract.

The module’s detailed information and usage

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.

Returns:

  • (String)

    additional module information



128
# File 'lib/birdwatcher/module.rb', line 128

def self.info; end

.inherited(k) ⇒ Object

Automatically set the module file path



35
36
37
# File 'lib/birdwatcher/module.rb', line 35

def self.inherited(k)
  k._file_path = caller.first[/^[^:]+/]
end

.metaHash

Get the module’s meta data

Returns:

  • (Hash)

    meta data

Raises:

  • (Birdwatcher::Model::MetadataNotSetError)

    if meta data has not been set



44
45
46
# File 'lib/birdwatcher/module.rb', line 44

def self.meta
  @meta || fail(MetadataNotSetError, "Metadata has not been set")
end

.meta=(meta) ⇒ Object

Set the module’s 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 <[email protected]>)

  • :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).

Examples:

Example meta data:

self.meta = {
  :name        => "User Importer",
  :description => "Import users from a file containing screen names",
  :author      => "Michael Henriksen <[email protected]>",
  :options     => {
    "FILE" => {
      :value       => nil,
      :description => "File to read screen names from.",
      :required    => true
    }
  }
}

Parameters:

  • meta (Hash)

    meta data



90
91
92
93
# File 'lib/birdwatcher/module.rb', line 90

def self.meta=(meta)
  (meta)
  @meta = meta
end

.module_by_path(path) ⇒ Birdwatcher::Module

Get a module by it’s path

Parameters:

  • path (String)

    Module’s short path

Returns:



101
102
103
# File 'lib/birdwatcher/module.rb', line 101

def self.module_by_path(path)
  modules[path]
end

.module_pathsObject

Get module short paths



107
108
109
# File 'lib/birdwatcher/module.rb', line 107

def self.module_paths
  modules.keys
end

.modulesHash

Get all Birdwatcher modules sorted by their short path

Returns:

  • (Hash)

    module classes where the key is the module’s short path



142
143
144
145
146
147
148
149
150
# File 'lib/birdwatcher/module.rb', line 142

def self.modules
  if !@modules
    @modules = {}
    descendants.each do |descendant|
      @modules[descendant.path] = descendant
    end
  end
  @modules
end

.pathObject

Get the module’s short path



113
114
115
# File 'lib/birdwatcher/module.rb', line 113

def self.path
  @_file_path.gsub("#{MODULE_PATH}/", "").gsub(".rb", "")
end

Instance Method Details

#executeObject

Execute a module and catch any exceptions raised Calls the module’s #run method if options are valid and catches any exceptions raised to display an error to the user.



157
158
159
160
161
162
# File 'lib/birdwatcher/module.rb', line 157

def execute
  validate_options && run
rescue => e
  error("#{e.class}".bold + ": #{e.message}")
  puts e.backtrace.join("\n")
end

#runObject

This method is abstract.

The module’s run method

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.



174
175
176
# File 'lib/birdwatcher/module.rb', line 174

def run
  fail NotImplementedError, "Modules must implement #run method"
end