verso 0.0.2 → 0.0.3

data/lib/verso/course_list.rb

@@ -1,36 +1,72 @@
 module Verso
-  class CourseList
+  # Search Verso courses by :text, :cluster, :program_area, :code, :edition,
+  # or any combination and get back an Array-like collection of
+  # {Verso::Course} objects.
+  #
+  # @see http://api.cteresource.org/docs/courses
+  #
+  # @example Search by text
+  #   courses = Verso::CourseList.new(:text => "golf") # => <Verso::CourseList:0x007fa5a10bbb68 @attrs={:text=>"golf"}>
+  #   courses.first.title # => "Turf Grass Applications, Advanced"
+  #
+  # @example Search by cluster
+  #   course = Verso::CourseList.new(:cluster => "Information Technology).first
+  #   course.title # => "Computer Applications"
+  #
+  # @example Search by program area
+  #   course = Verso::CourseList.new(:program_area => "Career Connections").last
+  #   course.title # => "Career Investigation Phase I"
+  #
+  # @example Search by code
+  #   courses = Verso::CourseList.new(:code => "6320") # => <Verso::CourseList:0x007fa5a1f27a08 @attrs={:code=>"6320"}>
+  #   courses.first # => <Verso::Course:0x007fa5a1f3e5c8 @attrs={:duration=>36, :edition=>"2012", :code=>"6320" . . . }>
+  #   courses.first.code # => "6320"
+  #
+  # @example Search by edition
+  #   all_2012 = Verso::CourseList.new(:edition => "2012")
+  #
+  # @example Search by combination
+  #   courses = Verso::CourseList.new(:text => "internet", :cluster => "Marketing") # => <Verso::CourseList:0x007fa5a19b6c90 @attrs={ . . . }>
+  #   courses.count # => 1
+  #
+  # @example An empty search returns an empty list
+  #   courses = Verso::CourseList.new
+  #   courses.count # => 0
+  #
+  # @overload initialize(attrs={})
+  #   @option attrs [String] :code Course code
+  #   @option attrs [String] :edition Edition year
+  #   @option attrs [String] :text Free text
+  #   @option attrs [String] :cluster Cluster title
+  #   @option attrs [String] :program_area Program Area title
+  class CourseList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :courses, :[], :each, :empty?, :last, :length
 
-    def initialize(raw_query)
-      @q_uri = Addressable::URI.new(
-        :path => '/courses',
-        :query_values => raw_query.
-          select { |k, v| v }.
-          reject { |k, v| v.to_s.empty? }
-      )
-    end
+    private
 
     def courses
-      @courses ||= if @q_uri.query_values.values.any?
-                     JSON.parse(http_get(@q_uri.request_uri))["courses"].
-                       collect { |c| Course.new(c) }
+      @courses ||= if q_uri.query_values.values.any?
+                       get_attr(:courses).collect { |c| Course.new(c) }
                    else
                      []
                    end
     end
 
-    def each &block
-      courses.each &block
-    end
-
-    def last
-      courses[-1]
+    def q_uri
+      Addressable::URI.new(
+        :path => '/courses',
+        :query_values => attrs.
+          reject { |k, v| k == :courses }.
+          select { |k, v| v }.
+          reject { |k, v| v.to_s.empty? }
+      )
     end
 
-    def empty?
-      courses.empty?
+    def path
+      q_uri.request_uri
     end
   end
 end

data/lib/verso/credential.rb

@@ -1,34 +1,108 @@
 module Verso
