shellopts 2.0.0.pre.4 → 2.0.0.pre.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 188e8a420eb3e7ead116f7daffaff32761f12be4efa9d8aa583cfb8050ee4a8b
-  data.tar.gz: 474ae6c949005b53201a7d62a03b53d6f57b263746c2bfeac681a93fb05d880e
+  metadata.gz: 8ac8ce6815e283630cb66195b0069a0d1772d8234dd580833e49b38cb0717fe8
+  data.tar.gz: e6fc6e96d47db9078edad643ce9ee4fabdeaf3450a5ab61fd330b701bfadf244
 SHA512:
-  metadata.gz: 2734bcdec0f1d3b68a26675eee2dd172b776be45b333917e74f7935912410bbc620ab152610820392b73ffe061e8e38d8c6cb8698faf94387655337de4d38d26
-  data.tar.gz: 7dd0c8dea7d12c259212b72551a769a11cda450df81b17f370cbc242ef5fbee28f2b0ecc739e9b2d4307ee65505e3bc939ebe433797d52b708b30f20a287b454
+  metadata.gz: f77988efda7870d95b7693125e0e4b9753dbbe637cfc126d92559654bd171f17f37698ac7588ce9d3fc0521ba00156b862e763f1ae95190d77d89cc5e500bf5a
+  data.tar.gz: 98d96929cd577649796e5f699e3c748f7ef3c72cb8ad3dd6036d2e656bae15229a414263a3701a4a027daacb869de2ceb52b1d3095fd1715c064d6befbaedbd0

data/.ruby-version

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

data/TODO

@@ -1,6 +1,8 @@
 
 TODO
-  o Remove ! from OptionStruct#subcommand return value. We know we're
+  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
@@ -43,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/main.rb

@@ -0,0 +1 @@
+hej

data/lib/shellopts.rb

@@ -4,11 +4,10 @@ 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'
+require 'shellopts/main.rb'
 
 # Name of program. Defined as the basename of the program file
-PROGRAM = File.basename($PROGRAM_NAME)
+#PROGRAM = File.basename($PROGRAM_NAME)
 
 # ShellOpts main Module
 #
@@ -21,7 +20,7 @@ PROGRAM = File.basename($PROGRAM_NAME)
 #
 # 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:
+# method can print a relevant spec string:
 #
 #   USAGE = "a,all f,file=FILE -- ARG1 ARG2"
 #   opts, args = ShellOpts.as_struct(USAGE, ARGV)
@@ -54,18 +53,68 @@ PROGRAM = File.basename($PROGRAM_NAME)
 # 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
+  def self.default_name()
+    @default_name || defined?(PROGRAM) ? PROGRAM : File.basename($0)
+  end
+
+  def self.default_name=(name)
+    @default_name = name
+  end
+
+  def self.default_usage()
+    @default_usage || defined?(USAGE) ? USAGE : nil
+  end
+
+  def self.default_usage=(usage)
+    @default_usage = usage
+  end
+
+  def self.default_key_type()
+    @default_key_type || ::ShellOpts::DEFAULT_KEY_TYPE
+  end
+
+  def self.default_key_type=(type)
+    @default_key_type = type
+  end
+
+  # Result of the last as_* command
+  def self.opts() @opts end
+  def self.args() @args end
+
   # Base class for ShellOpts exceptions
   class Error < RuntimeError; end
 
-  # Raised when a syntax 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
@@ -76,74 +125,133 @@ module ShellOpts
   # The current compilation object. It is set by #process
   def self.shellopts() @shellopts end
 
-  # Process command line and set and return the shellopts compile object
-  def self.process(usage, argv, name: self.name, message: nil)
+  # 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
-    messenger = message && Messenger.new(name, message, format: :custom)
-    @shellopts = ShellOpts.new(usage, argv, name: name, messenger: messenger)
+    @shellopts = ShellOpts.new(spec, argv, name: name, usage: usage)
+    @shellopts.process
   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]
+  # 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)
+    @opts = shellopts.idr
+    @args = shellopts.args
+    [@opts, @args]
   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]
+  # 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)
+    @opts = shellopts.to_a
+    @args = shellopts.args
+    [@opts, @args]
   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]
+  # 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)
+    @opts = shellopts.to_h(key_type: key_type, aliases: aliases)
+    @args = shellopts.args
+    [@opts, @args]
   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]
