shellopts 0.9.5 → 2.0.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f6d1397c2a4ae0a4e8c168f1d695f25ade753c37f94e8b4373ce57aa222593
-  data.tar.gz: 9589f39de24f13c5d5bf6ae873b58d425cc393654362e9afa7699c5d7dd81a46
+  metadata.gz: 79a36712cf9c41a500726cd042d9932f1c6ed7f7e7a334d5d245e0ad31185c75
+  data.tar.gz: ddeec0f65a4d8e4250cbc9d1332626395c135d0c4e34d879fafcfb89b492699a
 SHA512:
-  metadata.gz: 577ab3793305b1eeee0b3fca253832603fbeaf4d34a511e11a7625aa356b1031e17116213c055cb5672821e524d8c34409398a1209bc3cdade7a53fded96d87f
-  data.tar.gz: bcadf1a3c495a6bda0863e42c40ef82744abc2fbe401a57286c335b62cc4e50f51ddf76847d2c360fae08f51120f3fbcd4538076e6527f5d379bd5828978f9b7
+  metadata.gz: 2890ba5f277385eb8cc30a9e168d618f3633278cc41066c302ed82d7be46eeefb5a30f41a2471947bc78a0e55e8219cc472887a91b9d753a6687dfda605231e6
+  data.tar.gz: a02ecb6e6613163f2915125ea0cd71cab30c7fd3c11f840a99bad0cb27b6a14dad0b3c806d55f8ab752e4f7921731cab0753c562499b7c88eeb8e5e8400efaab

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
@@ -346,6 +378,16 @@ release a new version, update the version number in `version.rb`, and then run
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
+## Implementation
+
+FIXME
+# ShellOpts is a library for parsing command line options and commands. It
+# consists of the interface module {ShellOpts}, the implementation class
+# {ShellOpts::ShellOpts} and the representation classes
+# {ShellOpts::OptionsHash} and {ShellOpts::OptionsStruct}.
+# {ShellOpts::Messenger} is used for error messages
+
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/TODO

@@ -1,5 +1,34 @@
 
 TODO
+  o Remove ! from OptionStruct#subcommand return value. We know we're
+    processing commands so there is no need to have a distinct name and it
+    feels a lot more intuitive without it
+  o Add validation block to ShellOpts class methods
+  o Get rid of key_name. Define #name on Grammar::Node instead
+  o Define #name to the string name of the option/command without prefixed '--'
+    for options. This can cause collisions but they can be avoided using aliases
+  o Clean-up
+    o Grammar::options -> Grammar::option_multihash
+    o Clean-up identifiers etc.
+    o Un-multi-izing Grammar::option_multihash and turn it into a regular hash from key to option
+    o subcommand vs. command consistency
+  o Implement ObjectStruct#key! and ObjectStruct#value! (?)
+  o Allow command_alias == nil to suppress the method
+  o Raise on non-existing names/keys. Only return nil for declared names/keys that are not present
+  o Use hash_tree
+  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 Add a ShellOpts.option method:
+      file = ShellOpts.option("--file")
+    This will only work for options on the outermost level... maybe:
+      file = ShellOpts.option("load! --file")
   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
@@ -11,7 +40,7 @@ TODO
   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

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,208 +2,148 @@ require "shellopts/version"
 
 require 'shellopts/compiler.rb'
 require 'shellopts/parser.rb'
+require 'shellopts/generator.rb'
+require 'shellopts/option_struct.rb'
+require 'shellopts/messenger.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}
+# Name of program. Defined as the basename of the program file
+PROGRAM = File.basename($PROGRAM_NAME)
+
+# ShellOpts main Module
+#
+# This module contains methods to process command line options and arguments.
+# ShellOpts keeps a reference in ShellOpts.shellopts to the result of the last
+# command that was processed through its interface and use it as the implicit
+# object of many of its methods. This matches the typical use case where only
+# one command line is ever processed and makes it possible to create class
+# methods that knows about the command like #error and #fail
+#
+# For example; the following process and convert a command line into a struct
+# representation and also sets ShellOpts.shellopts object so that the #error
+# method can print a relevant usage string:
+#
+#   USAGE = "a,all f,file=FILE -- ARG1 ARG2"
+#   opts, args = ShellOpts.as_struct(USAGE, ARGV)
+#   File.exist?(opts.file) or error "Can't find #{opts.file}"
+#
+# The command line is processed through one of the methods #process, #as_array,
+# #as_hash, or #as_struct that returns a [data, args] tuple. The data type
+# depends on the method: #process yields a Idr object that internally serves as
+# the base for the #as_array and #as_hash and #as_struct that converts it into
+# an Array, Hash, or ShellOpts::OptionStruct object. For example:
+#
+#   USAGE = "..."
+#   ShellOpts.process(USAGE, ARGV)
+#   program, args = ShellOpts.as_program(USAGE, ARGV)
+#   array, args = ShellOpts.as_array(USAGE, ARGV)
+#   hash, args = ShellOpts.as_hash(USAGE, ARGV)
+#   struct, args = ShellOpts.as_struct(USAGE, ARGV)
 #
