mustermann 0.3.1 → 0.4.0

data/lib/mustermann/composite.rb

@@ -0,0 +1,101 @@
+module Mustermann
+  # Class for pattern objects composed of multiple patterns using binary logic.
+  # @see Mustermann::Pattern#&
+  # @see Mustermann::Pattern#|
+  # @see Mustermann::Pattern#^
+  class Composite < Pattern
+    attr_reader :patterns, :operator
+    supported_options :operator, :type
+
+    # @see Mustermann::Pattern.supported?
+    def self.supported?(option, **options)
+      return true if super
+      options[:type] and Mustermann[options[:type]].supported?(option, **options)
+    end
+
+    # @return [Mustermann::Pattern] a new composite pattern
+    def self.new(*patterns, **options)
+      patterns = patterns.flatten
+      case patterns.size
+      when 0 then raise ArgumentError, 'cannot create empty composite pattern'
+      when 1 then patterns.first
+      else super(patterns, **options)
+      end
+    end
+
+    def initialize(patterns, operator: :|, **options)
+      @operator = operator.to_sym
+      @patterns = patterns.flat_map { |p| patterns_from(p, **options) }
+    end
+
+    # @see Mustermann::Pattern#==
+    def ==(pattern)
+      patterns == patterns_from(pattern)
+    end
+
+    # @see Mustermann::Pattern#===
+    def ===(string)
+      patterns.map { |p| p === string }.inject(operator)
+    end
+
+    # @see Mustermann::Pattern#params
+    def params(string)
+      with_matching(string, :params)
+    end
+
+    # @see Mustermann::Pattern#match
+    def match(string)
+      with_matching(string, :match)
+    end
+
+    # @!visibility private
+    def respond_to_special?(method)
+      return false unless operator == :|
+      patterns.all? { |p| p.respond_to?(method) }
+    end
+
+    # (see Mustermann::Pattern#expand)
+    def expand(behavior = nil, values = {})
+      raise NotImplementedError, 'expanding not supported' unless respond_to? :expand
+      @expander ||= Mustermann::Expander.new(*patterns)
+      @expander.expand(behavior, values)
+    end
+
+    # (see Mustermann::Pattern#expand)
+    def to_templates
+      raise NotImplementedError, 'template generation not supported' unless respond_to? :to_templates
+      patterns.flat_map(&:to_templates).uniq
+    end
+
+    # @return [String] the string representation of the pattern
+    def to_s
+      simple_inspect
+    end
+
+    # @!visibility private
+    def inspect
+      "#<%p:%s>" % [self.class, simple_inspect]
+    end
+
+    # @!visibility private
+    def simple_inspect
+      pattern_strings = patterns.map { |p| p.simple_inspect }
+      "(#{pattern_strings.join(" #{operator} ")})"
+    end
+
+    # @!visibility private
+    def with_matching(string, method)
+      return unless self === string
+      pattern = patterns.detect { |p| p === string }
+      pattern.public_send(method, string) if pattern
+    end
+
+    # @!visibility private
+    def patterns_from(pattern, options = nil)
+      return pattern.patterns if pattern.is_a? Composite and pattern.operator == self.operator
+      [options ? Mustermann.new(pattern, **options) : pattern]
+    end
+
+    private :with_matching, :patterns_from
+  end
+end

data/lib/mustermann/expander.rb

@@ -41,7 +41,7 @@ module Mustermann
     # @return [Mustermann::Expander] the expander
     def add(*patterns)
       patterns.each do |pattern|
-        pattern = Mustermann.new(pattern.to_str, **@options) if pattern.respond_to? :to_str
+        pattern = Mustermann.new(pattern, **@options)
         raise NotImplementedError, "expanding not supported for #{pattern.class}" unless pattern.respond_to? :to_ast
         @api_expander.add(pattern.to_ast)
         @patterns << pattern
@@ -137,7 +137,7 @@ module Mustermann
     # @return [String] expanded string
     # @raise [NotImplementedError] raised if expand is not supported.
     # @raise [Mustermann::ExpandError] raised if a value is missing or unknown
-    def expand(behavior = nil, **values)
+    def expand(behavior = nil, values = {})
       behavior, values = nil, behavior if behavior.is_a? Hash
       values = map_values(values)
 

