Class: Lich::Common::DownstreamHook

Inherits:
Object
  • Object
show all
Defined in:
documented/common/downstreamhook.rb

Overview

Handles downstream hooks for processing strings. This class allows you to add, run, remove, and list hooks that can modify a server string.

Examples:

Adding a hook

DownstreamHook.add("example_hook", Proc.new { |str| str.upcase })

Class Method Summary collapse

Class Method Details

.add(name, action) ⇒ Boolean

Adds a new downstream hook.

Examples:

Adding a hook

DownstreamHook.add("example_hook", Proc.new { |str| str.upcase })

Parameters:

  • name (String) —

    The name of the hook.

  • action (Proc) —

    The action to be executed as a hook.

Returns:

  • (Boolean) —

    Returns true if the hook was added successfully, false otherwise.

Raises:

  • (ArgumentError) —

    Raises an error if action is not a Proc.



23
24
25
26
27
28
29
30
 
# File 'documented/common/downstreamhook.rb', line 23

def DownstreamHook.add(name, action)
  unless action.is_a?(Proc)
    echo "DownstreamHook: not a Proc (#{action})"
    return false
  end
  @@downstream_hook_sources[name] = (Script.current.name || "Unknown")
  @@downstream_hooks[name] = action
end

.hook_sources ⇒ Hash

Retrieves the hash of hook sources.

Examples:

Getting hook sources

sources = DownstreamHook.hook_sources

Returns:

  • (Hash) —

    A hash mapping hook names to their sources.



85
86
87
 
# File 'documented/common/downstreamhook.rb', line 85

def DownstreamHook.hook_sources
  @@downstream_hook_sources
end

.list ⇒ Array<String>

Lists all registered downstream hooks.

Examples:

Listing hooks

hooks = DownstreamHook.list

Returns:

  • (Array<String>) —

    An array of hook names.



66
67
68
 
# File 'documented/common/downstreamhook.rb', line 66

def DownstreamHook.list
  @@downstream_hooks.keys.dup
end

.remove(name) ⇒ void

This method returns an undefined value.

Removes a downstream hook by name.

Examples:

Removing a hook

DownstreamHook.remove("example_hook")

Parameters:

  • name (String) —

    The name of the hook to remove.



57
58
59
60
 
# File 'documented/common/downstreamhook.rb', line 57

def DownstreamHook.remove(name)
  @@downstream_hook_sources.delete(name)
  @@downstream_hooks.delete(name)
end

.run(server_string) ⇒ String?

Executes all registered downstream hooks on the given server string.

Examples:

Running hooks

modified_string = DownstreamHook.run("input string")

Parameters:

  • server_string (String) —

    The string to be processed by the hooks.

Returns:

  • (String, nil) —

    Returns the modified string or nil if the input is nil.

Raises:

  • (StandardError) —

    Catches exceptions raised by hooks and removes the faulty hook.



38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'documented/common/downstreamhook.rb', line 38

def DownstreamHook.run(server_string)
  for key in @@downstream_hooks.keys
    return nil if server_string.nil?
    begin
      server_string = @@downstream_hooks[key].call(server_string.dup) if server_string.is_a?(String)
    rescue
      @@downstream_hooks.delete(key)
      respond "--- Lich: DownstreamHook: #{$!}"
      respond $!.backtrace.first
    end
  end
  return server_string
end

.sources ⇒ String

Displays a table of hook names and their sources.

Examples:

Displaying hook sources

puts DownstreamHook.sources

Returns:

  • (String) —

    A formatted string representation of the hook sources.



74
75
76
77
78
79
 
# File 'documented/common/downstreamhook.rb', line 74

def DownstreamHook.sources
  info_table = Terminal::Table.new :headings => ['Hook', 'Source'],
                                   :rows     => @@downstream_hook_sources.to_a,
                                   :style    => { :all_separators => true }
  Lich::Messaging.mono(info_table.to_s)
end