chimps-cli 0.0.1

data/lib/chimps-cli/commands.rb

@@ -0,0 +1,179 @@
+module Chimps
+
+  config.use :commands
+
+  # A namespace to hold the various commands Chimps defines.
+  module Commands
+
+    def self.class_for name
+      self.instance_eval(name.to_s.capitalize)
+    end
+
+    def self.included obj
+      obj.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Create a new command from the given +command_name+.  The
+      # resulting command will be initialized but will not have been
+      # executed.
+      #
+      # @return [Chimps::Command]
+      def command
+        return unless Chimps.config.command
+        # Chimps.config.command_settings.resolve!
+        Chimps::Commands.class_for(Chimps.config.command_name).new(Chimps.config.command_settings)
+      end
+    end
+
+    protected
+    
+    def self.define_skip_column_names command
+      command.define :skip_column_names, :description => "Don't print column names in output (ignored unless TSV format)", :flag => :s, :type => :boolean
+    end
+
+    def self.define_data_file command
+      command.define :data, :description => "Path to a .json or .yaml file.", :flag => :d
+    end
+
+    def self.define_my command
+      command.define :my, :description => "List only resources owned by you.", :flag => :m, :type => :boolean
+    end
+
+    def self.define_pretty_print command
+      command.define :pretty, :description => "Pretty-print output", :flag => :p, :type => :boolean
+    end
+
+    def self.define_request_format command
+      command.define :request_format, :description => "The request format (json, xml, yaml) to request from Infochimps"
+    end
+
+    def self.define_response_format command
+      command.define :response_format, :description => "The response format (json, xml, yaml) to request from Infochimps"
+    end
+
+    def self.define_signable command
+      command.define :sign, :description => "Sign the request", :flag => :s, :type => :boolean
+    end
+
+    def self.define_print_headers command
+      command.define :headers, :description => "Print response headers", :flag => :i
+    end
+
+    def self.define_config
+      
+      #
+      # HTTP verbs
+      #
+      Chimps.config.define_command :get, :description => "Send a GET request" do |command|
+        # define_request_format(command)
+        define_response_format(command)
+        define_signable(command)
+        define_print_headers(command)
+      end
+
+      Chimps.config.define_command :post, :description => "Send a POST request" do |command|
+        # define_request_format(command)
+        define_response_format(command)
+        define_data_file(command)
+        define_signable(command)
+        define_print_headers(command)
+      end
+      
+      Chimps.config.define_command :put, :description => "Send a PUT request" do |command|
+        # define_request_format(command)
+        define_response_format(command)
+        define_data_file(command)
+        define_signable(command)
+        define_print_headers(command)
+      end
+      
+      Chimps.config.define_command :delete, :description => "Send a DELETE request" do |command|
+        # define_request_format(command)
+        define_response_format(command)
+        define_signable(command)
+        define_print_headers(command)
+      end
+      
+
+      #
+      # Core REST actions
+      #
+
+      Chimps.config.define_command :list, :description => "List datasets, sources, users, &c." do |command|
+        define_response_format(command)
+        define_skip_column_names(command)
+        define_my(command)
+        define_pretty_print(command)
+      end
+      
+      Chimps.config.define_command :show, :description => "Show a dataset, source, license, &c. in detail" do |command|
+        define_response_format(command)
+        define_response_format(command)
+        define_pretty_print(command)
+      end
+
+      Chimps.config.define_command :create, :description => "Create a new dataset, source, license, &c." do |command|
+        define_response_format(command)
+        define_data_file(command)
+      end
+
+      Chimps.config.define_command :update, :description => "Update an existing dataset, source, license, &c." do |command|
+        define_response_format(command)
+        define_data_file(command)
+      end
+
+      Chimps.config.define_command :destroy, :description => "Destroy an existing dataset, source, license, &c." do |command|
+        define_response_format(command)
+      end
+
+      #
+      # Workflows
+      #
+
+      Chimps.config.define_command :download, :description => "Download a dataset" do |command|
+        command.define :output, :description => "Path to output file (defaults to current directory)", :flag => :o, :type => String
+      end
+
+      # Chimps.config.define_command :upload, :description => "Upload a dataset" do |command|
+      #   command.define :create,  :description => "Create an empty upload", :flag => :C, :type => :boolean
+      #   command.define :start,   :description => "Start the processing of the upload", :flag => :s, :type => :boolean
+      #   command.define :destroy, :description => "Stop (if started) and destroy the current upload", :flag => :D, :type => :boolean
+      #   command.define :restart, :description => "Stop the current upload (if started) and begin anew", :flag => :r, :type => :boolean
+      # end
+      
+
+      #
+      # Other Actions
+      #
+
+
+      Chimps.config.define_command :me, :description => "Show your profile" do |command|
+        define_response_format(command)
+        define_pretty_print(command)
+      end
+
+      Chimps.config.define_command :search, :description => 'Search datasets, sources, licenses, &c.' do |command|
+        define_skip_column_names(command)
+        define_my(command)
+        define_pretty_print(command)
+        define_response_format(command)
+      end
+
+      Chimps.config.define_command :query, :description => "Get a response from the Query API" do |command|
+        define_pretty_print(command)
+        define_data_file(command)
+      end
+      
+      Chimps.config.define_command :test, :description => "Test your authentication credentials with Infochimps"
+
+      Chimps.config.define_help_command!
+      
+      Chimps.config.commands.keys.each do |command|
+        autoload command.to_s.capitalize.to_sym, "chimps-cli/commands/#{command}"
+      end
+    end
+    define_config
+
+  end
+end