-  class Credential
-    include HTTPGet
+  # Credential Resource
+  #
+  # The usual way to get a Credential would be to use {Verso::CredentialList}
+  # or to get one from a related object, such as a {Verso::Course} object.
+  #
+  # @see http://api.cteresource.org/docs/credentials/credential
+  #
+  # @!attribute [r] admin_notes
+  #   @return [String] HTML-formatted test administration notes
+  # @!attribute [r] amt_seal
+  #   @return [Booelean] Advanced Math and Technology seal
+  # @!attribute [r] contact_info
+  #   @return [String] Contractor contact information
+  # @!attribute [r] cost
+  #   @return [String] Cost
+  # @!attribute [r] cte_seal
+  #   @return [Boolean] CTE seal
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted text describing the credential.
+  # @!attribute [r] has_ancestor
+  #   @return [Boolean] Did this credential exist in an earlier edition?
+  # @!attribute [r] how_to_earn_it
+  #   @return [String] HTML-formatted text about how to earn it.
+  # @!attribute [r] id
+  #   @return [Fixnum] Credential id
+  # @!attribute [r] items
+  #   @return [String] Number of test items
+  # @!attribute [r] passing_score
+  #   @return [Sring] Passing score
+  # @!attribute [r] pretest
+  #   @return [Boolean,nil] Is a pre-test, study guide, or blueprint available?
+  # @!attribute [r] proctor
+  #   @return [String] Test examiner/proctor
+  # @!attribute [r] program_area
+  #   @return [String] Title of associated program area
+  # @!attribute [r] retired
+  #   @return [Boolean] Is this credential slated for deletion?
+  # @!attribute [r] site
+  #   @return [String] Allowed testing site
+  # @!attribute [r] time
+  #   @return [String] Time allowed
+  # @!attribute [r] title
+  #   @return [String] Credential title
+  # @!attribute [r] type
+  #   @return ['Certification','License'] Credential type
+  # @!attribute [r] verified_credit
+  #   @return [Boolean] Verified credit
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [Fixnum] :id Credential id *Required*
+  class Credential < Verso::Base
+    include HTTPGettable
+    attr_reader :admin_notes, :amt_seal, :contact_info, :cost, :cte_seal,
+      :description, :has_ancestor, :how_to_earn_it, :id, :items, :passing_score,
+      :pretest, :proctor, :program_area, :retired, :site, :time, :title, :type,
+      :verified_credit
+    alias amt_seal? amt_seal
+    alias cte_seal? cte_seal
+    alias has_ancestor? has_ancestor
+    alias retired? retired
+    alias verified_credit? verified_credit
 
-    def initialize(opts)
-      @raw_credential = opts
+    # VDOE contacts, each responding to #name, #email, and #phone, all Strings.
+    #
+    # @return [Array] VDOE contacts
+    def contacts
+      @contacts ||= get_attr(:contacts).collect { |c| OpenStruct.new(c) }
     end
 
-    def method_missing(mname)
-      if @raw_credential[mname.to_s].nil?
-        @raw_credential.merge!(
-          JSON.parse(http_get("/credentials/#{id}"))["credential"]
-        )
-      end
-      @raw_credential[mname.to_s]
+    # @return [String] Contractor name
+    def contractor_name
+      get_attr(:contractor_name).to_s
     end
 
-    def source
-      @source ||= OpenStruct.new(method_missing(:source))
+    # @return [String] Details
+    def details
+      get_attr(:details).to_s # #to_s b/c API sometimes returns nil
     end
 
-    def details
-      @details ||= if @raw_credential.has_key?("details")
-                     @raw_credential["details"]
-                   else
-                     method_missing(:details)
-                   end.to_s
+    # Source. Responds to #title, #url, and #contact_info. All are Strings or
+    # nil. The last is HTML-formatted.
+    #
+    # @return [OpenStruct] Source
+    def source
+      # force update if we only have part of source
+      attrs.merge!(fetch) unless attrs[:source] && attrs[:source].has_key?(:url)
+      OpenStruct.new(get_attr(:source))
     end
 
+    # @return [Array] Collection of related {Verso::Course} objects
     def related_courses
-      method_missing(:related_courses).collect { |rc| Course.new(rc) }
+      @courses ||= get_attr(:related_courses).collect { |rc| Course.new(rc) }
+    end
+
+  private
+
+    def path
+      "/credentials/#{id}"
+    end
+
+    def fetch
+      super[:credential]
     end
   end
 end

