mustermann 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b65ce2df601cc3924de9e697d1cde09019b4185
-  data.tar.gz: f562a51c35fdcb064b2901ccfcffe87ee6417be5
+  metadata.gz: c4814f10c7f9b66968a8eaadb89f2eeacb328096
+  data.tar.gz: 69ae8b9fd3dfd3d50f0301ae10e05f168c98e5fe
 SHA512:
-  metadata.gz: 700b01ee1c08b312d6914d386e0c3abcda85d4c630ef4c1393e57730d85f5e9debe3ce15c7f28670f51cedf2247e1e2ac6dff72d592ca1f009962fcc30a4248a
-  data.tar.gz: 85b14c218fedd69b702fa45cefdad5f54bfe87d3eb13d8c74b717caee1e219ef64252524e2ca608b1b044447ed746b049f5a48e534612ee40ef0fa503d9c8f33
+  metadata.gz: 44ad20b4f6e4324732e3d6734438b4400aacbab936fedb197aee75dcd9d9522797e1c1244ff86ebc78d7855e84b8b53e440acaa9785c13e7a2c33170850b0fba
+  data.tar.gz: c8b2bf771c04af78b64045fe61c6188cba366472242f72286802ea7737f60d8fb0728cc946fbaadad07e1502a829f7bb94b815d7501c1b5e808bf5559eb1e360

data/.travis.yml

@@ -1,7 +1,10 @@
 rvm:
-  - 2.0.0
-#  - ruby-head
-#  - jruby-head
-#matrix:
-#  allow_failures:
-#    - rvm: jruby-head
+- 2.0.0
+- 2.1.0-preview1
+- ruby-head
+- jruby-head
+- rbx-2.0.0
+matrix:
+  allow_failures:
+  - rvm: jruby-head
+  - rvm: rbx-2.0.0

data/README.md

@@ -1,6 +1,11 @@
 # The Amazing Mustermann
 
-[![Build Status](https://travis-ci.org/rkh/mustermann.png?branch=master)](https://travis-ci.org/rkh/mustermann) [![Coverage Status](https://coveralls.io/repos/rkh/mustermann/badge.png?branch=master)](https://coveralls.io/r/rkh/mustermann) [![Code Climate](https://codeclimate.com/github/rkh/mustermann.png)](https://codeclimate.com/github/rkh/mustermann) [![Dependency Status](https://gemnasium.com/rkh/mustermann.png)](https://gemnasium.com/rkh/mustermann) [![Gem Version](https://badge.fury.io/rb/mustermann.png)](http://badge.fury.io/rb/mustermann)
+[![Build Status](https://travis-ci.org/rkh/mustermann.svg?branch=master)](https://travis-ci.org/rkh/mustermann) [![Coverage Status](http://img.shields.io/coveralls/rkh/mustermann.svg?branch=master)](https://coveralls.io/r/rkh/mustermann) [![Code Climate](http://img.shields.io/codeclimate/github/rkh/mustermann.svg)](https://codeclimate.com/github/rkh/mustermann) [![Dependency Status](https://gemnasium.com/rkh/mustermann.svg)](https://gemnasium.com/rkh/mustermann) [![Gem Version](http://img.shields.io/gem/v/mustermann.svg)](https://rubygems.org/gems/mustermann)
+[![Inline docs](http://inch-ci.org/github/rkh/mustermann.svg)](http://inch-ci.org/github/rkh/mustermann)
+[![Documentation](http://img.shields.io/:yard-docs-38c800.svg)](http://rubydoc.info/gems/mustermann/frames)
+[![License](http://img.shields.io/:license-MIT-38c800.svg)](http://rkh.mit-license.org)
+[![Badges](http://img.shields.io/:badges-9/9-38c800.svg)](http://img.shields.io) 
+
 
 *Make sure you view the correct docs: [latest release](http://rubydoc.info/gems/mustermann/frames), [master](http://rubydoc.info/github/rkh/mustermann/master/frames).*
 
@@ -82,6 +87,16 @@ The available types are:
         <a href="#pattern_expanding">Expanding</a>
       </td>
     </tr>
+    <tr>
+      <th><a href="#regexp"><tt>regexp</tt></a></th>
+      <td>Regular expressions as implemented by Ruby</td>
+      <td><tt>/(?&lt;slug&gt;.*)</tt></td>
+      <td>
+        <a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
+        <a href="#uri_decode"><tt>uri_decode</tt></a>
+      </td>
+      <td></td>
+    </tr>
     <tr>
       <th><a href="#shell"><tt>shell</tt></th>
       <td>Unix style patterns</td>
@@ -346,6 +361,50 @@ expander = Mustermann::Expander.new("/:slug", additional_values: :append)
 expander.expand(slug: "foo", value: "bar") # => "/foo?value=bar"
 ```
 
+## Duck Typing
+
+All methods converting string input to pattern objects will also accept any arbitrary object that implements `to_pattern`:
+
+``` ruby
+require 'mustermann'
+
+class MyObject
+  def to_pattern(**options)
+    Mustermann.new("/foo", **options)
+  end
+end
+
+object = MyObject.new
+Mustermann.new(object, type: :rails) # => #<Mustermann::Rails:"/foo">
+```
+
+It might also be that you want to call `to_pattern` yourself instead of `Mustermann.new`. You can load `mustermann/to_pattern` to implement this method for strings, regular expressions and pattern objects:
+
+``` ruby
+require 'mustermann/to_pattern'
+
+"/foo".to_pattern               # => #<Mustermann::Sinatra:"/foo">
+"/foo".to_pattern(type: :rails) # => #<Mustermann::Rails:"/foo">
+%r{/foo}.to_pattern             # => #<Mustermann::Regular:"\\/foo">
+"/foo".to_pattern.to_pattern    # => #<Mustermann::Sinatra:"/foo">
+```
+
+You can also use the `Mustermann::ToPattern` mixin to easily add `to_pattern` to your own objects:
+
+``` ruby
+require 'mustermann/to_pattern'
+
+class MyObject
+  include Mustermann::ToPattern
+
+  def to_s
+    "/foo"
+  end
+end
+
+MyObject.new.to_pattern # => #<Mustermann::Sinatra:"/foo">
+```
+
 ## Partial Loading and Thread Safety
 
 Pattern objects are generally assumed to be thread-safe. You can easily match strings against the same pattern object concurrently.
@@ -481,7 +540,17 @@ By setting `ignore_unknown_options` to `true`, it will happily ignore the option
 
 ### `identity`
 
-Patterns that are no real patterns, just string matching.
+Identity patterns are strings that have to match the input exactly.
+
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/:example', type: :identity)
+pattern === "/foo.bar"      # => false
+pattern === "/:example"     # => true
+pattern.params("/foo.bar")  # => nil
+pattern.params("/:example") # => {}
+```
 
 <table>
   <thead>
@@ -502,6 +571,28 @@ Patterns that are no real patterns, just string matching.
 
 Patterns with the syntax used in Rails route definitions.
 
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/:example', type: :rails)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => false
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => nil
+
+pattern = Mustermann.new('/:example(/:optional)', type: :rails)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar", "optional" => nil   }
+pattern.params("/foo/bar") # => { "example" => "foo",     "optional" => "bar" }
+
+pattern = Mustermann.new('/*example', type: :rails)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => { "example" => "foo/bar" }
+```
+
 <table>
   <thead>
     <tr>
@@ -540,10 +631,64 @@ Patterns with the syntax used in Rails route definitions.
   </tbody>
 </table>
 
+### `regexp`
+
+Regular expression patterns, as used implemented by Ruby. Do not include characters for matching beginning or end of string/line.
+This pattern type is also known as `regular` and the pattern class is `Mustermann::Regular` (located in `mustermann/regular`).
+
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/(?<example>.*)', type: :regexp)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => { "example" => "foo/bar" }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Syntax Element</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><i>any string</i></td>
+      <td>Interpreted as regular expression.</td>
+    </tr>
+  </tbody>
+</table>
+
+It is also possible to turn a proper Regexp instance into a pattern object by passing it to `Mustermann.new`:
+
+``` ruby
+require 'mustermann'
+Mustermann.new(/(?<example>.*)/).params("input") # => { "example" => "input" }
+```
+
 ### `shell`
 
 Shell patterns, as used in Bash or with `Dir.glob`.
 
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/*', type: :shell)
+pattern === "/foo.bar" # => true
+pattern === "/foo/bar" # => false
+
+pattern = Mustermann.new('/**/*', type: :shell)
+pattern === "/foo.bar" # => true
+pattern === "/foo/bar" # => true
+
+pattern = Mustermann.new('/{foo,bar}', type: :shell)
+pattern === "/foo"     # => true
+pattern === "/bar"     # => true
+pattern === "/baz"     # => false
+```
+
 <table>
   <thead>
     <tr>
@@ -581,7 +726,29 @@ Shell patterns, as used in Bash or with `Dir.glob`.
 
 ### `simple`
 
-Patterns as used by Sinatra 1.3. Useful for porting an application that relies on this behavior to a later Sinatra version and to make sure [Sinatra 2.0](#sinatra) patterns do not decrease performance.
+Patterns as used by Sinatra 1.3. Useful for porting an application that relies on this behavior to a later Sinatra version and to make sure [Sinatra 2.0](#sinatra) patterns do not decrease performance. Simple patterns internally use the same code older Sinatra versions used for compiling the pattern. Error messages for broken patterns will therefore not be as informative as for other pattern implementations.
+
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/:example', type: :simple)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => false
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => nil
+
+pattern = Mustermann.new('/:example/?:optional?', type: :simple)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar", "optional" => nil   }
+pattern.params("/foo/bar") # => { "example" => "foo",     "optional" => "bar" }
+
+pattern = Mustermann.new('/*', type: :simple)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "splat" => ["foo.bar"] }
+pattern.params("/foo/bar") # => { "splat" => ["foo/bar"] }
+```
 
 <table>
   <thead>
@@ -629,6 +796,40 @@ Patterns as used by Sinatra 1.3. Useful for porting an application that relies o
 
 Sinatra 2.0 style patterns. The default used by Mustermann.
 
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/:example')
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => false
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => nil
+
+pattern = Mustermann.new('/\:example')
+pattern === "/foo.bar"      # => false
+pattern === "/:example"     # => true
+pattern.params("/foo.bar")  # => nil
+pattern.params("/:example") # => {}
+
+pattern = Mustermann.new('/:example(/:optional)?')
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar", "optional" => nil   }
+pattern.params("/foo/bar") # => { "example" => "foo",     "optional" => "bar" }
+
+pattern = Mustermann.new('/*')
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "splat" => ["foo.bar"] }
+pattern.params("/foo/bar") # => { "splat" => ["foo/bar"] }
+
+pattern = Mustermann.new('/*example')
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => true
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => { "example" => "foo/bar" }
+```
+
 <table>
   <thead>
     <tr>
@@ -644,6 +845,12 @@ Sinatra 2.0 style patterns. The default used by Mustermann.
         Capture behavior can be modified with <a href="#capture"><tt>capture</tt></a> and <a href="#greedy"><tt>greedy</tt></a> option.
       </td>
     </tr>
+    <tr>
+      <td><b>*</b><i>name</i></td>
+      <td>
+        Captures anything in a non-greedy fashion. Capture is named <i>name</i>.
+      </td>
+    </tr>
     <tr>
       <td><b>*</b></td>
       <td>
@@ -685,6 +892,19 @@ Parses fully expanded URI templates as specified by [RFC 6570](http://tools.ietf
 
 Note that it differs from URI templates in that it takes the unescaped version of special character instead of the escaped version.
 
+``` ruby
+require 'mustermann'
+
+pattern = Mustermann.new('/{example}', type: :template)
+pattern === "/foo.bar"     # => true
+pattern === "/foo/bar"     # => false
+pattern.params("/foo.bar") # => { "example" => "foo.bar" }
+pattern.params("/foo/bar") # => nil
+
+pattern = Mustermann.new("{/segments*}/{page}{.ext,cmpr:2}", type: :template)
+pattern.params("/a/b/c.tar.gz") # => {"segments"=>["a","b"], "page"=>"c", "ext"=>"tar", "cmpr"=>"gz"}
+```
+
 <table>
   <thead>
     <tr>
@@ -718,11 +938,6 @@ The operators `+` and `#` will always match non-greedy, whereas all other operat
 All modifiers and operators are supported. However, it does not parse lists as single values without the *explode* modifier (aka *star*).
 Parametric operators (`;`, `?` and `&`) currently only match parameters in given order.
 
-``` ruby
-pattern = Mustermann.new("{/segments*}/{page}{.ext,cmpr:2}", type: :template)
-pattern.params("/a/b/c.tar.gz") # => {"segments"=>["a","b"], "page"=>"c", "ext"=>"tar", "cmpr"=>"gz"}
-```
-
 Please keep the following in mind:
 
 > "Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables.  Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression.  In general, regular expression languages are better suited for variable matching."
@@ -733,6 +948,19 @@ you should set `uri_decode` to `false` in order to conform with the specificatio
 
 If you are looking for an alternative implementation that also supports expanding, check out [addressable](http://addressable.rubyforge.org/).
 
+## Mapper
+
+You can use a mapper to transform strings according to two or more mappings:
+
+``` ruby
+require 'mustermann/mapper'
+
+mapper = Mustermann::Mapper.new("/:page(.:format)?" => ["/:page/view.:format", "/:page/view.html"])
+mapper['/foo']     # => "/foo/view.html"
+mapper['/foo.xml'] # => "/foo/view.xml"
+mapper['/foo/bar'] # => "/foo/bar"
+```
+
 ## Routers
 
 Mustermann comes with basic router implementations that will call certain callbacks depending on the input.
@@ -757,7 +985,7 @@ This is not a full replacement for Rails, Sinatra, Cuba, etc, as it only cares a
 ``` ruby
 require 'mustermann/router/rack'
 
-router = Mustermann::Router::Rack do
+router = Mustermann::Router::Rack.new do
   on '/' do |env|
     [200, {'Content-Type' => 'text/plain'}, ['Hello World!']]
   end
@@ -795,6 +1023,16 @@ As there has been no stable release yet, the API might still change, though I co
 
 ### Development Releases
 
+* **Mustermann 0.3.0** (2014-08-18)
+    * More Infos:
+      [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.3.0),
+      [RubyDoc.info](http://rubydoc.info/gems/mustermann/0.3.0/frames),
+      [GitHub.com](https://github.com/rkh/mustermann/tree/v0.3.0)
+    * Add `regexp` pattern.
+    * Add named splats to Sinatra patterns.
+    * Add `Mustermann::Mapper`.
+    * Improve duck typing support.
+    * Improve documentation.
 * **Mustermann 0.2.0** (2013-08-24)
     * More Infos:
       [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.2.0),
@@ -832,6 +1070,5 @@ As there has been no stable release yet, the API might still change, though I co
 
 ### Upcoming Releases
 
-* **Mustermann 0.3.0** (next release with new features)
 * **Mustermann 1.0.0** (before Sinatra 2.0)
     * First stable release.

data/lib/mustermann.rb

@@ -1,15 +1,22 @@
+require 'mustermann/pattern'
+
 # Namespace and main entry point for the Mustermann library.
 #
 # Under normal circumstances the only external API entry point you should be using is {Mustermann.new}.
 module Mustermann
-  # @param [String] string The string representation of the new pattern
+  # @param [String, Pattern, Regexp, #to_pattern] input The representation of the new pattern
   # @param [Hash] options The options hash
   # @return [Mustermann::Pattern] pattern corresponding to string.
   # @raise (see [])
   # @raise (see Mustermann::Pattern.new)
   # @see file:README.md#Types_and_Options "Types and Options" in the README
-  def self.new(string, type: :sinatra, **options)
-    options.any? ? self[type].new(string, **options) : self[type].new(string)
+  def self.new(input, type: :sinatra, **options)
+    case input
+    when Pattern then input
+    when Regexp  then self[:regexp].new(input, **options)
+    when String  then self[type].new(input, **options)
+    else input.to_pattern(type: type, **options)
+    end
   end
 
   # Maps a type to its factory.
@@ -27,9 +34,9 @@ module Mustermann
   end
 
   # @!visibility private
-  def self.register(identifier = nil, constant = identifier.to_s.capitalize, load: "mustermann/#{identifier}")
+  def self.register(*identifiers, constant: identifiers.first.to_s.capitalize, load: "mustermann/#{identifiers.first}")
     @register ||= {}
-    @register[identifier] = [constant, load] if identifier
+    identifiers.each { |i| @register[i] = [constant, load] }
     @register
   end
 
@@ -42,6 +49,7 @@ module Mustermann
 
   register :identity
   register :rails
+  register :regular, :regexp
   register :shell
   register :simple
   register :sinatra

data/lib/mustermann/ast/expander.rb

@@ -59,10 +59,17 @@ module Mustermann
         @mappings ||= {}
       end
 
+      # all the known keys
+      # @!visibility private
+      def keys
+        @keys ||= []
+      end
+
       # add a tree for expansion
       # @!visibility private
       def add(ast)
         translate(ast).each do |keys, pattern, filter|
+          self.keys.concat(keys).uniq!
           mappings[keys.uniq.sort] ||= [keys, pattern, filter]
         end
       end
@@ -81,6 +88,14 @@ module Mustermann
         pattern % values.values_at(*keys)
       end
 
+      # @see Mustermann::Pattern#expandable?
+      # @!visibility private
+      def expandable?(values)
+        values = values.keys if values.respond_to? :keys
+        values = values.sort if values.respond_to? :sort
+        mappings.include? values
+      end
+
       # @see Mustermann::Expander#with_rest
       # @!visibility private
       def expandable_keys(keys)