shellopts 2.0.17 → 2.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebd7911e579af4ddddd064399e7b456b45cef80dc3c6589e404ba5e32811bd6c
-  data.tar.gz: ea555ad68d0d6c43bad39a4e195e6661f72e1e43b6d3dbe647f4c8ff13d7eea3
+  metadata.gz: 83e0ce72f27c72eec2087bee9296378fc0d84fc1124f830af27f21340cefffcc
+  data.tar.gz: 6c3b2363c1ca392b0950c792c48e353181f352ca22bfe16e7c42490248511b29
 SHA512:
-  metadata.gz: 453d3bd1e4354a56947623232f1fabcdc8d212a91d317ce16026c356c71c77ab53031e4e42d05242d0c04ce309ccd69fd75386d3d40705feac461f58d6a2c86b
-  data.tar.gz: 282655ab16154e1b50c25b6ddf8a07196a296f8a2bad4086cd78b8962a9003c22e1fb8dfbe2e339fc97973fef95b1cf9965a829bab23b2ad98f63df1aef8c009
+  metadata.gz: dcc6e2271a451f494e007c78e9054c49bbb6f65f0f0fcf5be07158488157782c8216fc0f6fce7e4c25dda6bf0e39ac8ae2096f733cb4af7c4b1360b28a978129
+  data.tar.gz: e1d60f792447e5884f2ad939fbf408d5c053ef413328e2e2a42a082e34e9672537d8d64916fbc136f11797ac2c87894c148939d4feac9cc43489d3c66faa538d

data/PROBLEMS

@@ -39,3 +39,14 @@ SPEC = %(
     mapping and grants are
 )
 
+###########################
+
+# If option is only defined on a subcommand, it doesn't flow before the subcommand. This should be legal:
+ 
+cmd -c sub
+
+# Only this is legal today
+
+cmd sub -c
+
+

data/TODO

@@ -1,3 +1,19 @@
+
+o Make opts[] point at the main object
+    opts[].subcommand is the direct subcommand of main
+o Make opts be the aggrated set of options in a subcommand
+    opts.subcommand is the concatenated path of subcommands
+o Make opts[:some_command] be the set of options for that subcommand (already done)
+o Sub-command options can overshadow options of outer commands but it is an
+  error to access them using opts. Use opts[] or opts[:some_command] instead
+
+o Add a default argument to extract:
+    def extract(range, *defaults)
+    end
+
+    extract(3..4, 'dbo')
+
+o More strict parsing of option and command lines
 o --option can't be escaped if on the start of a block line?
 o Use require_relative
 o In the following list is a command with a mandatory sub-command

data/lib/shellopts/grammar.rb

@@ -30,7 +30,7 @@ module ShellOpts
       def ancestors() parents.reverse end
 
       def inspect
-        "#{self.class}"
+        self.class.to_s
       end
 
     protected
@@ -72,7 +72,7 @@ module ShellOpts
       # Note that the analyzer fails with an an error if both --with-separator
       # and --with_separator are used because they would both map to
       # :with_separator
-      attr_reader :ident
+      attr_accessor :ident
 
       # Canonical name (String) of the object
       #
@@ -241,7 +241,7 @@ module ShellOpts
       def [](key)
         case key
           when String; lookup(key.split("."))
-          when Symbol; lookup(key.to_s.sub(".", "!.").split(".").map(&:to_sym))
+          when Symbol; lookup(key.to_s.gsub(".", "!.").split(".").map(&:to_sym))
           when Array; lookup(key)
         else
           nil

data/lib/shellopts/parser.rb

@@ -23,7 +23,7 @@ module ShellOpts
     end
 
     class Option
-      SHORT_NAME_RE = /[a-zA-Z0-9]/
+      SHORT_NAME_RE = /[a-zA-Z0-9?]/
       LONG_NAME_RE = /[a-zA-Z0-9][a-zA-Z0-9_-]*/
       NAME_RE = /(?:#{SHORT_NAME_RE}|#{LONG_NAME_RE})(?:,#{LONG_NAME_RE})*/
 
@@ -124,23 +124,18 @@ module ShellOpts
         super(nil, token)
       end
 
-      def add_version_option
-        option_token = Token.new(:option, 1, 1, "--version")
-        brief_token = Token.new(:brief, 1, 1, "Write version number and exit")
+      def inject_option(decl, brief, paragraph = nil, &block)
+        option_token = Token.new(:option, 1, 1, decl)
+        brief_token = Token.new(:brief, 1, 1, brief)
         group = OptionGroup.new(self, option_token)
         option = Option.parse(group, option_token)
         brief = Brief.parse(group, brief_token)
-      end
-
-      def add_help_options
-        option_token = Token.new(:option, 1, 1, "-h,help")
-        brief_token = Token.new(:brief, 1, 1, "Write help text and exit")
-        paragraph_token = Token.new(:text, 1, 1, 
-            "-h prints a brief help text, --help prints a longer man-style description of the command")
-        group = OptionGroup.new(self, option_token)
-        option = Option.parse(group, option_token)
-        brief = Brief.parse(group, brief_token)
-        paragraph = Paragraph.parse(group, paragraph_token)
+        paragraph ||= yield(option) if block_given?
+        if paragraph
+          paragraph_token = Token.new(:text, 1, 1, paragraph)
+          paragraph = Paragraph.parse(group, paragraph_token)
+        end
+        option
       end
     end
 

data/lib/shellopts/program.rb

@@ -62,53 +62,49 @@ module ShellOpts
       object
     end
 
-    # Return command or option object if present, otherwise nil. Returns a
-    # possibly empty array of option objects if the option is repeatable
+    # Returns the command or option object identified by the UID if present and
+    # otherwise nil. Returns a possibly empty array of option objects if the
+    # option is repeatable. Raise an ArgumentError if the key doesn't exists
     #
-    # The key is the name or identifier of the object or any any option
-    # alias. Eg.  :f, '-f', :file, or '--file' are all usable as option keys
-    # and :cmd!  or 'cmd' as command keys
+    # The +key+ is the symbolic UID of the object. Eg. :command.option or
+    # :command.subcommand!
     #
-    def [](key)
-      case object = __grammar__[key]
-        when ::ShellOpts::Grammar::Command
-          object.ident == __subcommand__!.__ident__ ? __subcommand__! : nil
-        when ::ShellOpts::Grammar::Option
-          if object.repeatable?
-            __option_hash__[object.ident] || []
+    def [](uid)
+      __grammar__.key?(uid) or ::Kernel.raise ::ArgumentError, "'#{uid}' is not a valid UID"
+      idents = uid.to_s.gsub(/\./, "!.").split(/\./).map(&:to_sym)
+      idents.inject(self) { |cmd, ident|
+        case ident.to_s
+          when /!$/
+            return nil if cmd.__subcommand__ != ident
+            cmd = cmd.__subcommand__!
           else
-            __option_hash__[object.ident]
-          end
-        else
-          ::Kernel.raise ::ArgumentError, "Unknown command or option: '#{key}'"
-      end
+            opt = cmd.__option_hash__[ident]
+            opt.nil? && cmd.__grammar__[ident].repeatable? ? [] : opt
+        end
+      }
     end
 
-    # Return true if the given command or option is present
-    def key?(key)
-      case object = __grammar__[key]
-        when ::ShellOpts::Grammar::Command
-          object.ident == __subcommand__
-        when ::ShellOpts::Grammar::Option
-          __option_hash__.key?(object.ident)
-        else
-          ::Kernel.raise ::ArgumentError, "Unknown command or option: '#{key}'"
-      end
-    end
-      
-    # Returns a hash of the given options if defined. Returns all options if no
-    # options are given
+    # Returns a hash from option ident to value
+    #
+    # The value depends on the option type: If it is not repeatable, the value
+    # is the argument or nil if not present (or allowed). If the option is
+    # repeatable and has an argument, the value is an array of the arguments,
+    # if it doesn't have an argument, the value is the number of occurrences
+    #
     def to_h(*keys)
       keys = ::Kernel::Array(keys).flatten
-      if keys.empty?
-        self.to_h(@__grammar__.options.map(&:ident))
-      else
-        keys.map { |key|
-          self.__send__("#{key}?".to_sym) ? [key, self.__send__(key)] : nil
-        }.compact.to_h
-      end
+      __option_values__.select { |key,_| keys.empty? || keys.include?(key) }
     end
 
+    # Like #to_h but present options without arguments have a true value
+    #
+    def to_h?(*keys)
+      keys = ::Kernel::Array(keys).flatten
+      keys = keys.empty? ? __option_values__.keys : keys
+      keys.filter_map { |key| __option_values__.key?(key) && [key, self.__send__(key)] }.to_h
+    end
+
+
     # Subcommand identifier or nil if not present. #subcommand is often used in
     # case statement to branch out to code that handles the given subcommand:
     #
@@ -148,7 +144,7 @@ module ShellOpts
     #
     def supercommand!() __supercommand__ end
 
-    # UID of command/program
+    # UID of command/program (String)
     def __uid__() @__grammar__.uid end
 
     # Identfier including the exclamation mark (Symbol)
@@ -309,6 +305,18 @@ module ShellOpts
 
   # The top-level command
   class Program < Command
+    # Accessors for standard options values that are not affected if the option
+    # is renamed
+    attr_accessor :__quiet__
+    attr_accessor :__verbose__
+    attr_accessor :__debug__
+
+    def initialize
+      super
+      @__quiet__ = false
+      @__verbose__ = 0
+      @__debug__ = false
+    end
   end
 
   # Option models an option as given by the user on the subcommand line.

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module ShellOpts
-  VERSION = "2.0.17"
+  VERSION = "2.0.20"
 end

data/lib/shellopts.rb

@@ -96,17 +96,20 @@ module ShellOpts
     # Automatically add a -h and a --help option if true
     attr_reader :help
 
-    # Version of client program. If not nil a --version option is added to the program
-    def version
-      return @version if @version
-      exe = caller.find { |line| line =~ /`<top \(required\)>'$/ }&.sub(/:.*/, "")
-      file = Dir.glob(File.dirname(exe) + "/../lib/*/version.rb").first
-      @version = IO.read(file).sub(/^.*VERSION\s*=\s*"(.*?)".*$/m, '\1') or
-          raise ArgumentError, "ShellOpts needs an explicit version"
-    end
+    # Version of client program. If not nil, a --version option is added to the program
+    attr_reader :version
+
+    # Automatically add a -q and a --quiet option if true
+    attr_reader :quiet
 
-    # Add message options (TODO)
-    attr_accessor :msgopts
+    # Automatically add a -v and a --verbose option if true
+    attr_reader :verbose
+
+    # Automatically add a --debug option if true
+    attr_reader :debug
+
+    # Version number (this is usually detected dynamically)
+    attr_reader :version_number
 
     # Floating options
     attr_accessor :float
@@ -122,12 +125,33 @@ module ShellOpts
     attr_reader :tokens
     alias_method :ast, :grammar
 
-    def initialize(name: nil, help: true, version: true, msgopts: false, float: true, exception: false)
+    def initialize(name: nil, 
+        # Options
+        help: true, 
+        version: true, 
+        quiet: nil,
+        verbose: nil,
+        debug: nil,
+
+        # Version number (usually detected)
+        version_number: nil,
+
+        # Floating options
+        float: true,
+
+        # Let exceptions through
+        exceptions: false
+      )
+        
       @name = name || File.basename($PROGRAM_NAME)
       @help = help
-      @use_version = version ? true : false
-      @version = @use_version && @version != true ? @version : nil
-      @msgopts, @float, @exception = msgopts, float, exception
+      @version = version || (version.nil? && !version_number.nil?)
+      @quiet = quiet
+      @verbose = verbose
+      @debug = debug
+      @version_number = version_number || find_version_number
+      @float = float
+      @exception = exception
     end
 
     # Compile source and return grammar object. Also sets #spec and #grammar.
@@ -139,8 +163,31 @@ module ShellOpts
         @file = find_caller_file
         @tokens = Lexer.lex(name, @spec, @oneline)
         ast = Parser.parse(tokens)
-        ast.add_version_option if @use_version
-        ast.add_help_options if @help
+
+        help_spec = (@help == true ? "-h,help" : @help)
+        version_spec = (@version == true ? "--version" : @version)
+        quiet_spec = (@quiet == true ? "-q,quiet" : @quiet)
+        verbose_spec = (@verbose == true ? "+v,verbose" : @verbose)
+        debug_spec = (@debug == true ? "--debug" : @debug)
+
+        @quiet_option = 
+            ast.inject_option(quiet_spec, "Quiet", "Do not write anything to standard output") if @quiet
+        @verbose_option = 
+            ast.inject_option(verbose_spec, "Increase verbosity", "Write verbose output") if @verbose
+        @debug_option = 
+            ast.inject_option(debug_spec, "Write debug information") if @debug
+        @help_option = 
+            ast.inject_option(help_spec, "Write short or long help") { |option|
+              short_option = option.short_names.first 
+              long_option = option.long_names.first
+              [
+                short_option && "#{short_option} prints a brief help text",
+                long_option && "#{long_option} prints a longer man-style description of the command"
+              ].compact.join(", ")
+            } if @help
+        @version_option = 
+            ast.inject_option(version_spec, "Write version number and exit") if @version
+
         @grammar = Analyzer.analyze(ast)
       }
       self
@@ -153,16 +200,22 @@ module ShellOpts
       handle_exceptions { 
         @argv = argv.dup
         @program, @args = Interpreter.interpret(grammar, argv, float: float, exception: exception)
-        if @program.version?
-          puts version 
-          exit
-        elsif @program.help?
-          if @program[:help].name == "-h"
-            ShellOpts.brief
-          else
+
+        # Process standard options (that may have been renamed)
+        if @program.__send__(:"#{@help_option.ident}?")
+          if @program[:help].name =~ /^--/
             ShellOpts.help
+          else
+            ShellOpts.brief
           end
           exit
+        elsif @program.__send__(:"#{@version_option.ident}?")
+          puts version_number
+          exit
+        else
+          @program.__quiet__ = @program.__send__(:"#{@quiet_option.ident}?") if @quiet
+          @program.__verbose__ = @program.__send__(:"#{@verbose_option.ident}") if @verbose
+          @program.__debug__ = @program.__send__(:"#{@debug_option.ident}?") if @debug
         end
       }
       self
@@ -235,6 +288,13 @@ module ShellOpts
     def self.help(subject = nil) ::ShellOpts.instance.help(subject) end
 
   private
+    def find_version_number
+      exe = caller.find { |line| line =~ /`<top \(required\)>'$/ }&.sub(/:.*/, "") or return nil
+      file = Dir.glob(File.dirname(exe) + "/../lib/*/version.rb").first or return nil
+      IO.read(file).sub(/^.*VERSION\s*=\s*"(.*?)".*$/m, '\1') or
+          raise ArgumentError, "ShellOpts needs an explicit version"
+    end
+
     def handle_exceptions(&block)
       return yield if exception
       begin
@@ -322,9 +382,12 @@ module ShellOpts
     end
   end
 
-  def self.process(spec, argv, msgopts: false, **opts)
-    msgopts ||= Messages.is_included?
-    ShellOpts.process(spec, argv, msgopts: msgopts, **opts)
+  def self.process(spec, argv, quiet: nil, verbose: nil, debug: nil, **opts)
+    constrain quiet, String, true, false, nil
+    quiet = quiet.nil? ? Message.is_included? || Verbose.is_included? : quiet
+    verbose = verbose.nil? ? ::ShellOpts::Verbose.is_included? : verbose
+    debug = debug.nil? ? Debug.is_included? : debug
+    ShellOpts.process(spec, argv, quiet: quiet, verbose: verbose, debug: debug, **opts)
   end
 
   @instance = nil
@@ -345,31 +408,57 @@ module ShellOpts
     exit 1
   end
 
-  # The Include module brings the reporting methods into the namespace when
-  # included
-  module Messages
+  def self.notice(message)
+    $stderr.puts "#{instance.program.__grammar__.name}: #{message}" \
+        if !instance.quiet || !instance.program.quiet?
+  end
+
+  def self.mesg(message)
+    $stdout.puts message if !instance.quiet || !instance.program.__quiet__
+  end
+
+  def self.verb(level = 1, message)
+    $stdout.puts message if instance.verbose && level <= instance.program.__verbose__
+  end
+
+  def self.debug(message)
+    $stdout.puts message if instance.debug && instance.program.__debug__
+  end
+
+  def self.quiet_flag
+  end
+
+  def self.verbose_flag
+  end
+
+  def self.debug_flag
+  end
+
+  module Message
     @is_included = false
     def self.is_included?() @is_included end
-    def self.include(...)
-      @is_included = true
-      super
-    end
+    def self.included(...) @is_included = true; super end
 
-    def notice(message)
-      $stderr.puts "#{name}: #{message}" if !quiet?
-    end
+    def notice(message) ::ShellOpts.notice(message) end
+    def mesg(message) ::ShellOpts.mesg(message) end
+  end
 
-    def mesg(message)
-      $stdout.puts message if !quiet?
-    end
+  module Verbose
+    @is_included = false
+    def self.is_included?() @is_included end
+    def self.included(...) @is_included = true; super end
 
-    def verb(level = 1, message)
-      $stdout.puts message if level <= @verbose
-    end
+    def notice(message) ::ShellOpts.notice(message) end
+    def mesg(message) ::ShellOpts.mesg(message) end
+    def verb(level = 1, message) ::ShellOpts.verb(level, message) end
+  end
 
-    def debug(message)
-      $stdout.puts message if debug?
-    end
+  module Debug
+    @is_included = false
+    def self.is_included?() @is_included end
+    def self.included(...) @is_included = true; super end
+
+    def debug(message) ::ShellOpts.debug(message) end
   end
 
   module ErrorHandling