data/lib/verso/credential_list.rb

@@ -1,28 +1,43 @@
 module Verso
-  class CredentialList
+  # Credential list resource
+  #
+  # Search for {Verso::Credential} objects using free text, or get back the
+  # list of all of them.
+  #
+  # @see http://api.cteresource.org/docs/credentials
+  #
+  # @example All
+  #   creds = Verso::CredentialList.new # => everything
+  #   creds.first # => <Verso::Credential:0x007fb1a39e4038 . . . >
+  #
+  # @example Search
+  #   creds = Verso::CredentialList.new(:text => "nocti")
+  #   creds.first.source.title # => "National Occupational Competency Testing Institute (NOCTI)"
+  #
+  # @overload initialize(attrs={})
+  #   @option attrs [String] :text Free text
+class CredentialList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :credentials, :[], :each, :empty?, :last, :length
 
-    attr_reader :credentials
+  private
 
-    def initialize(opts={})
-      @q_uri = Addressable::URI.new(:path => '/credentials')
-      @q_uri.query_values = opts unless opts[:text].to_s.empty?
-      @credentials = JSON.parse(http_get(@q_uri.request_uri))["credentials"].
+    def credentials
+      @credentials ||= get_attr(:credentials).
         collect { |c| Credential.new(c) }.
         sort_by { |c| c.title }
     end
 
-    def each &block
-      credentials.each &block
+    def path
+      q_uri ||= Addressable::URI.new(:path => '/credentials')
+      q_uri.query_values = { :text => text } unless text.empty?
+      q_uri.request_uri
     end
 
-    def last
-      credentials[-1]
-    end
-
-    def empty?
-      credentials.empty?
+    def text
+      attrs[:text] ? attrs[:text] : ''
     end
   end
 end

data/lib/verso/duty_area.rb

@@ -1,16 +1,29 @@
 module Verso
-  class DutyArea
-    attr_reader :title, :context
-
-    def initialize(raw_da, context)
-      @context = context
-      @title = raw_da["title"]
-      @raw_tasks = raw_da["tasks"]
-    end
+  # Duty Area
+  #
+  # A group of tasks in a {Verso::TaskList}.
+  #
+  # @see http://api.cteresource.org/docs/courses/course/tasks
+  #
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] edition
+  #   @return [String] Course edition year
+  # @!attribute [r] title
+  #   @return [String] Duty Area title
+  #
+  # @note A DutyArea is created for you by {Verso::TaskList}. It corresponds
+  #   to a portion of the Task List resource. You should never need to
+  #   instantiate one yourself.
+  class DutyArea < Verso::Base
+    attr_reader :code, :edition, :title
 
+    # Tasks within this Duty Area
+    #
+    # @return [Array] {Verso::Task} objects
     def tasks
-      @tasks ||= @raw_tasks.collect do |t|
-        Task.new(t.merge("code" => context.code, "edition" => context.edition))
+      @tasks ||= get_attr(:tasks).collect do |t|
+        Task.new(t.merge(:code => code, :edition => edition))
       end
     end
   end

data/lib/verso/edition_list.rb

@@ -1,19 +1,27 @@
 module Verso
-  class EditionList
+  # Edition List resource
+  #
+  # A collection of Edition proxies that respond to #year, returning a string
+  # year like '2012'.
+  #
+  # @example Get a list
+  #   editions = Verso::EditionList.new
+  #   editions.first.year => # "2012"
+  #
+  class EditionList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :editions, :[], :each, :empty?, :last, :length
 
-    def editions
-      @editions ||= JSON.parse(http_get('/editions/'))["editions"].
-                      collect { |e| OpenStruct.new(e) }
-    end
+  private
 
-    def each &block
-      editions.each &block
+    def editions
+      @editions ||= get_attr(:editions).collect { |e| OpenStruct.new(e) }
     end
 
