Class: Ego::Robot

Inherits:
Object
  • Object
show all
Includes:
Hooks, Hooks::InstanceHooks
Defined in:
lib/ego/robot.rb

Overview

The robot instance provides a DSL for plug-ins to use to implement new functionality and also share that functionality with other plug-ins.

Much built-in functionality of Ego is also implemented using the plug-in DSL.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Robot

Returns a new instance of Robot.

Parameters:

  • options (Options) —

    the options to create a robot with

See Also:



31
32
33
34
35
36
 
# File 'lib/ego/robot.rb', line 31

def initialize(options)
  @name = options.robot_name
  @options = options
  @capabilities = []
  @handlers = []
end

Instance Attribute Details

#capabilities ⇒ Object (readonly)

Returns the value of attribute capabilities.



20
21
22
 
# File 'lib/ego/robot.rb', line 20

def capabilities
  @capabilities
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



20
21
22
 
# File 'lib/ego/robot.rb', line 20

def name
  @name
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



20
21
22
 
# File 'lib/ego/robot.rb', line 20

def options
  @options
end

Instance Method Details

#can(desc) ⇒ Array

Adds a new capability, which documents functionality added by a plug-in.

Examples:

Add a capability to the robot instance

robot.can 'repeat what you say'

Parameters:

  • desc (String) —

    capability description

Returns:

  • (Array) —

    all capabilities registered to the robot

See Also:



71
72
73
 
# File 'lib/ego/robot.rb', line 71

def can(desc)
  @capabilities << Capability.new(desc)
end

#first_handler_for(query) ⇒ nil, Handler

Find the highest-priority handler for a given query and return it. When a block is passed, the block is called if and only if a handler is found, passing the handler and parsed params as the block's arguments.

Parameters:

  • query (String) —

    user query

Returns:

  • (nil) —

    if no handler can handle query

  • (Handler) —

    the first matching handler



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/ego/robot.rb', line 174

def first_handler_for(query)
  @handlers.sort.reverse_each do |handler|
    if (params = handler.handle(query))
      yield(handler, params) if block_given?
      return handler
    end
  end

  nil
end

#handle(query) ⇒ false

Run the action for the highest-priority handler that can handle the given query and return the result. Associated hooks are run before and after running the action.

Parameters:

  • query (String) —

    user query

Returns:

  • (false) —

    if query is not handled

  • result of the action

See Also:

Runs Hooks:

  • before_handle_query
  • after_handle_query
  • on_unhandled_query 


154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/ego/robot.rb', line 154

def handle(query)
  run_hook :before_handle_query, query

  first_handler_for(query) do |handler, params|
    return run_action(handler.action, params).tap do |_result|
      run_hook :after_handle_query, query, handler
    end
  end

  run_hook :on_unhandled_query, query
  false
end

#on(condition, priority = 5, &action) ⇒ void

This method returns an undefined value.

Register a new query handler.

The robot will execute the given block (the "action") when the given pattern (the "condition") matches. Conditions are assigned priorities, which determined in what order conditions are checked against the query. A higher number is treated as higher priority.

Examples:

Add a handler to the robot instance

robot.on(/^pattern/) do
  # ...
end

Add a handler with priority to the robot instance

robot.on(/^pattern/, 7) do
  # ...
end

Add multiple handlers for the same action

robot.on(
  /pattern/ => 6,
  /other pattern/ => 7,
  /another/ => 3,
) do
  # ...
end

Passing a lambda as a condition

robot.on(->(query) { query.length > 10 }) do
  # ...
end

Parameters:

  • condition (Proc, #match) —

    the condition that triggers the action

  • priority (Integer) (defaults to: 5) —

    the handler priority

  • action (Proc) —

    the block to be executed when condition is met

See Also:



112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/ego/robot.rb', line 112

def on(condition, priority = 5, &action)
  unless action # rubocop:disable Style/IfUnlessModifier
    raise RobotError, "Hook requires an action: robot.on #{condition.inspect}"
  end

  if condition.respond_to?(:each_pair)
    # Condition is a hash of conditions and priorities
    condition.each_pair { |c, p| on(c, p, &action) }
  else
    # Register a new handler with condition
    @handlers << Handler.new(condition, action, priority)
  end
end

#ready ⇒ self

Run on_ready hook.

Should be called after plug-ins are registered, before handling queries.

Returns:

  • (self)

Runs Hooks:

  • on_ready 


45
46
47
48
 
# File 'lib/ego/robot.rb', line 45

def ready
  run_hook :on_ready
  self
end

#run_action(action, params) ⇒ Object

Run action with given parameters in the context of the robot instance.

Parameters:

  • action (#call) —

    the action

  • params —

    the action parameters

Returns:

  • result of the action

Runs Hooks:

  • before_action
  • after_action 


134
135
136
137
138
139
 
# File 'lib/ego/robot.rb', line 134

def run_action(action, params)
  run_hook :before_action, action, params
  result = instance_exec(*params, &action)
  run_hook :after_action, action, params, result
  result
end

#shutdown ⇒ void

This method returns an undefined value.

Run on_shutdown hook.

Should be called after all queries are handled, before program termination.

Runs Hooks:

  • on_shutdown 


58
59
60
 
# File 'lib/ego/robot.rb', line 58

def shutdown
  run_hook :on_shutdown
end