described_routes 0.5.0 → 0.5.1

data/History.txt

@@ -1,3 +1,8 @@
+== 0.5.1 2009-05-22
+
+* Add ResourceTemplate::ResourceTemplate.find_by_rel
+* More low-level refactoring
+
 == 0.5.0 2009-05-22
 
 * API refactor, a possible prelude to new resource_template gem:

data/README.rdoc

@@ -24,7 +24,7 @@ Then:
   rake described_routes:yaml        # Describe resource structure in YAML format
   rake described_routes:text        # Describe resource structure in text (comparable to "rake routes")
 
-The text output looks like this:
+The JSON, XML and YAML formats (of which the YAML is the most readable) are designed for program consumption.  The more human-friendly text output looks like this:
 
   $ rake --silent described_routes:text
   root                   root                                          /
@@ -58,8 +58,6 @@ The text output looks like this:
 You can specify the base URL of your application by appending "BASE=http://..." to the rake command line.  The output will then 
 include full URI templates.
 
-The JSON, XML and YAML formats (of which the YAML is the most readable) are designed for program consumption. 
-
 === Run time
 
 Include the controller, perhaps in an initializer:

data/lib/described_routes.rb

@@ -2,5 +2,5 @@ require 'resource_template'
 
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/lib/resource_template.rb

@@ -12,9 +12,6 @@ class ResourceTemplate
   # Collection members generally don't need a rel as they are identified by their params
   attr_reader :rel
   
-  # A template for generating URIs.
-  attr_reader :uri_template
-  
   # A template for generating paths relative to the application's base.
   attr_reader :path_template
   
@@ -30,25 +27,35 @@ class ResourceTemplate
   # Nested resource templates, a Resources object
   attr_reader :resource_templates
   
-  # Initialize a ResourceTemplate.  See the attribute descriptions above for explanations of the parameters.
-  def initialize(name, rel, uri_template, path_template, params, optional_params, options, resource_templates)
-    @name, @rel, @uri_template, @path_template = name, rel, uri_template, path_template
-    @params = params || []
-    @optional_params = optional_params || []
-    @options = options || []
-    @resource_templates = resource_templates || Resources.new
-  end
-  
-  # Create a ResourceTemplate from its Hash representation
-  def self.from_hash(hash)
-    attributes = %w(name rel uri_template path_template params optional_params options).map{|k| hash[k]}
-    attributes << ResourceTemplates.new(hash["resource_templates"])
-    self.new(*attributes)
+  #
+  # Initialize a ResourceTemplate from a hash.  For example:
+  #
+  #   user_articles = ResourceTemplate.new(
+  #                       "name"               => "user_articles",
+  #                       "rel"                => "articles",
+  #                       "uri_template"       => "http://example.com/users/{user_id}/articles{-prefix|.|format}",
+  #                       "path_template"      => "/users/{user_id}/articles{-prefix|.|format}",
+  #                       "params"             => ["user_id"],
+  #                       "optional_params"    => ["format"],
+  #                       "resource_templates" => [user_article, new_user_article])
+  #
+  # <code>resource_templates</code> (if provided) can be a ResourceTemplates object, an array of ResourceTemplate objects
+  # or an array of hashes.  This last option makes it easy to initialize a whole hierarchy directly from deserialised JSON or YAML
+  # objects, e.g.:
+  #
+  #   user_articles = ResourceTemplate.new(JSON.parse(json))
+  #   user_articles = ResourceTemplate.new(YAML.load(yaml))
+  #
+  def initialize(hash={})
+    @name, @rel, @uri_template, @path_template = %w(name rel uri_template path_template).map{|attr| hash[attr]}
+    @params, @optional_params, @options = %w(params optional_params options).map{|attr| hash[attr] || []}
+    @resource_templates = ResourceTemplates.new(hash["resource_templates"])
   end
   
   # Convert to a hash (equivalent to its JSON or YAML representation)
   def to_hash
     hash = {}