data/lib/chimps-cli/commands/base.rb

@@ -0,0 +1,65 @@
+module Chimps
+
+  # A base class from which to subclass specific commands.  A subclass
+  # should
+  #
+  # - define class constants <tt>BANNER</tt> and <tt>HELP</tt> which
+  # - will display the appropriate help to the user.
+  # 
+  # - add specific options by defining a method that begins with
+  #   +define+ and ends with +options+ (i.e. - +define_output_options+
+  #   to add options related to output).
+  #
+  # - define a method <tt>execute!</tt> which will actually run the
+  #   command.
+  class Command
+
+    # Appears when printing help for this command, as the very first
+    # line.  Should be one-line summary of how to use this command.
+    USAGE = "Define #{self}::USAGE when you subclass Chimps::Command"
+
+    # Appears when printing help for this command.  Should consist of
+    # general help or examples of the command iteslf.  Help on
+    # specific options is automatically generated.
+    HELP   = "Define #{self}::HELP when you subclass Chimps::Command"
+
+    # The configuration settings for this command.
+    #
+    # @return [Configliere::Param]
+    attr_accessor :config
+
+    # Create a new command.  Will define options specific to
+    # subclases, parse the given +argv+, and load the global Chimps
+    # configuration.  Will _not_ execute the command.
+    #
+    # @param  [Configliere::Param]
+    # @return [Chimps::Command]
+    def initialize config
+      self.config = config
+    end
+
+    # The name of this command, including the
+    # <tt>Chimps::Commands</tt> prefix.
+    #
+    # @return [String]
+    def self.name
+      self.to_s.downcase
+    end
+
+    # The name of this command, excluding the
+    # <tt>Chimps::Commands</tt> prefix.
+    #
+    # @return [String]
+    def name
+      self.class.name.split('::').last
+    end
+    
+    # Run this command.
+    #
+    # Will raise a NotImplementedError for Chimps::Command itself --
+    # subclasses are expected to redefine this method.
+    def execute!
+      raise NotImplementedError.new("Redefine the `execute!' method in a subclass of #{self.class}.")
+    end
+  end
+end

data/lib/chimps-cli/commands/create.rb

@@ -0,0 +1,38 @@
+module Chimps
+  module Commands
+
+    # A command to issue a POST requst to create a resource at
+    # Infochimps.
+    class Create < Chimps::Command
+
+      include Chimps::Utils::ActsOnResource
+      include Chimps::Utils::UsesParamValueData
+      
+      def self.allowed_models
+        %w[dataset source license]
+      end
+
+      USAGE = "usage: chimps create [OPTIONS] [PROP=VALUE] ..."
+      HELP   = <<EOF
+
+Create a #{default_resource_type} using the properties and values supplied.
+
+#{how_to_input_data}
+#{resources_listing}
+
+Examples:
+
+  $ chimps create title='My Awesome Dataset' description="It is cool"
+  $ chimps create source -d my_source.yml
+EOF
+
+      # Issue the POST request.
+      def execute!
+        ensure_data_is_present!
+        Request.new(resources_path, :body => { resource_type => data}, :sign => true).post.print(:yaml => true)
+      end
+      
+    end
+  end
+end
+

data/lib/chimps-cli/commands/delete.rb

@@ -0,0 +1,29 @@
+module Chimps
+  module Commands
+
+    class Delete < Chimps::Command
+
+      include Chimps::Utils::HttpFormat
+      include Chimps::Utils::ExplicitPath
+
+      USAGE = "usage: chimps delete [OPTIONS] PATH"
+      HELP   = <<EOF
+
+Send a DELETE request to the given PATH at Infochimps.
+
+Examples:
+
+  $ chimps delete /datasets/my-crappy-dataset
+  $ chimps delete /sources/my-broken-source
+EOF
+
+      def execute!
+        response = Chimps::Request.new(path, :query_params => query_params, :sign => config[:sign]).delete(headers)
+        response.print_headers if config[:headers]
+        response.print
+      end
+
+    end
+  end
+end
+

data/lib/chimps-cli/commands/destroy.rb

@@ -0,0 +1,36 @@
+module Chimps
+  module Commands
+
+    # A command to issue a DELETE request against a resource at
+    # Infochimps.
+    class Destroy < Chimps::Command
+
+      include Chimps::Utils::ActsOnResource
+
+      def self.allowed_models
+        %w[dataset source license]
+      end
+
+      USAGE = "usage: chimps destroy [OPTIONS] [RESOURCE] ID_OR_SLUG"
+      HELP   = <<EOF
+
+Destroys a #{default_resource_type} identified by the given ID or slug.
+
+#{resources_listing}
+
+You can only destroy resources that you own.
+
+Examples:
+
+  $ chimps destroy my-crappy-dataset
+  $ chimps destroy source 7837
+EOF
+      
+      def execute!
+        Request.new(resource_path, :sign => true).delete.print
+      end
+      
+    end
+  end
+end
+

data/lib/chimps-cli/commands/download.rb

@@ -0,0 +1,40 @@
+module Chimps
+  module Commands
+
+    # A command to download data from Infochimps.
+    class Download < Chimps::Command
+
+      include Chimps::Utils::ActsOnResource
+
+      USAGE = "usage: chimps download [OPTIONS] ID_OR_HANDLE"
+      HELP   = <<EOF
+
+Download a dataset identified by the given ID_OR_HANDLE.
+
+If the dataset isn't free, you'll have to have purchased it first on
+Infochimps.
+
+Examples:
+
+  # download to the current directory
+  $ chimps download my-awesome-dataset
+
+  # download to /tmp directory
+  $ chimps download my-awesome-dataset --output=/tmp
+
+  # save as ~/data.tar.gz (dangerous if you change the extension!)
+  $ chimps download my-awesome-dataset --output=~/data.tar.gz
+EOF
+
+      def local_path
+        config[:output].blank? ? Dir.pwd : File.expand_path(config[:output])
+      end
+
+      def execute!
+        Chimps::Download.new(resource_identifier).download(local_path)
+      end
+      
+    end
+  end
+end
+

