mustermann 0.0.1

data/lib/mustermann/error.rb

@@ -0,0 +1,14 @@
+module Mustermann
+  # Raised if anything goes wrong while generating a {Pattern}.
+  class Error < StandardError; end
+
+  # Raised if anything goes wrong while compiling a {Pattern}.
+  class CompileError < Error; end
+
+  # Raised if anything goes wrong while parsing a {Pattern}.
+  class ParseError < Error; end
+
+  #@!visibility private
+  class UnexpectedClosingGroup < ParseError; end
+  private_constant :UnexpectedClosingGroup
+end

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, except: nil, capture: nil, pattern: { }, **options)
+      if path.respond_to? :to_str
+        pattern[:except]  = except  if except
+        pattern[:capture] = capture if capture
+
+        if settings.respond_to? :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)
+
+        if defined? Template and path.is_a? Template
+          condition { params.merge! path.params(request.path_info) }
+        end
+      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 Pattern
+  # @see file:README.md#identity Syntax description in the README
+  class Identity < Pattern
+    # @param (see Pattern#===)
+    # @return (see Pattern#===)
+    # @see (see Pattern#===)
+    def ===(string)
+      unescape(string) == @string
+    end
+  end
+end

data/lib/mustermann/pattern.rb

@@ -0,0 +1,142 @@
+require 'mustermann/error'
+require 'mustermann/simple_match'
+require 'uri'
+
+module Mustermann
+  # Superclass for all pattern implementations.
+  # @abstract
+  class Pattern
+    # 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 [Pattern] a new instance of Pattern
+    # @see #initialize
+    def self.new(string, ignore_unknown_options: false, **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
+
+      super(string, options)
+    end
+
+    supported_options :uri_decode, :ignore_unknown_options
+
+    # @overload initialize(string, **options)
+    # @param [String] string the string repesentation 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, uri_decode: true, **options)
+      @uri_decode = uri_decode
+      @string     = string.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 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, captures: nil)
+      return unless captures ||= match(string)
+      params   = named_captures.map do |name, positions|
+        values = positions.map { |pos| map_param(name, captures[pos]) }.flatten
+        values = values.first if values.size < 2 and not always_array? name
+        [name, values]
+      end
+
+      Hash[params]
+    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,26 @@
+require 'mustermann/ast'
+
+module Mustermann
+  # Rails style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :rails) === '/bar' # => true
+  #
+  # @see Pattern
+  # @see file:README.md#rails Syntax description in the README
+  class Rails < AST
+    def parse_element(buffer)
+      case char = buffer.getch
+      when nil then unexpected("end of string")
+      when ?)  then unexpected(char, exception: UnexpectedClosingGroup)
+      when ?*  then NamedSplat.parse { buffer.scan(/\w+/) }
+      when ?/  then Separator.new(char)
+      when ?(  then Optional.new(Group.parse { parse_buffer(buffer) })
+      when ?:  then Capture.parse { buffer.scan(/\w+/) }
+      else Char.new(char)
+      end
+    end
+
+    private :parse_element
+  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 Pattern
+  # @abstract
+  class RegexpBased < Pattern
+    # @return [Regexp] regular expression equivalent to the pattern.
+    attr_reader :regexp
+    alias_method :to_regexp, :regexp
+
+    # @param (see Pattern#initialize)
+    # @return (see Pattern#initialize)
+    # @see (see Pattern#initialize)
+    def initialize(string, **options)
+      @regexp = compile(string, **options)
+      super
+    end
+
+    extend Forwardable
+    def_delegators :regexp, :===, :=~, :match, :names, :named_captures
+
+    def compile(string, **options)
+      raise NotImplementedError, 'subclass responsibility'
+    end
+
+    private :compile
+  end
+end

data/lib/mustermann/shell.rb

@@ -0,0 +1,22 @@
+require 'mustermann/pattern'
+require 'mustermann/simple_match'
+
+module Mustermann
+  # Matches strings that are identical to the pattern.
+  #
+  # @example
+  #   Mustermann.new('/*.*', type: :shell) === '/bar' # => false
+  #
+  # @see Pattern
+  # @see file:README.md#shell Syntax description in the README
+  class Shell < Pattern
+    FLAGS ||= File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
+
+    # @param (see Pattern#===)
+    # @return (see Pattern#===)
+    # @see (see Pattern#===)
+    def ===(string)
+      File.fnmatch? @string, unescape(string), FLAGS
+    end
+  end
+end

data/lib/mustermann/simple.rb

@@ -0,0 +1,35 @@
+require 'mustermann/regexp_based'
+
+module Mustermann
+  # Sinatra 1.3 style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :simple) === '/bar' # => true
+  #
+  # @see Pattern
+  # @see file:README.md#simple Syntax description in the README
+  class Simple < RegexpBased
+    supported_options :greedy, :space_matches_plus
+
+    def compile(string, greedy: true, uri_decode: true, space_matches_plus: true, **options)
+      pattern = string.gsub(/[^\?\%\\\/\:\*\w]/) { |c| encoded(c, uri_decode, space_matches_plus) }
+      pattern.gsub!(/((:\w+)|\*)/) do |match|
+        match == "*" ? "(?<splat>.*?)" : "(?<#{$2[1..-1]}>[^/?#]+#{?? unless greedy})"
+      end
+      /\A#{Regexp.new(pattern)}\Z/
+    rescue SyntaxError, RegexpError => error
+      type = error.message["invalid group name"] ? CompileError : ParseError
+      raise type, error.message, error.backtrace
+    end
+
+    def encoded(char, uri_decode, space_matches_plus)
+      return Regexp.escape(char) unless uri_decode
+      parser  = URI::Parser.new
+      encoded = Regexp.union(parser.escape(char), parser.escape(char, /./).downcase, parser.escape(char, /./).upcase)
+      encoded = Regexp.union(encoded, encoded('+', true, true)) if space_matches_plus and char == " "
+      encoded
+    end
+
+    private :compile, :encoded
+  end
+end

data/lib/mustermann/simple_match.rb

@@ -0,0 +1,30 @@
+module Mustermann
+  # Fakes MatchData for patterns that do not support capturing.
+  # @see http://ruby-doc.org/core-2.0/MatchData.html MatchData
+  class SimpleMatch
+    # @api private
+    def initialize(string)
+      @string = string.dup
+    end
+
+    # @return [String] the string that was matched against
+    def to_s
+      @string.dup
+    end
+
+    # @return [Array<String>] empty array for immitating MatchData interface
+    def names
+      []
+    end
+
+    # @return [Array<String>] empty array for immitating MatchData interface
+    def captures
+      []
+    end
+
+    # @return [nil] imitates MatchData interface
+    def [](*args)
+      captures[*args]
+    end
+  end
+end

data/lib/mustermann/sinatra.rb

@@ -0,0 +1,32 @@
+require 'mustermann/ast'
+
+module Mustermann
+  # Sinatra 2.0 style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo') === '/bar' # => true
+  #
+  # @see Pattern
+  # @see file:README.md#sinatra Syntax description in the README
+  class Sinatra < AST
+    def parse_element(buffer)
+      case char = buffer.getch
+      when nil, ?? then unexpected(char)
+      when ?)      then unexpected(char, exception: UnexpectedClosingGroup)
+      when ?*      then Splat.new
+      when ?/      then Separator.new(char)
+      when ?(      then Group.parse { parse_buffer(buffer) }
+      when ?:      then Capture.parse { buffer.scan(/\w+/) }
+      when ?\\     then Char.new expect(buffer, /./)
+      else Char.new(char)
+      end
+    end
+
+    def parse_suffix(element, buffer)
+      return element unless buffer.scan(/\?/)
+      Optional.new(element)
+    end
+
+    private :parse_element, :parse_suffix
+  end
+end

data/lib/mustermann/template.rb

@@ -0,0 +1,140 @@
+require 'mustermann/ast'
+
+module Mustermann
+  # URI template pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/{foo}') === '/bar' # => true
+  #
+  # @see Pattern
+  # @see file:README.md#template Syntax description in the README
+  # @see http://tools.ietf.org/html/rfc6570 RFC 6570
+  class Template < AST
+    Operator  ||= Struct.new(:separator, :allow_reserved, :prefix, :parametric)
+    OPERATORS ||= {
+      nil => Operator.new(?,, false, false, false), ?+  => Operator.new(?,, true,  false, false),
+      ?#  => Operator.new(?,, true,  ?#,    false), ?.  => Operator.new(?., false, ?.,    false),
+      ?/  => Operator.new(?/, false, ?/,    false), ?;  => Operator.new(?;, false, ?;,    true),
+      ??  => Operator.new(?&, false, ??,    true),  ?&  => Operator.new(?&, false, ?&,    true)
+    }
+
+    # AST node for template expressions.
+    # @!visibility private
+    class Expression < Group
+      # @!visibility private
+      attr_accessor :operator
+
+      # makes sure we have the proper surrounding characters for the operator
+      # @!visibility private
+      def transform
+        self.operator = OPERATORS.fetch(operator) { raise CompileError, "#{operator} operator not supported" }
+        new_payload   = payload.inject { |list, element| Array(list) << separator << element }
+        @payload      = Array(new_payload).map!(&:transform)
+        payload.unshift separator(operator.prefix) if operator.prefix
+        self
+      end
+
+      # @!visibility private
+      def compile(greedy: true, **options)
+        super(allow_reserved: operator.allow_reserved, greedy: greedy && !operator.allow_reserved,
+          parametric: operator.parametric, separator: operator.separator, **options)
+      end
+
+      # @!visibility private
+      def separator(char = operator.separator)
+        AST.const_get(:Separator).new(char) # uhm
+      end
+    end
+
+    # AST node for template variables.
+    # @!visibility private
+    class Variable < Capture
+      # @!visibility private
+      attr_accessor :prefix, :explode
+
+      # @!visibility private
+      def compile(**options)
+        return super(**options) if explode or not options[:parametric]
+        parametric super(parametric: false, **options)
+      end
+
+      # @!visibility private
+      def pattern(parametric: false, **options)
+        register_param(parametric: parametric, **options)
+        pattern = super(**options)
+        pattern = parametric(pattern) if parametric
+        pattern = "#{pattern}(?:#{Regexp.escape(options.fetch(:separator))}#{pattern})*" if explode
+        pattern
+      end
+
+      # @!visibility private
+      def parametric(string)
+        "#{Regexp.escape(name)}(?:=#{string})?"
+      end
+
+      # @!visibility private
+      def qualified(string, **options)
+        prefix ? "#{string}{1,#{prefix}}" : super(string, **options)
+      end
+
+      # @!visibility private
+      def default(allow_reserved: false, **options)
+        allow_reserved ? '[\w\-\.~%\:/\?#\[\]@\!\$\&\'\(\)\*\+,;=]' : '[\w\-\.~%]'
+      end
+
+      # @!visibility private
+      def register_param(parametric: false, split_params: nil, separator: nil, **options)
+        return unless explode and split_params
+        split_params[name] = { separator: separator, parametric: parametric }
+      end
+    end
+
+    # @!visibility private
+    def parse_element(buffer)
+      parse_expression(buffer) || parse_literal(buffer)
+    end
+
+    # @!visibility private
+    def parse_expression(buffer)
+      return unless buffer.scan(/\{/)
+      operator   = buffer.scan(/[\+\#\.\/;\?\&\=\,\!\@\|]/)
+      expression = Expression.new(parse_variable(buffer), operator: operator)
+      expression.parse { parse_variable(buffer) if buffer.scan(/,/) }
+      expression if expect(buffer, ?})
+    end
+
+    # @!visibility private
+    def parse_variable(buffer)
+      match = expect(buffer, /(?<name>\w+)(?:\:(?<prefix>\d{1,4})|(?<explode>\*))?/)
+      Variable.new(match[:name], prefix: match[:prefix], explode: match[:explode])
+    end
+
+    # @!visibility private
+    def parse_literal(buffer)
+      return unless char = buffer.getch
+      raise unexpected(?}) if char == ?}
+      char == ?/ ? Separator.new('/') : Char.new(char)
+    end
+
+    # @!visibility private
+    def compile(*args, **options)
+      @split_params = {}
+      super(*args, split_params: @split_params, **options)
+    end
+
+    # @!visibility private
+    def map_param(key, value)
+      return super unless variable = @split_params[key]
+      value = value.split variable[:separator]
+      value.map! { |e| e.sub(/\A#{key}=/, '') } if variable[:parametric]
+      value.map! { |e| super(key, e) }
+    end
+
+    # @!visibility private
+    def always_array?(key)
+      @split_params.include? key
+    end
+
+    private :parse_element, :parse_expression, :parse_literal, :parse_variable, :map_param, :always_array?
+  end
+end