+    
     hash["name"] = name if name && !name.empty?
     hash["rel"] = rel if rel && !rel.empty?
     hash["uri_template"] = uri_template if uri_template && !uri_template.empty?
@@ -56,7 +63,6 @@ class ResourceTemplate
 
     hash["params"] = params if params && !params.empty?
     hash["optional_params"] = optional_params if optional_params && !optional_params.empty?
-
     hash["options"] = options if options && !options.empty?
 
     hash["resource_templates"] = resource_templates.to_parsed if !resource_templates.empty?
@@ -115,7 +121,7 @@ class ResourceTemplate
     end
   end
 
-  # returns params and any optional_params in order, removing the parent's params
+  # Returns params and any optional_params in order, removing the parent's params
   def positional_params(parent)
     all_params = params + optional_params
     if parent
@@ -125,17 +131,51 @@ class ResourceTemplate
     end
   end
   
+  # Returns this template's URI template, or one constructed from the given base and path template.
+  def uri_template(base=nil)
+    if @uri_template
+      @uri_template
+    elsif base && path_template
+      base + path_template
+    end
+  end
+  
+  # Returns an expanded URI template with template variables filled from the given params hash.
+  # Raises ArgumentError if params doesn't contain all mandatory params.
+  def uri_for(params_hash, base=nil)
+    missing_params = params - params_hash.keys
+    unless missing_params.empty?
+      raise ArgumentError.new("missing params #{missing_params.join(', ')}")
+    end
+    
+    t = uri_template(base)
+    unless t
+      raise RuntimeError.new("uri_template(#{base.inspect})=nil; path_template=#{path_template.inspect}")
+    end
+    
+    Addressable::Template.new(t).expand(params_hash).to_s
+  end
+  
+  # Returns an expanded path template with template variables filled from the given params hash.
+  # Raises ArgumentError if params doesn't contain all mandatory params, and a RuntimeError if there is no path_template.
+  def path_for(params_hash)
+    missing_params = params - params_hash.keys
+    raise ArgumentError.new("missing params #{missing_params.join(', ')}") unless missing_params.empty?
+    raise RuntimeError.new("#path_for called on resource template #{name.inspect} that has no path_template") if path_template.nil?
+    Addressable::Template.new(path_template).expand(params_hash).to_s
+  end
+  
   # Return a new resource template with the path_template or uri_template partially expanded with the given params
   def partial_expand(actual_params)
     self.class.new(
-        name,
-        rel,
-        partial_expand_uri_template(uri_template, actual_params),
-        partial_expand_uri_template(path_template, actual_params),
-        params - actual_params.keys,
-        optional_params - actual_params.keys,
-        options,
-        resource_templates.partial_expand(actual_params))
+        "name"               => name,
+        "rel"                => rel,
+        "uri_template"       => partial_expand_uri_template(uri_template, actual_params),
+        "path_template"      => partial_expand_uri_template(path_template, actual_params),
+        "params"             => params - actual_params.keys,
+        "optional_params"    => optional_params - actual_params.keys,
+        "options"            => options,
+        "resource_templates" => resource_templates.partial_expand(actual_params))
   end
   
   # Partially expand a URI template
@@ -143,6 +183,11 @@ class ResourceTemplate
     template && Addressable::Template.new(template).partial_expand(params).pattern
   end
   
+  # Find member ResourceTemplate objects with the given rel
+  def find_by_rel(rel)
+    resource_templates.select{|resource_template| resource_template.rel == rel}
+  end
+  
   class ResourceTemplates < Array
     # Initialize Resources (i.e. a new collection of ResourceTemplate objects) from given collection of ResourceTemplates or hashes
     def initialize(collection=[])
@@ -153,7 +198,7 @@ class ResourceTemplate
           if r.kind_of?(ResourceTemplate)
             push(r)
           elsif r.kind_of?(Hash)
