mustermann19 0.3.1

data/lib/mustermann/extension.rb

@@ -0,0 +1,52 @@
+require 'sinatra/version'
+fail "no need to load the Mustermann extension for #{::Sinatra::VERSION}" if ::Sinatra::VERSION >= '2.0.0'
+
+require 'mustermann'
+
+module Mustermann
+  # Sinatra 1.x extension switching default pattern parsing over to Mustermann.
+  #
+  # @example With classic Sinatra application
+  #   require 'sinatra'
+  #   require 'mustermann'
+  #
+  #   register Mustermann
+  #   get('/:id', capture: /\d+/) { ... }
+  #
+  # @example With modular Sinatra application
+  #   require 'sinatra/base'
+  #   require 'mustermann'
+  #
+  #   class MyApp < Sinatra::Base
+  #     register Mustermann
+  #     get('/:id', capture: /\d+/) { ... }
+  #   end
+  #
+  # @see file:README.md#Sinatra_Integration "Sinatra Integration" in the README
+  module Extension
+    def compile!(verb, path, block, options = {})
+      except  = options.delete(:except)
+      capture = options.delete(:capture)
+      pattern = options.delete(:pattern) || {}
+      if path.respond_to? :to_str
+        pattern[:except]  = except  if except
+        pattern[:capture] = capture if capture
+
+        if settings.respond_to? :pattern and settings.pattern?
+          pattern.merge! settings.pattern do |key, local, global|
+            next local unless local.is_a? Hash
+            next global.merge(local) if global.is_a? Hash
+            Hash.new(global).merge! local
+          end
+        end
+
+        path = Mustermann.new(path, pattern)
+        condition { params.merge! path.params(captures: Array(params[:captures]), offset: -1) }
+      end
+
+      super(verb, path, block, options)
+    end
+
+    private :compile!
+  end
+end

data/lib/mustermann/identity.rb

@@ -0,0 +1,19 @@
+require 'mustermann/pattern'
+
+module Mustermann
+  # Matches strings that are identical to the pattern.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :identity) === '/bar' # => false
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#identity Syntax description in the README
+  class Identity < Pattern
+    # @param (see Mustermann::Pattern#===)
+    # @return (see Mustermann::Pattern#===)
+    # @see (see Mustermann::Pattern#===)
+    def ===(string)
+      unescape(string) == @string
+    end
+  end
+end

data/lib/mustermann/mapper.rb

