google_contacts_api 0.4.1 → 0.4.2

data/README.markdown

@@ -28,14 +28,19 @@ oauth_access_token_for_user
 
 google_contacts_user = GoogleContactsApi::User.new(oauth_access_token_for_user)
 contacts = google_contacts_user.contacts
+# => <GoogleContactsApi::ContactSet: @start_index=1, @items_per_page=100000, @total_results=638>
 groups = google_contacts_user.groups
+# => <GoogleContactsApi::GroupSet: @start_index=1, @items_per_page=100000, @total_results=8>
 
 # group methods
 group = groups.first
+# => <GoogleContactsApi::Group: System Group: My Contacts>
 group.contacts
+# => <GoogleContactsApi::ContactSet: @start_index=1, @items_per_page=100000, @total_results=20>
 
 # contact methods
 contact = contacts.first
+# => <GoogleContactsApi::Contact: Alvin>
 contact.photo
 contact.title
 contact.id
@@ -43,7 +48,9 @@ contact.primary_email
 contact.emails
 ```
 
-In addition, Contacts and Groups are subclasses of [Hashie::Mash](https://github.com/intridea/hashie), so you can access any of the underlying data directly. Note that data is retrieved using Google's JSON API so the equivalent content of an XML element from the XML API is stored under the key "$t".
+`ContactSet` and `GroupSet` both implement `Enumberable`.
+
+In addition, `Contact` and `Group` are subclasses of [Hashie::Mash](https://github.com/intridea/hashie), so you can access any of the underlying data directly (for example, if Google returns new data [in their API](https://developers.google.com/google-apps/contacts/v3/)). Note that data is retrieved using Google's JSON API so the equivalent content of an XML element from the XML API is stored under the key "$t".
 
 The easiest way to see the convenience methods I've provided is to look at the RSpec tests.
 

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.2

data/google_contacts_api.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "google_contacts_api"
-  s.version = "0.4.1"
+  s.version = "0.4.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alvin Liang"]
@@ -35,6 +35,7 @@ Gem::Specification.new do |s|
     "lib/google_contacts_api/result.rb",
     "lib/google_contacts_api/result_set.rb",
     "lib/google_contacts_api/user.rb",
+    "lib/google_contacts_api/version.rb",
     "spec/contact_set.json",
     "spec/empty_contact_set.json",
     "spec/errors/auth_sub_401.html",

data/lib/google_contacts_api.rb

@@ -7,7 +7,4 @@ require 'google_contacts_api/contact_set'
 require 'google_contacts_api/result'
 require 'google_contacts_api/group'
 require 'google_contacts_api/contact'
-
-module GoogleContactsApi
-  VERSION = "0.3.3"
-end
+require 'google_contacts_api/version'

data/lib/google_contacts_api/contact.rb

@@ -1,39 +1,40 @@
 module GoogleContactsApi
+  # Represents a single contact.
+  # Methods we could implement:
+  # :categories, (:content again), :links, (:title again), :email
+  # :extended_properties, :deleted, :im, :name,
+  # :organizations, :phone_numbers, :structured_postal_addresses, :where
   class Contact < GoogleContactsApi::Result
-    # :categories, (:content again), :links, (:title again), :email
-    # :extended_properties, :deleted, :im, :name,
-    # :organizations, :phone_numbers, :structured_postal_addresses, :where
-    
     # Returns the array of links, as link is an array for Hashie.
     def links
       self["link"].map { |l| l.href }
     end
-    
+
     # Returns link to get this contact
     def self_link
       _link = self["link"].find { |l| l.rel == "self" }
       _link ? _link.href : nil
     end
-    
+
     # Returns alternative, possibly off-Google home page link
     def alternate_link
       _link = self["link"].find { |l| l.rel == "alternate" }
       _link ? _link.href : nil
     end
-    
+
     # Returns link for photo
     # (still need authentication to get the photo data, though)
     def photo_link
       _link = self["link"].find { |l| l.rel == "http://schemas.google.com/contacts/2008/rel#photo" }
       _link ? _link.href : nil
     end
-    
+
     # Returns binary data for the photo. You can probably
     # use it in a data-uri. This is in PNG format.
     def photo
       return nil unless @api && photo_link
       response = @api.oauth.get(photo_link)
-      
+
       case GoogleContactsApi::Api.parse_response_code(response)
       # maybe return a placeholder instead of nil
       when 400; return nil
@@ -45,13 +46,13 @@ module GoogleContactsApi
       else; return response.body
       end
     end
-    
+
     # Returns link to add/replace the photo
     def edit_photo_link
       _link = self["link"].find { |l| l.rel == "http://schemas.google.com/contacts/2008/rel#edit_photo" }
       _link ? _link.href : nil
     end
-    
+
     # Returns link to edit the contact
     def edit_link
       _link = self["link"].find { |l| l.rel == "edit" }
@@ -62,12 +63,12 @@ module GoogleContactsApi
     def phone_numbers
       self["gd$phoneNumber"] ? self["gd$phoneNumber"].map { |e| e['$t'] } : []
     end
-    
+
     # Returns all email addresses for the contact
     def emails
       self["gd$email"] ? self["gd$email"].map { |e| e.address } : []
     end
-    
+
     # Returns primary email for the contact
     def primary_email
       if self["gd$email"]
@@ -77,13 +78,15 @@ module GoogleContactsApi
         nil # no emails at all
       end
     end
-    
+
     # Returns all instant messaging addresses for the contact.
     # Doesn't yet distinguish protocols
     def ims
       self["gd$im"] ? self["gd$im"].map { |i| i.address } : []
     end
 
+    # Convenience method to return a nested $t field.
+    # If the field doesn't exist, return nil
     def nested_t_field_or_nil(level1, level2)
       if self[level1]
         self[level1][level2] ? self[level1][level2]['$t']: nil
@@ -116,12 +119,17 @@ module GoogleContactsApi
       spouse_rel['$t'] if spouse_rel
     end
 
+    # Return an Array of Hashes representing addresses with formatted metadata.
     def addresses
       self['gd$structuredPostalAddress'] ? self['gd$structuredPostalAddress'].map(&method(:format_address)) : []
     end
+
+    # Return an Array of Hashes representing phone numbers with formatted metadata.
     def phone_numbers_full
       self["gd$phoneNumber"] ? self["gd$phoneNumber"].map(&method(:format_phone_number)) : []
     end
+
+    # Return an Array of Hashes representing emails with formatted metadata.
     def emails_full
       self["gd$email"] ? self["gd$email"].map(&method(:format_email)) : []
     end

data/lib/google_contacts_api/contact_set.rb

@@ -1,6 +1,7 @@
 module GoogleContactsApi
+  # Represents a set of contacts.
   class ContactSet < GoogleContactsApi::ResultSet
-    # Populate from a response that contains contacts
+    # Initialize a ContactSet from an API response body that contains contacts data
     def initialize(response_body, api = nil)
       super
       if @parsed.nil? || @parsed.feed.nil? || @parsed.feed.entry.nil?

data/lib/google_contacts_api/contacts.rb

@@ -1,3 +1,4 @@
+# Module that implements a method to get contacts for a user or group
 module GoogleContactsApi
   module Contacts
     # Retrieve the contacts for this user or group

data/lib/google_contacts_api/group.rb

@@ -1,33 +1,35 @@
 module GoogleContactsApi
+  # Represents a single group.
   class Group < GoogleContactsApi::Result
     include GoogleContactsApi::Contacts
-    # Populate from a single entry element in the result response
-    # when requesting a set of Contacts
 
+    # Return true if this is a system group.
     def system_group?
       !self["gContact$systemGroup"].nil?
     end
 
+    # Return the contacts in this group and cache them.
     def contacts(params = {})
       # contacts in this group
       @contacts ||= super({"group" => self.id}.merge(params))
     end
-    
+
+    # Return the contacts in this group, retrieving them again from the server.
     def contacts!(params = {})
       # contacts in this group
       @contacts = super({"group" => self.id}.merge(params))
     end
-    
+
     # Returns the array of links, as link is an array for Hashie.
     def links
       self["link"].map { |l| l.href }
     end
-    
+
     def self_link
       _link = self["link"].find { |l| l.rel == "self" }
       _link ? _link.href : nil
     end
-    
+
     def edit_link
       _link = self["link"].find { |l| l.rel == "edit" }
       _link ? _link.href : nil

data/lib/google_contacts_api/group_set.rb

@@ -1,6 +1,6 @@
 module GoogleContactsApi
   class GroupSet < GoogleContactsApi::ResultSet
-    # Populate from a response that contains contacts
+    # Initialize a GroupSet from an API response body that contains groups data
     def initialize(response_body, api = nil)
       super
       @results = @parsed.feed.entry.map { |e| GoogleContactsApi::Group.new(e, nil, api) }

data/lib/google_contacts_api/result.rb

@@ -1,16 +1,12 @@
 require 'hashie'
 
 module GoogleContactsApi
-  # Base class for Group and Contact
+  # Base class for Group and Contact.
+  # In the JSON responses, ":" from the equivalent XML response is replaced
+  # with a "$", while element content is instead keyed with "$t".
   class Result < Hashie::Mash
-    # Note that the title is really just the (full) name
-    # ":" replaced with $, element content is keyed with $t
-    
-    # These are the accessors we can write
-    # :id, :title, :updated, :content
-    
     attr_reader :api
-    # Populate from a single result Hash/Hashie
+    # Initialize a Result from a single result's Hash/Hashie
     def initialize(source_hash = nil, default = nil, api = nil, &blk)
       @api = api if api
       super(source_hash, default, &blk)
@@ -25,7 +21,9 @@ module GoogleContactsApi
       _id = self["id"]
       _id ? _id["$t"] : nil
     end
-    
+
+    # For Contacts, returns the (full) name.
+    # For Groups, returns the name of the group.
     def title
       _title = self["title"]
       _title ? _title["$t"] : nil

data/lib/google_contacts_api/result_set.rb

@@ -1,7 +1,8 @@
 require 'json'
 
 module GoogleContactsApi
-  # Base class for GroupSet and ContactSet
+  # Base class for GroupSet and ContactSet that generically represents
+  # a set of results.
   class ResultSet
     include Enumerable
     attr_reader :api

data/lib/google_contacts_api/user.rb

@@ -7,8 +7,7 @@ module GoogleContactsApi
       @api = GoogleContactsApi::Api.new(oauth)
     end
 
-    # Retrieve the groups for this user
-    # TODO: Handle 403, 404, 401
+    # Retrieve the groups for this user.
     def groups(params = {})
       params = params.with_indifferent_access
       # compose params into a string
@@ -27,6 +26,7 @@ module GoogleContactsApi
       response = @api.get(url, params)
 
       case GoogleContactsApi::Api.parse_response_code(response)
+      # TODO: Better handle 401, 403, 404
       when 401; raise
       when 403; raise
       when 404; raise

data/lib/google_contacts_api/version.rb

@@ -0,0 +1,10 @@
+module GoogleContactsApi
+  module Version
+    MAJOR = 0
+    MINOR = 4
+    PATCH = 2
+    BUILD = nil
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end

data/spec/spec_helper.rb

@@ -6,7 +6,7 @@ require 'hashie'
 require 'net/http'
 require 'google_contacts_api'
 
-puts "Testing version #{GoogleContactsApi::VERSION}"
+puts "Testing version #{GoogleContactsApi::Version::STRING}"
 
 # Requires supporting files with custom matchers and macros, etc,
 # in ./support/ and its subdirectories.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google_contacts_api
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
   prerelease: 
 platform: ruby
 authors:
@@ -213,6 +213,7 @@ files:
 - lib/google_contacts_api/result.rb
 - lib/google_contacts_api/result_set.rb
 - lib/google_contacts_api/user.rb
+- lib/google_contacts_api/version.rb
 - spec/contact_set.json
 - spec/empty_contact_set.json
 - spec/errors/auth_sub_401.html
@@ -234,7 +235,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2779317021500043099
+      hash: -1381068612794242354
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: