mister_bin 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1363a49f614a04f932d61c6e52efbb9266a7c68605d3c232e95eb8b75fec9f7
-  data.tar.gz: dc34308fd4e779d20488e365895a4e3ef64c87290a20e1874fb1583687dcd8eb
+  metadata.gz: 145d72d39990c48d376b0090537d3ddd682ea2288fdea8ef96028f0745ecd60d
+  data.tar.gz: bc3bc649a79b06e746a260d7d0e0c19c973b3c29cf76bf966b4f621b261743c5
 SHA512:
-  metadata.gz: d2e2f3a8fe7799258c4995c36f9bef36a92c69977ed46e36537e53a9b0db40f402aece3fad632e1acd0827f12be086603fe55785809eeeaf323e4fda5cc44e4e
-  data.tar.gz: 786af8b7fe27061c2232166ba49d656c3c7972039bd3303f81a7b63a0b242496820c1f8b0f37c8ad739e74d9e6828446090339c55d45a528dfbcf12f4c380ef2
+  metadata.gz: 0e83d1905b8bfdc7e9d1e66a402fc3eaaf87ecf8a240a535d08a4b1d67b11b76062fcd78b2df06c84cae1a738c866fa0ab5081413f83fec5b70a64fb386de7f4
+  data.tar.gz: 7e1a2a406f3245786f36d2662532e17976f4e5f0b348febf303ef65b5f13c00b35465be6e9c86aa6ba9aa3304b13440a24d244cf3fd1a75e940af16a464ba33a

data/README.md

@@ -1,9 +1,9 @@
 Mister Bin
 ==================================================
 
