shellopts 0.9.1 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f97bd1dadffdc1a8e5eab5635bdb186ddb925bafc2fe60b478c84d3b9590fb63
-  data.tar.gz: 9909d8069a937593e7a583d6fd8db1989f7eb8e321d9c655e2d0f376caeffd24
+  metadata.gz: 943b9d0c44ba0291937be24cbc79d0155dfc22ac788c69a76639850d78af3303
+  data.tar.gz: f38e038f613c577b06e9d2facc6096b39eb18f28266ba8c58a8280adcf75fe47
 SHA512:
-  metadata.gz: 161c50d8cb2dc9abaa91164c3898f57942a6d51fcaadcb83bfd52cb96115548772be5d244d7e620f71751b523fdd5db0ab8a8a8bc76624be40a94d0341ac53c3
-  data.tar.gz: abaa5c58dfc5aaa98a553b4cb582c738a4bcd3649e5681c034a32b550bb583d106e4b0240cb0c5225dc0c8f58b3a32af2bd314d5894209b39b72e26446c6f4e3
+  metadata.gz: 42cc6102c0c66dcffda0b03f9c584c32abc0e62a65dbe79e1389753b74af11f189e27a456e79fb2cb082595622ddbce0840dd22419204e276a48134ac8afd610
+  data.tar.gz: 6a3b2e35718a5ee1f52e5d56a50ea067da90fef35a4ac3322738e24d5ba80f4aba4ac4a692caace4bb094ccfb84432e9211fef2b15dfef2e194a95569ca80686

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
@@ -257,8 +269,25 @@ system (eg. disk full) and omits the usage summary
 ```
 
 The methods are defined as instance methods on `ShellOpts::ShellOpts` and as
-class methods on `ShellOpts`. The class methods stores program name and usage
-string in global variables that are reset by `ShellOpts.reset`
+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`. It can be overridden by assigning to
+`ShellOpts.usage`. You'll often assign to the usage string when it needs to be
+split over several lines:
+
+```ruby
+
+USAGE="long-and-complex-usage-string"
+ShellOpts.usage = %(
+  usage explanation
+  split over
+  multiple lines
+)
+```
 
 ## Example
 

data/TODO

@@ -1,5 +1,11 @@
 
 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
   o Make an official dump method for debug
@@ -54,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,12 +2,28 @@ 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},
 # and {ShellOpts.fail} and the result class {ShellOpts::ShellOpts}
 #
+# ShellOpts inject the constant PROGRAM into the global scope. It contains the 
+# 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
@@ -68,15 +84,17 @@ 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")
   #
-  def self.process(usage, argv, program_name: File.basename($0), &block)
+  # 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)
     else
@@ -91,17 +109,28 @@ module ShellOpts
   # another command line
   def self.reset()
     @shellopts = nil
+    @usage = nil
   end
 
-  # Print error message and usage string and exit with status 1. Can only be
-  # called after #process. Forwards to {::ShellOpts#error}
+  # 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)
-    @shellopts&.error(*msgs) or raise InternalError, "ShellOpts class variable not initialized"
+    program = @shellopts&.program_name || PROGRAM
+    usage_string = usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
+    emit_and_exit(program, usage_string, *msgs)
   end
 
-  # Print error message and exit with status 1. Forwards to {::ShellOpts#fail}
+  # Print error message and exit with status 1. It use the current ShellOpts
+  # object if defined. This method should not be called in response to
+  # user-errors but system errors (like disk full)
   def self.fail(*msgs)
-    @shellopts&.fail(*msgs) or raise InternalError, "ShellOpts class variable not initialized"
+    program = @shellopts&.program_name || PROGRAM
+    emit_and_exit(program, nil, *msgs)
   end
 
   # The compilation object
@@ -109,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
@@ -162,16 +191,13 @@ module ShellOpts
     # should be called in response to user-errors (eg. specifying an illegal
     # option)
     def error(*msgs)
-      $stderr.puts "#{program_name}: #{msgs.join}"
-      $stderr.puts "Usage: #{program_name} #{usage}"
-      exit 1
+      ::ShellOpts.emit_and_exit(program_name, 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)
-      $stderr.puts "#{program_name}: #{msgs.join}"
-      exit 1
+      ::ShellOpts.emit_and_exit(program_name, nil, msgs)
     end
   end
 
@@ -191,5 +217,12 @@ module ShellOpts
 
 private
   @shellopts = nil
+
+  def self.emit_and_exit(program, usage, *msgs)
+    $stderr.puts "#{program}: #{msgs.join}"
+    $stderr.puts "Usage: #{program} #{usage}" if usage
+    exit 1
+  end
 end
 
+PROGRAM = File.basename($PROGRAM_NAME)

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/grammar/command.rb

@@ -19,7 +19,6 @@ module ShellOpts
       attr_reader :commands 
 
       # List of options in declaration order
-      # order
       attr_reader :option_list
 
       # List of commands in declaration order

data/lib/shellopts/utils.rb

@@ -0,0 +1,16 @@
+
+module ShellOpts
+  # Use `include ShellOpts::Utils` to include ShellOpts utility methods in the
+  # global namespace
+  module Utils
+    # Forwards to `ShellOpts.error`
+    def error(*msgs)
+      ::ShellOpts.error(*msgs)
+    end
+
+    # Forwards to `ShellOpts.fail`
+    def fail(*msgs)
+      ::ShellOpts.fail(*msgs)
+    end
+  end
+end

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module Shellopts
-  VERSION = "0.9.1"
+  VERSION = "0.9.6"
 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.1
+  version: 0.9.6
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-20 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
@@ -115,6 +116,7 @@ files:
 - lib/shellopts/grammar/option.rb
 - lib/shellopts/grammar/program.rb
 - lib/shellopts/parser.rb
+- lib/shellopts/utils.rb
 - lib/shellopts/version.rb
 - shellopts.gemspec
 homepage: http://github.com/clrgit/shellopts
@@ -136,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