mustermann-strscan 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 06f8fd306c3c984eba6afc9ca05e88efe2e03f78
+  data.tar.gz: 9f3b1baf5062f5f6ef3d1ff10607cddb4d48a8c7
+SHA512:
+  metadata.gz: 930c1721880ad0c61a8110181f5f14be48f6a8d0b35891c3234da4f0a20b7d7c3ebdf464d9899283a064b3b353b96fe2b358c4be765720406c3b470e3d312037
+  data.tar.gz: 31b9fefd04dba3e49f9231653476adb4744c4879327004f390a56404c5c31ccf23152a31afe5017d1064e2af4094fabf8f043487729a6a290cf4624993f3f239

data/README.md

@@ -0,0 +1,38 @@
+# String Scanner for Mustermann
+
+This gem implements `Mustermann::StringScanner`, a tool inspired by Ruby's [`StringScanner`]() class.
+
+``` ruby
+require 'mustermann/string_scanner'
+scanner = Mustermann::StringScanner.new("here is our example string")
+
+scanner.scan("here") # => "here"
+scanner.getch        # => " "
+
+if scanner.scan(":verb our")
+  scanner.scan(:noun, capture: :word)
+  scanner[:verb]  # => "is"
+  scanner[:nound] # => "example"
+end
+
+scanner.rest # => "string"
+```
+
+You can pass it pattern objects directly:
+
+``` ruby
+pattern = Mustermann.new(':name')
+scanner.check(pattern)
+```
+
+Or have `#scan` (and other methods) check these for you.
+
+``` ruby
+scanner.check('{name}', type: :template)
+```
+
+You can also pass in default options for ad hoc patterns when creating the scanner:
+
+``` ruby
+scanner = Mustermann::StringScanner.new(input, type: :shell)
+```

data/lib/mustermann/string_scanner.rb

