shellopts 2.0.0.pre.1 → 2.0.0.pre.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e60db3cf5de50dcd106cb0fca007d064e18354278a65207bb167bf8aa63d3433
-  data.tar.gz: 85b0108262357d6e5654e725ab12293f51fd2579beb13fa0d910be2200c32310
+  metadata.gz: b967bc79076cae64e2c68c3ef559568a4324d94f7d87800937b746e09755fcfe
+  data.tar.gz: 14c6a5866c6b33da7f7a27f050de46d03b7936842c366fb7b32121324f17d7b0
 SHA512:
-  metadata.gz: 375fe97651622560d786b288217e1a8581d12bbc497dee55b36848597d9410d393a127e86088cfe4ac8f949270d9f6797d6f135f65492f15bb9d4a84bff1ffbc
-  data.tar.gz: c69a813e4672d87c6a4da69e0e8086d8acfe54c8506cda64ce6dc36dbc12669cc79c29ffd480c6871937d87491139f4e7448fd35a6d6a7d333451addd6c634a6
+  metadata.gz: de339ab12a1ef41f75cbb386a6778adc0dca989f64e9180780c1e00276303824dacca681ccba287f746e0bf7b436b717384be48feb02b4b9faf4be3852c533a5
+  data.tar.gz: a4b286f8297d56afc672a8e9f21119580496c820a8377a419a1aca1905a08e67a5763ed1aa14678137a9c739f120d673a1227d7a18233b43a482e8c43c603d92

data/.ruby-version

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

data/TODO

@@ -1,5 +1,10 @@
 
 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 '--'
@@ -40,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)
@@ -40,6 +39,9 @@ PROGRAM = File.basename($PROGRAM_NAME)
 #   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
@@ -51,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
@@ -73,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

@@ -0,0 +1,48 @@
+
+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
+  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
+    def extract(count_or_range, message = nil) 
+      if count_or_range.is_a?(Range)
+        range = count_or_range
+        range.min <= self.size or inoa(message)
+        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)
+      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)
+      end
+    end
+
+    # 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)
+      count_or_range === self.size or inoa(message)
+      extract(count_or_range) # Can't fail
+    end
+
+  private
+    def inoa(message = nil) 
+      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