roda-route_list 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 22860ddac7c2f5805445a274c59217bfd1b829f1
+  data.tar.gz: 75976d49b266e7f6a4783ba4a4e8376ce7807873
+SHA512:
+  metadata.gz: 676bb12a6726a91ea0c782e18bcb7f0d4c925748129e706abec2ae0e3d3a4b19c14c1aa52125b11c10fbd01a3240dbc3899a93fb29caec8de6370f2f15f46cdf
+  data.tar.gz: f026084da9cd254125f26abd4e3efe7b45703cdbd1ed0436669c9ef10aac413a0c8f57a727630fab3b4f2ba0561d45d53cbd6a2869fdfe228ceab45406e68c1e

data/CHANGELOG

@@ -0,0 +1,3 @@
+= 1.0.0 (2015-03-08)
+
+* Initial public release

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Jeremy Evans
+
+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/README.rdoc

@@ -0,0 +1,98 @@
+= roda-route_list
+
+The Roda route_list plugin reads route information from a json
+file, and then makes the route metadata available for
+introspection.  This provides a workaround to the general
+issue of routing trees being unable to introspect the routes.
+
+== Installation
+
+  gem install roda-route_list
+
+== Source Code
+
+Source code is available on GitHub at https://github.com/jeremyevans/roda-route_list
+
+== Basic Usage
+
+This plugin assumes that a json file containing the routes
+metadata has already been created.  The recommended way to
+create one is to add comments above each route in the Roda
+app, in one of the following formats:
+
+  # route: /path/to/foo
+  # route: GET /path/to/foo
+  # route: GET|POST /path/to/foo/:foo_id
+  # route[route_name]: /path/to/foo
+  # route[route_name]: GET /path/to/foo
+  # route[foo]: GET|POST /path/to/foo/:foo_id
+
+As you can see, the general style is a comment followed by
+the word route.  If you want to name the route, you can
+put the name in brackets.  Then you have a colon.  Optionally
+after that you can have the method for the route, or multiple
+methods separated by pipes if the path works with multiple
+methods.  The end is the path for the route.
+
+Assuming you have added the appropriate comments as explained
+above, you can create the json file using the roda-parse_routes
+executable that came with the roda-route_list gem:
+
+  roda-parse_routes -f routes.json app.rb
+
+Assuming you have the necessary json file created, you can then
+get route information:
+
+  plugin :route_list
+
+  # Array of route metadata hashes
+  route_list # => [{:path=>'/path/to/foo', :methods=>['GET', 'POST']}]
+
+  # path for the route with the given name
+  named_route(:route_name) # => '/path/to/foo'
+
+  # path for the route with the given name, supplying hash for placeholders
+  named_route(:foo, :foo_id=>3) # => '/path/to/foo/3'
+
+  # path for the route with the given name, supplying array for placeholders
+  named_route(:foo, [3]) # => '/path/to/foo/3'
+
+The +named_route+ method is also available at the instance level to make it
+easier to use inside the route block.
+
+=== Automatically Updating the Routes Metadata
+
+==== On Heroku
+
+You can get this to work on Heroku by hooking into the facility for
+precompiling assets.  If this consider your route list an asset, this
+makes sense.  You just need to add an assets:precompile task, similar to
+this (or add the code an existing assets:precompile task):
+
+  namespace :assets do
+    desc "Update the routes metadata"
+    task :precompile do
+      sh 'roda-parse_routes -f routes.json app.rb'
+    end
+  end
+
+==== Otherwise
+
+At the top of your Roda app file, or at least before you create the Roda app
+subclass, just call the <tt>roda-parse_routes</tt> program:
+
+  # app.rb
+  system 'roda-parse_routes', '-f', 'routes.json', __FILE__
+  require 'roda'
+
+  class App < Roda
+    # ...
+  end
+
+== License
+
+MIT
+
+== Maintainer
+
+Jeremy Evans <code@jeremyevans.net>

data/Rakefile

@@ -0,0 +1,69 @@
+require "rake"
+require "rake/clean"
+
+CLEAN.include ["rdoc", "roda-route_list-*.gem"]
+
+desc "Build roda-route_list gem"
+task :package=>[:clean] do |p|
+  sh %{#{FileUtils::RUBY} -S gem build roda-route_list.gemspec}
+end
+
+### Specs
+
+begin
+  begin
+    # RSpec 1
+    require "spec/rake/spectask"
+    spec_class = Spec::Rake::SpecTask
+    spec_files_meth = :spec_files=
+  rescue LoadError
+    # RSpec 2
+    require "rspec/core/rake_task"
+    spec_class = RSpec::Core::RakeTask
+    spec_files_meth = :pattern=
+  end
+
+  spec = lambda do |name, files, d|
+    lib_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'lib')
+    ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{lib_dir}") : (ENV['RUBYLIB'] = lib_dir)
+    desc d
+    spec_class.new(name) do |t|
+      ENV['RUBY'] = FileUtils::RUBY
+      t.send(spec_files_meth, files)
+    end
+  end
+
+  task :default => [:spec]
+  spec.call("spec", Dir["spec/*_spec.rb"], "Run specs")
+rescue LoadError
+  task :default do
+    puts "Must install rspec to run the default task (which runs specs)"
+  end
+end
+
+### RDoc
+
+RDOC_DEFAULT_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', 'roda-route_list: List routes when using Roda']
+
+begin
+  gem 'hanna-nouveau'
+  RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
+rescue Gem::LoadError
+end
+
+rdoc_task_class = begin
+  require "rdoc/task"
+  RDoc::Task
+rescue LoadError
+  require "rake/rdoctask"
+  Rake::RDocTask
+end
+
+RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
+
+rdoc_task_class.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb"
+end
+

data/bin/roda-parse_routes

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'json'
+require File.join(File.dirname(File.dirname(File.expand_path(__FILE__))), 'lib', 'roda-route_parser')
+
+file = $stdout
+options = OptionParser.new do |opts|
+  opts.banner = "roda-parse_routes: Parse route comments from roda app files"
+  opts.define_head "Usage: roda-parse_routes [options] [file] ..."
+  opts.separator "Options:"
+
+  opts.on_tail("-h", "-?", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-f", "--file ", "output to given file instead of stdout") do  |v|
+    file = File.open(v, 'wb')
+  end
+end
+opts = options
+opts.parse!
+
+file.puts(RodaRouteParser.parse(ARGF).to_json)

data/lib/roda-route_parser.rb

@@ -0,0 +1,33 @@
+class RodaRouteParser
+  def self.parse(input)
+    new.parse(input)
+  end
+
+  def parse(input)
+    if input.is_a?(String)
+      require 'stringio'
+      return parse(StringIO.new(input))
+    end
+
+    routes = []
+    regexp = /\A\s*#\s*route(?:\[(\w+)\])?:\s+(?:([A-Z|]+)?\s+)?(\S+)\s*\z/
+    input.each_line do |line|
+      if md = regexp.match(line)
+        name, methods, route = md.captures
+        route = {'path'=>route}
+
+        if methods
+          route['methods'] = methods.split('|').compact
+        end
+
+        if name
+          route['name'] = name
+        end
+
+        routes << route
+      end
+    end
+
+    routes
+  end
+end

data/lib/roda/plugins/route_list.rb

@@ -0,0 +1,147 @@
+require 'json'
+
+class Roda
+  module RodaPlugins
+    # The route_list plugin reads route information from a json
+    # file, and then makes the route metadata available for
+    # introspection.  This provides a workaround to the general
+    # issue of routing trees being unable to introspect the routes.
+    #
+    # This plugin assumes that a json file containing the routes
+    # metadata has already been created.  The recommended way to
+    # create one is to add comments above each route in the Roda
+    # app, in one of the following formats:
+    #
+    #   # route: /path/to/foo
+    #   # route: GET /path/to/foo
+    #   # route: GET|POST /path/to/foo/:foo_id
+    #   # route[route_name]: /path/to/foo
+    #   # route[route_name]: GET /path/to/foo
+    #   # route[foo]: GET|POST /path/to/foo/:foo_id
+    #
+    # As you can see, the general style is a comment followed by
+    # the word route.  If you want to name the route, you can
+    # put the name in brackets.  Then you have a colon.  Optionally
+    # after that you can have the method for the route, or multiple
+    # methods separated by pipes if the path works with multiple
+    # methods.  The end is the path for the route.
+    #
+    # Assuming you have added the appropriate comments as explained
+    # above, you can create the json file using the roda-route_parser
+    # executable that came with the roda-route_list gem:
+    #
+    #   roda-route_parser -f routes.json app.rb
+    #
+    # Assuming you have the necessary json file created, you can then
+    # get route information:
+    #
+    #   plugin :route_list
+    #
+    #   # Array of route metadata hashes
+    #   route_list # => [{:path=>'/path/to/foo', :methods=>['GET', 'POST']}]
+    #
+    #   # path for the route with the given name
+    #   named_route(:route_name) # => '/path/to/foo'
+    #
+    #   # path for the route with the given name, supplying hash for placeholders
+    #   named_route(:foo, :foo_id=>3) # => '/path/to/foo/3'
+    #
+    #   # path for the route with the given name, supplying array for placeholders
+    #   named_route(:foo, [3]) # => '/path/to/foo/3'
+    #
+    # The +named_route+ method is also available at the instance level to make it
+    # easier to use inside the route block.
+    module RouteList
+      # Set the file to load the routes metadata from.  Options:
+      # :file :: The JSON file containing the routes metadata (default: 'routes.json')
+      def self.configure(app, opts={})
+        file = File.expand_path(opts.fetch(:file, 'routes.json'), app.opts[:root])
+        app.send(:load_routes, file)
+      end
+
+      module ClassMethods
+        # Array of route metadata hashes.
+        attr_reader :route_list
+
+        # Return the path for the given named route.  If args is not given,
+        # this returns the path directly.  If args is a hash, any placeholder
+        # values in the path are replaced with the matching values in args.
+        # If args is an array, placeholder values are taken from the array
+        # in order.
+        def named_route(name, args=nil)
+          unless path = @route_list_names[name]
+            raise RodaError, "no route exists with the name: #{name.inspect}"
+          end
+
+          if args
+            if args.is_a?(Hash)
+              range = 1..-1
+              path = path.gsub(/:[^\/]+/) do |match|
+                unless value = args[match[range].to_sym]
+                  raise RodaError, "no matching value exists in the hash for named route #{name}: #{match}"
+                end
+                value
+              end
+            else
+              values = args.dup
+              path = path.gsub(/:[^\/]+/) do |match|
+                if values.empty?
+                  raise RodaError, "not enough placeholder values provided for named route #{name}: #{match}"
+                end
+                values.shift
+              end
+
+              unless values.empty?
+                raise RodaError, "too many placeholder values provided for named route #{name}"
+              end
+            end
+          end
+
+          path
+        end
+
+        private
+
+        # Load the route metadata from the given json file.
+        def load_routes(file)
+          @route_list_names = {}
+
+          routes = JSON.parse(File.read(file))
+          @route_list = routes.map do |r|
+            path = r['path'].freeze
+            route = {:path=>path}
+
+            if methods = r['methods']
+              route[:methods] = methods.map{|x| x.to_sym}
+            end
+
+            if name = r['name']
+              name = name.to_sym
+              route[:name] = name.to_sym
+              @route_list_names[name] = path
+            end
+
+            route.freeze
+          end.freeze
+
+          @route_list_names.freeze
+          
+          nil
+        end
+      end
+      
+      module InstanceMethods
+        # Calls the app's named_route method.  If the app's :add_script_name option
+        # has been setting, prefixes the resulting path with the script name.
+        def named_route(name, args=nil)
+          app = self.class
+          path = app.named_route(name, args)
+          path = request.script_name.to_s + path if app.opts[:add_script_name]
+          path
+        end
+      end
+    end
+
+    register_plugin(:route_list, RouteList)
+  end
+end

data/spec/roda-route_list_spec.rb

@@ -0,0 +1,119 @@
+require 'roda'
+require 'json'
+
+if defined?(RSpec)
+  require 'rspec/version'
+  if RSpec::Version::STRING >= '2.11.0'
+    RSpec.configure do |config|
+      config.expect_with :rspec do |c|
+        c.syntax = :should
+      end
+    end
+  end
+end
+
+describe 'roda-route_list plugin' do
+  def req(path='/', env={})
+    if path.is_a?(Hash)
+      env = path
+    else
+      env['PATH_INFO'] = path
+    end
+
+    env = {"REQUEST_METHOD" => "GET", "PATH_INFO" => "/", "SCRIPT_NAME" => ""}.merge(env)
+    @app.call(env)
+  end
+  
+  def body(path='/', env={})
+    s = ''
+    b = req(path, env)[2]
+    b.each{|x| s << x}
+    b.close if b.respond_to?(:close)
+    s
+  end
+
+  before do 
+    @app = Class.new(Roda)
+    @app.plugin :route_list, :file=>'spec/routes.json'
+    @app.route do |r|
+      named_route(env['PATH_INFO'].to_sym)
+    end
+    @app
+  end
+
+  after do
+    File.delete('routes.json') if File.exist?('routes.json')
+  end
+
+  it "should correctly parse the routes from the json file" do
+    @app.route_list.should == [
+      {:path=>'/foo'},
+      {:path=>'/foo/bar', :name=>:bar},
+      {:path=>'/foo/baz', :methods=>[:GET]},
+      {:path=>'/foo/baz/quux/:quux_id', :name=>:quux, :methods=>[:GET, :POST]},
+    ]
+  end
+
+  it "should respect :root option when parsing json file" do
+    @app = Class.new(Roda)
+    @app.opts[:root] = 'spec'
+    @app.plugin :route_list, :file=>'routes2.json'
+    @app.route_list.should == [{:path=>'/foo'}]
+  end
+
+  it ".named_route should return path for route" do
+    @app.named_route(:bar).should == '/foo/bar'
+    @app.named_route(:quux).should == '/foo/baz/quux/:quux_id'
+  end
+
+  it ".named_route should return path for route when given a values hash" do
+    @app.named_route(:quux, :quux_id=>3).should == '/foo/baz/quux/3'
+  end
+
+  it ".named_route should return path for route when given a values array" do
+    @app.named_route(:quux, [3]).should == '/foo/baz/quux/3'
+  end
+
+  it ".named_route should raise RodaError if there is no matching route" do
+    proc{@app.named_route(:foo)}.should raise_error(Roda::RodaError)
+  end
+
+  it ".named_route should raise RodaError if there is no matching value when using a values hash" do
+    proc{@app.named_route(:quux, {})}.should raise_error(Roda::RodaError)
+  end
+
+  it ".named_route should raise RodaError if there is no matching value when using a values array" do
+    proc{@app.named_route(:quux, [])}.should raise_error(Roda::RodaError)
+  end
+
+  it ".named_route should raise RodaError if there are too many values when using a values array" do
+    proc{@app.named_route(:quux, [3, 1])}.should raise_error(Roda::RodaError)
+  end
+
+  it "should allow parsing routes from a separate file" do
+    @app.plugin :route_list, :file=>'spec/routes2.json'
+    @app.route_list.should == [{:path=>'/foo'}]
+  end
+
+  it "#named_route should work" do
+    body('bar').should == '/foo/bar'
+  end
+
+  it "#named_route should respect :add_script_name option" do
+    @app.opts[:add_script_name] = true
+    body('bar').should == '/foo/bar'
+    body('bar', 'SCRIPT_NAME'=>'/a').should == '/a/foo/bar'
+  end
+end
+
+describe 'roda-route_parser executable' do
+  after do
+    File.delete "spec/routes-example.json"
+  end
+
+  it "should correctly parse the routes" do
+    system(ENV['RUBY'], "bin/roda-parse_routes", "-f", "spec/routes-example.json", "spec/routes.example")
+    File.file?("spec/routes-example.json").should == true
+    JSON.parse(File.read('spec/routes-example.json')).should == JSON.parse(File.read('spec/routes.json'))
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: roda-route_list
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeremy Evans
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: roda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: |
+  Roda, like other routing tree web frameworks, doesn't have the ability
+  to introspect routes.  roda-route_list offers a way to specify a json
+  file containing the route metadata, which the route_list plugin will
+  read.  It also offers a roda-parse_routes binary that can parse routes
+  out of roda app files, if those app files contain comments specifying
+  the routes.
+email: code@jeremyevans.net
+executables:
+- roda-parse_routes
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+files:
+- CHANGELOG
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- bin/roda-parse_routes
+- lib/roda-route_parser.rb
+- lib/roda/plugins/route_list.rb
+- spec/roda-route_list_spec.rb
+homepage: http://github.com/jeremyevans/roda-route_list
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--quiet"
+- "--line-numbers"
+- "--inline-source"
+- "--title"
+- 'roda-route_list: List routes when using Roda'
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: List routes when using Roda
+test_files: []