mustermann19 0.3.1

data/lib/mustermann/ast/translator.rb

@@ -0,0 +1,108 @@
+require 'mustermann/ast/node'
+require 'mustermann/error'
+require 'delegate'
+
+module Mustermann
+  module AST
+    # Implements translator pattern
+    #
+    # @abstract
+    # @!visibility private
+    class Translator
+      # Encapsulates a single node translation
+      # @!visibility private
+      class NodeTranslator < DelegateClass(Node)
+        # @param [Array<Symbol, Class>] types list of types to register for.
+        # @!visibility private
+        def self.register(*types)
+          types.each do |type|
+            type = Node.constant_name(type) if type.is_a? Symbol
+            translator.dispatch_table[type.to_s] = self
+          end
+        end
+
+        # @param node [Mustermann::AST::Node, Object]
+        # @param translator [Mustermann::AST::Translator]
+        #
+        # @!visibility private
+        def initialize(node, translator)
+          @translator = translator
+          super(node)
+        end
+
+        # @!visibility private
+        attr_reader :translator
+
+        # shorthand for translating a nested object
+        # @!visibility private
+        def t(*args, &block)
+          return translator unless args.any?
+          translator.translate(*args, &block)
+        end
+
+        # @!visibility private
+        alias_method :node, :__getobj__
+      end
+
+      # maps types to translations
+      # @!visibility private
+      def self.dispatch_table
+        @dispatch_table ||= {}
+      end
+
+      # some magic sauce so {NodeTranslator}s know whom to talk to for {#register}
+      # @!visibility private
+      def self.inherited(subclass)
+        node_translator = Class.new(NodeTranslator)
+        node_translator.define_singleton_method(:translator) { subclass }
+        subclass.const_set(:NodeTranslator, node_translator)
+        super
+      end
+
+      # DSL-ish method for specifying the exception class to use.
+      # @!visibility private
+      def self.raises(error)
+        define_method(:error_class) { error }
+      end
+
+      # DSL method for defining single method translations.
+      # @!visibility private
+      def self.translate(*types, &block)
+        Class.new(const_get(:NodeTranslator)) do
+          register(*types)
+          define_method(:translate, &block)
+        end
+      end
+
+      raises Mustermann::Error
+
+      # @param [Mustermann::AST::Node, Object] node to translate
+      # @return decorator encapsulating translation
+      #
+      # @!visibility private
+      def decorator_for(node)
+        factory = node.class.ancestors.inject(nil) { |d,a| d || self.class.dispatch_table[a.name] }
+        raise error_class, "#{self.class}: Cannot translate #{node.class}" unless factory
+        factory.new(node, self)
+      end
+
+      # Start the translation dance for a (sub)tree.
+      # @!visibility private
+      def translate(node, *args, &block)
+        result = decorator_for(node).translate(*args, &block)
+        result = result.node while result.is_a? NodeTranslator
+        result
+      end
+
+      # @return [String] escaped character
+      # @!visibility private
+      def escape(char, options = {})
+        parser      = options[:parser] || URI::DEFAULT_PARSER
+        escape      = options[:escape] || parser.regexp[:UNSAFE]
+        also_escape = options[:also_escape]
+        escape = Regexp.union(also_escape, escape) if also_escape
+        char =~ escape ? parser.escape(char, Regexp.union(*escape)) : char
+      end
+    end
+  end
+end

data/lib/mustermann/ast/tree_renderer.rb

@@ -0,0 +1,29 @@
+require 'mustermann/ast/translator'
+
+module Mustermann
+  module AST
+    # Turns an AST into a human readable string.
+    # @!visibility private
+    class TreeRenderer < Translator
+      # @example
+      #   Mustermann::AST::TreeRenderer.render Mustermann::Sinatra::Parser.parse('/foo')
+      #
+      # @!visibility private
+      def self.render(ast)
+        new.translate(ast)
+      end
+
+      translate(Object) { inspect }
+      translate(Array) { map { |e| "\n" << t(e) }.join.gsub("\n", "\n  ") }
+      translate(:node) { "#{t.type(node)} #{t(payload)}" }
+      translate(:with_look_ahead) { "#{t.type(node)} #{t(head)} #{t(payload)}" }
+
+      # Turns a class name into a node identifier.
+      #
+      # @!visibility private
+      def type(node)
+        node.class.name[/[^:]+$/].split(/(?<=.)(?=[A-Z])/).map(&:downcase).join(?_)
+      end
+    end
+  end
+end

