sundbp-extlib 0.9.14
Sign up to get free protection for your applications and to get access to all the features.
- data/.autotest +21 -0
- data/.document +5 -0
- data/.gitignore +22 -0
- data/LICENSE +47 -0
- data/README.rdoc +17 -0
- data/Rakefile +28 -0
- data/VERSION +1 -0
- data/extlib.gemspec +146 -0
- data/lib/extlib.rb +50 -0
- data/lib/extlib/array.rb +36 -0
- data/lib/extlib/assertions.rb +8 -0
- data/lib/extlib/blank.rb +89 -0
- data/lib/extlib/boolean.rb +11 -0
- data/lib/extlib/byte_array.rb +6 -0
- data/lib/extlib/class.rb +177 -0
- data/lib/extlib/datetime.rb +29 -0
- data/lib/extlib/dictionary.rb +433 -0
- data/lib/extlib/hash.rb +442 -0
- data/lib/extlib/hook.rb +403 -0
- data/lib/extlib/inflection.rb +440 -0
- data/lib/extlib/lazy_array.rb +451 -0
- data/lib/extlib/lazy_module.rb +18 -0
- data/lib/extlib/logger.rb +198 -0
- data/lib/extlib/mash.rb +155 -0
- data/lib/extlib/module.rb +47 -0
- data/lib/extlib/nil.rb +5 -0
- data/lib/extlib/numeric.rb +5 -0
- data/lib/extlib/object.rb +175 -0
- data/lib/extlib/object_space.rb +13 -0
- data/lib/extlib/pathname.rb +20 -0
- data/lib/extlib/pooling.rb +235 -0
- data/lib/extlib/rubygems.rb +38 -0
- data/lib/extlib/simple_set.rb +66 -0
- data/lib/extlib/string.rb +176 -0
- data/lib/extlib/struct.rb +17 -0
- data/lib/extlib/symbol.rb +21 -0
- data/lib/extlib/time.rb +43 -0
- data/lib/extlib/virtual_file.rb +10 -0
- data/spec/array_spec.rb +39 -0
- data/spec/blank_spec.rb +85 -0
- data/spec/byte_array_spec.rb +7 -0
- data/spec/class_spec.rb +157 -0
- data/spec/datetime_spec.rb +22 -0
- data/spec/hash_spec.rb +537 -0
- data/spec/hook_spec.rb +1234 -0
- data/spec/inflection/plural_spec.rb +564 -0
- data/spec/inflection/singular_spec.rb +497 -0
- data/spec/inflection_extras_spec.rb +110 -0
- data/spec/lazy_array_spec.rb +1957 -0
- data/spec/lazy_module_spec.rb +38 -0
- data/spec/mash_spec.rb +311 -0
- data/spec/module_spec.rb +70 -0
- data/spec/object_space_spec.rb +9 -0
- data/spec/object_spec.rb +114 -0
- data/spec/pooling_spec.rb +511 -0
- data/spec/rcov.opts +6 -0
- data/spec/simple_set_spec.rb +57 -0
- data/spec/spec.opts +4 -0
- data/spec/spec_helper.rb +10 -0
- data/spec/string_spec.rb +221 -0
- data/spec/struct_spec.rb +12 -0
- data/spec/symbol_spec.rb +8 -0
- data/spec/time_spec.rb +29 -0
- data/spec/try_call_spec.rb +73 -0
- data/spec/try_dup_spec.rb +45 -0
- data/spec/virtual_file_spec.rb +21 -0
- data/tasks/ci.rake +1 -0
- data/tasks/metrics.rake +36 -0
- data/tasks/spec.rake +25 -0
- data/tasks/yard.rake +9 -0
- data/tasks/yardstick.rake +19 -0
- metadata +180 -0
data/lib/extlib/hash.rb
ADDED
@@ -0,0 +1,442 @@
|
|
1
|
+
class Hash
|
2
|
+
class << self
|
3
|
+
# Converts valid XML into a Ruby Hash structure.
|
4
|
+
#
|
5
|
+
# Mixed content is treated as text and any tags in it are left unparsed
|
6
|
+
#
|
7
|
+
# Any attributes other than type on a node containing a text node will be
|
8
|
+
# discarded
|
9
|
+
#
|
10
|
+
# [Typecasting is performed on elements that have a +type+ attribute:]
|
11
|
+
# integer:: Returns an Integer
|
12
|
+
# boolean:: Anything other than "true" evaluates to false.
|
13
|
+
# datetime::
|
14
|
+
# Returns a Time object. See Time documentation for valid Time strings.
|
15
|
+
# date::
|
16
|
+
# Returns a Date object. See Date documentation for valid Date strings.
|
17
|
+
#
|
18
|
+
# Keys are automatically converted to +snake_case+
|
19
|
+
#
|
20
|
+
# [Simple]
|
21
|
+
#
|
22
|
+
# <user gender='m'>
|
23
|
+
# <age type='integer'>35</age>
|
24
|
+
# <name>Home Simpson</name>
|
25
|
+
# <dob type='date'>1988-01-01</dob>
|
26
|
+
# <joined-at type='datetime'>2000-04-28 23:01</joined-at>
|
27
|
+
# <is-cool type='boolean'>true</is-cool>
|
28
|
+
# </user>
|
29
|
+
#
|
30
|
+
# Becomes:
|
31
|
+
#
|
32
|
+
# { "user" => {
|
33
|
+
# "gender" => "m",
|
34
|
+
# "age" => 35,
|
35
|
+
# "name" => "Home Simpson",
|
36
|
+
# "dob" => DateObject( 1998-01-01 ),
|
37
|
+
# "joined_at" => TimeObject( 2000-04-28 23:01),
|
38
|
+
# "is_cool" => true
|
39
|
+
# }
|
40
|
+
# }
|
41
|
+
#
|
42
|
+
# [Mixed Content]
|
43
|
+
#
|
44
|
+
# <story>
|
45
|
+
# A Quick <em>brown</em> Fox
|
46
|
+
# </story>
|
47
|
+
#
|
48
|
+
# Evaluates to:
|
49
|
+
#
|
50
|
+
# { "story" => "A Quick <em>brown</em> Fox" }
|
51
|
+
#
|
52
|
+
# [Attributes other than type on a node containing text]
|
53
|
+
#
|
54
|
+
# <story is-good='false'>
|
55
|
+
# A Quick <em>brown</em> Fox
|
56
|
+
# </story>
|
57
|
+
#
|
58
|
+
# Are ignored:
|
59
|
+
#
|
60
|
+
# { "story" => "A Quick <em>brown</em> Fox" }
|
61
|
+
#
|
62
|
+
# [Other attributes in addition to +type+]
|
63
|
+
#
|
64
|
+
# <bicep unit='inches' type='integer'>60</bicep>
|
65
|
+
#
|
66
|
+
# Evaluates with a typecast to an integer. But unit attribute is ignored:
|
67
|
+
#
|
68
|
+
# { "bicep" => 60 }
|
69
|
+
#
|
70
|
+
# @param [String] xml A string representation of valid XML.
|
71
|
+
#
|
72
|
+
# @return [Hash] A hash created by parsing +xml+
|
73
|
+
def from_xml( xml )
|
74
|
+
ToHashParser.from_xml(xml)
|
75
|
+
end
|
76
|
+
end
|
77
|
+
|
78
|
+
# Convert to Mash. This class has semantics of ActiveSupport's
|
79
|
+
# HashWithIndifferentAccess and we only have it so that people can write
|
80
|
+
# params[:key] instead of params['key'].
|
81
|
+
#
|
82
|
+
# @return [Mash] This hash as a Mash for string or symbol key access.
|
83
|
+
def to_mash
|
84
|
+
hash = Mash.new(self)
|
85
|
+
hash.default = default
|
86
|
+
hash
|
87
|
+
end
|
88
|
+
|
89
|
+
##
|
90
|
+
# Convert to URL query param string
|
91
|
+
#
|
92
|
+
# { :name => "Bob",
|
93
|
+
# :address => {
|
94
|
+
# :street => '111 Ruby Ave.',
|
95
|
+
# :city => 'Ruby Central',
|
96
|
+
# :phones => ['111-111-1111', '222-222-2222']
|
97
|
+
# }
|
98
|
+
# }.to_params
|
99
|
+
# #=> "name=Bob&address[city]=Ruby Central&address[phones][]=111-111-1111&address[phones][]=222-222-2222&address[street]=111 Ruby Ave."
|
100
|
+
#
|
101
|
+
# @return [String] This hash as a query string
|
102
|
+
#
|
103
|
+
# @api public
|
104
|
+
def to_params
|
105
|
+
params = self.map { |k,v| normalize_param(k,v) }.join
|
106
|
+
params.chop! # trailing &
|
107
|
+
params
|
108
|
+
end
|
109
|
+
|
110
|
+
##
|
111
|
+
# Convert a key, value pair into a URL query param string
|
112
|
+
#
|
113
|
+
# normalize_param(:name, "Bob") #=> "name=Bob&"
|
114
|
+
#
|
115
|
+
# @param [Object] key The key for the param.
|
116
|
+
# @param [Object] value The value for the param.
|
117
|
+
#
|
118
|
+
# @return [String] This key value pair as a param
|
119
|
+
#
|
120
|
+
# @api public
|
121
|
+
def normalize_param(key, value)
|
122
|
+
param = ''
|
123
|
+
stack = []
|
124
|
+
|
125
|
+
if value.is_a?(Array)
|
126
|
+
param << value.map { |element| normalize_param("#{key}[]", element) }.join
|
127
|
+
elsif value.is_a?(Hash)
|
128
|
+
stack << [key,value]
|
129
|
+
else
|
130
|
+
param << "#{key}=#{value}&"
|
131
|
+
end
|
132
|
+
|
133
|
+
stack.each do |parent, hash|
|
134
|
+
hash.each do |k, v|
|
135
|
+
if v.is_a?(Hash)
|
136
|
+
stack << ["#{parent}[#{k}]", v]
|
137
|
+
else
|
138
|
+
param << normalize_param("#{parent}[#{k}]", v)
|
139
|
+
end
|
140
|
+
end
|
141
|
+
end
|
142
|
+
|
143
|
+
param
|
144
|
+
end
|
145
|
+
|
146
|
+
##
|
147
|
+
# Create a hash with *only* key/value pairs in receiver and +allowed+
|
148
|
+
#
|
149
|
+
# { :one => 1, :two => 2, :three => 3 }.only(:one) #=> { :one => 1 }
|
150
|
+
#
|
151
|
+
# @param [Array[String, Symbol]] *allowed The hash keys to include.
|
152
|
+
#
|
153
|
+
# @return [Hash] A new hash with only the selected keys.
|
154
|
+
#
|
155
|
+
# @api public
|
156
|
+
def only(*allowed)
|
157
|
+
hash = {}
|
158
|
+
allowed.each {|k| hash[k] = self[k] if self.has_key?(k) }
|
159
|
+
hash
|
160
|
+
end
|
161
|
+
|
162
|
+
##
|
163
|
+
# Create a hash with all key/value pairs in receiver *except* +rejected+
|
164
|
+
#
|
165
|
+
# { :one => 1, :two => 2, :three => 3 }.except(:one)
|
166
|
+
# #=> { :two => 2, :three => 3 }
|
167
|
+
#
|
168
|
+
# @param [Array[String, Symbol]] *rejected The hash keys to exclude.
|
169
|
+
#
|
170
|
+
# @return [Hash] A new hash without the selected keys.
|
171
|
+
#
|
172
|
+
# @api public
|
173
|
+
def except(*rejected)
|
174
|
+
hash = self.dup
|
175
|
+
rejected.each {|k| hash.delete(k) }
|
176
|
+
hash
|
177
|
+
end
|
178
|
+
|
179
|
+
# @return [String] The hash as attributes for an XML tag.
|
180
|
+
#
|
181
|
+
# @example
|
182
|
+
# { :one => 1, "two"=>"TWO" }.to_xml_attributes
|
183
|
+
# #=> 'one="1" two="TWO"'
|
184
|
+
def to_xml_attributes
|
185
|
+
map do |k,v|
|
186
|
+
%{#{k.to_s.snake_case.sub(/^(.{1,1})/) { |m| m.downcase }}="#{v}"}
|
187
|
+
end.join(' ')
|
188
|
+
end
|
189
|
+
|
190
|
+
alias_method :to_html_attributes, :to_xml_attributes
|
191
|
+
|
192
|
+
# @param html_class<#to_s>
|
193
|
+
# The HTML class to add to the :class key. The html_class will be
|
194
|
+
# concatenated to any existing classes.
|
195
|
+
#
|
196
|
+
# @example hash[:class] #=> nil
|
197
|
+
# @example hash.add_html_class!(:selected)
|
198
|
+
# @example hash[:class] #=> "selected"
|
199
|
+
# @example hash.add_html_class!("class1 class2")
|
200
|
+
# @example hash[:class] #=> "selected class1 class2"
|
201
|
+
def add_html_class!(html_class)
|
202
|
+
if self[:class]
|
203
|
+
self[:class] = "#{self[:class]} #{html_class}"
|
204
|
+
else
|
205
|
+
self[:class] = html_class.to_s
|
206
|
+
end
|
207
|
+
end
|
208
|
+
|
209
|
+
# Converts all keys into string values. This is used during reloading to
|
210
|
+
# prevent problems when classes are no longer declared.
|
211
|
+
#
|
212
|
+
# @return [Array] An array of they hash's keys
|
213
|
+
#
|
214
|
+
# @example
|
215
|
+
# hash = { One => 1, Two => 2 }.proctect_keys!
|
216
|
+
# hash # => { "One" => 1, "Two" => 2 }
|
217
|
+
def protect_keys!
|
218
|
+
keys.each {|key| self[key.to_s] = delete(key) }
|
219
|
+
end
|
220
|
+
|
221
|
+
# Attempts to convert all string keys into Class keys. We run this after
|
222
|
+
# reloading to convert protected hashes back into usable hashes.
|
223
|
+
#
|
224
|
+
# @example
|
225
|
+
# # Provided that classes One and Two are declared in this scope:
|
226
|
+
# hash = { "One" => 1, "Two" => 2 }.unproctect_keys!
|
227
|
+
# hash # => { One => 1, Two => 2 }
|
228
|
+
def unprotect_keys!
|
229
|
+
keys.each do |key|
|
230
|
+
(self[Object.full_const_get(key)] = delete(key)) rescue nil
|
231
|
+
end
|
232
|
+
end
|
233
|
+
|
234
|
+
# Destructively and non-recursively convert each key to an uppercase string,
|
235
|
+
# deleting nil values along the way.
|
236
|
+
#
|
237
|
+
# @return [Hash] The newly environmentized hash.
|
238
|
+
#
|
239
|
+
# @example
|
240
|
+
# { :name => "Bob", :contact => { :email => "bob@bob.com" } }.environmentize_keys!
|
241
|
+
# #=> { "NAME" => "Bob", "CONTACT" => { :email => "bob@bob.com" } }
|
242
|
+
def environmentize_keys!
|
243
|
+
keys.each do |key|
|
244
|
+
val = delete(key)
|
245
|
+
next if val.nil?
|
246
|
+
self[key.to_s.upcase] = val
|
247
|
+
end
|
248
|
+
self
|
249
|
+
end
|
250
|
+
end
|
251
|
+
|
252
|
+
require 'rexml/parsers/streamparser'
|
253
|
+
require 'rexml/parsers/baseparser'
|
254
|
+
require 'rexml/light/node'
|
255
|
+
|
256
|
+
# This is a slighly modified version of the XMLUtilityNode from
|
257
|
+
# http://merb.devjavu.com/projects/merb/ticket/95 (has.sox@gmail.com)
|
258
|
+
# It's mainly just adding vowels, as I ht cd wth n vwls :)
|
259
|
+
# This represents the hard part of the work, all I did was change the
|
260
|
+
# underlying parser.
|
261
|
+
class REXMLUtilityNode
|
262
|
+
attr_accessor :name, :attributes, :children, :type
|
263
|
+
cattr_accessor :typecasts, :available_typecasts
|
264
|
+
|
265
|
+
self.typecasts = {}
|
266
|
+
self.typecasts["integer"] = lambda{|v| v.nil? ? nil : v.to_i}
|
267
|
+
self.typecasts["boolean"] = lambda{|v| v.nil? ? nil : (v.strip != "false")}
|
268
|
+
self.typecasts["datetime"] = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
|
269
|
+
self.typecasts["date"] = lambda{|v| v.nil? ? nil : Date.parse(v)}
|
270
|
+
self.typecasts["dateTime"] = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
|
271
|
+
self.typecasts["decimal"] = lambda{|v| BigDecimal(v)}
|
272
|
+
self.typecasts["double"] = lambda{|v| v.nil? ? nil : v.to_f}
|
273
|
+
self.typecasts["float"] = lambda{|v| v.nil? ? nil : v.to_f}
|
274
|
+
self.typecasts["symbol"] = lambda{|v| v.to_sym}
|
275
|
+
self.typecasts["string"] = lambda{|v| v.to_s}
|
276
|
+
self.typecasts["yaml"] = lambda{|v| v.nil? ? nil : YAML.load(v)}
|
277
|
+
self.typecasts["base64Binary"] = lambda{|v| v.unpack('m').first }
|
278
|
+
|
279
|
+
self.available_typecasts = self.typecasts.keys
|
280
|
+
|
281
|
+
def initialize(name, attributes = {})
|
282
|
+
@name = name.tr("-", "_")
|
283
|
+
# leave the type alone if we don't know what it is
|
284
|
+
@type = self.class.available_typecasts.include?(attributes["type"]) ? attributes.delete("type") : attributes["type"]
|
285
|
+
|
286
|
+
@nil_element = attributes.delete("nil") == "true"
|
287
|
+
@attributes = undasherize_keys(attributes)
|
288
|
+
@children = []
|
289
|
+
@text = false
|
290
|
+
end
|
291
|
+
|
292
|
+
def add_node(node)
|
293
|
+
@text = true if node.is_a? String
|
294
|
+
@children << node
|
295
|
+
end
|
296
|
+
|
297
|
+
def to_hash
|
298
|
+
if @type == "file"
|
299
|
+
f = StringIO.new((@children.first || '').unpack('m').first)
|
300
|
+
class << f
|
301
|
+
attr_accessor :original_filename, :content_type
|
302
|
+
end
|
303
|
+
f.original_filename = attributes['name'] || 'untitled'
|
304
|
+
f.content_type = attributes['content_type'] || 'application/octet-stream'
|
305
|
+
return {name => f}
|
306
|
+
end
|
307
|
+
|
308
|
+
if @text
|
309
|
+
return { name => typecast_value( translate_xml_entities( inner_html ) ) }
|
310
|
+
else
|
311
|
+
#change repeating groups into an array
|
312
|
+
groups = @children.inject({}) { |s,e| (s[e.name] ||= []) << e; s }
|
313
|
+
|
314
|
+
out = nil
|
315
|
+
if @type == "array"
|
316
|
+
out = []
|
317
|
+
groups.each do |k, v|
|
318
|
+
if v.size == 1
|
319
|
+
out << v.first.to_hash.entries.first.last
|
320
|
+
else
|
321
|
+
out << v.map{|e| e.to_hash[k]}
|
322
|
+
end
|
323
|
+
end
|
324
|
+
out = out.flatten
|
325
|
+
|
326
|
+
else # If Hash
|
327
|
+
out = {}
|
328
|
+
groups.each do |k,v|
|
329
|
+
if v.size == 1
|
330
|
+
out.merge!(v.first)
|
331
|
+
else
|
332
|
+
out.merge!( k => v.map{|e| e.to_hash[k]})
|
333
|
+
end
|
334
|
+
end
|
335
|
+
out.merge! attributes unless attributes.empty?
|
336
|
+
out = out.empty? ? nil : out
|
337
|
+
end
|
338
|
+
|
339
|
+
if @type && out.nil?
|
340
|
+
{ name => typecast_value(out) }
|
341
|
+
else
|
342
|
+
{ name => out }
|
343
|
+
end
|
344
|
+
end
|
345
|
+
end
|
346
|
+
|
347
|
+
# Typecasts a value based upon its type. For instance, if
|
348
|
+
# +node+ has #type == "integer",
|
349
|
+
# {{[node.typecast_value("12") #=> 12]}}
|
350
|
+
#
|
351
|
+
# @param value<String> The value that is being typecast.
|
352
|
+
#
|
353
|
+
# @details [:type options]
|
354
|
+
# "integer"::
|
355
|
+
# converts +value+ to an integer with #to_i
|
356
|
+
# "boolean"::
|
357
|
+
# checks whether +value+, after removing spaces, is the literal
|
358
|
+
# "true"
|
359
|
+
# "datetime"::
|
360
|
+
# Parses +value+ using Time.parse, and returns a UTC Time
|
361
|
+
# "date"::
|
362
|
+
# Parses +value+ using Date.parse
|
363
|
+
#
|
364
|
+
# @return [Integer, Boolean, Time, Date, Object]
|
365
|
+
# The result of typecasting +value+.
|
366
|
+
#
|
367
|
+
# @note
|
368
|
+
# If +self+ does not have a "type" key, or if it's not one of the
|
369
|
+
# options specified above, the raw +value+ will be returned.
|
370
|
+
def typecast_value(value)
|
371
|
+
return value unless @type
|
372
|
+
proc = self.class.typecasts[@type]
|
373
|
+
proc.nil? ? value : proc.call(value)
|
374
|
+
end
|
375
|
+
|
376
|
+
# Convert basic XML entities into their literal values.
|
377
|
+
#
|
378
|
+
# @param value<#gsub> An XML fragment.
|
379
|
+
#
|
380
|
+
# @return [#gsub] The XML fragment after converting entities.
|
381
|
+
def translate_xml_entities(value)
|
382
|
+
value.gsub(/</, "<").
|
383
|
+
gsub(/>/, ">").
|
384
|
+
gsub(/"/, '"').
|
385
|
+
gsub(/'/, "'").
|
386
|
+
gsub(/&/, "&")
|
387
|
+
end
|
388
|
+
|
389
|
+
# Take keys of the form foo-bar and convert them to foo_bar
|
390
|
+
def undasherize_keys(params)
|
391
|
+
params.keys.each do |key, value|
|
392
|
+
params[key.tr("-", "_")] = params.delete(key)
|
393
|
+
end
|
394
|
+
params
|
395
|
+
end
|
396
|
+
|
397
|
+
# Get the inner_html of the REXML node.
|
398
|
+
def inner_html
|
399
|
+
@children.join
|
400
|
+
end
|
401
|
+
|
402
|
+
# Converts the node into a readable HTML node.
|
403
|
+
#
|
404
|
+
# @return [String] The HTML node in text form.
|
405
|
+
def to_html
|
406
|
+
attributes.merge!(:type => @type ) if @type
|
407
|
+
"<#{name}#{attributes.to_xml_attributes}>#{@nil_element ? '' : inner_html}</#{name}>"
|
408
|
+
end
|
409
|
+
|
410
|
+
# @alias #to_html #to_s
|
411
|
+
def to_s
|
412
|
+
to_html
|
413
|
+
end
|
414
|
+
end
|
415
|
+
|
416
|
+
class ToHashParser
|
417
|
+
|
418
|
+
def self.from_xml(xml)
|
419
|
+
stack = []
|
420
|
+
parser = REXML::Parsers::BaseParser.new(xml)
|
421
|
+
|
422
|
+
while true
|
423
|
+
event = parser.pull
|
424
|
+
case event[0]
|
425
|
+
when :end_document
|
426
|
+
break
|
427
|
+
when :end_doctype, :start_doctype
|
428
|
+
# do nothing
|
429
|
+
when :start_element
|
430
|
+
stack.push REXMLUtilityNode.new(event[1], event[2])
|
431
|
+
when :end_element
|
432
|
+
if stack.size > 1
|
433
|
+
temp = stack.pop
|
434
|
+
stack.last.add_node(temp)
|
435
|
+
end
|
436
|
+
when :text, :cdata
|
437
|
+
stack.last.add_node(event[1]) unless event[1].strip.length == 0
|
438
|
+
end
|
439
|
+
end
|
440
|
+
stack.pop.to_hash
|
441
|
+
end
|
442
|
+
end
|
data/lib/extlib/hook.rb
ADDED
@@ -0,0 +1,403 @@
|
|
1
|
+
module Extlib
|
2
|
+
#
|
3
|
+
# TODO: Write more documentation!
|
4
|
+
#
|
5
|
+
# Overview
|
6
|
+
# ========
|
7
|
+
#
|
8
|
+
# The Hook module is a very simple set of AOP helpers. Basically, it
|
9
|
+
# allows the developer to specify a method or block that should run
|
10
|
+
# before or after another method.
|
11
|
+
#
|
12
|
+
# Usage
|
13
|
+
# =====
|
14
|
+
#
|
15
|
+
# Halting The Hook Stack
|
16
|
+
#
|
17
|
+
# Inheritance
|
18
|
+
#
|
19
|
+
# Other Goodies
|
20
|
+
#
|
21
|
+
# Please bring up any issues regarding Hooks with carllerche on IRC
|
22
|
+
#
|
23
|
+
module Hook
|
24
|
+
|
25
|
+
def self.included(base)
|
26
|
+
base.extend(ClassMethods)
|
27
|
+
base.const_set("CLASS_HOOKS", {}) unless base.const_defined?("CLASS_HOOKS")
|
28
|
+
base.const_set("INSTANCE_HOOKS", {}) unless base.const_defined?("INSTANCE_HOOKS")
|
29
|
+
base.class_eval do
|
30
|
+
class << self
|
31
|
+
def method_added(name)
|
32
|
+
process_method_added(name, :instance)
|
33
|
+
end
|
34
|
+
|
35
|
+
def singleton_method_added(name)
|
36
|
+
process_method_added(name, :class)
|
37
|
+
end
|
38
|
+
end
|
39
|
+
end
|
40
|
+
end
|
41
|
+
|
42
|
+
module ClassMethods
|
43
|
+
include Extlib::Assertions
|
44
|
+
# Inject code that executes before the target class method.
|
45
|
+
#
|
46
|
+
# @param target_method<Symbol> the name of the class method to inject before
|
47
|
+
# @param method_sym<Symbol> the name of the method to run before the
|
48
|
+
# target_method
|
49
|
+
# @param block<Block> the code to run before the target_method
|
50
|
+
#
|
51
|
+
# @note
|
52
|
+
# Either method_sym or block is required.
|
53
|
+
# -
|
54
|
+
# @api public
|
55
|
+
def before_class_method(target_method, method_sym = nil, &block)
|
56
|
+
install_hook :before, target_method, method_sym, :class, &block
|
57
|
+
end
|
58
|
+
|
59
|
+
#
|
60
|
+
# Inject code that executes after the target class method.
|
61
|
+
#
|
62
|
+
# @param target_method<Symbol> the name of the class method to inject after
|
63
|
+
# @param method_sym<Symbol> the name of the method to run after the target_method
|
64
|
+
# @param block<Block> the code to run after the target_method
|
65
|
+
#
|
66
|
+
# @note
|
67
|
+
# Either method_sym or block is required.
|
68
|
+
# -
|
69
|
+
# @api public
|
70
|
+
def after_class_method(target_method, method_sym = nil, &block)
|
71
|
+
install_hook :after, target_method, method_sym, :class, &block
|
72
|
+
end
|
73
|
+
|
74
|
+
#
|
75
|
+
# Inject code that executes before the target instance method.
|
76
|
+
#
|
77
|
+
# @param target_method<Symbol> the name of the instance method to inject before
|
78
|
+
# @param method_sym<Symbol> the name of the method to run before the
|
79
|
+
# target_method
|
80
|
+
# @param block<Block> the code to run before the target_method
|
81
|
+
#
|
82
|
+
# @note
|
83
|
+
# Either method_sym or block is required.
|
84
|
+
# -
|
85
|
+
# @api public
|
86
|
+
def before(target_method, method_sym = nil, &block)
|
87
|
+
install_hook :before, target_method, method_sym, :instance, &block
|
88
|
+
end
|
89
|
+
|
90
|
+
#
|
91
|
+
# Inject code that executes after the target instance method.
|
92
|
+
#
|
93
|
+
# @param target_method<Symbol> the name of the instance method to inject after
|
94
|
+
# @param method_sym<Symbol> the name of the method to run after the
|
95
|
+
# target_method
|
96
|
+
# @param block<Block> the code to run after the target_method
|
97
|
+
#
|
98
|
+
# @note
|
99
|
+
# Either method_sym or block is required.
|
100
|
+
# -
|
101
|
+
# @api public
|
102
|
+
def after(target_method, method_sym = nil, &block)
|
103
|
+
install_hook :after, target_method, method_sym, :instance, &block
|
104
|
+
end
|
105
|
+
|
106
|
+
# Register a class method as hookable. Registering a method means that
|
107
|
+
# before hooks will be run immediately before the method is invoked and
|
108
|
+
# after hooks will be called immediately after the method is invoked.
|
109
|
+
#
|
110
|
+
# @param hookable_method<Symbol> The name of the class method that should
|
111
|
+
# be hookable
|
112
|
+
# -
|
113
|
+
# @api public
|
114
|
+
def register_class_hooks(*hooks)
|
115
|
+
hooks.each { |hook| register_hook(hook, :class) }
|
116
|
+
end
|
117
|
+
|
118
|
+
# Register aninstance method as hookable. Registering a method means that
|
119
|
+
# before hooks will be run immediately before the method is invoked and
|
120
|
+
# after hooks will be called immediately after the method is invoked.
|
121
|
+
#
|
122
|
+
# @param hookable_method<Symbol> The name of the instance method that should
|
123
|
+
# be hookable
|
124
|
+
# -
|
125
|
+
# @api public
|
126
|
+
def register_instance_hooks(*hooks)
|
127
|
+
hooks.each { |hook| register_hook(hook, :instance) }
|
128
|
+
end
|
129
|
+
|
130
|
+
# Not yet implemented
|
131
|
+
def reset_hook!(target_method, scope)
|
132
|
+
raise NotImplementedError
|
133
|
+
end
|
134
|
+
|
135
|
+
# --- Alright kids... the rest is internal stuff ---
|
136
|
+
|
137
|
+
# Returns the correct HOOKS Hash depending on whether we are
|
138
|
+
# working with class methods or instance methods
|
139
|
+
def hooks_with_scope(scope)
|
140
|
+
case scope
|
141
|
+
when :class then class_hooks
|
142
|
+
when :instance then instance_hooks
|
143
|
+
else raise ArgumentError, 'You need to pass :class or :instance as scope'
|
144
|
+
end
|
145
|
+
end
|
146
|
+
|
147
|
+
def class_hooks
|
148
|
+
self.const_get("CLASS_HOOKS")
|
149
|
+
end
|
150
|
+
|
151
|
+
def instance_hooks
|
152
|
+
self.const_get("INSTANCE_HOOKS")
|
153
|
+
end
|
154
|
+
|
155
|
+
# Registers a method as hookable. Registering hooks involves the following
|
156
|
+
# process
|
157
|
+
#
|
158
|
+
# * Create a blank entry in the HOOK Hash for the method.
|
159
|
+
# * Define the methods that execute the before and after hook stack.
|
160
|
+
# These methods will be no-ops at first, but everytime a new hook is
|
161
|
+
# defined, the methods will be redefined to incorporate the new hook.
|
162
|
+
# * Redefine the method that is to be hookable so that the hook stacks
|
163
|
+
# are invoked approprietly.
|
164
|
+
def register_hook(target_method, scope)
|
165
|
+
if scope == :instance && !method_defined?(target_method)
|
166
|
+
raise ArgumentError, "#{target_method} instance method does not exist"
|
167
|
+
elsif scope == :class && !respond_to?(target_method)
|
168
|
+
raise ArgumentError, "#{target_method} class method does not exist"
|
169
|
+
end
|
170
|
+
|
171
|
+
hooks = hooks_with_scope(scope)
|
172
|
+
|
173
|
+
if hooks[target_method].nil?
|
174
|
+
hooks[target_method] = {
|
175
|
+
# We need to keep track of which class in the Inheritance chain the
|
176
|
+
# method was declared hookable in. Every time a child declares a new
|
177
|
+
# hook for the method, the hook stack invocations need to be redefined
|
178
|
+
# in the original Class. See #define_hook_stack_execution_methods
|
179
|
+
:before => [], :after => [], :in => self
|
180
|
+
}
|
181
|
+
|
182
|
+
define_hook_stack_execution_methods(target_method, scope)
|
183
|
+
define_advised_method(target_method, scope)
|
184
|
+
end
|
185
|
+
end
|
186
|
+
|
187
|
+
# Is the method registered as a hookable in the given scope.
|
188
|
+
def registered_as_hook?(target_method, scope)
|
189
|
+
! hooks_with_scope(scope)[target_method].nil?
|
190
|
+
end
|
191
|
+
|
192
|
+
# Generates names for the various utility methods. We need to do this because
|
193
|
+
# the various utility methods should not end in = so, while we're at it, we
|
194
|
+
# might as well get rid of all punctuation.
|
195
|
+
def hook_method_name(target_method, prefix, suffix)
|
196
|
+
target_method = target_method.to_s
|
197
|
+
|
198
|
+
case target_method[-1,1]
|
199
|
+
when '?' then "#{prefix}_#{target_method[0..-2]}_ques_#{suffix}"
|
200
|
+
when '!' then "#{prefix}_#{target_method[0..-2]}_bang_#{suffix}"
|
201
|
+
when '=' then "#{prefix}_#{target_method[0..-2]}_eq_#{suffix}"
|
202
|
+
# I add a _nan_ suffix here so that we don't ever encounter
|
203
|
+
# any naming conflicts.
|
204
|
+
else "#{prefix}_#{target_method[0..-1]}_nan_#{suffix}"
|
205
|
+
end
|
206
|
+
end
|
207
|
+
|
208
|
+
# This will need to be refactored
|
209
|
+
def process_method_added(method_name, scope)
|
210
|
+
hooks_with_scope(scope).each do |target_method, hooks|
|
211
|
+
if hooks[:before].any? { |hook| hook[:name] == method_name }
|
212
|
+
define_hook_stack_execution_methods(target_method, scope)
|
213
|
+
end
|
214
|
+
|
215
|
+
if hooks[:after].any? { |hook| hook[:name] == method_name }
|
216
|
+
define_hook_stack_execution_methods(target_method, scope)
|
217
|
+
end
|
218
|
+
end
|
219
|
+
end
|
220
|
+
|
221
|
+
# Defines two methods. One method executes the before hook stack. The other executes
|
222
|
+
# the after hook stack. This method will be called many times during the Class definition
|
223
|
+
# process. It should be called for each hook that is defined. It will also be called
|
224
|
+
# when a hook is redefined (to make sure that the arity hasn't changed).
|
225
|
+
def define_hook_stack_execution_methods(target_method, scope)
|
226
|
+
unless registered_as_hook?(target_method, scope)
|
227
|
+
raise ArgumentError, "#{target_method} has not be registered as a hookable #{scope} method"
|
228
|
+
end
|
229
|
+
|
230
|
+
hooks = hooks_with_scope(scope)
|
231
|
+
|
232
|
+
before_hooks = hooks[target_method][:before]
|
233
|
+
before_hooks = before_hooks.map{ |info| inline_call(info, scope) }.join("\n")
|
234
|
+
|
235
|
+
after_hooks = hooks[target_method][:after]
|
236
|
+
after_hooks = after_hooks.map{ |info| inline_call(info, scope) }.join("\n")
|
237
|
+
|
238
|
+
before_hook_name = hook_method_name(target_method, 'execute_before', 'hook_stack')
|
239
|
+
after_hook_name = hook_method_name(target_method, 'execute_after', 'hook_stack')
|
240
|
+
|
241
|
+
hooks[target_method][:in].class_eval <<-RUBY, __FILE__, __LINE__ + 1
|
242
|
+
#{scope == :class ? 'class << self' : ''}
|
243
|
+
|
244
|
+
private
|
245
|
+
|
246
|
+
remove_method :#{before_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
|
247
|
+
def #{before_hook_name}(*args)
|
248
|
+
#{before_hooks}
|
249
|
+
end
|
250
|
+
|
251
|
+
remove_method :#{after_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{after_hook_name} }
|
252
|
+
def #{after_hook_name}(*args)
|
253
|
+
#{after_hooks}
|
254
|
+
end
|
255
|
+
|
256
|
+
#{scope == :class ? 'end' : ''}
|
257
|
+
RUBY
|
258
|
+
end
|
259
|
+
|
260
|
+
# Returns ruby code that will invoke the hook. It checks the arity of the hook method
|
261
|
+
# and passes arguments accordingly.
|
262
|
+
def inline_call(method_info, scope)
|
263
|
+
name = method_info[:name]
|
264
|
+
|
265
|
+
if scope == :instance
|
266
|
+
args = method_defined?(name) && instance_method(name).arity != 0 ? '*args' : ''
|
267
|
+
#%(#{name}(#{args}) if self.class <= ObjectSpace._id2ref(#{method_info[:from].object_id}))
|
268
|
+
else
|
269
|
+
args = respond_to?(name) && method(name).arity != 0 ? '*args' : ''
|
270
|
+
#%(#{name}(#{args}) if self <= ObjectSpace._id2ref(#{method_info[:from].object_id}))
|
271
|
+
end
|
272
|
+
# ObjectSpace._id2ref should be replaced with WeakRef
|
273
|
+
%(#{name}(#{args})) # Always call hook, example: set_timestamps_on_save()
|
274
|
+
end
|
275
|
+
|
276
|
+
def define_advised_method(target_method, scope)
|
277
|
+
args = args_for(method_with_scope(target_method, scope))
|
278
|
+
|
279
|
+
renamed_target = hook_method_name(target_method, 'hookable_', 'before_advised')
|
280
|
+
|
281
|
+
source = <<-EOD
|
282
|
+
def #{target_method}(#{args})
|
283
|
+
retval = nil
|
284
|
+
catch(:halt) do
|
285
|
+
#{hook_method_name(target_method, 'execute_before', 'hook_stack')}(#{args})
|
286
|
+
retval = #{renamed_target}(#{args})
|
287
|
+
#{hook_method_name(target_method, 'execute_after', 'hook_stack')}(retval, #{args})
|
288
|
+
retval
|
289
|
+
end
|
290
|
+
end
|
291
|
+
EOD
|
292
|
+
|
293
|
+
if scope == :instance && !instance_methods(false).any? { |m| m.to_sym == target_method }
|
294
|
+
send(:alias_method, renamed_target, target_method)
|
295
|
+
|
296
|
+
proxy_module = Module.new
|
297
|
+
proxy_module.class_eval(source, __FILE__, __LINE__)
|
298
|
+
self.send(:include, proxy_module)
|
299
|
+
else
|
300
|
+
source = %{alias_method :#{renamed_target}, :#{target_method}\n#{source}}
|
301
|
+
source = %{class << self\n#{source}\nend} if scope == :class
|
302
|
+
class_eval(source, __FILE__, __LINE__)
|
303
|
+
end
|
304
|
+
end
|
305
|
+
|
306
|
+
# --- Add a hook ---
|
307
|
+
|
308
|
+
def install_hook(type, target_method, method_sym, scope, &block)
|
309
|
+
assert_kind_of 'target_method', target_method, Symbol
|
310
|
+
assert_kind_of 'method_sym', method_sym, Symbol unless method_sym.nil?
|
311
|
+
assert_kind_of 'scope', scope, Symbol
|
312
|
+
|
313
|
+
if !block_given? and method_sym.nil?
|
314
|
+
raise ArgumentError, "You need to pass 2 arguments to \"#{type}\"."
|
315
|
+
end
|
316
|
+
|
317
|
+
if method_sym.to_s[-1,1] == '='
|
318
|
+
raise ArgumentError, "Methods ending in = cannot be hooks"
|
319
|
+
end
|
320
|
+
|
321
|
+
unless [ :class, :instance ].include?(scope)
|
322
|
+
raise ArgumentError, 'You need to pass :class or :instance as scope'
|
323
|
+
end
|
324
|
+
|
325
|
+
if registered_as_hook?(target_method, scope)
|
326
|
+
hooks = hooks_with_scope(scope)
|
327
|
+
|
328
|
+
#if this hook is previously declared in a sibling or cousin we must move the :in class
|
329
|
+
#to the common ancestor to get both hooks to run.
|
330
|
+
if !(hooks[target_method][:in] <=> self)
|
331
|
+
before_hook_name = hook_method_name(target_method, 'execute_before', 'hook_stack')
|
332
|
+
after_hook_name = hook_method_name(target_method, 'execute_after', 'hook_stack')
|
333
|
+
|
334
|
+
hooks[target_method][:in].class_eval <<-RUBY, __FILE__, __LINE__ + 1
|
335
|
+
remove_method :#{before_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
|
336
|
+
def #{before_hook_name}(*args)
|
337
|
+
super
|
338
|
+
end
|
339
|
+
|
340
|
+
remove_method :#{after_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
|
341
|
+
def #{after_hook_name}(*args)
|
342
|
+
super
|
343
|
+
end
|
344
|
+
RUBY
|
345
|
+
|
346
|
+
while !(hooks[target_method][:in] <=> self) do
|
347
|
+
hooks[target_method][:in] = hooks[target_method][:in].superclass
|
348
|
+
end
|
349
|
+
|
350
|
+
define_hook_stack_execution_methods(target_method, scope)
|
351
|
+
hooks[target_method][:in].class_eval{define_advised_method(target_method, scope)}
|
352
|
+
end
|
353
|
+
else
|
354
|
+
register_hook(target_method, scope)
|
355
|
+
hooks = hooks_with_scope(scope)
|
356
|
+
end
|
357
|
+
|
358
|
+
#if we were passed a block, create a method out of it.
|
359
|
+
if block
|
360
|
+
method_sym = "__hooks_#{type}_#{quote_method(target_method)}_#{hooks[target_method][type].length}".to_sym
|
361
|
+
if scope == :class
|
362
|
+
meta_class.instance_eval do
|
363
|
+
define_method(method_sym, &block)
|
364
|
+
end
|
365
|
+
else
|
366
|
+
define_method(method_sym, &block)
|
367
|
+
end
|
368
|
+
end
|
369
|
+
|
370
|
+
# Adds method to the stack an redefines the hook invocation method
|
371
|
+
hooks[target_method][type] << { :name => method_sym, :from => self }
|
372
|
+
define_hook_stack_execution_methods(target_method, scope)
|
373
|
+
end
|
374
|
+
|
375
|
+
# --- Helpers ---
|
376
|
+
|
377
|
+
def args_for(method)
|
378
|
+
if method.arity == 0
|
379
|
+
"&block"
|
380
|
+
elsif method.arity > 0
|
381
|
+
"_" << (1 .. method.arity).to_a.join(", _") << ", &block"
|
382
|
+
elsif (method.arity + 1) < 0
|
383
|
+
"_" << (1 .. (method.arity).abs - 1).to_a.join(", _") << ", *args, &block"
|
384
|
+
else
|
385
|
+
"*args, &block"
|
386
|
+
end
|
387
|
+
end
|
388
|
+
|
389
|
+
def method_with_scope(name, scope)
|
390
|
+
case scope
|
391
|
+
when :class then method(name)
|
392
|
+
when :instance then instance_method(name)
|
393
|
+
else raise ArgumentError, 'You need to pass :class or :instance as scope'
|
394
|
+
end
|
395
|
+
end
|
396
|
+
|
397
|
+
def quote_method(name)
|
398
|
+
name.to_s.gsub(/\?$/, '_q_').gsub(/!$/, '_b_').gsub(/=$/, '_eq_')
|
399
|
+
end
|
400
|
+
end
|
401
|
+
|
402
|
+
end
|
403
|
+
end
|