lib/gscraper/search/query.rb in gscraper-0.2.4 vs lib/gscraper/search/query.rb in gscraper-0.3.0

@@ -1,7 +1,6 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # This program is free software; you can redistribute it and/or modify
@@ -15,11 +14,10 @@
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'gscraper/search/result'
 require 'gscraper/search/page'
 require 'gscraper/sponsored_ad'
@@ -80,14 +78,81 @@
 
       # Search for results containing numbers between the range
       attr_accessor :numeric_range
 
       #
-      # Creates a new Query object from the given search options. If a
-      # block is given, it will be passed the newly created Query object.
+      # Creates a new query.
       #
-      def initialize(options={},&block)
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [String] :query
+      #   The search query.
+      #
+      # @option options [String] :link
+      #   Search for results which link to the specified URI.
+      #
+      # @option options [String] :related
+      #   Search for results which relate to the specified URI.
+      #
+      # @option options [String] :info
+      #   Return information about the specified URI.
+      #
+      # @option options [String] :site
+      #   Limit results to the specified site.
+      #
+      # @option options [String] :filetype
+      #   Limit results to those with the specified file-type.
+      #
+      # @option options [String, Array] :allintitle
+      #   Search for results with all of the keywords appearing in the
+      #   title.
+      #
+      # @option options [String] :intitle
+      #   Search for results with the keyword appearing in the title.
+      #
+      # @option options [String, Array] :allintext
+      #   Search for results with all of the keywords appearing in the text.
+      #
+      # @option options [String] :intext
+      #   Search for results with the keyword appearing in the text.
+      #
+      # @option options [String, Array] :allinanchor
+      #   Search for results with all of the keywords appearing in the
+      #   text of links.
+      #
+      # @option options [String] :inanchor
+      #   Search for results with the keyword appearing in the text of
+      #   links.
+      #
+      # @option options [String] :exact_phrase
+      #   Search for results containing the specified exact phrase.
+      #
+      # @option options [String, Array] :with_words
+      #   Search for results containing all of the specified words.
+      #
+      # @option options [String, Array] :without_words
+      #   Search for results not containing any of the specified words.
+      #
+      # @option options [Range] :numeric_range
+      #   Search for results contain numbers that fall within the
+      #   specified Range.
+      #
+      # @option options [String] :define
+      #   Search for results containing the definition of the specified
+      #   keyword.
+      #
+      # @yield [query]
+      #   If a block is given, it will be passed the new query.
+      #
+      # @yieldparam [Query] query
+      #   The new query.
+      #
+      # @return [Query]
+      #   The new query.
+      #
+      def initialize(options={})
         @query = options[:query]
 
         @link = options[:link]
         @related = options[:related]
         @info = options[:info]
@@ -98,23 +163,29 @@
         @intitle = options[:intitle]
         @allinurl = options[:allinurl]
         @inurl = options[:inurl]
         @allintext = options[:allintext]
         @intext = options[:intext]
+        @allinanchor = options[:allinanchor]
+        @inanchor = options[:inanchor]
 
         @exact_phrase = options[:exact_phrase]
         @with_words = options[:with_words]
         @without_words = options[:without_words]
 
         @numeric_range = options[:numeric_range]
+        @define = options[:define]
 
-        block.call(self) if block
+        yield self if block_given?
       end
 
       #
-      # Returns the query expression.
+      # The query expression.
       #
+      # @return [String]
+      #   The expression representing the query.
+      #
       def expression
         expr = []
 
         append_modifier = lambda { |name|
           modifier = format_modifier(instance_variable_get("@#{name}"))
@@ -140,11 +211,15 @@
         append_modifier.call(:intitle)
         append_options.call(:allinurl)
         append_modifier.call(:inurl)
         append_options.call(:allintext)
         append_modifier.call(:intext)
+        append_options.call(:allinanchor)
+        append_modifier.call(:inanchor)
 
+        append_modifier.call(:define)
+
         if @exact_phrase
           expr << "\"#{@exact_phrase}\""
         end
 
         if @with_words.kind_of?(Array)
@@ -162,17 +237,35 @@
         return expr.join(' ')
       end
 
       protected
 
+      #
+      # Formats the value for a search modifer.
+      #
+      # @param [Regexp, String]
+      #   The value for the search modifier.
+      #
+      # @return [String]
+      #   The formatted value.
+      #
       def format_modifier(value)
         if value.kind_of?(Regexp)
           return value.source
         else
           return value.to_s
         end
       end
 
+      #
+      # Formats the value(s) for a search option.
+      #
+      # @param [Array, Regexp, String]
+      #   The value(s) for the search modifier.
+      #
+      # @return [String]
+      #   The formatted value.
+      #
       def format_options(value)
         if value.kind_of?(Array)
           return value.map { |element|
             format_modifier(element)
           }.join(' ')