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>.

Methods

expand   extract   inspect   keys   match   new   partial_expand   variables  

Classes and Modules

Class Addressable::Template::InvalidTemplateOperatorError
Class Addressable::Template::InvalidTemplateValueError
Class Addressable::Template::MatchData
Class Addressable::Template::TemplateOperatorAbortedError

Constants

OPERATOR_EXPANSION = /\{-([a-zA-Z]+)\|([#{anything}]+)\|([#{anything}]+)\}/
VARIABLE_EXPANSION = /\{([#{anything}]+?)(=([#{anything}]+))?\}/

Attributes

pattern  [R]  @return [String] The Template object‘s pattern.

Public Class methods

Creates a new Addressable::Template object.

@param [to_str] pattern The URI Template pattern.

@return [Addressable::Template] The initialized Template object.

Public Instance methods

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"]}

Returns a String representation of the Template object‘s state.

@return [String] The Template object‘s state, as a String.

keys()

Alias for variables

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"

Returns an Array of variables used within the template pattern. The variables are listed in the Array in the order they appear within the pattern. Multiple occurrences of a variable within a pattern are not represented in this Array.

@return [Array] The variables present in the template‘s pattern.

[Validate]