public_suffix_service 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,7 +23,16 @@ module PublicSuffixService
23
23
  # A domain is considered invalid when no rule is found
24
24
  # in the definition list.
25
25
  #
26
- # Since 0.6.0
26
+ # @example
27
+ #
28
+ # PublicSuffixService.parse("nic.test")
29
+ # # => PublicSuffixService::DomainInvalid
30
+ #
31
+ # PublicSuffixService.parse("http://www.nic.it")
32
+ # # => PublicSuffixService::DomainInvalid
33
+ #
34
+ # @since 0.6.0
35
+ #
27
36
  class DomainInvalid < Error
28
37
  end
29
38
 
@@ -32,9 +41,7 @@ module PublicSuffixService
32
41
  # but the rules set a requirement which is not satisfied
33
42
  # by the input you are trying to parse.
34
43
  #
35
- # Since 0.6.0
36
- #
37
- # Examples
44
+ # @example
38
45
  #
39
46
  # PublicSuffixService.parse("nic.do")
40
47
  # # => PublicSuffixService::DomainNotAllowed
@@ -42,11 +49,16 @@ module PublicSuffixService
42
49
  # PublicSuffixService.parse("www.nic.do")
43
50
  # # => PublicSuffixService::Domain
44
51
  #
52
+ # @since 0.6.0
53
+ #
45
54
  class DomainNotAllowed < DomainInvalid
46
55
  end
47
56
 
48
57
 
49
58
  # Backward Compatibility
59
+ #
60
+ # @deprecated Use {PublicSuffixService::DomainInvalid}.
61
+ #
50
62
  InvalidDomain = DomainInvalid
51
63
 
52
64
  end
@@ -18,24 +18,26 @@ module PublicSuffixService
18
18
 
19
19
  class Rule
20
20
 
21
- # Takes the <tt>name</tt> of the rule, detects the specific rule class
21
+ # Takes the +name+ of the rule, detects the specific rule class
22
22
  # and creates a new instance of that class.
23
- # The <tt>name</tt> becomes the rule value.
23
+ # The +name+ becomes the rule +value+.
24
24
  #
25
- # name - The String rule definition.
25
+ # @param [String] name The rule definition.
26
26
  #
27
- # Examples
27
+ # @return [PublicSuffixService::Rule::*] A rule instance.
28
28
  #
29
+ # @example Creates a Normal rule
29
30
  # PublicSuffixService::Rule.factory("ar")
30
31
  # # => #<PublicSuffixService::Rule::Normal>
31
32
  #
33
+ # @example Creates a Wildcard rule
32
34
  # PublicSuffixService::Rule.factory("*.ar")
33
35
  # # => #<PublicSuffixService::Rule::Wildcard>
34
36
  #
37
+ # @example Creates an Exception rule
35
38
  # PublicSuffixService::Rule.factory("!congresodelalengua3.ar")
36
39
  # # => #<PublicSuffixService::Rule::Exception>
37
40
  #
38
- # Returns a rule instance, a kind of PublicSuffixService::Rule::Base.
39
41
  def self.factory(name)
40
42
  klass = case name.to_s[0..0]
41
43
  when "*" then "wildcard"
@@ -53,20 +55,20 @@ module PublicSuffixService
53
55
  # in the {Public Suffix List}[http://publicsuffix.org].
54
56
  #
55
57
  # This is intended to be an Abstract class
56
- # and you sholnd't create a direct instance. The only purpose
58
+ # and you shouldn't create a direct instance. The only purpose
57
59
  # of this class is to expose a common interface
58
60
  # for all the available subclasses.
59
61
  #
60
- # * PublicSuffixService::Rule::Normal
61
- # * PublicSuffixService::Rule::Exception
62
- # * PublicSuffixService::Rule::Wildcard
62
+ # * {PublicSuffixService::Rule::Normal}
63
+ # * {PublicSuffixService::Rule::Exception}
64
+ # * {PublicSuffixService::Rule::Wildcard}
63
65
  #
64
66
  # == Properties
65
67
  #
66
68
  # A rule is composed by 4 properties:
67
69
  #
