shellopts 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f97bd1dadffdc1a8e5eab5635bdb186ddb925bafc2fe60b478c84d3b9590fb63
+  data.tar.gz: 9909d8069a937593e7a583d6fd8db1989f7eb8e321d9c655e2d0f376caeffd24
+SHA512:
+  metadata.gz: 161c50d8cb2dc9abaa91164c3898f57942a6d51fcaadcb83bfd52cb96115548772be5d244d7e620f71751b523fdd5db0ab8a8a8bc76624be40a94d0341ac53c3
+  data.tar.gz: abaa5c58dfc5aaa98a553b4cb582c738a4bcd3649e5681c034a32b550bb583d106e4b0240cb0c5225dc0c8f58b3a32af2bd314d5894209b39b72e26446c6f4e3

data/.gitignore

@@ -0,0 +1,28 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# simplecov
+/coverage/
+
+# Ignore Gemfile.lock. See https://stackoverflow.com/questions/4151495/should-gemfile-lock-be-included-in-gitignore
+/Gemfile.lock
+
+# Ignore vim files
+.*.swp
+
+# Ignore t.* files
+t
+t.*
+tt
+tt.*
+s
+s.*
+

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.5.1

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in shellopts.gemspec
+gemspec

data/README.md

@@ -0,0 +1,352 @@
+# Shellopts
+
+`ShellOpts` is a simple 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
+
+```ruby
+require 'shellopts'
+
+# Define options
+USAGE = "a,all count=#? file= +v,verbose -- FILE..."
+
+# Define default values
+all = false
+count = nil
+file = nil
+verbosity_level = 0
+
+# Process command line and return remaining non-option arguments
+args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
+  case opt
+    when '-a', '--all';    all = true
+    when '--count';        count = arg || 42
+    when '--file';         file = arg # never nil
+    when '-v, '--verbose'; verbosity_level += 1
+  else
+    fail "Internal Error: Unmatched option: '#{opt}'"
+  end
+end
+
+# Process remaining arguments
+args.each { |arg| ... }
+```
+
+Note that the `else` clause catches legal but unhandled options; it is not an
+user error. It typically happens because of a missing or misspelled option name
+in the `when` clauses
+
+If there is an error in the command line options, the program will exit with
+status 1 and print an error message and a short usage description on standard
+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
+
+```ruby
+args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
+  case opt
+    when ...
+  end
+end
+```
+
+This calls the block for each option in the same order as on the command line
+and return the remaining non-option args. It also sets up the `ShellOpts.error` and
+`ShellOpts.fail` methods. Please note that you need to call `ShellOpts.reset`
+if you want to process another command line
+
+If `ShellOpts.process` is called without a block it returns a
+`ShellOpts::ShellOpts` object. It can be used to process more than one command
+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
+args = shellopts.args                       # Access remaining arguments
+shellopts.error "Something went wrong"      # Emit an error message and exit
+```
+
+## Usage string
+
+A usage string, typically named `USAGE`, is a list of option and command
+definitions separated by whitespace. It can span multiple lines. A double
+dash (`--`) marks the end of the definition, anything after that is not
+interpreted but copied verbatim in error messages
+
+The general [syntax](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) is
+
+```EBNF
+options { command options } [ "--" anything ]
+```
+
+## Options
+
+An option is defined by a list of comma-separated names optionally prefixed by a
+`+` and/or followed by a `=` and a set of flags. The syntax is
+
+```EBNF
+[ "+" ] name-list [ "=" [ "#" | "$" ] [ label ] [ "?" ] ]
+```
+
+#### Repeated options
+
+Options are unique by default and the user will get an error if an option is
+used more than once. You can tell the parser to allow several instances of the
+same option by prefixing the option names with a `+`. A typical use case is to
+let the user repeat a 'verbose' option to increase verbosity: `+v,verbose`
+allows `-vvv` or `--verbose --verbose --verbose`. `ShellOpts::process` yields
+an entry for each usage so should handle repeated options like this
+
+```ruby
+verbosity_level = 0
+
+args = ShellOpts.process(USAGE, ARGV) do |opt, arg|
+  case opt
+    when '-v', '--verbose'; verbosity_level += 1
+    # other options
+  end
+end
+```
+
+#### Option names
+
+Option names are a comma-separated list of names. Names can consist of one or more
+ASCII letters (a-zA-Z), digits, underscores ('\_') and dashes ('-').  A name
+can't start with a dash, though
+
+Names that are one character long are considered 'short options' and are
+prefixed with a single dash on the command line (eg. '-a'). Names with two or
+more characters are 'long options' and are used with two dashes (eg. '--all').
+Note that short and long names handles arguments differently
+
+Examples:
+```
+a               # -a
+all             # --all
+a,all           # -a or --all
+r,R,recursive   # -r, -R, or --recursive
+```
+
+#### Option argument
+
+An option that takes an an argument is declared with a `=` after the name list.
+By default the type of an option is a `String` but a integer argument can be
+specified by the `#` flag and a float argument by the `$` flag.  
+
+You can label a option value that will be used in help texts and error
+messages. A usage string like `file=FILE` will be displayed as `--file=FILE`
+and `file=FILE?` like `--file[=FILE]`. If no label is given, `INT` will be used
+for integer arguments, `FLOAT` for floating point, and else `ARG`
+
+Arguments are mandatory by default but can be made optional by suffixing a `?`
+
+## Commands
+
+Sub-commands (like `git clone`) are defined by a name (or a dot-separated list
+of names) followed by an exclamation mark. All options following a command are
+local to that command. It is not possible to 'reset' this behaviour so global
+options should always come before the first command. Nested commands are
+specified using a dot-separated "path" to the nested sub-command
+
+Examples
+```
+g,global clone! t,template=
+g,global clone! t,template= clone.list! v,verbose
+```
+
+The last example could be called like `program -g clone list -v`. You may split
+the usage string to improve readability:
+
+```
+g,global 
+    clone! t,template= 
+        clone.list! v,verbose
+```
+
+#### Command processing
+
+Commands are treated like options but with a value that is an array of options (and 
+sub-commands) to the command:
+
+```ruby
+USAGE = "a cmd! b c"
+
+args = ShellOpts.process(USAGE, ARGV) { |opt,val|
+  case opt
+    when '-a'; # Handle -a
+    when 'cmd'
+      opt.each { |opt, val|
+        case opt
+          when '-b'; # Handle -b
+          when '-c'; # Handle -c
+        end
+      }
+  end
+}
+```
+
+## Parsing
+
+Parsing of the command line follows the UNIX traditions for short and long
+options. Short options are one letter long and prefixed by a `-`. Short options
+can be grouped so that `-abc` is the same as `-a -b -c`.  Long options are
+prefixed with a `--` and can't be grouped
+
+Mandatory arguments to short options can be separated by a whitespace (`-f
+/path/to/file`) but optional arguments needs to come immediately after the
+option: `-f/path/to/file`. Long options also allow a space separator for
+mandatory arguments but use `=` to separate the option from optional arguments:
+`--file=/path/to/file`
+
+Examples
+```
+f=              # -farg or -f arg
+f=?             # -farg
+
+file=           # --file=arg or --file arg
+file=?          # --file=arg
+```
+
+#### Error handling
+
+If the command line is invalid, it's a user error and the program exits with
+status 1 and prints an error message on STDERR 
+
+If there is an error in the usage string, ShellOpts raises a
+`ShellOpts::CompileError`. Note that this exception signals an error by the
+application developer and shouldn't be catched. If there is an internal error
+in the library, a ShellOpts::InternalError is raised and you should look for a
+newer version of `ShellOpts` or file a bug-report
+
+All ShellOpt exceptions derive from ShellOpt::Error
+
+#### Error handling methods
+
+ShellOpts provides two methods that can be used by the application to
+generate error messages in the style of ShellOpts: `ShellOpts.error` and
+`ShellOpts.fail`. Both write an error message on STDERR and terminates the
+program with status 1. 
+
+`error` is intended to respond to user errors (like giving a file name that
+doesn't exist) and prints a short usage summary to remind the user:
+
+```
+<PROGRAM>: <MESSAGE>
+Usage: <PROGRAM> <USAGE>
+```
+The usage string is a prettyfied version of the usage definition given to
+ShellOpts
+
+`fail` is used to report that something is wrong with the assumptions about the
+system (eg. disk full) and omits the usage summary
+```
+<PROGRAM>: <MESSAGE>
+```
+
+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`
+
+## Example
+
+The rm(1) command could be implemented like this
+```ruby
+
+require 'shellopts'
+
+# Define options
+USAGE = %{
+  f,force i I interactive=WHEN? r,R,recusive d,dir 
+  one-file-system no-preserve-root preserve-root 
+  v,verbose help version
+}
+
+# Define defaults
+force = false
+prompt = false
+prompt_once = false
+interactive = false
+interactive_when = nil
+recursive = false
+remove_empty_dirs = false
+one_file_system = false
+preserve_root = true
+verbose = false
+
+# Process command line
+args = ShellOpts.process(USAGE, ARGV) { |opt, val|
+  case opt
+    when '-f', '--force';           force = true
+    when '-i';                      prompt = true
+    when '-I';                      prompt_once = true
+    when '--interactive';           interactive = true; interactive_when = val
+    when '-r', '-R', '--recursive'; recursive = true
+    when '-d', '--dir';             remove_empty_dirs = true
+    when '--one-file-system';       one_file_system = true
+    when '--preserve-root';         preserve_root = true
+    when '--no-preserve-root';      preserve_root = false
+    when '--verbose';               verbose = true
+    when '--help';                  print_help; exit
+    when '--version';               puts VERSION; exit
+  end
+end
+
+# Remaining arguments are files or directories
+files = args
+```
+
+
+## See also
+
+* [Command Line Options: How To Parse In Bash Using “getopt”](http://www.bahmanm.com/blogs/command-line-options-how-to-parse-in-bash-using-getopt)
+
+## Installation
+
+To install in your gem repository:
+
+```
+$ gem install shellopts
+```
+
+To add it as a dependency for an executable add this line to your application's
+`Gemfile`. Use exact version match as ShellOpts is still in development:
+
+```ruby
+gem 'shellopts', 'x.y.z'
+```
+
+If you're developing a library, you should add the dependency to the `*.gemfile` instead:
+
+```ruby
+spec.add_dependency 'shellopts', 'x.y.z'
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/[USERNAME]/shellopts.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO

@@ -0,0 +1,97 @@
+
+TODO
+  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 Doc: Example of processing of sub-commands and sub-sub-commands
+
+  + More tests
+  + More doc
+  + Implement value-name-before-flags rule
+  + Kill option array values
+  + Kill key forms
+  + Rename Option#opt to Option#name
+  + Have all Ast objects to be on [key, name, value] form
+  + Change #=>i, $=>f and introduce b (boolean)
+  + Unshift program name to usage definition string before compiling
+  + Rename to UsageCompiler and ArgvParser
+  + Make usage-string handle commands
+  + Change !cmd to cmd!
+  + Clean-up terminology: Option-name is used for names with and without the prefixed dashes
+  + Rename Option#has_argument? and #optional? to something else
+  + Fix location reporting of compiler errors
+  + Allow '--' in usage so that everything after can be used as USAGE in error messages
+  + Handle pretty-printing of usage string in handling of ParserError
+  + Compiler.new.compile(usage), Parser.new(compiled_program).parse(argv)
+  + Check for duplicate option in the parser
+  + Handle CompilerError
+  + Use nil value as the name of the top 'command'
+  + Refactor compilation to avoid having the Command objects throw CompilerErrors
+  + Change to 'parser.parse' / 'parser.parse3'
+  + Use first long option as symbolic key
+  + Use full option names everywhere (eg. '--all' instead of 'all')
+
+  - Revert change from '#' -> 'i'
+  - Guard against reserved 'object_id' name in OpenStruct
+  - Default value ('=' -> ':')
+      Default values are better handled in the calling program
+
+  ? More specialized exceptions: "MissingArgumentError" etc.
+
+LATER
+  o Allow '-a' and '--aa' in usage
+  o Allow single-line comments
+  o Allow multi-line comments
+  o Regex as option value spec
+  o "FILE", "DIR", "NEWFILE", "NEWDIR" as keyword in option value spec
+      RFILE, RDIR
+      WFILE, WDIR
+      EFILE, EDIR
+  o Octal and hexadecimal integers
+  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...
+
+ON TO_H BRANCH
+  ShellOpts.process(usage, argv) { |opt,val| ... } => args
+  ShellOpts.process(usage, argv) { |key,opt,val| ... } => args
+
+  opts = ShellOpts.new(usage, argv, defaults = {})
+  opts = ShellOpts.new(usage, argv, defaults = OpenStruct.new)
+
+  opts.args
+  opts.to_a
+  opts.to_h
+  opts.to_openstruct
+
+  opts.each { |opt,val| ... }
+  opts.each { |key,opt,val| ... }
+
+LONG FORMAT
+
+  PROGRAM = File.basename(ARGV.first)
+  USAGE = "-a -f FILE -lvh FILE..."
+  DESCR = %(
+    Short description
+
+    Longer description
+  )
+  OPTIONS = %(
+    -a,--all
+      Process all files
+
+    -f, --file=FILE
+      Process file
+
+    !command
+      This is a command
+
+      --this-is-a-command-option
+        Options for commands are nested
+
+    ...
+  )
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "shellopts"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/mkdoc

@@ -0,0 +1,10 @@
+#!/usr/bin/bash
+
+LINK='<link rel="stylesheet" type="text/css" href="stylesheet.css">'
+
+{
+        echo $LINK
+        pandoc README.md
+} >index.html
+
+rdoc lib

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/ext/array.rb

@@ -0,0 +1,9 @@
+
+module XArray
+  refine Array do
+    # Find and return first duplicate. Return nil if not found
+    def find_dup
+      detect { |e| rindex(e) != index(e) }
+    end
+  end
+end

data/lib/shellopts/ast/command.rb

@@ -0,0 +1,41 @@
+module ShellOpts
+  module Ast
+    class Command < Node
+      # Array of options (Ast::Option). Initially empty but filled out by the
+      # parser
+      attr_reader :options
+
+      # Optional sub-command (Ast::Command). Initially nil but assigned by the
+      # parser
+      attr_accessor :command 
+
+      def initialize(grammar, name)
+        super(grammar, name)
+        @options = []
+        @command = nil
+      end
+
+      # Array of option or command tuples
+      def values
+        (options + (Array(command || []))).map { |node| node.to_tuple }
+      end
+
+      # :nocov:
+      def dump(&block)
+        super {
+          yield if block_given?
+          puts "options:"
+          indent { options.each { |opt| opt.dump } }
+          print "command:"
+          if command
+            puts
+            indent { command.dump }
+          else
+            puts "nil"
+          end
+        }
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/shellopts/ast/node.rb

@@ -0,0 +1,37 @@
+module ShellOpts
+  module Ast
+    class Node
+      # The associated Grammar::Node object
+      attr_reader :grammar
+
+      # Key of node. Shorthand for grammar.key
+      def key() @grammar.key end
+
+      # Name of node (either program, command, or option name)
+      attr_reader :name
+
+      # Initialize an +Ast::Node+ object. +grammar+ is the corresponding
+      # grammar object (+Grammar::Node+) and +name+ is the name of the option
+      # or sub-command
+      def initialize(grammar, name)
+        @grammar, @name = grammar, name
+      end
+
+      # Return a name/value pair
+      def to_tuple
+        [name, values]
+      end
+
+      # Return either a value (option value), an array of values (command), or
+      # nil (option without a value). Should be defined in sub-classes
+      def values() raise end
+
+      # :nocov:
+      def dump(&block)
+        puts key.inspect
+        indent { yield } if block_given?
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/shellopts/ast/option.rb

@@ -0,0 +1,21 @@
+module ShellOpts
+  module Ast
+    class Option < Node
+      # Optional value. Can be a String, Integer, or Float
+      attr_reader :value
+
+      def initialize(grammar, name, value)
+        super(grammar, name)
+        @value = value
+      end
+
+      def values() value end
+
+      # :nocov:
+      def dump
+        super { puts "values: #{values.inspect}" }
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/shellopts/ast/program.rb

@@ -0,0 +1,14 @@
+module ShellOpts
+  module Ast
+    class Program < Command
+      # Command line arguments. Initially nil but assigned by the parser. This array
+      # is the same as the argument array returned by Ast.parse
+      attr_accessor :arguments
+
+      def initialize(grammar) 
+        super(grammar, grammar.name) 
+        @arguments = nil
+      end
+    end
+  end
+end