Initial library.

Author: frankieroberto

.gitignore

@@ -0,0 +1,2 @@
+doc
+pkg

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 frankieroberto
+
+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.

README

@@ -0,0 +1,64 @@
+= guardian-content
+
+This gem allows you to interface with the Guardian-Content-API[http://www.guardian.co.uk/open-platform] via Ruby.
+
+== Installation
+
+Installation is as simple as typing the following text into a command prompt (such as Terminal):
+
+  gem install guardian-content
+
+== Usage
+
+To use the library within a project, simply include the line <code>require 'guardian-content'</code> - you can then use any of the methods listed below.
+
+Whilst the Guardian Content API doesn't require an API key for basic usage, for increased rate limits, and the ability to retrieve full text content, it is recommended that you register for an API key at http://guardian.mashery.com/. Once authorised, you can use the key via either declaring a <code>GUARDIAN_CONTENT_API_KEY</code> constant, or via the <code>key</code> param when initialising the class.
+
+=== Basic searching
+
+To do a basic free text search of Guardian documents, simply use the following command:
+
+  articles = GuardianContent::Content.search("your search term")
+
+If successful, this will the return an array of results, which you can loop through and access via some standard attributes:
+
+	articles.each do |article|
+		puts article.title
+		puts article.url
+	end
+
+To include additional meta-data in the results, use the <code>:select</code> parameter. There are two types of data you can request, tags and fields. To select all of both, use <code>:select => {:tags => :all, :fields => :all}</code>. You can then access the tags and keywords via attributes:
+
+	articles = GuardianContent::Content.search("your search term", :select => {:tags => :all, :fields => :all})
+	
+	articles.first.tags.each do |tag|
+		puts tag[:id]
+		puts tag[:title]
+	end
+	
+	puts articles.first.fields[:standfirst]
+	puts articles.first.fields[:headline]
+
+=== Retrieving an article based on id
+
+Each article or content item has a unique id. This can be accessed either via the #id attribute on a returned search result, or you can determine it from the Guardian website itself - the id is simply everything in an article's URL after the host name - eg for http://www.guardian.co.uk/world/2010/may/17/iran-nuclear-uranium-swap-turkey the id is <code>world/2010/may/17/iran-nuclear-uranium-swap-turkey</code>.
+
+To retrieve an article based on its id, use the #find_by_id method:
+
+	article = GuardianContent::Content.find_by_id("world/2010/may/17/iran-nuclear-uranium-swap-turkey")
+	
+The article's content and meta-data can then be accessed in the same way as for search results.	
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 frankieroberto. See LICENSE for details.

README.rdoc

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "guardian-content"
+    gem.summary = %Q{Queries the Guardian Content API}
+    gem.description = %Q{A library for the Guardian Content API}
+    gem.email = "frankie@frankieroberto.com"
+    gem.homepage = "http://github.com/frankieroberto/guardian-content"
+    gem.authors = ["frankieroberto"]
+    gem.add_development_dependency "shoulda", ">= 2.10.3"
+    gem.add_dependency('httparty', '>= 0.5.2')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "guardian-content #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

Rakefile

@@ -0,0 +1 @@
+0.2.0

VERSION

@@ -0,0 +1,69 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{guardian-content}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["frankieroberto"]
+  s.date = %q{2010-05-17}
+  s.description = %q{A library for the Guardian Content API}
+  s.email = %q{frankie@frankieroberto.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "guardian-content.gemspec",
+     "lib/guardian-content.rb",
+     "lib/guardian-content/content.rb",
+     "lib/guardian-content/contributor.rb",
+     "lib/guardian-content/extensions.rb",
+     "lib/guardian-content/keyword.rb",
+     "lib/guardian-content/section.rb",
+     "lib/guardian-content/tag.rb",
+     "test/helper.rb",
+     "test/test_guardian-content.rb",
+     "test/test_search_content.rb",
+     "test/test_section.rb",
+     "test/test_tag_search.rb"
+  ]
+  s.homepage = %q{http://github.com/frankieroberto/guardian-content}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Queries the Guardian Content API}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_guardian-content.rb",
+     "test/test_search_content.rb",
+     "test/test_section.rb",
+     "test/test_tag_search.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 2.10.3"])
+      s.add_runtime_dependency(%q<httparty>, [">= 0.5.2"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 2.10.3"])
+      s.add_dependency(%q<httparty>, [">= 0.5.2"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 2.10.3"])
+    s.add_dependency(%q<httparty>, [">= 0.5.2"])
+  end
+end
+

guardian-content.gemspec

@@ -0,0 +1,32 @@
+module GuardianContent
+  
+  require 'httparty'
+  
+  
+  def self.new(*params)
+    GuardianContent::Base.new(*params)
+  end
+  
+  class Base
+    include HTTParty
+    base_uri 'http://content.guardianapis.com/'
+  
+    def initialize(key = nil)
+      if defined?(GUARDIAN_CONTENT_API_KEY)
+        key = GUARDIAN_CONTENT_API_KEY
+      end
+      self.class.default_params "api-key" => key, "format" => "json"
+    end    
+
+    def reload(options = nil)
+      @attributes.update(self.class.find_by_id(self.id, options).instance_variable_get('@attributes'))
+      self
+    end
+
+
+  end
+end
+
+%w(extensions content section tag keyword contributor).each do |file|
+  require File.join(File.dirname(__FILE__), 'guardian-content', file)
+end

lib/guardian-content.rb

@@ -0,0 +1,107 @@
+class GuardianContent::Content < GuardianContent::Base
+
+  attr_reader :title, :id, :url, :publication_date, :section_id, :body, :keywords, :fields, :headline, :tags, :attributes
+
+  def initialize(attributes = {})
+    @attributes = attributes
+    @id = attributes[:id]
+    @title = attributes[:webTitle]
+    @url = attributes[:webUrl]
+    @section_id = attributes[:sectionId]
+    @publication_date = DateTime.parse(attributes[:webPublicationDate]) if attributes && attributes[:webPublicationDate]
+    @body = attributes[:body]
+    
+    if attributes[:tags]
+      @tags = []
+      attributes[:tags].each do |tag|
+        @tags << tag
+      end
+    end
+    
+    @fields = attributes[:fields].nested_symbolize_keys! if attributes[:fields]
+    
+    if attributes[:fields]
+      @headline = attributes[:fields][:headline]
+    end
+  end
+
+  def inspect
+    "#<Article id: \"" + self.id.to_s + "\" title: \"" + self.title.to_s + "\" + url: \"" + self.url.to_s + "\">"
+  end
+  
+  def section
+    return GuardianContent::Section.find_by_id(self.section_id)
+  end
+
+  # Does a text search for content, with various options.
+  # === Parameters
+  # * <tt>:conditions</tt> - A hash which can accept <tt>:tag</tt>, <tt>:section</tt>, <tt>:from</tt> and <tt>:to</tt>, eg: <code>:conditions => {:tag => "poltiics/gordon-brown", :from => Date.yesterday}</code>
+  # * <tt>:limit</tt> - An integer determining the maximum number of results to return (max: 50).
+  # * <tt>:order</tt> - The order of the results. Can be <tt>:relevance</tt>, <tt>:oldest</tt> or <tt>:newest</tt>
+  # === Examples
+  #   * GuardianContent::Content.search("election")
+  #   * GuardianContent::Content.search("election", :conditions => {:section => "politics"})
+  def self.search(q, options = {})
+    
+    query = {}
+    query["page-size"] = options[:limit] if options[:limit]
+    query["order-by"] = options[:order] if options[:order]
+
+    if options[:select]
+      if options[:select][:tags]
+        query["show-tags"] = options[:select][:tags]
+      end
+      if options[:select][:fields]
+        query["show-fields"] = options[:select][:fields]
+      end
+    end
+
+    if options[:conditions]
+      conditions = options[:conditions]
+      
+      query[:tag] = conditions[:tag] if conditions[:tag]
+      query[:section] = conditions[:section] if conditions[:section]
+
+      query["from-date"] = Date.parse(conditions[:from]).to_s if conditions[:from]
+      query["to-date"] = Date.parse(conditions[:to]).to_s if conditions[:to]
+
+    end
+
+    
+    query[:format] = "json"
+      
+    query[:q] = q
+    
+    opts = {:query => query}
+
+    response = self.get("/search", opts).nested_symbolize_keys![:response]
+    
+    results = recursively_symbolize_keys!(response[:results])
+    content = []
+
+    results.each do |result|
+      content << GuardianContent::Content.new(recursively_symbolize_keys!(result))
+    end
+    return content
+  end
+
+  # Fetch a Content item using its id. IDs are usually in the form of <tt>section/YYYY/month/DD/name-of-article</tt>. 
+  def self.find_by_id(id, options = {})
+    
+    query = {}
+    query["show-fields"] = "all"
+    query["show-tags"] = "all"
+    query[:format] = "json"
+    opts = {:query => query}
+        
+    attributes = {}
+    
+    response = recursively_symbolize_keys!self.get("/#{id}", opts).nested_symbolize_keys![:response]
+    
+    content = response[:content]
+
+    return GuardianContent::Content.new(recursively_symbolize_keys!(content))
+    
+  end  
+  
+end

lib/guardian-content/content.rb

@@ -0,0 +1,26 @@
+class GuardianContent::Contributor < GuardianContent::Tag
+
+  attr_reader :title, :id, :url
+  
+  def initialize(attributes = {})
+    @id = attributes[:id] || nil
+    @title = attributes[:web_title] || nil
+    @url = attributes[:web_url] || nil
+  end
+
+  def inspect
+    "#<Contributor id:" + self.id.to_s + " title:\"" + self.title.to_s + "\">"
+  end  
+  
+  def self.find_by_id(id)
+    
+    query = {}
+    query["show-fields"] = "all"
+    query[:format] = "json"
+    opts = {:query => query}
+    
+    return GuardianContent::Contributor.new(self.get("/#{id}").nested_symbolize_keys![:response][:tag])
+  
+  end  
+  
+end