mustermann 1.0.1 → 1.0.2.rc1

data/mustermann-contrib/examples/highlighting.rb

@@ -0,0 +1,35 @@
+require 'bundler/setup'
+require 'mustermann/visualizer'
+
+Hansi.mode = ARGV[0].to_i if ARGV.any?
+
+def self.example(type, *patterns)
+  print Hansi.render(:bold, "  #{type}: ".ljust(14))
+  patterns.each do |pattern|
+    pattern     = Mustermann.new(pattern, type: type)
+    space_after = pattern.to_s.size > 24 ? " " : " " * (25 - pattern.to_s.size)
+    highlight   = Mustermann::Visualizer.highlight(pattern, inspect: true)
+    print highlight.to_ansi + space_after
+  end
+  puts
+end
+
+puts
+example(:cake,     '/:prefix/**')
+example(:express,  '/:prefix+/:id(\d+)', '/:page/:slug+')
+example(:flask,    '/<prefix>/<int:id>', '/user/<int(min=0):id>')
+example(:identity, '/image.png')
+example(:pyramid,  '/{prefix:.*}/{id}',  '/{page}/*slug')
+example(:rails,    '/:slug(.:ext)')
+example(:regexp,   '/(?<slug>[^/]+)',    '/(?:page|user)/(\d+)')
+example(:shell,    '/**/*',              '/\{a,b\}/{a,b}')
+example(:simple,   '/:page/*slug')
+example(:sinatra,  '/:page/*slug',         '/users/{id}?')
+example(:template, '/{+pre}/{page}{?q,p}', '/users/{id}?')
+puts
+
+example(:composition)
+composite = Mustermann.new("/{a}", "/{b}/{c}")
+puts "  " + composite.to_ansi
+puts "  " + (Mustermann.new("/") ^ composite).to_ansi
+puts

data/mustermann-contrib/lib/mustermann/cake.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/ast/pattern'
+
+module Mustermann
+  # CakePHP style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :cake) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#cake Syntax description in the README
+  class Cake < AST::Pattern
+    register :cake
+
+    on(?:) { |c| node(:capture) { scan(/\w+/) } }
+    on(?*) { |c| node(:splat, convert: (-> e { e.split('/') } unless scan(?*))) }
+  end
+end