-            push(ResourceTemplate.from_hash(r))
+            push(ResourceTemplate.new(r))
           else
             raise ArgumentError.new("#{r.inspect} is neither a ResourceTemplate nor a Hash")
           end
@@ -161,16 +206,6 @@ class ResourceTemplate
       end
     end
 
-    # Create Resources from a YAML string
-    def self.parse_yaml(yaml)
-      new(YAML::load(yaml))
-    end
-
-    # Create Resources from a JSON string
-    def self.parse_json(json)
-      new(JSON.parse(json))
-    end
-
     # Create Resources from an XML string
     def self.parse_xml
       raise NotImplementedError.new
@@ -202,7 +237,7 @@ class ResourceTemplate
       end
       xm
     end
-
+    
     # Get a hash of all named ResourceTemplate objects contained in the supplied collection, keyed by name
     def all_by_name(h = {})
       inject(h) do |hash, resource_template|

data/test/test_resource_template.rb

@@ -6,7 +6,7 @@ class TestResourceTemplate < Test::Unit::TestCase
   
   def setup
     @json ||= File.read(File.dirname(__FILE__) + '/fixtures/described_routes_test.json')
-    @resource_templates = ResourceTemplate::ResourceTemplates.parse_json(json)
+    @resource_templates = ResourceTemplate::ResourceTemplates.new(JSON.parse(@json))
     @resource_templates_by_name = @resource_templates.all_by_name
     @user_articles = @resource_templates_by_name['user_articles']
     @user_article = @resource_templates_by_name['user_article']
@@ -45,6 +45,11 @@ class TestResourceTemplate < Test::Unit::TestCase
         YAML.load(resource_templates.to_yaml))
   end
   
+  def test_find_by_rel
+    assert_equal([user_article], user_articles.find_by_rel(nil))
+    assert_equal([edit_user_article], user_article.find_by_rel('edit'))
+  end
+  
   def test_positional_params
     assert_equal(['user_id', 'article_id', 'format'], user_article.positional_params(nil))
     assert_equal(['article_id', 'format'], user_article.positional_params(user_articles))
@@ -57,5 +62,41 @@ class TestResourceTemplate < Test::Unit::TestCase
     assert_equal(['article_id'], expanded_edit_user_article.params)
     assert(expanded_edit_user_article.optional_params.empty?)
     assert_equal('/users/dojo/articles/{article_id}/edit.json', expanded_edit_user_article.path_template)
+  end  
+  
+  def test_uri_for
+    assert_equal('http://localhost:3000/users/dojo/articles', user_articles.uri_for('user_id' => 'dojo'))
+    assert_equal('http://localhost:3000/users/dojo/articles.json', user_articles.uri_for('user_id' => 'dojo', 'format' => 'json'))
+  end
+  
+  def test_uri_for_with_missing_params
+    assert_raises(ArgumentError) do
+      user_articles.uri_for('format' => 'json') # no user_id param
+    end
+  end
+  
+  def test_uri_for_with_no_uri_template
+    users = ResourceTemplate.new('path_template' => '/users')
+    assert_raises(RuntimeError) do
+      users.uri_for({})
+    end
+    assert_equal('http://localhost:3000/users', users.uri_for({}, 'http://localhost:3000'))
+  end
+
+  def test_path_for
+    assert_equal('/users/dojo/articles', user_articles.path_for('user_id' => 'dojo'))
+    assert_equal('/users/dojo/articles.json', user_articles.path_for('user_id' => 'dojo', 'format' => 'json'))
+  end
+  
+  def test_path_for_with_missing_params
+    assert_raises(ArgumentError) do
+      user_articles.path_for('format' => 'json') # no user_id param
+    end
+  end
+  
+  def test_path_for_with_no_path_template
+    assert_raises(RuntimeError) do
+      ResourceTemplate.new.path_for({}) # no path_template
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: described_routes
 version: !ruby/object:Gem::Version 
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors: 
 - Mike Burrows
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-22 00:00:00 +01:00
+date: 2009-05-25 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency