osm 0.0.11 → 0.0.12

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## Version 0.0.12
+
+  * EveningActivity class renamed to Evening::Activity
+  * Change of method return types
+    * Activity.badges now returns an array of Osm::Activity::Badge objects
+    * Activity.files now returns an array of Osm::Activity::File objects
+    * Activity.versions now returns an array of Osm::Activity::Version objects
+    * Section.flexi_records now returns an array of Osm::Section::FlexiRecord objects
+    * Api.get\_register\_structure now returns an array of RegisterField objects
+  * Api.get\_register becomes Api.get\_register\_data and now returns an array of RegisterData objects
+  * Attribute name changes:
+    * Activity::Badge.section becomes section\_type
+    * Activity::File.file\_id becomes id
+    * Section.extra\_records becomes flexi\_records
+    * Member.joined\_in\_years attribute becomes joining\_in\_years
+  * from\_api method added to:
+    * Activity and sub classes
+    * ApiAccess
+    * DueBadges
+    * Evening and Evening::Activity
+    * Event
+    * Grouping
+    * Member
+    * RegisterData
+    * RegisterField
+    * Role
+    * Section
+    * Term
+
 ## Version 0.0.11
 
   * Fix undefined variable in id\_for\_term

data/lib/osm.rb

@@ -27,7 +27,7 @@ module Osm
       end
     end
 
-    raise Error.new('There is no current term for the section.')
+    raise Error, 'There is no current term for the section.'
   end
 
   def self.make_datetime(date, time)
@@ -69,7 +69,7 @@ module Osm
   end
 
   def self.symbolize_hash(hash_in)
-    raise ArgumentError.new('You did not pass in a hash') unless hash_in.is_a?(Hash)
+    raise ArgumentError, 'You did not pass in a hash' unless hash_in.is_a?(Hash)
 
     hash_out = {}
     hash_in.each do |key, value|
@@ -78,4 +78,12 @@ module Osm
     hash_out
   end
 
+  def self.is_array_of?(ar, ty)
+    return false unless ar.is_a?(Array)
+    ar.each do |it|
+      return false unless it.is_a?(ty)
+    end
+    return true
+  end
+
 end

data/lib/osm/activity.rb

@@ -34,53 +34,209 @@ module Osm
     # @!attribute [r] used
     #   @return [Fixnum] How many times this activity has been used (total accross all of OSM)
     # @!attribute [r] versions
-    #   @return [Array<Hash>] ? (:value - version, :firstname - created by, :label - label, :user_id - OSM user ID of creator)
+    #   @return [Array<Osm::Activity::Version>]
     # @!attribute [r] sections
     #   @return [Array<Symbol>] the sections the activity is appropriate for
     # @!attribute [r] tags
     #   @return [Array<String>] the tags attached to the activity
     # @!attribute [r] files
-    #   @return [Array<Hash> ? ('fileid', 'filename', 'name')
+    #   @return [Array<Osm::Activity::File>
     # @!attribute [r] badges
-    #   @return [Array<Hash> ? ('section', 'badgetype', 'badge', 'columnname', 'label')
-
-
-    # Initialize a new Activity using the hash returned by the API call
-    # @param data the hash of data for the object returned by the API
-    def initialize(data)
-      @id = data['details']['activityid'].to_i
-      @version = data['details']['version'].to_i
-      @group_id = data['details']['groupid'].to_i
-      @user_id = data['details']['userid'].to_i
-      @title = data['details']['title']
-      @description = data['details']['description']
-      @resources = data['details']['resources']
-      @instructions = data['details']['instructions']
-      @running_time = data['details']['runningtime'].to_i
-      @location = data['details']['location'].to_sym
-      @shared = data['details']['shared'].to_i
-      @rating = data['details']['rating'].to_i
-      @editable = data['editable']
-      @deletable = data['deletable'] ? true : false
-      @used = data['used'].to_i
-      @versions = data['versions']
-      @sections = data['sections'].is_a?(Array) ? Osm::make_array_of_symbols(data['sections']) : []
-      @tags = data['tags'].is_a?(Array) ? data['tags'] : []
-      @files = data['files'].is_a?(Array) ? data['files'] : []
-      @badges = data['badges'].is_a?(Array) ? data['badges'] : []
-
-      # Clean versions hashes
-      @versions.each do |version|
-        version.keys.each do |key|
-          version[(key.to_sym rescue key) || key] = version.delete(key)
-        end
-        version[:value] = version[:value].to_i
-        version[:user_id] = version[:userid].to_i
-        version.delete(:userid)
-        version[:selected] = (version[:selected] == 'selected')
+    #   @return [Array<Osm::Activity::Badge>
+
+
+    # Initialize a new Activity
+    # @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+    def initialize(attributes={})
+      [:id, :group_id, :user_id].each do |attribute|
+        it = attributes[attribute]
+        raise ArgumentError, ":#{attribute} must be nil or a Fixnum > 0" unless it.nil? || (it.is_a?(Fixnum) && it > 0)
+      end
+      [:version, :running_time, :shared].each do |attribute|
+        it = attributes[attribute]
+        raise ArgumentError, ":#{attribute} must be nil or a Fixnum >= 0" unless it.nil? || (it.is_a?(Fixnum) && it >= 0)
+      end
+
+      [:title, :description, :resources, :instructions].each do |attribute|
+        it = attributes[attribute]
+        raise ArgumentError, ":#{attribute} must be nil or a String" unless it.nil? || it.is_a?(String)
+      end
+
+      raise ArgumentError, ':location must be either :indoors, :outdoors or :both' unless [:indoors, :outdoors, :both].include?(attributes[:location])
+
+      raise ArgumentError, ':editable must be a Boolean' unless attributes[:editable].is_a?(TrueClass) || attributes[:editable].is_a?(FalseClass)
+      raise ArgumentError, ':deletable must be a Boolean' unless attributes[:deletable].is_a?(TrueClass) || attributes[:deletable].is_a?(FalseClass)
+
+      raise ArgumentError, ':rating must be a FixNum' unless attributes[:rating].is_a?(Fixnum)
+      raise ArgumentError, ':used must be a FixNum' unless attributes[:used].is_a?(Fixnum)
+
+      raise ArgumentError, ':sections must be an Array of Symbol' unless Osm::is_array_of?(attributes[:sections], Symbol)
+      raise ArgumentError, ':tags must be an Array of String' unless Osm::is_array_of?(attributes[:tags], String)
+      raise ArgumentError, ':versions must be an Array of Osm::Activity::Version' unless Osm::is_array_of?(attributes[:versions], Osm::Activity::Version)
+      raise ArgumentError, ':files must be an Array of Osm::Activity::File' unless Osm::is_array_of?(attributes[:files], Osm::Activity::File)
+      raise ArgumentError, ':badges must be an Array of Osm::Activity::Badge' unless Osm::is_array_of?(attributes[:badges], Osm::Activity::Badge)
+
+      attributes.each { |k,v| instance_variable_set("@#{k}", v) }
+    end
+
+    # Initialize a new Activity from api data
+    # @param [Hash] data the hash of data provided by the API
+    def self.from_api(data)
+      attributes = {}
+      attributes[:id] = Osm::to_i_or_nil(data['details']['activityid'])
+      attributes[:version] = data['details']['version'].to_i
+      attributes[:group_id] = Osm::to_i_or_nil(data['details']['groupid'])
+      attributes[:user_id] = Osm::to_i_or_nil(data['details']['userid'])
+      attributes[:title] = data['details']['title']
+      attributes[:description] = data['details']['description']
+      attributes[:resources] = data['details']['resources']
+      attributes[:instructions] = data['details']['instructions']
+      attributes[:running_time] = Osm::to_i_or_nil(data['details']['runningtime'])
+      attributes[:location] = data['details']['location'].to_sym
+      attributes[:shared] = Osm::to_i_or_nil(data['details']['shared'])
+      attributes[:rating] = data['details']['rating'].to_i
+      attributes[:editable] = data['editable']
+      attributes[:deletable] = data['deletable'] ? true : false
+      attributes[:used] = data['used'].to_i
+      attributes[:sections] = data['sections'].is_a?(Array) ? Osm::make_array_of_symbols(data['sections']) : []
+      attributes[:tags] = data['tags'].is_a?(Array) ? data['tags'] : []
+      attributes[:versions] = []
+      attributes[:files] = []
+      attributes[:badges] = []
+
+      # Populate Arrays
+      (data['files'].is_a?(Array) ? data['files'] : []).each do |file_data|
+        attributes[:files].push File.from_api(file_data)
+      end
+      (data['badges'].is_a?(Array) ? data['badges'] : []).each do |badge_data|
+        attributes[:badges].push Badge.from_api(badge_data)
+      end
+      (data['versions'].is_a?(Array) ? data['versions'] : []).each do |version_data|
+        attributes[:versions].push Version.from_api(version_data)
       end
+
+      return new(attributes)
     end
 
-  end
 
-end
+    private
+    class File
+      attr_reader :id, :activity_id, :file_name, :name
+      # @!attribute [r] id
+      #   @return [Fixnum] the OSM ID for the file
+      # @!attribute [r] activity_id
+      #   @return [Fixnum] the OSM ID for the activity
+      # @!attribute [r] file_name
+      #   @return [String] the file name of the file
+      # @!attribute [r] name
+      #   @return [String] the name of the file (more human readable than file_name)
+
+      # Initialize a new File
+      # @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+      def initialize(attributes={})
+        [:file_name, :name].each do |attribute|
+          raise ArgumentError, ":#{attribute} must a String" unless attributes[attribute].is_a?(String)
+        end
+        [:id, :activity_id].each do |attribute|
+          it = attributes[attribute]
+          raise ArgumentError, ":#{attribute} must be nil or a Fixnum > 0" unless it.nil? || (it.is_a?(Fixnum) && it > 0)
+        end
+
+        attributes.each { |k,v| instance_variable_set("@#{k}", v) }
+      end
+
+      # Initialize a new File from api data
+      # @param [Hash] data the hash of data provided by the API
+      def self.from_api(data)
+        return new({
+          :id => Osm::to_i_or_nil(data['fileid']),
+          :activity_id => Osm::to_i_or_nil(data['activityid']),
+          :file_name => data['filename'],
+          :name => data['name']
+        })
+      end
+
+    end # Activity::File
+
+    class Badge
+      attr_reader :activity_id, :section_type, :type, :badge, :requirement, :label
+      # @!attribute [r] activity_id
+      #   @return [Fixnum] the activity being done
+      # @!attribute [r] section_type
+      #   @return [Symbol] the section the badge 'belongs' to
+      # @!attribute [r] type
+      #   @return [Symbol] the type of badge
+      # @!attribute [r] badge
+      #   @return [String] short name of the badge
+      # @!attribute [r] requirement
+      #   @return [String] OSM reference to this badge requirement
+      # @!attribute [r] label
+      #   @return [String] human readable label for the requirement
+
+      # Initialize a new Badge
+      # @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+      def initialize(attributes={})
+        raise ArgumentError, ':activity_id must be nil or a Fixnum > 0' unless attributes[:activity_id].nil? || (attributes[:activity_id].is_a?(Fixnum) && attributes[:activity_id] > 0)
+        [:type, :section_type].each do |attribute|
+          raise ArgumentError, ":#{attribute} must be a Symbol" unless attributes[attribute].is_a?(Symbol)
+        end
+        [:label, :requirement, :badge].each do |attribute|
+          raise ArgumentError, ":#{attribute} must a String" unless attributes[attribute].is_a?(String)
+        end
+
+        attributes.each { |k,v| instance_variable_set("@#{k}", v) }
+      end
+
+      # Initialize a new Badge from api data
+      # @param [Hash] data the hash of data provided by the API
+      def self.from_api(data)
+        return new({
+          :activity_id => Osm::to_i_or_nil(data['activityid']),
+          :section_type => data['section'].to_sym,
+          :type => data['badgetype'].to_sym,
+          :badge => data['badge'],
+          :requirement => data['columnname'],
+          :label => data['label']
+        })
+      end
+
+    end # Activity::Badge
+
+    class Version
+      attr_reader :version, :created_by, :created_by_name, :label
+      # @!attribute [r] version
+      #   @return [Fixnum] the version of the activity
+      # @!attribute [r] created_by
+      #   @return [Fixnum] the OSM user ID of the person who created this version
+      # @!attribute [r] created_by_name
+      #   @return [String] the aname of the OSM user who created this version
+      # @!attribute [r] label
+      #   @return [String] the human readable label to use for this version
+
+      # Initialize a new Version
+      # @param [Hash] attributes the hash of attributes (see attributes for descriptions, use Symbol of attribute name as the key)
+      def initialize(attributes={})
+        raise ArgumentError, ':version must be nil or a Fixnum > 0' unless attributes[:version].nil? || (attributes[:version].is_a?(Fixnum) && attributes[:version] >= 0)
+        raise ArgumentError, ':created_by must be nil or a Fixnum >= 0' unless attributes[:created_by].nil? || (attributes[:created_by].is_a?(Fixnum) && attributes[:created_by] > 0)
+        raise ArgumentError, ':created_by_name must be nil or a String' unless attributes[:created_by_name].nil?  || attributes[:created_by_name].is_a?(String)
+        raise ArgumentError, ':label must be nil or a String' unless attributes[:label].nil?  || attributes[:label].is_a?(String)
+
+        attributes.each { |k,v| instance_variable_set("@#{k}", v) }
+      end
+
+      # Initialize a new Version from api data
+      # @param [Hash] data the hash of data provided by the API
+      def self.from_api(data)
+        return new({
+          :version => Osm::to_i_or_nil(data['value']),
+          :created_by => Osm::to_i_or_nil(data['userid']),
+          :created_by_name => data['firstname'],
+          :label => data['label']
+        })
+      end
+
+    end # Activity::Version
+
+  end # Activity
+
+end # Module