@@ -0,0 +1,313 @@
+require 'mustermann'
+require 'mustermann/pattern_cache'
+require 'delegate'
+
+module Mustermann
+  # Class inspired by Ruby's StringScanner to scan an input string using multiple patterns.
+  #
+  # @example
+  #   require 'mustermann/string_scanner'
+  #   scanner = Mustermann::StringScanner.new("here is our example string")
+  #
+  #   scanner.scan("here") # => "here"
+  #   scanner.getch        # => " "
+  #
+  #   if scanner.scan(":verb our")
+  #     scanner.scan(:noun, capture: :word)
+  #     scanner[:verb]  # => "is"
+  #     scanner[:nound] # => "example"
+  #   end
+  #
+  #   scanner.rest # => "string"
+  #
+  # @note
+  #   This structure is not thread-safe, you should not scan on the same StringScanner instance concurrently.
+  #   Even if it was thread-safe, scanning concurrently would probably lead to unwanted behaviour.
+  class StringScanner
+    # Exception raised if scan/unscan operation cannot be performed.
+    ScanError     = Class.new(::ScanError)
+    PATTERN_CACHE = PatternCache.new
+    private_constant :PATTERN_CACHE
+
+    # Patterns created by {#scan} will be globally cached, since we assume that there is a finite number
+    # of different patterns used and that they are more likely to be reused than not.
+    # This method allows clearing the cache.
+    #
+    # @see Mustermann::PatternCache
+    def self.clear_cache
+      PATTERN_CACHE.clear
+    end
+
+    # @return [Integer] number of cached patterns
+    # @see clear_cache
+    # @api private
+    def self.cache_size
+      PATTERN_CACHE.size
+    end
+
+    # Encapsulates return values for {StringScanner#scan}, {StringScanner#check}, and friends.
+    # Behaves like a String (the substring which matched the pattern), but also exposes its position
+    # in the main string and any params parsed from it.
+    class ScanResult < DelegateClass(String)
+      # The scanner this result came from.
+      # @example
+      #   require 'mustermann/string_scanner'
+      #   scanner = Mustermann::StringScanner.new('foo/bar')
+      #   scanner.scan(:name).scanner == scanner # => true
+      attr_reader :scanner
+
+      # @example
+      #   require 'mustermann/string_scanner'
+      #   scanner = Mustermann::StringScanner.new('foo/bar')
+      #   scanner.scan(:name).position # => 0
+      #   scanner.getch.position       # => 3
+      #   scanner.scan(:name).position # => 4
+      #
+      # @return [Integer] position the substring starts at
+      attr_reader :position
+      alias_method :pos, :position
+
+      # @example
+      #   require 'mustermann/string_scanner'
+      #   scanner = Mustermann::StringScanner.new('foo/bar')
+      #   scanner.scan(:name).length # => 3
+      #   scanner.getch.length       # => 1
+      #   scanner.scan(:name).length # => 3
+      #
+      # @return [Integer] length of the substring
+      attr_reader :length
+
+      # Params parsed from the substring.
+      # Will not include params from previous scan results.
+      #
+      # @example
+      #   require 'mustermann/string_scanner'
+      #   scanner = Mustermann::StringScanner.new('foo/bar')
+      #   scanner.scan(:name).params # => { "name" => "foo" }
+      #   scanner.getch.params       # => {}
+      #   scanner.scan(:name).params # => { "name" => "bar" }
+      #
+      # @see Mustermann::StringScanner#params
+      # @see Mustermann::StringScanner#[]
+      #
+      # @return [Hash] params parsed from the substring
+      attr_reader :params
+
+      # @api private
+      def initialize(scanner, position, length, params = {})
+        @scanner, @position, @length, @params = scanner, position, length, params
+      end
+
+      # @api private
+      # @!visibility private
+      def __getobj__
+        @__getobj__ ||= scanner.to_s[position, length]
+      end
+    end
+
+    # @return [Hash] default pattern options used for {#scan} and similar methods
+    # @see #initialize
+    attr_reader :pattern_options
+
+    # Params from all previous matches from {#scan} and {#scan_until},
+    # but not from {#check} and {#check_until}. Changes can be reverted
+    # with {#unscan} and it can be completely cleared via {#reset}.
+    #
+    # @return [Hash] current params
+    attr_reader :params
+
+    # @return [Integer] current scan position on the input string
+    attr_accessor :position
+    alias_method :pos, :position
+    alias_method :pos=, :position=
+
+    # @example with different default type
+    #   require 'mustermann/string_scanner'
+    #   scanner = Mustermann::StringScanner.new("foo/bar/baz", type: :shell)
+    #   scanner.scan('*')     # => "foo"
+    #   scanner.scan('**/*')  # => "/bar/baz"
+    #
+    # @param [String] string the string to scan
+    # @param [Hash] pattern_options default options used for {#scan}
+    def initialize(string = "", **pattern_options)
+      @pattern_options = pattern_options
+      @string          = String(string).dup
+      reset
+    end
+
+    # Resets the {#position} to the start and clears all {#params}.
+    # @return [Mustermann::StringScanner] the scanner itself
+    def reset
+      @position = 0
+      @params   = {}
+      @history  = []
+      self
+    end
+
+    # Moves the position to the end of the input string.
+    # @return [Mustermann::StringScanner] the scanner itself
+    def terminate
+      track_result ScanResult.new(self, @position, size - @position)
+      self
+    end
+
+    # Checks if the given pattern matches any substring starting at the current position.
+    #
+    # If it does, it will advance the current {#position} to the end of the substring and merges any params parsed
+    # from the substring into {#params}.
+    #
+    # @param (see Mustermann.new)
+    # @return [Mustermann::StringScanner::ScanResult, nil] the matched substring, nil if it didn't match
+    def scan(pattern, **options)
+      track_result check(pattern, **options)
+    end
+
+    # Checks if the given pattern matches any substring starting at any position after the current position.
+    #
+    # If it does, it will advance the current {#position} to the end of the substring and merges any params parsed
+    # from the substring into {#params}.
+    #
+    # @param (see Mustermann.new)
+    # @return [Mustermann::StringScanner::ScanResult, nil] the matched substring, nil if it didn't match
+    def scan_until(pattern, **options)
+      result, prefix = check_until_with_prefix(pattern, **options)
+      track_result(prefix, result)
+    end
+
+    # Reverts the last operation that advanced the position.
+    #
+    # Operations advancing the position: {#terminate}, {#scan}, {#scan_until}, {#getch}.
+    # @return [Mustermann::StringScanner] the scanner itself
+    def unscan
+      raise ScanError, 'unscan failed: previous match record not exist' if @history.empty?
+      previous = @history[0..-2]
+      reset
+      previous.each { |r| track_result(*r) }
+      self
+    end
+
+    # Checks if the given pattern matches any substring starting at the current position.
+    #
+    # Does not affect {#position} or {#params}.
+    #
+    # @param (see Mustermann.new)
+    # @return [Mustermann::StringScanner::ScanResult, nil] the matched substring, nil if it didn't match
+    def check(pattern, **options)
+      params, length = create_pattern(pattern, **options).peek_params(rest)
+      ScanResult.new(self, @position, length, params) if params
+    end
+
+    # Checks if the given pattern matches any substring starting at any position after the current position.
+    #
+    # Does not affect {#position} or {#params}.
+    #
+    # @param (see Mustermann.new)
+    # @return [Mustermann::StringScanner::ScanResult, nil] the matched substring, nil if it didn't match
+    def check_until(pattern, **options)
+      check_until_with_prefix(pattern, **options).first
+    end
+
+    def check_until_with_prefix(pattern, **options)
+      start      = @position
+      @position += 1 until eos? or result = check(pattern, **options)
+      prefix     = ScanResult.new(self, start, @position - start) if result
+      [result, prefix]
+    ensure
+      @position  = start
+    end
+
+    # Reads a single character and advances the {#position} by one.
+    # @return [Mustermann::StringScanner::ScanResult, nil] the character, nil if at end of string
+    def getch
+      track_result ScanResult.new(self, @position, 1) unless eos?
+    end
+
+    # Appends the given string to the string being scanned
+    #
+    # @example
+    #   require 'mustermann/string_scanner'
+    #   scanner = Mustermann::StringScanner.new
+    #   scanner << "foo"
+    #   scanner.scan(/.+/) # => "foo"
+    #
+    # @param [String] string will be appended
+    # @return [Mustermann::StringScanner] the scanner itself
+    def <<(string)
+      @string << string
+      self
+    end
+
+    # @return [true, false] whether or not the end of the string has been reached
+    def eos?
+      @position >= @string.size
+    end
+
+    # @return [true, false] whether or not the current position is at the start of a line
+    def beginning_of_line?
+      @position == 0 or @string[@position - 1] == "\n"
+    end
+
+    # @return [String] outstanding string not yet matched, empty string at end of input string
+    def rest
+      @string[@position..-1] || ""
+    end
+
+    # @return [Integer] number of character remaining to be scanned
+    def rest_size
+      @position > size ? 0 : size - @position
+    end
+
+    # Allows to peek at a number of still unscanned characters without advacing the {#position}.
+    #
+    # @param [Integer] length how many characters to look at
+    # @return [String] the substring
+    def peek(length = 1)
+      @string[@position, length]
+    end
+
+    # Shorthand for accessing {#params}. Accepts symbols as keys.
+    def [](key)
+      params[key.to_s]
+    end
+
+    # (see #params)
+    def to_h
+      params.dup
+    end
+
+    # @return [String] the input string
+    # @see #initialize
+    # @see #<<
+    def to_s
+      @string.dup
+    end
+
+    # @return [Integer] size of the input string
+    def size
+      @string.size
+    end
+
+    # @!visibility private
+    def inspect
+      "#<%p %d/%d @ %p>" % [ self.class, @position, @string.size, @string ]
+    end
+
+    # @!visibility private
+    def create_pattern(pattern, **options)
+      PATTERN_CACHE.create_pattern(pattern, **options, **pattern_options)
+    end
+
+    # @!visibility private
+    def track_result(*results)
+      results.compact!
+      @history << results if results.any?
+      results.each do |result|
+        @params.merge! result.params
+        @position += result.length
+      end
+      results.last
+    end
+
+    private :create_pattern, :track_result, :check_until_with_prefix
+  end
+end

