worochi 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2ca726002689f7fe66fe07d7ff2af93a5fc6b2e4
-  data.tar.gz: 27f7cfdcd912eeb33d9103969c59b192a79d47ab
+  metadata.gz: 69806f4b59d55c009448f571be6a511b5aa374d3
+  data.tar.gz: 107d2fd5ce53ca7fca92803a493c136f37b2e51e
 SHA512:
-  metadata.gz: 57fbb09d74618b9544fe5e2c8651637b1393cd97a76dec396474286393c6552ed8bfc6a568a57f60986f38665f1498352d87e0cb893e7a341d2e1034b3f39bf0
-  data.tar.gz: c0519b4338dbeabc4365776293935c6a6e6156c4ded75ed86756ab4d4d8c9c17807a27c013b640c33a0a4de359d44dc9c8d579871fd52e181b99518d54514639
+  metadata.gz: 7eeacb62b1a23e3e720b9ae6a274f9d6eab6737155c2ffb952ab12a99852a7192251152e360add6158cf8d3ef221ea7e2607aaf4a02aa7ba376f9c4070b897d1
+  data.tar.gz: fac7680732d95214bc6176faf2760cce1a04e76c85e51d0f1b9fab55c35a4eef09d7fe51881564a27899b5af856aba8fd16ce67855ac81bf4df25cca30c3f0e9

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Pixelapse
+
+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/lib/worochi/agent/dropbox.rb

@@ -7,6 +7,7 @@ class Worochi
     # @return [Hash] default options for Dropbox
     def default_options
       {
+        service: :dropbox,
         chunk_size: 2*1024*1024,
         overwrite: true,
         dir: '/'
@@ -20,11 +21,12 @@ class Worochi
     # @return [DropboxClient]
     def init_client
       @client = DropboxClient.new(options[:token])
+      @client
     end
 
     # Push a single {Item} to Dropbox.
     #
-    # @param [Item]
+    # @param item [Item]
     # @return [nil]
     def push_item(item)
       Worochi::Log.debug "Uploading #{item.path} (#{item.size} bytes) to Dropbox..."
@@ -40,9 +42,15 @@ class Worochi
     # Returns a list of files and subdirectories at the remote path specified
     # by `options[:dir]`.
     #
+    # @param path [String] path to list instead of the current directory
     # @return [Array<Hash>] list of files and subdirectories
-    def list
-      remote_path = options[:dir]
+    def list(path=nil)
+      if path
+        remote_path = path[0] == '/' ? path : File.join(options[:dir], path)
+      else
+        remote_path = options[:dir]
+      end
+      
       begin
         response = @client.metadata(remote_path)
       rescue DropboxError
@@ -62,8 +70,9 @@ class Worochi
     # Refer to {https://www.dropbox.com/developers/core/docs#chunked-upload
     # API documentation}.
     #
-    # @param [Item]
+    # @param item [Item]
     # @return [nil]
+    # @see https://www.dropbox.com/developers/core/docs#chunked-upload
     def push_item_chunked(item)
       Worochi::Log.debug "Using chunk uploader..."
       uploader = @client.get_chunked_uploader(item.content, item.size)
@@ -78,5 +87,18 @@ class Worochi
       uploader.finish(full_path(item), options[:overwrite])
       nil
     end
+
+    # Deletes the file at `path` from Dropbox.
+    #
+    # @param path [String] path relative to current directory
+    # @return [Boolean] `true` if a file was actually deleted
+    def delete(path)
+      begin
+        @client.file_delete(File.join(options[:dir], path))
+      rescue DropboxError
+        false
+      end
+      true
+    end
   end
 end

data/lib/worochi/agent/github.rb

@@ -10,7 +10,8 @@ class Worochi
     # @return [Hash] default options for GitHub
     def default_options
       {
-        source: 'master',
+        service: :github,
+        source: 'worochi',
         target: 'worochi',
         repo: 'darkmirage/test',
         block_size: Worochi::Helper::Github::BLOCK_SIZE,
@@ -26,12 +27,13 @@ class Worochi
     # @return [Octokit::Client]
     def init_client
       @client = Octokit::Client.new(login: 'me', oauth_token: options[:token])
+      @client
     end
 
     # Pushes a list of {Item} to GitHub.
     #
-    # @param [Array<Item>]
-    # @return [nil]
+    # @param items [Array<Item>]
+    # @return [String] Commit SHA1 hash
     # @see Agent#push_items
     def push_all(items)
       source_sha = source_branch
@@ -39,13 +41,13 @@ class Worochi
       commit = @client.create_commit(repo, options[:commit_msg], source_sha,
                                      target_branch)
       @client.update_ref(repo, "heads/#{options[:target]}", commit.sha)
-      nil
+      commit.sha
     end
 
     # Pushes a single {Item} to GitHub. This means making a new commit for each
     # file. Not recommended and should just use {#push_all} instead.
     #
-    # @param [Item]
+    # @param item [Item]
     # @return [nil]
     def push_item(item)
       Worochi::Log.warn 'push_item should not be used for GitHub'
@@ -55,11 +57,13 @@ class Worochi
     # Returns a list of files and subdirectories at the remote path specified
     # by `options[:dir]`.
     #
+    # @param path [String] path to list instead of the current directory
+    # @param sha [String] list a different branch than the `:source`
     # @return [Array<Hash>] list of files and subdirectories
-    def list
-      remote_path = options[:dir].sub(/^\//, '').sub(/\/$/, '')
+    def list(path=nil, sha=nil)
+      remote_path = (path || options[:dir]).sub(/^\//, '').sub(/\/$/, '')
 
-      result = @client.tree(repo, source_branch, recursive: true).tree
+      result = @client.tree(repo, sha || source_branch, recursive: true).tree
       result.sort! do |x, y|
         x.path.split('/').size <=> y.path.split('/').size
       end
@@ -124,7 +128,8 @@ class Worochi
       if item.size > options[:block_size]
         sha = stream_blob(item)
       else
-        sha = @client.create_blob(repo, Base64.strict_encode64(item.read), 'base64')
+        sha = @client.create_blob(repo, Base64.strict_encode64(item.read),
+                                  'base64')
       end
       Worochi::Log.debug "Uploaded [#{sha}]"
       sha

data/lib/worochi/agent/sample.rb

@@ -3,11 +3,14 @@ class Worochi
   # This is a sample of methods that should be implemented by a service agent.
   class Agent::Sample < Agent
 
+    # This is the minimum set of default options that should be specified.
+    #
     # @return [Hash] default options for sample API
     # @see Agent#set_options
     def default_options
       {
-        dir: '/'
+        service: :sample, # service name
+        dir: '/' # remote directory to act on
       }
     end
 
@@ -45,11 +48,13 @@ class Worochi
     # least the keys `:name`, `:path`, and `:type`, but can also contain other
     # service-specific meta information.
     #
+    # @param path [String] path to list instead of the current directory
     # @return [Array<Hash>] list of files and subdirectories
     # @see Agent#folders
     # @see Agent#files
-    def list
-      result = @client.get_file_list
+    def list(path=nil)
+      remote_path = path || options[:dir]
+      result = @client.get_file_list(remote_path)
       result.map do |elem|
         {
           name: elem.name,

data/lib/worochi/agent.rb

@@ -19,14 +19,13 @@ class Worochi
     # format the file list. An optional `opts` hash can be used to update the
     # agent options before pushing.
     #
-    # @example
-    #     agent = Worochi.create(:github, 'sfsFj41na89cx')
-    #     agent.push({ source: 'http://a.com/file.jpg', path: 'folder/file.jpg' })
-    #
     # @param origin [Array<Hash>, Array<String>, Hash, String]
     # @param opts [Hash] update agent options before pushing
     # @return [nil]
     # @see Item.open
+    # @example
+    #     agent = Worochi.create(:github, 'sfsFj41na89cx')
+    #     agent.push({ source: 'http://a.com/file.jpg', path: 'folder/file.jpg' })
     def push(origin, opts=nil)
       set_options(opts) unless opts.nil?
       items = Item.open(origin)
@@ -59,23 +58,38 @@ class Worochi
       nil
     end
 
-    # Returns a list of subdirectories at the remote path specified by
-    # `options[:dir]`. Relies on the service-specific implementation of
-    # `#list`.
-    #
-    # @return [Array<Hash>] list of subdirectories
-    def folders(details=false)
-      result = list.reject { |elem| elem[:type] != 'folder' }
-      result.map { |elem| elem[:name] } unless details
-    end
-
     # Returns a list of files at the remote path specified by `options[:dir]`.
     # Relies on the service-specific implementation of `#list`.
+    # 
+    # @overload files(details)
+    #   @param details [Boolean] display more information
+    # @overload files(path, details=false)
+    #   @param path [String] remote path to list instead of current directory
+    #   @param details [Boolean] display more information
+    # @return [Array<String>, Array<Hash>] list of files
+    # @example
+    #     agent = Worochi.create(:dropbox, 'sfsFj41na89cx', dir: '/abc')
+    #     agent.files # => ["k.jpg", "t.txt"]
+    #     agent.files(true)
+    #     # => [
+    #     #      { name: "k.jpg", type: "file", path: "/abc/k.jpg"},
+    #     #      { name: "t.txt", type: "file", path: "/abc/t.txt"}
+    #     #    ]
+    def files(*args)
+      list_helper(true, args)
+    end
+
+    # Returns a list of subdirectories at the remote path specified by
+    # `options[:dir]`. Relies on the service-specific implementation of
+    # `#list`. Refer to {#files} for overloaded prototypes.
     #
-    # @return [Array<Hash>] list of files
-    def files(details=false)
-      result = list.reject { |elem| elem[:type] != 'file' }
-      result.map { |elem| elem[:name] } unless details
+    # @return [Array<String>, Array<Hash>] list of subdirectories
+    # @see #files
+    # @example
+    #     agent = Worochi.create(:dropbox, 'sfsFj41na89cx', dir: '/abc')
+    #     agent.folders # => ["folder1", "folder2"]
+    def folders(*args)
+      list_helper(false, args)
     end
 
     # Updates {.options} using `opts`.
@@ -97,26 +111,51 @@ class Worochi
       options
     end
 
+    # Returns the display name for the agent's service.
+    #
+    # @return [String] display name
+    def name
+      Worochi::Config.humanize_service(type)
+    end
+
   private
+    # Parses the arguments for {#files} and {#folders}.
+    #
+    # @param file_only [Boolean] filters files or folders
+    # @param args [Array] argument list
+    # @return [Array<String>, Array<Hash>] list of files or folders
+    def list_helper(file_only, args)
+      details = true if args.first == true
+      if args.first.kind_of?(String)
+        path = args.first 
+        details = true if args[1] == true
+      end
+      excluded = file_only ? 'folder' : 'file'
+      result = list(path).reject { |elem| elem[:type] == excluded }
+      result.map! { |elem| elem[:name] } unless details
+      result
+    end
+
     # @return [String] full path combining remote directory and item path
     def full_path(item)
       File.join(options[:dir], item.path)
     end
 
-    # @return [Hash] default options for agents that do not override this
+    # Agents should override this.
+    #
+    # @return [nil]
     def default_options
-      { dir: '/' }
+      raise Error, 'Default options not specified.'
     end
 
     class << self
     public
       # Creates a new service-specific {Agent} based on `:service`.
       #
-      # @example
-      #     Worochi::Agent.new({ service: :github, token:'6st46setsybhd64' })
-      #
       # @param opts [Hash] service options; must contain `:service` key.
       # @return [Agent]
+      # @example
+      #     Worochi::Agent.new({ service: :github, token:'6st46setsybhd64' })
       def new(opts={})
         service = opts[:service]
         if self.name == 'Worochi::Agent'
@@ -131,6 +170,8 @@ class Worochi
       # Returns the class name for the {Agent} given a service name
       #
       # @return [String]
+      # @example
+      #     class_name(:google_drive) # => "GoogleDrive"
       def class_name(service)
         service.to_s.split('_').map{|e| e.capitalize}.join
       end

data/lib/worochi/config.rb

@@ -1,22 +1,54 @@
 class Worochi
   # Configurations for Worochi.
   module Config
-    @services = [:github, :dropbox]
+    @services = {
+      github: [1, 'GitHub'],
+      dropbox: [2, 'Dropbox']
+    }
     @s3_bucket = 'data-pixelapse'
     @s3_prefix = 's3'
 
     class << self
       # Array of service names. 
+      #
       # @return [Array<Symbol>]
-      attr_reader :services
+      def services
+        @services.keys
+      end
+
+      # Returns display name for the service.
+      #
+      # @param service [Symbol]
+      # @return [String] display name
+      def humanize_service(service)
+        @services[service][1]
+      end
+
+      # Returns the service ID for the service, which can be used as a
+      # primary key for databases.
+      #
+      # @param service [Symbol]
+      # @return [Integer] service ID
+      def service_id(service)
+        @services[service][0]
+      end
 
       # Name of S3 bucket.
+      #
       # @return [String]
       attr_reader :s3_bucket
 
       # Prefix for S3 resource paths.
+      #
       # @return [String]
       attr_reader :s3_prefix
+
+      # Disable debug and error messages if `true`.
+      #
+      # @return [Boolean]
+      attr_accessor :silent
+
+      alias_method :silent?, :silent
     end
   end
 end

data/lib/worochi/error.rb

@@ -1,2 +1,3 @@
+# Exception class for {Worochi} namespace
 class Worochi::Error < StandardError
 end

data/lib/worochi/helper/github.rb

@@ -4,6 +4,7 @@ class Worochi
   # Helper classes for GitHub JSON streaming.
   module Helper::Github
 
+    # Size to read in. Must be a multiple of 3 for Base64 streaming.
     BLOCK_SIZE = 12288
 
     # This is a wrapper that produces a JSON stream that works with

data/lib/worochi/helper.rb

@@ -1,16 +1,9 @@
 require 'aws-sdk' unless Worochi::Config.s3_bucket.nil?
 
 class Worochi
+  # Contains any global helper methods not specific to any individual service.
   module Helper
     class << self
-      # A regex generated from {Config.s3_prefix} for determining if a given
-      # String is an S3 path.
-      #
-      # @return [Regexp]
-      def s3_prefix_re
-        /^#{Config.s3_prefix}\:/
-      end
-
       # Given an S3 path, return the full URL for the corresponding object
       # determined using the AWS SDK.
       #
@@ -29,6 +22,15 @@ class Worochi
       def is_s3_path?(path)
         !s3_prefix_re.match(path).nil?
       end
+
+    private
+      # A regex generated from {Config.s3_prefix} for determining if a given
+      # String is an S3 path.
+      #
+      # @return [Regexp]
+      def s3_prefix_re
+        /^#{Config.s3_prefix}\:/
+      end
     end
   end
 end

data/lib/worochi/item.rb

@@ -15,10 +15,12 @@ class Worochi
     # An IO object containing the content of the file being pushed.
     # @return [IO]
     attr_accessor :content
-    def initialize(opts={})
-      @path = opts[:path]
-      raise Error, 'Missing Item content' if !opts[:content]
-      @content = opts[:content]
+
+    # @param path [String] relative destination path including file name
+    # @param content [IO] file content
+    def initialize(path, content)
+      @path = path
+      @content = content
       @content.rewind
     end
 
@@ -34,7 +36,15 @@ class Worochi
     #
     # @return [String]
     def read(*args)
-      content.read(args)
+      content.read(*args)
+    end
+
+    # Rewinds the content. This is just a wrapper for the `#rewind` method on
+    # {#content}.
+    #
+    # @return [0]
+    def rewind
+      content.rewind
     end
 
     class << self
@@ -79,12 +89,11 @@ class Worochi
           source = entry
         end
 
-        Item.new({
-          path: path || File.basename(source),
-          content: retrieve(source)
-        })
+        Item.new(path || File.basename(source), retrieve(source))
       end
 
+    private
+
       # Retrieves the file content from `source`.
       #
       # @param source [String] local or remote location of the file content

data/lib/worochi/log.rb

@@ -1,7 +1,9 @@
 require 'logger'
 
 class Worochi
+  # Implements colored log messages.
   class Log
+    # Maps severity level to color code for logging.
     SEVERITY_COLOR = {
       'DEBUG' => 37,
       'INFO' => 32,
@@ -10,6 +12,7 @@ class Worochi
       'FATAL' => 31
     }
     class << self
+      # Initializes the logging system.
       def init_log
         @logger = Logger.new(STDOUT)
         @logger.formatter = proc do |severity, datetime, progname, msg|
@@ -17,22 +20,30 @@ class Worochi
         end
       end
 
+      # Prints DEBUG messages
       def debug(message)
+        return if Worochi::Config.silent?
         init_log if @logger.nil?
         @logger.debug message
       end
 
+      # Prints WARN messages
       def warn(message)
+        return if Worochi::Config.silent?
         init_log if @logger.nil?
         @logger.warn message
       end
 
+      # Prints INFO messages
       def info(message)
+        return if Worochi::Config.silent?
         init_log if @logger.nil?
         @logger.info message
       end
 
+      # Prints ERROR messages
       def error(message)
+        return if Worochi::Config.silent?
         init_log if @logger.nil?
         @logger.error message
       end

data/lib/worochi/version.rb

@@ -0,0 +1,4 @@
+class Worochi
+  # Current version of the gem
+  VERSION = '0.0.1'
+end

data/lib/worochi.rb

@@ -5,6 +5,8 @@ require 'worochi/helper'
 require 'worochi/item'
 require 'worochi/agent'
 
+# The main class for the gem. This and the {Agent} class are the main
+# endpoints for interacting with the remote services.
 class Worochi
   @agents = []
 
@@ -17,6 +19,11 @@ class Worochi
     # Creates a new {Worochi::Agent} and adds it to the list of agents
     # listening to {Worochi.push} requests.
     #
+    # @param service [Symbol] service name as defined in {Config.services}
+    # @param token [String] authorization token for the service API
+    # @param opts [Hash] additional service-specific options
+    # @return [Worochi::Agent]
+    # @see Agent.new
     # @example
     #     Worochi.create(:dropbox, 'as89h38nFBUSHFfuh99f', { dir: '/folder' })
     # @example
@@ -27,12 +34,6 @@ class Worochi
     #       commit_msg: 'Hello'
     #     }
     #     Worochi.create(:github, '6st46setsytgbhd64', opts)
-    #
-    # @param service [Symbol] service name as defined in {Config.services}
-    # @param token [String] authorization token for the service API
-    # @param opts [Hash] additional service-specific options
-    # @return [Worochi::Agent]
-    # @see Agent.new
     def create(service, token, opts={})
       opts[:service] = service
       opts[:token] = token
@@ -47,7 +48,7 @@ class Worochi
     # @param agent [Worochi::Agent]
     # @return [nil]
     def add(agent)
-      @agents << agent
+      @agents << agent unless @agents.include?(agent)
       nil
     end
 
@@ -62,13 +63,13 @@ class Worochi
     end
 
     # Remove all agents belonging to a given service from the list. Removes
-    # all agents if service is not specified. (See {.reset}).
-    #
-    # @example
-    #     Worochi.remove(:dropbox)
+    # all agents if service is not specified.
     #
     # @param service [Symbol] service name as defined in {Config.services}
     # @return [nil]
+    # @see Worochi.reset
+    # @example
+    #     Worochi.remove(:dropbox)
     def remove_service(service=nil)
       if service.nil?
         reset
@@ -78,18 +79,24 @@ class Worochi
       nil
     end
 
-    # Removes all agents from the list
+    # Removes all agents from the list.
     #
     # @return [nil]
     def reset
       @agents.clear
     end
 
-    # List the active agents.
+    # List the active agents in a human-readable form.
     #
-    # @return [Array<String>]
-    def list
-      @agents.map { |a| a.to_s }
+    # @param print [Boolean] prints the result if `true`
+    # @return [String] formatted list of agents
+    def list(print=true)
+      list = @agents.each_with_index.map do |a, i|
+        "  \033[33m# #{i}\033[0m\t#{a.name}"
+      end
+      result = list.join("\n")
+      puts result if print && !result.empty?
+      result
     end
 
     # @return [Integer] number of active agents.