pattern_matcher 0.1.0 → 0.1.1

data/README.md

@@ -3,4 +3,143 @@ Pattern Matcher
 
 Gem to help manage, test and run regex pattern matchers for a given project.
 
-Gem can be found on rubygems at https://rubygems.org/gems/pattern_matcher
+Gem can be found on rubygems at https://rubygems.org/gems/pattern_matcher
+
+
+=========
+**Code coverage for Ruby 1.9**
+
+  * [Source Code]
+
+[Source Code]: https://github.com/aparker/pattern_matcher "Source Code @ GitHub"
+[leak-stopper]: https://rubygems.org/gems/leak_stopper "LeakStopper"
+
+
+PatternMatcher is a code tool that provides a framework for the storing, testing and running of common patterns.  It can be used
+in a one-off fashion from the command line or can be included inside of your application.  The underlying code uses regular 
+expression matching but provides more human readable responses when matches are found.
+
+The intention is to provide structured management of system-wide matching strings that can then be easily reused and tested to 
+ensure that intended behavior is maintained throughout the lifespan of the project.
+
+PatternMatcher is a result of abstracting the core logic for the [leak-stopper] gem and, as a result has some behavior that, while generalized, is intended to assist the functionality that LeakStopper intended to provide.
+
+Getting started (code)
+---------------
+
+1. Add pattern_matcher to your `Gemfile` and `bundle install`:
+
+2. Initialize Pattern pattern_matcher
+
+```ruby
+	PatternMatcher.configure do |config|
+    config.patterns_yml = File.join(File.dirname(__FILE__), "config", "patterns.yml")
+  end
+```
+
+3. Call `match_patterns_to_text` to get a list of `PatternMatcher::Match` objects
+
+```ruby
+	matches = PatternMatcher.match_patterns_to_text(some_text)
+	matches.each do |match|
+		puts match.to_s
+	end
+```
+
+4. Programatically `add_pattern_hash` to expand the scope of patterns tested
+
+```ruby
+  hash = {:pattern_id => "ANumber", :name => "A Number", :regex => "[0-9]", :description => "Just a single number."}
+  PatternMatcher.add_pattern_hash(hash)
+```
+
+Getting started (command line)
+---------------
+
+1. download pattern_matcher by calling `gem install pattern_matcher`:
+
+```ruby
+	gem 'simplecov', :require => false, :group => :test
+```
+
+## Example patterns.yml File
+
+The `patterns.yml` file is where patterns can be defined and maintained.  It looks like this:
+
+```
+patterns:
+  SSN:
+    name: Social Security Number
+    regex: '[0-9]{3}-[0-9]{2}-[0-9]{4}'
+    description: Social Security Numbers.
+    valid_examples: ['111-22-1111', '222-11-2222']
+  PhoneNumber:
+    name: Seven Digit Phone Number
+    regex: '[0-9]{3}-[0-9]{4}'
+    description: A seven digit US phone number.
+    valid_examples: ['111-1234', '867-5309']
+```
+
+**Pattern Key** - Below the patterns node is the Pattern Key.  This must be unique and identifies the pattern attributes on
+subsiquent nodes.
+
+**name** - The descriptitive title for the type of pattern this is.
+
+**regex** - A regular expression describing the pattern that is to be matched.  This is a _required_ part of the pattern and is
+used directly to identify matches within analyzed text.
+
+**description** - A detailed description of what the pattern is.
+
+**valid_examples** - A list of known matches that the system can test the regex pattern against to ensure expected behavior.
+
+
+## The PatternMatcher::Match object
+
+Think of the PatternMatcher::Match object as an extension of the MatchData class, one that provides a deeper explanation.
+
+The **Match** object returns the Name of the match along with a copy of the regex MatchData object.
+
+## Configuration
+
+To provide an appropriate level of flexability and ease of use, there are a number of things that can be set as configuration 
+options on ProjectManager.
+
+**patterns_yml** - The source of the patterns that are to be applied to the matcher.
+
+
+## List/Report Known Patterns
+
+**List Paterns**  - To view an entire list of the pattern keys that PatternMatcher knows about you can
+
+```
+  > PatternMatcher.patterns.keys
+  > [SSN, PhoneNumber, ...]
+```
+
+**Detailed List of Patterns**  - looks at each pattern and calls `.to_s` on each pattern
+
+```
+  > PatternMatcher.patterns.to_s
+  > "Social Security Number (true) -- [0-9]{3}-[0-9]{2}-[0-9]{4} -- Social Security Numbers.
+     Seven Digit Phone Number (true) -- [0-9]{3}-[0-9]{4} -- A seven digit US phone number."
+```
+
+**Details of a Single Pattern**  - a richer view into the pattern.
+
+```
+  > a_pattern = Pattern.new({:pattern_id => SSN, "name" => "Social Security Number", "regex" => "[0-9]{3}-[0-9]{2}-[0-9]{4}", "description" => "A Social Security Number."})
+  > a_pattern.to_s
+  > "Social Security Number (true) -- [0-9]{3}-[0-9]{2}-[0-9]{4} -- A Social Security Number"
+```
+
+
+## Validate Patterns
+
+#### Debugging Patterns
+
+A core role of PatternMatcher is to help maintain the patterns that are important to you.  This means making them easy to see and understand those patterns along with being able to have confidence that they are behaving as expected.
+
+```
+> PatternMatcher.proof_patterns
+> {"EmailAddress" => ["something#mail.com"]}
+```

