shellopts 2.0.0.pre.4 → 2.0.0.pre.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 188e8a420eb3e7ead116f7daffaff32761f12be4efa9d8aa583cfb8050ee4a8b
-  data.tar.gz: 474ae6c949005b53201a7d62a03b53d6f57b263746c2bfeac681a93fb05d880e
+  metadata.gz: c7ac01e4c6feb1897f74056a36c74db0cf78802d13437908aa18631ead7c97c5
+  data.tar.gz: 5443ff421ceb38fcf07aaf87ae7b3740fd804679ccdec377fb195c688c50b57b
 SHA512:
-  metadata.gz: 2734bcdec0f1d3b68a26675eee2dd172b776be45b333917e74f7935912410bbc620ab152610820392b73ffe061e8e38d8c6cb8698faf94387655337de4d38d26
-  data.tar.gz: 7dd0c8dea7d12c259212b72551a769a11cda450df81b17f370cbc242ef5fbee28f2b0ecc739e9b2d4307ee65505e3bc939ebe433797d52b708b30f20a287b454
+  metadata.gz: 0d8180a2acc6dac8e234567db9409cd9d01cebe8d4551f6cfa24488ce5d1fb848ec8b42b21d40e7d8f6990bf61e4dc8d482370e9cb4ceb409e3f18fdb70a877c
+  data.tar.gz: f07d22ab7976d5efa317356fc796f8bbe20b8c6a8ee609eb24106f60e8e56d9874181dcab4e873268b1aea5a1aa27ffd1253bb10499052edd995894c6eec9d88

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/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,64 @@ 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
+
   # 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 +121,122 @@ 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)
   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)
+  # 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. 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)
+  # 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. 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)
+    [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. 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)
+    [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
-  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)
     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

@@ -33,28 +33,16 @@ module ShellOpts
       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
     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

data/lib/shellopts/generator.rb

@@ -3,9 +3,9 @@ require 'shellopts/idr.rb'
 
 module ShellOpts
   module Idr
-    # Generates an Idr::Program from an Ast::Program object
-    def self.generate(ast, messenger)
-      Idr::Program.new(ast, messenger)
+    # Generates an Idr::Program from a ShellOpts object
+    def self.generate(shellopts)
+      Idr::Program.new(shellopts)
     end
   end
 end