verso 0.0.2 → 0.0.3

data/lib/verso/extra.rb

@@ -1,38 +1,40 @@
 module Verso
-  class Extra
-    include HTTPGet
-
-    def initialize(raw_extra)
-      @raw_extra = raw_extra
-    end
-
-    def code
-      @raw_extra["code"]
-    end
-
-    def edition
-      @raw_extra["edition"]
-    end
-
-
-    def name
-      @raw_extra["name"]
-    end
-
-
-    def title
-      @raw_extra["title"]
+  # Extra resource
+  #
+  # An extra (or related material) associated with a Course framework in
+  # Verso.
+  #
+  # @see http://api.cteresource.org/docs/courses/course/extras/extra
+  #
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] edition
+  #   @return [String] Edition year
+  # @!attribute [r] name
+  #   @return [String] Extra name, used as an identifier and not to
+  #     be confused with its title, found by {Verso::ExtrasList}
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted Extra description
+  # @!attribute [r] title
+  #   @return [String] Extra 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 Extra name *Required*
+  class Extra < Verso::Base
+    include HTTPGettable
+    attr_reader :code, :description, :edition, :name, :title
+
+  private
+
+    def path
+      "/courses/#{code},#{edition}/extras/#{name}"
     end
 
-    def description
-      if @raw_extra["description"].nil?
-        @raw_extra.merge!(
-          JSON.parse(
-            http_get("/courses/#{code},#{edition}/extras/#{name}")
-          )["extra"]
-        )
-      end
-      @raw_extra["description"]
+    def fetch
+      super[:extra]
     end
   end
 end

data/lib/verso/extras_list.rb

@@ -1,22 +1,38 @@
 module Verso
-  class ExtrasList
-    attr_reader :code, :edition
+  # Extras List resource
+  #
+  # A collection of {Verso::Extra} associated with a {Course} framework.
+  #
+  # @see http://api.cteresource.org/docs/courses/course/extras
+  #
+  # @example Get extras for 2012 edition of course 6320
+  #   extras = Verso::ExtrasList.new(:code => "6320", :edition => "2012")
+  #
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] edition
+  #   @return [String] Edition year
+  #
+  # @overload initialize(attrs={})
+  #   @note Certain attributes are required for instantiation.
+  #   @option attrs [String] :code Course code *Required*
+  #   @option attrs [String] :edition Edition year *Required*
+ class ExtrasList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    attr_reader :code, :edition
+    def_delegators :extras, :[], :each, :empty?, :last, :length
 
-    def initialize(opts)
-      @code, @edition = opts[:code], opts[:edition]
-    end
+  private
 
     def extras
-      @extras ||= JSON.parse(
-        http_get("/courses/#{code},#{edition}/extras/")
-      )["extras"].
-        collect { |e| Extra.new(e.merge("code" => code, "edition" => edition)) }
+      @extras ||= get_attr(:extras).
+        collect { |e| Extra.new(e.merge(:code => code, :edition => edition)) }
     end
 
-    def each &block
-      extras.each &block
+    def path
+      "/courses/#{code},#{edition}/extras/"
     end
   end
 end

data/lib/verso/frontmatter.rb

@@ -1,18 +1,50 @@
 module Verso
-  class Frontmatter
-    include HTTPGet
+  # Frontmatter resource
+  #
+  # Frontmatter for {Verso::Course} framework.
+  #
+  # @see http://api.cteresource.org/docs/courses/course/frontmatter
+  #
+  # @!attribute [r] acknowledgments_text
+  #   @return [String] HTML-formatted acknowledgments
+  # @!attribute [r] attribution_block
+  #   @return [String] HTML-formatted attribution
+  # @!attribute [r] code
+  #   @return [String] Course code
+  # @!attribute [r] copyright_year
+  #   @return [String] Copyright year
+  # @!attribute [r] developed_by
+  #   @return [String] HTML-formatted developed-by text
+  # @!attribute [r] developed_for
+  #   @return [String] HTML-formatted developed-for text
+  # @!attribute [r] edition
+  #   @return [String] Edition year
+  # @!attribute [r] foreword_text
+  #   @return [String] HTML-formatted foreword
+  # @!attribute [r] introduction_text
+  #   @return [String] HTML-formatted introduction_text
+  # @!attribute [r] notice_block
+  #   @return [String] HTML formatted notice_block
+  #
+  # @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 Frontmatter < Verso::Base
+    include HTTPGettable
+    attr_reader :acknowledgments_text, :attribution_block, :code,
+      :copyright_year, :developed_by, :developed_for, :edition,
+      :foreword_text, :introduction_text, :notice_block
 
-    def initialize(opts)
-      @raw_frontmatter = opts
+  private
+
+    def fetch
+      super[:frontmatter]
     end
 
-    def method_missing(mname)
-      if !@raw_frontmatter.has_key?(mname.to_s)
-        @raw_frontmatter = JSON.parse(
-          http_get("/courses/#{@raw_frontmatter['code']},#{@raw_frontmatter['edition']}/frontmatter")
-        )["frontmatter"]
-      end
-      @raw_frontmatter[mname.to_s]
+    def path
+      "/courses/#{code},#{edition}/frontmatter"
     end
   end
 end