data/lib/mustermann/ast/validation.rb

@@ -0,0 +1,43 @@
+require 'mustermann/ast/translator'
+
+module Mustermann
+  module AST
+    # Checks the AST for certain validations, like correct capture names.
+    #
+    # Internally a poor man's visitor (abusing translator to not have to implement a visitor).
+    # @!visibility private
+    class Validation < Translator
+      # Runs validations.
+      #
+      # @param [Mustermann::AST::Node] ast to be validated
+      # @return [Mustermann::AST::Node] the validated ast
+      # @raise [Mustermann::AST::CompileError] if validation fails
+      # @!visibility private
+      def self.validate(ast)
+        new.translate(ast)
+        ast
+      end
+
+      translate(Object, :splat) {}
+      translate(:node) { t(payload) }
+      translate(Array) { each { |p| t(p)} }
+      translate(:capture, :variable, :named_splat) { t.check_name(name) }
+
+      # @raise [Mustermann::CompileError] if name is not acceptable
+      # @!visibility private
+      def check_name(name)
+        raise CompileError, "capture name can't be empty" if name.nil? or name.empty?
+        raise CompileError, "capture name must start with underscore or lower case letter" unless name =~ /^[a-z_]/
+        raise CompileError, "capture name can't be #{name}" if name == "splat" or name == "captures"
+        raise CompileError, "can't use the same capture name twice" if names.include? name
+        names << name
+      end
+
+      # @return [Array<String>] list of capture names in tree
+      # @!visibility private
+      def names
+        @names ||= []
+      end
+    end
+  end
+end

data/lib/mustermann/caster.rb

@@ -0,0 +1,117 @@
+require 'enumerable/lazy' unless Enumerable.method_defined?(:lazy)
+require 'delegate'
+
+module Mustermann
+  # Class for defining and running simple Hash transformations.
+  #
+  # @example
+  #   caster = Mustermann::Caster.new
+  #   caster.register(:foo) { |value| { bar: value.upcase } }
+  #   caster.cast(foo: "hello", baz: "world") # => { bar: "HELLO", baz: "world" }
+  #
+  # @see Mustermann::Expander#cast
+  #
+  # @!visibility private
+  class Caster < DelegateClass(Array)
+    # @param (see #register)
+    # @!visibility private
+    def initialize(*types, &block)
+      super([])
+      register(*types, &block)
+    end
+
+    # @param [Array<Symbol, Regexp, #cast, #===>] types identifier for cast type (some need block)
+    # @!visibility private
+    def register(*types, &block)
+      types << Any.new(&block) if types.empty?
+      types.each { |type| self << caster_for(type, &block) }
+    end
+
+    # @param [Symbol, Regexp, #cast, #===] type identifier for cast type (some need block)
+    # @return [#cast] specific cast operation
+    # @!visibility private
+    def caster_for(type, &block)
+      case type
+      when Symbol, Regexp then Key.new(type, &block)
+      else type.respond_to?(:cast) ? type : Value.new(type, &block)
+      end
+    end
+
+    # Transforms a Hash.
+    # @param [Hash] hash pre-transform Hash
+    # @return [Hash] post-transform Hash
+    # @!visibility private
+    def cast(hash)
+      merge = {}
+      hash.delete_if do |key, value|
+        next unless casted = lazy.map { |e| e.cast(key, value) }.detect { |e| e }
+        casted = { key => casted } unless casted.respond_to? :to_hash
+        merge.update(casted.to_hash)
+      end
+      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
+      # @!visibility private
+      def initialize(&block)
+        @block = block
+      end
+
+      # @see Mustermann::Caster#cast
+      # @!visibility private
+      def cast(key, value)
+        case @block.arity
+        when 0 then @block.call
+        when 1 then @block.call(value)
+        else        @block.call(key, value)
+        end
+      end
+    end
+
+    # Class for block based casts that are triggered for key/value pairs with a matching value.
+    # @!visibility private
+    class Value < Any
+      # @param [#===] type used for matching values
+      # @!visibility private
+      def initialize(type, &block)
+        @type = type
+        super(&block)
+      end
+
+      # @see Mustermann::Caster#cast
+      # @!visibility private
+      def cast(key, value)
+        super if @type === value
+      end
+    end
+
+    # Class for block based casts that are triggered for key/value pairs with a matching key.
+    # @!visibility private
+    class Key < Any
+      # @param [#===] type used for matching keys
+      # @!visibility private
+      def initialize(type, &block)
+        @type = type
+        super(&block)
+      end
+
+      # @see Mustermann::Caster#cast
+      # @!visibility private
+      def cast(key, value)
+        super if @type === key
+      end
+    end
+  end
+end

