shellopts 0.9.6 → 2.0.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 943b9d0c44ba0291937be24cbc79d0155dfc22ac788c69a76639850d78af3303
-  data.tar.gz: f38e038f613c577b06e9d2facc6096b39eb18f28266ba8c58a8280adcf75fe47
+  metadata.gz: 34b7edfee1092f53f5c5c75d678c69b2fe753ecbcd6caa4876c923dd56dfbf68
+  data.tar.gz: f7dfa30cd0ec280eb3f36e6a4779e01eeea1d14fd904fe2b42d1b7d7d9e40b63
 SHA512:
-  metadata.gz: 42cc6102c0c66dcffda0b03f9c584c32abc0e62a65dbe79e1389753b74af11f189e27a456e79fb2cb082595622ddbce0840dd22419204e276a48134ac8afd610
-  data.tar.gz: 6a3b2e35718a5ee1f52e5d56a50ea067da90fef35a4ac3322738e24d5ba80f4aba4ac4a692caace4bb094ccfb84432e9211fef2b15dfef2e194a95569ca80686
+  metadata.gz: e3d9b271783e3f9c5b42aa2511c36a78814f239e848829fd347ad74fc5289b769da7264defe8af985bce500485d7e9480a240b3f9e261d70943b1ebc69cd671d
+  data.tar.gz: 3f91000787d5fa80570d378604a7cc28ef991585030bd1ce327b88e67dca3e4e647428d48863fc302165bcece5130cc2f140efb05fa478c2ff9443a7197a8b4e

data/README.md

@@ -7,11 +7,10 @@ line
 
 ## Usage
 
-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:
-
+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
  
@@ -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
 ```
@@ -196,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
@@ -275,20 +274,24 @@ class methods on `ShellOpts`. They can also be included in the global scope by
 #### 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:
+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 = %(
+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
@@ -316,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
@@ -375,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/lib/shellopts.rb

@@ -2,227 +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
-  # Return the hidden +ShellOpts::ShellOpts+ object (see .process)
-  def self.shellopts()
-    @shellopts
-  end
+  # Base class for ShellOpts exceptions
+  class Error < RuntimeError; 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
-  #
-  # 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 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)
-    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
+  # 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
-    @usage = 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)
-  #
-  # 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_string = usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
-    emit_and_exit(program, usage_string, *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
-
-    # 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
-    # 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