fuelcell 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NmY4YWExNmViMzhhMjBkM2Y4MWQ4YzgyYWE3OTBkNzIxMDhiNzU5Yg==
+  data.tar.gz: !binary |-
+    ZTk4ZDFkYTJiMzc4MmUxNTU4NjQxODQ4ZjcwNTA4MDkxNTc3ZjU3MA==
+SHA512:
+  metadata.gz: !binary |-
+    YWQ0ZWI5MDE5OWQ1YjgxMTI4MDlkZjJiODI3MGZiZDQ4ZjlmM2ZjZmNmMTk2
+    ZDJjNmE2NDdmMzRhM2I1MWYzODZjZDY5MjdhNjBmMWRkODI2NDRhM2I3YTM5
+    ODI0YjBjZGExNzlkMDhhYjdkNGY4M2FlNWM2MDllNmVkYjMwNTg=
+  data.tar.gz: !binary |-
+    YWMyY2EzMmYwYTM0ZjFhM2QxMjE5MDBmOGJmZDRkOTc0MmFiNTNkMTJmNjY0
+    NzRiNGU4Y2JhZTdjMWYwZDI4MWFmYzk2MDNlMzRkNmI3MmM0MDg0NTg3Zjhh
+    YTExODA0MzMxNzYzMDI1ZTNhYjUxZjFjMGJkMDQ0M2Y1ZjAzODU=

data/.codeclimate.yml

@@ -0,0 +1,12 @@
+---
+engines:
+  rubocop:
+    enabled: true
+  bundler-audit:
+    enabled: false
+ratings:
+  paths:
+  - "**.rb"
+
+exclude_paths:
+- spec/**/*

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+.ruby-version
+Gemfile.lock
+examples

data/.rspec

@@ -0,0 +1,5 @@
+--color
+--require codeclimate-test-reporter
+--require spec_helper
+--require pp
+--require fuelcell

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+- 2.2.2
+before_install: gem install bundler -v 1.11
+sudo: false
+addons:
+  code_climate:
+    repo_token: 29cdb1e4095c85dd0a2e9a0a1264b074c6d4008bc2069706ef283e6a68364ce5
+deploy:
+  on:
+    tags: true
+  provider: rubygems
+  api_key:
+    secure: Z4sBUqVeIuNJNKxXa+oYDxnfXlVaCAYl3f+8rWm4pKnHpLQYP1M8vj5LM3cmdHtUQiy/085zkvt5C6p2045PZ5sX3rueojoShqfvmNHgr3wYWQ2MZ3oHy3Vl6UJ3JYGoM/2wEclmqWQ49s1Zk4gnNZR4QyNZ/P4SWZ4FmJ9VmlI=
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+gem "codeclimate-test-reporter", group: :test, require: nil

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Robert Scott-Buccleuch
+
+MIT License
+
+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.md

@@ -0,0 +1,51 @@
+# Fuelcell
+[![Code Climate](https://codeclimate.com/github/engine8/fuelcell/badges/gpa.svg)](https://codeclimate.com/github/engine8/fuelcell)
+[![Test Coverage](https://codeclimate.com/github/engine8/fuelcell/badges/coverage.svg)](https://codeclimate.com/github/engine8/fuelcell/coverage)
+[![Build Status](https://travis-ci.org/engine8/fuelcell.svg?branch=master)](https://travis-ci.org/engine8/fuelcell)
+
+## Description
+Fuelcell is tool for parsing command line arguments & options, allowing you to
+concentrate more on your application and less on the logic needed to interface
+with your users through the command line. It handles mapping arguments to
+executable actions, defining options & arguments, self documenting help system,
+through a dsl that is small and simple to learn.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fuelcell'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fuelcell
+
+## Usage
+```ruby
+require 'fuelcell'
+
+Fuelcell.start(ARGV.dup) do
+  desc 'this is a basic hello world app'
+  arg 'name', default: 'World'
+  run ->(opts, args, shell) {
+    shell.puts "Hello #{args.name}"
+  }
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake false` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fuelcell. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "fuelcell"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+require "pry"
+Pry.start

data/bin/example.rb

@@ -0,0 +1,9 @@
+Fuelcell.define 'hello' do
+  require_relative 'world'
+  desc 'say hello to the world'
+  opt 'name|n', banner: 'name to say hello to', required: true
+  opt 'f|foo', banner: 'foo bar elements'
+  run ->(opts, args, shell) {
+    shell.puts 'hello example'
+  }
+end

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/test

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require 'pp'
+require "bundler/setup"
+require "fuelcell"
+
+Fuelcell.start(ARGV.dup, backtrace: true)  do
+  require_relative 'example'
+  desc 'this is an example of how a commands work with fuelcell'
+  opt 'all|a', banner: 'all of something'
+  arg 'foo', required: true
+  run->(opts, args, shell) {
+    shell.puts "testing #{args.foo}"
+  }
+  command 'fiz' do
+    run ->(opts, args, shell) {
+      shell.puts 'called by options'
+    }
+  end
+end

data/bin/world.rb

@@ -0,0 +1,6 @@
+Fuelcell.define 'hello world' do
+  desc 'the world is saying hello'
+  run ->(opts, args, shell) {
+    shell.puts 'world hello example'
+  }
+end

data/fuelcell.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fuelcell/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "fuelcell"
+  spec.version       = Fuelcell::VERSION
+  spec.authors       = ["Robert Scott-Buccleuch"]
+  spec.email         = ["rsb.code@gmail.com"]
+
+  spec.description   = %q{framework which simplifies working with the command-line.}
+  spec.summary       = spec.description
+  spec.homepage      = "https://github.com/rsb/fuelcell"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake",    "~> 10.0"
+  spec.add_development_dependency "pry",     "~> 0.10"
+  spec.add_development_dependency "rspec",   "~> 3.3.0"
+end

data/lib/fuelcell/action/arg_definition.rb

@@ -0,0 +1,36 @@
+module Fuelcell
+  module Action
+    class ArgDefinition
+      NO_DEFAULT_ASSIGNED = '__fuelcell_no_default_assigned__'
+      attr_reader :name, :type, :default, :required, :banner
+
+      alias_method :required?, :required
+
+      def initialize(text, config = {})
+        @name     = text.to_s
+        @required = config[:required] == true ? true : false
+        @type     = validate_type(config[:type])
+        @default  = config.fetch(:default) { NO_DEFAULT_ASSIGNED }
+        @banner   = config[:banner] || ''
+      end
+
+      def default?
+        @default == NO_DEFAULT_ASSIGNED ? false : true
+      end
+
+      private
+
+      def validate_type(value)
+        case value.to_s.to_sym
+        when :string, :text, :"" then :string
+        when :number, :numeric   then :numeric
+        when :boolean, :bool     then :bool
+        when :hash               then :hash
+        when :array              then :array
+        else
+          fail ArgumentError, "invalid type #{value}"
+        end
+      end
+    end
+  end
+end

data/lib/fuelcell/action/arg_results.rb

@@ -0,0 +1,57 @@
+module Fuelcell
+  module Action
+    class ArgResults
+      extend Forwardable
+      attr_reader :raw
+      def_delegators :@raw, :empty?, :each, :join
+
+      def initialize(array, hash)
+        @raw, @map = validate_results(array, hash)
+      end
+
+
+      def [](key)
+        return raw[key] if key.is_a?(Integer)
+        value(key)
+      end
+
+      protected
+      attr_reader :map
+
+      def method_missing(method, *args, &_block)
+        method = method.to_s
+        return map.key?(method.chomp('?')) if method[-1] == '?'
+        value(method)
+      end
+
+      def value(key)
+        return nil unless index?(key)
+        raw[index(key)]
+      end
+
+      def index?(key)
+        map.key?(key)
+      end
+
+      def index(key)
+        map[key]
+      end
+
+      private
+
+      def validate_results(array, hash)
+        hash.each do |(key, value)|
+          unless value.is_a?(Integer)
+            fail ArgumentError, "hash value for #{key} must be an integer"
+          end
+
+          unless array.at(value)
+            fail ArgumentError,
+                  "arg definition #{key} does not point to value in args array"
+          end
+        end
+        [array, hash]
+      end
+    end
+  end
+end

data/lib/fuelcell/action/args_manager.rb

@@ -0,0 +1,66 @@
+module Fuelcell
+  module Action
+    # Used by the Command to manage adding args from its dsl. It is also
+    # used during arg parsing to find args, or check if any required args
+    # have been missed
+    class ArgsManager
+      attr_reader :args
+      extend Forwardable
+
+      def_delegators :@args, :each, :each_with_index, :empty?
+
+      def initialize
+        @args = []
+      end
+
+      def args?
+        !empty?
+      end
+
+      def required
+        args.select { |arg| arg.required? }
+      end
+      alias_method :required_args, :required
+
+      def missing(names)
+        list = []
+        args.select do |arg|
+          list << arg if arg.required? && !names.include?(arg.name)
+        end
+        return [] if list.empty?
+
+        yield list if block_given?
+        list
+      end
+
+      def add(arg, config = {})
+        arg = create(arg, config) if arg.is_a?(String)
+        args.each do |item|
+          if item.name == arg.name
+            fail "can not add arg: duplicate exists with name #{arg.name}"
+          end
+        end
+        args << arg
+      end
+      alias_method :arg, :add
+
+      def remove(name)
+        # looks like an arg definition so lets use it's name
+        name = name.name if name.respond_to?(:name)
+        args.delete_if {|arg| arg.name == name}
+      end
+
+      def find(name)
+        target = false
+        args.each {|arg| target = arg if arg.name == name }
+        target
+      end
+      alias_method :find_arg, :find
+      alias_method :[], :find
+
+      def create(name, config = {})
+        ArgDefinition.new(name, config)
+      end
+    end
+  end
+end

data/lib/fuelcell/action/callable.rb

@@ -0,0 +1,54 @@
+module Fuelcell
+  module Action
+    module Callable
+      # Both getter and setting for callable object. This what the cli will
+      # execute when this command is found.
+      #
+      # @param value [Object] any object that implements :call
+      # @return [Object]
+      def callable(value = nil)
+        return @callable if value.nil?
+
+        unless value.respond_to?(:call)
+          fail ArgumentError, 'callable must implement :call'
+        end
+
+        @callable = value
+      end
+      alias_method :run, :callable
+
+      def callable?
+        callable.respond_to?(:call)
+      end
+      alias_method :runnable?, :callable?
+
+      # Executes this command.
+      #
+      # @param opts [Hash] processed opts from the cli parser
+      # @param args [Array] processed args from the cli parser
+      # @param shell [Fuelcell::Shell] IO abstraction
+      # @return [Integer] the exit code
+      def call(opts, args, shell)
+        fail 'command is not be called, callable not assigned' unless callable?
+        begin
+          cast_exit_code callable.call(opts, args, shell)
+        rescue StandardError => e
+          shell.exception e
+        end
+      end
+
+      protected
+
+      def cast_exit_code(code)
+        case code
+        when 0...255 then code
+        when nil, 0, '0', true then 0
+        when false, 1, '1' then 1
+        else
+          fail "command #{name} execution return code #{code} could " \
+            'not be interpreted as an exit code'
+        end
+      end
+    end
+  end
+end

data/lib/fuelcell/action/command.rb

@@ -0,0 +1,72 @@
+module Fuelcell
+  module Action
+    # Represents the action you want to perform. It also holds a list of option
+    # definitions used by the parser, along with meta data used by the help
+    # system and callable which is any object that implements call, this is
+    # your action.
+    class Command
+      attr_reader :name, :opts, :args
+      extend  Forwardable
+      include Subcommands
+      include Callable
+
+      delegate empty?: :subcommands
+      def_delegators :@opts, :find_opt, :opt, :missing_opts
+      def_delegators :@args, :find_arg, :arg, :missing_args
+
+      # Every command initializes with only its name set expecting the dsl
+      # to finish assigning the rest of its properties
+      #
+      # @param name [String]
+      def initialize(name)
+        @name  = name.to_s
+        @usage = nil
+        @desc  = nil
+        @opts  = OptsManager.new
+        @args  = ArgsManager.new
+      end
+
+      # This will assign both usage text and description, but when called
+      # with no args it will get the usage
+      #
+      # @param text [String]
+      # @param desc_text [String]
+      # @return [String]
+      def usage(text = nil, desc_text = nil)
+        return @usage   if text.nil?
+        desc(desc_text) unless desc_text.nil?
+        @usage = text
+      end
+
+      # Both getting and setter for description
+      #
+      # @param text [String]
+      # @return [String]
+      def desc(text = nil)
+        return @desc if text.nil?
+        @desc = text
+      end
+
+      # Allows a command to add subcommands to itself
+      #
+      # @param key [String]
+      # @yield instance_eval into Fuelcell::Command
+      # @return Fuelcell::Command
+      def command(key, &block)
+        cmd = Command.new(key)
+        cmd.instance_eval(&block)
+        add cmd
+      end
+
+      # Allows all the global option definitions from this command hierarchy
+      # to be add to the command given
+      #
+      # @param cmd [Fuelcell::Action::Command]
+      # @return [Fuelcell::Action::Command]
+      def add_global_options(cmd)
+        global_options.each { |_key, opt_definition| cmd.opt opt_definition }
+        cmd
+      end
+    end
+  end
+end

data/lib/fuelcell/action/not_found.rb

@@ -0,0 +1,55 @@
+module Fuelcell
+  module Action
+    # Null Object used to indicate a command has not been found
+    class NotFound < Command
+      def initialize(cmd_args)
+        super(validate_cmd_args(cmd_args))
+
+        @callable = command_not_found_action
+        @usage    = ''
+        @desc     = 'command not found command'
+      end
+
+      def usage(_value = nil)
+        @usage
+      end
+
+      def desc(_value = nil)
+        @desc
+      end
+
+      def callable(_value = nil)
+        @callable
+      end
+
+      def command(key, &block)
+        cmd = Command.new(key)
+        cmd.instance_eval(&block)
+        nil
+      end
+
+      def opt(_name, _config = {})
+      end
+
+      def <<(_cmd)
+      end
+
+      private
+
+      def validate_cmd_args(args)
+        args = args.is_a?(String) ? [args] : args
+        unless args.respond_to?(:join)
+          fail ArgumentError, 'cmd_args must implement join'
+        end
+        args.join(' ')
+      end
+
+      def command_not_found_action
+        lambda do |_opts, _args, shell|
+          shell.error "command #{name} not found"
+          return 1
+        end
+      end
+    end
+  end
+end

data/lib/fuelcell/action/opt_definition.rb

@@ -0,0 +1,79 @@
+require 'fuelcell/parser/opt_name_handler'
+
+module Fuelcell
+  module Action
+    # Responsible for defining all the information about an option so that the
+    # parser will be able to find it and its values when processing the command
+    # line.
+    class OptDefinition
+
+      include Action::Callable
+      NO_DEFAULT_ASSIGNED = '__fuelcell_no_default_assigned__'
+      attr_reader :name, :long, :short, :type, :default, :names, :required,
+        :cli_labels, :cli_names, :flag, :banner, :global, :cmd_path
+
+      alias_method :flag?, :flag
+      alias_method :required?, :required
+      alias_method :global?, :global
+
+      def initialize(text, config = {})
+        initialize_names(text)
+        @flag     = config[:flag] == true ? true : false
+        @required = config[:required] == true ? true : false
+        @global   = config[:global] == true ? true : false
+        @type     = validate_type(config[:type])
+        @default  = config.fetch(:default) { NO_DEFAULT_ASSIGNED }
+        @banner   = config[:banner] || ''
+        @cmd_path = config[:cmd_path]
+        callable config[:run] if config.key?(:run)
+      end
+
+      def default?
+        @default == NO_DEFAULT_ASSIGNED ? false : true
+      end
+
+      def name?(value)
+        names.include?(value)
+      end
+
+      def cmd_path?
+        !cmd_path.nil?
+      end
+
+      private
+
+      def initialize_names(text)
+        @name, @long, @short = Parser::OptNameHandler.new.call(text)
+        @cli_labels = []
+        @names      = [name]
+        initialize_short_name(short) if short
+        initialize_long_name(long)   if long
+        @cli_names = cli_labels.join(' ')
+      end
+
+      def initialize_long_name(long_name)
+        label = "--#{long_name}"
+        @cli_labels << label
+        @names += [long_name, label]
+      end
+
+      def initialize_short_name(short_name)
+        label = "-#{short_name}"
+        @cli_labels << label
+        @names += [short_name, label]
+      end
+
+      def validate_type(value)
+        case value.to_s.to_sym
+        when :string, :text, :"" then :string
+        when :number, :numeric   then :numeric
+        when :boolean, :bool     then :bool
+        when :hash               then :hash
+        when :array              then :array
+        else
+          fail ArgumentError, "invalid type #{value}"
+        end
+      end
+    end
+  end
+end