sickle 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fae05eea1313684c26edcc53f8e9058978e69aa6
-  data.tar.gz: 3fa560a8a59862a7b981ef2cf3c3ac9f8fbd94ea
+  metadata.gz: 03ca9b3349e1160e67bf4a7377b1c8ecbae4994c
+  data.tar.gz: e9e1e24472aa2adb8187c71252b419fbffb4b13f
 SHA512:
-  metadata.gz: 7cbea7eb809aeae6554824250dd09c7ee27f5a3bb57fd9c02c71b2aadbd7f32fdfda942d0968bdd745aea903ae4cf9c067ffcf9309150013ce0bc327897cf2b6
-  data.tar.gz: 22aa62f4fe8b4497b399309a4b3d625595dba42749a69f0d99eb1b26432067f2ab8c54e7cf8b09ce531239d7496d75824d2fa5e3991bf62ec1f9e5e61e833ee0
+  metadata.gz: 1c5ee9bb8e2d698b345aa890e4f12085b2d69b38223be0fbbcc914f11d3a1b73a6c9fe2ceb59a74e1f8f3156dbc904c4f66b33c6a6dbb85074e4c451fcd1a722
+  data.tar.gz: 99d5204b414e825d52c9ef011c3f6490677f9d6bc32c904fb0cc05a03b9dc610ec6785d86fa1edef53c60c5be9eef0065960d7787ce2514042ecb6f9ce55ac2a

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source 'http://rubygems.org'
 
 # Specify your gem's dependencies in sickle.gemspec
 gemspec

data/README.md

@@ -1,24 +1,170 @@
 # Sickle
 
-TODO: Write a gem description
+## Description
 
-## Installation
+Sickle is dead simple library for building complex command line tools.
 
-Add this line to your application's Gemfile:
+#### Features:
 
-    gem 'sickle'
+* Based on classes and modules
+* Support for commands
+* Support for namespaces
+* Support for command options and global options
+* Usage and help for free
+* No external dependencies (only stdlib optparse)
 
-And then execute:
 
-    $ bundle
+## Installation
 
-Or install it yourself as:
+You are probably building command line tool that will be released as gem, just add that line to you gemspec.
 
-    $ gem install sickle
+```ruby
+spec.add_dependency 'sickle'
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic usage
+
+Simple create a class with methods and some options
+
+```ruby
+require "sickle"
+
+class App
+  include Sickle::Runner
+
+  global_option :verbose                      # global flag
+
+  desc "install one of the available apps"    # command description
+  option :force                               # flag for `install` command
+  option :host, :default => "localhost"       # option
+  def install(name)
+    if options[:host]                         # access options
+      # do something
+    end
+    # the rest
+  end
+
+  desc "list all apps, search is possible"
+  def list(search = "")
+    # ...
+  end
+
+end
+
+App.run(ARGV) # start parsing ARGV
+```
+
+This will allow for execution command like:
+
+```bash
+$ mytool install foo
+$ mytool install foo --force --verbose --host 127.0.0.1
+$ mytool list
+$ mytool list rails --verbose
+```
+
+Help is for free:
+
+```
+$ mytool help
+USAGE:
+  mytool COMMAND [ARG1, ARG2, ...] [OPTIONS]
+
+TASKS:
+  help [COMMAND]  
+  install NAME    # install one of the available apps
+  list [SEARCH]   # list all apps, search is possible
+
+GLOBAL OPTIONS:
+  --verbose (default: false)
+```
+
+There is also detailed help for command:
+
+```bash
+$ mytool help install
+USAGE:
+  mytool install NAME
+
+DESCRIPTION:
+  install one of the available apps
+
+OPTIONS:
+  --force (default: false)
+  --host (default: localhost)
+```
+
+
+### Advanced usage - multiple modules
+
+```ruby
+module Users
+  include Sickle::Runner
+
+  desc "list all users"
+  def list
+    # ...
+  end
+
+  desc "create new user"
+  def create(name)
+    # ...
+  end
+end
+
+module Projects
+  include Sickle::Runner
+
+  desc "list all projects"
+  def list
+    # ...
+  end
+end
+
+module Global
+  include Sickle::Runner
+
+  desc "have some fun at top level"
+  def fun
+    # ...
+  end
+end
+
+class App
+  include Sickle::Runner
+
+  desc "top level command"
+  def main
+    # ...
+  end
+
+  include_modules :users => Users,      # bind commands from Users module under "users" namespace
+                  :p     => Projects    # bind commands from Projects module under "p" namespace
+
+  include Global                        # bind command from Global module at top level namespace
+end
+
+App.run(ARGV)
+
+```
+
+Run `$ mytool help` to see how commands are namespaced:
+
+```bash
+$ mytool help
+USAGE:
+  mytool COMMAND [ARG1, ARG2, ...] [OPTIONS]
+
+TASKS:
+  fun                # have some fun at top level
+  help [COMMAND]     
+  main               # top level command
+  p:list             # list all projects
+  users:create NAME  # create new user
+  users:list         # list all users
+```
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.test_files = FileList['spec/*_spec.rb']
+  t.verbose = true
+end
+

data/lib/sickle.rb

@@ -1,5 +1,254 @@
 require "sickle/version"
+require 'optparse'
 
 module Sickle
-  # Your code goes here...
+  class << self
+    def push_desc(desc)
+      @__desc = desc
+    end
+
+    def pop_desc
+      d = @__desc
+      @__desc = nil
+      d
+    end
+
+    def push_option(name, opts)
+      @__options ||= {}
+      @__options[name] = Option.new(name, opts)
+    end
+
+    def pop_options
+      o = @__options || {}
+      @__options = {}
+      o
+    end
+
+    def push_namespace(n)
+      namespace << n
+    end
+
+    def pop_namespace
+      namespace.pop
+    end
+
+    def namespace
+      @__namespace ||= []
+    end
+  end
+
+  module Runner
+    def self.included(base)
+      base.extend(Sickle::ClassMethods)
+
+      if base.is_a?(Class)
+        base.send(:include, Sickle::Help)
+        base.method_added(:help)
+      end
+    end
+
+    def options
+      @__options ||= {}
+    end
+  end
+
+  class Command
+    attr_accessor :meth, :name, :desc, :options
+
+    def initialize(meth, name, desc, options)
+      @meth, @name, @desc, @options = meth, name, desc, options
+    end
+  end
+
+  class Option
+    attr_accessor :name, :opts, :default
+
+    def initialize(name, opts)
+      @name, @opts = name, opts
+
+      @default = opts[:default] || false
+
+      if @default == true || @default == false
+        @type = :boolean
+      else
+        @type = @default.class.to_s.downcase.to_sym
+      end
+    end
+
+    def register(parser, results)
+      if @type == :boolean
+        parser.on("--#{@name}", opts[:desc]) do
+          results[@name] = true
+        end
+      else
+        parser.on("--#{@name} #{@name.upcase}") do |v|
+          results[@name] = coerce(v)
+        end
+      end
+    end
+
+    def coerce(value)
+      case @default
+      when Fixnum
+        value.to_i
+      when Float
+        value.to_f
+      else
+        value
+      end
+    end
+
+  end
+
+  module Help
+    def help(command = nil)
+      if command
+        __display_help_for_command(command)
+      else
+        __display_help
+      end
+    end
+
+    def __display_help_for_command(name)
+      if cmd = self.class.__commands[name]
+        puts "USAGE:"
+        u, _ = __display_command_usage(name, cmd)
+        puts "  #{$0} #{u}"
+        puts
+        puts "DESCRIPTION:"
+        puts cmd.desc.split("\n").map {|e| "  #{e}"}.join("\n")
+        puts
+        unless cmd.options.empty?
+          puts "OPTIONS:"
+          cmd.options.each do |_, opt|
+            puts __display_option(opt)
+          end
+        end
+
+        __display_global_options
+      else
+        puts "\e[31mCommand '#{name}' not found\e[0m"
+      end
+    end
+
+    def __display_command_usage(name, command)
+      params = command.meth.parameters.map do |(r, p)|
+        r == :req ? p.upcase : "[#{p.upcase}]"
+      end
+
+      ["#{name} #{params.join(" ")}", command]
+    end
+
+    def __display_help
+      puts "USAGE:"
+      puts "  #{$0} COMMAND [ARG1, ARG2, ...] [OPTIONS]"
+      puts
+
+      puts "TASKS:"
+      cmds = self.class.__commands.sort.map do |name, command|
+        __display_command_usage(name, command)
+      end
+      max = cmds.map {|a| a[0].length }.max
+      cmds.each do |(cmd, c)|
+        desc = c.desc ? "# #{c.desc}" : ""
+        puts "  #{cmd.ljust(max)}  #{desc}"
+      end
+
+      __display_global_options
+    end
+
+    def __display_global_options
+      unless self.class.__global_options.empty?
+        puts
+        puts "GLOBAL OPTIONS:"
+        self.class.__global_options.sort.each do |name, opt|
+          puts __display_option(opt)
+        end
+      end
+    end
+
+    def __display_option(opt)
+      "  --#{opt.name} (default: #{opt.default})"
+    end
+  end
+
+  module ClassMethods
+    def included(base)
+      __commands.each do |name, command|
+        name = (Sickle.namespace + [name]).join(":")
+        base.__commands[name] = command
+      end
+    end
+
+    def desc(label)
+      Sickle.push_desc(label)
+    end
+
+    def global_option(name, opts = {})
+      __global_options[name.to_s] = Option.new(name, opts)
+    end
+
+    def option(name, opts = {})
+      Sickle.push_option(name, opts)
+    end
+
+    def include_modules(hash)
+      hash.each do |key, value|
+        Sickle.push_namespace(key)
+        send(:include, value)
+        Sickle.pop_namespace
+      end
+    end
+
+    def __commands
+      @__commands ||= {}
+    end
+
+    def __global_options
+      @__global_options ||= {}
+    end
+
+    def run(argv)
+      # puts "ARGV: #{argv.inspect}"
+
+      if command_name = argv.shift
+        if command = __commands[command_name]
+          all = __global_options.values + command.options.values
+
+          results = {}
+          args = OptionParser.new do |parser|
+            all.each do |option|
+              option.register(parser, results)
+            end
+          end.parse!(argv)
+
+          all.each do |o|
+            results[o.name] ||= o.default
+          end
+
+          # puts "args: #{args.inspect}"
+          # puts "results: #{results.inspect}"
+
+
+          obj = self.new
+          obj.instance_variable_set(:@__options, results)
+          command.meth.bind(obj).call(*args)
+        else
+          puts "\e[31mCommand '#{command_name}' not found\e[0m"
+          puts
+          run(["help"])
+        end
+      else
+        run(["help"])
+      end
+    end
+
+
+
+    def method_added(a)
+      meth = instance_method(a)
+      __commands[a.to_s] = Command.new(meth, a, Sickle.pop_desc, Sickle.pop_options)
+    end
+  end
 end
+

data/lib/sickle/version.rb

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

data/sickle.gemspec

@@ -20,4 +20,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "turn"
 end

data/spec/runner_spec.rb

@@ -0,0 +1,68 @@
+require "minitest/spec"
+require "minitest/autorun"
+require "turn"
+
+require File.join(File.dirname(__FILE__), "test_app")
+
+describe Sickle do
+  describe "DSL" do
+    it "list of global options" do
+      App.__global_options.keys.must_equal ["verbose", "debug"]
+    end
+
+    it "list of commands" do
+      App.__commands.keys.must_equal(
+        %w(task1 task2 conflict sub:sub1 sub:conflict other:other1 other:conflict nosub))
+    end
+
+    it "correct commands descriptions" do
+      App.__commands["task1"].desc.must_equal "Run task 1"
+      App.__commands["task2"].desc.must_equal "Run task 2"
+      App.__commands["sub:sub1"].desc.must_equal "Run task Sub1"
+      App.__commands["other:other1"].desc.must_equal "Run task other sub1"
+      App.__commands["nosub"].desc.must_equal "No sub for me"
+    end
+
+    it "correct commands options" do
+      App.__commands["task1"].options.keys.must_equal [:quiet]
+      App.__commands["task2"].options.keys.must_equal [:fast, :slow, :number]
+    end
+  end
+
+  describe "Runner" do
+    it "task1" do
+      App.run(["task1", "x", "y"]).must_equal(
+        ["task1", "x", "y", "def", false, false, false])
+      App.run(["task1", "x", "y", "z", "--verbose"]).must_equal(
+        ["task1", "x", "y", "z", false, true, false])
+    end
+
+    it "task2" do
+      App.run(["task2"]).must_equal(
+        ["task2", 10, false, false, false, false])
+      App.run(%w(task2 --fast)).must_equal(
+        ["task2", 10, true, false, false, false])
+      App.run(%w(task2 --slow)).must_equal(
+        ["task2", 10, false, true, false, false])
+      App.run(%w(task2 --verbose)).must_equal(
+        ["task2", 10, false, false, true, false])
+      App.run(%w(task2 --debug)).must_equal(
+        ["task2", 10, false, false, false, true])
+      App.run(%w(task2 --fast --slow --verbose)).must_equal(
+        ["task2", 10, true, true, true, false])
+      App.run(%w(task2 --number 40)).must_equal(
+        ["task2", 40, false, false, false, false])
+    end
+
+    it "sub:sub1" do
+      App.run(%w(sub:sub1)).must_equal(
+        ["sub1"])
+    end
+
+    it "conflict" do
+      App.run(%w(conflict)).must_equal ["nosub:conflict"]
+      App.run(%w(sub:conflict)).must_equal ["sub1:conflict"]
+      App.run(%w(other:conflict)).must_equal ["other1:conflict"]
+    end
+  end
+end

data/spec/test_app.rb

@@ -0,0 +1,71 @@
+require File.join(File.dirname(__FILE__), "..", "lib", "sickle")
+
+module Sub
+  include Sickle::Runner
+
+  desc "Run task Sub1"
+  def sub1
+    p ["sub1"]
+  end
+
+  def conflict
+    p ["sub1:conflict"]
+  end
+end
+
+module Other
+  include Sickle::Runner
+
+  desc "Run task other sub1"
+  def other1(blah)
+    p ["other1", blah]
+  end
+
+  def conflict
+    p ["other1:conflict"]
+  end
+end
+
+module NoSub
+  include Sickle::Runner
+
+  desc "No sub for me"
+  def nosub
+    p ["nosub"]
+  end
+
+  def conflict
+    p ["nosub:conflict"]
+  end
+end
+
+class App
+  include Sickle::Runner
+
+  global_option :verbose
+  global_option :debug
+
+  desc "Run task 1"
+  option :quiet
+  def task1(a, b, c = "def")
+    p ["task1", a, b, c, options[:quiet], options[:verbose], options[:debug]]
+  end
+
+  desc "Run task 2"
+  option :fast
+  option :slow
+  option :number, :default => 10
+  def task2
+    p ["task2", options[:number], options[:fast], options[:slow], options[:verbose], options[:debug]]
+  end
+
+  def conflict
+    p ["app:conflict"]
+  end
+
+
+  include_modules :sub    => Sub,
+                  :other  => Other
+
+  include NoSub
+end

data/spec/test_run.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__))
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require "test_app"
+
+App.run(ARGV)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sickle
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Tymon Tobolski
@@ -38,6 +38,34 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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: turn
+  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'
 description: sickle
 email:
 - i@teamon.eu
@@ -53,6 +81,9 @@ files:
 - lib/sickle.rb
 - lib/sickle/version.rb
 - sickle.gemspec
+- spec/runner_spec.rb
+- spec/test_app.rb
+- spec/test_run.rb
 homepage: ''
 licenses:
 - MIT
@@ -77,4 +108,7 @@ rubygems_version: 2.0.0
 signing_key: 
 specification_version: 4
 summary: sickle
-test_files: []
+test_files:
+- spec/runner_spec.rb
+- spec/test_app.rb
+- spec/test_run.rb