pcr-ruby 0.1 → 0.2

data/.gitignore

@@ -17,6 +17,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-instructors.txt
-old
-pcr-ruby
+instructors.txt

data/README.md

@@ -4,11 +4,11 @@ pcr-ruby is a simple, intuitive way to retrieve course data from the Penn Course
 
 ## How to use pcr-ruby #
 
-*This section will change a lot as pcr-ruby is developed.  As such, this section may not be fully accurate, but I will try to keep the instructions as current as possible.*
+*This section may change a lot as pcr-ruby is developed.  As such, this section may not be fully accurate, but I will try to keep the instructions as current as possible.*
 
 pcr-ruby follows the structure of the PCR API, with a few name changes to make object identities and roles clearer in your code.  (Before using pcr-ruby, you should most definitely read the PCR API documentation, the link to which you should recieve upon being granted your API token.)
 
-The PCR API essentially consists of four types of objects: 'Courses', 'Sections', 'Instructors', and 'Course Histories'.  pcr-ruby aims to provide intuitive access to the data contained in these four object types while abstracting you and your user from background processing and unnecessary data.  To that end, pcr-ruby (thus far) consists of two types of objects: 'Courses' and 'Sections' ('Instructors' coming soon).
+The PCR API essentially consists of four types of objects: 'Courses', 'Sections', 'Instructors', and 'Course Histories'.  pcr-ruby aims to provide intuitive access to the data contained in these four object types while abstracting you and your user from background processing and unnecessary data.  To that end, pcr-ruby (thus far) consists of two types of objects: 'Courses', 'Sections', and 'Instructors'.
 
 ### 'Courses' in pcr-ruby ###
 
@@ -16,7 +16,9 @@ Course objects in the PCR API are essentially a group of that Course's Sections
 
 To create a Course:
 ```ruby
-course = PCR::Course.new(:course_code => "DEPT-###")
+require 'pcr-ruby'
+pcr = PCR.new(api_token)
+course = pcr.course(course_code)
 ```
 All other instance variables will auto-populate based on data from the PCR API.
 
@@ -38,7 +40,9 @@ In pcr-ruby, Sections are single offerings of a Course.  Each Section is associa
 
 To create a Section:
 ```ruby
-section = PCR::Section.new(:instance_variable => value)
+require 'pcr-ruby'
+pcr = PCR.new(api_token)
+section = pcr.section(id)
 ```
 Possible instance variables available for setting in the Section initialize method are: aliases, id, name, path, semester.
 
@@ -51,10 +55,8 @@ Sections have the following instance variables:
 *	**description** -- a string containing the class description, which is written by the Section's Instructor and details the scope and characteristics of the class.
 *	**comments** -- a string containing PCR's comments about the Section.  The comments are the most major part of the written review, and are sourced from student exit surveys.
 *	**ratings** -- a Hash of metrics and the ratings of the Section for each metric.
-*	**instructor** (to be developed) -- the Instructor object for the Section's professor.
-
-Sections have the following instance methods:
-*	**reviews()** -- retrieves the Section's review data from PCR.  Returns a Hash in the format {"comments" => @comments, "ratings" => @ratings}.
+*	**instructors** an Array of the Section's instructors.
+*	**reviews** -- a Hash of the Section's review data, in the format {"comments" => @comments, "ratings" => @ratings}.
 
 ### 'Instructors' in pcr-ruby ###
 
@@ -62,20 +64,19 @@ Instructors are arguably the most important part of PCR -- many students use PCR
 
 To create an Instructor:
 ```ruby
-instructor = PCR::Instructor.new(:id => id [, :name => name, :path => path, :sections => sections])
+require 'pcr-ruby'
+pcr = PCR.new(api_token)
+instructor = pcr.instructor(id)
 ```
-(You really only need to pass the id argument, as pcr-ruby will automatically retrieve the other information from PCR.)
 
-Insctructors have the following instance variables:
-*	**id** -- the Instructor's PCR id, a String in the form of "ID#-FIRST-M-LAST".
+Insctructors have the following instance variables.  All variables other than **id**, which is user-specified, will be filled from the PCR API:
+*	**id** -- the Instructor's PCR id, a String in the form of "ID#-FIRST-M-LAST".  The PCR API also accepts a String in the form of "ID#".
 *	**name** -- the Instructor's name, a String in the form of "FIRST-M-LAST".
 *	**path** -- the PCR sub-path that leads to the Instructor, a String in the form of "/instructors/id".
 *	**sections** -- a Hash of sections taught by Instructor.
 *	**reviews** -- a Hash of reviews of Instructor in JSON.
 
 Instructors have the following instance methods:
-*	**getInfo** -- a utility method to fill in missing info in Instructor object (used to minimize unnecessary API hits)
-*	**getReviews** -- a utility method to get review info for Instructor object (used to minimize unnecessary API hits)
 *	**average(metric)** -- returns the average value, across all Sections taught by Instructor, of "metric" as a Float.  "Metric" must be a recognized rating in the PCR API.  (Currently the names of these ratings are not intuitive, so I may provide plain-English access to rating names in the future.)
 *	**recent(metric)** -- returns the average value of "metric" for the most recent semester in which the Instructor taught as a float. (For example, if the professor taught 3 classes in the most recent semester, this would return the average of "metric" over the three classes.)  "Metric" must be a recognized rating in the PCR API.  (Currently the names of these ratings are not intuitive, so I may provide plain-English access to rating names in the future.)
 
@@ -89,7 +90,8 @@ Let's say we want to find the average course quality rating for Introduction to
 ```ruby
 require 'pcr.rb'
 course_code = "PSCI-150"
-course = PCR::Course.new(:course_code => course_code)
+pcr = PCR.new(API_TOKEN)
+course = pcr.course(course_code)
 puts course.average("rCourseQuality") #=> 3.041
 ```
 
@@ -97,7 +99,9 @@ Or, even more briefly:
 
 ```ruby
 require 'pcr.rb'
-puts PCR::Course.new(:course_code => "PSCI-150").average("rCourseQuality") #=> 3.041
+pcr = PCR.new(API_TOKEN)
+puts pcr.course("PSCI-150")course.average("rCourseQuality")
+#=> 3.041
 ```
 
 ### Get most recent course difficulty rating ###
@@ -105,16 +109,19 @@ Finding the most recent section's course difficulty rating is just as easy:
 
 ```ruby
 require 'pcr.rb'
-course = PCR::Course.new(:course_code => "PSCI-150")
+pcr = PCR.new(API_TOKEN)
+course = pcr.course("PSCI-150")
 puts course.recent("rDifficulty") #=> 2.5
 ```
 
 ### Get professor's average "ability to stimulate student interest" rating ###
 ```ruby
 require 'pcr.rb'
-instructor = PCR::Instructor.new(:id => "1090-LINDA-H-ZHAO")
+pcr = PCR.new(API_TOKEN)
+instructor = pcr.instructor("1090-LINDA-H-ZHAO")
 puts instructor.average("rStimulateInterest").round(2) #=> 1.7
 ```
 
 ## TODO ##
+* Implement stricter checks on course code arguments
 *	Implement search by professor last/first name rather than by ID.  ID is unintuitive.  Will probably need to see if I can make a lookup method, or simply pull down a database of all instructors and do a search on that database.

data/lib/classes/array.rb

@@ -0,0 +1,18 @@
+#Add useful array methods
+class Array
+  def binary_search(target)
+    self.search_iter(0, self.length-1, target)
+  end
+
+  def search_iter(lower, upper, target)
+    return -1 if lower > upper
+    mid = (lower+upper)/2
+    if (self[mid] == target)
+      mid
+    elsif (target < self[mid])
+      self.search_iter(lower, mid-1, target)
+    else
+      self.search_iter(mid+1, upper, target)
+    end
+  end
+end

data/lib/classes/course.rb

