mustermann 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a623efd27ea171ba18818550616788aeca18ded
-  data.tar.gz: f8e7956944902e37495c44085662cb39cedea8a9
+  metadata.gz: 6b65ce2df601cc3924de9e697d1cde09019b4185
+  data.tar.gz: f562a51c35fdcb064b2901ccfcffe87ee6417be5
 SHA512:
-  metadata.gz: f8e52f5e109283a3f6d9d2823b1410e3e41e3d8c3d3787e767c70fa8e7a018ff53738f994d856947c2473f8ef94c65eb56de79f51132aa729ca26a4d582ada2f
-  data.tar.gz: f3ff266371da60a7da88f492ad2ee3a46389a1a4806c2e57886f07b7b702408388ffaf3ff18175d59c1b67fdfafb2eb5a07d496ce8219cdccc3ae5fd90f06203
+  metadata.gz: 700b01ee1c08b312d6914d386e0c3abcda85d4c630ef4c1393e57730d85f5e9debe3ce15c7f28670f51cedf2247e1e2ac6dff72d592ca1f009962fcc30a4248a
+  data.tar.gz: 85b14c218fedd69b702fa45cefdad5f54bfe87d3eb13d8c74b717caee1e219ef64252524e2ca608b1b044447ed746b049f5a48e534612ee40ef0fa503d9c8f33

data/.travis.yml

@@ -1,6 +1,6 @@
 rvm:
   - 2.0.0
-  - ruby-head
+#  - ruby-head
 #  - jruby-head
 #matrix:
 #  allow_failures:

data/README.md

@@ -27,14 +27,6 @@ pattern = Mustermann.new('/:prefix/*.*')
 pattern.params('/a/b.c') # => { "prefix" => "a", splat => ["b", "c"] }
 ```
 
-Similarly, it is also possible to generate a string from a pattern by expanding it with such a hash:
-
-``` ruby
-pattern = Mustermann.new('/:file(.:ext)?')
-pattern.expand(file: 'pony')             # => "/pony"
-pattern.expand(file: 'pony', ext: 'jpg') # => "/pony.jpg"
-```
-
 It's generally a good idea to reuse pattern objects, since as much computation as possible is happening during object creation, so that the actual matching or expanding is quite fast.
 
 ## Types and Options
@@ -60,6 +52,7 @@ The available types are:
       <th>Description</th>
       <th>Example</th>
       <th>Available Options</th>
+      <th>Additional Features</th>
     </tr>
   </thead>
   <tbody>
@@ -71,6 +64,7 @@ The available types are:
         <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="#rails"><tt>rails</tt></a></th>
@@ -84,6 +78,9 @@ The available types are:
         <a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
         <a href="#uri_decode"><tt>uri_decode</tt></a>
       </td>
+      <td>
+        <a href="#pattern_expanding">Expanding</a>
+      </td>
     </tr>
     <tr>
       <th><a href="#shell"><tt>shell</tt></th>
@@ -93,6 +90,7 @@ The available types are:
         <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="#simple"><tt>simple</tt></a></th>
@@ -104,6 +102,7 @@ The available types are:
         <a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
         <a href="#uri_decode"><tt>uri_decode</tt></a>
       </td>
+      <td></td>
     </tr>
     <tr>
       <th><a href="#sinatra"><tt>sinatra</tt></a></th>
@@ -117,6 +116,9 @@ The available types are:
         <a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
         <a href="#uri_decode"><tt>uri_decode</tt></a>
       </td>
+      <td>
+        <a href="#pattern_expanding">Expanding</a>
+      </td>
     </tr>
     <tr>
       <th><a href="#template"><tt>template</tt></a></th>
@@ -130,6 +132,9 @@ The available types are:
         <a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
         <a href="#uri_decode"><tt>uri_decode</tt></a>
       </td>
+      <td>
+        <a href="#pattern_expanding">Expanding</a>
+      </td>
     </tr>
   </tbody>
 </table>
@@ -257,6 +262,89 @@ end
 * It would introduce breaking changes, even though these would be minor
 * Like Sinatra 2.0, Mustermann requires Ruby 2.0 or newer
 
+<a name="pattern_expanding"></a>
+## Expanding
+
+Similarly to parsing, it is also possible to generate a string from a pattern by expanding it with a hash.
+For simple expansions, you can use `Pattern#expand`.
+
+``` ruby
+pattern = Mustermann.new('/:file(.:ext)?')
+pattern.expand(file: 'pony')             # => "/pony"
+pattern.expand(file: 'pony', ext: 'jpg') # => "/pony.jpg"
+pattern.expand(ext: 'jpg')               # raises Mustermann::ExpandError
+```
+
+Expanding can be useful for instance when implementing link helpers.
+
+### Expander Objects
+
+To get fine-grained control over expansion, you can use `Mustermann::Expander` directly.
+
+You can create an expander object directly from a string:
+
+``` ruby
+require 'mustermann/expander'
+expander = Mustermann::Expander("/:file.jpg")
+expander.expand(file: 'pony') # => "/pony.jpg"
+
+expander = Mustermann::Expander(":file(.:ext)", type: :rails)
+expander.expand(file: 'pony', ext: 'jpg') # => "/pony.jpg"
+```
+
+Or you can pass it a pattern instance:
+
+``` ruby
+require 'mustermann'
+pattern = Mustermann.new("/:file")
+
+require 'mustermann/expander'
+expander = Mustermann::Expander.new(pattern)
+```
+
+### Expanding Multiple Patterns
+
+You can add patterns to an expander object via `<<`:
+
+``` ruby
+expander = Mustermann::Expander.new
+expander << "/users/:user_id"
+expander << "/pages/:page_id"
+
+expander.expand(user_id: 15) # => "/users/15"
+expander.expand(page_id: 58) # => "/pages/58"
+```
+
+You can set pattern options when creating the expander:
+
+``` ruby
+expander = Mustermann::Expander.new(type: :template)
+expander << "/users/{user_id}"
+expander << "/pages/{page_id}"
+```
+
+Additionally, it is possible to combine patterns of different types:
+
+``` ruby
+expander = Mustermann::Expander.new
+expander << Mustermann.new("/users/{user_id}", type: :template)
+expander << Mustermann.new("/pages/:page_id",  type: :rails)
+```
+
+### Handling Additional Values
+
+The handling of additional values passed in to `expand` can be changed by setting the `additional_values` option:
+
+``` ruby
+expander = Mustermann::Expander.new("/:slug", additional_values: :raise)
+expander.expand(slug: "foo", value: "bar") # raises Mustermann::ExpandError
+
+expander = Mustermann::Expander.new("/:slug", additional_values: :ignore)
+expander.expand(slug: "foo", value: "bar") # => "/foo"
+
+expander = Mustermann::Expander.new("/:slug", additional_values: :append)
+expander.expand(slug: "foo", value: "bar") # => "/foo?value=bar"
+```
 
 ## Partial Loading and Thread Safety
 