@@ -0,0 +1,98 @@
+require 'mustermann'
+require 'mustermann/expander'
+
+module Mustermann
+  # A mapper allows mapping one string to another based on pattern parsing and expanding.
+  #
+  # @example
+  #   require 'mustermann/mapper'
+  #   mapper = Mustermann::Mapper.new("/:foo" => "/:foo.html")
+  #   mapper['/example'] # => "/example.html"
+  class Mapper
+    # Creates a new mapper.
+    #
+    # @overload initialize(**options)
+    #   @param options [Hash] options The options hash
+    #   @yield block for generating mappings as a hash
+    #   @yieldreturn [Hash] see {#update}
+    #
+    #   @example
+    #     require 'mustermann/mapper'
+    #     Mustermann::Mapper.new(type: :rails) {{
+    #       "/:foo" => ["/:foo.html", "/:foo.:format"]
+    #     }}
+    #
+    # @overload initialize(**options)
+    #   @param  options [Hash] options The options hash
+    #   @yield block for generating mappings as a hash
+    #   @yieldparam mapper [Mustermann::Mapper] the mapper instance
+    #
+    #   @example
+    #     require 'mustermann/mapper'
+    #     Mustermann::Mapper.new(type: :rails) do |mapper|
+    #       mapper["/:foo"] = ["/:foo.html", "/:foo.:format"]
+    #     end
+    #
+    # @overload initialize(map = {}, **options)
+    #   @param map [Hash] see {#update}
+    #   @param [Hash] options The options hash
+    #
+    #   @example map before options
+    #     require 'mustermann/mapper'
+    #     Mustermann::Mapper.new("/:foo" => "/:foo.html", type: :rails)
+    #
+    #   @example map after options
+    #     require 'mustermann/mapper'
+    #     Mustermann::Mapper.new(type: :rails, "/:foo" => "/:foo.html")
+    def initialize(options = {}, &block)
+      @map               = []
+      @additional_values = options.delete(:additional_values) || :ignore
+      @options           = options
+      map = @options.inject({}) do |result, entry|
+        result[entry[0]] = @options.delete(entry[0]) if entry[0].is_a?(String)
+        result
+      end
+      block.arity == 0 ? update(yield) : yield(self) if block
+      update(map) if map
+    end
+
+    # Add multiple mappings.
+    #
+    # @param map [Hash{String, Pattern: String, Pattern, Arry<String, Pattern>, Expander}] the mapping
+    def update(map)
+      map.to_hash.each_pair do |input, output|
+        input  = Mustermann.new(input, @options.dup)
+        output = Expander.new(*output, @options.merge(additional_values: @additional_values)) unless output.is_a? Expander
+        @map << [input, output]
+      end
+    end
+
+    # @return [Hash{Patttern: Expander}] Hash version of the mapper.
+    def to_h
+      Hash[@map]
+    end
+
+    # Convert a string according to mappings. You can pass in additional params.
+    #
+    # @example mapping with and without additional parameters
+    #   mapper = Mustermann::Mapper.new("/:example" => "(/:prefix)?/:example.html")
+    #
+    def convert(input, values = {})
+      @map.inject(input) do |current, (pattern, expander)|
+        params = pattern.params(current)
+        params &&= Hash[values.merge(params).map { |k,v| [k.to_s, v] }]
+        expander.expandable?(params) ? expander.expand(params) : current
+      end
+    end
+
+    # Add a single mapping.
+    #
+    # @param key [String, Pattern] format of the input string
+    # @param value [String, Pattern, Arry<String, Pattern>, Expander] format of the output string
+    def []=(key, value)
+      update key => value
+    end
+
+    alias_method :[], :convert
+  end
+end

data/lib/mustermann/pattern.rb

@@ -0,0 +1,182 @@
+require 'mustermann/error'
+require 'mustermann/simple_match'
+require 'mustermann/equality_map'
+require 'uri'
+
+module Mustermann
+  # Superclass for all pattern implementations.
+  # @abstract
+  class Pattern
+    include Mustermann
+
+    # List of supported options.
+    #
+    # @overload supported_options
+    #   @return [Array<Symbol>] list of supported options
+    # @overload supported_options(*list)
+    #   Adds options to the list.
+    #
+    #   @api private
+    #   @param [Symbol] *list adds options to the list of supported options
+    #   @return [Array<Symbol>] list of supported options
+    def self.supported_options(*list)
+      @supported_options ||= []
+      options = @supported_options.concat(list)
+      options += superclass.supported_options if self < Pattern
+      options
+    end
+
+    # @param [Symbol] option The option to check.
+    # @return [Boolean] Whether or not option is supported.
+    def self.supported?(option)
+      supported_options.include? option
+    end
+
+    # @overload new(string, **options)
+    # @param (see #initialize)
+    # @raise (see #initialize)
+    # @raise [ArgumentError] if some option is not supported
+    # @return [Mustermann::Pattern] a new instance of Mustermann::Pattern
+    # @see #initialize
+    def self.new(string, options = {})
+      ignore_unknown_options = options.fetch(:ignore_unknown_options, false)
+      options.delete(:ignore_unknown_options)
+      unless ignore_unknown_options
+        unsupported = options.keys.detect { |key| not supported?(key) }
+        raise ArgumentError, "unsupported option %p for %p" % [unsupported, self] if unsupported
+      end
+
+      @map ||= EqualityMap.new
+      @map.fetch(string, options) { super(string, options) }
+    end
+
+    supported_options :uri_decode, :ignore_unknown_options
+
+    # @overload initialize(string, **options)
+    # @param [String] string the string representation of the pattern
+    # @param [Hash] options options for fine-tuning the pattern behavior
+    # @raise [Mustermann::Error] if the pattern can't be generated from the string
+    # @see file:README.md#Types_and_Options "Types and Options" in the README
+    # @see Mustermann.new
+    def initialize(string, options = {})
+      uri_decode = options.fetch(:uri_decode, true)
+      @uri_decode = uri_decode
+      @string     = string.to_s.dup
+    end
+
+    # @return [String] the string representation of the pattern
+    def to_s
+      @string.dup
+    end
+
+    # @param [String] string The string to match against
+    # @return [MatchData, Mustermann::SimpleMatch, nil] MatchData or similar object if the pattern matches.
+    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-match Regexp#match
+    # @see http://ruby-doc.org/core-2.0/MatchData.html MatchData
+    # @see Mustermann::SimpleMatch
+    def match(string)
+      SimpleMatch.new(string) if self === string
+    end
+
+    # @param [String] string The string to match against
+    # @return [Integer, nil] nil if pattern does not match the string, zero if it does.
+    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-3D-7E Regexp#=~
+    def =~(string)
+      0 if self === string
+    end
+
+    # @param [String] string The string to match against
+    # @return [Boolean] Whether or not the pattern matches the given string
+    # @note Needs to be overridden by subclass.
+    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-3D-3D-3D Regexp#===
+    def ===(string)
+      raise NotImplementedError, 'subclass responsibility'
+    end
+
+    # @return [Array<String>] capture names.
+    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-named_captures Regexp#named_captures
+    def named_captures
+      {}
+    end
+
+    # @return [Hash{String: Array<Integer>}] capture names mapped to capture index.
+    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-names Regexp#names
+    def names
+      []
+    end
+
+    # @param [String] string the string to match against
+    # @return [Hash{String: String, Array<String>}, nil] Sinatra style params if pattern matches.
+    def params(string = nil, options = {})
+      options, string = string, nil if string.is_a?(Hash)
+      captures = options[:captures]
+      offset   = options[:offset] || 0
+      return unless captures ||= match(string)
+      params   = named_captures.map do |name, positions|
+        values = positions.map { |pos| map_param(name, captures[pos + offset]) }.flatten
+        values = values.first if values.size < 2 and not always_array? name
+        [name, values]
+      end
+
+      Hash[params]
+    end
+
+    # @note This method is only implemented by certain subclasses.
+    #
+    # @example Expanding a pattern
+    #   pattern = Mustermann.new('/:name(.:ext)?')
+    #   pattern.expand(name: 'hello')             # => "/hello"
+    #   pattern.expand(name: 'hello', ext: 'png') # => "/hello.png"
+    #
+    # @example Checking if a pattern supports expanding
+    #   if pattern.respond_to? :expand
+    #     pattern.expand(name: "foo")
+    #   else
+    #     warn "does not support expanding"
+    #   end
+    #
+    # @param [Hash{Symbol: #to_s, Array<#to_s>}] values values to use for expansion
+    # @return [String] expanded string
+    # @raise [NotImplementedError] raised if expand is not supported.
+    # @raise [Mustermann::ExpandError] raised if a value is missing or unknown
+    # @see Mustermann::Expander
+    def expand(values = {})
+      raise NotImplementedError, "expanding not supported by #{self.class}"
+    end
+
+    # @!visibility private
+    # @return [Boolean]
+    # @see Object#respond_to?
+    def respond_to?(method, *args)
+      method.to_s == 'expand' ? false : super
+    end
+
+    # @!visibility private
+    def inspect
+      "#<%p:%p>" % [self.class, @string]
+    end
+
+    # @!visibility private
+    def map_param(key, value)
+      unescape(value, true)
+    end
+
+    # @!visibility private
+    def unescape(string, decode = @uri_decode)
+      return string unless decode and string
+      @uri ||= URI::Parser.new
+      @uri.unescape(string)
+    end
+
+    # @!visibility private
+    ALWAYS_ARRAY = %w[splat captures]
+
+    # @!visibility private
+    def always_array?(key)
+      ALWAYS_ARRAY.include? key
+    end
+
+    private :unescape, :map_param
+    #private_constant :ALWAYS_ARRAY
+  end
+end

data/lib/mustermann/rails.rb

@@ -0,0 +1,17 @@
+require 'mustermann/ast/pattern'
+
+module Mustermann
+  # Rails style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :rails) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#rails Syntax description in the README
+  class Rails < AST::Pattern
+    on(nil, ?)) { |c| unexpected(c) }
+    on(?*)      { |c| node(:named_splat) { scan(/\w+/) } }
+    on(?()      { |c| node(:optional, node(:group) { read unless scan(?)) }) }
+    on(?:)      { |c| node(:capture) { scan(/\w+/) } }
+  end
+end

data/lib/mustermann/regexp_based.rb

@@ -0,0 +1,30 @@
+require 'mustermann/pattern'
+require 'forwardable'
+
+module Mustermann
+  # Superclass for patterns that internally compile to a regular expression.
+  # @see Mustermann::Pattern
+  # @abstract
+  class RegexpBased < Pattern
+    # @return [Regexp] regular expression equivalent to the pattern.
+    attr_reader :regexp
+    alias_method :to_regexp, :regexp
+
+    # @param (see Mustermann::Pattern#initialize)
+    # @return (see Mustermann::Pattern#initialize)
+    # @see (see Mustermann::Pattern#initialize)
+    def initialize(string, options = {})
+      super
+      @regexp = compile(options)
+    end
+
+    extend Forwardable
+    def_delegators :regexp, :===, :=~, :match, :names, :named_captures
+
+    def compile(options = {})
+      raise NotImplementedError, 'subclass responsibility'
+    end
+
+    private :compile
+  end
+end

data/lib/mustermann/regular.rb

@@ -0,0 +1,26 @@
+require 'mustermann/regexp_based'
+
+module Mustermann
+  # Regexp pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/.*', type: :regexp) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#simple Syntax description in the README
+  class Regular < RegexpBased
+    # @param (see Mustermann::Pattern#initialize)
+    # @return (see Mustermann::Pattern#initialize)
+    # @see (see Mustermann::Pattern#initialize)
+    def initialize(string, options = {})
+      string = $1 if string.to_s =~ /\A\(\?\-mix\:(.*)\)\Z/ && string.inspect == "/#$1/"
+      super(string, options)
+    end
+
+    def compile(options = {})
+      /\A#{@string}\Z/
+    end
+
+    private :compile
+  end
+end

data/lib/mustermann/router.rb

@@ -0,0 +1,9 @@
+require 'mustermann/router/simple'
+require 'mustermann/router/rack'
+
+module Mustermann
+  # @see Mustermann::Router::Simple
+  # @see Mustermann::Router::Rack
+  module Router
+  end
+end

data/lib/mustermann/router/rack.rb

@@ -0,0 +1,50 @@
+require 'mustermann/router/simple'
+
+module Mustermann
+  module Router
+    # Simple pattern based router that allows matching paths to a given Rack application.
+    #
+    # @example config.ru
+    #    router = Mustermann::Rack.new do
+    #      on '/' do |env|
+    #        [200, {'Content-Type' => 'text/plain'}, ['Hello World!']]
+    #      end
+    #
+    #      on '/:name' do |env|
+    #        name = env['mustermann.params']['name']
+    #        [200, {'Content-Type' => 'text/plain'}, ["Hello #{name}!"]]
+    #      end
+    #
+    #      on '/something/*', call: SomeApp
+    #    end
+    #
+    #    # in a config.ru
+    #    run router
+    class Rack < Simple
+      def initialize(options = {}, &block)
+        env_prefix  = options.delete(:env_prefix) || "mustermann"
+        params_key  = options.delete(:params_key) || "#{env_prefix}.params"
+        pattern_key = options.delete(:pattern_key) || "#{env_prefix}.pattern"
+        @params_key, @pattern_key = params_key, pattern_key
+        options[:default] = [404, {"Content-Type" => "text/plain", "X-Cascade" => "pass"}, ["Not Found"]] unless options.include? :default
+        super(options, &block)
+      end
+
+      def invoke(callback, env, params, pattern)
+        params_was, pattern_was             = env[@params_key], env[@pattern_key]
+        env[@params_key], env[@pattern_key] = params, pattern
+        response = callback.call(env)
+        response[1].each { |k,v| throw :pass if k.downcase == 'x-cascade' and v == 'pass' }
+        response
+      ensure
+        env[@params_key], env[@pattern_key] = params_was, pattern_was
+      end
+
+      def string_for(env)
+        env['PATH_INFO']
+      end
+
+      private :invoke, :string_for
+    end
+  end
+end