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

described_routes 0.3.6 → 0.4.0

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