documentcloud 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Miles Zimmerman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+DocumentCloud RubyGem
+=====================
+
+Rubygem for interacting with the DocumentCloud API
+
+
+## Usage
+
+```gem install documentcloud``` or put in your gemfile and ```bundle install```
+
+To authenticate, initialize the configuration and pass in a block:
+
+``` ruby
+DocumentCloud.configure do |config|
+  config.email    = 'my_email@somedomain.com'
+  config.password = 'my_secret_password'
+end
+```
+
+
+### Search
+
+All search results return Document objects that has methods and accessors for the information.
+
+``` ruby
+search = DocumentCloud.search('my query')
+
+puts search.total # returns number of results
+
+puts search.documents[0].pdf
+```
+
+
+### Upload
+
+You can upload a document by providing a ruby File object, or a string with the url to a file.
+
+``` ruby
+local_doc = DocumentCloud.upload(File.new('/my/file/path.pdf','rb'), 'My Document Title')
+
+remote_doc = DocumentCloud.upload('http://somesite.com/file.pdf', 'Document Title')
+```
+
+Both return a document object which can then be used.
+
+
+### Information
+
+DocumentCloud API info: http://www.documentcloud.org/help/api

data/documentcloud.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'document_cloud/version'
+
+Gem::Specification.new do |spec|
+  spec.add_dependency "rest-client", "~> 1.6.7"
+  spec.add_dependency 'multi_json', '~> 1.8'
+  
+  spec.name          = 'documentcloud'
+  spec.version       = DocumentCloud::Version
+  spec.description   = "Rubygem for interacting with the DocumentCloud API"
+  spec.summary       = spec.description
+  spec.authors       = ["Miles Zimmerman"]
+  spec.email         = ['miles@zserver.org']
+  spec.homepage      = 'https://github.com/mileszim/documentcloud'
+  spec.licenses      = ['MIT']
+  
+  spec.files         = %w(LICENSE README.md documentcloud.gemspec)
+  spec.files        += Dir.glob("lib/**/*.rb")
+  
+  spec.require_paths = ['lib']
+end

data/lib/document_cloud.rb

@@ -0,0 +1,43 @@
+require 'rest_client'
+require 'multi_json'
+require 'date'
+
+require_relative 'document_cloud/document'
+require_relative 'document_cloud/search_results'
+require_relative 'document_cloud/default'
+require_relative 'document_cloud/configurable'
+require_relative 'document_cloud/client'
+
+module DocumentCloud
+  class << self
+    include DocumentCloud::Configurable
+    
+    # Delegate to a DocumentCloud::Client
+    #
+    # @return [DocumentCloud::Client]
+    def client
+      @client = DocumentCloud::Client.new(credentials) unless defined?(@client)
+      @client
+    end
+    
+    # Has a client been initialized on the DocumentCloud module?
+    #
+    # @return [Boolean]
+    def client?
+      !!@client
+    end
+    
+    
+    def respond_to?(method_name, include_private=false)
+      client.respond_to?(method_name, include_private) || super
+    end
+    
+    private
+
+      def method_missing(method_name, *args, &block)
+        return super unless client.respond_to?(method_name)
+        client.send(method_name, *args, &block)
+      end
+    
+  end
+end

data/lib/document_cloud/api/document.rb

@@ -0,0 +1,23 @@
+module DocumentCloud
+  module API
+    module Document
+      include DocumentCloud::API::Utils
+      DOCUMENT_PATH = "/documents/"
+      
+      # Fetch a document
+      #
+      # @param id [String] The document id
+      # @returns [DocumentCloud::Document] The fetched document
+      def document(id)
+        build_object DocumentCloud::Document, get(document_path(id))
+      end
+      
+      private
+            
+        def document_path(document_id)
+          "#{DOCUMENT_PATH}/#{document_id.to_s}.json"
+        end
+      
+    end
+  end
+end

data/lib/document_cloud/api/search.rb

