described_routes 0.1.4 → 0.2.0

data/History.txt

@@ -1,4 +1,12 @@
-== 0.1.1 2009-04-24
+== 0.2.0 2009-04-29
+
+* 1 minor enhancement:
+  * add show method to controller
+* other:
+  * add tests
+  * refactoring
+
+== 0.1.1 2009-04-28
 
 * 1 minor enhancement:
   * include uri_template elements in XML

data/Manifest.txt

@@ -12,6 +12,7 @@ lib/tasks/described_routes.rb
 script/console
 script/destroy
 script/generate
+test/fixtures/described_routes_test.json
 test/test_described_routes.rb
 test/test_helper.rb
 test/test_resource_template.rb

data/README.rdoc

@@ -6,7 +6,7 @@ Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YA
 
 == SYNOPSIS:
 
-=== Build-time output
+=== Build time
 
 In your Rakefile:
 
@@ -16,7 +16,6 @@ Then:
 
   $ rake --tasks described_routes
   rake described_routes:json        # Describe resource structure in JSON format
-  rake described_routes:ruby        # Describe resource structure as a Ruby literal
   rake described_routes:xml         # Describe resource structure in XML format
   rake described_routes:yaml        # Describe resource structure in YAML format
   rake described_routes:yaml_short  # Describe resource structure in YAML format (basic structure only)
@@ -62,20 +61,27 @@ Add the following route in config/routes.rb:
 
   map.resources :described_routes, :controller => "described_routes/rails"
 
-You (or your client application) can now browse to any of the following:
+You (or your client application) can now browse to any of the following top level addresses:
 
 * .../described_routes.json
 * .../described_routes.xml
 * .../described_routes.yaml
 * .../described_routes.yaml?short=true
 
-If the application has a route named "root", run-time-generated data will include URI templates based on root_url.
+and for the named route "users" (say):
+
+* .../described_routes/users.json
+* .../described_routes/users.xml
+* .../described_routes/users.yaml
+* .../described_routes/users.yaml?short=true
+
+If the application has a route named "root", run-time-generated data will include uri_template attributes based on root_url in addition to the path_template attributes supported at build time.
  
 == DATA STRUCTURES and FORMATS
 
 === Natural structure
 
-The YAML, JSON and Ruby representations appear as simple array and hash structures (which is what they're generated from internally).  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 (which is what they're generated from internally).  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.
 
 Attributes:
 
@@ -95,23 +101,21 @@ Note that only named routes are considered.  Pre-Rails 2.3 "formatted routes" ar
 
 This follows the natural structure but with the following modifications:
 
-* A +Resource+ element for each resource
-* A +Resources+ element for each list of resources (top level or subresources)
+* A +ResourceTemplate+ element for each resource template
+* A +ResourceTemplates+ element for each list of resources (top level or subresources)
 * +Params+ and +OptionalParams+ elements for +params+ and +optional_params+, each containing +param+ elements
 * A single +options+ element contains the applicable HTTP methods as a comma-separated list
 
+Calls to parse_xml will at present result in NoMethodError exceptions being raised.
+
 == REQUIREMENTS:
 
-Rails.  Note however that the output format is not Rails-specific.
+Rails, for the Rake tasks and Rails controller.  The ResourceTemplate class and its formats are however Rails-independent.
 
 == INSTALL:
 
   sudo gem install described_routes
 
