RubyGems - described_routes - Versions diffs - 0.3.6 → 0.4.0 - Mend

described_routes 0.3.6 → 0.4.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.

Files changed (8) hide show

data/History.txt +4 -0
data/README.rdoc +76 -6
data/lib/described_routes.rb +1 -1
data/lib/described_routes/rails_controller.rb +3 -1
data/lib/described_routes/resource_template.rb +28 -1
data/test/test_resource_template.rb +9 -0
data/test_rails_app/test/integration/described_routes_run_time_test.rb +5 -0
metadata +4 -4

data/History.txt CHANGED Viewed

@@ -1,3 +1,7 @@
+== 0.4.0 2009-05-13
+* Partial template expansion
 == 0.3.6 2009-05-12
 * add ResourceTemplate#positional_params

data/README.rdoc CHANGED Viewed

@@ -1,13 +1,9 @@
 = described_routes README
-Framework-neutral descriptions of Rails routes in JSON, YAML, XML and plain text formats.  Also the home (for now at least) of the ResourceTemplate class.
+Framework-neutral metadata, describing Rails routes in JSON, YAML, XML and plain text formats.  Also the home (for now at least) of the ResourceTemplate class.
 Note to reader: you are invited to comment on the roadmap at http://positiveincline.com/?p=213
-== DESCRIPTION:
-Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML, XML and plain text formats for potential consumption by client applications (e.g. those based on path-to[http://github.com/asplake/path-to/tree]).
 == SYNOPSIS:
 === Build time
@@ -105,11 +101,77 @@ Example:
         edit             edit_user_profile    GET                    http://localhost:3000/users/{user_id}/profile/edit{-prefix|.|format}
         new              new_user_profile     GET                    http://localhost:3000/users/{user_id}/profile/new{-prefix|.|format}
+==== Partial template expansion
+Any query parameters passed to the controller will be used to pre-populate the templates.  In this example, the
+<code>article_id</code> and <code>format</code> parameters have been replaced, leaving <code>article_id</code>:
+  $ curl "http://localhost:3000/described_routes/user.text?format=json&user_id=dojo"
+  user                 user                 GET, PUT, DELETE       http://localhost:3000/users/dojo.json
+    edit               edit_user            GET                    http://localhost:3000/users/dojo/edit.json
+    articles           user_articles        GET, POST              http://localhost:3000/users/dojo/articles.json
+      new_user_article new_user_article     GET                    http://localhost:3000/users/dojo/articles/new.json
+      recent           recent_user_articles GET                    http://localhost:3000/users/dojo/articles/recent.json
+      {article_id}     user_article         GET, PUT, DELETE       http://localhost:3000/users/dojo/articles/{article_id}.json
+        edit           edit_user_article    GET                    http://localhost:3000/users/dojo/articles/{article_id}/edit.json
+    profile            user_profile         GET, PUT, DELETE, POST http://localhost:3000/users/dojo/profile.json
+      edit             edit_user_profile    GET                    http://localhost:3000/users/dojo/profile/edit.json
+      new              new_user_profile     GET                    http://localhost:3000/users/dojo/profile/new.json
+More typically, JSON, YAML or XML format would be requested.  Their addresses can be referenced in <code><link></code> elements in the
+<code><head></code> section of an HTML page or (better) in HTTP headers, so any resource - regardless of format - can easily link to its
+own instance-specific metadata.
+JSON example (after pretty printing):
+  $ curl "http://localhost:3000/described_routes/user_articles.yaml?user_id=dojo&format=json"
+  {
+     "name":"user_articles",
+     "rel":"articles",
+     "path_template":"\/users\/dojo\/articles.json",
+     "uri_template":"http:\/\/localhost:3000\/users\/dojo\/articles.json",
+     "options":["GET", "POST"],
+     "resource_templates":[
+        {
+           "name":"new_user_article",
+           "options":["GET"],
+           "path_template":"\/users\/dojo\/articles\/new.json",
+           "uri_template":"http:\/\/localhost:3000\/users\/dojo\/articles\/new.json",
+           "rel":"new_user_article"
+        },
+        {
+           "name":"recent_user_articles",
+           "options":["GET"],
+           "path_template":"\/users\/dojo\/articles\/recent.json",
+           "uri_template":"http:\/\/localhost:3000\/users\/dojo\/articles\/recent.json",
+           "rel":"recent"
+        },
+        {
+           "name":"user_article",
+           "resource_templates":[
+              {
+                 "name":"edit_user_article",
+                 "options":["GET"],
+                 "path_template":"\/users\/dojo\/articles\/{article_id}\/edit.json",
+                 "uri_template":"http:\/\/localhost:3000\/users\/dojo\/articles\/{article_id}\/edit.json",
+                 "rel":"edit",
+                 "params":["article_id"]
+              }
+           ],
+           "options":["GET", "PUT", "DELETE"],
+           "path_template":"\/users\/dojo\/articles\/{article_id}.json",
+           "uri_template":"http:\/\/localhost:3000\/users\/dojo\/articles\/{article_id}.json",
+           "params":["article_id"]
+        }
+     ]
+  }
 == DATA STRUCTURES and FORMATS
 === Natural structure
-The YAML and JSON representations appear as simple array and hash structures.  Each resource is represented by a hash of attributes (one of which may be a list of child resources); the top level structure is an array of the resources that don't have parents.
+The YAML and JSON representations appear as simple array and hash structures.  Each resource is represented by a hash of attributes
+(one of which may be a list of child resources); the top level structure is an array of parentless resources.
 Attributes:
@@ -136,6 +198,10 @@ This follows the natural structure but with the following modifications:
 Calls to parse_xml will at present result in NoMethodError exceptions being raised.
+=== Samples
+See <code>test_rails_app/test/fixtures</code> for sample outputs in each of the supported formats.
 == CUSTOMISATION
 It is possible to customise the data collected from Rails, for example to hide sensitive routes:
@@ -148,6 +214,10 @@ This hook operates on the raw "parsed" (Array/Hash) data before conversion to Re
 Rails, for the Rake tasks and Rails controller.  The ResourceTemplate class and its formats are however Rails-independent.
+The addressable[http://github.com/sporkmonger/addressable/tree/master] gem, used by the Rails controller for partial template
+expansion.   You will need to grab the latest from github as (at the time of writing) the latest gem package hasn't been released
+to Rubyforge.
 == INSTALL:
   sudo gem install described_routes

data/lib/described_routes.rb CHANGED Viewed

@@ -2,5 +2,5 @@ require 'described_routes/resource_template'
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.3.6"
+  VERSION = "0.4.0"
 end

data/lib/described_routes/rails_controller.rb CHANGED Viewed

@@ -5,7 +5,7 @@ module DescribedRoutes
   class RailsController < ActionController::Base
     def index
       base_url = root_url rescue nil
-      resource_templates = RailsRoutes.get_resource_templates(base_url)
+      resource_templates = ResourceTemplate.partial_expand(RailsRoutes.get_resource_templates(base_url), request.query_parameters)
       respond_to do |format|
         format.html # index.html.erb
@@ -28,6 +28,8 @@ module DescribedRoutes
       base_url = root_url rescue nil
       resources = RailsRoutes.get_resource_templates(base_url)
       resource_template = ResourceTemplate.all_by_name(resources)[params[:id]]
+      # TODO 404 if nil
+      resource_template = resource_template.partial_expand(request.query_parameters)
       respond_to do |format|
         format.html # show.html.erb

data/lib/described_routes/resource_template.rb CHANGED Viewed

@@ -1,4 +1,5 @@
 require "json"
+require "addressable/template"
 module DescribedRoutes
   class ResourceTemplate
@@ -76,7 +77,7 @@ module DescribedRoutes
     # Convert to YAML
     def to_yaml
-      to_hash.to_json
+      to_hash.to_yaml
     end
     #
@@ -216,6 +217,32 @@ module DescribedRoutes
         all_params
       end
     end
+    # Partially expand the path_template or uri_template of the given resource templates with the given params,
+    # returning new resource templates
+    def self.partial_expand(resource_templates, actual_params)
+      resource_templates.map do |resource_template|
+        resource_template.partial_expand(actual_params)
+      end
+    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,
+          self.class.partial_expand(resource_templates, actual_params))
+    end
+    # Partially expand a URI template
+    def partial_expand_uri_template(template, params)#:nodoc:
+      template && Addressable::Template.new(template).partial_expand(params).pattern
+    end
   end
 end

data/test/test_resource_template.rb CHANGED Viewed

@@ -49,4 +49,13 @@ class TestResourceTemplate < Test::Unit::TestCase
     assert_equal(["user_id", "article_id", "format"], user_article.positional_params(nil))
     assert_equal(["article_id", "format"], user_article.positional_params(user_articles))
   end
+  def test_partial_expand
+    expanded = DescribedRoutes::ResourceTemplate.all_by_name([user_articles.partial_expand("user_id" => "dojo", "format" => "json")])
+    expanded_edit_user_article = expanded["edit_user_article"]
+    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
 end

data/test_rails_app/test/integration/described_routes_run_time_test.rb CHANGED Viewed

@@ -34,4 +34,9 @@ class DescribedRoutesRunTimeTest < ActionController::IntegrationTest
     assert_response :success
     assert_equal(read_fixture("yaml_short"), body)
   end
+  def test_partial_expand
+    get "/described_routes/new_user_profile.text?user_id=dojo&format=json"
+    assert_equal("new_user_profile new_user_profile GET http://www.example.com/users/dojo/profile/new.json", body.chomp)
+  end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: described_routes
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.4.0
 platform: ruby
 authors:
 - Mike Burrows
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-05-12 00:00:00 +01:00
+date: 2009-05-13 00:00:00 +01:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -32,7 +32,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.8.0
     version:
-description: Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML, XML and plain text formats for potential consumption by client applications (e.g. those based on path-to[http://github.com/asplake/path-to/tree]).
+description: ""
 email:
 - mjb@asplake.co.uk
 executables: []
@@ -123,7 +123,7 @@ rubyforge_project: describedroutes
 rubygems_version: 1.3.3
 signing_key:
 specification_version: 3
-summary: Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML, XML and plain text formats for potential consumption by client applications (e.g
+summary: ""
 test_files:
 - test/test_described_routes.rb
 - test/test_helper.rb