rails-rfc6570 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0011c2277baf555923c718d4a01115c09b782073
+  data.tar.gz: 1d1bb93a9d2d0532c9d2701199ef56e6825cd385
+SHA512:
+  metadata.gz: ff0b022b561c859014393657fd794529c58f182db2994df60803b4eb978244f125a47640c01092297a34cf7b2d4cc1236769d6ab9bb9fe8c6b1d8cc3f4b3e62a
+  data.tar.gz: 2c9a03ee10bd4d793a275e661434b8edd7aa3a1b4c40e501b02fdd963dfb06ed503abf4c6c8f6f91da580801977e094b94e728ae6a7fa255a18d922e46455aad

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jan Graichen
+
+MIT License
+
+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.md

@@ -0,0 +1,119 @@
+# Rails::RFC6570
+
+Pragmatical access to your Rails routes as RFC6570 URI templates.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rails-rfc6570', '~> 0.1'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rails-rfc6570
+
+## Usage
+
+**Rails::RFC6570** gives you direct access to your Rails routes as RFC6570 URI templates using the [addressable](https://github.com/sporkmonger/addressable) gem. It further patches `Addressable::Template` with a `#as_json` and `#to_s` so that you can simply pass the template objects or even partial expanded templates to your render call, decorator or serializer.
+
+This examples print a JSON index resource just like https://api.github.com:
+
+```ruby
+class ApplicationController < ActionController::API
+  def index
+    render json: rfc6570_routes(ignore: %w(format), path_only: false)
+  end
+end
+```
+
+By default the `format` placeholder is ignored and the HTTP host will be included in the URI template.
+
+Additionally you can specify a list of query parameters in your controllers:
+
+```ruby
+class UserController < ApplicationController
+
+  rfc6570_params index: [:query, :email, :active]
+  def index
+    # ...
+  end
+
+  def show
+    # ...
+  end
+
+  # ...
+end
+```
+
+Given the above and this routes
+
+```ruby
+Rails::Application.routes.draw do
+  resources :users, except: [:new, :edit]
+  root to: 'application#index'
+end
+```
+
+the root action will return something similar to the following JSON:
+
+```json
+{
+users: "http://localhost:3000/users{?query,email,active}",
+user: "http://localhost:3000/users/{id}",
+root: "http://localhost:3000/"
+}
+```
+
+You can also access your RFC6570 routes pragmatically everywhere you can access Rails' URL helpers e.g. in a decorator.
+
+You can use this to e.g. partial expand templates for nested resources:
+
+```ruby
+module ApplicationHelpers
+  include Rails.application.routes.url_helpers
+end
+
+class UserDecorator < Draper::Decorator
+  def as_json(opts)
+    {
+      id: object.id,
+      self_url: user_url(object),
+      posts_url: user_posts_rfc6570.partial_expand(user_id: object.id),
+    }
+  end
+end
+```
+
+You can also combine **Rails::RFC6570** with [rack-link_headers](https://jgraichen/rack-link_headers) and provide Hypermedia-linking everywhere!
+
+```ruby
+class UserController < ApplicationController
+  respond_to :json
+
+  def show
+    @user = User.find
+    response.link user_url(@user), rel: :self
+    response.link user_posts_rfc6570.partial_expand(user_id: @user.id), rel: :posts
+    response.link profile_rfc6570.expand(user_id: @user.id), rel: :profile
+
+    respond_with @user
+  end
+end
+```
+
+## ToDos
+
+* Still has *no* tests.
+
+## Contributing
+
+1. Fork it (http://github.com/jgraichen/rails-routes/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/rails/rfc6570.rb

@@ -0,0 +1,186 @@
+require 'rails/routes/version'
+
+module ActionDispatch
+  module Journey
+    module Visitors
+      class RFC6570 < String
+        def initialize(opts = {})
+          super()
+
+          @opts        = opts
+          @group_depth = 0
+        end
+
+        def ignore
+          @opts.fetch(:ignore) { %w(format) }
+        end
+
+        def route
+          @route ||= @opts[:route]
+        end
+
+        def accept(node)
+          str = super
+
+          if @opts.fetch(:params, true) && route
+            controller = route.defaults[:controller].to_s
+            action     = route.defaults[:action].to_s
+
+            if controller.present? && action.present?
+              params = Rails::Routes.params_for(controller, action)
+              str += '{?' + params.join(',') + '}' if params && params.any?
+            end
+          end
+
+          str
+        end
+
+        def symbol_name(node)
+          name = node.to_s.tr '*:', ''
+
+          if ignore.include?(name)
+            nil
+          else
+            name
+          end
+        end
+
+        def placeholder(node, prefix = nil, suffix = nil)
+          name = symbol_name node
+          if name
+            "{#{prefix}#{name}#{suffix}}"
+          else
+            ''
+          end
+        end
+
+        def visit_SYMBOL(node)
+          placeholder node
+        end
+
+        def binary(node)
+          case [node.left.type, node.right.type]
+            when [:DOT, :SYMBOL]
+              if @group_depth == 0
+                '.' + placeholder(node.right)
+              else
+                placeholder node.right, '.'
+              end
+            when [:SLASH, :SYMBOL]
+              if @group_depth == 0
+                '/' + placeholder(node.right)
+              else
+                placeholder(node.right, '/')
+              end
+            when [:SLASH, :STAR]
+              placeholder node.right, '/', '*'
+            when [:CAT, :STAR]
+              visit(node.left).to_s.gsub(/\/+$/, '') + placeholder(node.right, '/', '*')
+            else
+              super
+          end
+        end
+
+        def visit_GROUP(node)
+          if @group_depth >= 1
+            raise RuntimeError.new \
+              'Cannot transform nested groups.'
+          else
+            @group_depth += 1
+            visit node.left
+          end
+        ensure
+          @group_depth -= 1
+        end
+      end
+    end
+  end
+end
+
+module Rails
+  module RFC6570
+    if defined?(::Rails::Railtie)
+      class Railtie < Rails::Railtie # :nodoc:
+        initializer 'rails-routes', :group => :all do |app|
+          require 'rails/routes/patches'
+
+          ActiveSupport.on_load(:action_controller) do
+            include Rails::RFC6570::Helper
+            extend Rails::RFC6570::ControllerExtension
+            Rails.application.routes.url_helpers.include Rails::RFC6570::UrlHelper
+          end
+        end
+      end
+    end
+
+    module Helper
+      def rfc6570_routes(opts = {})
+        routes = {}
+        Rails.application.routes.named_routes.names.each do |key|
+          routes[key] = rfc6570_route(key, opts)
+        end
+
+        routes
+      end
+
+      def rfc6570_route(name, opts = {})
+        route    = Rails.application.routes.named_routes[name]
+        unless route
+          raise KeyError.new "No named routed for `#{name}'."
+        end
+
+        template = route.to_rfc6570(opts)
+
+        if opts.fetch(:path_only, false)
+          template
+        else
+          root_uri = Addressable::URI.parse(root_url)
+
+          Addressable::Template.new root_uri.join(template.pattern).to_s
+        end
+      end
+    end
+
+    module ControllerExtension
+      def rfc6570_defs
+        @__rfc6570_defs ||= {}
+      end
+
+      def rfc6570_params(defs)
+        rfc6570_defs.merge! defs
+      end
+
+      def rfc6570_params_for(defs)
+        rfc6570_defs[defs]
+      end
+    end
+
+    module UrlHelper
+      include Rails::RFC6570::Helper
+
+      def respond_to_missing?(mth, include_private = false)
+        if mth =~ /^(\w+)_rfc6570$/
+          Rails.application.routes.named_routes.names.include?($1)
+        else
+          super
+        end
+      end
+
+      def method_missing(mth, *args, &block)
+        if mth =~ /^(\w+)_rfc6570$/
+          rails_route $1
+        else
+          super
+        end
+      end
+    end
+
+    def params_for(controller, action)
+      ctr = "#{controller.camelize}Controller".constantize
+      ctr.rfc6570_defs[action.to_sym] if ctr.respond_to?(:rfc6570_defs)
+    rescue NameError
+      nil
+    end
+    extend self
+  end
+end

data/lib/rails/rfc6570/patches.rb

@@ -0,0 +1,45 @@
+require 'action_dispatch'
+require 'action_dispatch/journey'
+require 'addressable/template'
+
+module Addressable
+  class Template
+    def to_s
+      pattern
+    end
+
+    def as_json(*)
+      pattern
+    end
+  end
+end
+
+module ActionDispatch
+  module Routing
+    class RouteSet
+      def to_rfc6570(opts = {})
+        routes.map{|r| r.to_rfc6570(opts) }
+      end
+
+      class NamedRouteCollection
+        def to_rfc6570(opts = {})
+          Hash[routes.map{|n, r| [n, r.to_rfc6570(opts)] }]
+        end
+      end
+    end
+  end
+
+  module Journey
+    class Route
+      def to_rfc6570(opts = {})
+        path.spec.to_rfc6570 opts.merge(route: self)
+      end
+    end
+
+    class Nodes::Node
+      def to_rfc6570(opts = {})
+        ::Addressable::Template.new Visitors::RFC6570.new(opts).accept(self)
+      end
+    end
+  end
+end

data/lib/rails/rfc6570/version.rb

@@ -0,0 +1,16 @@
+module Rails
+  module RFC6570
+    module VERSION
+      MAJOR = 0
+      MINOR = 1
+      PATCH = 0
+      STAGE = nil
+
+      STRING = [MAJOR, MINOR, PATCH, STAGE].reject(&:nil?).join('.').freeze
+
+      def self.to_s
+        STRING
+      end
+    end
+  end
+end

data/rails-rfc6570.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rails/rfc6570/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rails-rfc6570'
+  spec.version       = Rails::RFC6570::VERSION
+  spec.authors       = ['Jan Graichen']
+  spec.email         = ['jg@altimos.de']
+  spec.summary       = %q(Pragmatical access to your Rails routes as RFC6570 URI templates.)
+  spec.description   = %q(Pragmatical access to your Rails routes as RFC6570 URI templates.)
+  spec.homepage      = 'https://github.com/jgraichen/rails-rfc6570'
+  spec.license       = 'MIT'
+
+  spec.files         = Dir['**/*'].grep(/^(
+      (bin|lib|test|spec|features)\/|
+      (.*\.gemspec|.*LICENSE.*|.*README.*|.*CHANGELOG.*)
+    )/x)
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'addressable', '~> 2.3'
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: rails-rfc6570
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jan Graichen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pragmatical access to your Rails routes as RFC6570 URI templates.
+email:
+- jg@altimos.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rails/rfc6570.rb
+- lib/rails/rfc6570/patches.rb
+- lib/rails/rfc6570/version.rb
+- rails-rfc6570.gemspec
+homepage: https://github.com/jgraichen/rails-rfc6570
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Pragmatical access to your Rails routes as RFC6570 URI templates.
+test_files: []