-Then add the following to your Rakefile:
-
-  require "tasks/described_routes"
-
 == Author
 
 Mike Burrows (asplake), email mailto:mjb@asplake.co.uk, website positiveincline.com[http://positiveincline.com] (see articles tagged described_routes[http://positiveincline.com/?tag=described_routes])

data/lib/described_routes.rb

@@ -2,91 +2,5 @@ require 'described_routes/resource_template'
 
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.1.4"
-  
-  # Convert an array of ResourceTemplate objects to array of hashes equivalent to their JSON or YAML representations
-  def self.to_parsed(resource_templates)
-    resource_templates.map{|resource_template| resource_template.to_hash}
-  end
-  
-  # Convert an array of ResourceTemplate objects to JSON
-  def self.to_json(resource_templates)
-    self.to_parsed(resource_templates).to_json
-  end
-  
-  # Convert an array of ResourceTemplate objects to YAML
-  def self.to_yaml(resource_templates)
-    self.to_parsed(resource_templates).to_yaml
-  end
-  
-  # Create an array of ResourceTemplate objects from a JSON string
-  def self.parse_json(json)
-    self.from_parsed(JSON.parse(json))
-  end
-  
-  # Create an array of ResourceTemplate objects from a JSON string
-  def self.parse_yaml(yaml)
-    self.from_parsed(YAML::load(yaml))
-  end
-
-  # Create an array of ResourceTemplate objects from an array of hashes
-  def self.from_parsed(parsed)
-    raise ArgumentError.new("not an array") unless parsed.kind_of?(Array)
-
-    parsed.map do |hash|
-      ResourceTemplate.from_hash(hash)
-    end
-  end
-
-  #
-  # Produces the XML format, given an XML builder object and an array of ResourceTemplate objects
-  #
-  def self.to_xml(xm, resource_templates)
-    xm.ResourceTemplates do |xm|
-      resource_templates.each do |resource_template|
-        xm.ResourceTemplate do |xm|
-          value_tag(xm, resource_template, "rel")
-          value_tag(xm, resource_template, "name")
-          value_tag(xm, resource_template, "path_template")
-          value_tag(xm, resource_template, "uri_template")
-
-          list_tag(xm, resource_template["params"], "Params", "param")
-          list_tag(xm, resource_template["optional_params"], "OptionalParams", "param")
-
-          # could use a list of elements here, but let's follow HTTP's lead and reduce the verbosity
-          options = resource_template["options"] || []
-          xm.options(options.join(", ")) unless options.empty?
-
-          resource_templates = resource_template["resource_templates"] || []
-          to_xml(xm, resource_templates) unless resource_templates.empty?
-        end
-      end
-    end
-    xm
-  end
-
-  def self.value_tag(xm, h, tag) #:nodoc:
-    value = h[tag]
-    xm.tag!(tag, value) unless value.blank?
-  end
-
-  def self.list_tag(xm, collection, collection_tag, member_tag) #:nodoc:
-    unless collection.nil? or collection.empty?
-      xm.tag!(collection_tag) do |xm|
-        collection.each do |value|
-          xm.tag!(member_tag, value)
-        end
-      end
-    end
-  end
-  
-  # Get a hash of all named ResourceTemplate objects contained in the supplied collection, keyed by name
-  def self.all_by_name(resource_templates, h = {})
-    resource_templates.inject(h) do |hash, resource_template|
-      hash[resource_template.name] = resource_template if resource_template.name
-      all_by_name(resource_template.resource_templates, hash)
-      hash
-    end
-    h
-  end
+  VERSION = "0.2.0"
 end

data/lib/described_routes/rails_controller.rb

@@ -5,20 +5,39 @@ module DescribedRoutes
   class RailsController < ActionController::Base
     def index
       base_url = root_url rescue nil
-      resources = RailsRoutes.get_resources(base_url)
+      resource_templates = RailsRoutes.get_resource_templates(base_url)
       
       respond_to do |format|
         format.html # index.html.erb
-        format.json { render :json => resources.to_json }
+        format.json { render :json => ResourceTemplate.to_json(resource_templates) }
         format.yaml do
-          yaml = resources.to_yaml
+          yaml = resource_templates.to_yaml(resource_templates)
           yaml = yaml.grep(/(name|rel|path_template|uri_template|resources):|^---/).to_s if ['true', '1'].member?(params["short"])
           render :text => yaml
         end
         format.xml do
-          render :xml => DescribedRoutes::to_xml(
+          render :xml => ResourceTemplate::to_xml(
                              Builder::XmlMarkup.new(:indent => 2),
-                             resources).target!
+                             resource_templates).target!
+        end
+      end
+    end
+    
+    def show
+      base_url = root_url rescue nil
+      resources = RailsRoutes.get_resource_templates(base_url)
+      resource_template = ResourceTemplate.all_by_name(resources)[params[:id]]
+      
+      respond_to do |format|
+        format.html # show.html.erb
+        format.json { render :json => resource_template.to_json }
+        format.yaml do
+          yaml = resource_template.to_yaml
+          yaml = yaml.grep(/(name|rel|path_template|uri_template|resources):|^---/).to_s if ['true', '1'].member?(params["short"])
+          render :text => yaml
+        end
+        format.xml do
+          render :xml => resource_template.to_xml(Builder::XmlMarkup.new(:indent => 2)).target!
         end
       end
     end

data/lib/described_routes/rails_routes.rb

@@ -1,12 +1,19 @@
-require 'described_routes'
+require 'described_routes/resource_template'
 
 module DescribedRoutes
   module RailsRoutes
+    #
+    # Process Rails routes and return an array of DescribedRoutes::ResourceTemplate objects
+    #
+    def self.get_resource_templates(base_url = nil)
+      DescribedRoutes::ResourceTemplate.from_parsed(get_parsed_rails_resources(base_url))
+    end
+
     #
     # Based on the implementation of "rake routes".  Returns a hash of Rails path specifications (slightly normalized)
     # mapped to hashes of the attributes we need. 
     #
-    def self.get_rails_resources
+    def self.get_rails_resources #:nodoc:
       ActionController::Routing::Routes.routes.inject({}) do |resources, route|
         name = ActionController::Routing::Routes.named_routes.routes.index(route).to_s
         controller = route.parameter_shell[:controller]
@@ -19,7 +26,11 @@ module DescribedRoutes
         # TODO - probably a better way to do this, just need a pattern that matches :id and not :id[a-zA-Z0-9_]+
         segs.gsub!(/:[a-zA-Z0-9_]+/) do |match|
           if match == ":id" && controller
-            ":#{controller.singularize.sub(/.*\//, "")}_id"
+            if controller == "described_routes/rails"
+              "{route_name}"
+            else
+              ":#{controller.singularize.sub(/.*\//, "")}_id"
+            end
           else
             match
           end
@@ -79,9 +90,10 @@ module DescribedRoutes
     end
 
     #
-    # Takes the routes from Rails and produces the required tree structure.
+    # Takes the routes from Rails and produces the required tree structure.  Returns the "parsed" format - i.e. a representation
+    # in Ruby Array and Hash objects
     #
-    def self.get_resources(base_url = nil)
+    def self.get_parsed_rails_resources(base_url = nil) #:nodoc:
       base_url = base_url.sub(/\/$/, '') if base_url
       resources = get_rails_resources
       resources.delete_if{|k, v| v["name"].blank? or v["name"] =~ /^formatted/}
@@ -99,8 +111,8 @@ module DescribedRoutes
         # compare parent and child names, and populate "rel" with either
         # 1) a prefix (probably an action name)
         # 2) a suffix (probably a nested resource)
-        # If neither applies, let's hope the child is identified by parameter (i.e. the parent is a collection)
-        # TODO rewrite this so that it's done when the child is created
+        # 3) the child's name if the parent and child's params are identical
+        # If none of the above applies, the child must be identifable by parameter
         name = resource["name"]
         prefix = /^(.*)_#{name}$/
         suffix = /^#{name}_(.*)$/
@@ -110,13 +122,15 @@ module DescribedRoutes
             child["rel"] = $1
           elsif child_name =~ suffix
             child["rel"] = $1
-          end 
+          elsif child["params"] == resource["params"]
+            child["rel"] = child["name"]
+          end
         end
     
         resource
       end
     end
-
+    
     #
     # Depth-first tree traversal
     #

data/lib/described_routes/resource_template.rb

@@ -60,11 +60,113 @@ module DescribedRoutes
 
       hash["options"] = options if options && !options.empty?
 
-      hashes = DescribedRoutes.to_parsed(resource_templates)
+      hashes = DescribedRoutes::ResourceTemplate.to_parsed(resource_templates)
       hash["resource_templates"] = hashes if hashes && !hashes.empty?
       
       hash
     end
+    
+    # Convert to JSON
+    def to_json
+      to_hash.to_json
+    end
+
+    # Convert to YAML
+    def to_yaml
+      to_hash.to_json
+    end
+    
+    #
+    # Produces the XML format, given an XML builder object and an array of ResourceTemplate objects
+    #
+    def to_xml(xm)
+      xm.ResourceTemplate do |xm|
+        value_tag(xm, "rel")
+        value_tag(xm, "name")
+        value_tag(xm, "path_template")
+        value_tag(xm, "uri_template")
+
+        list_tag(xm, params, "Params", "param")
+        list_tag(xm, optional_params, "OptionalParams", "param")
+
+        # could use a list of elements here, but let's follow HTTP's lead and reduce the verbosity
+        xm.options(options.join(", ")) unless options.empty?
+
+        self.class.to_xml(xm, resource_templates) unless resource_templates.empty?
+      end
+      xm
+    end
+
+    def value_tag(xm, tag) #:nodoc:
+      value = self.send(tag.to_sym)
+      xm.tag!(tag, value) unless value.blank?
+    end
+
+    def list_tag(xm, collection, collection_tag, member_tag) #:nodoc:
+      unless collection.nil? or collection.empty?
+        xm.tag!(collection_tag) do |xm|
+          collection.each do |value|
+            xm.tag!(member_tag, value)
+          end
+        end
+      end
+    end
+  
+    # Convert an array of ResourceTemplate objects to array of hashes equivalent to their JSON or YAML representations
+    def self.to_parsed(resource_templates)
+      resource_templates.map{|resource_template| resource_template.to_hash}
+    end
+  
+    # Convert an array of ResourceTemplate objects to JSON
+    def self.to_json(resource_templates)
+      self.to_parsed(resource_templates).to_json
+    end
+  
+    # Convert an array of ResourceTemplate objects to YAML
+    def self.to_yaml(resource_templates)
+      self.to_parsed(resource_templates).to_yaml
+    end
+  
+    # Create an array of ResourceTemplate objects from a JSON string
+    def self.parse_json(json)
+      self.from_parsed(JSON.parse(json))
+    end
+  
+    # Create an array of ResourceTemplate objects from a JSON string
+    def self.parse_yaml(yaml)
+      self.from_parsed(YAML::load(yaml))
+    end
+
+    # Create an array of ResourceTemplate objects from an array of hashes
+    def self.from_parsed(parsed)
+      raise ArgumentError.new("not an array") unless parsed.kind_of?(Array)
+
+      parsed.map do |hash|
+        ResourceTemplate.from_hash(hash)
+      end
+    end
+
+    #
+    # Produces the XML format, given an XML builder object and an array of ResourceTemplate objects
+    #
+    def self.to_xml(xm, resource_templates)
+      xm.ResourceTemplates do |xm|
+        resource_templates.each do |resource_template|
+          resource_template.to_xml(xm)
+        end
+      end
+      xm
+    end
+
+    # Get a hash of all named ResourceTemplate objects contained in the supplied collection, keyed by name
+    def self.all_by_name(resource_templates, h = {})
+      resource_templates.inject(h) do |hash, resource_template|
+        hash[resource_template.name] = resource_template if resource_template.name
+        all_by_name(resource_template.resource_templates, hash)
+        hash
+      end
+      h
+    end
   end
 end
 

data/lib/tasks/described_routes.rb

@@ -6,24 +6,44 @@ namespace :described_routes do
   desc "Describe resource structure in JSON format"
 
   task :json => :environment do
-    puts DescribedRoutes::RailsRoutes.get_resources.to_json
+    puts DescribedRoutes::ResourceTemplate.to_json(
+            DescribedRoutes::RailsRoutes.get_resource_templates)
   end
 
   desc "Describe resource structure in YAML format"
   task :yaml => :environment do
-    puts DescribedRoutes::RailsRoutes.get_resources.to_yaml
+    puts DescribedRoutes::ResourceTemplate.to_yaml(
+            DescribedRoutes::RailsRoutes.get_resource_templates)
   end
 
   desc "Describe resource structure in YAML format (basic structure only)"
   task :yaml_short => :environment do
-    puts DescribedRoutes::RailsRoutes.get_resources.to_yaml.grep(/(name|rel|path_template|uri_template|resources):|^---/)
+    puts DescribedRoutes::ResourceTemplate.to_yaml(
+            DescribedRoutes::RailsRoutes.get_resource_templates).grep(
+                /(name|rel|path_template|uri_template|resources):|^---/)
   end
 
   desc "Describe resource structure in XML format"
   task :xml => :environment do
-    puts DescribedRoutes::to_xml(
-           Builder::XmlMarkup.new(:indent => 2),
-           DescribedRoutes::RailsRoutes.get_resources
-         ).target!
+    puts DescribedRoutes::ResourceTemplate.to_xml(
+             Builder::XmlMarkup.new(:indent => 2),
+             DescribedRoutes::RailsRoutes.get_resource_templates
+           ).target!
+  end
+  
+  # unsupported, for testing
+  task :ruby => :environment do
+    puts DescribedRoutes::ResourceTemplate.to_parsed(
+            DescribedRoutes::RailsRoutes.get_resource_templates).inspect
+  end
+
+  # unsupported
+  task :get_rails_resources => :environment do
+    puts DescribedRoutes::RailsRoutes.get_rails_resources.inspect
+  end
+  
+  # unsupported
+  task :get_parsed_rails_resources => :environment do
+    puts DescribedRoutes::RailsRoutes.get_parsed_rails_resources.inspect
   end
 end

data/test/fixtures/described_routes_test.json

@@ -0,0 +1 @@
+[{"name":"root","path_template":"\/"},{"name":"admin_products","resource_templates":[{"name":"admin_product","resource_templates":[{"name":"edit_admin_product","options":["GET"],"path_template":"\/admin\/products\/{product_id}\/edit{-prefix|.|format}","rel":"edit"}],"options":["GET","PUT","DELETE"],"path_template":"\/admin\/products\/{product_id}{-prefix|.|format}"},{"name":"new_admin_product","options":["GET"],"path_template":"\/admin\/products\/new{-prefix|.|format}","rel":"new_admin_product"}],"options":["GET","POST"],"path_template":"\/admin\/products{-prefix|.|format}"},{"name":"described_routes","resource_templates":[{"name":"new_described_route","options":["GET"],"path_template":"\/described_routes\/new{-prefix|.|format}","rel":"new_described_route"},{"name":"described_route","resource_templates":[{"name":"edit_described_route","options":["GET"],"path_template":"\/described_routes\/{route_name}\/edit{-prefix|.|format}","rel":"edit"}],"options":["GET","PUT","DELETE"],"path_template":"\/described_routes\/{route_name}{-prefix|.|format}","rel":"described_route"}],"options":["GET","POST"],"path_template":"\/described_routes{-prefix|.|format}"},{"name":"pages","resource_templates":[{"name":"page","resource_templates":[{"name":"edit_page","options":["GET"],"path_template":"\/pages\/{page_id}\/edit{-prefix|.|format}","rel":"edit"},{"name":"summary_page","options":["GET"],"path_template":"\/pages\/{page_id}\/summary{-prefix|.|format}","rel":"summary"},{"name":"toggle_visibility_page","options":["POST"],"path_template":"\/pages\/{page_id}\/toggle_visibility{-prefix|.|format}","rel":"toggle_visibility"}],"options":["GET","PUT","DELETE"],"path_template":"\/pages\/{page_id}{-prefix|.|format}"},{"name":"new_page","options":["GET"],"path_template":"\/pages\/new{-prefix|.|format}","rel":"new_page"}],"options":["GET","POST"],"path_template":"\/pages{-prefix|.|format}"},{"name":"users","resource_templates":[{"name":"user","resource_templates":[{"name":"user_articles","resource_templates":[{"name":"user_article","resource_templates":[{"name":"edit_user_article","options":["GET"],"path_template":"\/users\/{user_id}\/articles\/{article_id}\/edit{-prefix|.|format}","rel":"edit"}],"options":["GET","PUT","DELETE"],"path_template":"\/users\/{user_id}\/articles\/{article_id}{-prefix|.|format}"},{"name":"new_user_article","options":["GET"],"path_template":"\/users\/{user_id}\/articles\/new{-prefix|.|format}","rel":"new_user_article"},{"name":"recent_user_articles","options":["GET"],"path_template":"\/users\/{user_id}\/articles\/recent{-prefix|.|format}","rel":"recent"}],"options":["GET","POST"],"path_template":"\/users\/{user_id}\/articles{-prefix|.|format}","rel":"articles"},{"name":"edit_user","options":["GET"],"path_template":"\/users\/{user_id}\/edit{-prefix|.|format}","rel":"edit"},{"name":"user_profile","resource_templates":[{"name":"edit_user_profile","options":["GET"],"path_template":"\/users\/{user_id}\/profile\/edit{-prefix|.|format}","rel":"edit"},{"name":"new_user_profile","options":["GET"],"path_template":"\/users\/{user_id}\/profile\/new{-prefix|.|format}","rel":"new"}],"options":["GET","PUT","DELETE","POST"],"path_template":"\/users\/{user_id}\/profile{-prefix|.|format}","rel":"profile"}],"options":["GET","PUT","DELETE"],"path_template":"\/users\/{user_id}{-prefix|.|format}"},{"name":"new_user","options":["GET"],"path_template":"\/users\/new{-prefix|.|format}","rel":"new_user"}],"options":["GET","POST"],"path_template":"\/users{-prefix|.|format}"}]

data/test/test_resource_template.rb

@@ -1,2 +1,45 @@
 require 'test/unit'
 require 'described_routes/resource_template'
+
+class TestResourceTemplate < Test::Unit::TestCase
+  attr_reader :json, :resource_templates, :resource_templates_by_name, :user_articles, :user_article, :edit_user_article
+  
+  
+  def setup
+    @json ||= File.read(File.dirname(__FILE__) + "/fixtures/described_routes_test.json")
+    @resource_templates = DescribedRoutes::ResourceTemplate.parse_json(json)
+    @resource_templates_by_name = DescribedRoutes::ResourceTemplate.all_by_name(@resource_templates)
+    @user_articles = @resource_templates_by_name["user_articles"]
+    @user_article = @resource_templates_by_name["user_article"]
+    @edit_user_article = @resource_templates_by_name["edit_user_article"]
+  end
+
+  def test_fixture
+    assert_kind_of(DescribedRoutes::ResourceTemplate, user_articles)
+    assert_kind_of(DescribedRoutes::ResourceTemplate, user_article)
+    assert_kind_of(DescribedRoutes::ResourceTemplate, edit_user_article)
+
+    assert_equal("user_article", user_article.name)
+    assert_equal([], user_article.params)
+    assert_equal([], user_article.optional_params)
+
+    assert_equal("articles", user_articles.rel)
+    assert_nil(user_article.rel)
+    assert_equal("edit", edit_user_article.rel)
+
+    assert(user_articles.resource_templates.member?(user_article))
+    assert(user_article.resource_templates.member?(edit_user_article))
+  end
+  
+  def test_json
+    assert_equal(
+        JSON.parse(json),
+        JSON.parse(DescribedRoutes::ResourceTemplate.to_json(resource_templates)))
+  end
+  
+  def test_yaml
+    assert_equal(
+        JSON.parse(json),
+        YAML.load(DescribedRoutes::ResourceTemplate.to_yaml(resource_templates)))
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: described_routes
 version: !ruby/object:Gem::Version 
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors: 
 - Mike Burrows
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-28 00:00:00 +01:00
+date: 2009-04-29 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,6 +59,7 @@ files:
 - script/console
 - script/destroy
 - script/generate
+- test/fixtures/described_routes_test.json
 - test/test_described_routes.rb
 - test/test_helper.rb
 - test/test_resource_template.rb