@@ -0,0 +1,25 @@
+module DocumentCloud
+  module API
+    module Search
+      include DocumentCloud::API::Utils
+      SEARCH_PATH = '/search.json'
+      
+      # Search catalog of public documents
+      #
+      # @see http://www.documentcloud.org/help/api
+      # @param q [String] The search query
+      # @param options [Hash] Customizable set of options
+      # @param options [Integer] :page        Response page number
+      # @param options [Integer] :per_page    The number of documents to return per page
+      # @param options [Boolean] :sections    Include document sections in the results
+      # @param options [Boolean] :annotations Include document annotations in the results
+      # @param options [Boolean] :data        Include key/value data in the results
+      # @param options [Integer] :mentions    Include highlighted mentions of the search phrase
+      # @returns [DocumentCloud::SearchResults] Results of the search
+      def search(q, options={})
+        build_object DocumentCloud::SearchResults, get(SEARCH_PATH, options.merge(:q => q))
+      end
+      
+    end
+  end
+end

data/lib/document_cloud/api/upload.rb

@@ -0,0 +1,28 @@
+module DocumentCloud
+  module API
+    module Upload
+      include DocumentCloud::API::Utils
+      UPLOAD_PATH = '/upload.json'
+      
+      # Upload a document
+      #
+      # @see http://www.documentcloud.org/help/api
+      # @param file  [String|File] Local file to upload, or remote url of file
+      # @param title [String] The document's canonical title
+      # @param options [Hash] Customizable set of options
+      # @param options [String]  :source          The source who produced the document
+      # @param options [String]  :description     A paragraph of detailed description
+      # @param options [String]  :related_article The URL of the article associated with the document
+      # @param options [String]  :published_url   The URL of the page on which the document will be embedded
+      # @param options [String]  :access          One of 'public', 'private', 'organization', defaults to 'private'
+      # @param options [Integer] :project         A numeric Project id, to upload the document into an existing project. 
+      # @param options [Hash]    :data            A hash of arbitrary key/value data pairs
+      # @param options [Boolean] :secure          If you're dealing with a truly sensitive document, pass the "secure" parameter in order to prevent the document from being sent to OpenCalais for entity extraction. 
+      # @returns [DocumentCloud::Document] The document uploaded
+      def upload(file, title, options={})
+        build_object DocumentCloud::Document, post(UPLOAD_PATH, options.merge(file: file, title: title))
+      end
+      
+    end
+  end
+end

data/lib/document_cloud/api/utils.rb

@@ -0,0 +1,17 @@
+module DocumentCloud
+  module API
+    module Utils
+      
+      def parse_json(json)
+        MultiJson.load(json, symbolize_keys: true)
+      end
+      
+      def build_object(object, json)
+        parsed = parse_json json
+        parsed = parsed[:document] if parsed[:document]
+        object.new(parsed)
+      end
+      
+    end
+  end
+end

data/lib/document_cloud/client.rb

@@ -0,0 +1,37 @@
+require_relative 'configurable'
+require_relative 'api/utils'
+require_relative 'api/search'
+require_relative 'api/upload'
+require_relative 'api/document'
+
+module DocumentCloud
+  class Client
+    include DocumentCloud::API::Utils
+    include DocumentCloud::API::Search
+    include DocumentCloud::API::Upload
+    include DocumentCloud::API::Document
+    include DocumentCloud::Configurable
+    
+    def initialize(options={})
+      DocumentCloud::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || DocumentCloud.instance_variable_get(:"@#{key}"))
+      end
+    end
+    
+    # Perform HTTP GET request
+    def get(path, params={})
+      RestClient.get request_base+path, {params: params}
+    end
+    
+    def post(path, params={})
+      RestClient.post request_base+path, params
+    end
+    
+    private
+    
+      def request_base
+        "#{DocumentCloud::Default.http_mode}://#{@email}:#{@password}@#{DocumentCloud::Default.endpoint}"
+      end
+    
+  end
+end

data/lib/document_cloud/configurable.rb

@@ -0,0 +1,34 @@
+module DocumentCloud
+  module Configurable
+    attr_writer :email, :password
+    
+    class << self
+      def keys
+        @keys ||= [:email, :password]
+      end
+    end
+    
+    # Allow block configuration
+    def configure
+      yield self
+      format_email!
+      self
+    end
+    
+    private
+    
+      # @return [Hash]
+      def credentials
+        {
+          email:    @email,
+          password: @password 
+        }
+      end
+    
+      # Ensure email is correct format for RestClient posts
+      def format_email!
+        @email.gsub!(/@/, "%40")
+      end
+    
+  end
+end

data/lib/document_cloud/default.rb

@@ -0,0 +1,20 @@
+module DocumentCloud
+  module Default
+    
+    ENDPOINT  = 'www.documentcloud.org/api' unless defined? DocumentCloud::Default::ENDPOINT
+    HTTP_MODE = 'https'                     unless defined? DocumentCloud::Default::HTTP_mode
+    
+    class << self
+      
+      def endpoint
+        ENDPOINT
+      end
+      
+      def http_mode
+        HTTP_MODE
+      end
+      
+    end
+    
+  end
+end

data/lib/document_cloud/document.rb

@@ -0,0 +1,46 @@
+module DocumentCloud
+  class Document
+    attr_reader :id, :title, :access, :pages, :description, :source,
+      :canonical_url, :language, :display_language, :created_at, :updated_at
+    
+    def initialize(attrs={})
+      @id               = attrs[:id]
+      @title            = attrs[:title]
+      @access           = attrs[:access]
+      @pages            = attrs[:pages]
+      @description      = attrs[:description]
+      @source           = attrs[:source]
+      @canonical_url    = attrs[:canonical_url]
+      @language         = attrs[:language]
+      @display_language = attrs[:display_language]
+      @created_at       = DateTime.parse(attrs[:created_at])
+      @updated_at       = DateTime.parse(attrs[:updated_at])
+      @resources        = attrs[:resources]
+    end
+    
+    def pdf
+      @resources[:pdf]
+    end
+    
+    def print_annotations
+      @resources[:print_annotations]
+    end
+    
+    def related_article
+      @resources[:related_article]
+    end
+    
+    def text
+      @resources[:text]
+    end
+    
+    def thumbnail
+      @resources[:thumbnail]
+    end
+    
+    def image(page, size=1)
+      @resources[:page][:image].gsub(/\{page\}/, page.to_s).gsub(/\{size\}/,size.to_s)
+    end
+    
+  end
+end

data/lib/document_cloud/search_results.rb

@@ -0,0 +1,19 @@
+module DocumentCloud
+  class SearchResults
+    attr_reader :total, :page, :per_page, :query
+    
+    def initialize(attrs)
+      @total    = attrs[:total]
+      @page     = attrs[:page]
+      @per_page = attrs[:per_page]
+      @query    = attrs[:q]
+      
+      @documents = attrs[:documents].map {|d| DocumentCloud::Document.new(d) }
+    end
+    
+    def documents
+      @documents
+    end
+    
+  end
+end

data/lib/document_cloud/version.rb

@@ -0,0 +1,19 @@
+module DocumentCloud
+  class Version
+    MAJOR = 0 unless defined? DocumentCloud::Version::MAJOR
+    MINOR = 1 unless defined? DocumentCloud::Version::MINOR
+    PATCH = 1 unless defined? DocumentCloud::Version::PATCH
+    PRE = nil unless defined? DocumentCloud::Version::PRE
+
+    class << self
+
+      # @return [String]
+      def to_s
+        [MAJOR, MINOR, PATCH, PRE].compact.join('.')
+      end
+
+    end
+    
+  end
+end
+  

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: documentcloud
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Miles Zimmerman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-13 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
+email:
+- miles@zserver.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- documentcloud.gemspec
+- lib/document_cloud/api/document.rb
+- lib/document_cloud/api/search.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/search_results.rb
+- lib/document_cloud/version.rb
+- lib/document_cloud.rb
+homepage: https://github.com/mileszim/documentcloud
+licenses:
+- MIT
+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: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Rubygem for interacting with the DocumentCloud API
+test_files: []
+has_rdoc: