acclimate 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c626e3bd29a1754fcd54ef6d510992fb6f839954
-  data.tar.gz: 939c681995bc048e0d7588584dfeec286d8df4ea
+  metadata.gz: afef825e7d4cfbca7f8904fa47a080fd83180df6
+  data.tar.gz: e3ded2d6fb6abcf8ee0f1f452f9ce75666bb8dd7
 SHA512:
-  metadata.gz: fba0333e080bc8bb26016b793b25420812f77fc99643a2a38944d689985297241f42203e887fbf9251deb1279ce1c04207be8fd1ca02f37c1ab58417de241a12
-  data.tar.gz: 5f06b381f3390d53f9059aff5411485b987fb9d193658bfab2df033f792b078eb5b105ce87ca16b73ef1ebdc2b28c7ca6f87511a95e926502bb17b134211af71
+  metadata.gz: 266b1c62853e24fef875cd348ed9721948b613b4766edb2857b20c85b4f219b882521e0b6126429d2cd6e7cd4c48c19b9dbb0be1047d57ad804e033c3ca9eef9
+  data.tar.gz: 419bd4a87a130f610cd03793b276ce91b18f773a460313dd4da80b1e8ae4604f1bf72ccbf494d53b502d9cf2546702da0bd9a9d451259ade74f1712a1f41a936

data/.ruby-gemset

@@ -1 +1 @@
-phil_columns
+acclimate

data/README.md

@@ -1,6 +1,6 @@
 # Acclimate
 
-A CLI building toolkit
+A CLI building toolkit.  Pronounced A CLI Mate.
 
 
 ## Installation
@@ -17,6 +17,242 @@ Or install it yourself as:
 
     $ gem install acclimate
 
+
 ## Usage
 
-This release is simply a placeholder for the gem.
+Acclimate provides a toolkit to aid in the boilerplate pieces of a CLI project including: configuration, commands, 
+helpers for the CLI class(es), error handling and some output helpers.  Acclimate assumes the usage of 
+[Thor](http://whatisthor.com/) for creating the CLI portion of your CLI project.  Please refer to Thor's documentation
+for further help.
+
+### CliHelper
+
+Acclimate's CliHelper module provides convenience methods as well as some sane defaults for [Thor](http://whatisthor.com/).
+
+#### The #execute Method
+
+The execute method provides a common API to direct your CLI commands to actual command class instances to do the work.
+
+    module AwesomeCli
+      class Cli < Thor
+        include Acclimate::CliHelper
+
+        desc "some-command", "Does something useful"
+        option :do_it_good, type: :boolean
+        def some_command( filepath )
+          execute AwesomeCli::Command::SomeCommand, filepath: filepath
+        end
+      end
+    end
+
+The call to `#execute` instantiates the command class, and merges the filepath argument into the options arguments, passing
+it into the command class' initializer.
+
+
+### Configuration
+
+Acclimate's configuration class provides a base from which to build a custom configuration class in your
+CLI project.  The simplest implementation of a configuration class for your project is to inherit from 
+`Acclimate::Configuration` and do nothing else.
+
+    module AwesomeCli
+      class Configuration < Acclimate::Configuration
+      end
+    end
+
+Now you can use the configuration class simply by passing a hash of values into it.
+
+    conf = AwesomeCli::Configuration.new( env: 'development', filepath: 'some/file/path' )
+
+    conf[:env]               #=> 'development'
+    conf['env']              #=> 'development'
+    conf.env                 #=> 'development'
+    conf.slice( :env )       #=> { :env => 'development }
+    conf.slice( :env ).class #=> AwesomeCli::Configuration
+
+Pretty much any method that works on a standard `Hash` will work on the configuration.  This magic is a result
+of `Acclimate::Configuration` inheriting from [Hashie::Mash](https://github.com/intridea/hashie#mash).
+
+In addition, any commands (see the commands section below) that inherit from `Acclimate::Command` accept the
+command line options in their initializer and expose a `#config` method that wraps the options in a configuration
+object for you.
+
+### Commands
+
+Acclimate's command class provides a base from which to build the commands for your CLI.  Whn building an Acclimate
+CLI, we use commands to encapsulate the actual behavior of each CLI defined command or sub-command.  This serves multiple 
+purposes.  First, it keeps the command logic out of the CLI class(es), which is basically the view or GUI of a CLI project.
+Second, having the actual logic encapsulated in a command means including our CLI gem into another project and borrowing 
+the behavior is possible through direct utilization of the command class(es), without interacting with the CLI classes.
+
+Building a command class is as simple as inheriting from `Acclimate::Command` and implementing an `#execute` method.
+
+    module AwesomeCli
+      class SomeCommand < Acclimate::Command
+        def execute
+          # do something useful ...
+        end
+      end
+    end
+
+Due to the fact that your commands will certainly have some additional common behavior that Acclimate does not provide,
+it is a good idea to have a base class for your commands.  For instance, in order to use your custom configuration class 
+as opposed to an instance of `Acclimate::Configuration`, you must override the `#config_klass` method in your command(s). 
+You command base class is the ideal place to do so.
+
+    module AwesomeCli
+      class CommandBase < Acclimate::Command
+      protected
+        def a_helper
+          # do something helpful
+        end
+
+        def config_klass
+          AwesomeCli::Configuration
+        end
+      end
+
+      class SomeCommand < CommandBase
+        def execute
+          # do something useful ...
+        end
+      end
+    end
+
+### Output
+
+Acclimate's output module can be included in any class in your CLI and is already included in any class that inherits from
+`Acclimate::Command` or includes `Acclimate::CliHelper`.  In addition to it own [output helpers](https://github.com/midas/acclimate/blob/master/lib/acclimate/output.rb), 
+the module also include [Thor's shell module](http://rdoc.info/github/wycats/thor/Thor/Shell/Basic).
+
+#### The #confirm Method
+
+Acclimate's `#confirm` method is the accepted strategy for outputting command status throughout the execution of the 
+command.  The `#confirm` method outputs a statement, executes a provided block, then outputs either OK or ERROR depending 
+on the results of the block.
+
+    module AwesomeCli
+      module SomeCommand < CommandBase
+        def execute
+          confirm "Doing something useful" do
+            # something useful here
+          end
+
+          confirm "Doing something helpful" do
+            # something helpful here
+          end
+        end
+      end
+    end
+
+Executing the previous command
+
+    command = AwesomeCli::SomeCommand.new
+    command.execute
+
+Results in the following output
+
+    Doing something useful ... OK
+    Doing something helpful ... OK
+
+
+## Error Handling
+
+Acclimate can handle known error conditions gracefully for you.  In the cases wher eyou would like to output a useful
+error message but not overwhelm your user with a Ruby backtrace, simply raise the `Acclimate::Error`.
+
+    raise Acclimate::error, 'External service unavailable, please try the command again later'
+
+### Errors and the #confirm Method
+
+If an error is encountered within the block that should be gracefully handled by Acclimate as opposed to an ugly Ruby
+stacktrace, you may raise Acclimate::Error.
+
+    module AwesomeCli
+      module SomeCommand < CommandBase
+        def execute
+          confirm "Doing something useful" do
+            raise Acclimate::Error, 'A known error description'
+          end
+        end
+      end
+    end
+
+Executing the previous command
+
+    command = AwesomeCli::SomeCommand.new
+    command.execute
+
+Results in the following output
+
+    Doing something useful ... ERROR
+    Error: A known error condition
+
+By default, the exit code for an error is 1.  This can be overridden when raising an error.
+
+    raise Acclimate::Error.new( 'A known error description', exit_code: 35 )
+
+In some cases it is not enough to raise an `Acclimate::Error` and let the graceful error handling ensue.  You may need 
+to clean something up or want to output additional error details.  It is this case the `Acclimate::ConfirmationError` is
+for.
+ 
+Let's assume your command is parsing a text file and wants to output which lines were unparseable along with an error 
+message.
+
+    module AwesomeCli
+      module ParseTextFile < CommandBase
+        def execute
+          confirm "Parsing text file" do
+            parse_file
+            raise_if_in_error_lines!
+          end
+        end
+
+      protected
+
+        def raise_if_in_error_lines!
+          raise Acclimate::ConfirmationError.new( 'Unparseable lines were encountered', exit_code: 12, 
+                                                                                        finish_proc: report_in_error_lines )
+        end
+
+        def report_in_error_lines
+          -> {
+            in_error_lines.each do |line|
+              say_stderr( "  #{line}" )
+            end
+          }
+        end
+
+        def parse_file
+          File.readlines( config.filepath ).each do |line|
+            begin
+              parse_line( line )
+            rescue
+              in_error_lines << line
+            end
+          end
+        end
+
+        def parse_line( line )
+          # some parsing logic ...
+        end
+
+        def in_error_lines
+          @in_error_lines ||= []
+        end
+
+      end
+    end
+
+Executing the previous command
+
+    command = AwesomeCli::ParseTextFile.new
+    command.execute
+
+Results in the following output
+
+    Parsing text file ... ERROR
+    Unparseable lines were encountered
+      1 something unparseable
+      7 something else unparseable
+

data/acclimate.gemspec

@@ -20,5 +20,10 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "gem-dandy"
+  spec.add_development_dependency "pry-debugger"
   spec.add_development_dependency "rake"
+
+  spec.add_dependency "hashie"
+  spec.add_dependency "rainbow"
+  spec.add_dependency "thor"
 end

data/lib/acclimate/cli_helper.rb

@@ -0,0 +1,53 @@
+module Acclimate
+  module CliHelper
+
+    def self.included( base )
+      base.class_eval do
+        include Acclimate::Output
+
+        no_commands do
+
+          def execute( klass, additional_options={} )
+            klass.new( options.merge( additional_options )).execute
+          rescue Acclimate::Error => e
+            handle_error( e ) unless e.handled?
+            exit( e.exit_code || 1 )
+          end
+
+          def handle_error( e )
+            say "Error: #{e.message}", :red
+          end
+
+        end
+      end
+
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+      def handle_argument_error( command, error, _, __ )
+        method = "handle_argument_error_for_#{command.name}"
+
+        if respond_to?( method )
+          send( method, command, error )
+        else
+          handle_argument_error_default( command, error )
+        end
+      end
+
+      def handle_argument_error_default( command, error )
+        $stdout.puts "Incorrect usage of command: #{command.name}"
+        $stdout.puts "  #{error.message}", ''
+        $stdout.puts "For correct usage:"
+        $stdout.puts "  acclimate help #{command.name}"
+      end
+
+      def handle_no_command_error( name )
+        $stdout.puts "Unrecognized command: #{name}"
+      end
+
+    end
+
+  end
+end

data/lib/acclimate/command.rb

@@ -0,0 +1,33 @@
+require 'pathname'
+
+module Acclimate
+  class Command
+
+    include Acclimate::Output
+
+    def initialize( options )
+      @options = options
+    end
+
+    def execute
+      raise NotImplementedError, "You must implement #{self.class.name}#execute"
+    end
+
+  protected
+
+    attr_reader :options
+
+    def config
+      @config = config_klass.new( options )
+    end
+
+    def base_path
+      Pathname.new( Dir.pwd )
+    end
+
+    def config_klass
+      Acclimate::Configuration
+    end
+
+  end
+end

data/lib/acclimate/configuration.rb

@@ -0,0 +1,21 @@
+require 'hashie'
+
+module Acclimate
+  class Configuration < Hashie::Mash
+
+    def initialize( options={} )
+      super( options )
+    end
+
+    def slice( *keys )
+      klass.new( select { |k,v| keys.map( &:to_s ).include?( k ) } )
+    end
+
+  protected
+
+    def klass
+      self.class
+    end
+
+  end
+end

data/lib/acclimate/confirmation_error.rb

@@ -0,0 +1,27 @@
+module Acclimate
+  class ConfirmationError < StandardError
+
+    def initialize( message, options={} )
+      @options = options
+      super( message )
+    end
+
+    def exit_code
+      options[:exit_code] || 1
+    end
+
+    def finish
+      return unless finish_proc
+      finish_proc.call
+    end
+
+  protected
+
+    attr_reader :options
+
+    def finish_proc
+      options[:finish_proc]
+    end
+
+  end
+end

data/lib/acclimate/error.rb

@@ -0,0 +1,23 @@
+module Acclimate
+  class Error < StandardError
+
+    def initialize( message, options={} )
+      @options = options
+
+      super( message )
+    end
+
+    def exit_code
+      options[:exit_code] || 1
+    end
+
+    def handled?
+      options[:handled] || false
+    end
+
+  protected
+
+    attr_reader :options
+
+  end
+end

data/lib/acclimate/output.rb

@@ -0,0 +1,52 @@
+require 'thor/shell'
+
+module Acclimate
+  module Output
+
+    def self.included( base )
+      base.send( :include, Thor::Shell )
+    end
+
+    def write( msg, color=:white )
+      $stdout.write( Rainbow( msg ).color( color ))
+    end
+
+    def say( msg, color=:white )
+      $stdout.puts( Rainbow( msg ).color( color ))
+    end
+
+    def say_stderr( msg, color=:white )
+      $stdout.puts( Rainbow( msg ).color( color ))
+    end
+
+    def header( msg )
+      say msg, :cyan
+    end
+
+    def say_ok
+      say 'OK', :green
+    end
+
+    def say_error
+      say_stderr 'ERROR', :red
+    end
+
+    def say_skipping
+      say 'SKIPPING', :yellow
+    end
+
+    def confirm( msg, color=:white, &block )
+      write "#{msg}... ", color
+      block.call
+      say_ok
+    rescue ConfirmationError => e
+      say_error
+      say_stderr( e.message, :red )
+      e.finish
+      raise Acclimate::Error.new( nil, handled: true, exit_code: e.exit_code )
+    rescue
+      say_error
+      raise
+    end
+  end
+end

data/lib/acclimate/version.rb

@@ -1,3 +1,3 @@
 module Acclimate
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/acclimate.rb

@@ -1,5 +1,15 @@
 require "acclimate/version"
+require 'pry-debugger'
+require 'rainbow'
+require 'thor'
 
 module Acclimate
-  # Your code goes here...
+
+  autoload :CliHelper,         'acclimate/cli_helper'
+  autoload :Command,           'acclimate/command'
+  autoload :Configuration,     'acclimate/configuration'
+  autoload :ConfirmationError, 'acclimate/confirmation_error'
+  autoload :Error,             'acclimate/error'
+  autoload :Output,            'acclimate/output'
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acclimate
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - C. Jason Harrelson (midas )
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-debugger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Cli building toolkit.  See README for more details.
 email:
 - jason@lookforwardenterprises.com
@@ -68,6 +124,12 @@ files:
 - Rakefile
 - acclimate.gemspec
 - lib/acclimate.rb
+- lib/acclimate/cli_helper.rb
+- lib/acclimate/command.rb
+- lib/acclimate/configuration.rb
+- lib/acclimate/confirmation_error.rb
+- lib/acclimate/error.rb
+- lib/acclimate/output.rb
 - lib/acclimate/version.rb
 homepage: ''
 licenses: