mustermann 0.1.0 → 0.2.0

data/lib/mustermann/ast/transformer.rb

@@ -5,43 +5,51 @@ module Mustermann
     # Takes a tree, turns it into an even better tree.
     # @!visibility private
     class Transformer < Translator
-      # @!visibility private
-      Operator  ||= Struct.new(:separator, :allow_reserved, :prefix, :parametric)
-
-      # Operators available for expressions.
-      # @!visibility private
-      OPERATORS ||= {
-        nil => Operator.new(?,, false, false, false), ?+  => Operator.new(?,, true,  false, false),
-        ?#  => Operator.new(?,, true,  ?#,    false), ?.  => Operator.new(?., false, ?.,    false),
-        ?/  => Operator.new(?/, false, ?/,    false), ?;  => Operator.new(?;, false, ?;,    true),
-        ??  => Operator.new(?&, false, ??,    true),  ?&  => Operator.new(?&, false, ?&,    true)
-      }
 
       # Transforms a tree.
       # @note might mutate handed in tree instead of creating a new one
       # @param [Mustermann::AST::Node] tree to be transformed
       # @return [Mustermann::AST::Node] transformed tree
       # @!visibility private
-      def self.transform(ast)
-        new.translate(ast)
+      def self.transform(tree)
+        new.translate(tree)
       end
 
       translate(:node) { self }
-
-      translate(:expression) do
-        self.operator = OPERATORS.fetch(operator) { raise CompileError, "#{operator} operator not supported" }
-        separator     = Node[:separator].new(operator.separator)
-        prefix        = Node[:separator].new(operator.prefix)
-        self.payload  = Array(payload.inject { |list, element| Array(list) << t(separator) << t(element) })
-        payload.unshift(prefix) if operator.prefix
-        self
-      end
-
       translate(:group, :root) do
         self.payload = t(payload)
         self
       end
 
+      # URI expression transformations depending on operator
+      # @!visibility private
+      class ExpressionTransform < NodeTranslator
+        register :expression
+
+        # @!visibility private
+        Operator  ||= Struct.new(:separator, :allow_reserved, :prefix, :parametric)
+
+        # Operators available for expressions.
+        # @!visibility private
+        OPERATORS ||= {
+          nil => Operator.new(?,, false, false, false), ?+  => Operator.new(?,, true,  false, false),
+          ?#  => Operator.new(?,, true,  ?#,    false), ?.  => Operator.new(?., false, ?.,    false),
+          ?/  => Operator.new(?/, false, ?/,    false), ?;  => Operator.new(?;, false, ?;,    true),
+          ??  => Operator.new(?&, false, ??,    true),  ?&  => Operator.new(?&, false, ?&,    true)
+        }
+
+        # Sets operator and inserts separators in between variables.
+        # @!visibility private
+        def translate
+          self.operator = OPERATORS.fetch(operator) { raise CompileError, "#{operator} operator not supported" }
+          separator     = Node[:separator].new(operator.separator)
+          prefix        = Node[:separator].new(operator.prefix)
+          self.payload  = Array(payload.inject { |list, element| Array(list) << t(separator) << t(element) })
+          payload.unshift(prefix) if operator.prefix
+          self
+        end
+      end
+
       # Inserts with_look_ahead nodes wherever appropriate
       # @!visibility private
       class ArrayTransform < NodeTranslator

data/lib/mustermann/ast/translator.rb

@@ -12,7 +12,7 @@ module Mustermann
       # Encapsulates a single node translation
       # @!visibility private
       class NodeTranslator < DelegateClass(Node)
-        # @param [Array<Symbol, Class>] list of types to register for.
+        # @param [Array<Symbol, Class>] types list of types to register for.
         # @!visibility private
         def self.register(*types)
           types.each do |type|
@@ -76,7 +76,7 @@ module Mustermann
 
       raises Mustermann::Error
 
-      # @param [Mustermann::AST::Node, Object] object to translate
+      # @param [Mustermann::AST::Node, Object] node to translate
       # @return decorator encapsulating translation
       #
       # @!visibility private

data/lib/mustermann/ast/validation.rb

@@ -4,14 +4,14 @@ 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 impelment a visitor).
+    # 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
-      # @raises [Mustermann::AST::CompileError] if validation fails
+      # @raise [Mustermann::AST::CompileError] if validation fails
       # @!visibility private
       def self.validate(ast)
         new.translate(ast)
@@ -21,13 +21,16 @@ module Mustermann
       translate(Object, :splat) {}
       translate(:node) { t(payload) }
       translate(Array) { each { |p| t(p)} }
+      translate(:capture, :variable, :named_splat) { t.check_name(name) }
 
-      translate(:capture, :variable, :named_splat) do
+      # @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 t.names.include? name
-        t.names << name
+        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

data/lib/mustermann/caster.rb

@@ -0,0 +1,116 @@
+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,46 @@
+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
+    # @!visibility private
+    def initialize
+      @keys = {}
+      @map  = ObjectSpace::WeakMap.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(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/expander.rb

@@ -0,0 +1,169 @@
+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, additional_values: :raise, **options)
+      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 againg 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 = caster.cast(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
+
+    def with_rest(values)
+      expandable     = @api_expander.expandable_keys(values.keys)
+      non_expandable = values.keys - expandable
+      yield expand(:raise, slice(values, expandable)), slice(values, 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
+
+    private :with_rest, :slice, :append, :caster
+  end
+end