@@ -645,13 +733,56 @@ 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/).
 
+## 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 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
+```
+
 ## Requirements
 
 Mustermann has no dependencies besides a Ruby 2.0 compatible Ruby implementation.
 
 It is known to work on **MRI 2.0** and **MRI trunk**.
-**JRuby** is not yet supported, but is likely to follow soon (see [issue #2](https://github.com/rkh/mustermann/issues/2) for up to date information on JRuby).
-**Rubinius** is not yet able to parse the Mustermann source code.
+
+**JRuby** is not yet fully supported. It is possible to run large parts of Mustermann by passing in `--2.0 -X-C` starting from JRuby 1.7.4. See [issue #2](https://github.com/rkh/mustermann/issues/2) for up to date information.
+
+**Rubinius** is not yet able to parse the Mustermann source code. See [issue #14](https://github.com/rkh/mustermann/issues/14) for up to date information.
 
 ## Release History
 
@@ -664,13 +795,26 @@ As there has been no stable release yet, the API might still change, though I co
 
 ### Development Releases
 
-* **Mustermann 0.0.1** (2013-04-27)
+* **Mustermann 0.2.0** (2013-08-24)
     * More Infos:
-      [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.0.1),
-      [RubyDoc.info](rubydoc.info/gems/mustermann/0.0.1/frames),
-      [GitHub.com](https://github.com/rkh/mustermann/tree/v0.0.1)
-    * Initial Release.
+      [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.2.0),
+      [RubyDoc.info](http://rubydoc.info/gems/mustermann/0.2.0/frames),
+      [GitHub.com](https://github.com/rkh/mustermann/tree/v0.2.0)
+    * Add first class expander objects.
+    * Add params casting for expander.
+    * Add simple router and rack router.
+    * Add weak equality map to significantly improve performance.
+    * Fix Ruby warnings.
+    * Improve documentation.
+    * Refactor pattern validation, AST transformations.
+    * Increase test coverage (from 100%+ to 100%++).
+    * Improve JRuby compatibility.
+    * Work around bug in 2.0.0-p0.
 * **Mustermann 0.1.0** (2013-05-12)
+    * More Infos:
+      [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.1.0),
+      [RubyDoc.info](http://rubydoc.info/gems/mustermann/0.1.0/frames),
+      [GitHub.com](https://github.com/rkh/mustermann/tree/v0.1.0)
     * Add `Pattern#expand` for generating strings from patterns.
     * Add better internal API for working with the AST.
     * Improved documentation.
