shellopts 0.9.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35b358de39fe1966b1f9ad95dd2e92b296e86f122439a0e69d9ca3367005e279
-  data.tar.gz: 6080ae9b374490c0a39f70a440b65e80a711756646997e2589d059c627c9c12a
+  metadata.gz: 4cc3c3ef5b7b13876949b290b9d247c41778eaa38ea01432d5abac47b663478a
+  data.tar.gz: bc2c44f163f81d8b51545679e8f8280ac889fbb1f96a7898e5a65fa63d337d4a
 SHA512:
-  metadata.gz: 7ac618dcd5a918827b7a57dd8b462352f8f464e844428eac60aabd5c3cca220a89898f3bd1f4abf7e5d8f8dbac9bfb46dfd22c8a1d4baf300683fc2ccbe24630
-  data.tar.gz: a278e013c2a8e2ec673c4dc8ebb0198a8060e71164a5b3d3d68f48ec5f56009b1d2589f5f069855d640e7c76f50fe7493ea21e2118c331803e1e0ef003e83178
+  metadata.gz: d3c501335a899e4b14280cbb14b7f9e8a0d9ef28715760394d8f13ea837d0a5d3d9b91b9d07dcb42a747753e97a10c157ae5c5b20b95804b1746e0ebad7d88c9
+  data.tar.gz: 387c888158bbbebe127c6efde55c7bbb14436b7dcb8227cac38e2c9dac85e9a3d956c062e04b86101e28fa0bde4977fefadad4d1a643dd48d9218e5c04558ad2

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,12 +1,27 @@
 
 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
+        # Unhandled option means return value is nil
+      end
   o Consolidate some of the 3 variations of #error and #fail
   o Add a option flag for solitary options (--help) 
   o Make a #to_yaml
   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
@@ -55,6 +70,7 @@ LATER
   o Escape of separator in lists
   o Handle output of subcommand usage like "cmd1 cmd1.cmd2 cmd2"
   o Command-specific arguments: clone! o,opt ++ ARG1 ARG2...
+  o Hostname and email as basic types
 
 ON TO_H BRANCH
   ShellOpts.process(usage, argv) { |opt,val| ... } => args

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/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/compiler.rb

@@ -27,7 +27,7 @@ module ShellOpts
 
       # Initialize a Compiler object. source is the option definition string
       def initialize(program_name, source)
-        @program_name, @tokens = program_name, source.split(/\s+/)
+        @program_name, @tokens = program_name, source.split(/\s+/).reject(&:empty?)
 
         # @commands_by_path is an hash from command-path to Command or Program
         # object. The top level Program object has nil as its path.

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module Shellopts
-  VERSION = "0.9.3"
+  VERSION = "1.0.0"
 end

data/shellopts.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "indented_io"
   spec.add_development_dependency "simplecov"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shellopts
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-30 00:00:00.000000000 Z
+date: 2020-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -28,16 +28,16 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: rspec
   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