shellopts 2.0.16 → 2.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256d4f5a28f8f4028030ac17631d4e93a36584b77c96cd8090ecab8dc393f36f
-  data.tar.gz: 381c0515800feb0a4d2327d336ed35c43e5441915cf6aef5cb4ebd365cbe8d39
+  metadata.gz: 35b9e7b5699cc1a5637d4c00dd95c74047074f1227b0d05f9a9c8b04e1e2cc8b
+  data.tar.gz: c8deed23c8e6f0b26d080e15d2830edb5e65d1b5f2f821ccd83db7db27d7aefd
 SHA512:
-  metadata.gz: ac3af229c984160970034b5bbef21584bb5d78e6581f3efb2d4d9c10e9217ebde1e3cc248136224c4859d9a73ded08fc1a6782ebddb55a2d8eff1b5d480c42f9
-  data.tar.gz: 855d30fcd66f441a09ab53d50284a11e2a24bcd8c24b9c5573e1783c571005ab6b7a383aefbd0d9883893207550fe9bd880def44e361f000c87289a3476fe48f
+  metadata.gz: 5d3e96ec825ca58c0e653613ab84e2ede3e661737f5699571c81aaf9b2cb1252ea802581e5b981a1757d8a5a750ba998c43730c6d2da7d8228b721b06a45640e
+  data.tar.gz: e64eeac4c3bf784f8ef3a5e3a61c596e262bd23c4ee05857f76138f82ff2180afb72ccd5c2b7ffedc4e6aa2887b10c76e3a80c33e24ceadd20e71513549b5bf0

data/PROBLEMS

@@ -0,0 +1,52 @@
+
+# Subcommand options are not recognized unless there exists an option on the
+# program level (try to remove -a below)
+
+SPEC = %(
+  Foreign data wrapper maintenance tool
+
+  -a,an-option
+    Gryf
+
+  list.servers! -- DATABASE
+    List foreign servers
+
+  create.server! -- DATABASE FDW-SERVER MSSQL-DATABASE [MSSQL-HOST [MSSQL-PORT]]
+    Create a new FDW server
+
+    -c,credentials=EFILE
+      Credentials file. The credentials file is a YAML formatted file that can
+      define the fields 'user', 'password', 'host', and 'port'
+
+  drop.server! -- DATABASE FDW-SERVER
+    Drop a FDW server. This cascades to FDW users too
+
+  list.users! -- DATABASE
+    List FDW users. 'users' in this context is postgres users that have an
+    associated FDW user mapping
+
+    --servers @ Also list the user's FDW servers
+
+  create.user! -- DATABASE FDW-SERVER [FDW-USER [FDW-PASSWORD]]
+    Create a FDW user. The user has to exist beforehand, this command only adds
+    a user mapping to the user and grants the usage privilege
+
+    -c,credentials=EFILE
+      Credentials file
+
+  drop.user! -- DATABASE FDW-USER
+    Drops a FDW user. The postgres user is not dropped but the user's user
+    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/lib/ext/follow.rb

@@ -0,0 +1,26 @@
+
+module Algorithm
+  class FollowEnumerator < Enumerator
+    def initialize(object, method = nil, &block)
+      closure = method ? lambda { |object| object.__send__(method) } : block
+      super() { |yielder|
+        while object
+          yielder << object
+          object = closure.call(object)
+        end
+      }
+    end
+  end
+
+  def follow(object, method = nil, &block)
+    !method.nil? || block_given? or raise ArgumentError, "Needs either a method or a block"
+    method.nil? == block_given? or raise ArgumentError, "Can't use both method and block"
+    FollowEnumerator.new(object, method, &block)
+  end
+
+  module_function :follow
+end
+
+
+
+

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

@@ -52,7 +52,7 @@ module ShellOpts
     # These methods can be overridden by an option or a command (this constant
     # is not used - it is just for informational purposes)
     OVERRIDEABLE_METHOD_NAMES = %w(
-        subcommand subcommand! supercommand!
+        subcommand subcommand! subcommands subcommands! supercommand!
     )
 
     # Redefine ::new to call #__initialize__
@@ -62,40 +62,28 @@ 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
     def to_h(*keys)
@@ -133,6 +121,13 @@ module ShellOpts
     #
     def subcommand!() __subcommand__! end
 
+    # Returns the concatenated identifier of subcommands (eg. :cmd.subcmd!)
+    def subcommands() __subcommands__ end
+
+    # Returns the subcommands in an array. This doesn't include the top-level
+    # program object
+    def subcommands!() __subcommands__! end
+
     # The parent command or nil. Initialized by #add_command
     #
     # Note: Can be overridden by a subcommand declaration (but not an
@@ -141,7 +136,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)
@@ -180,6 +175,16 @@ module ShellOpts
     # The actual subcommand object or nil if not present
     def __subcommand__!() @__subcommand__ end
 
+    # Implementation of the #subcommands method
+    def __subcommands__()
+      __subcommands__!.last&.__uid__&.to_sym
+    end
+
+    # Implementation of the #subcommands! method
+    def __subcommands__!()
+      ::Algorithm.follow(self.__subcommand__!, :__subcommand__!).to_a
+    end
+
   private
     def __initialize__(grammar)
       @__grammar__ = grammar
@@ -292,6 +297,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.16"
+  VERSION = "2.0.19"
 end

data/lib/shellopts.rb

@@ -5,6 +5,7 @@ require 'constrain'
 include Constrain
 
 require 'ext/array.rb'
+require 'ext/follow.rb'
 require 'ext/forward_to.rb'
 require 'ext/lcs.rb'
 include ForwardTo
@@ -95,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
@@ -121,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.
@@ -138,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
@@ -152,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
@@ -234,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
@@ -321,9 +382,13 @@ 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
@@ -344,31 +409,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