@@ -679,9 +823,15 @@ As there has been no stable release yet, the API might still change, though I co
     * Better handling of edge cases around extend.
     * More specs to ensure API stability.
     * Largely rework internals of Sinatra, Rails and Template patterns.
+* **Mustermann 0.0.1** (2013-04-27)
+    * More Infos:
+      [RubyGems.org](http://rubygems.org/gems/mustermann/versions/0.0.1),
+      [RubyDoc.info](http://rubydoc.info/gems/mustermann/0.0.1/frames),
+      [GitHub.com](https://github.com/rkh/mustermann/tree/v0.0.1)
+    * Initial Release.
 
 ### Upcoming Releases
 
-* **Mustermann 0.2.0** (next release with new features)
+* **Mustermann 0.3.0** (next release with new features)
 * **Mustermann 1.0.0** (before Sinatra 2.0)
     * First stable release.

data/Rakefile

@@ -1,4 +1,4 @@
-ENV['JRUBY_OPTS'] = '--2.0'
+ENV['JRUBY_OPTS'] = '--2.0 -X-C'
 ENV['RBXOPT'] = '-X20'
 
 task(:spec) { ruby '-w -S rspec' }

data/bench/capturing.rb

@@ -7,14 +7,14 @@ require 'addressable/template'
 
 
 Mustermann.register(:regexp, Class.new(Mustermann::RegexpBased) {
-  def compile(string, **options)
-    Regexp.new(string)
+  def compile(**options)
+    Regexp.new(@string)
   end
 }, load: false)
 
 Mustermann.register(:addressable, Class.new(Mustermann::RegexpBased) {
-  def compile(string, **options)
-    Addressable::Template.new(string)
+  def compile(**options)
+    Addressable::Template.new(@string)
   end
 }, load: false)
 

data/bench/regexp.rb

@@ -0,0 +1,21 @@
+require 'benchmark'
+
+puts " atomic vs normal segments ".center(52, '=')
+
+types = {
+  normal: /\A\/(?:a|%61)\/(?<b>[^\/\?#]+)(?:\/(?<c>[^\/\?#]+))?\Z/,
+  atomic: /\A\/(?:a|%61)\/(?<b>(?>[^\/\?#]+))(?:\/(?<c>(?>[^\/\?#]+)))?\Z/
+}
+
+Benchmark.bmbm do |x|
+  types.each do |name, regexp|
+    string = "/a/" << ?a * 10000 << "/" << ?a * 5000
+    fail unless regexp.match(string)
+    string << "/"
+    fail if regexp.match(string)
+
+    x.report name.to_s do
+      100.times { regexp.match(string) }
+    end
+  end
+end

data/lib/mustermann/ast/expander.rb

@@ -81,6 +81,12 @@ module Mustermann
         pattern % values.values_at(*keys)
       end
 
+      # @see Mustermann::Expander#with_rest
+      # @!visibility private
+      def expandable_keys(keys)
+        mappings.keys.select { |k| (k - keys).empty? }.max_by(&:size) || keys
+      end
+
       # helper method for raising an error for unexpandable values
       # @!visibility private
       def error_for(values)
@@ -91,17 +97,17 @@ module Mustermann
       # @see Mustermann::AST::Translator#expand
       # @!visibility private
       def escape(string, *args)
-        # URI::Parser is pretty slow, let's not had every string to it, even if it's uneccessary
+        # URI::Parser is pretty slow, let's not had every string to it, even if it's unnecessary
         string =~ /\A\w*\Z/ ? string : super
       end
 
-      # Turns a sprintf pattern into our secret internal data strucutre.
+      # Turns a sprintf pattern into our secret internal data structure.
       # @!visibility private
       def pattern(string = "", *keys, **filters)
         [[keys, string, filters]]
       end
 
-      # Creates the product of two of our secret internal data strucutres.
+      # Creates the product of two of our secret internal data structures.
       # @!visibility private
       def add_to(list, result)
         list << [[], ""] if list.empty?

data/lib/mustermann/ast/node.rb

@@ -107,7 +107,6 @@ module Mustermann
           root         = new
           root.pattern = string
           root.parse(&block)
-          #root.transform
           root
         end
       end

data/lib/mustermann/ast/parser.rb

@@ -9,7 +9,6 @@ module Mustermann
     # @!visibility private
     class Parser
       # @param [String] string to be parsed
-      # @param [Hash] **options parse options
       # @return [Mustermann::AST::Node] parse tree for string
       # @!visibility private
       def self.parse(string)
@@ -64,7 +63,7 @@ module Mustermann
         block ? type.parse(*args, &block) : type.new(*args)
       end
 
-      # Create a node for a character we don't have an explicite rule for.
+      # Create a node for a character we don't have an explicit rule for.
       #
       # @param [String] char the character
       # @return [Mustermann::AST::Node] the node
@@ -88,9 +87,9 @@ module Mustermann
       # @return [Mustermann::AST::Node] node with suffix
       # @!visibility private
       def read_suffix(element)
-        self.class.suffix.inject(element) do |element, (regexp, callback)|
-          next element unless payload = scan(regexp)
-          instance_exec(payload, element, &callback)
+        self.class.suffix.inject(element) do |ele, (regexp, callback)|
+          next ele unless payload = scan(regexp)
+          instance_exec(payload, ele, &callback)
         end
       end
 
@@ -122,7 +121,7 @@ module Mustermann
       # Helper for raising an exception for an unexpected character.
       # Will read character from buffer if buffer is passed in.
       #
-      # @param [String, nil] char the unexcpected character
+      # @param [String, nil] char the unexpected character
       # @raise [Mustermann::ParseError, Exception]
       # @!visibility private
       def unexpected(char = getch, exception: ParseError)

data/lib/mustermann/ast/pattern.rb

@@ -2,8 +2,10 @@ require 'mustermann/ast/parser'
 require 'mustermann/ast/compiler'
 require 'mustermann/ast/transformer'
 require 'mustermann/ast/validation'
-require 'mustermann/ast/expander'
+
 require 'mustermann/regexp_based'
+require 'mustermann/equality_map'
+require 'mustermann/expander'
 
 module Mustermann
   # @see Mustermann::AST::Pattern
@@ -15,14 +17,9 @@ module Mustermann
 
       extend Forwardable, SingleForwardable
       single_delegate on: :parser, suffix: :parser
-      instance_delegate %i[parser compiler transformer validation expander_class] => 'self.class'
+      instance_delegate %i[parser compiler transformer validation] => 'self.class'
       instance_delegate parse: :parser, transform: :transformer, validate: :validation
 
-      # @api private
-      # @return [#expand] expander object for pattern
-      # @!visibility private
-      attr_accessor :expander
-
       # @api private
       # @return [#parse] parser object for pattern
       # @!visibility private
@@ -53,25 +50,22 @@ module Mustermann
         Validation
       end
 
-      # @api private
-      # @return [#new] expander factory for pattern
       # @!visibility private
-      def self.expander_class
-        Expander
-      end
-
-      # @!visibility private
-      def compile(string, **options)
-        self.expander      = expander_class.new
+      def compile(**options)
         options[:except] &&= parse options[:except]
-        ast                = validate(transform(parse(string)))
-        expander.add(ast)
-        compiler.compile(ast, **options)
+        compiler.compile(to_ast, **options)
       rescue CompileError => error
-        error.message << ": %p" % string
+        error.message << ": %p" % @string
         raise error
       end
 
+      # Internal AST representation of pattern.
+      # @!visibility private
+      def to_ast
+        @ast_cache ||= EqualityMap.new
+        @ast_cache.fetch(@string) { validate(transform(parse(@string))) }
+      end
+
       # All AST-based pattern implementations support expanding.
       #
       # @example (see Mustermann::Pattern#expand)
@@ -79,8 +73,10 @@ module Mustermann
       # @return (see Mustermann::Pattern#expand)
       # @raise (see Mustermann::Pattern#expand)
       # @see Mustermann::Pattern#expand
+      # @see Mustermann::Expander
       def expand(**values)
-        expander.expand(**values)
+        @expander ||= Mustermann::Expander.new(self)
+        @expander.expand(**values)
       end
 
       private :compile