shellopts 0.9.5 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f6d1397c2a4ae0a4e8c168f1d695f25ade753c37f94e8b4373ce57aa222593
-  data.tar.gz: 9589f39de24f13c5d5bf6ae873b58d425cc393654362e9afa7699c5d7dd81a46
+  metadata.gz: 3096c35af16a39ffc98b52f02799aa25efa311b20916309496ee33b2a50dcf47
+  data.tar.gz: ebc336b7a5595412d1f705378f24dc6136c17e3257db7ca5ddec021349ec2a88
 SHA512:
-  metadata.gz: 577ab3793305b1eeee0b3fca253832603fbeaf4d34a511e11a7625aa356b1031e17116213c055cb5672821e524d8c34409398a1209bc3cdade7a53fded96d87f
-  data.tar.gz: bcadf1a3c495a6bda0863e42c40ef82744abc2fbe401a57286c335b62cc4e50f51ddf76847d2c360fae08f51120f3fbcd4538076e6527f5d379bd5828978f9b7
+  metadata.gz: d44d80cc028fa9c9a7add7206b6a0f096cc3deb1c7e3f756075171c4ebfb20fdb6246215ec02d8920e9b450ebfcd5355a0c3b4179cc03d7fb4f6f89eea6f3a15
+  data.tar.gz: 5bb562a9806196a6b6594897d3a09b8a1dc70abebf9f51194a6d31c031e86c54e69d1531acbb5ba6d675afb97c12d86ad2da4216af06bdcac8e056430787a97a

data/.gitignore

@@ -2,6 +2,7 @@
 /.yardoc
 /_yardoc/
 /doc/
+/rdoc/
 /pkg/
 /spec/reports/
 /tmp/

data/README.md

@@ -1,20 +1,19 @@
 # Shellopts
 
-`ShellOpts` is a simple command line parsing libray that covers most modern use
+`ShellOpts` is a simple Linux command line parsing libray that covers most modern use
 cases incl. sub-commands. Options and commands are specified using a
 getopt(1)-like string that is interpreted by the library to process the command
 line
 
 ## Usage
 
-The following program accepts `-a` and `--all` that are aliases
-for the same option, `--count` that may be given an integer argument but
-defaults to 42, `--file` that has a mandatory argument, and `-v` and
-`--verbose` that can be repeated to increase the verbosity level
+The following program accepts the options -a or --all, --count, --file, and -v
+or --verbose. It expects `--count` to have an optional integer argument,
+`--file` to have a mandatory argument, and allows `-v` and `--verbose` to be
+repeated:
 
 ```ruby
-require 'shellopts'
-
+ 
 # Define options
 USAGE = "a,all count=#? file= +v,verbose -- FILE..."
 
@@ -36,7 +35,7 @@ args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
   end
 end
 
-# Process remaining arguments
+# Process remaining command line arguments
 args.each { |arg| ... }
 ```
 
@@ -50,10 +49,10 @@ error
 
 ## Processing
 
-`ShellOpts.process` compiles a usage definition string into a grammar and use that to
-parse the command line. If given a block, the block is called with a name/value
-pair for each option or command and return a list of the remaining non-option
-arguments
+`ShellOpts.process` compiles a usage definition string into a grammar and use
+that to parse the command line. If given a block, the block is called with a
+name/value pair for each option or command and return a list of the remaining
+non-option arguments
 
 ```ruby
 args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
@@ -74,7 +73,7 @@ line at a time and to inspect the grammar and AST
 
 ```ruby
 shellopts = ShellOpts.process(USAGE, ARGV)  # Returns a ShellOpts::ShellOpts object
-shellopts.each { |opt, val| ... }           # Access options
+shellopts.each { |opt, arg| ... }           # Access options
 args = shellopts.args                       # Access remaining arguments
 shellopts.error "Something went wrong"      # Emit an error message and exit
 ```
@@ -101,6 +100,18 @@ An option is defined by a list of comma-separated names optionally prefixed by a
 [ "+" ] name-list [ "=" [ "#" | "$" ] [ label ] [ "?" ] ]
 ```
 
+#### Flags
+
+There are the following flags:
+
+|Flag|Effect|
+|---|---|
+|+|Repeated option (prefix)|
+|=|Argument. Mandatory unless `?` is also used|
+|#|Integer argument|
+|$|Floating point argument|
+|?|Optional argument|
+
 #### Repeated options
 
 Options are unique by default and the user will get an error if an option is
@@ -184,11 +195,11 @@ sub-commands) to the command:
 ```ruby
 USAGE = "a cmd! b c"
 
-args = ShellOpts.process(USAGE, ARGV) { |opt,val|
+args = ShellOpts.process(USAGE, ARGV) { |opt, arg|
   case opt
     when '-a'; # Handle -a
     when 'cmd'
-      opt.each { |opt, val|
+      arg.each { |opt, arg|
         case opt
           when '-b'; # Handle -b
           when '-c'; # Handle -c
@@ -260,6 +271,27 @@ The methods are defined as instance methods on `ShellOpts::ShellOpts` and as
 class methods on `ShellOpts`. They can also be included in the global scope by
 `include ShellOpts::Utils`
 
+#### Usage string
+
+The error handling methods prints a prettified version of the usage string
+given to `ShellOpts.parse`. The usage string can be overridden by assigning to
+`ShellOpts.usage`. A typical use case is when you want to split the usage
+description over multiple lines:
+
+```ruby
+
+USAGE="long-and-complex-usage-string"
+ShellOpts.usage = <<~EOD
+  usage explanation
+  split over
+  multiple lines
+EOD
+```
+
+Note that this only affects the module-level `ShellOpts.error` method and not
+object-level `ShellOpts::ShellOpts#error` method. This is considered a bug and
+will fixed at some point
+
 ## Example
 
 The rm(1) command could be implemented like this
@@ -287,12 +319,12 @@ preserve_root = true
 verbose = false
 
 # Process command line
