shake 0.1.0

data/README.md

@@ -0,0 +1,229 @@
+Shake
+=====
+
+**Simple command runner.**
+
+Goals:
+
+ * Shake lets you create extendable CLI runners very easily.
+
+ * Shake intends to replicate Thor/Rake's basic functionality in one very small package.
+
+Why not Rake or Thor?
+
+ * Shake starts up way faster than Thor and Rake.
+ * Rake doesn't support arguments.
+ * Rake can't be extended easily to support anything more than `rake` + `Rakefile`.
+ * Thor can be too huge for your purposes.
+
+Shake was made with the idea of being easily-embeddable into your projects
+for your command line runners. It's a single ~4kb Ruby file.
+
+    # Shakefile
+    # Place this file in your project somewhere
+    class Shake
+      task(:start) {
+        puts "Starting '#{params.join(' ')}'..."
+      }
+
+      task.description = "Starts something"
+
+      task(:stop) {
+        puts "Stopping..."
+      }
+
+      task.description = "Stops it"
+    end
+
+In your shell:
+
+    $ shake start server
+    Starting 'server'...
+
+    $ shake stop
+    Stopping...
+
+    $ shake help
+    Commands:
+      start       Starts something
+      stop        Stops it
+      help        Shows a list of commands
+
+Usage
+=====
+
+### Using Shakefiles
+
+Using the command `shake` will load your project's `Shakefile`.
+
+    # ~/project/Shakefile
+    class Shake
+      task(:deploy) do
+        puts "Deploying..."
+        system "ssh admin@server.com git pull && thin restart"
+      end
+    end
+
+And in your shell:
+
+    $ cd ~/project
+    $ shake deploy
+    Deploying...
+
+### Parameters
+
+Get the parameters with `params` (an array). Verify parameters with `wrong_usage`.
+
+    task(:init) do
+      wrong_usage  if params.empty?
+      system "wget #{params.first}"
+    end
+
+Example:
+
+    $ shake init
+    Invalid usage.
+    See `shake help` for more information.
+
+### Parameter options and flags
+
+You may get params from it with `params.extract` or `params.delete`. Doing `extract`
+will remove it from params.
+
+    task(:create) do
+      type  = params.extract('-t') || 'default'
+      quiet = params.delete('-q')
+      file  = params.shift
+      wrong_usage  if params.any?
+
+      puts "Creating '#{file}' (quiet: #{!!quiet}, type: #{type})"
+    end
+
+Example:
+
+    $ shake create                 #=> Invalid
+    $ shake create foobar          #=> Creating 'foobar' (quiet: false, type: default)
+    $ shake create foobar -q       #=> Creating 'foobar' (quiet: true, type: default)
+    $ shake create foobar -t xyz   #=> Creating 'foobar' (quiet: false, type: xyz)
+
+# Common commands
+
+Use `err` to print something to STDERR. Use `pass` to halt execution.
+
+    task(:delete) do
+      unless File.exists?(params.first)
+        err 'You can't delete something that doesn't exist!'
+        pass
+      end
+
+      FileUtils.rm_rf params.first
+    end
+
+You may also pass parameters to `pass` to have it printed out before halting.
+
+    pass 'The target already exists.'  if File.exists?(target)
+
+### Default tasks
+
+Use `default` to specify a default task. (The default task is usually `help`)
+
+    class Shake
+      task(:test) do
+        Dir['test/**/*_test.rb'].each { |f| load f }
+      end
+
+      default :test
+    end
+
+    # Typing `shake` will be the same as `shake test`
+
+### Invalid commands
+
+Use `invalid` to define what happens when
+
+    class Shake
+      invalid {
+        err "Invalid command. What's wrong with you?"
+      }
+    end
+
+In your shell:
+
+    $ shake foobar
+    Invalid command. What's wrong with you?
+
+### Defining helpers
+
+Tasks are executed in the class's context, so just define your helpers like so:
+
+    module Helpers
+      def say_status(what, str)
+        puts "%15s %s" % [ what, str ]
+      end
+    end
+
+    class Shake
+      extend Helpers
+    end
+
+Then use them in your tasks.
+
+    class Shake
+      task(:info) do
+        say_status :info, "It's a fine day"
+      end
+    end
+
+### Manual invocation
+
+You can use shake in your projects without using the `shake` command. (recommended!)
+
+    require 'shake'
+
+    # If you want to load your own project file (optional)
+    file = Shake.find_in_project('Projectfile') and load file
+
+    # Now define some tasks, and then:
+    Shake.run!
+
+### Subclassing Shake
+
+You may subclass shake for your own project.
+
+By default, it will not have any of the default tasks (that is, `shake help`, and
+the "invalid command" message). Use `include Defaults` if you want this behavior.
+
+    require 'shake'
+
+    class CLI < Shake
+      include Defaults  # optional, see above
+
+      task(:flip) do
+        what = rand < 0.5 ? "heads" : "tails"
+        puts "The coin says #{what}"
+      end
+    end
+
+    CLI.run!
+
+### Defining tasks
+
+    # In your Shakefile or something
+    class Shake
+      task(:reset) do
+        # ...
+      end
+
+      task.description = "Resets passwords."
+    end
+
+Alternatively:
+
+    class Shake
+      task(:reset) do
+        # ...
+      end
+
+      task(:reset).description = "Resets passwords."
+    end
+