data/lib/mustermann/equality_map.rb

@@ -0,0 +1,48 @@
+module Mustermann
+  # A simple wrapper around ObjectSpace::WeakMap that allows matching keys by equality rather than identity.
+  # Used for caching.
+  #
+  # @see #fetch
+  # @!visibility private
+  class EqualityMap
+    MAP_CLASS = defined?(ObjectSpace::WeakMap) ? ObjectSpace::WeakMap : Hash
+
+    # @!visibility private
+    def initialize
+      @keys = {}
+      @map  = MAP_CLASS.new
+    end
+
+    # @param [Array<#hash>] key for caching
+    # @yield block that will be called to populate entry if missing
+    # @return value stored in map or result of block
+    # @!visibility private
+    def fetch(*key)
+      identity = @keys[key.hash]
+      key      = identity == key ? identity : key
+
+      # it is ok that this is not thread-safe, worst case it has double cost in
+      # generating, object equality is not guaranteed anyways
+      @map[key] ||= track(key, yield)
+    end
+
+    # @param [#hash] key for identifying the object
+    # @param [Object] object to be stored
+    # @return [Object] same as the second parameter
+    def track(key, object)
+      ObjectSpace.define_finalizer(object, finalizer(key.hash))
+      @keys[key.hash] = key
+      object
+    end
+
+    # Finalizer proc needs to be generated in different scope so it doesn't keep a reference to the object.
+    #
+    # @param [Fixnum] hash for key
+    # @return [Proc] finalizer callback
+    def finalizer(hash)
+      proc { @keys.delete(hash) }
+    end
+
+    private :track, :finalizer
+  end
+end

data/lib/mustermann/error.rb

@@ -0,0 +1,6 @@
+module Mustermann
+  Error        ||= Class.new(StandardError) # Raised if anything goes wrong while generating a {Pattern}.
+  CompileError ||= Class.new(Error)         # Raised if anything goes wrong while compiling a {Pattern}.
+  ParseError   ||= Class.new(Error)         # Raised if anything goes wrong while parsing a {Pattern}.
+  ExpandError  ||= Class.new(Error)         # Raised if anything goes wrong while expanding a {Pattern}.
+end

data/lib/mustermann/expander.rb

