textquery 0.1.0

data/README.rdoc

@@ -0,0 +1,51 @@
+= TextQuery
+
+Does it match? When regular expressions are not enough, textquery is the answer. For
+example, regular expressions cannot evaluate recursive rules and often result in
+overly verbose and complicated expressions.
+
+Textquery is a simple PEG grammar with support for:
+- AND (spaces are implicit AND's)
+- OR
+- NOT (- is an alias)
+- 'quoted strings'
+
+== Example
+
+  TextQuery.new("'to be' OR NOT 'to_be'").match?("to be")   # => true
+
+  TextQuery.new("-test").match?("some string of text")      # => true
+  TextQuery.new("NOT test").match?("some string of text")   # => true
+
+  TextQuery.new("a AND b").match?("b a")                    # => true
+  TextQuery.new("a AND b").match?("a c")                    # => false
+
+  q = TextQuery.new("a AND (b AND NOT (c OR d))")
+  q.match?("d a b")                                         # => false
+  q.match?("b")                                             # => false
+  q.match?("a b cdefg")                                     # => true
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009 Ilya Grigorik
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "textquery"
+    gemspec.summary = "Evaluate any text against a collection of match rules"
+    gemspec.description = gemspec.summary
+    gemspec.email = "ilya@igvita.com"
+    gemspec.homepage = "http://github.com/igrigorik/textquery"
+    gemspec.authors = ["Ilya Grigorik"]
+    gemspec.add_dependency("treetop")
+    gemspec.rubyforge_project = "textquery"
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/textquery.rb

@@ -0,0 +1,3 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require "textquery/textquery.rb"

data/lib/textquery/textquery.rb

@@ -0,0 +1,40 @@
+require 'treetop'
+
+class WordMatch < Treetop::Runtime::SyntaxNode
+  def eval(text)
+    not text.match(/^#{query}\s|\s#{query}\s|\s#{query}$|^#{query}$/).nil?
+  end
+
+  def query
+    Regexp.escape(text_value)
+  end
+end
+
+Treetop.load File.dirname(__FILE__) + "/textquery_grammar"
+
+class TextQuery
+  def initialize(query = '')
+    @parser = TextQueryGrammarParser.new
+    @query  = nil
+
+    parse(query) if not query.empty?
+  end
+
+  def parse(query)
+    @query = @parser.parse(query)
+    if not @query
+      puts @parser.terminal_failures.join("\n")
+    end
+    @query
+  end
+
+  def eval(input)
+    if @query
+      @query.eval(input)
+    else
+      puts 'no query specified'
+    end
+  end
+  alias :match? :eval
+  
+end

data/lib/textquery/textquery_grammar.treetop

@@ -0,0 +1,77 @@
+grammar TextQueryGrammar
+
+  rule expression
+     logical / value
+  end
+
+  rule logical
+    op1:value space operator:binary space op2:expression {
+      def eval(text)
+        operator.eval(op1.eval(text), op2.eval(text))
+      end
+    }
+    /
+    op1:value [\s]+ op2:expression {
+        def eval(text)
+          op1.eval(text) && op2.eval(text)
+        end
+      }
+  end
+
+  rule binary
+    'AND' {
+      def eval(a,b)
+        a && b
+      end
+    }
+    /
+    'OR' {
+      def eval(a,b)
+        a || b
+      end
+    }
+  end
+
+  rule unary
+    ('-' / 'NOT') {
+      def eval(a)
+        not a
+      end
+    }
+  end
+
+  rule space
+    [\s]*
+  end
+
+  rule word
+    [^\s\(\)]+ <WordMatch>
+  end
+
+  rule words
+    [^\']+ <WordMatch>
+  end
+
+  rule value
+    '(' space expression space ')' {
+       def eval(text)
+         expression.eval(text)
+       end
+    }
+    /
+    operator:unary space value {
+      def eval(text)
+        operator.eval(value.eval(text))
+      end
+    }
+    /
+    "'" space words space "'" {
+      def eval(text)
+        words.eval(text)
+      end
+    }
+    /
+    word
+  end
+
+end

data/spec/textquery_spec.rb

@@ -0,0 +1,174 @@
+require "rubygems"
+require "spec"
+require "pp"
+
+require "lib/textquery"
+
+# Resources:
+# - http://github.com/nathansobo/treetop
+# - http://github.com/nathansobo/treetop/blob/master/examples/lambda_calculus/arithmetic.treetop
+# - http://snippets.dzone.com/tag/Treetop
+# - http://treetop.rubyforge.org/index.html
+# - http://en.wikipedia.org/wiki/Parsing_expression_grammar
+#
+
+describe TextQuery do
+  before(:all) do
+    @parser = TextQuery.new
+  end
+
+  def parse(input)
+    result = @parser.parse(input)
+    unless result
+      puts @parser.terminal_failures.join("\n")
+    end
+    result
+  end
+
+  it "should accept any non space separated sequence" do
+    %w[query 123 text123 #tag $%*].each do |input|
+      @parser.parse(input).text_value.should == input
+      parse(input).eval(input).should be_true
+    end
+  end
+
+  it "should look for exact word boundary match" do
+    parse("text").eval("textstring").should be_false
+    parse("text").eval("stringtext").should be_false
+    parse("text").eval("some textstring").should be_false
+    parse("text").eval("string of texts stuff").should be_false
+    parse("$^").eval("string of $^* stuff").should be_false
+  end
+
+  it "should accept logical AND" do
+    parse("a AND b").eval("c").should be_false
+    parse("a AND b").eval("a").should be_false
+    parse("a AND b").eval("b").should be_false
+
+    parse("a AND b").eval("a b").should be_true
+    parse("a AND b").eval("a c b").should be_true
+  end
+  
+  it "should accept logical OR" do
+    parse("a OR b").eval("c").should be_false
+    parse("a OR b").eval("a").should be_true
+    parse("a OR b").eval("b").should be_true
+
+    parse("a OR b").eval("a b").should be_true
+    parse("a OR b").eval("a c b").should be_true
+  end
+
+  it "should give precedence to AND" do
+    # a AND (b OR c) == a AND b OR c
+    parse("a AND b OR c").eval("a b c").should be_true
+    parse("a AND b OR c").eval("a b").should be_true
+    parse("a AND b OR c").eval("a c").should be_true
+
+    parse("a AND b OR c").eval("b c").should be_false
+    parse("a AND b OR c").eval("c").should be_false
+    parse("a AND b OR c").eval("b").should be_false
+  end
+
+  it "should accept logical NOT" do
+    %w[- NOT].each do |operator|
+      parse("#{operator} a").eval("a").should be_false
+      parse("#{operator} #{operator} a").eval("a").should be_true
+
+      parse("#{operator} a OR a").eval("a").should be_true
+      parse("a OR #{operator} a").eval("a").should be_true
+
+      parse("b AND #{operator} a").eval("b").should be_true
+      parse("b AND #{operator} a").eval("a").should be_false
+    end
+  end
+
+  it "should evaluate sub expressions" do
+    parse("(a AND b)").eval("a b").should be_true
+    parse("(a OR b)").eval("a b").should be_true
+    parse("(a AND NOT b)").eval("a b").should be_false
+
+    parse("(a AND b) OR c").eval("a b c").should be_true
+    parse("(a AND b) OR c").eval("a b").should be_true
+    parse("(a AND b) OR c").eval("a c").should be_true
+    
+    parse("(a AND b) OR c").eval("c").should be_true
+    parse("a AND (b OR c)").eval("c").should be_false
+    
+    # for the win...
+    parse("a AND (b AND (c OR d))").eval("d a b").should be_true
+  end
+
+  it "should not trip up on placement of brackets" do
+    parse("a AND (-b)").eval("a b").should    == parse("a AND -(b)").eval("a b")
+    parse("(-a) AND b").eval("a b").should    == parse("-(a) AND b").eval("a b")
+    parse("-(a) AND -(b)").eval("a b").should == parse("(-a) AND (-b)").eval("a b")
+
+    parse("a OR (-b)").eval("a b").should     == parse("a OR -(b)").eval("a b")
+    parse("(-a) OR b").eval("a b").should     == parse("-(a) OR b").eval("a b")
+    parse("(-a) OR (-b)").eval("a b").should  == parse("-(a) OR -(b)").eval("a b")
+
+    parse("a AND (b OR c)").eval("a b c").should be_true
+    parse("a AND (b OR c)").eval("a b").should be_true
+    parse("a AND (b OR c)").eval("a c").should be_true
+
+    parse("(NOT a) OR a").eval("a").should be_true
+    parse("(NOT a) AND (NOT b) AND (NOT c)").eval("b").should be_false
+    parse("a AND (b AND (c OR NOT d))").eval("a b d").should be_false
+    parse("a AND (b AND (c OR NOT d))").eval("a b c").should be_true
+    parse("a AND (b AND (c OR NOT d))").eval("a b e").should be_true
+    
+    parse("a AND (b AND NOT (c OR d))").eval("a b").should be_true
+    parse("a AND (b AND NOT (c OR d))").eval("a b c").should be_false
+    parse("a AND (b AND NOT (c OR d))").eval("a b d").should be_false
+
+    parse("-a AND -b AND -c").eval("e").should be_true
+    parse("(-a) AND (-b) AND (-c)").eval("e").should be_true
+    parse("(NOT a) AND (NOT b) AND (NOT c)").eval("e").should be_true
+    parse("NOT a AND NOT b AND NOT c").eval("e").should be_true
+  end
+
+  it "should accept quoted strings" do
+    parse("'some text'").eval("some text").should be_true
+    parse("'some text string'").eval("some text").should be_false
+
+    parse("'some text string'").eval("some text 1 string").should be_false
+    parse("-'some text string'").eval("some text 1 string").should be_true
+
+    parse("a AND -'a b'").eval("a b c").should be_false
+    parse("a AND -'a b'").eval("a c b").should be_true
+
+    parse("(a OR b) AND (-'a b c')").eval("a b c").should be_false
+    parse("(a OR b) AND (-'a b c')").eval("a c b").should be_true
+    parse("(a AND b) AND (-'a b c')").eval("a c b").should be_true
+
+    # shakespeare got nothin' on ruby...
+    parse("'to be' OR NOT 'to be'").eval("to be").should be_true
+  end
+
+  it "should treat spaces as implicit ANDs" do
+    parse("a b").eval("a c b").should be_true
+    parse("b a c").eval("a c b").should be_true
+    parse("b a c").eval("a c").should be_false
+
+    parse("some text AND 'exact match'").eval("some exact match text").should be_true
+    parse("some text AND 'exact match'").eval("some exact text match").should be_false
+
+    parse("some text AND -'exact match'").eval("some exact text match").should be_true
+    parse("some text AND -'exact match'").eval("some exact match").should be_false
+  end
+
+  it "should wrap the grammar API" do
+    TextQuery.new("'to be' OR NOT 'to_be'").match?("to be").should be_true
+    TextQuery.new("-test").match?("some string of text").should be_true
+    TextQuery.new("NOT test").match?("some string of text").should be_true
+    TextQuery.new("a AND b").match?("b a").should be_true
+    TextQuery.new("a AND b").match?("a c").should be_false
+
+    q = TextQuery.new("a AND (b AND NOT (c OR d))")
+    q.match?("d a b").should be_false
+    q.match?("b").should be_false
+    q.match?("a b cdefg").should be_true
+    q.eval("a b cdefg").should be_true
+
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: textquery
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ilya Grigorik
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-28 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: treetop
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Evaluate any text against a collection of match rules
+email: ilya@igvita.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/textquery.rb
+- lib/textquery/textquery.rb
+- lib/textquery/textquery_grammar.treetop
+- spec/textquery_spec.rb
+has_rdoc: true
+homepage: http://github.com/igrigorik/textquery
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: textquery
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Evaluate any text against a collection of match rules
+test_files: 
+- spec/textquery_spec.rb