README.md in search_lingo-1.0.0.beta2 vs README.md in search_lingo-1.0.0.beta3

- old
+ new

@@ -11,10 +11,13 @@ The way the searches themselves are performed lies outside the scope of this project. Although originally designed to work with basic searching with ActiveRecord models, it should be usable with other data stores provided they let you chain queries together onto a single object. +Be advised this software is still in beta release, and some of the internals +are still subject to significant change. + ## Installation Add this line to your application's Gemfile: ```ruby @@ -29,10 +32,55 @@ $ gem install search_lingo ## Usage +Here is a simple example. + + class Task < ActiveRecord::Base + end + + class TaskSearch < SearchLingo::AbstractSearch + def default_parse(token) + [:where, 'tasks.name LIKE ?', "%#{token}%"] + end + end + + TaskSearch.new('foo bar', Task).results + # => Task.where('tasks.name LIKE ?', '%foo%').where('tasks.name LIKE ?', '%bar%') + TaskSearch.new('"foo bar"', Task).results + # => Task.where('tasks.name LIKE ?', '%foo bar%') + +And here is a more complex example. + + class Category < ActiveRecord::Base + has_many :tasks + end + + class Task < ActiveRecord::Base + belongs_to :category + end + + class TaskSearch < SearchLingo::AbstractSearch + parser do |token| + token.match /\Acategory:\s*"?(.*?)"?\z/ do |m} + [:where, { categories: { name: m[1] } }] + end + end + + def default_parse(token) + [:where, 'tasks.name LIKE ?', "%#{token}%"] + end + + def scope + @scope.includes(:category).references(:category) + end + end + + TaskSearch.new('category: "foo bar" baz', Task).results + # => Task.includes(:category).references(:category).where(categories: { name: 'foo bar' }).where('tasks.name LIKE ?', '%baz%') + Create a class which inherits from SearchLingo::AbstractSearch. Provide an implementation of <code>#default_parse</code> in that class. Register parsers for specific types of search tokens using the <code>parser</code> class method. Instantiate your search class by passing in the query string and the scope on @@ -55,25 +103,58 @@ important that this method be implemented in such a way that it always succeeds.) ## Search Classes -Search classes should inherit from SearchLingo::AbstractSearch and they should -override the <code>#default_parse</code> instance method. It is important that -this method be defined in such a way that it always succeeds, as the results -will be sent to the query object via <code>#public_send</code>. In addtion, the -class method <code>parser</code> can be used to declare additional parsers that -should be used by the search class. (See the section "Parsing" for more -information on what makes a suitable parser.) +Search classes should inherit from SearchLogic::AbstractSearch, and they must +provide their own implementation of <code>#default_parse</code>. Optionally, a +search class may also use the parse class method to add specialized parsers for +handling tokens that match specific patterns. As each token is processed, the +search class will first run through the specialized parsers. If none of them +succeed, it will fall back on the <code>#default_parse</code> method. See the +section "Parsing" for more information on how parsers work and how they should +be structured. +## Tokenization + +Queries are comprised of zero or more tokens separated by white space. A token +has a term and an optional operator. (A simple token has no operator; a +compound token does.) A term can be a single word or multiple words joined by +spaces and contained within double quotes. For example <code>foo</code> and +<code>"foo bar baz"</code> are both single terms. An operator is one or more +alphanumeric characters followed by a colon and zero or more spaces. + + QUERY := TOKEN* + TOKEN := (OPERATOR ':' [[:space:]]*)? TERM + OPERATOR := [[:alnum:]]+ + TERM := '"' [^"]* '"' | [[:graph:]]+ + +The following are all examples of tokens: + +* <code>foo</code> +* <code>"foo bar"</code> +* <code>foo: bar</code> +* <code>foo: "bar baz"</code> + +(If you need a term to equal something that might otherwise be interpreted as +an operator, you can enclose the term in double quotes, e.g., while <code>foo: +bar</code> would be interpreted a single compound token, <code>"foo:" +bar</code> would be treated as two distinct simple tokens.) + +Tokens are passed to parsers as instances of the Token class. The Token class +provides <code>#operator</code> and <code>#term</code> methods, but delegates +all other behavior to the String class. Consequently, when writing parsers, you +have the option of either interacting with the token as a raw String or making +use of the extra functionality of Tokens. + ## Parsers Any object that can respond to the <code>#call</code> method can be used as a parser. If the parser succeeds, it should return an Array of arguments that can be sent to the query object using <code>#public_send</code>, e.g., <code>[:where, { id: 42 }]</code>. If the parser fails, it should return a -falsey value (typically nil). +falsey value. For very simple parsers which need not be reusable, you can pass the parsing logic to the <code>parser</code> method as a block: class MySearch < SearchLingo::AbstractSearch @@ -126,37 +207,9 @@ end class CategorySearch < SearchLingo::AbstractSearch parser Parsers::IdParser.new :categories end - -## Tokenization - -Queries are comprised of one or more tokens separated by spaces. A simple token -is a term which can be a single word (or date, number, etc.) or multiple terms -within a pair of double quotes. A compound token is a simple token preceded by -an operator followed by zero or more spaces. - - QUERY := TOKEN* - TOKEN := COMPOUND_TOKEN | TERM - COMPOUND_TOKEN := OPERATOR TERM - OPERATOR := [[:graph:]]+: - TERM := "[^"]*" | [[:graph:]]+ - -Terms can be things like: - -* foo -* "foo bar" -* 6/14/15 -* 1000.00 - -Operators can be things like: - -* foo: -* bar_baz: - -(If you want to perform a query with a term that could potentially be parsed as -an operator, you would place the term in quotes, i.e., "foo:".) ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.