data/lib/mustermann/strscan.rb

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

data/mustermann-strscan.gemspec

@@ -0,0 +1,18 @@
+$:.unshift File.expand_path("../../mustermann/lib", __FILE__)
+require "mustermann/version"
+
+Gem::Specification.new do |s|
+  s.name                  = "mustermann-strscan"
+  s.version               = Mustermann::VERSION
+  s.author                = "Konstantin Haase"
+  s.email                 = "konstantin.mailinglists@googlemail.com"
+  s.homepage              = "https://github.com/rkh/mustermann"
+  s.summary               = %q{StringScanner for Mustermann}
+  s.description           = %q{Implements a version of Ruby's StringScanner that works with Mustermann patterns}
+  s.license               = 'MIT'
+  s.required_ruby_version = '>= 2.1.0'
+  s.files                 = `git ls-files`.split("\n")
+  s.test_files            = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables           = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.add_dependency 'mustermann', Mustermann::VERSION
+end

data/spec/string_scanner_spec.rb

@@ -0,0 +1,271 @@
+require 'support'
+require 'mustermann/string_scanner'
+
+describe Mustermann::StringScanner do
+  include Support::ScanMatcher
+
+  subject(:scanner) { Mustermann::StringScanner.new(example_string) }
+  let(:example_string) { "foo bar" }
+
+  describe :scan do
+    it { should scan("foo")     }
+    it { should scan(/foo/)     }
+    it { should scan(:name)     }
+    it { should scan(":name")   }
+
+    it { should_not scan(" ")   }
+    it { should_not scan("bar") }
+
+    example do
+      should scan("foo")
+      should scan(" ")
+      should scan("bar")
+    end
+
+    example do
+      scanner.position = 4
+      should scan("bar")
+    end
+
+    example do
+      should scan("foo")
+      scanner.reset
+      should scan("foo")
+    end
+  end
+
+  describe :check do
+    it { should check("foo")     }
+    it { should check(/foo/)     }
+    it { should check(:name)     }
+    it { should check(":name")   }
+
+    it { should_not check(" ")   }
+    it { should_not check("bar") }
+
+    example do
+      should     check("foo")
+      should_not check(" ")
+      should_not check("bar")
+      should     check("foo")
+    end
+
+    example do
+      scanner.position = 4
+      should check("bar")
+    end
+  end
+
+  describe :scan_until do
+    it { should scan_until("foo")     }
+    it { should scan_until(":name")   }
+    it { should scan_until(" ")       }
+    it { should scan_until("bar")     }
+    it { should_not scan_until("baz") }
+
+    example do
+      should scan_until(" ")
+      should check("bar")
+    end
+
+    example do
+      should scan_until(" ")
+      scanner.reset
+      should scan("foo")
+    end
+  end
+
+  describe :check_until do
+    it { should check_until("foo")     }
+    it { should check_until(":name")   }
+    it { should check_until(" ")       }
+    it { should check_until("bar")     }
+    it { should_not check_until("baz") }
+
+    example do
+      should check_until(" ")
+      should_not check("bar")
+    end
+  end
+
+  describe :getch do
+    example { scanner.getch.should be == "f" }
+
+    example do
+      scanner.scan("foo")
+      scanner.getch.should be == " "
+      should scan("bar")
+    end
+
+    example do
+      scanner.getch
+      scanner.reset
+      should scan("foo")
+    end
+  end
+
+  describe :<< do
+    example do
+      should_not scan_until("baz")
+      scanner << " baz"
+      scanner.to_s.should be == "foo bar baz"
+      should scan_until("baz")
+    end
+  end
+
+  describe :eos? do
+    it { should_not be_eos }
+    example do
+      scanner.position = 7
+      should be_eos
+    end
+  end
+
+  describe :beginning_of_line? do
+    let(:example_string) { "foo\nbar" }
+    it { should be_beginning_of_line }
+
+    example do
+      scanner.position = 2
+      should_not be_beginning_of_line
+    end
+
+    example do
+      scanner.position = 3
+      should_not be_beginning_of_line
+    end
+
+    example do
+      scanner.position = 4
+      should be_beginning_of_line
+    end
+  end
+
+  describe :rest do
+    example { scanner.rest.should be == "foo bar" }
+    example do
+      scanner.position = 4
+      scanner.rest.should be == "bar"
+    end
+  end
+
+  describe :rest_size do
+    example { scanner.rest_size.should be == 7 }
+    example do
+      scanner.position = 4
+      scanner.rest_size.should be == 3
+    end
+  end
+
+  describe :peek do
+    example { scanner.peek(3).should be == "foo" }
+
+    example do
+      scanner.peek(3).should be == "foo"
+      scanner.peek(3).should be == "foo"
+    end
+
+    example do
+      scanner.position = 4
+      scanner.peek(3).should be == "bar"
+    end
+  end
+
+  describe :inspect do
+    example { scanner.inspect.should be == '#<Mustermann::StringScanner 0/7 @ "foo bar">' }
+    example do
+      scanner.position = 4
+      scanner.inspect.should be == '#<Mustermann::StringScanner 4/7 @ "foo bar">'
+    end
+  end
+
+  describe :[] do
+    example do
+      should scan(:name)
+      scanner['name'].should be == "foo bar"
+    end
+
+    example do
+      should scan(:name, capture: /\S+/)
+      scanner['name'].should be == "foo"
+      should scan(" :name", capture: /\S+/)
+      scanner['name'].should be == "bar"
+    end
+
+    example do
+      should scan(":a",  capture: /\S+/)
+      should scan(" :b", capture: /\S+/)
+      scanner['a'].should be == "foo"
+      scanner['b'].should be == "bar"
+    end
+
+    example do
+      a = scanner.scan(":a",  capture: /\S+/)
+      b = scanner.scan(" :b", capture: /\S+/)
+      a.params['a'].should be == 'foo'
+      b.params['b'].should be == 'bar'
+      a.params['b'].should be_nil
+      b.params['a'].should be_nil
+    end
+
+    example do
+      result = scanner.check(":a",  capture: /\S+/)
+      result.params['a'].should be == 'foo'
+      scanner['a'].should be_nil
+    end
+
+    example do
+      should scan(:name)
+      scanner.reset
+      scanner['name'].should be_nil
+    end
+  end
+
+  describe :unscan do
+    example do
+      should scan(:name, capture: /\S+/)
+      scanner['name'].should be == "foo"
+      should scan(" :name", capture: /\S+/)
+      scanner['name'].should be == "bar"
+      scanner.unscan
+      scanner['name'].should be == "foo"
+      scanner.rest.should be == " bar"
+    end
+
+    example do
+      should scan_until(" ")
+      scanner.unscan
+      scanner.rest.should be == "foo bar"
+    end
+
+    example do
+      expect { scanner.unscan }.to raise_error(Mustermann::StringScanner::ScanError,
+        'unscan failed: previous match record not exist')
+    end
+  end
+
+  describe :terminate do
+    example do
+      scanner.terminate
+      scanner.should be_eos
+    end
+  end
+
+  describe :to_h do
+    example { scanner.to_h.should be == {} }
+    example do
+    end
+  end
+
+  describe :to_s do
+    example { scanner.to_s.should be == "foo bar" }
+  end
+
+  describe :clear_cache do
+    example do
+      scanner.scan("foo")
+      Mustermann::StringScanner.clear_cache
+      Mustermann::StringScanner.cache_size.should be == 0
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: mustermann-strscan
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Konstantin Haase
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mustermann
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+description: Implements a version of Ruby's StringScanner that works with Mustermann
+  patterns
+email: konstantin.mailinglists@googlemail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/mustermann/string_scanner.rb
+- lib/mustermann/strscan.rb
+- mustermann-strscan.gemspec
+- spec/string_scanner_spec.rb
+homepage: https://github.com/rkh/mustermann
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: StringScanner for Mustermann
+test_files:
+- spec/string_scanner_spec.rb
+has_rdoc: