shellopts 0.9.2 → 0.9.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 710c9651cae2494969fe031b4d8a91bbcebd123c8d395b512bec5b193c50e6ea
-  data.tar.gz: e2a4901ea784ec6331ccd65ef4df58daf04aba44c0c395f736da27eee14f8f12
+  metadata.gz: 4a081efe12e3a4e2f4b38eab4d2f6776c5dc3c748fb06178a4b42dbbba4e9612
+  data.tar.gz: 27a8d76c4de24c440bd330aa84d2e17014456c927af3c4a12807573df798c01a
 SHA512:
-  metadata.gz: ad85e178173ba17e7cfc0b452cc1bcdd50e7c17374885b8aecddd4495e04a5492c14bdecfdd13445738e63c8bfa2434c3f0957ab1e7d803dc18ba42722726761
-  data.tar.gz: be53d32e0fdcbcf4caee01762e5bb5d6b8452ffeaf6ae7f65e9746cf7a222aa65ab38ca8dd4db8de91c6f0507e4fc9df88d30c286e29a83d994d020bae4759a1
+  metadata.gz: 4f21b1f020dd04219272d5772cf0483b88c108af9991450e2532fcdab5322635a80a1cbac512c284358d10f271c03b4adef65ffb379d3df8a1d6635b9ca9f518
+  data.tar.gz: e88c6c0abcb49a7ba6568aa66c62267a63b92cfb9969387522a52b045fc34d4121cddb4b8c11ffe68d8ed3f13f925391e393e5b4ac292732696de019f7ed4217

data/.gitignore

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

data/README.md

@@ -1,20 +1,20 @@
 # 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
+Program that accepts the options -a or --all, --count, --file, and -v or
+--verbose.  The usage definition 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'
 
+```ruby
+ 
 # Define options
 USAGE = "a,all count=#? file= +v,verbose -- FILE..."
 
@@ -36,7 +36,7 @@ args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
   end
 end
 
-# Process remaining arguments
+# Process remaining command line arguments
 args.each { |arg| ... }
 ```
 
@@ -50,10 +50,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|
@@ -101,6 +101,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
@@ -260,6 +272,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

data/TODO

@@ -1,5 +1,10 @@
 
 TODO
+  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
@@ -55,6 +60,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

@@ -2,6 +2,7 @@ require "shellopts/version"
 
 require 'shellopts/compiler.rb'
 require 'shellopts/parser.rb'
+require 'shellopts/utils.rb'
 
 # ShellOpts is a library for parsing command line options and sub-commands. The
 # library API consists of the methods {ShellOpts.process}, {ShellOpts.error},
@@ -11,6 +12,18 @@ require 'shellopts/parser.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
@@ -71,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)
@@ -94,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
@@ -110,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
@@ -118,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
@@ -171,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
 
@@ -198,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.2"
+  VERSION = "0.9.7"
 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.2
+  version: 0.9.7
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-27 00:00:00.000000000 Z
+date: 2020-07-18 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