@@ -0,0 +1,89 @@
+#Course object matches up with the coursehistory request of the pcr api.
+#A Course essentially is a signle curriculum and course code, and includes all Sections across time (semesters).
+class Course < PCR
+  attr_accessor :course_code, :sections, :id, :name, :path, :reviews
+  
+  def initialize(course_code)
+    if course_code.is_a? String and course_code.isValidCourseCode?
+      @course_code = course_code
+      
+      #Read JSON from the PCR API
+      api_url = @@api_endpt + "coursehistories/" + self.course_code + "/?token=" + @@token
+      json = JSON.parse(open(api_url).read)
+      
+      #Create array of Section objects, containing all Sections found in the API JSON for the Course
+      @sections = []
+      json["result"]["courses"].each do |c|
+        @sections << Section.new(c["id"])
+      end
+      
+      #Set variables according to Course JSON data
+      @id = json["result"]["id"]
+      @name = json["result"]["name"]
+      @path = json["result"]["path"]
+      
+      #Get reviews for the Course -- unfortunately this has to be a separate query
+      api_url_reviews = @@api_endpt + "coursehistories/" + self.id.to_s + "/reviews?token=" + @@token
+      json_reviews = JSON.parse(open(api_url_reviews).read)
+      @reviews = json_reviews["result"]["values"]
+
+    else
+      raise CourseError, "Invalid course code specified.  Use format [DEPT-###]."
+    end
+  end
+  
+  def average(metric)
+    #Ensure that we know argument type
+    if metric.is_a? Symbol
+      metric = metric.to_s
+    end
+    
+    if metric.is_a? String
+      #Loop vars
+      total = 0
+      n = 0
+      
+      #For each section, check if ratings include metric arg -- if so, add metric rating to total and increment counting variable
+      self.reviews.each do |review|
+        ratings = review["ratings"]
+        if ratings.include? metric
+          total = total + review["ratings"][metric].to_f
+          n = n + 1
+        else
+          raise CourseError, "No ratings found for \"#{metric}\" in #{self.name}."
+        end
+      end
+      
+      #Return average score as a float
+      (total/n)
+      
+    else
+      raise CourseError, "Invalid metric format. Metric must be a string or symbol."
+    end
+  end
+  
+  def recent(metric)
+    #Ensure that we know argument type
+    if metric.is_a? Symbol
+      metric = metric.to_s
+    end
+    
+    
+    if metric.is_a? String
+      #Get the most recent section
+      section = self.sections[-1]
+      
+      #Iterate through all the section reviews, and if the section review id matches the id of the most recent section, return that rating
+      self.reviews.each do |review|
+        if review["section"]["id"].to_s[0..4].to_i == section.id
+          return review["ratings"][metric]
+        end
+      end
+      
+      raise CourseError, "No ratings found for #{metric} in #{section.semester}."
+      
+    else
+      raise CourseError, "Invalid metric format. Metric must be a string or symbol."
+    end
+  end
+end

data/lib/classes/errors.rb

@@ -0,0 +1,6 @@
+#These errors serve as more specific exceptions so we know where exactly errors are coming from.
+class CourseError < StandardError
+end
+
+class InstructorError < StandardError
+end

data/lib/classes/instructor.rb

@@ -0,0 +1,130 @@
+#Instructor is a professor.  Instructors are not tied to a course or section, but will have to be referenced from Sections.
+class Instructor < PCR
+  attr_accessor :id, :name, :path, :sections, :reviews
+  
+  def initialize(id)    
+    #Assign args. ID is necessary because that's how we look up Instructors in the PCR API.
+    if id.is_a? String
+      @id = id
+    else
+      raise InstructorError("Invalid Instructor ID specified.")
+    end
+    
+    #Hit PCR API to get missing info based on id
+    self.getInfo
+    self.getReviews
+
+  end
+  
+  #Hit the PCR API to get all missing info
+  #Separate method in case we want to conduct it separately from a class init
+  def getInfo
+    api_url = @@api_endpt + "instructors/" + self.id + "?token=" + @@token
+    json = JSON.parse(open(api_url).read)
+    
+    @name = json["result"]["name"].downcase.titlecase unless @name
+    @path = json["result"]["path"] unless @path
+    @sections = json["result"]["reviews"]["values"] unless @sections #Mislabeled reviews in PCR API
+  end
+  
+  #Separate method for getting review data in case we don't want to make an extra API hit each init
+  def getReviews
+    if not self.reviews #make sure we don't already have reviews
+      api_url = @@api_endpt + "instructors/" + self.id + "/reviews?token=" + @@token
+      json = JSON.parse(open(api_url).read)
+      
+      @reviews = json["result"]["values"] #gets array
+    end
+  end
+  
+  #Get average value of a certain rating for Instructor
+  def average(metric)
+    #Ensure that we know argument type
+    if metric.is_a? Symbol
+      metric = metric.to_s
+    end
+    
+    if metric.is_a? String
+      #Loop vars
+      total = 0
+      n = 0
+      
+      #For each section, check if ratings include metric arg -- if so, add metric rating to total and increment counting variable
+      self.getReviews
+      self.reviews.each do |review|
+        ratings = review["ratings"]
+        if ratings.include? metric
+          total = total + review["ratings"][metric].to_f
+          n = n + 1
+        else
+          raise CourseError, "No ratings found for \"#{metric}\" for #{self.name}."
+        end
+      end
+      
+      #Return average score as a float
+      (total/n)
+      
+    else
+      raise CourseError, "Invalid metric format. Metric must be a string or symbol."
+    end
+  end
+
+  #Get most recent value of a certain rating for Instructor
+  def recent(metric)
+    #Ensure that we know argument type
+    if metric.is_a? Symbol
+      metric = metric.to_s
+    end
+    
+    if metric.is_a? String
+      #Iterate through reviews and create Section for each section reviewed, presented in an array
+      sections = []
+      section_ids = []
+      self.getReviews
+      self.reviews.each do |review|
+        if section_ids.index(review["section"]["id"].to_i).nil?
+          s = PCR::Section.new(review["section"]["id"].to_i, false)
+          sections << s
+          section_ids << s.id
+        end
+      end
+      
+      #Get only most recent Section(s) in the array
+      sections.reverse! #Newest first
+      targets = []
+      sections.each do |s|
+        s.hit_api(:get_reviews => true)
+        if sections.index(s) == 0
+          targets << s
+        elsif s.semester == sections[0].semester and s.id != sections[0].id
+          targets << s
+        else
+          break
+        end
+      end
+      
+      #Calculate recent rating
+      total = 0
+      num = 0
+      targets.each do |section|
+        #Make sure we get the rating for the right Instructor
+        section.ratings.each do |rating|
+          if rating.key?(self.id)
+            if rating[self.id][metric].nil?
+              raise InstructorError, "No ratings found for #{metric} for #{self.name}."
+            else
+              total = total + rating[self.id][metric].to_f
+              num += 1
+            end
+          end
+        end
+      end
+
+      # Return recent rating
+      total / num
+      
+    else
+      raise CourseError, "Invalid metric format. Metric must be a string or symbol."
+    end
+  end
+end

data/lib/classes/section.rb

@@ -0,0 +1,53 @@
+#Section is an individual class under the umbrella of a general Course
+class Section < PCR
+  attr_accessor :aliases, :id, :name, :path, :semester, :description, :comments, :ratings, :instructors, :reviews
+  
+  def initialize(id, hit_api = true)
+    # Set instance vars
+    @id = id
+    
+    # Hit api to fill additional info
+    self.hit_api() unless hit_api == false
+    
+  end
+  
+  def hit_api()
+    data = ["aliases", "name", "path", "semester", "description"]
+    api_url = @@api_endpt + "courses/" + self.id.to_s + "?token=" + @@token
+    json = JSON.parse(open(api_url).read)
+    
+    data.each do |d|
+      case d
+      when "aliases"
+        self.instance_variable_set("@#{d}", json["result"]["aliases"])
+      when "name"
+        self.instance_variable_set("@#{d}", json["result"]["name"])
+      when "path"
+        self.instance_variable_set("@#{d}", json["result"]["path"])
+      when "semester"
+        self.instance_variable_set("@#{d}", json["result"]["semester"])
+      when "description"
+        self.instance_variable_set("@#{d}", json["result"]["description"])
+      end
+    end
+    
+    # Get review data
+    self.get_reviews
+    
+  end
+  
+  def get_reviews()
+    api_url = @@api_endpt + "courses/" + self.id.to_s + "/reviews?token=" + @@token
+    json = JSON.parse(open(api_url).read)
+    @comments = []
+    @ratings = []
+    @instructors = []
+    json["result"]["values"].each do |a|
+      @comments << {a["instructor"]["id"] => a["comments"]}
+      @ratings << {a["instructor"]["id"] => a["ratings"]}
+      @instructors << a["instructor"]
+    end
+    @reviews = {"comments" => @comments, "ratings" => @ratings}
+  end
+  
+end

data/lib/classes/string.rb

@@ -0,0 +1,68 @@
+#Add some useful String methods
+class ::String
+  #Checks if String is valid Penn course code format
+  def isValidCourseCode?
+    test = self.split('-')
+    if test[0].length == 4 and test[1].length == 3
+      true
+    else
+      false
+    end
+  end
+  
+  #Methods to convert strings to titlecase.
+  #Thanks https://github.com/samsouder/titlecase
+  def titlecase
+    small_words = %w(a an and as at but by en for if in of on or the to v v. via vs vs.)
+
+    x = split(" ").map do |word|
+      # note: word could contain non-word characters!
+      # downcase all small_words, capitalize the rest
+      small_words.include?(word.gsub(/\W/, "").downcase) ? word.downcase! : word.smart_capitalize!
+      word
+    end
+    # capitalize first and last words
+    x.first.smart_capitalize!
+    x.last.smart_capitalize!
+    # small words after colons are capitalized
+    x.join(" ").gsub(/:\s?(\W*#{small_words.join("|")}\W*)\s/) { ": #{$1.smart_capitalize} " }
+  end
+
+  def smart_capitalize
+    # ignore any leading crazy characters and capitalize the first real character
+    if self =~ /^['"\(\[']*([a-z])/
+      i = index($1)
+      x = self[i,self.length]
+      # word with capitals and periods mid-word are left alone
+      self[i,1] = self[i,1].upcase unless x =~ /[A-Z]/ or x =~ /\.\w+/
+    end
+    self
+  end
+
+  def smart_capitalize!
+    replace(smart_capitalize)
+  end
+  
+  #Method to compare semesters. Returns true if self is later, false if self is before, 0 if same
+  #s should be a string like "2009A"
+  def compareSemester(s)
+    year = self[0..3]
+    season = self[4]
+    compYear = s[0..3]
+    compSeason = s[4]
+    
+    if year.to_i > compYear.to_i #Later year
+      return true
+    elsif year.to_i < compYear.to_i #Earlier year
+      return false
+    elsif year.to_i == compYear.to_i #Same year, so test season
+      if season > compSeason #Season is later
+        return true
+      elsif season = compSeason #Exact same time
+        return 0
+      elsif season < compSeason #compSeason is later
+        return false
+      end
+    end
+  end
+end

data/lib/pcr-ruby.rb

@@ -15,12 +15,12 @@ class PCR
     Course.new(course_code)
   end
   
-  def section(*args)
-    Section.new(*args)
+  def section(id, hit_api = true)
+    Section.new(id, hit_api)
   end
   
-  def instructor(id, *args)
-    Instructor.new(id, *args)
+  def instructor(id)
+    Instructor.new(id)
   end
 end
 

data/lib/pcr-ruby/version.rb

@@ -0,0 +1,5 @@
+module Pcr
+  module Ruby
+    VERSION = "0.2"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pcr-ruby
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-21 00:00:00.000000000 Z
+date: 2012-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -38,7 +38,14 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/classes/array.rb
+- lib/classes/course.rb
+- lib/classes/errors.rb
+- lib/classes/instructor.rb
+- lib/classes/section.rb
+- lib/classes/string.rb
 - lib/pcr-ruby.rb
+- lib/pcr-ruby/version.rb
 - pcr-ruby.gemspec
 homepage: ''
 licenses: []