verso 0.0.2 → 0.0.3

data/.gitignore

@@ -3,3 +3,5 @@
 Gemfile.lock
 pkg/*
 tmp/*
+doc/*
+.yardoc/*

data/README.md

@@ -6,8 +6,7 @@ Technical Education curriculum, course, and occupation data.
 
 ## Installation
 
-The verso gem has been tested with Ruby 1.9.3. It does not currently work with
-Ruby 1.8.7.
+The verso gem has been tested with Ruby 1.9.3 and 1.8.7.
 
     gem install verso
 
@@ -17,28 +16,17 @@ Ruby 1.8.7.
     cd verso
     rake install
 
-## Caveat
-
-This gem has been *extracted* from a larger project, the Web application that
-presents [Verso](http://www.cteresource.org/verso/), the [Administrative
-Planning Guide](http://www.cteresource.org/apg/), and the [Career Planning
-Guide](http://www.cteresource.org/cpg/) on the Virginia CTE Resource Center Web
-site. For this reason the object interfaces are sometimes inconsistent (for
-instance collection objects do not always respond to all the expected
-methods -- `#to_a` is your friend), the specs are incomplete, and the
-documentation is nil.
-
-All that said, the wrapper is reasonably complete, and should make a great
-starting pointing for getting course, curriculum, and occupation data out of
-Verso. The classes available in lib/verso correspond to the resources described
-in the [API documentation](http://api.cteresource.org/docs). The usual points
-of entry are the [Cluster List](http://api.cteresource.org/docs/clusters), the
+## Quick Start
+
+The wrapper should make a great starting pointing for getting course,
+curriculum, and occupation data out of Verso. The classes available in
+lib/verso correspond to the resources described in the [API
+documentation](http://api.cteresource.org/docs). The usual points of entry
+are the [Cluster List](http://api.cteresource.org/docs/clusters), the
 [Course List](http://api.cteresource.org/docs/courses), the [Occupation
 List](http://api.cteresource.org/docs/occupations), and the [Credential
 List](http://api.cteresource.org/docs/credentials).
 
-## Quick Start
-
 ### Start with Clusters
 
     require 'verso'
@@ -51,8 +39,8 @@ List](http://api.cteresource.org/docs/credentials).
 
     require 'verso'
     course = Verso::CourseList.new(:code => "6321").first
-    course.title # => "Accouting, Advanced"
-    da = course.duty_areas.to_a[5] # I warned you about the incomplete interface . . . .
+    course.title # => "Accounting, Advanced"
+    da = course.duty_areas[5]
     da.title # => "Using Technology to Implement Accounting Procedures"
     da.tasks.last.statement # => "Apply emerging technology trends used in the accounting profession."
 

data/lib/verso.rb

@@ -1,9 +1,16 @@
+# external
 require 'addressable/uri'
+require 'forwardable'
 require 'json'
 require 'net/http'
 require 'ostruct'
 
-require 'verso/http_get'
+# base/mixin/override
+require 'verso/base'
+require 'verso/hash'
+require 'verso/http_gettable'
+
+# resources and children
 require 'verso/cluster'
 require 'verso/cluster_list'
 require 'verso/correlation_list'
@@ -25,9 +32,10 @@ require 'verso/occupation_list'
 require 'verso/pathway'
 require 'verso/program_area_list'
 require 'verso/program_area'
-require 'verso/sol_correlation_list'
 require 'verso/standard'
 require 'verso/standards_list'
 require 'verso/task'
 require 'verso/task_list'
+
+# gem version
 require 'verso/version'

data/lib/verso/base.rb

@@ -0,0 +1,50 @@
+# A wrapper for the Virginia CTE Resource Center's Web API, providing access
+# to Virginia's Career and Technical Education curriculum, course, and
+# occupation data.
+#
+# @see http://api.cteresource.org/docs Web API documentation
+module Verso
+  # @abstract Classes derived from Verso::Base should define attr_readers or
+  #   appropriate methods (using Verso::Base#get_attr w/in methods) to access
+  #   attributes stored in the attrs hash.
+  #
+  # @!attribute [r] attrs
+  #   attribute hash
+  class Base
+    attr_reader :attrs
+    alias to_hash attrs
+
+    # Initialize new object
+    #
+    # @param attrs [Hash]
+    # @return [Verso::Base]
+    def initialize(attrs={})
+      @attrs = attrs.symbolize_nested_keys!
+    end
+
+    # Define methods to retrieve values from attribute hash
+    #
+    # @param attrs [Symbol]
+    def self.attr_reader(*attrs)
+      attrs.each do |attr|
+        class_eval do
+          define_method attr do
+            get_attr(attr.to_sym)
+          end
+        end
+      end
+    end
+
+  protected
+
+    # Get attribute value from attrs attribute store or raise NoMethodError
+    # if the key is not defined.
+    #
+    # @param attr [Symbol]
+    # @return attribute value
+    # @raise [NoMethodError]
+    def get_attr(attr)
+      attrs.has_key?(attr) ? attrs[attr] : method_missing(attr)
+    end
+  end
+end

data/lib/verso/cluster.rb

@@ -1,43 +1,73 @@
 module Verso
-  class Cluster
-    include HTTPGet
+  # Career Cluster Resource
+  #
+  # @see http://api.cteresource.org/docs/clusters/cluster
+  # @see http://www.careertech.org/career-clusters/glance/clusters.html
+  #
+  # @!attribute [r] code
+  #   @return [String] Cluster code
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted Cluster description
+  # @!attribute [r] id
+  #   @return [Fixnum] Cluster id
+  # @!attribute [r] postsecondary_info
+  #   @return [String] HTML-formatted postsecondary preparation info
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [Fixnum] :id Cluster id *Required*
+  class Cluster < Verso::Base
+    include HTTPGettable
+    attr_reader :code, :description, :id, :postsecondary_info
 
-    def initialize(opts)
-      @raw_cluster = opts
+    # Return VDOE Cluster contact. The contact will respond to #name, #email,
+    # and #phone, returning Strings.
+    #
+    # @return [OpenStruct]
+    def contact
+      @contact ||= OpenStruct.new(get_attr(:contact))
     end
 
-    def method_missing(mname)
-      if !@raw_cluster.has_key?(mname.to_s)
-        @raw_cluster.merge!(JSON.parse(http_get("/clusters/#{id}"))["cluster"])
-      end
-      @raw_cluster[mname.to_s]
+    # Courses related to the Cluster
+    #
+    # @return [Verso::CourseList]
+    def courses
+      @courses ||= CourseList.new(:cluster => slug.gsub('-', ' ')).
+                     sort_by { |c| c.title + c.edition }.
+                     uniq { |c| c.code + c.edition }
     end
 
-    def id
-      @raw_cluster["id"]
+    # The Cluster's Pathways
+    #
+    # @see http://www.careertech.org/career-clusters/clusters-occupations.html
+    # @see Verso::Pathway
+    #
+    # @return [Array]
+    def pathways
+      @pathways ||= get_attr(:pathways).
+        collect { |p| Pathway.new(p) }
     end
 
-    def title
-      @title ||= @raw_cluster["title"] || @raw_cluster["cluster"]["title"]
+    # @return [String] parameterized title
+    def slug
+      title.parameterize
     end
 
-    def contact
-      @contact ||= OpenStruct.new(method_missing(:contact))
+    # @return [String] Cluster title
+    def title
+      @title ||= attrs[:title] || attrs[:cluster][:title]
     end
 
-    def slug
-      @raw_cluster["title"].parameterize
-    end
+  private
 
-    def pathways
-      @pathways ||= method_missing(:pathways).
-        collect { |p| Pathway.new(p) }
+    def fetch
+      super[:cluster]
     end
 
-    def courses
-      @courses ||= CourseList.new(:cluster => slug.gsub('-', ' ')).
-                     sort_by { |c| c.title + c.edition }.
-                     uniq { |c| c.code + c.edition }
+    # @return [String] URI for Cluster resource
+    def path
+      "/clusters/#{id}"
     end
   end
 end

data/lib/verso/cluster_list.rb

@@ -1,19 +1,24 @@
 module Verso
-  class ClusterList
+  # Career Cluster List Resource
+  #
+  # A collection of {Verso::Cluster} objects
+  #
+  # @see http://api.cteresource.org/docs/clusters
+  # @see http://www.careertech.org/career-clusters/glance/clusters.html
+  class ClusterList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :clusters, :[], :each, :empty?, :last, :length
 
-    def clusters
-      @clusters ||= JSON.parse(http_get('/clusters/'))["clusters"].
-                      collect { |c| Cluster.new(c) }
-    end
+  private
 
-    def each &block
-      clusters.each &block
+    def clusters
+      @clusters ||= get_attr(:clusters).collect { |c| Cluster.new(c) }
     end
 
-    def last
-      clusters[-1]
+    def path
+      "/clusters/"
     end
   end
 end

data/lib/verso/correlation_list.rb

@@ -1,53 +1,43 @@
 module Verso
-  class CorrelationList
+  # Correlation List Resource
+  #
+  # A crosswalk of competencies to standards body goals.
+  # @see http://api.cteresource.org/docs/courses/course/standards/standard/correlations
+  #
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] edition
+  #   @return [String] Edition year
+  # @!attribute [r] name
+  #   @return [String] Standards Body name, used as an identifier and not to
+  #     be confused with its title
+  #
+  # @overload initialize(attrs={})
+  #   @note Certain attributes are required for instantiation.
+  #   @option attrs [String] :code Course code *Required*
+  #   @option attrs [String] :edition Edition year *Required*
+  #   @option attrs [String] :name Standards Body name *Required*
+  class CorrelationList < Verso::Base
     include Enumerable
-    include HTTPGet
-
-    def initialize(context, name)
-      @context = context
-      @name = name
-    end
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :correlations, :[], :each, :empty?, :last, :length
+    attr_reader :code, :edition, :name
 
+    # @return [String] Standards body title
     def title
-      @title ||= @context.standards.find { |s| s.name == @name }.title
+      @title ||= first.goals.first.title
     end
 
-    def code
-      @context.code
-    end
-
-    def edition
-      @context.edition
-    end
-
-    def tasklist
-      @context.duty_areas
-    end
-
-    def sol_names
-      @sol_names ||= @context.standards.sols.collect { |s| s.name }
-    end
+  private
 
     def correlations
-      @correlations ||= JSON.parse(
-        http_get("/courses/#{code},#{edition}/standards/#{@name}/correlations")
-      )["correlations"]
+      @correlations ||= get_attr(:correlations).
+        collect { |c| Task.new(c.merge(:code => code, :edition => edition)) }
     end
 
-    def each &block
-      count = 0
-      tasklist.each do |da|
-        da.tasks.each do |task|
-          count += 1
-          related = correlations.find { |c| c["id"] == task.id }
-          if related.nil?
-            next
-          else
-            related["number"] = count
-            yield Task.new(related)
-          end
-        end
-      end
+    def path
+      "/courses/#{code},#{edition}/standards/#{name}/correlations"
     end
   end
 end

data/lib/verso/course.rb

@@ -1,23 +1,79 @@
 module Verso
-  class Course
-    include HTTPGet
+  # Course Resource
+  #
+  # The chief container of Virginia CTE course data and the *parent of
+  # curriculum data.
+  #
+  # @see http://api.cteresource.org/docs/courses/course
+  #
+  # @!attribute [r] co_op
+  #   @return [Boolean] Is this a co-op course?
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] complement
+  #   @return [Boolean] Is this a complementary course?
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted course description
+  # @!attribute [r] duration
+  #   @return [Fixnum] Course duration in weeks
+  # @!attribute [r] edition
+  #   @return [String] Edition year
+  # @!attribute [r] grade_levels
+  #   @return [String] Space-separated list of recommended grade levels
+  # @!attribute [r] hours
+  #   @return [nil,Fixnum] Course hours
+  # @!attribute [r] hs_credit_in_ms
+  #   @return [Boolean] High school credit in middle school?
+  # @!attribute [r] osha_exempt
+  #   @return [Boolean] Is this course exempt from the OSHA memo?
+  # @!attribute [r] related_resources
+  #   @return [Array] Array of strings specifying related resources
+  #   @see http://api.cteresource.org/docs/courses/course
+  # @!attribute [r] title
+  #   @return [String] Course title
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [String] :code Course code *Required*
+  #   @option attrs [String] :edition Edition year *Required*
+  class Course < Verso::Base
+    include HTTPGettable
+    attr_reader :co_op, :code, :complement, :description, :duration,
+      :edition, :grade_levels, :hours, :hs_credit_in_ms, :osha_exempt,
+      :related_resources, :title
+    alias co_op? co_op
+    alias complement? complement
+    alias hs_credit_in_ms? hs_credit_in_ms
+    alias osha_exempt? osha_exempt
 
-    def initialize(raw_course)
-      @raw_course = raw_course
+    # @return [Array] Collection of certification {Verso::Credential} objects
+    def certifications
+      @certfications ||= credentials.select { |c| c.type == "Certification" }
     end
 
-    def method_missing(mname)
-      if !@raw_course.has_key?(mname.to_s)
-        @raw_course = JSON.parse(http_get("/courses/#{code},#{edition}"))
-      end
-      @raw_course.has_key?(mname.to_s) ? @raw_course[mname.to_s] : super
+    # @return [Array] Collection of {Verso::Credential} objects
+    def credentials
+      @credentials ||= get_attr(:credentials).collect { |c| Credential.new(c) }
     end
 
-    def task(tid)
-      @tasks ||= {}
-      @tasks[tid] ||= Task.new("code" => code, "edition" => edition, "id" => tid)
+    # @return [Verso::TaskList] TaskList is a collection of {Verso::DutyArea}
+    #   objects.
+    def duty_areas
+      @duty_areas ||= TaskList.new(:code => code, :edition => edition)
+    end
+    alias tasklist duty_areas
+
+    # @return [Verso::ExtrasList]
+    def extras
+      @extras ||= if related_resources.include?("extras")
+                    ExtrasList.new(:code => code, :edition => edition)
+                  else
+                    []
+                  end
     end
 
+    # @return [Verso:Frontmatter]
     def frontmatter
       @frontmatter ||= if self.related_resources.include?("frontmatter")
                          Frontmatter.new("code" => code, "edition" => edition)
@@ -26,59 +82,66 @@ module Verso
                        end
     end
 
-    def duty_areas
-      @duty_areas ||= TaskList.new(:code => code, :edition => edition)
-    end
-
-    def occupation_data
-      @occupation_data ||= method_missing(:occupation_data).
-        collect { |od| OccupationData.new(od) }
+    # @return [Boolean] Is this a middle school course?
+    def is_ms?
+      grade_levels.split.first.to_i < 9
     end
 
-    def prerequisites
-      @prerequisites ||= prerequisite_courses.collect { |c| Course.new(c) }
+    # @return [Boolean] is this a high school course?
+    def is_hs?
+      grade_levels.split.last.to_i > 8
     end
 
-    def related_courses
-      @related_courses ||= method_missing(:related_courses).
-                             collect { |c| Course.new(c) }
+    # @return [Array] Colection of license {Verso::Credential} objects
+    def licenses
+      @licenses ||= credentials.select { |c| c.type == "License" }
     end
 
-    def credentials
-      @credentials ||= method_missing(:credentials).
-                         collect { |c| Credential.new(c) }
+    # @return [Array] Collection of prerequisite {Verso::Course} objects
+    def prerequisite_courses
+      @prerequisites ||= get_attr(:prerequisite_courses).
+                           collect { |c| Course.new(c) }
     end
+    alias prerequisites prerequisite_courses
 
-    def certifications
-      @certfications ||= credentials.select { |c| c.type == "Certification" }
+    # @return [Array] Collection of {Verso::OccupationData} objects
+    def occupation_data
+      @occupation_data ||= get_attr(:occupation_data).
+        collect { |od| OccupationData.new(od) }
     end
 
-    def licenses
-      @licenses ||= credentials.select { |c| c.type == "License" }
+    # @return [Array] Collection of related {Verso::Course} objects
+    #   forming sequences with this course.
+    def related_courses
+      @related_courses ||= get_attr(:related_courses).
+                             collect { |c| Course.new(c) }
     end
 
+    # @return [Verso::StandardsList] Standards bodies correlated to this
+    #   course's tasks.
     def standards
       @standards ||= if self.related_resources.include?("standards")
                        StandardsList.from_course(self)
                      else
-                       StandardsList.new([], self)
+                       StandardsList.new(:code => code, :edition => edition,
+                                         :standards => [])
                      end
     end
 
-    def is_ms?
-      grade_levels.split.first.to_i < 9
+    # Fetch a complete task given a task id.
+    #
+    # @param [Fixnum] tid The task id
+    # @return [Verso::Task]
+    def task(tid)
+      @tasks ||= {}
+      @tasks[tid] ||= Task.new("code" => code, "edition" => edition,
+                               "id" => tid)
     end
 
-    def is_hs?
-      grade_levels.split.last.to_i > 8
-    end
+  private
 
-    def extras
-      @extras ||= if related_resources.include?("extras")
-                    ExtrasList.new(:code => code, :edition => edition)
-                  else
-                    []
-                  end
+    def path
+      "/courses/#{code},#{edition}"
     end
   end
 end