described_routes 0.0.2 → 0.0.3

data/LICENSE

@@ -0,0 +1,20 @@
+path-to, Copyright (c) 2009 Mike Burrows
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -1,12 +1,16 @@
 History.txt
+LICENSE
 Manifest.txt
 PostInstall.txt
 README.rdoc
 Rakefile
 lib/described_routes.rb
+lib/described_routes/rails_routes.rb
+lib/described_routes/resource_template.rb
 lib/tasks/described_routes.rb
 script/console
 script/destroy
 script/generate
 test/test_described_routes.rb
 test/test_helper.rb
+test/test_resource_template.rb

data/lib/described_routes/rails_routes.rb

@@ -0,0 +1,153 @@
+require 'described_routes'
+
+module DescribedRoutes
+  module RailsRoutes
+    #
+    # 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
+      ActionController::Routing::Routes.routes.inject({}) do |resources, route|
+        name = ActionController::Routing::Routes.named_routes.routes.index(route).to_s
+        controller = route.parameter_shell[:controller]
+        action = route.parameter_shell[:action]
+        options = [route.conditions[:method]].flatten.map{|option| option.to_s.upcase}
+        segs = route.segments.inject("") {|str,s| str << s.to_s }
+        segs.chop! if segs.length > 1
+
+        # prefix :id parameters consistently
+        # 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"
+          else
+            match
+          end
+        end
+
+        # ignore optional format parameter when comparing paths
+        key = segs.sub("(.:format)", "")
+        if resources[key]
+          # we've seen the (normalised) path before; add to options
+          resources[key]["options"] += options
+        else
+          template = segs
+
+          # collect & format mandatory parameters
+          params = []
+          template.gsub!(/:[a-zA-Z0-9_]+/) do |match|
+            param = match[1..-1]
+            param = controller.singularize.sub(/.*\//, "") + "_id" if param == "id" && controller
+            params << param
+            "{#{param}}"
+          end
+
+          # collect & format optional format parameter
+          optional_params = []
+          template.sub!("(.{format})") do |match|
+            optional_params << "format"
+            "{-prefix|.|format}"
+          end
+          params -= optional_params
+
+          # so now we have (for example):
+          #   segs              #=> "/users/:user_id/edit(.:format)" (was "/users/:id")
+          #   key               #=> "/users/:user_id/edit"
+          #   template          #=> "/users/{user_id}/edit"
+          #   params            #=> ["user_id"]
+          #   optional_params   #=> ["format"]
+          #   action            #=> "edit"
+          #   options           #=> ["GET"]
+          #   name              #=>  "edit_user"
+
+          # create a new route hash
+          resource = {
+            "path_template" => template,
+            "options" => options,
+          }
+          resource["params"] = params unless params.empty?
+          resource["optional_params"] = optional_params unless optional_params.empty?
+
+          resources[key] = resource
+        end
+
+        # this may be the first time we've seen a good name for this key
+        resources[key]["name"] ||= name unless name.blank? or name =~ /^formatted/
+
+        resources
+      end
+    end
+
+    #
+    # Takes the routes from Rails and produces the required tree structure.
+    #
+    def self.get_resources
+      resources = get_rails_resources
+      resources.delete_if{|k, v| v["name"].blank? or v["name"] =~ /^formatted/}
+
+      key_tree = make_key_tree(resources.keys.sort){|possible_prefix, key|
+        key[0...possible_prefix.length] == possible_prefix && possible_prefix != "/"
+      }
+
+      tree = map_key_tree(key_tree) do |key, children|
+        resource = resources[key]
+        resource["resource_templates"] = children unless children.empty?
+        resource.delete("options") if resource["options"] == [""]
+
+        # 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
+        name = resource["name"]
+        prefix = /^(.*)_#{name}$/
+        suffix = /^#{name}_(.*)$/
+        children.each do |child|
+          child_name = child["name"]
+          if child_name =~ prefix
+            child["rel"] = $1
+          elsif child_name =~ suffix
+            child["rel"] = $1
+          end 
+        end
+    
+        resource
+      end
+    end
+
+    #
+    # Depth-first tree traversal
+    #
+    #   tree = [["/", []], ["/a", [["/a/b", [["/a/b/c", []]]], ["/a/d", []]]], ["/b", []]]
+    #   map_key_tree(tree){|key, processed_children| {key => processed_children}}
+    #   # => [{"/"=>[]}, {"/a"=>[{"/a/b"=>[{"/a/b/c"=>[]}]}, {"/a/d"=>[]}]}, {"/b"=>[]}]
+    #
+    def self.map_key_tree(tree, &blk) #:nodoc:
+      tree.map do |pair|
+        key, children = pair
+        blk.call(key, map_key_tree(children, &blk))
+      end
+    end
+  
+    #
+    # Turns a sorted array of strings into a tree structure as follows:
+    #
+    #   make_key_tree(["/", "/a", "/a/b", "/a/b/c", "/a/d", "/b"]){|possible_prefix, route|
+    #     route[0...possible_prefix.length] == possible_prefix && possible_prefix != "/"
+    #   }
+    #   => [["/", []], ["/a", [["/a/b", [["/a/b/c", []]]], ["/a/d", []]]], ["/b", []]]
+    #
+    # Note that in the example (as in is actual usage in this module), we choose not to to have the root resource ("/") as
+    # the parent of all other resources.
+    #
+    def self.make_key_tree(sorted_keys, &is_prefix) #:nodoc:
+      head, *tail = sorted_keys
+      if head
+        children, siblings = tail.partition{|p| is_prefix.call(head, p)}
+        [[head, make_key_tree(children, &is_prefix)]] + make_key_tree(siblings, &is_prefix)
+      else
+        []
+      end
+    end
+  end
+end

data/lib/described_routes/resource_template.rb

@@ -0,0 +1,66 @@
+require "json"
+
+module DescribedRoutes
+  class ResourceTemplate
+    # The template's name.  Optional.  Making these unique across the application is helpful for clients
+    # that may wish to pick out nested templates by name.
+    attr_reader :name
+    
+    # Optional attribute that describes a resource's relationship to its parent.  For example:
+    # * a nested route to a resource's edit page would have rel of "edit"
+    # * a nested collection of articles under a "user" resource would have have a rel of "articles"
+    # Collection members generally don't need a rel as they are identified by their params
+    attr_reader :rel
+    
+    # A template for generating paths relative to the application's base.
+    attr_reader :path_template
+    
+    # The parameters required by the path template
+    attr_reader :params
+    
+    # Optional paramaters that may be used by the path template
+    attr_reader :optional_params
+    
+    # "options" in the sense of the HTTP option request - i.e. a list of HTTP methods.  Optional.
+    attr_reader :options
+    
+    # An optional list of nested resource templates
+    attr_reader :resource_templates
+    
+    # Initialize a ResourceTemplate.  See the attribute descriptions above for explanations of the parameters.
+    def initialize(name, rel, path_template, params, optional_params, options, resource_templates)
+      @name, @rel, @path_template = name, rel, path_template
+      @params = params || []
+      @optional_params = optional_params || []
+      @options = options || []
+      @resource_templates = resource_templates || []
+    end
+    
+    # Create a ResourceTemplate from its Hash representation
+    def self.from_hash(hash)
+      attributes = %w(name rel path_template params optional_params options).map{|k| hash[k]}
+      if hash["resource_templates"]
+        attributes << hash["resource_templates"].map{|h| from_hash(h)} if hash["resource_templates"]
+      else
+        attributes << nil
+      end
+      self.new(*attributes)
+    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["path_template"] = path_template if path_template && !path_template.empty?
+
+      hash["options"] = options if options && !options.empty?
+
+      hashes = DescribedRoutes.to_parsed(resource_templates)
+      hash["resource_templates"] = hashes if hashes && !hashes.empty?
+      
+      hash
+    end
+  end
+end
+

data/lib/described_routes.rb

@@ -2,7 +2,7 @@ require 'described_routes/resource_template'
 
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
   
   # Convert an array of ResourceTemplate objects to array of hashes equivalent to their JSON or YAML representations
   def self.to_parsed(resource_templates)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: described_routes
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Mike Burrows
@@ -46,17 +46,21 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - History.txt
+- LICENSE
 - Manifest.txt
 - PostInstall.txt
 - README.rdoc
 - Rakefile
 - lib/described_routes.rb
+- lib/described_routes/rails_routes.rb
+- lib/described_routes/resource_template.rb
 - lib/tasks/described_routes.rb
 - script/console
 - script/destroy
 - script/generate
 - test/test_described_routes.rb
 - test/test_helper.rb
+- test/test_resource_template.rb
 has_rdoc: true
 homepage: 
 licenses: []