Module Tap::Signals::ClassMethods
In: lib/tap/signals/class_methods.rb

Methods

Constants

SIGNALS_CLASS = Configurable::ClassMethods::CONFIGURATIONS_CLASS

Attributes

signal_registry  [R]  A hash of (key, Signal) pairs defining signals available to the class.

Public Class methods

[Source]

    # File lib/tap/signals/class_methods.rb, line 12
12:       def self.initialize(base)
13:         unless base.instance_variable_defined?(:@signal_registry)
14:           base.instance_variable_set(:@signal_registry, SIGNALS_CLASS.new)
15:         end
16:         
17:         unless base.instance_variable_defined?(:@signals)
18:           base.instance_variable_set(:@signals, nil)
19:         end
20:         
21:         unless base.instance_variable_defined?(:@use_signal_constants)
22:           base.instance_variable_set(:@use_signal_constants, true)
23:         end
24:       end

Public Instance methods

Caches the signals hash so as to improve peformance. Call with on set to false to turn off caching.

[Source]

    # File lib/tap/signals/class_methods.rb, line 54
54:       def cache_signals(on=true)
55:         @signals = nil
56:         @signals = self.signals if on
57:       end

A hash of (key, Signal) pairs representing all signals defined on this class or inherited from ancestors. The signals hash is generated on each call to ensure it accurately reflects any signals added on ancestors. This slows down signal calls through instance.signal.

Call cache_signals after all signals have been declared in order to prevent regeneration of signals and to significantly improve performance.

[Source]

    # File lib/tap/signals/class_methods.rb, line 34
34:       def signals
35:         return @signals if @signals
36: 
37:         signals = SIGNALS_CLASS.new
38:         ancestors.reverse.each do |ancestor|
39:           next unless ancestor.kind_of?(ClassMethods)
40:           ancestor.signal_registry.each_pair do |key, value|
41:             if value.nil?
42:               signals.delete(key)
43:             else
44:               signals[key] = value
45:             end
46:           end
47:         end
48: 
49:         signals
50:       end

Protected Instance methods

[Source]

     # File lib/tap/signals/class_methods.rb, line 102
102:       def define_signal(sig, opts=nil, &block) # :yields: args
103:         unless opts.kind_of?(Hash)
104:           opts = {:class => opts, :bind => false}
105:         end
106:         
107:         # generate a subclass of signal
108:         klass = opts[:class] || Signal
109:         signal = Class.new(klass)
110:         
111:         # bind the new signal
112:         method_name = opts.has_key?(:bind) ? opts[:bind] : sig
113:         if method_name
114:           signal.send(:define_method, :call) do |args|
115:             args = process(args)
116:             obj.send(method_name, *args, &self.block)
117:           end
118:         end
119:         
120:         if block_given?
121:           signal.send(:define_method, :process, &block)
122:         end
123:         
124:         if signal.respond_to?(:desc=)
125:           caller_index = opts[:caller_index] || 1
126:           signal.desc ||= Lazydoc.register_caller(Lazydoc::Trailer, caller_index)
127:         end
128:         
129:         register_signal(sig, signal, opts)
130:       end

Removes a signal much like remove_method removes a method. The signal constant is likewise removed unless the :remove_const option is set to to true.

[Source]

     # File lib/tap/signals/class_methods.rb, line 135
135:       def remove_signal(sig, opts={})
136:         sig = sig.to_s
137:         unless signal_registry.has_key?(sig)
138:           raise NameError.new("#{sig} is not a signal for #{self}")
139:         end
140: 
141:         unregister_signal(sig, opts)
142:       end

Defines a signal to call a method using an argument vector. The argv is sent to the method using a splat, so any method may be signaled. A signature of keys may be specified to automatically generate an argv from a hash; values for the keys are collected in order.

A block may also be provided to pre-process the argv before it is sent to the method; the block return is sent to the method (and so should be an argv).

[Source]

    # File lib/tap/signals/class_methods.rb, line 73
73:       def signal(sig, opts={}, &block) # :yields: sig, argv
74:         signature = opts[:signature] || []
75:         remainder = opts[:remainder] || false
76:         opts[:caller_index] ||= 2
77:         
78:         define_signal(sig, opts) do |args|
79:           argv = convert_to_array(args, signature, remainder)
80:           block ? block.call(self, argv) : argv
81:         end
82:       end

Defines a signal to call a method that receives a single hash as an input. A signature may be specified to automatically generate a hash from an array input.

A block may also be provided to pre-process the hash before it is sent to the method; the block return is sent to the method (and so should be a hash).

[Source]

     # File lib/tap/signals/class_methods.rb, line 91
 91:       def signal_hash(sig, opts={}, &block) # :yields: sig, argh
 92:         signature = opts[:signature] || []
 93:         remainder = opts[:remainder]
 94:         opts[:caller_index] ||= 2
 95:         
 96:         define_signal(sig, opts) do |args|
 97:           argh = convert_to_hash(args, signature, remainder)
 98:           [block ? block.call(self, argh) : argh]
 99:         end
100:       end

Undefines a signal much like undef_method undefines a method. The signal constant is likewise removed unless the :remove_const option is set to to true.

Implementation Note

Signals are undefined by setting the key to nil in the registry. Deleting the signal is not sufficient because the registry needs to convey to self and subclasses to not inherit the signal from ancestors.

This is unlike remove_signal where the signal is simply deleted from the signal_registry.

[Source]

     # File lib/tap/signals/class_methods.rb, line 157
157:       def undef_signal(sig, opts={})
158:         # temporarily cache as an optimization
159:         signals_cache = signals
160:         sig = sig.to_s
161:         unless signals_cache.has_key?(sig)
162:           raise NameError.new("#{sig} is not a signal for #{self}")
163:         end
164:         
165:         unregister_signal(sig, opts)
166:         signal_registry[sig] = nil
167:         signals_cache[sig]
168:       end

[Source]

    # File lib/tap/signals/class_methods.rb, line 61
61:       def use_signal_constants(input=true)
62:         @use_signal_constants = input
63:       end

[Validate]