68
70
  # name - The name of the rule, corresponding to the rule definition
69
- # in the public suffic list
71
+ # in the public suffix list
70
72
  # value - The value, a normalized version of the rule name.
71
73
  # The normalization process depends on rule tpe.
72
74
  # type - The rule type (:normal, :wildcard, :exception)
@@ -128,12 +130,20 @@ module PublicSuffixService
128
130
  # rule.decompose("www.google.com")
129
131
  # # => ["www.google", "com"]
130
132
  #
133
+ # @abstract
134
+ #
131
135
  class Base
132
136
 
133
137
  attr_reader :name, :value, :type, :labels
134
138
 
135
139
  # Initializes a new rule with name and value.
136
- # If value is nil, name also becomes the value for this rule.
140
+ # If value is +nil+, name also becomes the value for this rule.
141
+ #
142
+ # @param [String] name
143
+ # The name of the rule
144
+ # @param [String] value
145
+ # The value of the rule. If nil, defaults to +name+.
146
+ #
137
147
  def initialize(name, value = nil)
138
148
  @name = name.to_s
139
149
  @value = value || @name
@@ -143,10 +153,12 @@ module PublicSuffixService
143
153
 
144
154
  # Checks whether this rule is equal to <tt>other</tt>.
145
155
  #
146
- # other - The PublicSuffixService::Rule::Base to compare.
156
+ # @param [PublicSuffixService::Rule::*] other
157
+ # The rule to compare.
147
158
  #
148
- # Returns true if this rule and other are instances of the same class
149
- # and has the same value, false otherwise.
159
+ # @return [Boolean]
160
+ # Returns true if this rule and other are instances of the same class
161
+ # and has the same value, false otherwise.
150
162
  def ==(other)
151
163
  return false unless other.is_a?(self.class)
152
164
  self.equal?(other) ||
@@ -155,32 +167,72 @@ module PublicSuffixService
155
167
  alias :eql? :==
156
168
 
157
169
 
158
- # Checks whether this rule matches <tt>domain</tt>.
170
+ # Checks if this rule matches +domain+.
171
+ #
172
+ # @param [String, #to_s] domain
173
+ # The domain name to check.
159
174
  #
160
- # domain - The String domain name to check.
175
+ # @return [Boolean]
176
+ #
177
+ # @example
178
+ # rule = Rule.factory("com")
179
+ # # #<PublicSuffixService::Rule::Normal>
180
+ # rule.match?("example.com")
181
+ # # => true
182
+ # rule.match?("example.net")
183
+ # # => false
161
184
  #
162
- # Returns Boolean.
163
185
  def match?(domain)
164
186
  l1 = labels
165
187
  l2 = Domain.domain_to_labels(domain)
166
188
  odiff(l1, l2).empty?
167
189
  end
168
190
 
191
+ # Checks if this rule allows +domain+.
192
+ #
193
+ # @param [String, #to_s] domain
194
+ # The domain name to check.
195
+ #
196
+ # @return [Boolean]
197
+ #
198
+ # @example
199
+ # rule = Rule.factory("*.do")
200
+ # # #<PublicSuffixService::Rule::Wildcard>
201
+ # rule.allow?("example.do")
202
+ # # => false
203
+ # rule.allow?("www.example.do")
204
+ # # => true
205
+ #
206
+ def allow?(domain)
207
+ !decompose(domain).last.nil?
208
+ end
209
+
210
+
169
211
  # Gets the length of this rule for comparison.
170
- # The length usually matches the number of rule <tt>parts</tt>.
212
+ # The length usually matches the number of rule +parts+.
213
+ #
171
214
  # Subclasses might actually override this method.
172
215
  #
173
- # Returns an Integer with the number of parts.
216
+ # @return [Integer] The number of parts.
174
217
  def length
175
218
  parts.length
176
219
  end
177
220
 
178
- # Raises NotImplementedError.
221
+ #
222
+ # @raise [NotImplementedError]
223
+ # @abstract
179
224
  def parts
180
225
  raise NotImplementedError
181
226
  end
182
227
 
