Module: URITemplate
- Extended by:
- ClassMethods
- Defined in:
- lib/uri_template.rb,
lib/uri_template/colon.rb,
lib/uri_template/utils.rb
Overview
The MIT License (MIT)
Copyright © 2011-2014 Hannes Georg
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Defined Under Namespace
Modules: ClassMethods, Expression, Invalid, InvalidValue, Literal, Token, Utils Classes: Colon, RFC6570, RegexpEnumerator, Unconvertable
Constant Summary collapse
- SCHEME_REGEX =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
/\A[a-z]+:/i.freeze
- HOST_REGEX =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
/\A(?:[a-z]+:)?\/\/[^\/]+/i.freeze
- URI_SPLIT =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
/\A(?:([a-z]+):)?(?:\/\/)?([^\/]+)?/i.freeze
- VERSIONS =
A hash with all available implementations.
{ :rfc6570 => :RFC6570, :default => :RFC6570, :colon => :Colon, :latest => :RFC6570 }
Class Method Summary collapse
-
.apply(a, method, b, *args) ⇒ Object
Applies a method to a URITemplate with another URITemplate as argument.
-
.coerce(a, b) ⇒ Tuple<URITemplate,URITemplate,Bool,Bool>
Tries to coerce two URITemplates into a common representation.
- .coerce_first_arg(meth) ⇒ Object private
-
.new(*args) ⇒ Object
Creates an uri template using an implementation.
-
.resolve_class(*args) ⇒ Object
Looks up which implementation to use.
Instance Method Summary collapse
-
#concat(other) ⇒ Object
(also: #+, #>>)
Concatenate two template with conversion.
-
#eq(other) ⇒ Object
(also: #==)
Compares two template patterns.
-
#expand(variables = {}) ⇒ Object
Expands this uri template with the given variables.
-
#expand_partial(variables = {}) ⇒ URITemplate
Works like #expand with two differences:.
-
#host? ⇒ Boolean
(also: #absolute?)
Returns whether this uri-template includes a host name.
-
#path_concat(other) ⇒ Object
(also: #/)
Tries to concatenate two templates, as if they were path segments.
-
#pattern ⇒ Object
(also: #to_s)
Returns the pattern for this template.
-
#relative? ⇒ Boolean
Opposite of #absolute?.
-
#scheme? ⇒ Boolean
Returns whether this uri-template includes a scheme.
-
#static_characters ⇒ Object
Returns the number of static characters in this template.
-
#tokens ⇒ Array<URITemplate::Token>
abstract
Returns the tokens of this templates.
-
#type ⇒ Symbol
abstract
Returns the type of this template.
-
#variables ⇒ Array<String>
Returns an array containing all variables.
Methods included from ClassMethods
convert, included, try_convert
Class Method Details
.apply(a, method, b, *args) ⇒ Object
Applies a method to a URITemplate with another URITemplate as argument. This is a useful shorthand since both URITemplates are automatically coerced.
167 168 169 170 |
# File 'lib/uri_template.rb', line 167 def self.apply(a, method, b, *args) a,b,_,_ = self.coerce(a,b) a.send(method,b,*args) end |
.coerce(a, b) ⇒ Tuple<URITemplate,URITemplate,Bool,Bool>
Tries to coerce two URITemplates into a common representation. Returns an array with two URITemplates and two booleans indicating which of the two were converted or raises an ArgumentError.
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 |
# File 'lib/uri_template.rb', line 131 def self.coerce(a,b) if a.kind_of? URITemplate if a.class == b.class return [a,b,false,false] end b_as_a = a.class.try_convert(b) if b_as_a return [a,b_as_a,false,true] end end if b.kind_of? URITemplate a_as_b = b.class.try_convert(a) if a_as_b return [a_as_b, b, true, false] end end bc = self.try_convert(b) if bc.kind_of? URITemplate a_as_b = bc.class.try_convert(a) if a_as_b return [a_as_b, bc, true, true] end end raise ArgumentError, "Expected at least on URITemplate, but got #{a.inspect} and #{b.inspect}" unless a.kind_of? URITemplate or b.kind_of? URITemplate raise ArgumentError, "Cannot coerce #{a.inspect} and #{b.inspect} into a common representation." end |
.coerce_first_arg(meth) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/uri_template.rb', line 173 def self.coerce_first_arg(meth) alias_method( (meth.to_s + '_without_coercion').to_sym , meth ) class_eval(<<-RUBY) def #{meth}(other, *args, &block) this, other, this_converted, _ = URITemplate.coerce( self, other ) if this_converted return this.#{meth}(other,*args, &block) end return #{meth}_without_coercion(other,*args, &block) end RUBY end |
.new(*args) ⇒ Object
Creates an uri template using an implementation. The args should at least contain a pattern string. Symbols in the args are used to determine the actual implementation.
118 119 120 121 |
# File 'lib/uri_template.rb', line 118 def self.new(*args) klass, rest = resolve_class(*args) return klass.new(*rest) end |
.resolve_class(*args) ⇒ Object
Looks up which implementation to use. Extracts all symbols from args and looks up the first in VERSIONS.
100 101 102 103 104 105 |
# File 'lib/uri_template.rb', line 100 def self.resolve_class(*args) symbols, rest = args.partition{|x| x.kind_of? Symbol } version = symbols.fetch(0, :default) raise ArgumentError, "Unknown template version #{version.inspect}, defined versions: #{VERSIONS.keys.inspect}" unless VERSIONS.key?(version) return self.const_get(VERSIONS[version]), rest end |
Instance Method Details
#concat(other) ⇒ Object Also known as: +, >>
Concatenate two template with conversion.
384 385 386 387 388 389 390 391 392 |
# File 'lib/uri_template.rb', line 384 def concat(other) if other.host? or other.scheme? raise ArgumentError, "Expected to receive a relative template but got an absoulte one: #{other.inspect}. If you think this is a bug, please report it." end return self if other.tokens.none? return other if self.tokens.none? return self.class.new( self.to_s + other.to_s ) end |
#eq(other) ⇒ Object Also known as: ==
Compares two template patterns.
331 332 333 |
# File 'lib/uri_template.rb', line 331 def eq(other) return self.pattern == other.pattern end |
#expand(variables = {}) ⇒ Object
Expands this uri template with the given variables. The variables should be converted to strings using URITemplate::Utils#object_to_param.
The keys in the variables hash are converted to strings in order to support the Ruby 1.9 hash syntax.
If the variables are given as an array, they will be matched against the variables in the template based on their order.
208 209 210 211 212 213 |
# File 'lib/uri_template.rb', line 208 def (variables = {}) variables = normalize_variables(variables) tokens.map{|part| part.(variables) }.join end |
#expand_partial(variables = {}) ⇒ URITemplate
Works like #expand with two differences:
- the result is a uri template instead of string
- undefined variables are left in the template
223 224 225 226 227 228 |
# File 'lib/uri_template.rb', line 223 def (variables = {}) variables = normalize_variables(variables) self.class.new(tokens.map{|part| part.(variables) }.flatten(1)) end |
#host? ⇒ Boolean Also known as: absolute?
Returns whether this uri-template includes a host name
This method is usefull to check wheter this template will generate or match a uri with a host.
300 301 302 |
# File 'lib/uri_template.rb', line 300 def host? return scheme_and_host[1] end |
#path_concat(other) ⇒ Object Also known as: /
Tries to concatenate two templates, as if they were path segments. Removes double slashes or insert one if they are missing.
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 |
# File 'lib/uri_template.rb', line 351 def path_concat(other) if other.host? or other.scheme? raise ArgumentError, "Expected to receive a relative template but got an absoulte one: #{other.inspect}. If you think this is a bug, please report it." end return self if other.tokens.none? return other if self.tokens.none? tail = self.tokens.last head = other.tokens.first if tail.ends_with_slash? if head.starts_with_slash? return self.class.new( remove_double_slash(self.tokens, other.tokens).join ) end elsif !head.starts_with_slash? return self.class.new( (self.tokens + ['/'] + other.tokens).join) end return self.class.new( (self.tokens + other.tokens).join ) end |
#pattern ⇒ Object Also known as: to_s
Returns the pattern for this template.
324 325 326 |
# File 'lib/uri_template.rb', line 324 def pattern @pattern ||= tokens.map(&:to_s).join end |
#relative? ⇒ Boolean
Opposite of #absolute?
448 449 450 |
# File 'lib/uri_template.rb', line 448 def relative? !absolute? end |
#scheme? ⇒ Boolean
Returns whether this uri-template includes a scheme
This method is usefull to check wheter this template will generate or match a uri with a scheme.
317 318 319 |
# File 'lib/uri_template.rb', line 317 def scheme? return scheme_and_host[0] end |
#static_characters ⇒ Object
Returns the number of static characters in this template. This method is useful for routing, since it’s often pointful to use the url with fewer variable characters. For example ‘static’ and ‘sta{var\}’ both match ‘static’, but in most cases ‘static’ should be prefered over ‘sta{var\}’ since it’s more specific.
282 283 284 |
# File 'lib/uri_template.rb', line 282 def static_characters @static_characters ||= tokens.select(&:literal?).map{|t| t.string.size }.inject(0,:+) end |
#tokens ⇒ Array<URITemplate::Token>
Returns the tokens of this templates. Tokens should include either Literal or Expression.
258 259 260 |
# File 'lib/uri_template.rb', line 258 def tokens raise "Please implement #tokens on #{self.class.inspect}." end |
#type ⇒ Symbol
Returns the type of this template. The type is a symbol which can be used in resolve_class to resolve the type of this template.
250 251 252 |
# File 'lib/uri_template.rb', line 250 def type raise "Please implement #type on #{self.class.inspect}." end |
#variables ⇒ Array<String>
Returns an array containing all variables. Repeated variables are ignored. The concrete order of the variables may change.
268 269 270 |
# File 'lib/uri_template.rb', line 268 def variables @variables ||= tokens.map(&:variables).flatten.uniq.freeze end |