shellopts 1.0.0 → 2.0.0.pre.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cc3c3ef5b7b13876949b290b9d247c41778eaa38ea01432d5abac47b663478a
-  data.tar.gz: bc2c44f163f81d8b51545679e8f8280ac889fbb1f96a7898e5a65fa63d337d4a
+  metadata.gz: c7ac01e4c6feb1897f74056a36c74db0cf78802d13437908aa18631ead7c97c5
+  data.tar.gz: 5443ff421ceb38fcf07aaf87ae7b3740fd804679ccdec377fb195c688c50b57b
 SHA512:
-  metadata.gz: d3c501335a899e4b14280cbb14b7f9e8a0d9ef28715760394d8f13ea837d0a5d3d9b91b9d07dcb42a747753e97a10c157ae5c5b20b95804b1746e0ebad7d88c9
-  data.tar.gz: 387c888158bbbebe127c6efde55c7bbb14436b7dcb8227cac38e2c9dac85e9a3d956c062e04b86101e28fa0bde4977fefadad4d1a643dd48d9218e5c04558ad2
+  metadata.gz: 0d8180a2acc6dac8e234567db9409cd9d01cebe8d4551f6cfa24488ce5d1fb848ec8b42b21d40e7d8f6990bf61e4dc8d482370e9cb4ceb409e3f18fdb70a877c
+  data.tar.gz: f07d22ab7976d5efa317356fc796f8bbe20b8c6a8ee609eb24106f60e8e56d9874181dcab4e873268b1aea5a1aa27ffd1253bb10499052edd995894c6eec9d88

data/.ruby-version

@@ -1 +1 @@
-ruby-2.5.1
+ruby-2.6.6

data/README.md

@@ -378,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,23 @@
 
 TODO
+  o Rethink #error and #fail <- The use-case is one-file ruby scripts. Idea: Only use in main exe file?
+  o Create exceptions: UserError SystemFail and allow them to be used instead of #error and #fail
+  ? 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
@@ -9,7 +27,10 @@ TODO
     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
@@ -24,6 +45,7 @@ TODO
   o Long version usage strings (major release)
   o Doc: Example of processing of sub-commands and sub-sub-commands
 
+  + Add a 'mandatory' argument to #subcommand
   + More tests
   + More doc
   + Implement value-name-before-flags rule

data/lib/shellopts.rb

@@ -2,231 +2,241 @@ require "shellopts/version"
 
 require 'shellopts/compiler.rb'
 require 'shellopts/parser.rb'
-require 'shellopts/utils.rb'
+require 'shellopts/generator.rb'
+require 'shellopts/option_struct.rb'
+require 'shellopts/main.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 spec 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)
+#
+# +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 inject the constant PROGRAM into the global scope. It contains the 
+# ShellOpts injects the constant PROGRAM into the global scope. It contains the 
 # name of the program
 #
+# INCLUDING SHELLOPTS
+# 
+# ShellOpts can optionally be included in your shell application main file but
+# it is not supposed to be included anywhere else
+#
+# Some behind the scenes magic happen if you include the ShellOpts module in your
+# main exe file
+#
 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
-  #
-  # 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
-    end
+  def self.default_name()
+    @default_name || defined?(PROGRAM) ? PROGRAM : File.basename($0)
   end
 
-  # Reset the hidden +ShellOpts::ShellOpts+ class variable so that you can process
-  # 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_string = usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
-    emit_and_exit(program, @usage.nil?, usage_string, *msgs)
-  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, false, nil, *msgs)
-  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
+  def self.default_name=(name)
+    @default_name = name
+  end
 
-    # Unroll the AST into a nested array
-    def to_a
-      @ast.values
-    end
+  def self.default_usage()
+    @default_usage || defined?(USAGE) ? USAGE : nil
+  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
+  def self.default_usage=(usage)
+    @default_usage = usage
+  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, true, usage, msgs)
-    end
+  def self.default_key_type()
+    @default_key_type || ::ShellOpts::DEFAULT_KEY_TYPE
+  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, false, nil, msgs)
-    end
+  def self.default_key_type=(type)
+    @default_key_type = type
   end
 
   # Base class for ShellOpts exceptions
   class Error < RuntimeError; end
 
-  # Raised when an error is detected in the usage string
+  # Raised when a syntax error is detected in the spec string
   class CompilerError < Error
-    def initialize(start, message)
-      super(message)
+    def initialize(start, usage)
+      super(usage)
       set_backtrace(caller(start))
     end
   end
 
+  # Raised when an error is detected in the command line
+  class ParserError < Error; end
+
+  # Raised when the command line error is caused by the user. It is raised by
+  # the parser but can also be used by the application if the command line
+  # fails a semantic check
+  class UserError < ParserError; end
+
+  # Raised when the error is caused by a failed assumption about the system. It
+  # is not raised by the ShellOpts library as it only concerns itself with
+  # command line syntax but can be used by the application to report a failure
+  # through ShellOpts#fail method when the ShellOpts module is included
+  class SystemFail < Error; end
+
+  # Raised when an error is detected during conversion from the Idr to array,
+  # hash, or struct
+  class ConversionError < Error; end
+
   # Raised when an internal error is detected
   class InternalError < Error; end
 
-private
-  @shellopts = nil
+  # The current compilation object. It is set by #process
+  def self.shellopts() @shellopts end
 
-  def self.emit_and_exit(program, use_usage, usage, *msgs)
-    $stderr.puts "#{program}: #{msgs.join}"
-    if use_usage
-      $stderr.puts "Usage: #{program} #{usage}" if usage
-    else
-      $stderr.puts usage if usage
+  # Name of program
+  def program_name() shellopts!.name end
+  def program_name=(name) shellopts!.name = name end
+
+  # Usage string
+  def usage() shellopts!.spec end
+  def usage=(spec) shellopts!.spec = spec end
+
+  # Process command line, set current shellopts object, and return it.
+  # Remaining arguments from the command line can be accessed through
+  # +shellopts.args+
+  def self.process(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage) 
+    @shellopts.nil? or reset
+    @shellopts = ShellOpts.new(spec, argv, name: name, usage: usage)
+  end
+
+  # Process command line, set current shellopts object, and return a
+  # [Idr::Program, argv] tuple. Automatically includes the ShellOpts module
+  # if called from the main Ruby object (ie. your executable)
+  def self.as_program(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage) 
+    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
+    process(spec, argv, name: name, usage: usage)
+    [shellopts.idr, shellopts.args]
+  end
+
+  # Process command line, set current shellopts object, and return a [array,
+  # argv] tuple. Automatically includes the ShellOpts module if called from the
+  # main Ruby object (ie. your executable)
+  def self.as_array(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage)
+    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
+    process(spec, argv, name: name, usage: usage)
+    [shellopts.to_a, shellopts.args]
+  end
+
+  # Process command line, set current shellopts object, and return a [hash,
+  # argv] tuple. Automatically includes the ShellOpts module if called from the
+  # main Ruby object (ie. your executable)
+  def self.as_hash(
+      spec, argv, 
+      name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, 
+      key_type: ::ShellOpts.default_key_type, 
+      aliases: {})
+    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
+    process(spec, argv, name: name, usage: usage)
+    [shellopts.to_h(key_type: key_type, aliases: aliases), shellopts.args]
+  end
+
+  # Process command line, set current shellopts object, and return a [struct,
+  # argv] tuple. Automatically includes the ShellOpts module if called from the
+  # main Ruby object (ie. your executable)
+  def self.as_struct(
+      spec, argv, 
+      name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, 
+      aliases: {})
+    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
+    process(spec, argv, name: name, usage: usage)
+    [shellopts.to_struct(aliases: aliases), shellopts.args]
+  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. Automatically includes the ShellOpts module if called from the
+  # main Ruby object (ie. your executable)
+  def self.each(spec = nil, argv = nil, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, &block)
+    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
+    process(spec, argv, name: name, usage: usage)
+    shellopts.each(&block)
+  end
+
+  # Print error usage and spec 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, exit: true)
+    shellopts!.error(msgs, exit: exit)
+  end
+
+  # Print error usage and exit with status 1. This method should not be
+  # called in response to system errors (eg. disk full)
+  def self.fail(*msgs, exit: true)
+    shellopts!.fail(*msgs, exit: exit)
+  end
+
+  def self.included(base)
+    # base.equal?(Object) is only true when included in main (we hope)
+    if !@is_included_in_main && base.equal?(Object) 
+      @is_included_in_main = true
+      at_exit do
+        case $!
+          when ShellOpts::UserError
+            ::ShellOpts.error($!.message, exit: false)
+            exit!(1)
+          when ShellOpts::SystemFail
+            ::ShellOpts.fail($!.message)
+            exit!(1)
+        end
+      end
     end
-    exit 1
+    super
+  end
+
+private
+  # Default default key type
+  DEFAULT_KEY_TYPE = :name
+
+  # Reset state variables
+  def self.reset()
+    @shellopts = nil
   end
+
+  # (shorthand) Raise an InternalError if shellopts is nil. Return shellopts
+  def self.shellopts!
+    ::ShellOpts.shellopts or raise UserError, "No ShellOpts.shellopts object"
+  end
+
+  @shellopts = nil
+  @is_included_in_main = false
 end
 
-PROGRAM = File.basename($PROGRAM_NAME)