data/mustermann-contrib/lib/mustermann/express.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/ast/pattern'
+
+module Mustermann
+  # Express style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :express) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#flask Syntax description in the README
+  class Express < AST::Pattern
+    register :express
+
+    on(nil, ??, ?+, ?*, ?)) { |c| unexpected(c) }
+    on(?:) { |c| node(:capture) { scan(/\w+/) } }
+    on(?() { |c| node(:splat, constraint: read_brackets(?(, ?))) }
+
+    suffix ??, after: :capture do |char, element|
+      unexpected(char) unless element.is_a? :capture
+      node(:optional, element)
+    end
+
+    suffix ?*, after: :capture do |match, element|
+      node(:named_splat, element.name)
+    end
+
+    suffix ?+, after: :capture do |match, element|
+      node(:named_splat, element.name, constraint: ".+")
+    end
+
+    suffix ?(, after: :capture do |match, element|
+      element.constraint = read_brackets(?(, ?))
+      element
+    end
+  end
+end

data/mustermann-contrib/lib/mustermann/file_utils.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/file_utils/glob_pattern'
+require 'mustermann/mapper'
+require 'fileutils'
+
+module Mustermann
+  # Implements handy file operations using patterns.
+  module FileUtils
+    extend self
+
+    # Turn a Mustermann pattern into glob pattern.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   Mustermann::FileUtils.glob_pattern('/:name')                  # => '/*'
+    #   Mustermann::FileUtils.glob_pattern('src/:path/:file.(js|rb)') # => 'src/**/*/*.{js,rb}'
+    #   Mustermann::FileUtils.glob_pattern('{a,b}/*', type: :shell)   # => '{a,b}/*'
+    #
+    #   pattern = Mustermann.new('/foo/:page', '/bar/:page') # => #<Mustermann::Composite:...>
+    #   Mustermann::FileUtils.glob_pattern(pattern)          # => "{/foo/*,/bar/*}"
+    #
+    # @param [Object] pattern the object to turn into a glob pattern.
+    # @return [String] the glob pattern
+    def glob_pattern(*pattern, **options)
+      pattern_with_glob_pattern(*pattern, **options).last
+    end
+
+    # Uses the given pattern(s) to search for files and directories.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #   Mustermann::FileUtils.glob(':base.:ext') # => ['example.txt']
+    #
+    #   Mustermann::FileUtils.glob(':base.:ext') do |file, params|
+    #     file   # => "example.txt"
+    #     params # => {"base"=>"example", "ext"=>"txt"}
+    #   end
+    def glob(*pattern, **options, &block)
+      raise ArgumentError, "no pattern given" if pattern.empty?
+      pattern, glob_pattern = pattern_with_glob_pattern(*pattern, **options)
+      results               = [] unless block
+      Dir.glob(glob_pattern) do |result|
+        next unless params = pattern.params(result)
+        block ? block[result, params] : results << result
+      end
+      results
+    end
+
+    # Allows to search for files an map these onto other strings.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   Mustermann::FileUtils.glob_map(':base.:ext' => ':base.bak.:ext') # => {'example.txt' => 'example.bak.txt'}
+    #   Mustermann::FileUtils.glob_map(':base.:ext' => :base) { |file, mapped| mapped } # => ['example']
+    #
+    # @see Mustermann::Mapper
+    def glob_map(map = {}, **options, &block)
+      map    = Mapper === map ? map : Mapper.new(map, **options)
+      mapped = glob(*map.to_h.keys).map { |f| [f, unescape(map[f])] }
+      block ? mapped.map(&block) : Hash[mapped]
+    end
+
+    # Copies files based on a pattern mapping.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # copies example.txt to example.bak.txt
+    #   Mustermann::FileUtils.cp(':base.:ext' => ':base.bak.:ext')
+    #
+    # @see #glob_map
+    def cp(map = {}, recursive: false, **options)
+      utils_opts, opts = split_options(:preserve, :dereference_root, :remove_destination, **options)
+      cp_method        = recursive ? :cp_r : :cp
+      glob_map(map, **opts) { |o,n| f.send(cp_method, o, n, **utils_opts) }
+    end
+
+
+    # Copies files based on a pattern mapping, recursively.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # copies Foo.app/example.txt to Foo.back.app/example.txt
+    #   Mustermann::FileUtils.cp_r(':base.:ext' => ':base.bak.:ext')
+    #
+    # @see #glob_map
+    def cp_r(map = {}, **options)
+      cp(map, recursive: true, **options)
+    end
+
+    # Moves files based on a pattern mapping.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # moves example.txt to example.bak.txt
+    #   Mustermann::FileUtils.mv(':base.:ext' => ':base.bak.:ext')
+    #
+    # @see #glob_map
+    def mv(map = {}, **options)
+      utils_opts, opts = split_options(**options)
+      glob_map(map, **opts) { |o,n| f.mv(o, n, **utils_opts) }
+    end
+
+
+    # Creates links based on a pattern mapping.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # creates a link from bin/example to lib/example.rb
+    #   Mustermann::FileUtils.ln('lib/:name.rb' => 'bin/:name')
+    #
+    # @see #glob_map
+    def ln(map = {}, symbolic: false, **options)
+      utils_opts, opts = split_options(**options)
+      link_method      = symbolic ? :ln_s : :ln
+      glob_map(map, **opts) { |o,n| f.send(link_method, o, n, **utils_opts) }
+    end
+
+    # Creates symbolic links based on a pattern mapping.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # creates a symbolic link from bin/example to lib/example.rb
+    #   Mustermann::FileUtils.ln_s('lib/:name.rb' => 'bin/:name')
+    #
+    # @see #glob_map
+    def ln_s(map = {}, **options)
+      ln(map, symbolic: true, **options)
+    end
+
+    # Creates symbolic links based on a pattern mapping.
+    # Overrides potentailly existing files.
+    #
+    # @example
+    #   require 'mustermann/file_utils'
+    #
+    #   # creates a symbolic link from bin/example to lib/example.rb
+    #   Mustermann::FileUtils.ln_sf('lib/:name.rb' => 'bin/:name')
+    #
+    # @see #glob_map
+    def ln_sf(map = {}, **options)
+      ln(map, symbolic: true, force: true, **options)
+    end
+
+
+    # Splits options into those meant for Mustermann and those
+    # meant for ::FileUtils.
+    #
+    # @!visibility private
+    def split_options(*utils_option_names, **options)
+      utils_options, pattern_options = {}, {}
+      utils_option_names += %i[force noop verbose]
+
+      options.each do |key, value|
+        list = utils_option_names.include?(key) ? utils_options : pattern_options
+        list[key] = value
+      end
+
+      [utils_options, pattern_options]
+    end
+
+    # Create a Mustermann pattern from whatever the input is and turn it into
+    # a glob pattern.
+    #
+    # @!visibility private
+    def pattern_with_glob_pattern(*pattern, **options)
+      options[:uri_decode]    ||= false
+      pattern                   = Mustermann.new(*pattern.flatten, **options)
+      @glob_patterns          ||= {}
+      @glob_patterns[pattern] ||= GlobPattern.generate(pattern)
+      [pattern, @glob_patterns[pattern]]
+    end
+
+    # The FileUtils method to use.
+    # @!visibility private
+    def f
+      ::FileUtils
+    end
+
+    # Unescape an URI escaped string.
+    # @!visibility private
+    def unescape(string)
+      @uri ||= URI::Parser.new
+      @uri.unescape(string)
+    end
+
+    # Create a new version of Mustermann::FileUtils using a different ::FileUtils module.
+    # @see DryRun
+    # @!visibility private
+    def with_file_utils(&block)
+      Module.new do
+        include Mustermann::FileUtils
+        define_method(:f, &block)
+        private(:f)
+        extend self
+      end
+    end
+
+    private :pattern_with_glob_pattern, :split_options, :f, :unescape
+
+    alias_method :copy,     :cp
+    alias_method :move,     :mv
+    alias_method :link,     :ln
+    alias_method :symlink,  :ln_s
+    alias_method :[],       :glob
+
+    DryRun  ||= with_file_utils { ::FileUtils::DryRun  }
+    NoWrite ||= with_file_utils { ::FileUtils::NoWrite }
+    Verbose ||= with_file_utils { ::FileUtils::Verbose }
+  end
+end

data/mustermann-contrib/lib/mustermann/file_utils/glob_pattern.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require 'mustermann/ast/translator'
+
+module Mustermann
+  module FileUtils
+    # AST Translator to turn Mustermann patterns into glob patterns.
+    # @!visibility private
+    class GlobPattern < Mustermann::AST::Translator
+      # Character that need to be escaped in glob patterns.
+      # @!visibility private
+      ESCAPE = %w([ ] { } * ** \\)
+
+      # Turn a Mustermann pattern into glob pattern.
+      # @param [#to_glob, #to_ast, Object] pattern the object to turn into a glob pattern.
+      # @return [String] the glob pattern
+      # @!visibility private
+      def self.generate(pattern)
+        return pattern.to_glob               if pattern.respond_to? :to_glob
+        return new.translate(pattern.to_ast) if pattern.respond_to? :to_ast
+        return "**/*" unless pattern.is_a? Mustermann::Composite
+        "{#{pattern.patterns.map { |p| generate(p) }.join(',')}}"
+      end
+
+      translate(:root, :group, :expression) { t(payload) || ""                           }
+      translate(:separator, :char)          { t.escape(payload)                          }
+      translate(:capture)                   { constraint ? "**/*" : "*"                  }
+      translate(:optional)                  { "{#{t(payload)},}"                         }
+      translate(:named_splat, :splat)       { "**/*"                                     }
+      translate(:with_look_ahead)           { t(head) + t(payload)                       }
+      translate(:union)                     { "{#{payload.map { |e| t(e) }.join(',')}}"  }
+      translate(Array)                      { map { |e| t(e) }.join                      }
+
+      # Escape with a slash rather than URI escaping.
+      # @!visibility private
+      def escape(char)
+        ESCAPE.include?(char) ? "\\#{char}" : char
+      end
+    end
+  end
+end

data/mustermann-contrib/lib/mustermann/fileutils.rb

@@ -0,0 +1 @@
+require 'mustermann/file_utils'

data/mustermann-contrib/lib/mustermann/flask.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/ast/pattern'
+
+module Mustermann
+  # Flask style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/<foo>', type: :flask) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#flask Syntax description in the README
+  class Flask < AST::Pattern
+    include Concat::Native
+    register :flask
+
+    on(nil, ?>, ?:) { |c| unexpected(c) }
+
+    on(?<) do |char|
+      converter_name       = expect(/\w+/, char: char)
+      args, opts           = scan(?() ? read_args(?=, ?)) : [[], {}]
+
+      if scan(?:)
+        name = read_escaped(?>)
+      else
+        converter_name, name = 'default', converter_name
+        expect(?>)
+      end
+
+      converter   = pattern.converters.fetch(converter_name) { unexpected("converter %p" % converter_name) }
+      converter   = converter.new(*args, **opts)  if converter.respond_to? :new
+      constraint  = converter.constraint          if converter.respond_to? :constraint
+      convert     = converter.convert             if converter.respond_to? :convert
+      qualifier   = converter.qualifier           if converter.respond_to? :qualifier
+      node_type   = converter.node_type           if converter.respond_to? :node_type
+      node_type ||= :capture
+
+      node(node_type, name, convert: convert, constraint: constraint, qualifier: qualifier)
+    end
+
+    # A class for easy creating of converters.
+    # @see Mustermann::Flask#register_converter
+    class Converter
+      # Constraint on the format used for the capture.
+      # Should be a regexp (or a string corresponding to a regexp)
+      # @see Mustermann::Flask#register_converter
+      attr_accessor :constraint
+
+      # Callback
+      # Should be a Proc.
+      # @see Mustermann::Flask#register_converter
+      attr_accessor :convert
+
+      # Constraint on the format used for the capture.
+      # Should be a regexp (or a string corresponding to a regexp)
+      # @see Mustermann::Flask#register_converter
+      # @!visibility private
+      attr_accessor :node_type
+
+      # Constraint on the format used for the capture.
+      # Should be a regexp (or a string corresponding to a regexp)
+      # @see Mustermann::Flask#register_converter
+      # @!visibility private
+      attr_accessor :qualifier
+
+      # @!visibility private
+      def self.create(&block)
+        Class.new(self) do
+          define_method(:initialize) { |*a, **o| block[self, *a, **o] }
+        end
+      end
+
+      # Makes sure a given value falls inbetween a min and a max.
+      # Uses the passed block to convert the value from a string to whatever
+      # format you'd expect.
+      #
+      # @example
+      #   require 'mustermann/flask'
+      #
+      #   class MyPattern < Mustermann::Flask
+      #     register_converter(:x) { between(5, 15, &:to_i) }
+      #   end
+      #
+      #   pattern = MyPattern.new('<x:id>')
+      #   pattern.params('/12') # => { 'id' => 12 }
+      #   pattern.params('/16') # => { 'id' => 15 }
+      #
+      # @see Mustermann::Flask#register_converter
+      def between(min, max)
+        self.convert = proc do |input|
+          value = yield(input)
+          value = yield(min) if min and value < yield(min)
+          value = yield(max) if max and value > yield(max)
+          value
+        end
+      end
+    end
+
+    # Generally available converters.
+    # @!visibility private
+    def self.converters(inherited = true)
+      return @converters ||= {} unless inherited
+      defaults = superclass.respond_to?(:converters) ? superclass.converters : {}
+      defaults.merge(converters(false))
+    end
+
+    # Allows you to register your own converters.
+    #
+    # It is reommended to use this on a subclass, so to not influence other subsystems
+    # using flask templates.
+    #
+    # The object passed in as converter can implement #convert and/or #constraint.
+    #
+    # It can also instead implement #new, which will then return an object responding
+    # to some of these methods. Arguments from the flask pattern will be passed to #new.
+    #
+    # If passed a block, it will be yielded to with a {Mustermann::Flask::Converter}
+    # instance and any arguments in the flask pattern.
+    #
+    # @example with simple object
+    #   require 'mustermann/flask'
+    #
+    #   MyPattern    = Class.new(Mustermann::Flask)
+    #   up_converter = Struct.new(:convert).new(:upcase.to_proc)
+    #   MyPattern.register_converter(:upper, up_converter)
+    #
+    #   MyPattern.new("/<up:name>").params('/foo') # => { "name" => "FOO" }
+    #
+    # @example with block
+    #   require 'mustermann/flask'
+    #
+    #   MyPattern    = Class.new(Mustermann::Flask)
+    #   MyPattern.register_converter(:upper) { |c| c.convert = :upcase.to_proc }
+    #
+    #   MyPattern.new("/<up:name>").params('/foo') # => { "name" => "FOO" }
+    #
+    # @example with converter class
+    #   require 'mustermann/flasl'
+    #
+    #   class MyPattern < Mustermann::Flask
+    #     class Converter
+    #       attr_reader :convert
+    #       def initialize(send: :to_s)
+    #         @convert = send.to_sym.to_proc
+    #       end
+    #     end
+    #
+    #     register_converter(:t, Converter)
+    #   end
+    #
+    #   MyPattern.new("/<t(send=upcase):name>").params('/Foo')   # => { "name" => "FOO" }
+    #   MyPattern.new("/<t(send=downcase):name>").params('/Foo') # => { "name" => "foo" }
+    #
+    # @param [#to_s] name converter name
+    # @param [#new, #convert, #constraint, nil] converter
+    def self.register_converter(name, converter = nil, &block)
+      converter ||= Converter.create(&block)
+      converters(false)[name.to_s] = converter
+    end
+
+    register_converter(:string) do |converter, minlength: nil, maxlength: nil, length: nil|
+      converter.qualifier = "{%s,%s}" % [minlength || 1, maxlength] if minlength or maxlength
+      converter.qualifier = "{%s}"    % length if length
+    end
+
+    register_converter(:int) do |converter, min: nil, max: nil, fixed_digits: false|
+      converter.constraint = /\d/
+      converter.qualifier  = "{#{fixed_digits}}" if fixed_digits
+      converter.between(min, max) { |string| Integer(string) }
+    end
+
+    register_converter(:float) do |converter, min: nil, max: nil|
+      converter.constraint = /\d*\.?\d+/
+      converter.qualifier  = ""
+      converter.between(min, max) { |string| Float(string) }
+    end
+
+    register_converter(:path) do |converter|
+      converter.node_type = :named_splat
+    end
+
+    register_converter(:any) do |converter, *strings|
+      strings              = strings.map { |s| Regexp.escape(s) unless s == {} }.compact
+      converter.qualifier  = ""
+      converter.constraint = Regexp.union(*strings)
+    end
+
+    register_converter(:default, converters['string'])
+
+    supported_options :converters
+    attr_reader :converters
+
+    def initialize(input, converters: {}, **options)
+      @converters = self.class.converters.dup
+      converters.each { |k,v| @converters[k.to_s] = v } if converters
+      super(input, **options)
+    end
+  end
+end