-    def last
-      editions[-1]
+    def path
+      "/editions/"
     end
   end
 end

data/lib/verso/emphasis.rb

@@ -1,21 +1,35 @@
 module Verso
-  class Emphasis
-    include HTTPGet
+  # Academic Emphasis resource
+  #
+  # @see http://api.cteresource.org/docs/academics/emphasis
+  #
+  # @!attribute [r] id
+  #   @return [Fixnum] Academic Emphasis id
+  # @!attribute [r] title
+  #   @return Academic Emphasis title
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [Fixnum] :id Academic Emphasis id *Required*
+  class Emphasis < Verso::Base
+    include HTTPGettable
+    attr_reader :id, :title
 
-    def initialize(raw_emphasis)
-      @raw_emphasis = raw_emphasis
+    # @return [Array] Collection of related {Verso::OccupationData} objects
+    def occupation_data
+      @occupation_data ||= get_attr(:occupation_data).
+        collect { |od| OccupationData.new(od) }
     end
 
-    def method_missing(mname)
-      if !@raw_emphasis.has_key?(mname.to_s)
-        @raw_emphasis = JSON.parse(http_get("/academics/#{id}"))["emphasis"]
-      end
-      @raw_emphasis[mname.to_s]
+  private
+
+    def fetch
+      super[:emphasis]
     end
 
-    def occupation_data
-      @occupation_data ||= method_missing(:occupation_data).
-        collect { |od| OccupationData.new(od) }
+    def path
+      "/academics/#{id}"
     end
   end
 end

data/lib/verso/emphasis_list.rb

@@ -1,19 +1,27 @@
 module Verso
-  class EmphasisList
+  # Academic Emphasis List resource
+  #
+  # A collection of all {Verso::Emphasis} objects.
+  #
+  # @see http://api.cteresource.org/docs/academics
+  #
+  # @example Get a list
+  #   emphases = Verso::EmphasisList.new # => all of them
+  #   emphases.first.title # => "Algebra"
+  class EmphasisList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :emphases, :[], :each, :empty?, :last, :length
 
-    def emphases
-      @emphases ||= JSON.parse(http_get('/academics/'))["emphases"].
-        collect { |em| Emphasis.new(em) }
-    end
+  private
 
-    def each &block
-      emphases.each &block
+    def emphases
+      @emphases ||= get_attr(:emphases).collect { |em| Emphasis.new(em) }
     end
 
-    def last
-      emphases[-1]
+    def path
+      "/academics/"
     end
   end
 end

data/lib/verso/examination_list.rb

@@ -1,21 +1,37 @@
 module Verso
-  class ExaminationList
+  # Examination List resource
+  #
+  # A collection of Examination stand-in objects that respond to:
+  # * #amt_seal @return [Boolean] AMT Seal
+  # * #passing_score @return [String] Passing score
+  # * #retired @return [Boolean] Slated to be deleted?
+  # * #source @return [String] Title of exam source
+  # * #title @return [String] Exam title
+  # * #verified_credit @return [Booelean] Verified credit
+  #
+  # The attributes of the Examination stand-ins are similar to
+  # {Verso::Credential}.
+  #
+  # @example Get the list
+  #   exams = Verso::ExaminationList.new # => everything
+  #   exams.first.title # => "Advanced Placement Computer Science A"
+  #
+  # @see http://api.cteresource.org/docs/examinations
+  class ExaminationList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :examinations, :[], :each, :empty?, :last, :length
 
-    attr_reader :examinations
+  private
 
-    def initialize
-      @examinations = JSON.parse(http_get("/examinations/"))["examinations"].
-        collect { |e| OpenStruct.new(e) }
+    def examinations
+      @examinations ||= get_attr(:examinations).
+                          collect { |e| OpenStruct.new(e) }
     end
 
-    def each &block
-      examinations.each &block
-    end
-
-    def last
-      examinations[-1]
+    def path
+      "/examinations/"
     end
   end
 end