Class | Addressable::Template |
In: |
lib/addressable/template.rb
|
Parent: | Object |
This is an implementation of a URI template based on <a href="URI">tinyurl.com/uritemplatedraft03">URI Template draft 03</a>.
OPERATOR_EXPANSION | = | /\{-([a-zA-Z]+)\|([#{anything}]+)\|([#{anything}]+)\}/ |
VARIABLE_EXPANSION | = | /\{([#{anything}]+?)(=([#{anything}]+))?\}/ |
pattern | [R] | @return [String] The Template object‘s pattern. |
Creates a new Addressable::Template object.
@param [to_str] pattern The URI Template pattern.
@return [Addressable::Template] The initialized Template object.
Expands a URI template into a full URI.
@param [Hash] mapping The mapping that corresponds to the pattern. @param [validate, transform] processor
An optional processor object may be supplied. The object should respond to either the <tt>validate</tt> or <tt>transform</tt> messages or both. Both the <tt>validate</tt> and <tt>transform</tt> methods should take two parameters: <tt>name</tt> and <tt>value</tt>. The <tt>validate</tt> method should return <tt>true</tt> or <tt>false</tt>; <tt>true</tt> if the value of the variable is valid, <tt>false</tt> otherwise. An <tt>InvalidTemplateValueError</tt> exception will be raised if the value is invalid. The <tt>transform</tt> method should return the transformed variable value as a <tt>String</tt>. If a <tt>transform</tt> method is used, the value will not be percent encoded automatically. Unicode normalization will be performed both before and after sending the value to the transform method.
@return [Addressable::URI] The expanded URI template.
@example
class ExampleProcessor def self.validate(name, value) return !!(value =~ /^[\w ]+$/) if name == "query" return true end def self.transform(name, value) return value.gsub(/ /, "+") if name == "query" return value end end Addressable::Template.new( "http://example.com/search/{query}/" ).expand( {"query" => "an example search query"}, ExampleProcessor ).to_str #=> "http://example.com/search/an+example+search+query/" Addressable::Template.new( "http://example.com/search/{-list|+|query}/" ).expand( {"query" => "an example search query".split(" ")} ).to_str #=> "http://example.com/search/an+example+search+query/" Addressable::Template.new( "http://example.com/search/{query}/" ).expand( {"query" => "bogus!"}, ExampleProcessor ).to_str #=> Addressable::Template::InvalidTemplateValueError
Extracts a mapping from the URI using a URI Template pattern.
@param [Addressable::URI, to_str] uri
The URI to extract from.
@param [restore, match] processor
A template processor object may optionally be supplied. The object should respond to either the <tt>restore</tt> or <tt>match</tt> messages or both. The <tt>restore</tt> method should take two parameters: [String] name and [String] value. The <tt>restore</tt> method should reverse any transformations that have been performed on the value to ensure a valid URI. The <tt>match</tt> method should take a single parameter: [String] name. The <tt>match</tt> method should return a <tt>String</tt> containing a regular expression capture group for matching on that particular variable. The default value is ".*?". The <tt>match</tt> method has no effect on multivariate operator expansions.
@return [Hash, NilClass]
The <tt>Hash</tt> mapping that was extracted from the URI, or <tt>nil</tt> if the URI didn't match the template.
@example
class ExampleProcessor def self.restore(name, value) return value.gsub(/\+/, " ") if name == "query" return value end def self.match(name) return ".*?" if name == "first" return ".*" end end uri = Addressable::URI.parse( "http://example.com/search/an+example+search+query/" ) Addressable::Template.new( "http://example.com/search/{query}/" ).extract(uri, ExampleProcessor) #=> {"query" => "an example search query"} uri = Addressable::URI.parse("http://example.com/a/b/c/") Addressable::Template.new( "http://example.com/{first}/{second}/" ).extract(uri, ExampleProcessor) #=> {"first" => "a", "second" => "b/c"} uri = Addressable::URI.parse("http://example.com/a/b/c/") Addressable::Template.new( "http://example.com/{first}/{-list|/|second}/" ).extract(uri) #=> {"first" => "a", "second" => ["b", "c"]}
Extracts match data from the URI using a URI Template pattern.
@param [Addressable::URI, to_str] uri
The URI to extract from.
@param [restore, match] processor
A template processor object may optionally be supplied. The object should respond to either the <tt>restore</tt> or <tt>match</tt> messages or both. The <tt>restore</tt> method should take two parameters: [String] name and [String] value. The <tt>restore</tt> method should reverse any transformations that have been performed on the value to ensure a valid URI. The <tt>match</tt> method should take a single parameter: [String] name. The <tt>match</tt> method should return a <tt>String</tt> containing a regular expression capture group for matching on that particular variable. The default value is ".*?". The <tt>match</tt> method has no effect on multivariate operator expansions.
@return [Hash, NilClass]
The <tt>Hash</tt> mapping that was extracted from the URI, or <tt>nil</tt> if the URI didn't match the template.
@example
class ExampleProcessor def self.restore(name, value) return value.gsub(/\+/, " ") if name == "query" return value end def self.match(name) return ".*?" if name == "first" return ".*" end end uri = Addressable::URI.parse( "http://example.com/search/an+example+search+query/" ) match = Addressable::Template.new( "http://example.com/search/{query}/" ).match(uri, ExampleProcessor) match.variables #=> ["query"] match.captures #=> ["an example search query"] uri = Addressable::URI.parse("http://example.com/a/b/c/") match = Addressable::Template.new( "http://example.com/{first}/{second}/" ).match(uri, ExampleProcessor) match.variables #=> ["first", "second"] match.captures #=> ["a", "b/c"] uri = Addressable::URI.parse("http://example.com/a/b/c/") match = Addressable::Template.new( "http://example.com/{first}/{-list|/|second}/" ).match(uri) match.variables #=> ["first", "second"] match.captures #=> ["a", ["b", "c"]]
Expands a URI template into another URI template.
@param [Hash] mapping The mapping that corresponds to the pattern. @param [validate, transform] processor
An optional processor object may be supplied. The object should respond to either the <tt>validate</tt> or <tt>transform</tt> messages or both. Both the <tt>validate</tt> and <tt>transform</tt> methods should take two parameters: <tt>name</tt> and <tt>value</tt>. The <tt>validate</tt> method should return <tt>true</tt> or <tt>false</tt>; <tt>true</tt> if the value of the variable is valid, <tt>false</tt> otherwise. An <tt>InvalidTemplateValueError</tt> exception will be raised if the value is invalid. The <tt>transform</tt> method should return the transformed variable value as a <tt>String</tt>. If a <tt>transform</tt> method is used, the value will not be percent encoded automatically. Unicode normalization will be performed both before and after sending the value to the transform method.
@return [Addressable::Template] The partially expanded URI template.
@example
Addressable::Template.new( "http://example.com/{one}/{two}/" ).partial_expand({"one" => "1"}).pattern #=> "http://example.com/1/{two}/" Addressable::Template.new( "http://example.com/search/{-list|+|query}/" ).partial_expand( {"query" => "an example search query".split(" ")} ).pattern #=> "http://example.com/search/an+example+search+query/" Addressable::Template.new( "http://example.com/{-join|&|one,two}/" ).partial_expand({"one" => "1"}).pattern #=> "http://example.com/?one=1{-prefix|&two=|two}" Addressable::Template.new( "http://example.com/{-join|&|one,two,three}/" ).partial_expand({"one" => "1", "three" => 3}).pattern #=> "http://example.com/?one=1{-prefix|&two=|two}&three=3"