183
- # Raises NotImplementedError.
228
+ #
229
+ # @param [String, #to_s] domain
230
+ # The domain name to decompose.
231
+ #
232
+ # @return [Array<String, nil>]
233
+ #
234
+ # @raise [NotImplementedError]
235
+ # @abstract
184
236
  def decompose(domain)
185
237
  raise NotImplementedError
186
238
  end
@@ -188,7 +240,6 @@ module PublicSuffixService
188
240
 
189
241
  private
190
242
 
191
-
192
243
  def odiff(one, two)
193
244
  ii = 0
194
245
  while(ii < one.size && one[ii] == two[ii])
@@ -201,6 +252,11 @@ module PublicSuffixService
201
252
 
202
253
  class Normal < Base
203
254
 
255
+ # Initializes a new rule with +name+.
256
+ #
257
+ # @param [String] name
258
+ # The name of this rule.
259
+ #
204
260
  def initialize(name)
205
261
  super(name, name)
206
262
  end
@@ -208,16 +264,19 @@ module PublicSuffixService
208
264
  # dot-split rule value and returns all rule parts
209
265
  # in the order they appear in the value.
210
266
  #
211
- # Returns an Array with the domain parts.
267
+ # @return [Array<String>]
212
268
  def parts
213
269
  @parts ||= @value.split(".")
214
270
  end
215
271
 
216
272
  # Decomposes the domain according to rule properties.
217
273
  #
218
- # domain - The String domain name to parse.
274
+ # @param [String, #to_s] domain
275
+ # The domain name to decompose.
276
+ #
277
+ # @return [Array<String>]
278
+ # The array with [trd + sld, tld].
219
279
  #
220
- # Return an Array with [trd + sld, tld].
221
280
  def decompose(domain)
222
281
  domain.to_s =~ /^(.*)\.(#{parts.join('\.')})$/
223
282
  [$1, $2]
@@ -227,6 +286,11 @@ module PublicSuffixService
227
286
 
228
287
  class Wildcard < Base
229
288
 
289
+ # Initializes a new rule with +name+.
290
+ #
291
+ # @param [String] name
292
+ # The name of this rule.
293
+ #
230
294
  def initialize(name)
231
295
  super(name, name.to_s[2..-1])
232
296
  end
@@ -234,20 +298,27 @@ module PublicSuffixService
234
298
  # dot-split rule value and returns all rule parts
235
299
  # in the order they appear in the value.
236
300
  #
237
- # Returns an Array with the domain parts.
301
+ # @return [Array<String>]
238
302
  def parts
239
303
  @parts ||= @value.split(".")
240
304
  end
241
305
 
306
+ # Overwrites the default implementation to cope with
307
+ # the +*+ char.
308
+ #
309
+ # @return [Integer] The number of parts.
242
310
  def length
243
311
  parts.length + 1 # * counts as 1
244
312
  end
245
313
 
246
314
  # Decomposes the domain according to rule properties.
247
315
  #
248
- # domain - The String domain name to parse.
316
+ # @param [String, #to_s] domain
317
+ # The domain name to decompose.
318
+ #
319
+ # @return [Array<String>]
320
+ # The array with [trd + sld, tld].
249
321
  #
250
- # Return an Array with [trd + sld, tld].
251
322
  def decompose(domain)
252
323
  domain.to_s =~ /^(.*)\.(.*?\.#{parts.join('\.')})$/
253
324
  [$1, $2]
@@ -257,6 +328,10 @@ module PublicSuffixService
257
328
 
258
329
  class Exception < Base
259
330
 
331
+ # Initializes a new rule with +name+.
332
+ #
333
+ # @param [String] name The name of this rule.
334
+ #
260
335
  def initialize(name)
261
336
  super(name, name.to_s[1..-1])
262
337
  end
@@ -269,16 +344,19 @@ module PublicSuffixService
269
344
  # If the prevailing rule is a exception rule,
270
345
  # modify it by removing the leftmost label.
271
346
  #
272
- # Returns an Array with the domain parts.
347
+ # @return [Array<String>]
273
348
  def parts
274
349
  @parts ||= @value.split(".")[1..-1]
275
350
  end
276
351
 
277
352
  # Decomposes the domain according to rule properties.
278
353
  #
279
- # domain - The String domain name to parse.
354
+ # @param [String, #to_s] domain
355
+ # The domain name to decompose.
356
+ #
357
+ # @return [Array<String>]
358
+ # The array with [trd + sld, tld].
280
359
  #
281
- # Return an Array with [trd + sld, tld].
282
360
  def decompose(domain)
283
361
  domain.to_s =~ /^(.*)\.(#{parts.join('\.')})$/
284
362
  [$1, $2]
@@ -16,11 +16,11 @@
16
16
 
17
17
  module PublicSuffixService
18
18
 
19
- # = Rule List
19
+ # A {PublicSuffixService::RuleList} is a collection of one
20
+ # or more {PublicSuffixService::Rule}.
20
21
  #
21
- # A PublicSuffixService::RuleList is a collection of one or more PublicSuffixService::Rule.
22
- #
23
- # Given a RuleList, you can add or remove PublicSuffixService::Rule,
22
+ # Given a {PublicSuffixService::RuleList},
23
+ # you can add or remove {PublicSuffixService::Rule},
24
24
  # iterate all items in the list or search for the first rule
25
25
  # which matches a specific domain name.
26
26
  #
@@ -41,47 +41,48 @@ module PublicSuffixService
41
41
  # list.find("example.org")
42
42
  # # => nil
43
43
  #
44
- # You can create as many PublicSuffixService::RuleList you want.
45
- # The PublicSuffixService::RuleList.default rule list is used by DomainName
44
+ # You can create as many {PublicSuffixService::RuleList} you want.
45
+ # The {PublicSuffixService::RuleList.default} rule list is used
46
46
  # to tokenize and validate a domain.
47
47
  #
48
- # PublicSuffixService::RuleList implements Enumerable module.
48
+ # {PublicSuffixService::RuleList} implements +Enumerable+ module.
49
49
  #
50
50
  class RuleList
51
51
  include Enumerable
52
52
 
53
53
  # Gets the list of rules.
54
54
  #
55
- # Returns the Array of rule instances.
56
- # Each rule is an instance of the proper corresponding of
57
- # PublicSuffixService::Rule::Base.
55
+ # @return [Array<PublicSuffixService::Rule::*>]
58
56
  attr_reader :list
59
57
 
60
58
  # Gets the naive index, a hash that with the keys being the first label of
61
59
  # every rule pointing to an array of integers (indexes of the rules in @list)
62
- attr_reader :indexes
60
+ #
61
+ # @return [Array]
62
+ attr_reader :indexes
63
63
 
64
64
 
65
- # Initializes an empty PublicSuffixService::RuleList.
66
- # If block is given, yields on self.
67
- def initialize(&block) # :yields: self
65
+ # Initializes an empty {PublicSuffixService::RuleList}.
66
+ #
67
+ # @yield [self] Yields on self.
68
+ # @yieldparam [PublicSuffixService::RuleList] self The newly creates instance
69
+ #
70
+ def initialize(&block)
68
71
  @list = []
69
72
  @indexes = {}
70
73
  yield(self) if block_given?
71
74
  create_index!
72
75
  end
73
76
 
74
- # Creates a naive index for @list. Just a hash that will tell
75
- # us where the elements of @list are relative to its first
76
- # Rule#labels element.
77
+ # Creates a naive index for +@list+. Just a hash that will tell
78
+ # us where the elements of +@list+ are relative to its first
79
+ # {PublicSuffixService::Rule::Base#labels} element.
77
80
  #
78
81
  # For instance if @list[5] and @list[4] are the only elements of the list
79
82
  # where Rule#labels.first is 'us' @indexes['us'] #=> [5,4], that way in
80
83
  # select we can avoid mapping every single rule against the candidate domain.
81
- #
82
- # Returns nothing.
83
84
  def create_index!
84
- @list.map{|l| l.labels.first }.each_with_index do |elm, inx|
85
+ @list.map { |l| l.labels.first }.each_with_index do |elm, inx|
85
86
  if !@indexes.has_key?(elm)
86
87
  @indexes[elm] = [inx]
87
88
  else
@@ -91,14 +92,16 @@ module PublicSuffixService
91
92
  end
92
93
 
93
94
  # Checks whether two lists are equal.
95
+ #
94
96
  # RuleList <tt>one</tt> is equal to <tt>two</tt>, if <tt>two</tt> is an instance of
95
- # <tt>PublicSuffixService::RuleList</tt> and each <tt>PublicSuffixService::Rule::Base</tt>
97
+ # {PublicSuffixService::RuleList} and each +PublicSuffixService::Rule::*+
96
98
  # in list <tt>one</tt> is available in list <tt>two</tt>,
97
99
  # in the same order.
98
100
  #
99
- # other - The PublicSuffixService::RuleList to compare.
101
+ # @param [PublicSuffixService::RuleList] other
102
+ # The rule list to compare.
100
103
  #
101
- # Returns true if self is equal to other.
104
+ # @return [Boolean]
102
105
  def ==(other)
103
106
  return false unless other.is_a?(RuleList)
104
107
  self.equal?(other) ||
@@ -107,34 +110,40 @@ module PublicSuffixService
107
110
  alias :eql? :==
108
111
 
109
112
  # Iterates each rule in the list.
110
- #
111
- # Returns nothing.
112
113
  def each(*args, &block)
113
114
  @list.each(*args, &block)
114
115
  end
115
116
 
116
- # Gets the list as Array.
117
+ # Gets the list as array.
117
118
  #
118
- # Return an Array.
119
+ # @return [Array<PublicSuffixService::Rule::*>]
119
120
  def to_a
120
121
  @list
121
122
  end
122
123
 
123
- # Adds the given object to the list.
124
+ # Adds the given object to the list
125
+ # and optionally refreshes the rule index.
124
126
  #
125
- # rule - The rule to add to the list.
126
- # Expected to be a subclass of PublicSuffixService::Rule::Base.
127
+ # @param [PublicSuffixService::Rule::*] rule
128
+ # The rule to add to the list.
129
+ # @param [Boolean] index
130
+ # Set to true to recreate the rule index
131
+ # after the rule has been added to the list.
127
132
  #
128
- # Returns self.
129
- def add(rule)
133
+ # @return [self]
134
+ #
135
+ # @see #create_index!
136
+ #
137
+ def add(rule, index = true)
130
138
  @list << rule
139
+ create_index! if index == true
131
140
  self
132
141
  end
133
142
  alias << add
134
143
 
135
144
  # Gets the number of elements in the list.
136
145
  #
137
- # Returns an Integer.
146
+ # @return [Integer]
138
147
  def size
139
148
  @list.size
140
149
  end
@@ -142,14 +151,14 @@ module PublicSuffixService
142
151
 
143
152
  # Checks whether the list is empty.
144
153
  #
145
- # Returns true if the list contains no elements.
154
+ # @return [Boolean]
146
155
  def empty?
147
156
  @list.empty?
148
157
  end
149
158
 
150
159
  # Removes all elements.
151
160
  #
152
- # Returns self.
161
+ # @return [self]
153
162
  def clear
154
163
  @list.clear
155
164
  self
@@ -176,9 +185,7 @@ module PublicSuffixService
176
185
  # which directly match the labels of the prevailing rule (joined by dots).
177
186
  # * The registered domain is the public suffix plus one additional label.
178
187
  #
179
- # Note: This might not be the most efficient algorithm.
180
- #
181
- # Returns a PublicSuffixService::Rule::Base instance or nil.
188
+ # @return [PublicSuffixService::Rule::*, nil]
182
189
  def find(domain)
183
190
  rules = select(domain)
184
191
  rules.select { |r| r.type == :exception }.first ||
@@ -187,14 +194,14 @@ module PublicSuffixService
187
194
 
188
195
  # Selects all the rules matching given domain.
189
196
  #
190
- # Will use @indexes to try only the rules that share the same first label,
191
- # that will speed up things when using RuleList.find('foo') a lot.
197
+ # Will use +@indexes+ to try only the rules that share the same first label,
198
+ # that will speed up things when using +RuleList.find('foo')+ a lot.
192
199
  #
193
- # Returns an Array of rule instances.
194
- # Each rule is an instance of the corresponding subclass of
195
- # PublicSuffixService::Rule::Base.
200
+ # @param [String, #to_s] domain The domain name.
201
+ #
202
+ # @return [Array<PublicSuffixService::Rule::*>]
196
203
  def select(domain)
197
- indices = (@indexes[ Domain.domain_to_labels(domain).first ] || [])
204
+ indices = (@indexes[Domain.domain_to_labels(domain).first] || [])
198
205
  @list.values_at(*indices).select { |rule| rule.match?(domain) }
199
206
  end
200
207
 
@@ -203,36 +210,37 @@ module PublicSuffixService
203
210
 
204
211
  class << self
205
212
 
206
- # Gets the default PublicSuffixService::RuleList.
207
- # Initializes a new PublicSuffixService::RuleList parsing the content
208
- # of PublicSuffixService::RuleList.default_definition, if required.
213
+ # Gets the default rule list.
214
+ # Initializes a new {PublicSuffixService::RuleList} parsing the content
215
+ # of {PublicSuffixService::RuleList.default_definition}, if required.
209
216
  #
210
- # Returns a PublicSuffixService::RuleList.
217
+ # @return [PublicSuffixService::RuleList]
211
218
  def default
212
219
  @@default ||= parse(default_definition)
213
220
  end
214
221
 
215
- # Sets the default <tt>PublicSuffixService::RuleList</tt> to <tt>value</tt>.
222
+ # Sets the default rule list to +value+.
216
223
  #
217
- # value - The new PublicSuffixService::RuleList.
224
+ # @param [PublicSuffixService::RuleList] value
225
+ # The new rule list.
218
226
  #
219
- # Returns the PublicSuffixService::RuleList.
227
+ # @return [PublicSuffixService::RuleList]
220
228
  def default=(value)
221
229
  @@default = value
222
230
  end
223
231
 
224
- # Sets the default PublicSuffixService::RuleList to nil.
232
+ # Sets the default rule list to +nil+.
225
233
  #
226
- # Returns self.
234
+ # @return [self]
227
235
  def clear
228
236
  self.default = nil
229
237
  self
230
238
  end
231
239
 
232
- # Resets the default <tt>PublicSuffixService::RuleList</tt> and reinitialize it
233
- # parsing the content of <tt>PublicSuffixService::RuleList.default_definition</tt>.
240
+ # Resets the default rule list and reinitialize it
241
+ # parsing the content of {PublicSuffixService::RuleList.default_definition}.
234
242
  #
235
- # Returns a PublicSuffixService::RuleList.
243
+ # @return [PublicSuffixService::RuleList]
236
244
  def reload
237
245
  self.clear.default
238
246
  end
@@ -242,18 +250,19 @@ module PublicSuffixService
242
250
  # or a simple <tt>String</tt>.
243
251
  # The object must respond to <tt>#each_line</tt>.
244
252
  #
245
- # Returns a File.
253
+ # @return [File]
246
254
  def default_definition
247
255
  File.new(File.join(File.dirname(__FILE__), "definitions.dat"))
248
256
  end
249
257
 
250
258
 
251
- # Parse given <tt>input</tt> treating the content as Public Suffic List.
259
+ # Parse given +input+ treating the content as Public Suffix List.
260
+ #
252
261
  # See http://publicsuffix.org/format/ for more details about input format.
253
262
  #
254
- # Returns an Array of rule instances.
255
- # Each rule is an instance of the corresponding subclass of
256
- # PublicSuffixService::Rule::Base.
263
+ # @param [String] input The rule list to parse.
264
+ #
265
+ # @return [Array<PublicSuffixService::Rule::*>]
257
266
  def parse(input)
258
267
  new do |list|
259
268
  input.each_line do |line|
@@ -267,7 +276,7 @@ module PublicSuffixService
267
276
  next
268
277
  # append rule
269
278
  else
270
- list << Rule.factory(line)
279
+ list.add(Rule.factory(line), false)
271
280
  end
272
281
  end
273
282
  end