rubyoverflow 0.5 → 1.0.2

data/README.rdoc

@@ -1,23 +1,34 @@
 = rubyoverflow
 
-{<img src="https://secure.travis-ci.org/phsr/rubyoverflow.png" />}[http://travis-ci.org/phsr/rubyoverflow]
-
 rubyoverflow is a library for querying the Stack Overflow API
 
-== Example
+== Configuration
 
-    require 'rubyoverflow'
+    Rubyoverflow::Client.config do |options|
+      options.host = 'http://api.superuser.com' # optional, defaults to stackoverflow, queries super user
+      options.api_key = 'api_key_here'  # optional, sets the api key
+      options.version = '0.8' # optional, defaults to 0.8,sets the api version
+    end
 
-    c = Rubyoverflow::Client.new
-    result = c.users.fetch(:id => 53587) # By default, this will query StackOverflow.com
-    me = result.users.first              # Get the first user out of the results
-    puts me.display_name                 # => "Dan Seaver"
+== Example
 
+    require 'rubyoverflow'
+    include Rubyoverflow
+    # Tags Example
+    tagsSet = Tags.retrieve_all({:sort=>'name',:order=>'asc',:pagesize=>'5'}) # gets the first 5 tags in alphabetical order by name
+    firstTag = tagsSet.tags.first # gets the first tag
+    secondTagSet = tagsSet.get_next_set #gets the next page of tags using the prior parameters
+    thirdTagSet = secondTagSet.get_next_set #gets the third page of tags using the prior parameters
+    puts firstTag.name # => tag's name
+    puts tag.count # => # of questions with tag
+    
+    #User Example
+    me = Users.retrieve_by_id(53587).users.first  #gets me
+    myquestions = me.get_questions  #gets the questions I asked
 
-    c = Rubyoverflow::Client.new :host => "api.serverfault.com" # Query ServerFault.com
 
 == 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
@@ -28,5 +39,5 @@ rubyoverflow is a library for querying the Stack Overflow API
 
 == Copyright
 
-Copyright (c) 2011 Dan Seaver. See LICENSE for details.
+Copyright (c) 2010 phsr. See LICENSE for details.
 

data/RELEASENOTES

@@ -1,2 +1,98 @@
+[1.0.1]
+Minor formatting refactorings
+Setup tests with rspec
+Updated Client.new to accept an ApiSite
+Added Styling class
+Added styling and state to ApiSite (was previously missing)
+Added change_end_point to Client and Base classes (accessible from any querying class)
+Removed display_name from Statistics
+Added site, total_accepted, and view_per_day from Statistics (was previously missing)
+Added tests for Answer and Answers
+Added tests for Base and got Base.convert_if_array working correctly
+Replaced convert_if_array to convert_to_id_list
+Added User#item_id
+Added tests for Badge and Badges
+Completed check_badge_set stub in test/helper
+Added item_id to badge so that you can pass an array containing badges to a method
+Updated convert_if_array to append the id of an item if that class defines the item_id method
+Added protected_date to Question (previously missing)
+Removed parameters from User#get_badges, as the route doesn't support parameters
+Update Users.retrieve_by_badge to support a Badge as a parameter
+Stubbed out test helper methods for checking class sets
+Completed unit tests for Users and User classes
+
+
+[1.0.0]
+Updated PostTimelineEvent to implement new property, question_id
+Updated get_post to properly handle the post being a question or answer
+Added get_parent_question to PostTimelineEvent
+
+[0.9.1]
+Switched from using Open-URI+GZIP+JSON to HTTParty
+
+[0.9.0]
+Updated API_VERSION to match the Stack Exchange API version
+
+[0.8.4]
+Added ApiSite and ApiSites as well as ApiSites.retrieve_sites to retrieve all API endpoints known to the Stack Exchange API
+Added the class method Users.retrieve_associated_accounts and the instance method User.retrieve_associated_accounts, which calls the Users.retrieve_associated_accounts method with the instance's associated_id
+
+[0.8.3]
+Added Badge#get_recipients
+Added Answer#get_comments
+Added Users.get_moderators
+Added PostTimelineEvent#get_post, PostTimelineEvent#get_post_comment, and PostTimelineEvent#get_revision
+Added Question#get_timeline, Question#get_answers, Question#get_comments
+
+[0.8.2]
+Added get_next_set to paged results, retrieve the next set using the same parameters that were used to retrieve the initial set
+Added methods to get answers, questions, favorites, etc from a user that has been retrieved
+
+[0.8.1]
+All classes moved into the Rubyoverflow module
+
+[0.8.0]
+Added Revision and Revisions, along with revision retrieval methods
+Added Questions.search which maps to '/search'
+Added Errors
+
+[0.6.0]
+Added RepChange and RepChanges with RepChanges.retrieve_by_user
+Added UserTimeLineEvent and UserTimeLineEvents with UserTimeLineEvent.retrieve_by_user
+Added PostTimeLineEvent and PostTimeLineEvents with PostTimeLineEvent.retrieve_by_question
+
+[0.5.1]
+Removed @dash member from classes, as it is only used in initialize, shrinking memory usage of classes
+
 [0.5.0]
-Restarting rubyoverflow development, paths /sites and /users (only, no sub-paths) covered
+Added Question and Questions with question retrieval methods
+
+[0.4.1]
+Added Users and retrieve, retrieve_by_id and retrieve_by_badge
+
+[0.4.0]
+Added Comment and Answer wrappers
+Added retrieval methods for comments and answers
+
+[0.3.2]
+Update Badges.retrieve_by_user(id) and Tags.retrieve_by_user(id) to accept an array of ids
+
+[0.3.1]
+Added Badges.retrieve_by_user(id)
+Fixed User class (added if to creation of BadgesCount member)
+
+[0.3.0]
+Mapped User, Badge, BadgeCount, Badges
+Added PagedBase and PagedDash to reuse common properties of paged queries
+Added Badges.retrieve_all, retrieve_all_non_tag_based and retrieve_all_tag_based
+Refactored Tags to use new PagedBase and PagedDash classes
+
+[0.2.3]
+Tags.retrieve_by_user(id,parameters) gets tags that the user has participated in
+
+[0.2.0-2]
+Added support for query string, api key, other stack overflow sites
+Added support for Tag retrieval
+
+[0.1]
+Initial Release, retrieves stack overflow statistics

data/Rakefile

@@ -1,10 +1,52 @@
-require 'bundler/gem_tasks'
+require 'rubygems'
+require 'rake'
+require 'rspec'
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rubyoverflow"
+    gem.summary = %Q{rubyoverflow is a library for querying the Stack Overflow API}
+    gem.description = %Q{rubyoverflow is a library for querying the Stack Overflow API}
+    gem.email = "phasor@phsr.org"
+    gem.homepage = "http://github.com/phsr/rubyoverflow"
+    gem.authors = ["phsr"]
+    gem.add_dependency 'httparty', '>=0'
+    gem.add_dependency 'hashie', '>=0'
+    gem.add_development_dependency "rspec", ">= 0"
+    gem.files.include FileList['lib/**/*.rb', 'bin/*', '[A-Z]*', 'test/**/*'].to_a
+    # 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 'rspec/core/rake_task'
- 
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.pattern = 'spec/**/*_spec.rb'
-  t.rspec_opts = '--format progress'
+
+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 :default => :spec
+
+task :default => :test
+
+task :doc => :rdoc
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rubyoverflow #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -1 +1 @@
-0.5
+1.0.2

data/lib/rubyoverflow.rb

@@ -2,44 +2,118 @@ path = File.expand_path(File.dirname(__FILE__))
 $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
 
 require 'httparty'
+require 'zlib'
 require 'ostruct'
-
 require 'hashie'
-require 'json'
-require 'rubyoverflow/sites'
+
+require 'rubyoverflow/base'
+require 'rubyoverflow/pagedBase'
+require 'rubyoverflow/pagedDash'
+
+require 'rubyoverflow/apiVersion'
+require 'rubyoverflow/badge'
+require 'rubyoverflow/badges'
+require 'rubyoverflow/comments'
+require 'rubyoverflow/comment'
+require 'rubyoverflow/badgeCounts'
+require 'rubyoverflow/statistics'
+require 'rubyoverflow/tag'
+require 'rubyoverflow/tags'
+require 'rubyoverflow/user'
 require 'rubyoverflow/users'
-require "rubyoverflow/version"
+
+require 'rubyoverflow/answer'
+require 'rubyoverflow/answers'
+
+require 'rubyoverflow/question'
+require 'rubyoverflow/questions'
+
+require 'rubyoverflow/repChange'
+require 'rubyoverflow/repChanges'
+
+require 'rubyoverflow/userTimelineEvent'
+require 'rubyoverflow/userTimelineEvents'
+
+require 'rubyoverflow/postTimelineEvent'
+require 'rubyoverflow/postTimelineEvents'
+
+require 'rubyoverflow/revision'
+require 'rubyoverflow/revisions'
+
+require 'rubyoverflow/errors'
+
+require 'rubyoverflow/styling'
+
+require 'rubyoverflow/apiSite'
+require 'rubyoverflow/apiSites'
 
 module Rubyoverflow
   class Client
     include HTTParty
-    format :plain
+    format :json
+    #Most of this class is borrowed from the Pilha (http://github.com/dlt/pilha) project because a) it works, b) a lot of this code would be the same regardless of implementation
+    # (especially the open => gzip code, query string, and normalize), and c) I'm new to ruby, so I'm going to skip pass some of the more 'boring' stuff and get to the 
+    # interesting parts.  I plan to re-examine this at a later point
     HOST = 'http://api.stackoverflow.com'
     VERSION = '1.1'
 
-    attr_accessor :host
-    attr_accessor :api_key
-
+    attr_reader :host
+    attr_reader :api_key
+    
     def initialize(options = OpenStruct.new)
       if options.kind_of? OpenStruct
         @host = options.host || HOST
         @version = options.version || VERSION
         @api_key = options.api_key if options.api_key
       end
+      
+     
     end
-
-    def request(path, parameters = {})
-      parameters['key'] = @api_key unless @api_key.nil? || @api_key.empty?
+    
+    
+    
+    def request(path, parameters)
+      parameters['key'] = @api_key if @api_key
       url = host_path + normalize(path) + query_string(parameters)
       response = self.class.get url
-      return JSON.parse(response.body), url
+      return response.parsed_response, url
     end
-
+    
     def host_path
       normalize(@host) +  normalize(@version)
     end
-
+    
     class << self
+      # this specifically works well, and I don't fully understand it, so I borrowed this from Pilha more than anything else
+      # If you want to explain why I only have to configure this once than forget about it, please do, because this stuff is currently over my head
+      def config &block
+        options = OpenStruct.new
+        yield options if block_given?
+        init_client! Client.new(options)
+      end
+      
+      def change_end_point(val = nil)
+        options = OpenStruct.new
+        if val.kind_of? ApiSite
+          options.host = val.api_endpoint
+        end
+
+        if val.kind_of? String
+          options.host = val
+        end
+        options.api_key = Base.client.api_key
+        
+        init_client! Client.new(options)
+      end
+      
+      def init_client!(client)
+        base_eigenclass = class << Base; self; end
+        base_eigenclass.send :define_method, :client do
+          @client = client
+        end
+        client
+      end
+      
       def stackauth_client(api_key = '')
         options = OpenStruct.new
         options.host = 'http://stackauth.com/'
@@ -52,16 +126,16 @@ module Rubyoverflow
     def normalize(path)
       path.end_with?('/') ? path : path+ '/'
     end
-
+    
     def query_string(parameters)
       if !parameters.empty?
         params = parameters.sort_by { |k, v| k.to_s }
         pairs  = params.map { |key, value| "#{key}=#{value}" }
-
-        '?' + pairs.join('&')
+        
+        '?' + pairs.join('&') + "&jsonp"
       else
         ''
       end
    end
   end
-end
+end

data/lib/rubyoverflow/answer.rb

@@ -0,0 +1,61 @@
+module Rubyoverflow
+  class Answer < Base
+    attr_reader :answer_id, :accepted, :answer_comments_url, :question_id, :locked_date, :owner,
+      :creation_date, :last_edit_date, :last_activity_date, :up_vote_count, :down_vote_count,
+      :view_count, :score, :community_owned, :title, :body, :comments
+  
+    def initialize(hash, request_path = '')
+      dash = AnswerDash.new hash
+    
+      @answer_id = dash.answer_id
+      @accepted = dash.accepted
+      @answer_comments_url = dash.answer_comments_url
+      @question_id = dash.question_id
+      @locked_date = dash.locked_date
+      @owner = User.new dash.owner 
+      @creation_date = dash.creation_date
+      @last_edit_date = dash.last_edit_date
+      @last_activity_date = dash.last_activity_date
+      @up_vote_count = dash.up_vote_count
+      @down_vote_count = dash.down_vote_count
+      @view_count = dash.view_count
+      @score = dash.score
+      @community_owned = dash.community_owned
+      @title = dash.title
+      @body = dash.body
+      @comments = Comments.new dash.comments if dash.comments
+    end
+    
+    #Gets the comments made on the answer
+    def get_comments(parameters = {})
+      if @answer_comments_url
+        hash,url =request(@answer_comments_url, parameters)
+        Comments.new hash, url
+      else
+        nil
+      end
+    end
+
+  end
+
+  class AnswerDash < BaseDash
+  
+    property :answer_id
+    property :accepted
+    property :answer_comments_url
+    property :question_id
+    property :locked_date
+    property :owner
+    property :creation_date
+    property :last_edit_date
+    property :last_activity_date
+    property :up_vote_count
+    property :down_vote_count
+    property :view_count
+    property :score
+    property :community_owned
+    property :title
+    property :body
+    property :comments
+  end
+end

data/lib/rubyoverflow/answers.rb

@@ -0,0 +1,60 @@
+module Rubyoverflow
+  class Answers < PagedBase
+    attr_reader :answers
+  
+    def initialize(hash, request_path = '')
+      dash = AnswersDash.new hash
+    
+      @answers = Array.new
+      dash.answers.each {|answerHash| @answers.push(Answer.new answerHash)}
+    
+      super(dash, request_path)
+    end
+  
+    #Retrieves the next set of answers using the same parameters used to retrieve the current set
+    def get_next_set
+      hash,url = perform_next_page_request
+      Answers.new hash,url
+    end
+    
+    class << self
+    
+      #Retrieves a set of questions by their id(s)
+      #
+      #id can be an int, string, or an array of ints or strings
+      #
+      #Maps to '/answers/{id}'
+      def retrieve_by_id(id, parameters = {})
+        id = convert_to_id_list(id)
+        hash,url = request('answers/'+id.to_s, parameters)
+        Answers.new hash,url
+      end
+    
+      #Retrieves a set of answers made by a set of users by their ids
+      #
+      #id can be an int, string, or an array of ints or strings
+      #
+      #Maps to 'users/{id}/answers'
+      def retrieve_by_user(id, parameters={})
+        id = convert_to_id_list(id)
+        hash, url = request('users/'+id.to_s+"/answers", parameters)
+        Answers.new hash, url
+      end
+    
+      #Retrieves a set of answers from a set of questions by the questions' ids
+      #
+      #id can be an int, string, or an array of ints or strings
+      #
+      #Maps to 'questions/{id}/answers'
+      def retrieve_by_question(id, parameters={})
+        id = convert_to_id_list(id)
+        hash, url = request('questions/'+id.to_s+"/answers", parameters)
+        Answers.new hash, url
+      end
+    end
+  end
+
+  class AnswersDash < PagedDash
+    property :answers
+  end
+end