data/lib/osm/api.rb

@@ -113,7 +113,7 @@ module Osm
 
       result = Array.new
       data.each do |item|
-        role = Osm::Role.new(item)
+        role = Osm::Role.from_api(item)
         result.push role
         cache_write("section-#{role.section.id}", role.section, :expires_in => @@default_cache_ttl*2)
         self.user_can_access :section, role.section.id, api_data
@@ -205,7 +205,7 @@ module Osm
 
       result = Array.new
       data['patrols'].each do |item|
-        grouping = Osm::Grouping.new(item)
+        grouping = Osm::Grouping.from_api(item)
         result.push grouping
         cache_write("grouping-#{grouping.id}", grouping, :expires_in => @@default_cache_ttl*2)
         self.user_can_access :grouping, grouping.id, api_data
@@ -229,7 +229,7 @@ module Osm
       result = Array.new
       data.each_key do |key|
         data[key].each do |item|
-          term = Osm::Term.new(item)
+          term = Osm::Term.from_api(item)
           result.push term
           cache_write("term-#{term.id}", term, :expires_in => @@default_cache_ttl*2)
           self.user_can_access :term, term.id, api_data
@@ -284,7 +284,7 @@ module Osm
       activities = data['activities'] || {}
 
       items.each do |item|
-        evening = Osm::Evening.new(item, activities[item['eveningid']])
+        evening = Osm::Evening.from_api(item, activities[item['eveningid']])
         result.push evening
         evening.activities.each do |activity|
           self.user_can_access :activity, activity.activity_id, api_data
@@ -313,7 +313,7 @@ module Osm
         data = perform_query("programme.php?action=getActivity&id=#{activity_id}&version=#{version}", api_data)
       end
 
-      activity = Osm::Activity.new(data)
+      activity = Osm::Activity.from_api(data)
       cache_write("activity-#{activity_id}-#{nil}", activity, :expires_in => @@default_cache_ttl*2) if version.nil?
       cache_write("activity-#{activity_id}-#{activity.version}", activity, :expires_in => @@default_cache_ttl/2)
       self.user_can_access :activity, activity.id, api_data
@@ -339,7 +339,7 @@ module Osm
 
       result = Array.new
       data['items'].each do |item|
-        result.push Osm::Member.new(item)
+        result.push Osm::Member.from_api(item)
       end
       self.user_can_access :member, section_id, api_data
       cache_write("members-#{section_id}-#{term_id}", result, :expires_in => @@default_cache_ttl)
@@ -363,7 +363,7 @@ module Osm
 
       result = Array.new
       data['apis'].each do |item|
-        this_item = Osm::ApiAccess.new(item)
+        this_item = Osm::ApiAccess.from_api(item)
         result.push this_item
         self.user_can_access(:programme, section_id, api_data) if this_item.can_read?(:programme)
         self.user_can_access(:member, section_id, api_data) if this_item.can_read?(:member)
@@ -412,7 +412,7 @@ module Osm
       result = Array.new
       unless data['items'].nil?
         data['items'].each do |item|
-          result.push Osm::Event.new(item)
+          result.push Osm::Event.from_api(item)
         end
       end
       self.user_can_access :programme, section_id, api_data