data/lib/verso/hash.rb

@@ -0,0 +1,19 @@
+class Hash
+  def symbolize_nested_keys!
+    keys.each do |key|
+      self[(key.to_sym rescue key) || key] = if self[key].is_a?(Hash)
+        delete(key).symbolize_nested_keys!
+      elsif self[key].is_a?(Array)
+        delete(key).collect do |i|
+          if i.is_a?(Hash)
+            i.symbolize_nested_keys!
+          end
+          i
+        end
+      else
+        delete(key)
+      end
+    end
+    self
+  end
+end

data/lib/verso/http_gettable.rb

@@ -0,0 +1,31 @@
+module Verso
+  # Mixin for classes derived from {Verso::Base}. Provides the capability to
+  # fetch the JSON resource to update attributes of the class.
+  #
+  # @abstract Implement a path method that gives the relative path of the
+  #   corresponding JSON resource.
+  module HTTPGettable
+  protected
+
+    # Get an attribute from the attributes store {#attrs}. Fetch  and merge
+    # first if the attribute store doesn't have the key.
+    #
+    # @param [Symbol] attr The attribute key
+    # @return [Object] The attribute
+    def get_attr(attr)
+      attrs.merge!(fetch) unless attrs.has_key?(attr)
+      super attr
+    end
+
+    # HTTP GET the JSON resource
+    # @return [String] JSON resource
+    def http_get
+      Net::HTTP.get('api.cteresource.org', path, 80)
+    end
+
+    # @return [Hash] Resource hash
+    def fetch
+      JSON.parse(http_get).symbolize_nested_keys!
+    end
+  end
+end

data/lib/verso/occupation.rb

@@ -1,25 +1,47 @@
 module Verso
-  class Occupation
-    include HTTPGet
+  # Occupation resource
+  #
+  # An occupation is contained by a Pathway
+  #
+  # @see http://api.cteresource.org/docs/occupations/occupation
+  # @see http://www.careertech.org/career-clusters/clusters-occupations.html
+  #
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted Occupation description
+  # @!attribute [r] id
+  #   @return [Fixnum] Occupation ID
+  # @!attribute [r] preparations
+  #   @return [Array] Collection of preparation titles (strings)
+  # @!attribute [r] title
+  #   @return [String] Occupation title
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [Fixnum] :id Occupation ID *Required*
+  class Occupation < Verso::Base
+    include HTTPGettable
+    attr_reader :description, :id, :preparations, :title
 
-    def initialize(raw_occupation)
-      @raw_occupation = raw_occupation
+    # @return [Verso::Pathway] Pathway that is the parent of this occupation
+    def pathway
+      @pathway ||= Pathway.new(get_attr(:pathway))
     end
 
-    def method_missing(mname)
-      if @raw_occupation[mname.to_s].nil?
-        @raw_occupation = JSON.parse(http_get("/occupations/#{id}"))["occupation"]
-      end
-      @raw_occupation[mname.to_s]
+    # @return [Array] Collection of related {Verso::Course} objects
+    def related_courses
+      @related_courses ||= get_attr(:related_courses).
+                             collect { |c| Course.new(c) }
     end
 
-    def related_courses
-      @related_courses ||= method_missing(:related_courses).
-        collect { |c| Course.new(c) }
+  private
+
+    def fetch
+      super[:occupation]
     end
 
-    def pathway
-      @pathway ||= Pathway.new(method_missing(:pathway))
+    def path
+      "/occupations/#{id}"
     end
   end
 end

data/lib/verso/occupation_data.rb

@@ -1,30 +1,51 @@
 module Verso
-  class OccupationData
-    def initialize(od)
-      @raw_od = od
-    end
-
+  # Occupation Data
+  #
+  # A list of occupations grouped by the Cluster/Pathway that contains them.
+  # Occupation Data is not an independent resource. It is a component of
+  # {Verso::OccupationList}, {Verso::Course}, and {Verso::Emphasis}.
+  #
+  # @see http://api.cteresource.org/docs/academics/emphasis
+  # @see http://api.cteresource.org/docs/courses/course
+  # @see http://api.cteresource.org/docs/occupations
+  #
+  # @note Because an OccupationData object is created for you by other
+  #   resources you should never need to instantiate one yourself.
+  class OccupationData < Verso::Base
+    # @return [Verso::Cluster] Cluster (grandparent of occupations)
     def cluster
-      @cluster ||= Cluster.new(@raw_od["cluster"])
+      @cluster ||= Cluster.new(get_attr(:cluster))
     end
 
-    def pathway
-      @pathway ||= Pathway.new(@raw_od["pathway"])
+    # @return [Array] Collection of {Verso::Occupation} objects
+    def occupations
+      @occupations ||= get_attr(:occupations).collect { |o| Occupation.new(o) }
     end
 
-    def occupations
-      @occupations ||= @raw_od["occupations"].
-        collect { |o| Occupation.new(o) }
+    # @return [Verso::Pathway] Pathway (parent of occupations)
+    def pathway
+      @pathway ||= Pathway.new(get_attr(:pathway))
     end
 
+    # Find OccupationData by cluster, pathway, and occupation slugs
+    #
+    # @example Find an OccupationData for an occupation
+    #   od = Verso::OccupationData.find_by_slugs('finance', 'accounting', 'cost-analyst')
+    #   od.occupations.count # => 1
+    #   od.occupations.first.title # => 'Cost Analyst'
+    #
+    # @param [String] cslug Cluster slug
+    # @param [String] pslug Pathway slug
+    # @param [String] slug Occupation slug
+    # @return [Verso::OccupationData,nil] Containing only one Occupation
     def self.find_by_slugs(cslug, pslug, slug)
       cluster = ClusterList.new.find { |c| c.title.parameterize == cslug }
       pathway = cluster.pathways.find { |p| p.title.parameterize == pslug }
       occupation = pathway.occupations.find { |o| o.title.parameterize == slug }
       OccupationData.new(
-        { "cluster" => { "title" => cluster.title },
-          "pathway" => { "title" => pathway.title },
-          "occupations" => [{ "title" => occupation.title }] }
+        { :cluster => { :title => cluster.title },
+          :pathway => { :title => pathway.title },
+          :occupations => [{ :title => occupation.title }] }
       )
     end
   end

data/lib/verso/occupation_list.rb

@@ -1,32 +1,35 @@
 module Verso
-  class OccupationList
+  # Occupation list resource
+  #
+  # Search {Verso::Occupation} objects using free text. Result is a collection
+  # of {Verso::OccupationData} objects containing relevant {Verso::Occupation}
+  # objects.
+  #
+  # @see http://api.cteresource.org/docs/occupations
+  #
+  # @example Search by free text
+  #   ods = Verso::OccupationList.new(:text => "golf") # => golf-related ODs
+  #
+  # @overload initialize(attrs={})
+  #   @option attrs [String] :text Free text
+  class OccupationList < Verso::Base
     include Enumerable
-    include HTTPGet
+    include HTTPGettable
+    extend Forwardable
+    def_delegators :occupations, :[], :each, :empty?, :last, :length
 
-    def initialize(raw_query={})
-      @q_uri = Addressable::URI.new(
-        :path => '/occupations',
-        :query_values => raw_query
-      )
-    end
+  private
 
     def occupations
-      @occupations ||= JSON.
-        parse(http_get(@q_uri.request_uri))["occupation_data"].
+      return [] if attrs[:text].to_s.empty?
+      @occupations ||= get_attr(:occupation_data).
           collect { |o| OccupationData.new(o) }.
           sort_by { |o| [o.cluster.title, o.pathway.title] }
     end
 
-    def each &block
-      occupations.each &block
-    end
-
-    def last
-      occupations[-1]
-    end
-
-    def empty?
-      occupations.empty?
+    def path
+      @path ||= Addressable::URI.new(:path => '/occupations',
+                                     :query_values => attrs).request_uri
     end
   end
 end

data/lib/verso/pathway.rb

@@ -1,25 +1,43 @@
 module Verso
-  class Pathway
-    include HTTPGet
+  # Pathway Resource
+  #
+  # @see http://api.cteresource.org/docs/pathways/pathway
+  # @see http://www.careertech.org/career-clusters/clusters-occupations.html
+  #
+  # @!attribute [r] description
+  #   @return [String] HTML-formatted Pathway description
+  # @!attribute [r] id
+  #   @return [Fixnum] Pathway id
+  # @!attribute [r] title
+  #   @return [String] Pathway title
+  #
+  # @overload initialize(attrs={})
+  #   @note Any attributes may be set upon instantiation, using Options Hash.
+  #     The following are required:
+  #   @option attrs [Fixnum] :id Pathway id *Required*
+  class Pathway < Verso::Base
+    include HTTPGettable
+    attr_reader :description, :id, :title
 
-    def initialize(raw_pathway)
-      @raw_pathway = raw_pathway
-    end
-
-    def method_missing(mname)
-      if @raw_pathway[mname.to_s].nil?
-        @raw_pathway = JSON.parse(http_get("/pathways/#{id}"))["pathway"]
-      end
-      @raw_pathway[mname.to_s]
+    # @return [Verso::Cluster] Parent Cluster
+    def cluster
+      @cluster ||= Cluster.new(get_attr(:cluster))
     end
 
+    # @return [Array] Children {Verso::Occupation} objects
     def occupations
-      @occupations ||= method_missing(:occupations).
+      @occupations ||= get_attr(:occupations).
         collect { |o| Occupation.new(o) }
     end
 
-    def cluster
-      @cluster ||= Cluster.new(method_missing(:cluster))
+  private
+
+    def fetch
+      super[:pathway]
+    end
+
+    def path
+      "/pathways/#{id}"
     end
   end
 end