documentcloud 0.2.2 → 0.3.1

data/README.md

@@ -1,7 +1,10 @@
 DocumentCloud RubyGem
 =====================
 
-Rubygem for interacting with the DocumentCloud API.
+[![Gem Version](https://badge.fury.io/rb/documentcloud.png)](http://badge.fury.io/rb/documentcloud)
+
+Rubygem for interacting with the DocumentCloud API
+
 
 
 ## Usage
@@ -9,11 +12,10 @@ Rubygem for interacting with the DocumentCloud API.
 ```gem install documentcloud``` or put in your gemfile and ```bundle install```
 
 then
-
-```ruby
+``` ruby
 require 'documentcloud'
 ```
-
+if not in Rails
 
 To authenticate, initialize the configuration and pass in a block:
 
@@ -51,31 +53,53 @@ remote_doc = DocumentCloud.upload('http://somesite.com/file.pdf', 'Document Titl
 Both return a document object which can then be used.
 
 
+## Objects
+
+This gem creates several objects built from the JSON response in order to provide convenience methods and accessors.
+
 ### Document
 
-Fetch a document by passing the document id.
+Document objects wrap any document JSON. They are returned in search results, upload, and document methods.
 
 ``` ruby
 doc = DocumentCloud.document('1234-document-id')
-```
-
 
+# Accessors
+doc.id
+doc.title
+doc.access
+doc.pages
+doc.description
+doc.source
+doc.canonical_url
+doc.language
+doc.display_langauge
+
+# Methods
+doc.pdf               # Full URL to pdf
+doc.print_annotations
+doc.related_article
+doc.text              # Raw parsed text from document
+doc.thumbnail         # Primary thumbnail of document
+
+# Images
+doc.image(page, size) # Returns the image of a page at the specified size
+```
 
-### Update
-
-Update a document by providing the file id, and any parameters you want to change.
+### Search Results
+SearchResults objects return information about the search, and an array of Document objects
 
 ``` ruby
-updated_doc = DocumentCloud.update('1234-file-name', title: 'Changed Document Title')
-```
-
+results = DocumentCloud.search('my query')
 
-### Destroy
+results.total    # Total number of results
+results.page     # The current results page. Used by specifying page param: DocumentCloud.search('my query', page: 2)
+results.per_page # Number of results per page
+results.query    # Query string
 
-Destroy a document simply by passing the document id.
+results.documents # Array of documents of results:
 
-``` ruby
-DocumentCloud.destroy('1234-file-name')
+results.documents[0].title # First result title
 ```
 
 

data/lib/document_cloud.rb

@@ -3,6 +3,7 @@ require 'multi_json'
 require 'date'
 
 require_relative 'document_cloud/document'
+require_relative 'document_cloud/project'
 require_relative 'document_cloud/search_results'
 require_relative 'document_cloud/default'
 require_relative 'document_cloud/configurable'

data/lib/document_cloud/api/create_project.rb

@@ -0,0 +1,21 @@
+module DocumentCloud
+  module API
+    module CreateProject
+      include DocumentCloud::API::Utils
+      PROJECTS_PATH = "/projects.json"
+
+      # Create new project
+      #
+      # @see http://www.documentcloud.org/help/api
+      # @param title [String] The document's canonical title
+      # @param options [Hash] Customizable set of options
+      # @param options [String] :description  A paragraph of detailed description
+      # @param options [Array]  :document_ids A list of documents that the project contains, by id
+      # @returns [DocumentCloud::Project] The project created
+      def create_project(title, options={})
+        build_object DocumentCloud::Project, post(PROJECTS_PATH, options.merge(title: title))
+      end
+      
+    end
+  end
+end

data/lib/document_cloud/api/entities.rb

@@ -0,0 +1,24 @@
+module DocumentCloud
+  module API
+    module Entities
+      include DocumentCloud::API::Utils
+      DOCUMENT_PATH = "/documents"
+      ENTITIES_PATH = "/entities.json"
+      
+      # Fetch document entities
+      #
+      # @param id [String] The document id
+      # @returns [Hash] The fetched document entities
+      def entities(id)
+        parse_json(get(entities_path(id)))[:entities]
+      end
+      
+      private
+            
+        def entities_path(document_id)
+          "#{DOCUMENT_PATH}/#{document_id.to_s}/#{ENTITIES_PATH}"
+        end
+      
+    end
+  end
+end

data/lib/document_cloud/api/projects.rb

@@ -0,0 +1,15 @@
+module DocumentCloud
+  module API
+    module Projects
+      include DocumentCloud::API::Utils
+      PROJECTS_PATH = "/projects.json"
+
+      # List projects
+      #
+      # @returns [Hash] The fetched document entities
+      def projects
+        build_objects DocumentCloud::Project, get(PROJECTS_PATH)
+      end
+    end
+  end
+end

data/lib/document_cloud/api/update_project.rb

@@ -0,0 +1,28 @@
+module DocumentCloud
+  module API
+    module UpdateProject
+      include DocumentCloud::API::Utils
+      PROJECT_PATH = "/projects"
+
+      # update a project
+      #
+      # @see http://www.documentcloud.org/help/api
+      # @param id [String] The project id
+      # @param options [Hash] Customizable set of options
+      # @param options [String] :title        The document's canonical title
+      # @param options [String] :description  A paragraph of detailed description
+      # @param options [Array]  :document_ids A list of documents that the project contains, by id
+      # @returns [DocumentCloud::Project] The project created
+      def update_project(id, options={})
+        build_object(DocumentCloud::Project, put(project_path(id), options))
+      end
+      
+      private
+            
+        def project_path(project_id)
+          "#{PROJECT_PATH}/#{project_id.to_s}.json"
+        end
+      
+    end
+  end
+end

data/lib/document_cloud/api/utils.rb

@@ -9,9 +9,19 @@ module DocumentCloud
       def build_object(object, json)
         parsed = parse_json json
         parsed = parsed[:document] if parsed[:document]
+        parsed = parsed[:project]  if parsed[:project]
+        parsed = parsed[:projects] if parsed[:projects]
         object.new(parsed)
       end
       
+      def build_objects(object, json)
+        parsed = parse_json json
+        parsed = parsed[:document] if parsed[:document]
+        parsed = parsed[:project]  if parsed[:project]
+        parsed = parsed[:projects] if parsed[:projects]
+        return parsed.map{|o| object.new(o) }
+      end
+      
     end
   end
 end

data/lib/document_cloud/client.rb

@@ -5,6 +5,10 @@ require_relative 'api/upload'
 require_relative 'api/document'
 require_relative 'api/update'
 require_relative 'api/destroy'
+require_relative 'api/entities'
+require_relative 'api/projects'
+require_relative 'api/create_project'
+require_relative 'api/update_project'
 
 module DocumentCloud
   class Client
@@ -14,6 +18,10 @@ module DocumentCloud
     include DocumentCloud::API::Document
     include DocumentCloud::API::Update
     include DocumentCloud::API::Destroy
+    include DocumentCloud::API::Entities
+    include DocumentCloud::API::Projects
+    include DocumentCloud::API::CreateProject
+    include DocumentCloud::API::UpdateProject
     include DocumentCloud::Configurable
     
     def initialize(options={})

data/lib/document_cloud/configurable.rb

@@ -1,3 +1,4 @@
+require 'cgi'
 module DocumentCloud
   module Configurable
     attr_writer :email, :password
@@ -12,6 +13,7 @@ module DocumentCloud
     def configure
       yield self
       format_email!
+      format_password!
       self
     end
     
@@ -27,7 +29,10 @@ module DocumentCloud
     
       # Ensure email is correct format for RestClient posts
       def format_email!
-        @email.gsub!(/@/, "%40")
+        @email = CGI.escape @email
+      end
+      def format_password!
+        @password = CGI.escape @password
       end
     
   end

data/lib/document_cloud/document.rb

@@ -42,5 +42,10 @@ module DocumentCloud
       @resources[:page][:image].gsub(/\{page\}/, page.to_s).gsub(/\{size\}/,size.to_s)
     end
     
+    def entities
+      @entities ||= DocumentCloud.entities(@id)
+      @entities
+    end
+    
   end
 end

data/lib/document_cloud/project.rb

@@ -0,0 +1,18 @@
+module DocumentCloud
+  class Project
+    attr_reader :id, :title, :description
+    
+    def initialize(attrs={})
+      @id               = attrs[:id]
+      @title            = attrs[:title]
+      @description      = attrs[:description]
+      @document_ids     = attrs[:document_ids]
+    end
+    
+    def documents
+      @documents ||= @document_ids.map {|id| DocumentCloud.document(id) }
+      @documents
+    end
+    
+  end
+end

data/lib/document_cloud/version.rb

@@ -1,8 +1,8 @@
 module DocumentCloud
   class Version
     MAJOR = 0 unless defined? DocumentCloud::Version::MAJOR
-    MINOR = 2 unless defined? DocumentCloud::Version::MINOR
-    PATCH = 2 unless defined? DocumentCloud::Version::PATCH
+    MINOR = 3 unless defined? DocumentCloud::Version::MINOR
+    PATCH = 1 unless defined? DocumentCloud::Version::PATCH
     PRE = nil unless defined? DocumentCloud::Version::PRE
 
     class << self
@@ -13,7 +13,6 @@ module DocumentCloud
       end
 
     end
-    
+
   end
 end
-  

metadata

@@ -1,41 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: documentcloud
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
+  prerelease: 
 platform: ruby
 authors:
 - Miles Zimmerman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-13 00:00:00.000000000 Z
+date: 2015-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.6.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.6.7
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
 description: Rubygem for interacting with the DocumentCloud API
@@ -48,16 +53,21 @@ files:
 - LICENSE
 - README.md
 - documentcloud.gemspec
+- lib/document_cloud/api/create_project.rb
 - lib/document_cloud/api/destroy.rb
 - lib/document_cloud/api/document.rb
+- lib/document_cloud/api/entities.rb
+- lib/document_cloud/api/projects.rb
 - lib/document_cloud/api/search.rb
 - lib/document_cloud/api/update.rb
+- lib/document_cloud/api/update_project.rb
 - lib/document_cloud/api/upload.rb
 - lib/document_cloud/api/utils.rb
 - lib/document_cloud/client.rb
 - lib/document_cloud/configurable.rb
 - lib/document_cloud/default.rb
 - lib/document_cloud/document.rb
+- lib/document_cloud/project.rb
 - lib/document_cloud/search_results.rb
 - lib/document_cloud/version.rb
 - lib/document_cloud.rb
@@ -65,25 +75,27 @@ files:
 homepage: https://github.com/mileszim/documentcloud
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.10
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Rubygem for interacting with the DocumentCloud API
 test_files: []
+has_rdoc: 

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MjI1MGE0NTU0MTRiMDk3ZmE4ODQ0NjAwNmNlODc3YWM4YTZiZWZmYQ==
-  data.tar.gz: !binary |-
-    MDkwYjFlNDRkZmRlZjRmMGNiNjVkNzE1OTEwNGNiZWMxZTE5ZDQ3NQ==
-SHA512:
-  metadata.gz: !binary |-
-    OWIzMDcxMDk1ZWE1M2Q0NjNiNTVlZTc1MjUxNWFkOTE3NTQ5M2ViYzhhNjkz
-    MTIyNTYwMThmODBkOGUzMTc2YmU5NzE4MjE5NDg4ZDliMzhjN2NiYzg1YzU5
-    NTkxNzIyNWIzZTkyN2MyYmYwZDQ1YmQyYmE3MGM4YjM0MTQ0ZWY=
-  data.tar.gz: !binary |-
-    MzdkMTk5MDk1ODFjNTEyYjAzNWJjMDVkYWZmYjJhMWFjNDVlZjAzOWIxMzZk
-    ZDVjNDE5ZDRlYjBhZGQwZWIyZTk2ZTc1ZWIzNjEyMjhkMDJhYzNhODc5MzAx
-    Zjc1MGY3M2IyODQ3NWE1YTYzYjJiMWIxY2U4NzAzNWE0ZDFjNTI=