shellopts 0.9.5 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f6d1397c2a4ae0a4e8c168f1d695f25ade753c37f94e8b4373ce57aa222593
-  data.tar.gz: 9589f39de24f13c5d5bf6ae873b58d425cc393654362e9afa7699c5d7dd81a46
+  metadata.gz: 943b9d0c44ba0291937be24cbc79d0155dfc22ac788c69a76639850d78af3303
+  data.tar.gz: f38e038f613c577b06e9d2facc6096b39eb18f28266ba8c58a8280adcf75fe47
 SHA512:
-  metadata.gz: 577ab3793305b1eeee0b3fca253832603fbeaf4d34a511e11a7625aa356b1031e17116213c055cb5672821e524d8c34409398a1209bc3cdade7a53fded96d87f
-  data.tar.gz: bcadf1a3c495a6bda0863e42c40ef82744abc2fbe401a57286c335b62cc4e50f51ddf76847d2c360fae08f51120f3fbcd4538076e6527f5d379bd5828978f9b7
+  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
@@ -260,6 +272,23 @@ 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`. 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
 
 The rm(1) command could be implemented like this

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_string, *msgs)
   end
 
   # Print error message and exit with status 1. It use the current ShellOpts
@@ -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

data/lib/shellopts/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shellopts
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 0.9.6
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-03 00:00:00.000000000 Z
+date: 2020-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -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