data/Rakefile

@@ -0,0 +1,5 @@
+task :test do
+  Dir['test/**/*_test.rb'].each { |f| load f }
+end
+
+task :default => :test

data/examples/example

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+require 'shake'
+
+## Example
+# This is a very simple example of using Shake with a subclass.
+
+class Monk < Shake
+  # Include the Shake default commands (like `help` and stuff)
+  # This is optional, but you probably want this for most cases.
+  include Defaults
+
+  # Define a task like this.
+  # The other command line options will be accesible as the
+  # `params` array. Pass it onto Clap or something.
+  task(:start) {
+    puts "Running..."
+    puts "Your options: #{params.inspect}"
+  }
+
+  # Just `task` will return the last defined task.
+  # By the way, only `help` cares about the description (skip
+  # it if you wish), and you can add as much metadata to the
+  # tasks as you need.
+  task.description = "Starts the server"
+
+  # You may also define task metadata like this.
+  # Note that there are no namespaces, but feel free to use
+  # the colon anyway.
+  task(:'redis:start', :description => "Runs redis") {
+    puts "Starting redis..."
+  }
+
+  # Or this way:
+  task(:stop) {
+    puts "Stopping..."
+  }
+
+  task(:stop).description = "Stops the server"
+end
+
+# This gets ARGV and dispatches the appropriate task
+Monk.run!
+
+# Example output:
+#
+#    $ ./monk
+#    Usage: monk <command>
+#    
+#    Commands:
+#      help           Shows a list of commands
+#      start          Starts the server
+#      redis:start    Runs redis
+#      stop           Stops the server
+#    
+#    $ ./monk start production
+#    Running...
+#    Your options: ['production']
+#    
+#    $ ./monk aaaa
+#    Unknown command: aaaa
+#    See `monk help` for a list of commands.

data/examples/example2

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+require 'shake'
+
+## Shake
+# Shake is a very simple Thor/Rake replacement. It intends
+# to replicate thor's basic functionality in <100loc.
+#
+# This is a very simple example.
+#
+Shake.task(:hello) {
+  puts "hi!"
+}
+
+Shake.run!
+
+# Example output:
+#
+#    $ ./example
+#    Usage: example <command>
+#    
+#    Commands:
+#      help
+#      hello
+#    
+#    $ ./example hello
+#    hi!
+#    
+#    $ ./example aaaa
+#    Unknown command: aaaa
+#    See `example help` for a list of commands.

data/lib/shake.rb

@@ -0,0 +1,186 @@
+require 'ostruct'
+
+class Shake
+  VERSION = "0.1.0"
+
+  Abort = Class.new(StandardError)
+
+  class << self
+    attr_reader :params
+    attr_reader :command
+
+    # By the way: every task gets evaluated in the context of the class.
+    # Just make more static methods (`def self.monkey`) if you need them
+    # in your tasks.
+    #
+    # This also means that all the methods here are available for use
+    # in your tasks.
+
+    # Returns a list of tasks.
+    # It gives out a hash with symbols as keys, and openstructs as values.
+    def tasks
+      @tasks ||= Hash.new
+    end
+
+    # Sets or retrieves a task.
+    # If no arguments are given, it returns the last task defined.
+    #
+    # Examples:
+    #
+    #     task(:start) { ... }
+    #     task(:start, description: 'Starts it') { ... }
+    #     task(:start)
+    #     task.description = "Starts it"
+    #
+    def task(what=nil, options={}, &blk)
+      return @last  if what.nil?
+
+      key = what.downcase.to_sym
+      @last = tasks[key] = new_task(options, &blk)  if block_given?
+      tasks[key]
+    end
+
+    # Sets or retrieves the default task.
+    #
+    # Examples:
+    #
+    #     default :default_task
+    #     default { ... }
+    #
+    def default(what=nil, &blk)
+      @default = what || blk || @default
+    end
+
+    # Sets or retrieves the 'invalid command' task.
+    # See `default` for examples.
+    def invalid(what=nil, &blk)
+      @invalid = what || blk || @invalid
+    end
+
+    # Invokes a task with the given arguments.
+    # You may even nest multiple task invocations.
+    #
+    # Examples:
+    #
+    #    invoke(:start)
+    #    invoke(:start, 'nginx', 'memcache')
+    #
+    def invoke(what, *args)
+      old, @params = @params, args.extend(Params)
+      return  if what.nil?
+
+      begin
+        return instance_eval(&what)  if what.is_a?(Proc)
+
+        task = task(what)  or return nil
+        instance_eval &task.proc
+        true
+      rescue Abort
+        true
+      ensure
+        @params = old
+      end
+    end
+
+    # Stops the execution of a task.
+    def pass(msg=nil)
+      err msg  unless msg.nil?
+      raise Abort
+    end
+
+    # Halts a task because of wrong usage.
+    #
+    # Example:
+    #
+    #   wrong_usage  if params.any?
+    #
+    def wrong_usage
+      invoke(invalid) and pass
+    end
+
+    # Runs with the given arguments and dispatches the appropriate task.
+    # Use `run!` if you want to go with command line arguments.
+    #
+    # Example:
+    #
+    #     # This is equivalent to `invoke(:start, 'nginx')`
+    #     run 'start', 'nginx'
+    #
+    def run(*argv)
+      return invoke(default)  if argv.empty?
+
+      @command = argv.shift
+      invoke(@command, *argv) or invoke(invalid, *argv)
+    end
+
+    def run!
+      run *ARGV
+    end
+
+    def executable
+      File.basename($0)
+    end
+
+    def err(str="")
+      $stderr.write "#{str}\n"
+    end
+
+    # Traverse back it's parents and find the file called `file`.
+    def find_in_project(file)
+      dir = Dir.pwd
+      while true
+        path = File.join(dir, file)
+        return path  if File.exists?(path)
+
+        parent = File.expand_path(File.join(dir, '..'))
+        return nil  if parent == dir
+
+        dir = parent
+      end
+    end
+
+  protected
+    def new_task(options={}, &blk)
+      t = OpenStruct.new(options)
+      t.proc = blk
+      t
+    end
+  end
+
+  module Params
+    def extract(what)
+      i = index(what) and slice!(i, 2)[1]
+    end
+  end
+
+  # This is a list of default commands.
+  # The class Shake itself uses this, but if you subclass it,
+  # you will have to do `include Defaults` yourself.
+  module Defaults
+    def self.included(to)
+      to.default :help
+
+      to.task(:help) {
+        err "Usage: #{executable} <command>"
+        err
+        err "Commands:"
+        tasks.each { |name, task| err "  %-20s %s" % [ name, task.description ] }
+      }
+
+      to.task(:help).description = "Shows a list of commands"
+
+      to.invalid {
+        if task(command)
+          err "Invalid usage."
+          err "See `#{executable} help` for more info."
+        else
+          err "Unknown command: #{command}"
+          err "See `#{executable} help` for a list of commands."
+        end
+      }
+    end
+  end
+
+  include Defaults
+end
+

data/test/mock.rb

@@ -0,0 +1,9 @@
+class Shake
+  def self.puts(str='')
+    $out << "#{str}\n"
+  end
+
+  def self.err(str='')
+    $err << "#{str}\n"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,47 @@
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'shake'
+require 'contest'
+require 'fileutils'
+
+require File.expand_path('../mock', __FILE__)
+
+class Test::Unit::TestCase
+  def temp_path(*a)
+    root %w(test tmp) + a
+  end
+
+  def root(*a)
+    File.join File.expand_path('../../', __FILE__), *a
+  end
+
+  setup do
+    $out, $err = '', ''
+    FileUtils.rm_rf temp_path  if File.directory?(temp_path)
+    FileUtils.mkdir_p temp_path
+    Dir.chdir temp_path
+  end
+
+  teardown do
+    FileUtils.rm_rf temp_path
+  end
+
+  def cout
+    $out
+  end
+
+  def cerr
+    $err
+  end
+
+  # Simulate bin/shake
+  def shake(*args)
+    ARGV.slice! 0, ARGV.length
+    args.each { |a| ARGV << a }
+    load File.expand_path('../../bin/shake', __FILE__)
+  end
+
+  def shakefile(str)
+    File.open('Shakefile', 'w') { |f| f.write str.strip }
+  end
+end

data/test/unit/params_test.rb

@@ -0,0 +1,72 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+class ParamsTest < Test::Unit::TestCase
+  class Bake < ::Shake
+    task :heat do
+      wrong_usage  if params.size != 1
+      puts "OK"
+    end
+
+    task :cool do
+      quiet = params.delete('-q')
+      type  = params.extract('-t') || params.extract('--type') || 'default'
+      wrong_usage  unless params.empty?
+
+      puts "Quiet #{!!quiet}, type #{type}"
+    end
+
+    invalid do
+      err "What?"
+    end
+  end
+
+  test 'wrong usage' do
+    Bake.run *%w{heat}
+    assert cerr == "What?\n"
+  end
+
+  test 'wrong usage 2' do
+    Bake.run *%w{heat x y}
+    assert cerr == "What?\n"
+  end
+
+  test 'proper usage' do
+    Bake.run *%w{heat x}
+    assert cout == "OK\n"
+  end
+
+  test 'cool' do
+    Bake.run 'cool'
+    assert cout == "Quiet false, type default\n"
+  end
+
+  test 'wrong usage' do
+    Bake.run *%w{cool down}
+    assert cerr == "What?\n"
+  end
+
+  test 'cool 2' do
+    Bake.run *%w{cool -q}
+    assert cout == "Quiet true, type default\n"
+  end
+
+  test 'cool 3' do
+    Bake.run *%w{cool -t special}
+    assert cout == "Quiet false, type special\n"
+  end
+
+  test 'cool 4' do
+    Bake.run *%w{cool -t special -q}
+    assert cout == "Quiet true, type special\n"
+  end
+
+  test 'cool 5' do
+    Bake.run *%w{cool -q -t}
+    assert cout == "Quiet true, type default\n"
+  end
+
+  test 'wrong usage again' do
+    Bake.run *%w{cool -q xyz}
+    assert cerr == "What?\n"
+  end
+end

data/test/unit/shakefile_test.rb

@@ -0,0 +1,44 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+class ShakefileTest < Test::Unit::TestCase
+  test 'no shakefile' do
+    shake
+    assert cout.empty?
+    assert cerr.include?('No Shakefile')
+  end
+
+  context 'basics' do
+    setup do
+      shakefile %{
+        class Shake
+          task :start do
+            puts "Starting..."
+            puts params.inspect  if params.any?
+          end
+          task.description = 'Starts the server'
+        end
+      }
+    end
+
+    test 'help' do
+      shake 'help'
+      assert cout.empty?
+      assert cerr =~ /^  start *Starts the server/
+    end
+
+    test 'invalid command' do
+      shake 'stop'
+      assert cerr.include?('Unknown command: stop')
+    end
+
+    test 'run' do
+      shake 'start'
+      assert_equal "Starting...\n", cout
+    end
+
+    test 'run with args' do
+      shake *%w(start x)
+      assert_equal "Starting...\n[\"x\"]\n", cout
+    end
+  end
+end

data/test/unit/subclass_test.rb

@@ -0,0 +1,29 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+class SubclassTest < Test::Unit::TestCase
+  class Bake < ::Shake
+    task :melt do
+      puts "Working..."
+    end
+
+    invalid do
+      err "What?"
+    end
+  end
+
+  test 'subclassing' do
+    Bake.run 'melt'
+    assert cout == "Working...\n"
+  end
+
+  test 'nothing to do' do
+    Bake.run
+    assert cerr.empty?
+    assert cout.empty?
+  end
+
+  test 'invalid command' do
+    Bake.run 'foobar'
+    assert cerr == "What?\n"
+  end
+end

data/test/unit/traverse_test.rb

@@ -0,0 +1,15 @@
+require File.expand_path('../../test_helper', __FILE__)
+
+class TraverseTest < Test::Unit::TestCase
+  test 'traverse backwards' do
+    shakefile %{
+      Shake.task(:create) { puts 'Creating...' }
+    }
+
+    Dir.mkdir 'xxx'
+    Dir.chdir 'xxx'
+
+    shake 'create'
+    assert_equal "Creating...\n", cout
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: shake
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Rico Sta. Cruz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-15 00:00:00 +08:00
+default_executable: 
+dependencies: []
+
+description: Shake is a simple replacement for Thor/Rake.
+email: 
+- rico@sinefunc.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/shake.rb
+- test/mock.rb
+- test/test_helper.rb
+- test/unit/params_test.rb
+- test/unit/shakefile_test.rb
+- test/unit/subclass_test.rb
+- test/unit/traverse_test.rb
+- examples/example
+- examples/example2
+- README.md
+- Rakefile
+has_rdoc: true
+homepage: http://github.com/rstacruz/shake
+licenses: []
+
+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.5.0
+signing_key: 
+specification_version: 3
+summary: Simple command line runner.
+test_files: []
+