@@ -0,0 +1,206 @@
+require 'mustermann/ast/expander'
+require 'mustermann/caster'
+require 'mustermann'
+
+module Mustermann
+  # Allows fine-grained control over pattern expansion.
+  #
+  # @example
+  #   expander = Mustermann::Expander.new(additional_values: :append)
+  #   expander << "/users/:user_id"
+  #   expander << "/pages/:page_id"
+  #
+  #   expander.expand(page_id: 58, format: :html5) # => "/pages/58?format=html5"
+  class Expander
+    attr_reader :patterns, :additional_values, :caster
+
+    # @param [Array<#to_str, Mustermann::Pattern>] patterns list of patterns to expand, see {#add}.
+    # @param [Symbol] additional_values behavior when encountering additional values, see {#expand}.
+    # @param [Hash] options used when creating/expanding patterns, see {Mustermann.new}.
+    def initialize(*patterns)
+      options = patterns.last.is_a?(Hash) ? patterns.pop : {}
+      additional_values = options.delete(:additional_values) || :raise
+      unless additional_values == :raise or additional_values == :ignore or additional_values == :append
+        raise ArgumentError, "Illegal value %p for additional_values" % additional_values
+      end
+
+      @patterns          = []
+      @api_expander      = AST::Expander.new
+      @additional_values = additional_values
+      @options           = options
+      @caster            = Caster.new(Caster::Nil)
+      add(*patterns)
+    end
+
+    # Add patterns to expand.
+    #
+    # @example
+    #   expander = Mustermann::Expander.new
+    #   expander.add("/:a.jpg", "/:b.png")
+    #   expander.expand(a: "pony") # => "/pony.jpg"
+    #
+    # @param [Array<#to_str, Mustermann::Pattern>] patterns list of to add for expansion, Strings will be compiled to patterns.
+    # @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
+        raise NotImplementedError, "expanding not supported for #{pattern.class}" unless pattern.respond_to? :to_ast
+        @api_expander.add(pattern.to_ast)
+        @patterns << pattern
+      end
+      self
+    end
+
+    alias_method :<<, :add
+
+    # Register a block as simple hash transformation that runs before expanding the pattern.
+    # @return [Mustermann::Expander] the expander
+    #
+    # @overload cast
+    #   Register a block as simple hash transformation that runs before expanding the pattern for all entries.
+    #
+    #   @example casting everything that implements to_param to param
+    #     expander.cast { |o| o.to_param if o.respond_to? :to_param }
+    #
+    #   @yield every key/value pair
+    #   @yieldparam key [Symbol] omitted if block takes less than 2
+    #   @yieldparam value [Object] omitted if block takes no arguments
+    #   @yieldreturn [Hash{Symbol: Object}] will replace key/value pair with returned hash
+    #   @yieldreturn [nil, false] will keep key/value pair in hash
+    #   @yieldreturn [Object] will replace value with returned object
+    #
+    # @overload cast(*type_matchers)
+    #   Register a block as simple hash transformation that runs before expanding the pattern for certain entries.
+    #
+    #   @example convert user to user_id
+    #     expander = Mustermann::Expander.new('/users/:user_id')
+    #     expand.cast(:user) { |user| { user_id: user.id } }
+    #
+    #     expand.expand(user: User.current) # => "/users/42"
+    #
+    #   @example convert user, page, image to user_id, page_id, image_id
+    #     expander = Mustermann::Expander.new('/users/:user_id', '/pages/:page_id', '/:image_id.jpg')
+    #     expand.cast(:user, :page, :image) { |key, value| { "#{key}_id".to_sym => value.id } }
+    #
+    #     expand.expand(user: User.current) # => "/users/42"
+    #
+    #   @example casting to multiple key/value pairs
+    #     expander = Mustermann::Expander.new('/users/:user_id/:image_id.:format')
+    #     expander.cast(:image) { |i| { user_id: i.owner.id, image_id: i.id, format: i.format } }
+    #
+    #     expander.expander(image: User.current.avatar) # => "/users/42/avatar.jpg"
+    #
+    #   @example casting all ActiveRecord objects to param
+    #     expander.cast(ActiveRecord::Base, &:to_param)
+    #
+    #   @param [Array<Symbol, Regexp, #===>] type_matchers
+    #     To identify key/value pairs to match against.
+    #     Regexps and Symbols match against key, everything else matches against value.
+    #
+    #   @yield every key/value pair
+    #   @yieldparam key [Symbol] omitted if block takes less than 2
+    #   @yieldparam value [Object] omitted if block takes no arguments
+    #   @yieldreturn [Hash{Symbol: Object}] will replace key/value pair with returned hash
+    #   @yieldreturn [nil, false] will keep key/value pair in hash
+    #   @yieldreturn [Object] will replace value with returned object
+    #
+    # @overload cast(*cast_objects)
+    #
+    #   @param [Array<#cast>] cast_objects
+    #     Before expanding, will call #cast on these objects for each key/value pair.
+    #     Return value will be treated same as block return values described above.
+    def cast(*types, &block)
+      caster.register(*types, &block)
+      self
+    end
+
+    # @example Expanding a pattern
+    #   pattern = Mustermann::Expander.new('/:name', '/:name.:ext')
+    #   pattern.expand(name: 'hello')             # => "/hello"
+    #   pattern.expand(name: 'hello', ext: 'png') # => "/hello.png"
+    #
+    # @example Handling additional values
+    #   pattern = Mustermann::Expander.new('/:name', '/:name.:ext')
+    #   pattern.expand(:ignore, name: 'hello', ext: 'png', scale: '2x') # => "/hello.png"
+    #   pattern.expand(:append, name: 'hello', ext: 'png', scale: '2x') # => "/hello.png?scale=2x"
+    #   pattern.expand(:raise,  name: 'hello', ext: 'png', scale: '2x') # raises Mustermann::ExpandError
+    #
+    # @example Setting additional values behavior for the expander object
+    #   pattern = Mustermann::Expander.new('/:name', '/:name.:ext', additional_values: :append)
+    #   pattern.expand(name: 'hello', ext: 'png', scale: '2x') # => "/hello.png?scale=2x"
+    #
+    # @param [Symbol] behavior
+    #   What to do with additional key/value pairs not present in the values hash.
+    #   Possible options: :raise, :ignore, :append.
+    #
+    # @param [Hash{Symbol: #to_s, Array<#to_s>}] values
+    #   Values to use for expansion.
+    #
+    # @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 = {})
+      values, behavior = behavior, nil if behavior.is_a?(Hash)
+      values = map_values(values)
+
+      case behavior || additional_values
+      when :raise  then @api_expander.expand(values)
+      when :ignore then with_rest(values) { |uri, rest| uri }
+      when :append then with_rest(values) { |uri, rest| append(uri, rest) }
+      else raise ArgumentError, "unknown behavior %p" % behavior
+      end
+    end
+
+    # @see Object#==
+    def ==(other)
+      return false unless other.class == self.class
+      other.patterns == patterns and other.additional_values == additional_values
+    end
+
+    # @see Object#eql?
+    def eql?(other)
+      return false unless other.class == self.class
+      other.patterns.eql? patterns and other.additional_values.eql? additional_values
+    end
+
+    # @see Object#hash
+    def hash
+      patterns.hash + additional_values.hash
+    end
+
+    def expandable?(values)
+      return false unless values
+      expandable, _ = split_values(map_values(values))
+      @api_expander.expandable? expandable
+    end
+
+    def with_rest(values)
+      expandable, non_expandable = split_values(values)
+      yield expand(:raise, slice(values, expandable)), slice(values, non_expandable)
+    end
+
+    def split_values(values)
+      expandable     = @api_expander.expandable_keys(values.keys)
+      non_expandable = values.keys - expandable
+      [expandable, non_expandable]
+    end
+
+    def slice(hash, keys)
+      Hash[keys.map { |k| [k, hash[k]] }]
+    end
+
+    def append(uri, values)
+      return uri unless values and values.any?
+      entries = values.map { |pair| pair.map { |e| @api_expander.escape(e, also_escape: /[\/\?#\&\=%]/) }.join(?=) }
+      "#{ uri }#{ uri[??]??&:?? }#{ entries.join(?&) }"
+    end
+
+    def map_values(values)
+      values = values.dup
+      @api_expander.keys.each { |key| values[key] ||= values.delete(key.to_s) if values.include? key.to_s }
+      caster.cast(values)
+    end
+
+    private :with_rest, :slice, :append, :caster, :map_values, :split_values
+  end
+end