rake-toolkit_program 0.1.1

data/lib/rake/toolkit_program/utils.rb

@@ -0,0 +1,48 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# Copyright 2019 PayTrace, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file defines utility extensions to standard library modules.
+
+module Rake
+  module ToolkitProgram
+    module RangeConversion
+      ##
+      # Return a Range the includes the end
+      #
+      # This method will error if the subject Range excludes the end but
+      # the bounds are not Integers.
+      #
+      def to_inclusive
+        return self unless exclude_end?
+        raise "only Integer Ranges can be converted" if [self.begin, self.end].any? {|v| !(Integer === v)}
+        return (self.begin..(self.end - 1))
+      end
+    end
+    Range.include RangeConversion
+  end
+
+  module ToolkitProgram::ShellwordsExt
+    def split(s, drop_comment: false)
+      super(s).tap do |r|
+        break r[0..((r.index {|i| i.start_with?('#')} || 0) - 1)] if drop_comment
+      end
+    end
+    class <<Shellwords
+      prepend ToolkitProgram::ShellwordsExt
+    end
+  end
+end

data/lib/rake/toolkit_program/version.rb

@@ -0,0 +1,10 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# This file contains no information protectable under copyright laws
+
+module Rake
+  module ToolkitProgram
+    VERSION = "0.1.1"
+  end
+end

data/rake-toolkit_program.gemspec

@@ -0,0 +1,51 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# Copyright 2019 PayTrace, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This is the gemspec file for the rake-toolkit_program gem.
+
+require 'pathname'
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rake/toolkit_program/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rake-toolkit_program"
+  spec.version       = Rake::ToolkitProgram::VERSION
+  spec.authors       = ["Richard Weeks"]
+  spec.email         = ["rtweeks21@gmail.com"]
+  spec.license       = 'Apache-2.0'
+
+  spec.summary       = %q{Build powerful CLI toolkits with simple code}
+  spec.description   = (Pathname(__FILE__).dirname / "README.md").read()
+  spec.homepage      = "https://github.com/PayTrace/rake-toolkit_program"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency "rake", ">= 10.0"
+  spec.add_dependency "colorize", "~> 0.8"
+  spec.add_dependency "dedent", "~> 1.0"
+
+  spec.add_development_dependency "bundler", ['>= 1.13', '< 3']
+  spec.add_development_dependency "rspec", "~> 3.9"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-coolline"
+end

metadata

@@ -0,0 +1,271 @@
+--- !ruby/object:Gem::Specification
+name: rake-toolkit_program
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Richard Weeks
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-12-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: dedent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: pry-coolline
+  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: "# Rake::ToolkitProgram\n\nCreate toolkit programs easily with `Rake`
+  and `OptionParser` syntax.  Bash completions and usage help are baked in.\n\n##
+  Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'rake-toolkit_program'\n```\n\nAnd
+  then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install
+  rake-toolkit_program\n\n## Quickstart\n\n* Shebang it up (in a file named `awesome_tool.rb`)\n
+  \ ```ruby\n  #!/usr/bin/env ruby\n  ```\n* Require the library\n  ```ruby\n  require
+  'rake/toolkit_program'\n  ```\n* Make your life easier\n  ```ruby\n  Program = Rake::ToolkitProgram\n
+  \ ```\n* Define your command tasks\n  ```ruby\n  Program.command_tasks do\n    desc
+  \"Build it\"\n    task 'build' do\n      # Ruby code here\n    end\n    \n    desc
+  \"Test it\"\n    task 'test' => ['build'] do\n      # Rake syntax ↑↑↑↑↑↑↑ for dependencies\n
+  \     # Ruby code here\n    end\n  end\n  ```\n  You can use `Program.args` in your
+  tasks to access the other arguments on the command line.  For argument parsing integrated
+  into the help provided by the program, see the use of `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args`
+  below.\n* Wire the mainline\n  ```ruby\n  Program.run(on_error: :exit_program!)
+  if $0 == __FILE__\n  ```\n* In the shell, prepare to run the program (UNIX/Linux
+  systems only)\n  ```console\n  $ chmod +x awesome_tool.rb\n  $ ./awesome_tool.rb
+  --install-completions\n  Completions installed in /home/rtweeks/.bashrc\n  Source
+  /home/rtweeks/.bash-complete/awesome_tool.rb-completions for immediate availability.\n
+  \ $ source /home/rtweeks/.bash-complete/awesome_tool.rb-completions\n  ```\n* Ask
+  for help\n  ```console\n  $ ./awesome_tool.rb help\n  \n  *** ./awesome_tool.rb
+  Toolkit Program ***\n  \n      .\n      .\n      .\n  ```\n\n## Usage\n\nLet's look
+  at a short sample toolkit program -- put this in `awesome.rb`:\n\n```ruby\n#!/usr/bin/env
+  ruby\nrequire 'rake/toolkit_program'\nrequire 'ostruct'\n\nToolkitProgram = Rake::ToolkitProgram\nToolkitProgram.title
+  = \"My Awesome Toolkit of Awesome\"\n\nToolkitProgram.command_tasks do\n  desc <<-END_DESC.dedent\n
+  \   Fooing myself\n  \n    I'm not sure what I'm doing, but I'm definitely fooing!\n
+  \ END_DESC\n  task :foo do\n    a = ToolkitProgram.args\n    puts \"I'm fooed#{'
+  on a ' if a.implement}#{a.implement}\"\n  end.parse_args(into: OpenStruct.new) do
+  |parser, args|\n    parser.no_positional_args!\n    parser.on('-i', '--implement
+  IMPLEMENT', 'An implement on which to be fooed') do |val|\n      args.implement
+  = val\n    end\n  end\nend\n\nif __FILE__ == $0\n  ToolkitProgram.run(on_error:
+  :exit_program!)\nend\n```\n\nMake sure to `chmod +x awesome.rb`!\n\nWhat does this
+  support?\n\n    $ ./awesome.rb foo\n    I'm fooed\n    $ ./awesome.rb --help\n    \n
+  \   *** My Awesome Toolkit of Awesome ***\n\n    Usage: ./awesome.rb COMMAND [OPTION
+  ...]\n\n    Avaliable options vary depending on the command given. For details\n
+  \   of a particular command, use:\n\n        ./awesome.rb help COMMAND\n\n    Commands:\n
+  \        foo   Fooing myself\n        help   Show a list of commands or details
+  of one command\n\n    Use help COMMAND to get more help on a specific command.\n
+  \   \n    $ ./awesome.rb help foo\n    \n    *** My Awesome Toolkit of Awesome ***\n\n
+  \   Usage: ./awesome.rb foo [OPTION ...]\n\n    Fooing myself\n\n    I'm not sure
+  what I'm doing, but I'm definitely fooing!\n\n    Options:\n        -i, --implement
+  IMPLEMENT        An implement on which to be fooed\n    \n    $ ./awesome.rb --install-completions\n
+  \   Completions installed in /home/rtweeks/.bashrc\n    Source /home/rtweeks/.bash-complete/awesome.rb-completions
+  for immediate availability.\n    $ source /home/rtweeks/.bash-complete/awesome.rb-completions\n
+  \   $ ./awesome.rb <tab><tab>\n    foo   help\n    $ ./awesome.rb f<tab>\n    ↳
+  ./awesome.rb foo\n    $ ./awesome.rb foo <tab>\n    ↳ ./awesome.rb foo --\n    $
+  ./awesome.rb foo --<tab><tab>\n    --help       --implement\n    $ ./awesome.rb
+  foo --i<tab>\n    ↳ ./awesome.rb foo --implement\n    $ ./awesome.rb foo --implement
+  <tab><tab>\n    --help      awesome.rb\n    $ ./awesome.rb foo --implement spoon\n
+  \   I'm fooed on a spoon\n\n### Defining Toolkit Commands\n\nJust define tasks in
+  the block of `Rake::ToolkitProgram.command_tasks` with `task` (i.e. `Rake::DSL#task`).
+  \ If `desc` is used to provide a description, the task will become visible in help
+  and completions.\n\nWhen a command task is initially defined, positional arguments
+  to the command are available as an `Array` through `Rake::ToolkitProgram.args`.\n\n###
+  Option Parsing\n\nThis gem extends `Rake::Task` with a `#parse_args` method that
+  creates a `Rake::ToolkitProgram::CommandOptionParser` (derived from the standard
+  library's `OptionParser`) and an argument accumulator and `yield`s them to its block.\n*
+  The arguments accumulated through the `Rake::ToolkitProgram::CommandOptionParser`
+  are available to the task in `Rake::ToolkitProgram.args`, replacing the normal `Array`
+  of positional arguments.\n* Use the `into:` keyword of `#parse_args` to provide
+  a custom argument accumulator object for the associated command.  The default argument
+  accumulator constructor can be defined with `Rake::ToolkitProgram.default_parsed_args`.
+  \ Without either of these, the default accumulator is a `Hash`.\n* Options defined
+  using `OptionParser#on` (or any of the variants) will print in the help for the
+  associated command.\n\n### Positional Arguments\n\nAccessing positional arguments
+  given after the command name depends on whether or not `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args`
+  has been called on the command task.  If this method is not called, positional arguments
+  will be an `Array` accessible through `Rake::ToolkitProgram.args`.\n\nWhen `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args`
+  is used:\n* `Rake::ToolkitProgram::CommandOptionParser#capture_positionals` can
+  be used to define how positional arguments are accumulated.\n  * If the argument
+  accumulator is a `Hash`, the default (without calling this method) is to assign
+  the `Array` of positional arguments to the `nil` key of the `Hash`.\n  * For other
+  types of accumulators, the positional arguments are only accessible if `Rake::ToolkitProgram::CommandOptionParser#capture_positionals`
+  is used to define how they are captured.\n  * If a block is given to this method,
+  the block of the method will receive the `Array` of positional arguments.  If it
+  is passed an argument value, that value is used as the key under which to store
+  the positional arguments if the argument accumulator is a `Hash`.\n* `Rake::ToolkitProgram::CommandOptionParser#expect_positional_cardinality`
+  can be used to set a rule for the count of positional arguments.  This will affect
+  the _usage_ presented in the help for the associated command.\n* `Rake::ToolkitProgram::CommandOptionParser#map_positional_args`
+  may be used to transform (or otherwise process) positional arguments one at a time
+  and in the context of options and/or arguments appearing earlier on the command
+  line.\n\n### Convenience Methods\n\n* `Rake::Task(Rake::ToolkitProgram::TaskExt)#prohibit_args`
+  is a quick way, for commands that accept no options or positional arguments, to
+  declare this so the help and bash completions reflect this.  It is equivalent to
+  using `#parse_args` and telling the parser `parser.expect_positional_cardinality(0)`.\n\n*
+  `Rake::ToolkitProgram::CommandOptionParser#no_positional_args!` is a shortcut for
+  calling `#expect_positional_cardinality(0)` on the same object.\n\n* `Rake::Task(Rake::ToolkitProgram::TaskExt)#invalid_args!`
+  and `Rake::ToolkitProgram::CommandOptionParser#invalid_args!` are convenient ways
+  to raise `Rake::ToolkitProgram::InvalidCommandLine` with a message.\n\n## OptionParser
+  in Rubies Before and After v2.4\n\nThe `OptionParser` class was extended in Ruby
+  2.4 to simplify capturing options into a `Hash` or other container implementing
+  `#[]=` in a similar way.  This gem supports that, but it means that behavior varies
+  somewhat between the pre-2.4 era and the 2.4+ era.  To have consistent behavior
+  across that version change, the recommendation is to use a `Struct`, `OpenStruct`,
+  or custom class to hold program options rather than `Hash`.\n\n## Development\n\nAfter
+  checking out the repo, run `bin/setup` to install dependencies. You can also run
+  `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo
+  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).\n\nTo run
+  the tests, use `rake`, `rake test`, or `rspec spec`.  Tests can only be run on systems
+  that support `Kernel#fork`, as this is used to present a pristine and isolated environment
+  for setting up the tool.  If run using Ruby 2.3 or earlier, some tests will be pending
+  because functionality expects Ruby 2.4's `OptionParser`.\n\n## Contributing\n\nBug
+  reports and pull requests are welcome on GitHub at https://github.com/PayTrace/rake-toolkit_program.
+  \ For further details on contributing, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n"
+email:
+- rtweeks21@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/program_exit_from_error.rb
+- lib/rake/toolkit_program.rb
+- lib/rake/toolkit_program/command_option_parser.rb
+- lib/rake/toolkit_program/completion.rb
+- lib/rake/toolkit_program/errors.rb
+- lib/rake/toolkit_program/help.rb
+- lib/rake/toolkit_program/help_styling.rb
+- lib/rake/toolkit_program/task_ext.rb
+- lib/rake/toolkit_program/utils.rb
+- lib/rake/toolkit_program/version.rb
+- rake-toolkit_program.gemspec
+homepage: https://github.com/PayTrace/rake-toolkit_program
+licenses:
+- Apache-2.0
+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: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Build powerful CLI toolkits with simple code
+test_files: []