-args = ShellOpts.process(USAGE, ARGV) { |opt, val|
+args = ShellOpts.process(USAGE, ARGV) { |opt, arg|
   case opt
     when '-f', '--force';           force = true
     when '-i';                      prompt = true
     when '-I';                      prompt_once = true
-    when '--interactive';           interactive = true; interactive_when = val
+    when '--interactive';           interactive = true; interactive_when = arg
     when '-r', '-R', '--recursive'; recursive = true
     when '-d', '--dir';             remove_empty_dirs = true
     when '--one-file-system';       one_file_system = true

data/TODO

@@ -1,5 +1,15 @@
 
 TODO
+  o Also allow assignment to usage string for ShellOpts::ShellOpts objects
+  o Create a ShellOpts.args method? It would be useful when processing commands:
+      case opt
+        when "command"
+          call_command_method(ShellOpts.args[1], ShellOpts.args[2])
+      end
+    ShellOpts.args would be a shorthand for ShellOpts.shellopts.args
+    Another option would be to create an argument-processing method:
+      shellopts.argv(2) -> call error if not exactly two arguments else return elements
+      
   o Check on return value from #process block to see if all options was handled:
       case opt
         when '-v'; verbose = true # Return value 'true' is ok
@@ -11,7 +21,7 @@ TODO
   o Make an official dump method for debug
   o Make a note that all options are processed at once and not as-you-go
   o Test that arguments with spaces work
-  o Long version usage strings
+  o Long version usage strings (major release)
   o Doc: Example of processing of sub-commands and sub-sub-commands
 
   + More tests

data/bin/mkdoc

@@ -1,10 +1,15 @@
 #!/usr/bin/bash
 
-LINK='<link rel="stylesheet" type="text/css" href="stylesheet.css">'
+set -e
 
-{
-        echo $LINK
-        pandoc README.md
-} >index.html
+# Generate github-like page
+(
+    cd doc
+    {
+        echo '<link rel="stylesheet" type="text/css" href="stylesheet.css">'
+        pandoc ../README.md
+    } >index.html
+)
 
-rdoc lib
+# Generate rdoc
+rdoc --output=rdoc --force-output lib

data/doc/stylesheet.css

@@ -0,0 +1,409 @@
+/*
+Copyright (c) 2017 Chris Patuzzo
+https://twitter.com/chrispatuzzo
+
+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.
+*/
+
+body {
+  font-family: Helvetica, arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.6;
+  padding-top: 10px;
+  padding-bottom: 10px;
+  background-color: white;
+  padding: 30px;
+  color: #333;
+}
+
+body > *:first-child {
+  margin-top: 0 !important;
+}
+
+body > *:last-child {
+  margin-bottom: 0 !important;
+}
+
+a {
+  color: #4183C4;
+  text-decoration: none;
+}
+
+a.absent {
+  color: #cc0000;
+}
+
+a.anchor {
+  display: block;
+  padding-left: 30px;
+  margin-left: -30px;
+  cursor: pointer;
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  margin: 20px 0 10px;
+  padding: 0;
+  font-weight: bold;
+  -webkit-font-smoothing: antialiased;
+  cursor: text;
+  position: relative;
+}
+
+h2:first-child, h1:first-child, h1:first-child + h2, h3:first-child, h4:first-child, h5:first-child, h6:first-child {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, h5:hover a.anchor, h6:hover a.anchor {
+  text-decoration: none;
+}
+
+h1 tt, h1 code {
+  font-size: inherit;
+}
+
+h2 tt, h2 code {
+  font-size: inherit;
+}
+
+h3 tt, h3 code {
+  font-size: inherit;
+}
+
+h4 tt, h4 code {
+  font-size: inherit;
+}
+
+h5 tt, h5 code {
+  font-size: inherit;
+}
+
+h6 tt, h6 code {
+  font-size: inherit;
+}
+
+h1 {
+  font-size: 28px;
+  color: black;
+}
+
+h2 {
+  font-size: 24px;
+  border-bottom: 1px solid #cccccc;
+  color: black;
+}
+
+h3 {
+  font-size: 18px;
+}
+
+h4 {
+  font-size: 16px;
+}
+
+h5 {
+  font-size: 14px;
+}
+
+h6 {
+  color: #777777;
+  font-size: 14px;
+}
+
+p, blockquote, ul, ol, dl, li, table, pre {
+  margin: 15px 0;
+}
+
+hr {
+  border: 0 none;
+  color: #cccccc;
+  height: 4px;
+  padding: 0;
+}
+
+body > h2:first-child {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+body > h1:first-child {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+body > h1:first-child + h2 {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+body > h3:first-child, body > h4:first-child, body > h5:first-child, body > h6:first-child {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+h1 p, h2 p, h3 p, h4 p, h5 p, h6 p {
+  margin-top: 0;
+}
+
+li p.first {
+  display: inline-block;
+}
+
+ul, ol {
+  padding-left: 30px;
+}
+
+ul :first-child, ol :first-child {
+  margin-top: 0;
+}
+
+ul :last-child, ol :last-child {
+  margin-bottom: 0;
+}
+
+dl {
+  padding: 0;
+}
+
+dl dt {
+  font-size: 14px;
+  font-weight: bold;
+  font-style: italic;
+  padding: 0;
+  margin: 15px 0 5px;
+}
+
+dl dt:first-child {
+  padding: 0;
+}
+
+dl dt > :first-child {
+  margin-top: 0;
+}
+
+dl dt > :last-child {
+  margin-bottom: 0;
+}
+
+dl dd {
+  margin: 0 0 15px;
+  padding: 0 15px;
+}
+
+dl dd > :first-child {
+  margin-top: 0;
+}
+
+dl dd > :last-child {
+  margin-bottom: 0;
+}
+
+blockquote {
+  border-left: 4px solid #dddddd;
+  padding: 0 15px;
+  color: #777777;
+}
+
+blockquote > :first-child {
+  margin-top: 0;
+}
+
+blockquote > :last-child {
+  margin-bottom: 0;
+}
+
+table {
+  padding: 0;
+}
+table tr {
+  border-top: 1px solid #cccccc;
+  background-color: white;
+  margin: 0;
+  padding: 0;
+}
+
+table tr:nth-child(2n) {
+  background-color: #f8f8f8;
+}
+
+table tr th {
+  font-weight: bold;
+  border: 1px solid #cccccc;
+  text-align: left;
+  margin: 0;
+  padding: 6px 13px;
+}
+
+table tr td {
+  border: 1px solid #cccccc;
+  text-align: left;
+  margin: 0;
+  padding: 6px 13px;
+}
+
+table tr th :first-child, table tr td :first-child {
+  margin-top: 0;
+}
+
+table tr th :last-child, table tr td :last-child {
+  margin-bottom: 0;
+}
+
+img {
+  max-width: 100%;
+}
+
+span.frame {
+  display: block;
+  overflow: hidden;
+}
+
+span.frame > span {
+  border: 1px solid #dddddd;
+  display: block;
+  float: left;
+  overflow: hidden;
+  margin: 13px 0 0;
+  padding: 7px;
+  width: auto;
+}
+
+span.frame span img {
+  display: block;
+  float: left;
+}
+
+span.frame span span {
+  clear: both;
+  color: #333333;
+  display: block;
+  padding: 5px 0 0;
+}
+
+span.align-center {
+  display: block;
+  overflow: hidden;
+  clear: both;
+}
+
+span.align-center > span {
+  display: block;
+  overflow: hidden;
+  margin: 13px auto 0;
+  text-align: center;
+}
+
+span.align-center span img {
+  margin: 0 auto;
+  text-align: center;
+}
+
+span.align-right {
+  display: block;
+  overflow: hidden;
+  clear: both;
+}
+
+span.align-right > span {
+  display: block;
+  overflow: hidden;
+  margin: 13px 0 0;
+  text-align: right;
+}
+
+span.align-right span img {
+  margin: 0;
+  text-align: right;
+}
+
+span.float-left {
+  display: block;
+  margin-right: 13px;
+  overflow: hidden;
+  float: left;
+}
+
+span.float-left span {
+  margin: 13px 0 0;
+}
+
+span.float-right {
+  display: block;
+  margin-left: 13px;
+  overflow: hidden;
+  float: right;
+}
+
+span.float-right > span {
+  display: block;
+  overflow: hidden;
+  margin: 13px auto 0;
+  text-align: right;
+}
+
+code, tt {
+  margin: 0 2px;
+  padding: 0 5px;
+  white-space: nowrap;
+  border: 1px solid #eaeaea;
+  background-color: #f8f8f8;
+  border-radius: 3px;
+}
+
+pre code {
+  margin: 0;
+  padding: 0;
+  white-space: pre;
+  border: none;
+  background: transparent;
+}
+
+.highlight pre {
+  background-color: #f8f8f8;
+  border: 1px solid #cccccc;
+  font-size: 13px;
+  line-height: 19px;
+  overflow: auto;
+  padding: 6px 10px;
+  border-radius: 3px;
+}
+
+pre {
+  background-color: #f8f8f8;
+  border: 1px solid #cccccc;
+  font-size: 13px;
+  line-height: 19px;
+  overflow: auto;
+  padding: 6px 10px;
+  border-radius: 3px;
+}
+
+pre code, pre tt {
+  background-color: transparent;
+  border: none;
+}

data/lib/shellopts.rb

@@ -12,6 +12,18 @@ require 'shellopts/utils.rb'
 # name of the program
 #
 module ShellOpts
+  # Return the hidden +ShellOpts::ShellOpts+ object (see .process)
+  def self.shellopts()
+    @shellopts
+  end
+
+  # Prettified usage string used by #error and #fail. Default is +usage+ of
+  # the current +ShellOpts::ShellOpts+ object
+  def self.usage() @usage || @shellopts&.usage end
+
+  # Set the usage string
+  def self.usage=(usage) @usage = usage end
+  
   # Process command line options and arguments.  #process takes a usage string
   # defining the options and the array of command line arguments to be parsed
   # as arguments
@@ -72,14 +84,16 @@ module ShellOpts
   # #process saves a hidden {ShellOpts::ShellOpts} class variable used by the
   # class methods #error and #fail. Call #reset to clear the global object if
   # you really need to parse more than one command line. Alternatively you can
-  # create +ShellOpts::ShellOpts+ objects yourself and use the object methods
-  # #error and #fail instead:
+  # create +ShellOpts::ShellOpts+ objects yourself and also use the object methods
+  # #error and #fail:
   #
   #   shellopts = ShellOpts::ShellOpts.new(USAGE, ARGS)
   #   shellopts.each { |name, value| ... }
   #   shellopts.args.each { |arg| ... }
   #   shellopts.error("Something went wrong")
   #
+  # Use #shellopts to get the hidden +ShellOpts::ShellOpts+ object
+  #
   def self.process(usage, argv, program_name: PROGRAM, &block)
     if !block_given?
       ShellOpts.new(usage, argv, program_name: program_name)
@@ -95,15 +109,20 @@ module ShellOpts
   # another command line
   def self.reset()
     @shellopts = nil
+    @usage = nil
   end
 
   # Print error message and usage string and exit with status 1. It use the
   # current ShellOpts object if defined. This method should be called in
   # response to user-errors (eg. specifying an illegal option)
+  #
+  # If there is no current ShellOpts object +error+ will look for USAGE to make
+  # it possible to use +error+ before the command line is processed and also as
+  # a stand-alone error reporting method
   def self.error(*msgs)
     program = @shellopts&.program_name || PROGRAM
-    usage = @shellopts&.usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
-    emit_and_exit(program, usage, *msgs)
+    usage_string = usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
+    emit_and_exit(program, @usage.nil?, usage_string, *msgs)
   end
 
   # Print error message and exit with status 1. It use the current ShellOpts
@@ -111,7 +130,7 @@ module ShellOpts
   # user-errors but system errors (like disk full)
   def self.fail(*msgs)
     program = @shellopts&.program_name || PROGRAM
-    emit_and_exit(program, nil, *msgs)
+    emit_and_exit(program, false, nil, *msgs)
   end
 
   # The compilation object
@@ -119,7 +138,7 @@ module ShellOpts
     # Name of program
     attr_reader :program_name
 
-    # Usage string. Shorthand for +grammar.usage+
+    # Prettified usage string used by #error and #fail. Shorthand for +grammar.usage+
     def usage() @grammar.usage end
 
     # The grammar compiled from the usage string. If #ast is defined, it's
@@ -172,13 +191,13 @@ module ShellOpts
     # should be called in response to user-errors (eg. specifying an illegal
     # option)
     def error(*msgs)
-      ::ShellOpts.emit_and_exit(program_name, usage, msgs)
+      ::ShellOpts.emit_and_exit(program_name, true, usage, msgs)
     end
 
     # Print error message and exit with status 1. This method should not be
     # called in response to user-errors but system errors (like disk full)
     def fail(*msgs)
-      ::ShellOpts.emit_and_exit(program_name, nil, msgs)
+      ::ShellOpts.emit_and_exit(program_name, false, nil, msgs)
     end
   end
 
@@ -199,9 +218,13 @@ module ShellOpts
 private
   @shellopts = nil
 
-  def self.emit_and_exit(program, usage, *msgs)
+  def self.emit_and_exit(program, use_usage, usage, *msgs)
     $stderr.puts "#{program}: #{msgs.join}"
-    $stderr.puts "Usage: #{program} #{usage}" if usage
+    if use_usage
+      $stderr.puts "Usage: #{program} #{usage}" if usage
+    else
+      $stderr.puts usage if usage
+    end
     exit 1
   end
 end

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module Shellopts
-  VERSION = "0.9.5"
+  VERSION = "1.0.1"
 end

data/shellopts.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "bundler", "~> 2.2.10"
   spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "indented_io"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shellopts
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 1.0.1
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-03 00:00:00.000000000 Z
+date: 2021-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 2.2.10
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 2.2.10
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -103,6 +103,7 @@ files:
 - bin/console
 - bin/mkdoc
 - bin/setup
+- doc/stylesheet.css
 - lib/ext/array.rb
 - lib/shellopts.rb
 - lib/shellopts/ast/command.rb
@@ -137,8 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Parse command line options and arguments