data/lib/mustermann/identity.rb

@@ -1,4 +1,6 @@
+require 'mustermann'
 require 'mustermann/pattern'
+require 'mustermann/ast/node'
 
 module Mustermann
   # Matches strings that are identical to the pattern.
@@ -9,11 +11,65 @@ module Mustermann
   # @see Mustermann::Pattern
   # @see file:README.md#identity Syntax description in the README
   class Identity < Pattern
+    register :identity
+
     # @param (see Mustermann::Pattern#===)
     # @return (see Mustermann::Pattern#===)
     # @see (see Mustermann::Pattern#===)
     def ===(string)
       unescape(string) == @string
     end
+
+    # @param (see Mustermann::Pattern#peek_size)
+    # @return (see Mustermann::Pattern#peek_size)
+    # @see (see Mustermann::Pattern#peek_size)
+    def peek_size(string)
+      return unless unescape(string).start_with? @string
+      return @string.size if string.start_with? @string # optimization
+      @string.each_char.with_index.inject(0) do |count, (char, index)|
+        char_size = 1
+        escaped   = @@uri.escape(char, /./)
+        char_size = escaped.size if string[index, escaped.size].downcase == escaped.downcase
+        count + char_size
+      end
+    end
+
+    # URI templates support generating templates (the logic is quite complex, though).
+    #
+    # @example (see Mustermann::Pattern#to_templates)
+    # @param (see Mustermann::Pattern#to_templates)
+    # @return (see Mustermann::Pattern#to_templates)
+    # @see Mustermann::Pattern#to_templates
+    def to_templates
+      [@@uri.escape(to_s)]
+    end
+
+    # Generates an AST so it's compatible with {Mustermann::AST::Pattern}.
+    # Not used internally by {Mustermann::Identity}.
+    # @!visibility private
+    def to_ast
+      payload = @string.each_char.with_index.map { |c, i| AST::Node[c == ?/ ? :separator : :char].new(c, start: i, stop: i+1) }
+      AST::Node[:root].new(payload, pattern: @string, start: 0, stop: @string.length)
+    end
+
+    # Identity patterns support expanding.
+    #
+    # This implementation does not use {Mustermann::Expander} internally to save memory and
+    # compilation time.
+    #
+    # @example (see Mustermann::Pattern#expand)
+    # @param (see Mustermann::Pattern#expand)
+    # @return (see Mustermann::Pattern#expand)
+    # @raise (see Mustermann::Pattern#expand)
+    # @see Mustermann::Pattern#expand
+    # @see Mustermann::Expander
+    def expand(behavior = nil, values = {})
+      return to_s if values.empty? or behavior == :ignore
+      raise ExpandError,    "cannot expand with keys %p" % values.keys.sort if behavior == :raise
+      raise ArgumentError,  "unknown behavior %p"        % behavior         if behavior != :append
+      params    = values.map { |key, value| @@uri.escape(key.to_s) + "=" + @@uri.escape(value.to_s, /[^\w]/) }
+      separator = @string.include?(??) ? ?& : ??
+      @string + separator + params.join(?&)
+    end
   end
 end

data/lib/mustermann/pattern.rb

@@ -8,6 +8,7 @@ module Mustermann
   # @abstract
   class Pattern
     include Mustermann
+    @@uri ||= URI::Parser.new
 
     # List of supported options.
     #
@@ -26,9 +27,16 @@ module Mustermann
       options
     end
 
+    # Registers the pattern with Mustermann.
+    # @see Mustermann.register
+    # @!visibility private
+    def self.register(*names)
+      names.each { |name| Mustermann.register(name, self) }
+    end
+
     # @param [Symbol] option The option to check.
     # @return [Boolean] Whether or not option is supported.
-    def self.supported?(option)
+    def self.supported?(option, **options)
       supported_options.include? option
     end
 
@@ -40,7 +48,7 @@ module Mustermann
     # @see #initialize
     def self.new(string, ignore_unknown_options: false, **options)
       unless ignore_unknown_options
-        unsupported = options.keys.detect { |key| not supported?(key) }
+        unsupported = options.keys.detect { |key| not supported?(key, **options) }
         raise ArgumentError, "unsupported option %p for %p" % [unsupported, self] if unsupported
       end
 
@@ -90,13 +98,73 @@ module Mustermann
       raise NotImplementedError, 'subclass responsibility'
     end
 
-    # @return [Array<String>] capture names.
+    # Tries to match the pattern against the beginning of the string (as opposed to the full string).
+    # Will return the count of the matching characters if it matches.
+    #
+    # @example
+    #   pattern = Mustermann.new('/:name')
+    #   pattern.size("/Frank/Sinatra") # => 6
+    #
+    # @param [String] string The string to match against
+    # @return [Integer, nil] the number of characters that match
+    def peek_size(string)
+      # this is a very naive, unperformant implementation
+      string.size.downto(0).detect { |s| self === string[0, s] }
+    end
+
+    # Tries to match the pattern against the beginning of the string (as opposed to the full string).
+    # Will return the substring if it matches.
+    #
+    # @example
+    #   pattern = Mustermann.new('/:name')
+    #   pattern.peek("/Frank/Sinatra") # => "/Frank"
+    #
+    # @param [String] string The string to match against
+    # @return [String, nil] matched subsctring
+    def peek(string)
+      size = peek_size(string)
+      string[0, size] if size
+    end
+
+    # Tries to match the pattern against the beginning of the string (as opposed to the full string).
+    # Will return a MatchData or similar instance for the matched substring.
+    #
+    # @example
+    #   pattern = Mustermann.new('/:name')
+    #   pattern.peek("/Frank/Sinatra") # => #<MatchData "/Frank" name:"Frank">
+    #
+    # @param [String] string The string to match against
+    # @return [MatchData, Mustermann::SimpleMatch, nil] MatchData or similar object if the pattern matches.
+    # @see #peek_params
+    def peek_match(string)
+      matched = peek(string)
+      match(matched) if matched
+    end
+
+    # Tries to match the pattern against the beginning of the string (as opposed to the full string).
+    # Will return a two element Array with the params parsed from the substring as first entry and the length of
+    # the substring as second.
+    #
+    # @example
+    #   pattern   = Mustermann.new('/:name')
+    #   params, _ = pattern.peek_params("/Frank/Sinatra")
+    #
+    #   puts "Hello, #{params['name']}!" # Hello, Frank!
+    #
+    # @param [String] string The string to match against
+    # @return [Array<Hash, Integer>, nil] Array with params hash and length of substing if matched, nil otherwise
+    def peek_params(string)
+      match = peek_match(string)
+      [params(captures: match), match.to_s.size] if match
+    end
+
+    # @return [Hash{String: Array<Integer>}] capture names mapped to capture index.
     # @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.
+    # @return [Array<String>] capture names.
     # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-names Regexp#names
     def names
       []
@@ -129,20 +197,122 @@ module Mustermann
     #     warn "does not support expanding"
     #   end
     #
-    # @param [Hash{Symbol: #to_s, Array<#to_s>}] values values to use for expansion
+    # Expanding is supported by almost all patterns (notable execptions are {Mustermann::Shell},
+    # {Mustermann::Regular} and {Mustermann::Simple}).
+    #
+    # Union {Mustermann::Composite} patterns (with the | operator) support expanding if all
+    # patterns they are composed of also support it.
+    #
+    # @param (see Mustermann::Expander#expand)
     # @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)
+    def expand(behavior = nil, values = {})
       raise NotImplementedError, "expanding not supported by #{self.class}"
     end
 
+    # @note This method is only implemented by certain subclasses.
+    #
+    # Generates a list of URI template strings representing the pattern.
+    #
+    # Note that this transformation is lossy and the strings matching these
+    # templates might not match the pattern (and vice versa).
+    #
+    # This comes in quite handy since URI templates are not made for pattern matching.
+    # That way you can easily use a more precise template syntax and have it automatically
+    # generate hypermedia links for you.
+    #
+    # @example generating templates
+    #   Mustermann.new("/:name").to_templates                   # => ["/{name}"]
+    #   Mustermann.new("/:foo(@:bar)?/*baz").to_templates       # => ["/{foo}@{bar}/{+baz}", "/{foo}/{+baz}"]
+    #   Mustermann.new("/{name}", type: :template).to_templates # => ["/{name}"]
+    #
+    # @example generating templates from composite patterns
+    #   pattern  = Mustermann.new('/:name')
+    #   pattern |= Mustermann.new('/{name}', type: :template)
+    #   pattern |= Mustermann.new('/example/*nested')
+    #   pattern.to_templates # => ["/{name}", "/example/{+nested}"]
+    #
+    # Template generation is supported by almost all patterns (notable execptions are
+    # {Mustermann::Shell}, {Mustermann::Regular} and {Mustermann::Simple}).
+    # Union {Mustermann::Composite} patterns (with the | operator) support template generation
+    # if all patterns they are composed of also support it.
+    #
+    # @example Checking if a pattern supports expanding
+    #   if pattern.respond_to? :to_templates
+    #     pattern.to_templates
+    #   else
+    #     warn "does not support template generation"
+    #   end
+    #
+    # @return [Array<String>] list of URI templates
+    def to_templates
+      raise NotImplementedError, "template generation not supported by #{self.class}"
+    end
+
+    # @overload |(other)
+    #   Creates a pattern that matches any string matching either one of the patterns.
+    #   If a string is supplied, it is treated as an identity pattern.
+    #
+    #   @example
+    #     pattern = Mustermann.new('/foo/:name') | Mustermann.new('/:first/:second')
+    #     pattern === '/foo/bar' # => true
+    #     pattern === '/fox/bar' # => true
+    #     pattern === '/foo'     # => false
+    #
+    # @overload &(other)
+    #   Creates a pattern that matches any string matching both of the patterns.
+    #   If a string is supplied, it is treated as an identity pattern.
+    #
+    #   @example
+    #     pattern = Mustermann.new('/foo/:name') & Mustermann.new('/:first/:second')
+    #     pattern === '/foo/bar' # => true
+    #     pattern === '/fox/bar' # => false
+    #     pattern === '/foo'     # => false
+    #
+    # @overload ^(other)
+    #   Creates a pattern that matches any string matching exactly one of the patterns.
+    #   If a string is supplied, it is treated as an identity pattern.
+    #
+    #   @example
+    #     pattern = Mustermann.new('/foo/:name') ^ Mustermann.new('/:first/:second')
+    #     pattern === '/foo/bar' # => false
+    #     pattern === '/fox/bar' # => true
+    #     pattern === '/foo'     # => false
+    #
+    # @param [Mustermann::Pattern, String] other the other pattern
+    # @return [Mustermann::Pattern] a composite pattern
+    def |(other)
+      Mustermann.new(self, other, operator: __callee__, type: :identity)
+    end
+
+    alias_method :&, :|
+    alias_method :^, :|
+
+    # @example
+    #   pattern = Mustermann.new('/:a/:b')
+    #   strings = ["foo/bar", "/foo/bar", "/foo/bar/"]
+    #   strings.detect(&pattern) # => "/foo/bar"
+    #
+    # @return [Proc] proc wrapping {#===}
+    def to_proc
+      @to_proc ||= method(:===).to_proc
+    end
+
     # @!visibility private
     # @return [Boolean]
     # @see Object#respond_to?
     def respond_to?(method, *args)
-      method.to_s == 'expand' ? false : super
+      return super unless %i[expand to_templates].include? method
+      respond_to_special?(method)
+    end
+
+    # @!visibility private
+    # @return [Boolean]
+    # @see #respond_to?
+    def respond_to_special?(method)
+      method(method).owner != Mustermann::Pattern
     end
 
     # @!visibility private
@@ -150,6 +320,12 @@ module Mustermann
       "#<%p:%p>" % [self.class, @string]
     end
 
+    # @!visibility private
+    def simple_inspect
+      type = self.class.name[/[^:]+$/].downcase
+      "%s:%p" % [type, @string]
+    end
+
     # @!visibility private
     def map_param(key, value)
       unescape(value, true)
@@ -158,8 +334,7 @@ module Mustermann
     # @!visibility private
     def unescape(string, decode = @uri_decode)
       return string unless decode and string
-      @uri ||= URI::Parser.new
-      @uri.unescape(string)
+      @@uri.unescape(string)
     end
 
     # @!visibility private
@@ -170,7 +345,7 @@ module Mustermann
       ALWAYS_ARRAY.include? key
     end
 
-    private :unescape, :map_param
+    private :unescape, :map_param, :respond_to_special?
     private_constant :ALWAYS_ARRAY
   end
 end