data/lib/pattern_matcher.rb

@@ -8,12 +8,13 @@ require "pattern_matcher/config"
 require "pattern_matcher/pattern"
 require "pattern_matcher/match"
 require "pattern_matcher/matcher"
+require "pattern_matcher/pattern_manager"
 
 module PatternMatcher
 
   def self.configure
     yield configuration if block_given?
-    @patterns = Matcher.initialize_patterns
+    @patterns = PatternManager.initialize_patterns
   end
 
   def self.configuration
@@ -26,7 +27,7 @@ module PatternMatcher
 
   def self.match_patterns_to_text(text)
     matches = []
-    @patterns.each do |pattern|
+    @patterns.to_a.each do |pattern|
       regex_match = Matcher.match_pattern_in_text(pattern, text)
       matches << Match.new({:name => pattern.name, :regex_match => regex_match}) if regex_match
     end
@@ -34,12 +35,22 @@ module PatternMatcher
   end
 
   def self.proof_patterns
-    pattern_errors = []
+    pattern_errors = {}
     @patterns.each do |pattern|
-      pattern_errors << pattern.validate_all_examples if pattern.is_valid?
+      failures = pattern.validate_all_examples
+      pattern_errors[pattern.pattern_id] = failures if (pattern.is_valid? && failures.count > 0)
     end
     pattern_errors
   end
 
+  def self.patterns
+    @patterns
+  end
+
+  def self.add_pattern_hash(hash)
+    pattern = Pattern.new(hash)
+    @patterns.add_pattern pattern if pattern.is_valid?
+  end
+
 end
 

data/lib/pattern_matcher/match.rb

@@ -5,9 +5,15 @@ module PatternMatcher
 
     def initialize(hash)
       if hash.is_a?(Hash)
-        @name = hash[:name]
-        @regex_match = hash[:regex_match]
+  		extract_attributes_from_hash hash
       end
     end
+
+    private
+
+    def extract_attributes_from_hash(hash)
+    	@name = hash[:name]
+        @regex_match = hash[:regex_match]
+    end
   end
 end

data/lib/pattern_matcher/matcher.rb

@@ -16,11 +16,6 @@ module PatternMatcher
       return regex.match text if is_valid_regex?(regex) && is_valid_text?(text)
     end
 
-    def self.initialize_patterns
-      raw_pattern_hash = load_yaml || {}
-      @@patterns = hash_to_patterns_array(raw_pattern_hash)
-    end
-
     private
 
     def self.is_valid_regex_string?(string)
@@ -35,21 +30,5 @@ module PatternMatcher
       !text.nil? && !text.empty? 
     end
 