-# ShellOpts inject the constant PROGRAM into the global scope. It contains the 
+# +args+ is a ShellOpts::Argv object containing the the remaning command line
+# arguments. Argv is derived from Array
+#
+# ShellOpts can raise the exception CompilerError is there is an error in the
+# USAGE string. If there is an error in the user supplied command line, #error
+# is called instead and the program terminates with exit code 1. ShellOpts
+# raises ConversionError is there is a name collision when converting to the
+# hash or struct representations. Note that CompilerError and ConversionError
+# are caused by misuse of the library and the problem should be corrected by
+# the developer
+#
+# ShellOpts injects the constant PROGRAM into the global scope. It contains the 
 # name of the program
 #
 module ShellOpts
-  # 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
-  #
-  # If called with a block, the block is called with name and value of each
-  # option or command and #process returns a list of remaining command line
-  # arguments. If called without a block a ShellOpts::ShellOpts object is
-  # returned
-  # 
-  # The value of an option is its argument, the value of a command is an array
-  # of name/value pairs of options and subcommands. Option values are converted
-  # to the target type (String, Integer, Float) if specified
-  #
-  # Example
-  #
-  #   # Define options
-  #   USAGE = 'a,all g,global +v,verbose h,help save! snapshot f,file=FILE h,help'
-  #
-  #   # Define defaults
-  #   all = false
-  #   global = false
-  #   verbose = 0
-  #   save = false
-  #   snapshot = false
-  #   file = nil
-  #
-  #   # Process options
-  #   argv = ShellOpts.process(USAGE, ARGV) do |name, value|
-  #     case name
-  #       when '-a', '--all'; all = true
-  #       when '-g', '--global'; global = value
-  #       when '-v', '--verbose'; verbose += 1
-  #       when '-h', '--help'; print_help(); exit(0)
-  #       when 'save'
-  #         save = true
-  #         value.each do |name, value|
-  #           case name
-  #             when '--snapshot'; snapshot = true
-  #             when '-f', '--file'; file = value
-  #             when '-h', '--help'; print_save_help(); exit(0)
-  #           end
-  #         end
-  #     else
-  #       raise "Not a user error. The developer forgot or misspelled an option"
-  #     end
-  #   end
-  #
-  #   # Process remaining arguments
-  #   argv.each { |arg| ... }
-  #
-  # If an error is encountered while compiling the usage string, a
-  # +ShellOpts::Compiler+ exception is raised. If the error happens while
-  # parsing the command line arguments, the program prints an error message and
-  # exits with status 1. Failed assertions raise a +ShellOpts::InternalError+
-  # exception
-  #
-  # Note that you can't process more than one command line at a time because
-  # #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:
-  #
-  #   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: PROGRAM, &block)
-    if !block_given?
-      ShellOpts.new(usage, argv, program_name: program_name)
-    else
-      @shellopts.nil? or raise InternalError, "ShellOpts class variable already initialized"
-      @shellopts = ShellOpts.new(usage, argv, program_name: program_name)
-      @shellopts.each(&block)
-      @shellopts.args
+  # Base class for ShellOpts exceptions
+  class Error < RuntimeError; end
+
+  # Raised when a syntax error is detected in the usage string
+  class CompilerError < Error
+    def initialize(start, message)
+      super(message)
+      set_backtrace(caller(start))
     end
   end
 
-  # Reset the hidden +ShellOpts::ShellOpts+ class variable so that you can process
-  # another command line
-  def self.reset()
-    @shellopts = nil
-  end
+  # Raised when an error is detected during conversion from the Idr to array,
+  # hash, or struct
+  class ConversionError < Error; 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)
-  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)
-  end
+  # Raised when an internal error is detected
+  class InternalError < Error; end
 
-  # 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)
-    program = @shellopts&.program_name || PROGRAM
-    emit_and_exit(program, nil, *msgs)
-  end
+  # The current compilation object. It is set by #process
+  def self.shellopts() @shellopts end
 
-  # The compilation object
-  class ShellOpts
-    # Name of program
-    attr_reader :program_name
-
-    # Usage string. Shorthand for +grammar.usage+
-    def usage() @grammar.usage end
-
-    # The grammar compiled from the usage string. If #ast is defined, it's
-    # equal to ast.grammar
-    attr_reader :grammar
-
-    # The AST resulting from parsing the command line arguments
-    attr_reader :ast
-
-    # List of remaining non-option command line arguments. Shorthand for ast.arguments
-    def args() @ast.arguments end
-
-    # Compile a usage string into a grammar and use that to parse command line
-    # arguments
-    #
-    # +usage+ is the usage string, and +argv+ the command line (typically the
-    # global ARGV array). +program_name+ is the name of the program and is
-    # used in error messages. It defaults to the basename of the program
-    #
-    # Errors in the usage string raise a CompilerError exception. Errors in the
-    # argv arguments terminates the program with an error message
-    def initialize(usage, argv, program_name: File.basename($0))
-      @program_name = program_name
-      begin
-        @grammar = Grammar.compile(program_name, usage)
-        @ast = Ast.parse(@grammar, argv)
-      rescue Grammar::Compiler::Error => ex
-        raise CompilerError.new(5, ex.message)
-      rescue Ast::Parser::Error => ex
-        error(ex.message)
-      end
-    end
+  # Process command line and set and return the shellopts compile object
+  def self.process(usage, argv, name: self.name, message: nil)
+    @shellopts.nil? or reset
+    messenger = message && Messenger.new(name, message, format: :custom)
+    @shellopts = ShellOpts.new(usage, argv, name: name, messenger: messenger)
+  end
 
-    # Unroll the AST into a nested array
-    def to_a
-      @ast.values
-    end
+  # Return the internal data representation of the command line (Idr::Program).
+  # Note that #as_program that the remaning arguments are accessible through
+  # the returned object
+  def self.as_program(usage, argv, name: self.name, message: nil) 
+    process(usage, argv, name: name, message: message)
+    [shellopts.idr, shellopts.args]
+  end
 
-    # Iterate the result as name/value pairs. See {ShellOpts.process} for a
-    # detailed description
-    def each(&block)
-      if block_given?
-        to_a.each { |*args| yield(*args) }
-      else
-        to_a # FIXME: Iterator
-      end
-    end
+  # Process command line, set current shellopts object, and return a [array, argv]
+  # tuple. Returns the representation of the current object if not given any
+  # arguments
+  def self.as_array(usage, argv, name: self.name, message: nil)
+    process(usage, argv, name: name, message: message)
+    [shellopts.to_a, shellopts.args]
+  end
 
-    # Print error message and usage string and exit with status 1. This method
-    # should be called in response to user-errors (eg. specifying an illegal
-    # option)
-    def error(*msgs)
-      ::ShellOpts.emit_and_exit(program_name, usage, msgs)
-    end
+  # Process command line, set current shellopts object, and return a [hash, argv]
+  # tuple. Returns the representation of the current object if not given any
+  # arguments
+  def self.as_hash(usage, argv, name: self.name, message: nil, use: ShellOpts::DEFAULT_USE, aliases: {})
+    process(usage, argv, name: name, message: message)
+    [shellopts.to_hash(use: use, aliases: aliases), shellopts.args]
+  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)
-    end
+  # Process command line, set current shellopts object, and return a [struct, argv]
+  # tuple. Returns the representation of the current object if not given any
+  # arguments
+  def self.as_struct(usage, argv, name: self.name, message: nil, use: ShellOpts::DEFAULT_USE, aliases: {})
+    process(usage, argv, name: name, message: message)
+    [shellopts.to_struct(use: use, aliases: aliases), shellopts.args]
   end
 
-  # Base class for ShellOpts exceptions
-  class Error < RuntimeError; end
+  # Process command line, set current shellopts object, and then iterate
+  # options and commands as an array. Returns an enumerator to the array
+  # representation of the current shellopts object if not given a block
+  # argument
+  def self.each(usage = nil, argv = nil, name: self.name, message: nil, &block)
+    process(usage, argv, name: name, message: message)
+    shellopts.each(&block)
+  end
 
-  # Raised when an error is detected in the usage string
-  class CompilerError < Error
-    def initialize(start, message)
-      super(message)
-      set_backtrace(caller(start))
-    end
+  # Print error message and usage string and exit with status 1. This method
+  # should be called in response to user-errors (eg. specifying an illegal
+  # option)
+  def self.error(*msgs)
+    raise "Oops" if shellopts.nil?
+    shellopts.error(*msgs)
   end
 
-  # Raised when an internal error is detected
-  class InternalError < Error; end
+  # Print error message and exit with status 1. This method should not be
+  # called in response to system errors (eg. disk full)
+  def self.fail(*msgs)
+    raise "Oops" if shellopts.nil?
+    shellopts.fail(*msgs)
+  end
 
 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
+  # Reset state variables
+  def self.reset()
+    @shellopts = nil
   end
-end
 
-PROGRAM = File.basename($PROGRAM_NAME)
+  @shellopts = nil
+end