data/lib/chimps-cli/commands/get.rb

@@ -0,0 +1,30 @@
+module Chimps
+  module Commands
+
+    class Get < Chimps::Command
+
+      include Chimps::Utils::HttpFormat
+      include Chimps::Utils::ExplicitPath
+
+      USAGE = "usage: chimps get [OPTIONS] PATH"
+      HELP   = <<EOF
+
+Send a GET request to the given PATH at Infochimps.
+
+Examples:
+
+  $ chimps get /datasets                        # list datasets (#{default_response_fmt} by default)
+  $ chimps get /datasets --response_format=yaml # in YAML
+  $ chimps get /sources/1.xml                   # look at source 1 in XML
+EOF
+
+      def execute!
+        response = Chimps::Request.new(path, :query_params => query_params, :sign => config[:sign]).get(headers)
+        response.print_headers if config[:headers]
+        response.print
+      end
+
+    end
+  end
+end
+

data/lib/chimps-cli/commands/help.rb

@@ -0,0 +1,100 @@
+module Chimps
+  module Commands
+    class Help < Chimps::Command
+
+      USAGE = "usage: chimps help [OPTIONS] [COMMAND]"
+
+      HELP = <<EOF
+This is the Infochimps command-line client.  You can use it to search,
+browse, create, edit, or delete data and metadata in the Infochimps
+repository at http://www.infochimps.com.
+
+Before you can create, edit, or delete anything you'll need to get an
+Infochimps account at http://www.infochimps.org/signup.  You'll
+automatically be granted an API key.
+
+But you can still browse, search, and download (free) data
+immediately.
+
+Learn more about the Infochimps API which powers this tool at
+
+  http://www.infochimps.com/apis
+
+= Commands
+
+chimps is a wrapper over the RESTful Infochimps API.  It exposes the
+following core actions
+
+  $ chimps list
+  $ chimps show
+  $ chimps create
+  $ chimps update
+  $ chimps destroy
+
+for datasets (as well as other selected resources).  It also helps
+automate the workflow of uploading and downloading data with
+
+  $ chimps upload
+  $ chimps download
+
+You can also make queries against the Infochimps Query API with
+
+  $ chimps query
+
+learn more about the Infochimps Query API at
+http://www.infochimps.com/api.
+
+Finally, you can test that your system is configured properly and that
+you can authenticate with Infochimps with
+
+  $ chimps test
+
+Get more help on a specific command with
+
+  $ chimps help COMMAND
+
+for any of the commands above.
+
+= Setup
+
+Once you have obtained an API key and secret from Infochimps, place
+them in a file #{Chimps.config[:config]} in your home directory
+with the following format
+
+  ---
+  # in #{Chimps.config[:config]}
+
+  # API credentials for use with the Infochimps Dataset API
+  :site:
+    :key: oreeph6giedaeL3
+    :secret: Queechei6cu8chiuyiig8cheg5Ahx0boolaizi1ohtarooFu1doo5ohj5ohp9eehae5hakoongahghohgoi7yeihohx1eidaeng0eaveefohchoh6WeeV1EM
+
+  # API credentials for use on the Infochimps Query API
+  :query:
+    :key: zei7eeloShoah3Ce
+EOF
+  
+      def command_name
+        config.argv[1]
+      end
+
+      def command
+        @command ||= Chimps::Commands.class_for(command_name).new(Chimps.config.commands[command_name][:config])
+      end
+      
+      def execute!
+        if config.argv.size > 1 && Chimps.config.command?(command_name)
+          $stderr.puts command.class::USAGE
+          $stderr.puts command.class::HELP
+          command.config.dump_basic_help "Additional options accepted by all commands:"
+        else
+          $stderr.puts self.class::USAGE
+          $stderr.puts self.class::HELP
+        end
+        Chimps.config.dump_basic_help
+      end
+
+    end
+  end
+end
+