described_routes 0.0.2

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2009-04-24
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

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

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on described_routes, see http://describedroutes.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.rdoc

@@ -0,0 +1,95 @@
+= described_routes README
+
+== DESCRIPTION:
+
+Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML and XML formats for potential consumption by client applications (e.g. those based on path-to[http://github.com/asplake/path-to/tree]).
+
+== SYNOPSIS:
+
+In your Rakefile:
+
+  require 'tasks/described_routes'
+
+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)
+
+For a flavour, try the short form:
+
+  $ rake described_routes:yaml_short
+  - name: users
+    path_template: /users{-prefix|.|format}
+    resources: 
+    - name: user
+      path_template: /users/{user_id}{-prefix|.|format}
+      resources: 
+      - name: user_articles
+        rel: articles
+        path_template: /users/{user_id}/articles{-prefix|.|format}
+        resources: 
+        - name: user_article
+          path_template: /users/{user_id}/articles/{article_id}{-prefix|.|format}
+          resources: 
+          - name: edit_user_article
+            path_template: /users/{user_id}/articles/{article_id}/edit{-prefix|.|format}
+            rel: edit
+        - name: new_user_article
+          path_template: /users/{user_id}/articles/new{-prefix|.|format}
+          rel: new
+        - name: recent_user_articles
+          path_template: /users/{user_id}/articles/recent{-prefix|.|format}
+          rel: recent
+      - name: edit_user
+        path_template: /users/{user_id}/edit{-prefix|.|format}
+        rel: edit
+
+The above YAML is an abbreviated form that shows only name, rel, path_template for each resource in the hierarchy.  The full form includes parameter lists (both mandatory and optional) and options (i.e. HTTP methods).
+
+== 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.
+
+Attributes:
+
++name+::            A Rails-generated route name
++rel+::             An indication of a child resource's relationship to its parent
++options+::         A list of HTTP methods supported by the resource
++path_template+::   A template for the resource's path, in the style of URI Template but as a relative path
++params+::          A list of parameters required by path_template
++optional_params+:: A list of optional parameters that may be incorporated by the path_template
+
+Empty or blank attributes are omitted.
+
+Note that only named routes are considered.  Pre-Rails 2.3 "formatted routes" are explicitly excluded, and for Rails 2.3 onwards, <tt>"format"</tt> is the only entry likely to appear in the optional_parameters attribute.
+
+=== XML
+
+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)
+* +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
+
+== REQUIREMENTS:
+
+Rails.  Note however that the output format is not Rails-specific.
+
+== 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/Rakefile

@@ -0,0 +1,37 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+$:.push File.dirname(__FILE__) + '/lib'
+require 'described_routes'
+
+# undefined method `empty?' for nil:NilClass
+# /Library/Ruby/Site/1.8/rubygems/specification.rb:886:in `validate'
+class NilClass
+  def empty?
+    true
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('described_routes', DescribedRoutes::VERSION) do |p|
+  p.developer('Mike Burrows', 'mjb@asplake.co.uk')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = 'describedroutes' # TODO this is default value
+  # p.extra_deps         = [
+  #   ['activesupport','>= 2.0.2'],
+  # ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/lib/described_routes.rb

@@ -0,0 +1,91 @@
+require 'described_routes/resource_template'
+
+module DescribedRoutes
+  # rubygem version
+  VERSION = "0.0.2"
+  
+  # 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")
+
+          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
+end

data/lib/tasks/described_routes.rb

@@ -0,0 +1,29 @@
+require 'tasks/rails'
+require 'described_routes/rails_routes'
+
+namespace :described_routes do
+  desc "Describe resource structure as a Ruby literal"
+  desc "Describe resource structure in JSON format"
+
+  task :json => :environment do
+    puts DescribedRoutes::RailsRoutes.get_resources.to_json
+  end
+
+  desc "Describe resource structure in YAML format"
+  task :yaml => :environment do
+    puts DescribedRoutes::RailsRoutes.get_resources.to_yaml
+  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|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!
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/described_routes.rb'}"
+puts "Loading described_routes gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/test/test_described_routes.rb

@@ -0,0 +1,11 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class TestDescribedRoutes < Test::Unit::TestCase
+
+  def setup
+  end
+  
+  def test_truth
+    assert true
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'stringio'
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/described_routes'

data/test/test_resource_template.rb

@@ -0,0 +1,2 @@
+require 'test/unit'
+require 'described_routes/resource_template'

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification 
+name: described_routes
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Mike Burrows
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-27 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: newgem
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.3.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.0
+    version: 
+description: Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML and XML formats for potential consumption by client applications (e.g. those based on path-to[http://github.com/asplake/path-to/tree]).
+email: 
+- mjb@asplake.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+- Rakefile
+- lib/described_routes.rb
+- lib/tasks/described_routes.rb
+- script/console
+- script/destroy
+- script/generate
+- test/test_described_routes.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: describedroutes
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 3
+summary: Outputs hierarchical, framework-neutral descriptions of Rails routes in JSON, YAML and XML formats for potential consumption by client applications (e.g
+test_files: 
+- test/test_described_routes.rb
+- test/test_helper.rb
+- test/test_resource_template.rb