instacli 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 50a85c046d7c6a005f5ae3fb995afb467b83e462
+  data.tar.gz: 16832c6490f6822773c851a5d84f86394a89ae82
+SHA512:
+  metadata.gz: af9511d7f1c66621428c30f3346b84efff385d8f7eeb4648011c297fa40fead434a12ab53c5575e0593ca6ba1c83f3015dd4f299af3283fbcba95c798159f3b9
+  data.tar.gz: 8d33afe6a36f0e4a1445659cff0b1bb31ce0ef2890e8f40003ee1ba28a98e3acda27cecaf423c51080d2b1ecfb0df3ee36be5291d7790173fa35c34bbebee3ca

data/LICENSE.txt

@@ -0,0 +1,21 @@
+
+The MIT License (MIT)
+Copyright © 2016 Chris Olstrom <chris@olstrom.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.org

@@ -0,0 +1,135 @@
+#+TITLE: Instant CLI
+#+LATEX: \pagebreak
+
+* Overview (just add objects!)
+
+  An unopinionated universal commandline interface for Ruby. Given a collection
+  of Objects, provides a reasonable CLI with automatic help generation.
+
+* Rationale (why you care)
+
+  Ruby has a number of excellent gems for building commandline applications.
+  They range in complexity, but share a common approach: defining an interface
+  to some objects.
+
+  But... your objects already have interfaces: their =public methods=.
+
+  ~instacli~ adopts this perspective when building a CLI.
+
+* Installation (I can haz?)
+
+  #+BEGIN_SRC shell
+    gem install instacli
+  #+END_SRC
+
+* Usage (How to use it)
+
+** Building a CLI for an Object
+
+   Imagine we have an =EchoClass= that implements an =echo(string)= method that
+   returns ~string~. Something like this:
+
+  #+BEGIN_SRC ruby
+    class EchoClass
+      def echo(string)
+        string
+      end
+    end
+  #+END_SRC
+
+  We can add a CLI for it like so:
+
+  #+BEGIN_SRC ruby
+    require 'instacli'
+
+    boring_object = EchoClass.new
+
+    cli = InstaCLI.new boring: boring_object
+
+    cli.execute(*ARGV)
+  #+END_SRC
+
+  Assuming this code is in ~cli.rb~, and ~cli.rb~ is executable, we can use this
+  CLI as follows:
+
+  #+BEGIN_SRC shell
+    ./cli.rb boring echo foo
+  #+END_SRC
+
+  And it will output =foo= to =STDOUT=.
+
+** Autogenerating Documentation
+
+   Using the same ~EchoClass~, we can add help like so:
+
+   #+BEGIN_SRC ruby
+     class CLI < InstaCLI::CLI
+       include InstaCLI::Help
+     end
+
+     cli = CLI.new boring: boring_object
+
+     cli.execute(*ARGV)
+   #+END_SRC
+
+   Now running ~cli.rb~ with ~--help~, like so:
+
+   #+BEGIN_SRC shell
+     ./cli.rb --help boring echo
+   #+END_SRC
+
+   Will print the following:
+
+   #+BEGIN_EXAMPLE
+     NAME:
+       cli boring echo - CommandLine Interface
+
+     USAGE:
+       cli boring echo <string>
+   #+END_EXAMPLE
+
+* How does it work?
+
+** Mapping Commands to Objects
+
+   A single ~InstaCLI~ can expose as many objects as you like. Just give it a
+   hash, mapping the command names you want to use, to the objects they expose.
+
+   #+BEGIN_SRC ruby
+     mapping = {
+       foo: SomeObject.new,
+       bar: AnotherObject.new
+     }
+
+     InstaCLI::CLI.new mapping
+   #+END_SRC
+
+** Automatic Subcommands
+
+   Any =public methods= on an object will be exposed as subcommands (ignoring
+   any generic methods from ~Object~ itself).
+
+** Automatic Help
+
+   Disabled by default, can be enabled with ~include InstaCLI::Help~.
+
+   The parameters of a method are used to generate usage documentation,
+   following the common convention of =<required>= and =[optional]=.
+
+   If a method raises an ~ArugmentError~, a usage notice will be displayed,
+   outlining the correct usage.
+
+** Command Demultiplexing (aka "that thing =busybox= does")
+
+   Disabled by default, can be enabled with ~include InstaCLI::Demuxing~.
+
+   When enabled, the name the program was invoked with is read as the command to
+   execute.
+
+* License
+
+  ~instacli~ is available under the [[https://tldrlegal.com/license/mit-license][MIT License]]. See ~LICENSE.txt~ for the full text.
+
+* Contributors
+
+  - [[https://colstrom.github.io/][Chris Olstrom]] | [[mailto:chris@olstrom.com][e-mail]] | [[https://twitter.com/ChrisOlstrom][Twitter]]

data/instacli.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |gem|
+  gem.name        = 'instacli'
+  gem.version     = `git describe --tags --abbrev=0`.chomp
+  gem.licenses    = 'MIT'
+  gem.authors     = ['Chris Olstrom']
+  gem.email       = 'chris@olstrom.com'
+  gem.homepage    = 'https://github.com/colstrom/instacli'
+  gem.summary     = 'Instant CommandLine Interfaces - just add Objects!'
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  gem.require_paths = ['lib']
+
+  gem.add_runtime_dependency 'contracts', '~> 0.14', '>= 0.14.0'
+end

data/lib/instacli/cli.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+
+require 'contracts'
+require_relative 'exception_variant'
+
+module InstaCLI
+  # Instant CLI - just add Objects!
+  class CLI
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    Contract None => ArrayOf[ExceptionVariant]
+    def rescues
+      [ArgumentError]
+    end
+
+    Contract Maybe[HashOf[Symbol, Object]] => InstaCLI::CLI
+    def initialize(**mapping)
+      @mapping = mapping
+      self
+    end
+
+    Contract None => ArrayOf[Symbol]
+    def objects
+      @mapping.keys
+    end
+
+    Contract RespondTo[:to_sym] => Bool
+    def object?(o)
+      object.include? o.to_sym
+    end
+
+    Contract RespondTo[:to_sym] => Object
+    def object(o)
+      @mapping.fetch(o.to_sym) { Object.new }
+    end
+
+    Contract RespondTo[:to_sym] => ArrayOf[Symbol]
+    def methods(o)
+      object(o).methods - Object.methods
+    end
+
+    Contract RespondTo[:to_sym], RespondTo[:to_sym] => Bool
+    def method?(o, m)
+      methods(o).include? m.to_sym
+    end
+
+    Contract RespondTo[:to_sym], RespondTo[:to_sym] => Any
+    def method(o, m)
+      raise ArgumentError unless method? o, m
+      object(o).method(m)
+    end
+
+    Contract RespondTo[:to_sym], RespondTo[:to_sym] => ArrayOf[String]
+    def parameters(o, m)
+      method(o, m)
+        .parameters
+        .map { |p| p.first == :req ? "<#{p.last}>" : "[#{p.last}]" }
+    end
+
+    def help(*)
+      ''
+    end
+
+    def execute(*args)
+      return STDERR.puts help(*args[1..-1]) if %w(--help -h).include?(args.first)
+
+      o, m, *rest = *args
+
+      begin
+        STDOUT.puts method(o, m).call(*rest)
+      rescue *rescues
+        STDERR.puts help(*args)
+      end
+    end
+  end
+end

data/lib/instacli/demuxing.rb

@@ -0,0 +1,26 @@
+require 'contracts'
+
+module InstaCLI
+  # Mixin for routing by invocation (like busybox)
+  module Demuxing
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    Contract None => String
+    def invoked_as
+      File.basename $PROGRAM_NAME
+    end
+
+    def execute(*args)
+      return STDERR.puts help(invoked_as, args[1..-1]) if %w(--help -h).include?(args.first)
+
+      m, *rest = *args
+
+      begin
+        STDOUT.puts method(invoked_as, m).call(*rest)
+      rescue *rescues
+        STDERR.puts help(invoked_as, *args)
+      end
+    end
+  end
+end

data/lib/instacli/exception_variant.rb

@@ -0,0 +1,8 @@
+module InstaCLI
+  # Contract matching any descendant of Exception
+  class ExceptionVariant
+    def self.valid?(object)
+      object.ancestors.include? Exception
+    end
+  end
+end

data/lib/instacli/help.rb

@@ -0,0 +1,48 @@
+require 'contracts'
+
+module InstaCLI
+  # Usage documentation for --help
+  module Help
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    def header(*args)
+      "NAME:\n\t#{[program, *args].join ' '} - #{description}"
+    end
+
+    Contract None => String
+    def commands
+      ['COMMANDS:', *objects].join("\n\t")
+    end
+
+    Contract RespondTo[:to_sym] => String
+    def commands(o)
+      ['COMMANDS:', *methods(o)].join("\n\t")
+    end
+
+    Contract RespondTo[:to_sym], RespondTo[:to_sym] => String
+    def usage(o, m)
+      "USAGE:\n\t #{[program, o, m, *parameters(o, m)].join(' ')}"
+    end
+
+    def help(*args)
+      if args.length < 2
+        [header(*args), commands(*args)].join("\n\n")
+      else
+        [header(*args), usage(*args)].join("\n\n")
+      end
+    end
+
+    private
+
+    Contract None => String
+    def program
+      File.basename $PROGRAM_NAME
+    end
+
+    Contract None => String
+    def description
+      'CommandLine Interface'
+    end
+  end
+end

data/lib/instacli.rb

@@ -0,0 +1,12 @@
+
+require_relative 'instacli/cli'
+require_relative 'instacli/exception_variant'
+require_relative 'instacli/help'
+require_relative 'instacli/demuxing'
+
+# Convenience Wrapper
+module InstaCLI
+  def self.new(*args)
+    InstaCLI::CLI.new(*args)
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: instacli
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Olstrom
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-06-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: contracts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+description: 
+email: chris@olstrom.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.org
+- instacli.gemspec
+- lib/instacli.rb
+- lib/instacli/cli.rb
+- lib/instacli/demuxing.rb
+- lib/instacli/exception_variant.rb
+- lib/instacli/help.rb
+homepage: https://github.com/colstrom/instacli
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Instant CommandLine Interfaces - just add Objects!
+test_files: []
+has_rdoc: