cmd.rb 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e81a52d995f13903b644a2dcc326b35b57d37bc9b0e1840509835791a7c3100
+  data.tar.gz: fb89b7ca7ba61d017141bebaeaa129589b812c7a7a742e5e0619cda3e4374b86
+SHA512:
+  metadata.gz: 9131c3ffccbba0aef5cdcf3f19e7288ce8228b5095a9cac7e021c08202a09b4094a584e520a846c4be13e63f846f06a8b0583daf63dc3c01a8b7ef26185c2f0c
+  data.tar.gz: 3eaed61342560a42a56952e74f1723c9f35a08ae22b13c7bb403bb5dd3a8d3ca85cc046a7bda3dab6246a94d36fce301188c011e3f7789a89057e911d138ece8

data/.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: cmd.rb
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        ruby: [3.1, 3.2]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - run: bundle install
+    - run: bundle exec rake

data/.gitignore

@@ -0,0 +1,6 @@
+*.lock
+.yardoc/
+doc/
+.bundle/
+.localgems/
+.gems/

data/.projectile

@@ -0,0 +1,2 @@
+-.localgems/
+-doc/

data/.rubocop.yml

@@ -0,0 +1,36 @@
+##
+# Plugins
+require:
+  - standard
+
+##
+# Defaults: standard-rb
+inherit_gem:
+  standard: config/base.yml
+
+##
+# All cops
+AllCops:
+  TargetRubyVersion: 3.2
+  Include:
+    - lib/*.rb
+    - lib/**/*.rb
+    - test/*.rb
+
+##
+# Enabled
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+##
+# Disabled
+Layout/ArgumentAlignment:
+  Enabled: false
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Layout/EmptyLineBetweenDefs:
+  Enabled: false
+Style/TrivialAccessors:
+  Enabled: false
+Style/CommandLiteral:
+  Enabled: false

data/.yardoc-template/default/fulldoc/html/css/0x1eef.css

@@ -0,0 +1,15 @@
+#main #content #filecontents p, .discussion p {
+  max-width: 768px;
+}
+
+#toc {
+  position: fixed;
+  right: 25px;
+  display: none;
+}
+
+@media screen and (min-width: 1280px) {
+  #toc {
+    display: block;
+  }
+}

data/.yardoc-template/default/layout/html/setup.rb

@@ -0,0 +1,5 @@
+def stylesheets
+  s = super
+  s << "css/0x1eef.css"
+  s
+end

data/.yardoc-template/default/module/setup.rb

@@ -0,0 +1,7 @@
+##
+# Sort methods in ascending order based
+# on the line number where a method is
+# defined.
+def sort_listing(listing)
+  listing.sort_by { _1.files[1] }
+end

data/.yardopts

@@ -0,0 +1,4 @@
+-m markdown -M redcarpet --no-private -t default -p .yardoc-template --hide-void-return
+-
+README.md
+LICENSE

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+gemspec
+gem "optparse", github: "ruby/optparse"
+gem "ryo.rb", "~> 0.4", github: "0x1eef/ryo.rb", tag: "v0.4.2"
+gem "test-cmd.rb", "~> 0.2", github: "0x1eef/test-cmd.rb"
+gem "webrick"

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2023 by 0x1eef <0x1eef@protonmail.com>
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+## About
+
+cmd.rb is a library for building command-line applications
+in Ruby. The interface is centered around a class that implements
+a command (or it could be a sub-command) that defines a banner,
+a set of options, and a set of defaults for those options. The
+option parsing implementation is delegated to
+[ruby/optparse](https://github.com/ruby/optparse)
+(with a few minor enhancements).
+
+## Example
+
+The following example demonstrates a simple command that is
+implemented with `Dir.entries`. The command accepts two options
+that have fallback default values set:
+
+**Definition**
+
+```ruby
+#!/usr/bin/env ruby
+
+require "cmd"
+class Ls < Cmd
+  set_banner usage: "ls [OPTIONS]",
+             description: "Lists the contents of a directory"
+  set_option "-g PATTERN", "--grep PATTERN", "A regular expression", as: Regexp, default: /.+/
+  set_option "-d PATH", "--directory PATH", "A path to a directory", as: String, default: Dir.home
+
+  def run
+    options = parse_options(argv)
+    options.help ? show_help : run_command(options)
+  end
+
+  private
+
+  def run_command(options)
+    puts Dir.entries(options.directory)
+            .grep(options.grep)
+            .sort
+            .join("\n")
+  end
+end
+
+##
+# Run the command
+Ls.new(ARGV).run
+```
+
+**Command help (-h)**
+
+```
+$ chmod u+x ls
+$ ./ls --help
+Usage: ls [OPTIONS]
+
+Description:
+  Lists the contents of a directory
+
+Options:
+  -g, --grep PATTERN         A regular expression
+  -p, --path PATH            A path to a directory
+  -h, --help                 Show help
+
+```
+
+## Sources
+
+* [Source code (GitHub)](https://github.com/0x1eef/cmd.rb#readme)
+* [Source code (GitLab)](https://gitlab.com/0x1eef/cmd.rb#about)
+
+## Install
+
+cmd.rb is distributed as a RubyGem through its git repositories. <br>
+[GitHub](https://github.com/0x1eef/cmd.rb),
+and
+[GitLab](https://gitlab.com/0x1eef/cmd.rb)
+are available as sources.
+
+**Gemfile**
+
+```ruby
+gem "cmd.rb", github: "0x1eef/cmd.rb"
+gem "ryo.rb", github: "0x1eef/ryo.rb"
+```
+
+## <a id="license"> License </a>
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
+<br>
+See [LICENSE](./LICENSE).

data/Rakefile.rb

@@ -0,0 +1,8 @@
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+  t.warning = false
+end
+task default: :test

data/VERSION

@@ -0,0 +1 @@
+v0.3.2

data/cmd.rb.gemspec

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+version = File.binread File.join(__dir__, "VERSION")
+Gem::Specification.new do |gem|
+  gem.name = "cmd.rb"
+  gem.authors = ["0x1eef"]
+  gem.email = ["0x1eef@protonmail.com"]
+  gem.homepage = "https://github.com/0x1eef/cmd.rb#readme"
+  gem.version = version[/[\d.]+/]
+  gem.licenses = ["0BSD"]
+  gem.files = `git ls-files`.split($/)
+  gem.require_paths = ["lib"]
+  gem.summary = "A library for building command-line applications"
+  gem.description = gem.summary
+  gem.add_runtime_dependency "ryo.rb", "~> 0.4"
+  gem.add_runtime_dependency "optparse", "~> 0.3"
+  gem.add_development_dependency "test-unit", "~> 3.5.7"
+  gem.add_development_dependency "yard", "~> 0.9"
+  gem.add_development_dependency "redcarpet", "~> 3.5"
+  gem.add_development_dependency "standard", "~> 1.13"
+  gem.add_development_dependency "test-cmd.rb", "~> 0.2"
+  gem.add_development_dependency "rake", "~> 13.1"
+end

data/lib/cmd/mixins/argv.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+##
+# The {Cmd::ARGV} module provides an initialize method, and an
+# attribute reader for an array of strings (usually ARGV). Classes
+# who include the {Cmd Cmd} module indirectly include this module as
+# well.
+module Cmd::ARGV
+  ##
+  # @return [Array<String>]
+  #  Returns an array of strings.
+  attr_reader :argv
+
+  ##
+  # @param [Array<String>] argv
+  #  An array of strings.
+  def initialize(argv)
+    @argv = argv.dup
+  end
+end

data/lib/cmd/mixins/help.rb

@@ -0,0 +1,9 @@
+
+module Cmd::Help
+  def show_help(io = $stdout)
+    banner = self.class.banner
+    io.puts "Usage: #{banner.usage}\n\n" \
+            "Description:\n  #{banner.description}\n\n" \
+            "Options: #{option_parser.help}\n"
+  end
+end

data/lib/cmd/mixins/option_parser.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "ryo"
+
+##
+# The {Cmd::OptionParser Cmd::OptionParser} module provides a light wrapper
+# around Ruby's
+# [OptionParser](https://docs.ruby-lang.org/en/3.2/OptionParser.html)
+# class.
+module Cmd::OptionParser
+  def self.included(klass)
+    klass.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    ##
+    # Set command banner.
+    #
+    # @param [String] usage
+    #  An example of how a command is used.
+    #
+    # @param [String] description
+    #  The description of a command.
+    #
+    # @return [void]
+    def set_banner(usage:, description:)
+      banner.usage = usage
+      banner.description = description
+    end
+
+    ##
+    # Set a command option.
+    #
+    # @param [String] short
+    #  Short option switch.
+    #
+    # @param [String] long
+    #  Long option switch.
+    #
+    # @param [String] desc
+    #  The description of an option.
+    #
+    # @param [Class] as
+    #  The type (String, Integer, etc) of the option's value.
+    #
+    # @param [Object] default
+    #  The default value for an option.
+    #
+    # @return [void]
+    def set_option(short, long, desc, as: String, default: nil)
+      option_parser.on(short, long, desc, as)
+      set_default({ short => default, long => default })
+    end
+
+    ##
+    # Set command option defaults.
+    #
+    # @param [{String => Object}] defaults
+    #
+    # @return [void]
+    def set_default(defaults)
+      @defaults = Ryo.from(defaults)
+    end
+
+    ##
+    # (see Cmd::OptionParser#option_parser)
+    def option_parser
+      @option_parser ||= ::OptionParser.new(nil, 26, " " * 2).tap do
+        _1.banner = ""
+        _1.on("-h", "--help", "Show help")
+      end
+    end
+
+    ##
+    # @private
+    def banner
+      @banner ||= Ryo({})
+    end
+
+    ##
+    # @private
+    def defaults
+      @defaults ||= Ryo({})
+    end
+  end
+
+  ##
+  # Parses an array of strings with
+  # [OptionParser#parse](https://docs.ruby-lang.org/en/3.2/OptionParser.html#method-i-parse).
+  #
+  # @param [Array<String>] argv
+  #  An array of strings
+  #
+  # @return [Ryo::Object]
+  #  Returns the parsed options as a Ryo object
+  def parse_options(argv)
+    options = Ryo.from(self.class.defaults)
+    option_parser.parse(argv, into: options)
+    options
+  end
+
+  ##
+  # Parses an array of strings with
+  # [OptionParser#parse!](https://docs.ruby-lang.org/en/3.2/OptionParser.html#method-i-parse-21).
+  #
+  # @param [Array<String>] argv
+  #  An array of strings
+  #
+  # @return [Ryo::Object]
+  #  Returns the parsed options as a Ryo object
+  def parse_options!(argv)
+    options = Ryo.from(self.class.defaults)
+    option_parser.parse!(argv, into: options)
+    options
+  end
+
+  ##
+  # @return [OptionParser]
+  #  Returns an instance of
+  #  [OptionParser](https://docs.ruby-lang.org/en/3.2/OptionParser.html)
+  def option_parser
+    self.class.option_parser
+  end
+end

data/lib/cmd.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Cmd
+  require_relative "cmd/mixins/argv"
+  require_relative "cmd/mixins/help"
+  require_relative "cmd/mixins/option_parser"
+
+  include ARGV
+  include Help
+
+  def self.inherited(klass)
+    klass.class_eval { include(OptionParser) }
+  end
+end

data/share/examples/cmd.rb/ls

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require_relative "setup"
+
+require "cmd"
+class Ls < Cmd
+  set_banner usage: "ls [OPTIONS]",
+             description: "Lists the contents of a directory"
+  set_option "-g PATTERN", "--grep PATTERN", "A regular expression", as: Regexp, default: /.+/
+  set_option "-d PATH", "--directory PATH", "A path to a directory", as: String, default: Dir.home
+
+  def run
+    options = parse_options(argv)
+    options.help ? show_help : run_command(options)
+  end
+
+  private
+
+  def run_command(options)
+    puts Dir.entries(options.directory)
+            .grep(options.grep)
+            .sort
+            .join("\n")
+  end
+end
+
+##
+# Run the command
+Ls.new(ARGV).run

data/share/examples/cmd.rb/setup.rb

@@ -0,0 +1 @@
+require "bundler/setup"

data/test/readme_examples_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "setup"
+
+class READMETest < Test::Unit::TestCase
+  include Test::Cmd
+
+  def test_ls_command
+    assert_equal "dev\netc\nhome\n",
+                 run_example("ls --directory test/fakefs/ --grep [^.gitkeep]").stdout
+  end
+
+  def test_ls_command_help
+    help = "Usage: ls [OPTIONS]\n\n" \
+           "Description:\n" \
+           "  Lists the contents of a directory\n\n" \
+           "Options: \n" \
+           "  -h, --help                 Show help\n" \
+           "  -g, --grep PATTERN         A regular expression\n" \
+           "  -d, --directory PATH       A path to a directory\n\n"
+    assert_equal help, run_example("ls --help").stdout
+  end
+
+  private
+
+  def run_example(command)
+    cmd File.join(__dir__, "..", "share", "examples", "cmd.rb", command)
+  end
+end

data/test/setup.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "test-unit"
+require "test-cmd"

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: cmd.rb
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- '0x1eef'
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ryo.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: test-cmd.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+description: A library for building command-line applications
+email:
+- 0x1eef@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/tests.yml"
+- ".gitignore"
+- ".projectile"
+- ".rubocop.yml"
+- ".yardoc-template/default/fulldoc/html/css/0x1eef.css"
+- ".yardoc-template/default/layout/html/setup.rb"
+- ".yardoc-template/default/module/setup.rb"
+- ".yardopts"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile.rb
+- VERSION
+- cmd.rb.gemspec
+- lib/cmd.rb
+- lib/cmd/mixins/argv.rb
+- lib/cmd/mixins/help.rb
+- lib/cmd/mixins/option_parser.rb
+- share/examples/cmd.rb/ls
+- share/examples/cmd.rb/setup.rb
+- test/fakefs/.gitkeep
+- test/fakefs/dev/.gitkeep
+- test/fakefs/etc/.gitkeep
+- test/fakefs/home/.gitkeep
+- test/readme_examples_test.rb
+- test/setup.rb
+homepage: https://github.com/0x1eef/cmd.rb#readme
+licenses:
+- 0BSD
+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.4.10
+signing_key:
+specification_version: 4
+summary: A library for building command-line applications
+test_files: []