@@ -437,7 +437,7 @@ module Osm
       section_type = get_section(section_id, api_data).type.to_s
       data = perform_query("challenges.php?action=outstandingBadges&section=#{section_type}&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
-      data = Osm::DueBadges.new(data)
+      data = Osm::DueBadges.from_api(data)
       self.user_can_access :badge, section_id, api_data
       cache_write("due_badges-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl*2)
 
@@ -449,7 +449,7 @@ module Osm
     # @param [Osm:Term, Fixnum] section the term (or its ID) to get the structure for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
-    # @return [Array<Hash>] representing the rows of the register
+    # @return [Array<Osm::RegisterField>] representing the fields of the register
     def get_register_structure(section, term=nil, options={}, api_data={})
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
@@ -460,25 +460,25 @@ module Osm
 
       data = perform_query("users.php?action=registerStructure&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
-      data.each_with_index do |item, item_index|
-        data[item_index] = item = Osm::symbolize_hash(item)
-        item[:rows].each_with_index do |row, row_index|
-          item[:rows][row_index] = row = Osm::symbolize_hash(row)
+      structure = []
+      data.each do |item|
+        item['rows'].each do |row|
+          structure.push Osm::RegisterField.from_api(row)
         end
       end
       self.user_can_access :register, section_id, api_data
-      cache_write("register_structure-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl/2)
+      cache_write("register_structure-#{section_id}-#{term_id}", structure, :expires_in => @@default_cache_ttl/2)
 
-      return data
+      return structure
     end
 
-    # Get register
+    # Get register data
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the register for
     # @param [Osm:Term, Fixnum] section the term (or its ID) to get the register for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
-    # @return [Array<Hash>] representing the attendance of each member
-    def get_register(section, term=nil, options={}, api_data={})
+    # @return [Array<RegisterData>] representing the attendance of each member
+    def get_register_data(section, term=nil, options={}, api_data={})
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
 
@@ -490,10 +490,7 @@ module Osm
 
       data = data['items']
       data.each do |item|
-        item = Osm::symbolize_hash(item)
-        item[:scoutid] = item[:scoutid].to_i
-        item[:sectionid] = item[:sectionid].to_i
-        item[:patrolid] = item[:patrolid].to_i
+        item = Osm::RegisterData.from_api(item)
       end
       self.user_can_access :register, section_id, api_data
       cache_write("register-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl/2)
@@ -528,7 +525,7 @@ module Osm
     # @!macro options_api_data
     # @return [Boolean] if the operation suceeded or not
     def update_evening(evening, api_data={})
-      response = perform_query("programme.php?action=editEvening", api_data.merge(evening.data_for_saving))
+      response = perform_query("programme.php?action=editEvening", api_data.merge(evening.to_api))
 
       # The cached programmes for the section will be out of date - remove them
       get_terms(api_data).each do |term|
@@ -601,14 +598,14 @@ module Osm
       begin
         result = HTTParty.post("#{@base_url}/#{url}", {:body => api_data})
       rescue SocketError, TimeoutError, OpenSSL::SSL::SSLError
-        raise ConnectionError.new('A problem occured on the internet.')
+        raise ConnectionError, 'A problem occured on the internet.'
       end
-      raise ConnectionError.new("HTTP Status code was #{result.response.code}") if !result.response.code.eql?('200')
+      raise ConnectionError, "HTTP Status code was #{result.response.code}" if !result.response.code.eql?('200')
 
-      raise Error.new(result.response.body) unless looks_like_json?(result.response.body)
+      raise Error, result.response.body unless looks_like_json?(result.response.body)
       decoded = ActiveSupport::JSON.decode(result.response.body)
       osm_error = get_osm_error(decoded)
-      raise Error.new(osm_error) if osm_error
+      raise Error, osm_error if osm_error
       return decoded        
     end
 
@@ -654,10 +651,10 @@ module Osm
       if value.is_a?(cl)
         value = value.send(id_method)
       else
-        raise(ArgumentError, "Invalid type for #{error_name}") unless value.is_a?(Fixnum)
+        raise ArgumentError, "Invalid type for #{error_name}" unless value.is_a?(Fixnum)
       end
 
-      raise(ArgumentError, "Invalid #{error_name} ID") unless value > 0
+      raise ArgumentError, "Invalid #{error_name} ID" unless value > 0
       return value
     end