-    def self.load_yaml
-      YAML.load_file(PatternMatcher.configuration.patterns_yml) if PatternMatcher.configuration.patterns_yml
-    end
-
-    def self.hash_to_patterns_array(hash)
-      patterns = []
-      hash_patterns(hash).each do |a_pattern|
-        patterns << PatternMatcher::Pattern.new(a_pattern[1])
-      end
-      patterns
-    end
-
-    def self.hash_patterns(hash)
-        (hash["patterns"] || {}) if !hash.nil?
-    end
-
   end
 end

data/lib/pattern_matcher/pattern.rb

@@ -1,11 +1,12 @@
 module PatternMatcher
   class Pattern
 
-    attr_accessor :name, :regex_string, :description, :valid_examples
+    attr_accessor :pattern_id, :name, :regex_string, :description, :valid_examples
     attr_accessor :regex
 
     def initialize(hash)
-      if !hash.nil?
+      if hash.is_a?(Hash)
+        @pattern_id = hash[:pattern_id]
         @name = hash["name"]
         @regex_string = hash["regex"]
         @regex = Matcher.string_to_regex(@regex_string)
@@ -22,8 +23,22 @@ module PatternMatcher
       failures
     end
 
+    def to_s
+      "#{@name} (#{is_valid?}) -- #{@regex_string} -- #{@description}"
+    end
+
+    def to_h
+      {
+        :name => @name,
+        :is_valid => is_valid?,
+        :regex_string => @regex_string,
+        :description => @description,
+        :valid_examples => @valid_examples
+      }
+    end
+
     def is_valid?
-        return !@regex.nil?
+        return !@regex.nil? && !@pattern_id.nil?
     end
 
     def pattern_example_valid?(example)

data/lib/pattern_matcher/pattern_manager.rb

@@ -0,0 +1,64 @@
+module PatternMatcher
+  class PatternManager
+
+    attr_accessor :patterns_hash
+
+    def self.initialize_patterns
+      raw_pattern_hash = load_yaml || {}
+      PatternManager.new_from_raw_hash raw_pattern_hash
+    end
+
+    def self.new_from_raw_hash(raw_hash)
+      patterns = {}
+      hash_patterns(raw_hash).each_pair do |a_key, a_pattern|
+        a_pattern[:pattern_id] = a_key
+        patterns[a_key] = PatternMatcher::Pattern.new(a_pattern)
+      end
+      PatternManager.new(patterns)
+    end
+
+    def initialize(pattern_hash)
+      @patterns_hash = pattern_hash
+    end
+
+    def add_pattern(pattern)
+      @patterns_hash[pattern.pattern_id] = pattern if pattern.is_valid?
+    end
+
+    def keys
+      @patterns_hash.keys
+    end
+
+    def to_s
+      ret_str = ""
+      @patterns_hash.values.each do |pattern|
+        ret_str += pattern.to_s + "\n"
+      end
+      ret_str
+    end
+
+    def to_a
+      @patterns_hash.values
+    end
+
+    def each
+      @patterns_hash.values.each do |pattern|
+        yield pattern
+      end
+    end
+
+    def count
+      @patterns_hash.keys.count || 0
+    end
+
+    private
+
+    def self.load_yaml
+      YAML.load_file(PatternMatcher.configuration.patterns_yml) if PatternMatcher.configuration.patterns_yml
+    end
+
+    def self.hash_patterns(hash)
+        (hash["patterns"] || {}) if !hash.nil?
+    end
+  end
+end

data/lib/pattern_matcher/version.rb

@@ -1,3 +1,3 @@
 module PatternMatcher
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pattern_matcher
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-01 00:00:00.000000000 Z
+date: 2014-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -69,11 +69,12 @@ files:
 - lib/pattern_matcher/match.rb
 - lib/pattern_matcher/matcher.rb
 - lib/pattern_matcher/pattern.rb
+- lib/pattern_matcher/pattern_manager.rb
 - lib/pattern_matcher/version.rb
 - lib/pattern_matcher.rb
 - LICENSE
 - README.md
-homepage: https://rubygems.org/gems/pattern_matcher
+homepage: https://github.com/aparkerw/pattern_matcher
 licenses:
 - MIT
 post_install_message: