mustermann 0.4.0 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7452f3272ea2fe09869f438b2cef90dcba6bf4b
-  data.tar.gz: 5d79d32db97549662b82ef1b589d6d35f1f9df80
+  metadata.gz: 90d5c978f69743fdbee3eec3efc6bc6c05a83dfb
+  data.tar.gz: e777bda67af6ff598fc5a584ae786fa78eb68c4b
 SHA512:
-  metadata.gz: 22ad9c7d0bfb6ae62a339cbfbe2581a91a9f860e4ba2f035ea26157ec0e31e16125d9f159561f43f821e2a07f239eda9e3df318ef3c29d63296a9107bcf65265
-  data.tar.gz: 5394bb963e310669de6e569b06bc690f90060dded1ecbb991d9307c904f5dcb4d6a1c39da7683be8e79eec4782ec28502c716ae9bc528c4221ea7ae0e708434a
+  metadata.gz: 2b92c4b696adefa6c6c0ce16fc6a3ef7a3e85834e9579dbc8a7108fc535888da5dc907f39c087fac8abf5b26a387b81e85c7c45f161b691e40f9709e382df07b
+  data.tar.gz: fe32e08661344ce33c9066610e6d1591999fb62210597714e1f406b2161e4e517438d5c026fe801b84a262ec97cdbc76e471ecffae233275888aa4d1f6139814

data/README.md

@@ -27,7 +27,7 @@ pattern.params('/a/b.c') # => { "prefix" => "a", splat => ["b", "c"] }
 
 * **[Pattern Types](#-pattern-types):** Mustermann supports a wide variety of different pattern types, making it compatible with a large variety of existing software.
 * **[Fine Grained Control](#-available-options):** You can easily adjust matching behavior and add constraints to the placeholders and capture groups.
-* **[Binary Operators](#-binary-operators):** Patterns can be combined into composite patterns using binary operators.
+* **[Binary Operators](#-binary-operators) and [Concatenation](#-concatenation):** Patterns can be combined into composite patterns using binary operators.
 * **[Regexp Look Alike](#-regexp-look-alike):** Mustermann patterns can be used as a replacement for regular expressions.
 * **[Parameter Parsing](#-parameter-parsing):** Mustermann can parse matched parameters into a Sinatra-style "params" hash, including type casting.
 * **[Peeking](#-peeking):** Lets you check if the beginning of a string matches a pattern.
@@ -42,7 +42,6 @@ pattern.params('/a/b.c') # => { "prefix" => "a", splat => ["b", "c"] }
 These features are included in the library, but not loaded by default
 
 * **[Mapper](#-mapper):** A simple tool for mapping one string to another based on patterns.
-* **[Routers](#-routers):** Model execution flow based on pattern matching. Comes with a simple Rack router.
 * **[Sinatra Integration](#-sinatra-integration):** Mustermann can be used as a [Sinatra](http://www.sinatrarb.com/) extension. Sinatra 2.0 and beyond will use Mustermann by default.
 
 <a name="-pattern-types"></a>
@@ -95,6 +94,22 @@ first ^ second === "/foo/bar" # => false
 
 These resulting objects are fully functional pattern objects, allowing you to call methods like `params` or `to_proc` on them. Moreover, *or* patterns created solely from expandable patterns will also be expandable. The same logic also applies to generating templates from *or* patterns.
 
+<a name="-concatenation"></a>
+## Concatenation
+
+Similar to [Binary Operators](#-binary-operators), two patterns can be concatenated using `+`.
+
+``` ruby
+require 'mustermann'
+
+prefix = Mustermann.new("/:prefix")
+about  = prefix + "/about"
+
+about.params("/main/about") # => {"prefix" => "main"}
+```
+
+Patterns of different types can be mixed. The availability of `to_templates` and `expand` depends on the patterns being concatenated.
+
 <a name="-regexp-look-alike"></a>
 ## Regexp Look Alike
 
@@ -285,7 +300,40 @@ pattern.expand(:append, slug: "foo", value: "bar") # => "/foo?value=bar"
 <a name="-generating-templates"></a>
 ## Generating Templates
 
-... TODO ...
+You can generate a list of URI templates that correspond to a Mustermann pattern (it is a list rather than a single template, as most pattern types are significantly more expressive than URI templates).
+
+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.
+
+Template generation is supported by almost all patterns (notable exceptions are `shell`, `regexp` and `simple` patterns).
+
+``` ruby
+require 'mustermann'
+
+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}"
+```
+
+Union Composite patterns (with the | operator) support template generation if all patterns they are composed of also support it.
+
+``` ruby
+require 'mustermann'
+
+pattern  = Mustermann.new('/:name')
+pattern |= Mustermann.new('/{name}', type: :template)
+pattern |= Mustermann.new('/example/*nested')
+pattern.to_templates # => ["/{name}", "/example/{+nested}"]
+```
+
+If accepting arbitrary patterns, you can and should use `respond_to?` to check feature availability.
+
+``` ruby
+if pattern.respond_to? :to_templates
+  pattern.to_templates
+else
+  warn "does not support template generation"
+end
+```
 
 <a name="-proc-look-alike"></a>
 ## Proc Look Alike
@@ -326,47 +374,6 @@ mapper['/foo.xml'] # => "/foo/view.xml"
 mapper['/foo/bar'] # => "/foo/bar"
 ```
 
-<a name="-routers"></a>
-## Routers
-
-Mustermann comes with basic router implementations that will call certain callbacks depending on the input.
-
-### Simple Router
-
-The simple router chooses callbacks based on an input string.
-
-``` ruby
-require 'mustermann/router/simple'
-
-router = Mustermann::Router::Simple.new(default: 42)
-router.on(':name', capture: :digit) { |string| string.to_i }
-router.call("23")      # => 23
-router.call("example") # => 42
-```
-
-### Rack Router
-
-This is not a full replacement for Rails, Sinatra, Cuba, etc, as it only cares about path based routing.
-
-``` ruby
-require 'mustermann/router/rack'
-
-router = Mustermann::Router::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
-```
 <a name="-sinatra-integration"></a>
 ## Sinatra Integration
 
@@ -747,7 +754,15 @@ This comes with a few trade-offs:
 
 **Supported options:**
 [`uri_decode`](#-available-options--uri_decode),
-[`ignore_unknown_options`](#-available-options--ignore_unknown_options).
+[`ignore_unknown_options`](#-available-options--ignore_unknown_options), `check_anchors`.
+
+The pattern string (or actual Regexp instance) should not contain anchors (`^` outside of square brackets, `$`, `\A`, `\z`, or `\Z`).
+Anchors will be injected where necessary by Mustermann.
+
+By default, Mustermann will raise a `Mustermann::CompileError` if an anchor is encountered.
+If you still want it to contain anchors at your own risk, set the `check_anchors` option to `false`.
+
+Using anchors will break [peeking](#-peeking) and [concatenation](#-concatenation).
 
 <table>
   <thead>
@@ -811,7 +826,7 @@ This comes with a few trade-offs:
       </td>
     </tr>
     <tr>
-      <td><b>(</b><i>expression</i><b>|</b><i>expression</i><b>|</b><i>...</i><b>)</b></td>
+      <td><i>expression</i><b>|</b><i>expression</i><b>|</b><i>...</i></td>
       <td>
         Will match anything matching the nested expressions. May contain any other syntax element, including captures.
       </td>

data/lib/mustermann.rb

@@ -1,5 +1,6 @@
 require 'mustermann/pattern'
 require 'mustermann/composite'
+require 'mustermann/concat'
 require 'thread'
 
 # Namespace and main entry point for the Mustermann library.
@@ -57,7 +58,7 @@ module Mustermann
   # @raise (see Mustermann::Pattern.new)
   # @raise [TypeError] if the passed object cannot be converted to a pattern
   # @see file:README.md#Types_and_Options "Types and Options" in the README
-  def self.new(*input, type: DEFAULT_TYPE, **options)
+  def self.new(*input, type: DEFAULT_TYPE, operator: :|, **options)
     type ||= DEFAULT_TYPE
     input  = input.first if input.size < 2
     case input
@@ -65,7 +66,7 @@ module Mustermann
     when Regexp  then self[:regexp].new(input, **options)
     when String  then self[type].new(input, **options)
     when Symbol  then self[:sinatra].new(input.inspect, **options)
-    when Array   then Composite.new(input, type: type, **options)
+    when Array   then input.map { |i| new(i, type: type, **options) }.inject(operator)
     else
       pattern = input.to_pattern(type: type, **options) if input.respond_to? :to_pattern
       raise TypeError, "#{input.class} can't be coerced into Mustermann::Pattern" if pattern.nil?

data/lib/mustermann/ast/compiler.rb

@@ -84,6 +84,8 @@ module Mustermann
         # @!visibility private
         def translate(**options)
           return super(**options) if explode or not options[:parametric]
+          # Remove this line after fixing broken compatibility between 2.1 and 2.2
+          options.delete(:parametric) if options.has_key?(:parametric)
           parametric super(parametric: false, **options)
         end
 

data/lib/mustermann/ast/node.rb

@@ -152,6 +152,10 @@ module Mustermann
       class Optional < Node
       end
 
+      # @!visibility private
+      class Or < Node
+      end
+
       # @!visibility private
       class Root < Node
         # @!visibility private

data/lib/mustermann/ast/parser.rb

@@ -124,25 +124,8 @@ module Mustermann
       # @return [String, MatchData, nil]
       # @!visibility private
       def scan(regexp)
-        match_buffer(:scan, regexp)
-      end
-
-      # Wrapper around {StringScanner#check} that turns strings into escaped
-      # regular expressions and returns a MatchData if the regexp has any
-      # named captures.
-      #
-      # @param [Regexp, String] regexp
-      # @see StringScanner#check
-      # @return [String, MatchData, nil]
-      # @!visibility private
-      def check(regexp)
-        match_buffer(:check, regexp)
-      end
-
-      # @!visibility private
-      def match_buffer(method, regexp)
         regexp = Regexp.new(Regexp.escape(regexp)) unless regexp.is_a? Regexp
-        string = buffer.public_send(method, regexp)
+        string = buffer.scan(regexp)
         regexp.names.any? ? regexp.match(string) : string
       end
 
@@ -245,10 +228,6 @@ module Mustermann
         char = "space" if char == " "
         raise exception, "unexpected #{char || "end of string"} while parsing #{string.inspect}"
       end
-
-      private :match_buffer
     end
-
-    private_constant :Parser
   end
 end

data/lib/mustermann/ast/pattern.rb

@@ -7,7 +7,7 @@ require 'mustermann/ast/template_generator'
 require 'mustermann/ast/param_scanner'
 require 'mustermann/regexp_based'
 require 'mustermann/expander'
-require 'tool/equality_map'
+require 'mustermann/equality_map'
 
 module Mustermann
   # @see Mustermann::AST::Pattern
@@ -86,7 +86,7 @@ module Mustermann
       # Internal AST representation of pattern.
       # @!visibility private
       def to_ast
-        @ast_cache ||= Tool::EqualityMap.new
+        @ast_cache ||= EqualityMap.new
         @ast_cache.fetch(@string) do
           ast   = parse(@string, pattern: self)
           ast &&= transform(ast)
@@ -133,4 +133,4 @@ module Mustermann
       private :compile, :parse, :transform, :validate, :generate_templates, :param_converters, :scan_params, :set_boundaries
     end
   end
-end
+end

data/lib/mustermann/ast/transformer.rb

@@ -15,10 +15,59 @@ module Mustermann
         new.translate(tree)
       end
 
-      translate(:node) { self }
-      translate(:group, :root) do
-        self.payload = t(payload)
-        self
+      # recursive descent
+      translate(:node) do
+        node.payload = t(payload)
+        node
+      end
+
+      # ignore unknown objects on the tree
+      translate(Object) { node }
+
+      # turn a group containing or nodes into a union
+      # @!visibility private
+      class GroupTransformer < NodeTranslator
+        register :group
+
+        # @!visibility private
+        def translate
+          payload.flatten! if payload.is_a?(Array)
+          return union if payload.any? { |e| e.is_a? :or }
+          self.payload = t(payload)
+          self
+        end
+
+        # @!visibility private
+        def union
+          groups = split_payload.map { |g| group(g) }
+          Node[:union].new(groups, start: node.start, stop: node.stop)
+        end
+
+        # @!visibility private
+        def group(elements)
+          return t(elements.first) if elements.size == 1
+          start, stop = elements.first.start, elements.last.stop if elements.any?
+          Node[:group].new(t(elements), start: start, stop: stop)
+        end
+
+        # @!visibility private
+        def split_payload
+          groups = [[]]
+          payload.each { |e| e.is_a?(:or) ? groups << [] : groups.last << e }
+          groups.map!
+        end
+      end
+
+      # inject a union node right inside the root node if it contains or nodes
+      # @!visibility private
+      class RootTransformer < GroupTransformer
+        register :root
+
+        # @!visibility private
+        def union
+          self.payload = [super]
+          self
+        end
       end
 
       # URI expression transformations depending on operator

data/lib/mustermann/caster.rb

@@ -22,6 +22,7 @@ module Mustermann
     # @param [Array<Symbol, Regexp, #cast, #===>] types identifier for cast type (some need block)
     # @!visibility private
     def register(*types, &block)
+      return if types.empty? and block.nil?
       types << Any.new(&block) if types.empty?
       types.each { |type| self << caster_for(type, &block) }
     end
@@ -41,6 +42,7 @@ module Mustermann
     # @return [Hash] post-transform Hash
     # @!visibility private
     def cast(hash)
+      return hash if empty?
       merge = {}
       hash.delete_if do |key, value|
         next unless casted = lazy.map { |e| e.cast(key, value) }.detect { |e| e }
@@ -50,16 +52,6 @@ module Mustermann
       hash.update(merge)
     end
 
-    # Specific cast for remove nil values.
-    # @!visibility private
-    module Nil
-      # @see Mustermann::Caster#cast
-      # @!visibility private
-      def self.cast(key, value)
-        {} if value.nil?
-      end
-    end
-
     # Class for block based casts that are triggered for every key/value pair.
     # @!visibility private
     class Any

data/lib/mustermann/composite.rb

@@ -8,9 +8,9 @@ module Mustermann
     supported_options :operator, :type
 
     # @see Mustermann::Pattern.supported?
-    def self.supported?(option, **options)
+    def self.supported?(option, type: nil, **options)
       return true if super
-      options[:type] and Mustermann[options[:type]].supported?(option, **options)
+      Mustermann[type || Mustermann::DEFAULT_TYPE].supported?(option, **options)
     end
 
     # @return [Mustermann::Pattern] a new composite pattern
@@ -33,6 +33,16 @@ module Mustermann
       patterns == patterns_from(pattern)
     end
 
+    # @see Mustermann::Pattern#eql?
+    def eql?(pattern)
+      patterns.eql? patterns_from(pattern)
+    end
+
+    # @see Mustermann::Pattern#hash
+    def hash
+      patterns.hash | operator.hash
+    end
+
     # @see Mustermann::Pattern#===
     def ===(string)
       patterns.map { |p| p === string }.inject(operator)
@@ -61,7 +71,7 @@ module Mustermann
       @expander.expand(behavior, values)
     end
 
-    # (see Mustermann::Pattern#expand)
+    # (see Mustermann::Pattern#to_templates)
     def to_templates
       raise NotImplementedError, 'template generation not supported' unless respond_to? :to_templates
       patterns.flat_map(&:to_templates).uniq

data/lib/mustermann/concat.rb

@@ -0,0 +1,124 @@
+module Mustermann
+  # Class for pattern objects that are a concatenation of other patterns.
+  # @see Mustermann::Pattern#+
+  class Concat < Composite
+    # Mixin for patterns to support native concatenation.
+    # @!visibility private
+    module Native
+      # @see Mustermann::Pattern#+
+      # @!visibility private
+      def +(other)
+        other &&= Mustermann.new(other, type: :identity, **options)
+        return super unless native = native_concat(other)
+        self.class.new(native, **options)
+      end
+
+      # @!visibility private
+      def native_concat(other)
+        "#{self}#{other}" if native_concat?(other)
+      end
+
+      # @!visibility private
+      def native_concat?(other)
+        other.class == self.class and other.options == options
+      end
+
+      private :native_concat, :native_concat?
+    end
+
+    # Should not be used directly.
+    # @!visibility private
+    def initialize(*)
+      super
+      AST::Validation.validate(combined_ast) if respond_to? :expand
+    end
+
+    # @see Mustermann::Composite#operator
+    # @return [Symbol] always :+
+    def operator
+      :+
+    end
+
+    # @see Mustermann::Pattern#===
+    def ===(string)
+      peek_size(string) == string.size
+    end
+
+    # @see Mustermann::Pattern#match
+    def match(string)
+      peeked = peek_match(string)
+      peeked if peeked.to_s == string
+    end
+
+    # @see Mustermann::Pattern#params
+    def params(string)
+      params, size = peek_params(string)
+      params if size == string.size
+    end
+
+    # @see Mustermann::Pattern#peek_size
+    def peek_size(string)
+      pump(string) { |p,s| p.peek_size(s) }
+    end
+
+    # @see Mustermann::Pattern#peek_match
+    def peek_match(string)
+      pump(string, initial: SimpleMatch.new) do |pattern, substring|
+        return unless match = pattern.peek_match(substring)
+        [match, match.to_s.size]
+      end
+    end
+
+    # @see Mustermann::Pattern#peek_params
+    def peek_params(string)
+      pump(string, inject_with: :merge, with_size: true) { |p, s| p.peek_params(s) }
+    end
+
+    # (see Mustermann::Pattern#expand)
+    def expand(behavior = nil, values = {})
+      raise NotImplementedError, 'expanding not supported' unless respond_to? :expand
+      @expander ||= Mustermann::Expander.new(self) { combined_ast }
+      @expander.expand(behavior, values)
+    end
+
+    # (see Mustermann::Pattern#to_templates)
+    def to_templates
+      raise NotImplementedError, 'template generation not supported' unless respond_to? :to_templates
+      @to_templates ||= patterns.inject(['']) { |list, pattern| list.product(pattern.to_templates).map(&:join) }.uniq
+    end
+
+    # @!visibility private
+    def respond_to_special?(method)
+      method = :to_ast if method.to_sym == :expand
+      patterns.all? { |p| p.respond_to?(method) }
+    end
+
+    # used to generate results for various methods by scanning through an input string
+    # @!visibility private
+    def pump(string, inject_with: :+, initial: nil, with_size: false)
+      substring = string
+      results   = Array(initial)
+
+      patterns.each do |pattern|
+        result, size = yield(pattern, substring)
+        return unless result
+        results << result
+        size    ||= result
+        substring = substring[size..-1]
+      end
+
+      results = results.inject(inject_with)
+      with_size ? [results, string.size - substring.size] : results
+    end
+
+    # generates one big AST from all patterns
+    # will not check if patterns support AST generation
+    # @!visibility private
+    def combined_ast
+      payload = patterns.map { |p| AST::Node[:group].new(p.to_ast.payload) }
+      AST::Node[:root].new(payload)
+    end
+
+    private :combined_ast, :pump
+  end
+end