.\" DO NOT MODIFY THIS FILE! it was generated by rd2 .TH google.rb 1 "February 2006" .SH NAME .PP Ruby/Google .SH SYNOPSIS .nf \& require 'google' \& \& KEY = File.open("#{ENV['HOME']}/.google_key") {|kf| kf.readline.chomp} \& \& query = ARGV.shift || 'ruby programming language' \& google = Google::Search.new(KEY) \& google.utf8('iso\-8859\-15') \& \& i = 0 \& q = google.search(query) \& q.resultElements.each do |result| \& printf "\\nResult # %d\\n\\n", i += 1 \& result.each do |key| \& printf("%s = %s\\n", key, result.send(key)) \& end \& end \& \& puts '\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-' \& i = 0 \& q.directoryCategories.each do |category| \& printf "\\nCategory # %d\\n\\n", i += 1 \& category.each do |key| \& printf("%s = %s\\n", key, category.send(key)) \& end \& end \& \& printf "Estimated number of results is %d.\\n", q.estimatedTotalResultsCount \& printf "Your query took %6f seconds.\\n", q.searchTime .fi .SH DESCRIPTION .PP Ruby/Google allows you to programmatically query the Google search\-engine. It is currently in the alpha stage and the interface is liable to change at any time. .SH CLASS METHODS .TP .fi .B Search.new(key) .PP This constructs a new Google::Search object. The key parameter is the key that Google assigned to you when you registered for the Web API download. If you don't yet have a key, go to Google and obtain one. .TP .fi .B Search.query_length_ok?(query) .PP This checks to see whether the query length is under MAX_QUERY_LENGTH characters. It returns either \fItrue\fP or \fIfalse\fP. .TP .fi .B Search.query_words_ok?(query) .PP This checks to see whether the number of words in query is under MAX_QUERY_WORDS. It returns either \fItrue\fP or \fIfalse\fP. .TP .fi .B Search.query_sites_ok?(query) .PP This checks to see whether the number of \fIsite:\fP restrict terms in query is below MAX_QUERY_SITES. It returns either \fItrue\fP or \fIfalse\fP. .SS \- .PP The above 3 methods check for compliance with the limitations of the Google Web API, as defined in section 2.7 of the APIs_Reference.html file that came with your Google API archive. .TP .fi .B Search.query_ok?(query) .PP This encapsulates the above 3 methods and can be used when one wishes to know if query is bad, but not necessarily why it is bad. It returns either \fItrue\fP or \fIfalse\fP. .TP .fi .B Search.restrict(type, *data) .PP This assembles a query term, based on the restrict type and its parameter(s), passed as *data. A full list of query terms is given in section 2.2 of APIs_Reference.html. .IP .B \(bu If type is \fIphrase\fP, a double\-quoted copy of each string passed as *data is returned. .IP .B \(bu If type is \fIdaterange\fP, the first three parameters of *data must be the year, month, and day of a start date. The next three parameters, if given, form the year, month, and day of an end date. If these last three parameters are not given, today's date will be substituted. .IP .B \(bu Other supported restrict types are \fIsite\fP, \fIintitle\fP, \fIallintitle\fP, \fIinurl\fP, \fIallinurl\fP, \fIallintext\fP, \fIallinlinks\fP, \fIfiletype\fP, \fInotfiletype\fP, \fIinfo\fP, \fIlink\fP, \fIrelated\fP, \fIcache\fP, \fIinclude\fP and \fIexclude\fP. Some of these names differ slightly from those given in section 2.2 of APIs_Reference.html in order to simplify their use and memorability. .SH INSTANCE METHODS .TP .fi .B Search#utf8(source) .PP If source is not \fInil\fP, subsequent invocations of Search#search and Search#spell will convert their first argument from encoding source to UTF\-8 prior to sending the request to Google. .PP You should use this if your query string is not already UTF\-8 and contains 8 bit characters. Otherwise, an XSD::ValueSpaceError exception may be thrown. .TP .fi .B Search#search(query, start, max, filter, restrict, safe, lr, ie, oe) .PP This performs a standard Google query search. Only the query parameter is mandatory. .PP The meaning of the other parameters can be obtained from section 2.1 of APIs_Reference.html, although the ie and oe parameters are now deprecated and should not be used. A warning will be issued if Ruby is run in verbose mode and either of these parameters is used. .PP This method returns a Struct::Response object, the members of which are described in section 3.1 of APIs_Reference.html. .PP The resultElements member is an Array of Struct::ResultElement objects. Members of the Struct::ResultElement object are described in section 3.2 of APIs_Reference.html. Note that the \fIURL\fP parameter is actually represented by the url member, since Ruby does not allow a variable name to begin with a capital letter. .PP The directoryCategories member is an Array of Struct::DirectoryCategory. Members of the Struct::DirectoryCategory object are described in section 3.3 of APIs_Reference.html. .TP .fi .B Search#spell(phrase) .PP This performs a Google spell\-check on phrase. If Google has a spelling suggestion to make, a String is returned. Otherwise, \fInil\fP is returned. .TP .fi .B Search#cache(url) .PP This attempts to retrieve a copy of the page corresponding to url from Google's cache. If Google has not cached the URL in question, a page containing a message to this effect will be returned instead. .PP This method always returns a String. .SH ENVIRONMENT .TP .fi .B HTTP_PROXY or http_proxy If this is defined, the named system will be used as an HTTP proxy. .SH AUTHOR .PP Written by Ian Macdonald .SH COPYRIGHT .nf \& Copyright (C) 2002\-2006 Ian Macdonald \& \& This is free software; see the source for copying conditions. \& There is NO warranty; not even for MERCHANTABILITY or FITNESS \& FOR A PARTICULAR PURPOSE. .fi .SH SEE ALSO .PP Ruby/Google home page \- http://www.caliban.org/ruby/ Google Web APIs \- http://www.google.com/apis/ .SH BUGS .PP Send all bug reports, enhancement requests and patches to the author. .SH HISTORY .PP $Id: google.rb,v 1.37 2006/02/08 00:28:18 ianmacd Exp $