-[![Gem](https://img.shields.io/gem/v/mister_bin.svg?style=flat-square)](https://rubygems.org/gems/mister_bin)
-[![Build](https://img.shields.io/travis/DannyBen/mister_bin.svg?style=flat-square)](https://travis-ci.org/DannyBen/mister_bin)
-[![Maintainability](https://img.shields.io/codeclimate/maintainability/DannyBen/mister_bin.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/mister_bin)
+[![Gem Version](https://badge.fury.io/rb/mister_bin.svg)](https://badge.fury.io/rb/mister_bin)
+[![Build Status](https://travis-ci.org/DannyBen/mister_bin.svg?branch=master)](https://travis-ci.org/DannyBen/mister_bin)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ae82443a99c2839d8ba8/maintainability)](https://codeclimate.com/github/DannyBen/mister_bin/maintainability)
 
 ---
 
@@ -30,4 +30,147 @@ Design Goals
 Usage
 --------------------------------------------------
 
-Soon
+Creating a command line utility with Mister Bin involves at least two files:
+
+1. The main "app" file. This is the actual "executable".
+2. One or more subcommand files. These files use the DSL.
+
+For example, assuming we would like to create a command line tool similar 
+to `git`, we will create two files:
+
+The `git` executable:
+
+```ruby
+# git
+#!/usr/bin/env ruby
+require 'mister_bin'
+
+exit MisterBin::Runner.run __FILE__, ARGV
+```
+
+The file to handle the `git push` command:
+```ruby
+# git-push.rb
+version "0.1.0"
+help "Push git repo"
+
+usage "git push [--all]"
+
+option "--all", "Push all branches"
+
+action do |args|
+  if args['--all']
+    puts "pushing all"
+  else
+    puts "pushing, some..."
+  end
+end
+```
+
+Mister Bin also provides support for secondary subcommands. For example,
+if you want to create a command line that responds to the below commands:
+
+```
+$ git status
+$ git repo create
+$ git repo delete
+```
+
+You will need to create these files:
+
+1. `git`
+2. `git-status.rb`
+3. `git-repo-create.rb`
+4. `git-repo-delete.rb`
+
+Alternatively, if you prefer to handle all `repo` subcommands in a single, 
+file, simple implement these instead:
+
+1. `git`
+2. `git-status.rb`
+3. `git-repo.rb`
+
+
+
+Creating the Main Executable
+--------------------------------------------------
+
+The main executable is usually simple, and contains this code:
+
+```ruby
+# git
+#!/usr/bin/env ruby
+require 'mister_bin'
+
+exit MisterBin::Runner.run __FILE__, ARGV
+```
+
+This code will start the execution chain based on the arguments provided 
+when running it.
+
+The `Runner.run` method requires two parameters:
+
+1. The path to the base executable file (usually, `__FILE__` is what you 
+   need).
+2. An array of arguments (usually `ARGV` is what you need).
+
+
+
+Creating Subcommands
+--------------------------------------------------
+
+When the main executable is executed, it will look for files matching a 
+specific pattern in the same directory.
+
+Assuming the main executable is called `myapp`, it will look for 
+`myapp-*.rb` files (e.g. `myapp-status.rb`)
+
+These files do not need to be executables, and should use the DSL to define
+their actions.
+
+
+
+The DSL
+--------------------------------------------------
+
+The DSL is designed to create a [docopt][1] document. Most commands are 
+optional.
+
+The below example outlines all available DSL commands.
+
+
+```ruby
+# Optional help string
+help "A short sentence or paragraph describing the command"
+
+# Version string for the command
+version "0.1.1"
+
+# Usage patterns. You can use either a compact docopt notation, or provide
+# multiple usage calls.
+# The first two will create the same result as the last one.
+usage "app ls"
+usage "app ls --all"
+usage "app ls [--all]"
+usage "app new NAME"
+
+# Describe any flags
+option "--all", "Also show hidden files"
+option "-f --force", "Force delete"
+
+# Describe any parameters
+param "NAME", "The name of the repository"
+
+# Provide examples
+example "app ls"
+example "app ls --all"
+
+# Define the actual action to execute when the command is called
+# All arguments will be provided to your block.
+action do |args|
+  puts args['--all'] ? "success --all" : "success"
+end
+```
+
+
+[1]: http://docopt.org/

data/lib/mister_bin/command.rb

@@ -14,8 +14,8 @@ module MisterBin
       script.execute argv
     end
 
-    def argv
-      command.split ' '
-    end
+    # def argv
+    #   command.split ' '
+    # end
   end
 end

data/lib/mister_bin/commands.rb

@@ -14,20 +14,15 @@ module MisterBin
     end
 
     def names
-      all.keys
+      all.keys.sort
     end
 
-    def find(query)
-      query = [query] unless query.is_a? Array
-      query_regex = /^#{query.join '.* '}/
-      keys = names.select { |k| k =~ /^#{query_regex}/ }
-      keys = names.select { |k| k =~ /^#{query.first}/ } if keys.empty?
-      keys.map { |k| [k, all[k]] }.to_h
-    end
-
-    def find_one(query)
-      result = find query
-      result.size == 1 ? result.values.first : false
+    def find(command, subcommand=nil)
+      if subcommand and names.include? "#{command} #{subcommand}"
+        all["#{command} #{subcommand}"]
+      else
+        all["#{command}"]
+      end
     end
 
     private

data/lib/mister_bin/docopt_maker.rb

@@ -9,7 +9,7 @@ module MisterBin
     include Singleton
     include Colsole
 
-    attr_reader :usages, :options, :examples
+    attr_reader :usages, :options, :examples, :params
     attr_accessor :help, :version
 
     def initialize
@@ -19,29 +19,32 @@ module MisterBin
     def reset
       @usages = []
       @options = []
+      @params = []
       @examples = []
       @version = '0.0.0'
       @help = nil
     end
 
     def docopt
-      [help_string, usage_string, options_string, examples_string].join "\n"
+      [help_string, usage_string, options_string, 
+        params_string, examples_string].compact.join "\n"
     end
 
     private
 
     def help_string
-      word_wrap help
+      help ? word_wrap(help) + "\n" : nil
     end
 
     def usage_string
-      result = ["", "Usage:"]
+      result = ["Usage:"]
       usages.each { |text| result << word_wrap("  #{text}") }
+      result << ""
       result.join "\n"
     end
 
     def options_string
-      result = ["", "Options:"]
+      result = ["Options:"]
       options.each do |option|
         result << "  #{option[0]}"
         result << word_wrap("    #{option[1]}")
@@ -51,15 +54,29 @@ module MisterBin
       result << "  -h --help"
       result << "    Show this help\n"
       result << "  --version"
-      result << "    Show version number"
+      result << "    Show version number\n"
+      result.join "\n"
+    end
+
+    def params_string
+      return nil if params.empty?
+
+      result = ["Parameters:"]
+      params.each do |param|
+        result << "  #{param[0]}"
+        result << word_wrap("    #{param[1]}")
+        result << ""
+      end
+
       result.join "\n"
     end
 
     def examples_string
-      return '' if examples.empty?
+      return nil if examples.empty?
 
-      result = ["", "Examples:"]
+      result = ["Examples:"]
       examples.each { |text| result << word_wrap("  #{text}") }
+      result << ""
       result.join "\n"
     end
   end

data/lib/mister_bin/runner.rb

@@ -23,8 +23,7 @@ module MisterBin
     private
 
     def execute(argv)
-      argv = expand_argv argv
-      command = commands.find_one argv[0..1]
+      command = commands.find argv[0], argv[1]
 
       if command
         execute_command command, argv
@@ -52,15 +51,5 @@ module MisterBin
     def commands
       @commands ||= Commands.new name, basedir
     end
-
-    def expand_argv(argv)
-      command = commands.find_one argv[0..1]
-      if command
-        argv.shift command.argv.size
-        command.argv + argv
-      else
-        argv
-      end
-    end
   end
 end

data/lib/mister_bin/script.rb

@@ -1,7 +1,12 @@
 require 'docopt'
+require 'colsole'
 
 module MisterBin
   class Script
+    # We are in cluding colsole to allow the evaluated script to use its
+    # functions
+    include Colsole
+
     attr_reader :file, :action_block
 
     def initialize(file)
@@ -41,6 +46,10 @@ module MisterBin
       DocoptMaker.instance.options << [flags, text]
     end
 
+    def param(param, text)
+      DocoptMaker.instance.params << [param, text]
+    end
+
     def example(text)
       DocoptMaker.instance.examples << text
     end

data/lib/mister_bin/version.rb

@@ -1,3 +1,3 @@
 module MisterBin
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mister_bin
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Danny Ben Shitrit