+  # 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)
+    @opts = shellopts.to_struct(aliases: aliases)
+    @args = shellopts.args
+    [@opts, @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
-  def self.each(usage = nil, argv = nil, name: self.name, message: nil, &block)
-    process(usage, argv, name: name, message: message)
+  # 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)
+    @opts = shellopts.to_a
+    @args = shellopts.args
     shellopts.each(&block)
   end
 
-  # Print error message and usage string and exit with status 1. This method
+  # 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)
-    raise "Oops" if shellopts.nil?
-    shellopts.error(*msgs)
+  def self.error(*msgs, exit: true)
+    shellopts!.error(msgs, exit: exit)
   end
 
-  # Print error message and exit with status 1. This method should not be
+  # 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)
-    raise "Oops" if shellopts.nil?
-    shellopts.fail(*msgs)
+  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
+    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
+

data/lib/shellopts/args.rb

@@ -2,21 +2,23 @@
 module ShellOpts
   # Specialization of Array for arguments lists. Args extends Array with a
   # #extract and an #expect method to extract elements from the array. The
-  # methods call #error() in response to errors
+  # methods raise a ShellOpts::UserError exception in case of errors
   class Args < Array
     def initialize(shellopts, *args)
       @shellopts = shellopts
       super(*args)
     end
 
-    # Remove and return elements from beginning of the array. If
-    # +count_or_range+ is a number, that number of elements will be returned.
-    # If the count is one, a simple value is returned instead of an array.  If
-    # the count is negative, the elements will be removed from the end of the
-    # array. If +count_or_range+ is a range, the number of elements returned
-    # will be in that range. The range can't contain negative numbers #expect
-    # calls #error() if there's is not enough elements in the array to satisfy
-    # the request
+    # Remove and return elements from beginning of the array
+    #
+    # If +count_or_range+ is a number, that number of elements will be
+    # returned.  If the count is one, a simple value is returned instead of an
+    # array.  If the count is negative, the elements will be removed from the
+    # end of the array. If +count_or_range+ is a range, the number of elements
+    # returned will be in that range. The range can't contain negative numbers 
+    #
+    # #extract raise a ShellOpts::UserError exception if there's is not enough
+    # elements in the array to satisfy the request
     def extract(count_or_range, message = nil) 
       if count_or_range.is_a?(Range)
         range = count_or_range
@@ -24,37 +26,29 @@ module ShellOpts
         n_extract = [self.size, range.max].min
         n_extend = range.max > self.size ? range.max - self.size : 0
         r = self.shift(n_extract) + Array.new(n_extend)
+        range.max <= 1 ? r.first : r
       else
         count = count_or_range
         self.size >= count.abs or inoa(message)
         start = count >= 0 ? 0 : size + count
         r = slice!(start, count.abs)
-        r.size == 0 ? nil : (r.size == 1 ? r.first : r)
+        r.size <= 0 ? nil : (r.size == 1 ? r.first : r)
       end
     end
 
-    # Remove and returns elements from the array. If +count_or_range+ is a
-    # number, that number of elements will be returned. If the count is one, a
-    # simple value is returned instead of an array. If +count_or_range+ is a
-    # range, the number of elements returned will be in that range. The range
-    # can't contain negative numbers.  #expect calls #error() if the array has
-    # remaning elemens after removal satisfy the request
+    # As #extract except it doesn't allow negative counts and that the array is
+    # expect to be emptied by the operation
+    #
+    # #expect raise a ShellOpts::UserError exception if the array is not emptied 
+    # by the operation
     def expect(count_or_range, message = nil)
-      if count_or_range.is_a?(Range)
-        range = count_or_range
-        range.cover?(self.size) or inoa(message)
-        self.shift(self.size)
-      else
-        count = count_or_range
-        count == self.size or inoa(message)
-        r = self.shift(count)
-        r.size == 0 ? nil : (r.size == 1 ? r.first : r)
-      end
+      count_or_range === self.size or inoa(message)
+      extract(count_or_range) # Can't fail
     end
 
   private
     def inoa(message = nil) 
-      @shellopts.messenger.error(message || "Illegal number of arguments") 
+      raise ShellOpts::UserError, message || "Illegal number of arguments"
     end
   end
 end

data/lib/shellopts/ast/command.rb

@@ -7,17 +7,17 @@ module ShellOpts
 
       # Optional sub-command (Ast::Command). Initially nil but assigned by the
       # parser
-      attr_accessor :command 
+      attr_accessor :subcommand 
 
       def initialize(grammar, name)
         super(grammar, name)
         @options = []
-        @command = nil
+        @subcommand = nil
       end
 
       # Array of option or command tuples
       def values
-        (options + (Array(command || []))).map { |node| node.to_tuple }
+        (options + (Array(subcommand || []))).map { |node| node.to_tuple }
       end
 
       # :nocov:
@@ -26,10 +26,10 @@ module ShellOpts
           yield if block_given?
           puts "options:"
           indent { options.each { |opt| opt.dump } }
-          print "command:"
-          if command
+          print "subcommand:"
+          if subcommand
             puts
-            indent { command.dump }
+            indent { subcommand.dump }
           else
             puts "nil"
           end

data/lib/shellopts/compiler.rb

@@ -29,11 +29,11 @@ module ShellOpts
       def initialize(name, source)
         @name, @tokens = name, source.split(/\s+/).reject(&:empty?)
 
-        # @commands_by_path is an hash from command-path to Command or Program
+        # @subcommands_by_path is an hash from subcommand-path to Command or Program
         # object. The top level Program object has nil as its path.
-        # @commands_by_path is used to check for uniqueness of commands and to
-        # link sub-commands to their parents
-        @commands_by_path = {}
+        # @subcommands_by_path is used to check for uniqueness of subcommands and to
+        # link sub-subcommands to their parents
+        @subcommands_by_path = {}
       end
 
       def call
@@ -49,30 +49,26 @@ module ShellOpts
       # Returns the current token and advance to the next token
       def next_token() @tokens.shift end
 
-      def error(msg) # Just a shorthand. Unrelated to ShellOpts.error
-        raise Compiler::Error.new(msg)
-      end
-
       def compile_program
-        program = @commands_by_path[nil] = Grammar::Program.new(@name, compile_options)
+        program = @subcommands_by_path[nil] = Grammar::Program.new(@name, compile_options)
         while curr_token && curr_token != "--"
-          compile_command
+          compile_subcommand
         end
         program.args.concat(@tokens[1..-1]) if curr_token
         program
       end
 
-      def compile_command
+      def compile_subcommand
         path = curr_token[0..-2]
         ident_list = compile_ident_list(path, ".")
         parent_path = ident_list.size > 1 ? ident_list[0..-2].join(".") : nil
         name = ident_list[-1]
 
-        parent = @commands_by_path[parent_path] or
-            error "No such command: #{parent_path.inspect}"
-        !@commands_by_path.key?(path) or error "Duplicate command: #{path.inspect}"
+        parent = @subcommands_by_path[parent_path] or
+            raise Compiler::Error, "No such subcommand: #{parent_path.inspect}"
+        !@subcommands_by_path.key?(path) or raise Compiler::Error, "Duplicate subcommand: #{path.inspect}"
         next_token
-        @commands_by_path[path] = Grammar::Command.new(parent, name, compile_options)
+        @subcommands_by_path[path] = Grammar::Command.new(parent, name, compile_options)
       end
 
       def compile_options
@@ -81,7 +77,7 @@ module ShellOpts
           option_list << compile_option
         end
         dup = option_list.map(&:names).flatten.find_dup and 
-            error "Duplicate option name: #{dup.inspect}"
+            raise Compiler::Error, "Duplicate option name: #{dup.inspect}"
         option_list
       end
 
@@ -102,7 +98,7 @@ module ShellOpts
         long_names = []
         ident_list = compile_ident_list(names, ",")
         (dup = ident_list.find_dup).nil? or 
-            error "Duplicate identifier #{dup.inspect} in #{curr_token.inspect}"
+            raise Compiler::Error, "Duplicate identifier #{dup.inspect} in #{curr_token.inspect}"
         ident_list.each { |ident|
           if ident.size == 1
             short_names << "-#{ident}"
@@ -115,13 +111,15 @@ module ShellOpts
         Grammar::Option.new(short_names, long_names, flags, label)
       end
 
-      # Compile list of option names or a command path
+      # Compile list of option names or a subcommand path
       def compile_ident_list(ident_list_str, sep)
         ident_list_str.split(sep, -1).map { |str| 
-          !str.empty? or error "Empty identifier in #{curr_token.inspect}"
-          !str.start_with?("-") or error "Identifier can't start with '-' in #{curr_token.inspect}"
+          !str.empty? or 
+              raise Compiler::Error, "Empty identifier in #{curr_token.inspect}"
+          !str.start_with?("-") or 
+              raise Compiler::Error, "Identifier can't start with '-' in #{curr_token.inspect}"
           str !~ /([^\w\d#{sep}-])/ or 
-              error "Illegal character #{$1.inspect} in #{curr_token.inspect}"
+              raise Compiler::Error, "Illegal character #{$1.inspect} in #{curr_token.inspect}"
           str
         }
       end