shellopts 1.0.0 → 2.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cc3c3ef5b7b13876949b290b9d247c41778eaa38ea01432d5abac47b663478a
-  data.tar.gz: bc2c44f163f81d8b51545679e8f8280ac889fbb1f96a7898e5a65fa63d337d4a
+  metadata.gz: e60db3cf5de50dcd106cb0fca007d064e18354278a65207bb167bf8aa63d3433
+  data.tar.gz: 85b0108262357d6e5654e725ab12293f51fd2579beb13fa0d910be2200c32310
 SHA512:
-  metadata.gz: d3c501335a899e4b14280cbb14b7f9e8a0d9ef28715760394d8f13ea837d0a5d3d9b91b9d07dcb42a747753e97a10c157ae5c5b20b95804b1746e0ebad7d88c9
-  data.tar.gz: 387c888158bbbebe127c6efde55c7bbb14436b7dcb8227cac38e2c9dac85e9a3d956c062e04b86101e28fa0bde4977fefadad4d1a643dd48d9218e5c04558ad2
+  metadata.gz: 375fe97651622560d786b288217e1a8581d12bbc497dee55b36848597d9410d393a127e86088cfe4ac8f949270d9f6797d6f135f65492f15bb9d4a84bff1ffbc
+  data.tar.gz: c69a813e4672d87c6a4da69e0e8086d8acfe54c8506cda64ce6dc36dbc12669cc79c29ffd480c6871937d87491139f4e7448fd35a6d6a7d333451addd6c634a6

data/README.md

@@ -378,6 +378,16 @@ release a new version, update the version number in `version.rb`, and then run
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
+## Implementation
+
+FIXME
+# ShellOpts is a library for parsing command line options and commands. It
+# consists of the interface module {ShellOpts}, the implementation class
+# {ShellOpts::ShellOpts} and the representation classes
+# {ShellOpts::OptionsHash} and {ShellOpts::OptionsStruct}.
+# {ShellOpts::Messenger} is used for error messages
+
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/TODO

@@ -1,5 +1,18 @@
 
 TODO
+  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 '--'
+    for options. This can cause collisions but they can be avoided using aliases
+  o Clean-up
+    o Grammar::options -> Grammar::option_multihash
+    o Clean-up identifiers etc.
+    o Un-multi-izing Grammar::option_multihash and turn it into a regular hash from key to option
+    o subcommand vs. command consistency
+  o Implement ObjectStruct#key! and ObjectStruct#value! (?)
+  o Allow command_alias == nil to suppress the method
+  o Raise on non-existing names/keys. Only return nil for declared names/keys that are not present
+  o Use hash_tree
   o Also allow assignment to usage string for ShellOpts::ShellOpts objects
   o Create a ShellOpts.args method? It would be useful when processing commands:
       case opt
@@ -9,7 +22,10 @@ TODO
     ShellOpts.args would be a shorthand for ShellOpts.shellopts.args
     Another option would be to create an argument-processing method:
       shellopts.argv(2) -> call error if not exactly two arguments else return elements
-      
+  o Add a ShellOpts.option method:
+      file = ShellOpts.option("--file")
+    This will only work for options on the outermost level... maybe:
+      file = ShellOpts.option("load! --file")
   o Check on return value from #process block to see if all options was handled:
       case opt
         when '-v'; verbose = true # Return value 'true' is ok

data/lib/shellopts.rb

@@ -2,231 +2,145 @@ require "shellopts/version"
 
 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'
 
-# ShellOpts is a library for parsing command line options and sub-commands. The
-# library API consists of the methods {ShellOpts.process}, {ShellOpts.error},
-# and {ShellOpts.fail} and the result class {ShellOpts::ShellOpts}
+# Name of program. Defined as the basename of the program file
+PROGRAM = File.basename($PROGRAM_NAME)
+
+# ShellOpts main Module
+#
+# This module contains methods to process command line options and arguments.
+# ShellOpts keeps a reference in ShellOpts.shellopts to the result of the last
+# command that was processed through its interface and use it as the implicit
+# object of many of its methods. This matches the typical use case where only
+# one command line is ever processed and makes it possible to create class
+# methods that knows about the command like #error and #fail
+#
+# 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:
+#
+#   USAGE = "a,all f,file=FILE -- ARG1 ARG2"
+#   opts, args = ShellOpts.as_struct(USAGE, ARGV)
+#   File.exist?(opts.file) or error "Can't find #{opts.file}"
+#
+# The command line is processed through one of the methods #process, #as_array,
+# #as_hash, or #as_struct that returns a [data, args] tuple. The data type
+# depends on the method: #process yields a Idr object that internally serves as
+# the base for the #as_array and #as_hash and #as_struct that converts it into
+# an Array, Hash, or ShellOpts::OptionStruct object. For example:
+#
+#   USAGE = "..."
+#   ShellOpts.process(USAGE, ARGV)
+#   program, args = ShellOpts.as_program(USAGE, ARGV)
+#   array, args = ShellOpts.as_array(USAGE, ARGV)
+#   hash, args = ShellOpts.as_hash(USAGE, ARGV)
+#   struct, args = ShellOpts.as_struct(USAGE, ARGV)
 #
-# ShellOpts inject the constant PROGRAM into the global scope. It contains the 
+# 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
+# raises ConversionError is there is a name collision when converting to the
+# hash or struct representations. Note that CompilerError and ConversionError
+# are caused by misuse of the library and the problem should be corrected by
+# the developer
+#
+# ShellOpts injects the constant PROGRAM into the global scope. It contains the 
 # name of the program
 #
 module ShellOpts
-  # Return the hidden +ShellOpts::ShellOpts+ object (see .process)
-  def self.shellopts()
-    @shellopts
-  end
+  # Base class for ShellOpts exceptions
+  class Error < RuntimeError; end
 
-  # Prettified usage string used by #error and #fail. Default is +usage+ of
-  # the current +ShellOpts::ShellOpts+ object
-  def self.usage() @usage || @shellopts&.usage end
-
-  # Set the usage string
-  def self.usage=(usage) @usage = usage end
-  
-  # Process command line options and arguments.  #process takes a usage string
-  # defining the options and the array of command line arguments to be parsed
-  # as arguments
-  #
-  # If called with a block, the block is called with name and value of each
-  # option or command and #process returns a list of remaining command line
-  # arguments. If called without a block a ShellOpts::ShellOpts object is
-  # returned
-  # 
-  # The value of an option is its argument, the value of a command is an array
-  # of name/value pairs of options and subcommands. Option values are converted
-  # to the target type (String, Integer, Float) if specified
-  #
-  # Example
-  #
-  #   # Define options
-  #   USAGE = 'a,all g,global +v,verbose h,help save! snapshot f,file=FILE h,help'
-  #
-  #   # Define defaults
-  #   all = false
-  #   global = false
-  #   verbose = 0
-  #   save = false
-  #   snapshot = false
-  #   file = nil
-  #
-  #   # Process options
-  #   argv = ShellOpts.process(USAGE, ARGV) do |name, value|
-  #     case name
-  #       when '-a', '--all'; all = true
-  #       when '-g', '--global'; global = value
-  #       when '-v', '--verbose'; verbose += 1
-  #       when '-h', '--help'; print_help(); exit(0)
-  #       when 'save'
-  #         save = true
-  #         value.each do |name, value|
-  #           case name
-  #             when '--snapshot'; snapshot = true
-  #             when '-f', '--file'; file = value
-  #             when '-h', '--help'; print_save_help(); exit(0)
-  #           end
-  #         end
-  #     else
-  #       raise "Not a user error. The developer forgot or misspelled an option"
-  #     end
-  #   end
-  #
-  #   # Process remaining arguments
-  #   argv.each { |arg| ... }
-  #
-  # If an error is encountered while compiling the usage string, a
-  # +ShellOpts::Compiler+ exception is raised. If the error happens while
-  # parsing the command line arguments, the program prints an error message and
-  # exits with status 1. Failed assertions raise a +ShellOpts::InternalError+
-  # exception
-  #
-  # Note that you can't process more than one command line at a time because
-  # #process saves a hidden {ShellOpts::ShellOpts} class variable used by the
-  # class methods #error and #fail. Call #reset to clear the global object if
-  # you really need to parse more than one command line. Alternatively you can
-  # create +ShellOpts::ShellOpts+ objects yourself and also use the object methods
-  # #error and #fail:
-  #
-  #   shellopts = ShellOpts::ShellOpts.new(USAGE, ARGS)
-  #   shellopts.each { |name, value| ... }
-  #   shellopts.args.each { |arg| ... }
-  #   shellopts.error("Something went wrong")
-  #
-  # Use #shellopts to get the hidden +ShellOpts::ShellOpts+ object
-  #
-  def self.process(usage, argv, program_name: PROGRAM, &block)
-    if !block_given?
-      ShellOpts.new(usage, argv, program_name: program_name)
-    else
-      @shellopts.nil? or raise InternalError, "ShellOpts class variable already initialized"
-      @shellopts = ShellOpts.new(usage, argv, program_name: program_name)
-      @shellopts.each(&block)
-      @shellopts.args
+  # Raised when a syntax error is detected in the usage string
+  class CompilerError < Error
+    def initialize(start, message)
+      super(message)
+      set_backtrace(caller(start))
     end
   end
 
-  # Reset the hidden +ShellOpts::ShellOpts+ class variable so that you can process
-  # another command line
-  def self.reset()
-    @shellopts = nil
-    @usage = nil
-  end
+  # Raised when an error is detected during conversion from the Idr to array,
+  # hash, or struct
+  class ConversionError < Error; end
 
-  # Print error message and usage string and exit with status 1. It use the
-  # current ShellOpts object if defined. This method should be called in
-  # response to user-errors (eg. specifying an illegal option)
-  #
-  # If there is no current ShellOpts object +error+ will look for USAGE to make
-  # it possible to use +error+ before the command line is processed and also as
-  # a stand-alone error reporting method
-  def self.error(*msgs)
-    program = @shellopts&.program_name || PROGRAM
-    usage_string = usage || (defined?(USAGE) && USAGE ? Grammar.compile(PROGRAM, USAGE).usage : nil)
-    emit_and_exit(program, @usage.nil?, usage_string, *msgs)
-  end
+  # Raised when an internal error is detected
+  class InternalError < Error; end
 
-  # Print error message and exit with status 1. It use the current ShellOpts
-  # object if defined. This method should not be called in response to
-  # user-errors but system errors (like disk full)
-  def self.fail(*msgs)
-    program = @shellopts&.program_name || PROGRAM
-    emit_and_exit(program, false, nil, *msgs)
-  end
+  # The current compilation object. It is set by #process
+  def self.shellopts() @shellopts end
 
-  # The compilation object
-  class ShellOpts
-    # Name of program
-    attr_reader :program_name
-
-    # Prettified usage string used by #error and #fail. Shorthand for +grammar.usage+
-    def usage() @grammar.usage end
-
-    # The grammar compiled from the usage string. If #ast is defined, it's
-    # equal to ast.grammar
-    attr_reader :grammar
-
-    # The AST resulting from parsing the command line arguments
-    attr_reader :ast
-
-    # List of remaining non-option command line arguments. Shorthand for ast.arguments
-    def args() @ast.arguments end
-
-    # Compile a usage string into a grammar and use that to parse command line
-    # arguments
-    #
-    # +usage+ is the usage string, and +argv+ the command line (typically the
-    # global ARGV array). +program_name+ is the name of the program and is
-    # used in error messages. It defaults to the basename of the program
-    #
-    # Errors in the usage string raise a CompilerError exception. Errors in the
-    # argv arguments terminates the program with an error message
-    def initialize(usage, argv, program_name: File.basename($0))
-      @program_name = program_name
-      begin
-        @grammar = Grammar.compile(program_name, usage)
-        @ast = Ast.parse(@grammar, argv)
-      rescue Grammar::Compiler::Error => ex
-        raise CompilerError.new(5, ex.message)
-      rescue Ast::Parser::Error => ex
-        error(ex.message)
-      end
-    end
+  # Process command line and set and return the shellopts compile object
+  def self.process(usage, argv, name: self.name, message: nil)
+    @shellopts.nil? or reset
+    messenger = message && Messenger.new(name, message, format: :custom)
+    @shellopts = ShellOpts.new(usage, argv, name: name, messenger: messenger)
+  end
 
-    # Unroll the AST into a nested array
-    def to_a
-      @ast.values
-    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]
+  end
 
-    # Iterate the result as name/value pairs. See {ShellOpts.process} for a
-    # detailed description
-    def each(&block)
-      if block_given?
-        to_a.each { |*args| yield(*args) }
-      else
-        to_a # FIXME: Iterator
-      end
-    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]
+  end
 
-    # Print error message and usage string and exit with status 1. This method
-    # should be called in response to user-errors (eg. specifying an illegal
-    # option)
-    def error(*msgs)
-      ::ShellOpts.emit_and_exit(program_name, true, usage, msgs)
-    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]
+  end
 
-    # Print error message and exit with status 1. This method should not be
-    # called in response to user-errors but system errors (like disk full)
-    def fail(*msgs)
-      ::ShellOpts.emit_and_exit(program_name, false, nil, msgs)
-    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]
   end
 
-  # Base class for ShellOpts exceptions
-  class Error < RuntimeError; 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)
+    shellopts.each(&block)
+  end
 
-  # Raised when an error is detected in the usage string
-  class CompilerError < Error
-    def initialize(start, message)
-      super(message)
-      set_backtrace(caller(start))
-    end
+  # Print error message and usage 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)
   end
 
-  # Raised when an internal error is detected
-  class InternalError < Error; end
+  # Print error message 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)
+  end
 
 private
-  @shellopts = nil
-
-  def self.emit_and_exit(program, use_usage, usage, *msgs)
-    $stderr.puts "#{program}: #{msgs.join}"
-    if use_usage
-      $stderr.puts "Usage: #{program} #{usage}" if usage
-    else
-      $stderr.puts usage if usage
-    end
-    exit 1
+  # Reset state variables
+  def self.reset()
+    @shellopts = nil
   end
-end
 
-PROGRAM = File.basename($PROGRAM_NAME)
+  @shellopts = nil
+end

data/lib/shellopts/ast/node.rb

@@ -23,7 +23,7 @@ module ShellOpts
       end
 
       # Return either a value (option value), an array of values (command), or
-      # nil (option without a value). Should be defined in sub-classes
+      # nil (option without a value). It must be defined in sub-classes of Ast::Node
       def values() raise end
 
       # :nocov:

data/lib/shellopts/compiler.rb

@@ -8,12 +8,12 @@ require 'shellopts/grammar/program.rb'
 module ShellOpts
   module Grammar
     # Compiles an option definition string and returns a Grammar::Program
-    # object. program_name is the name of the program and source is the 
+    # object. name is the name of the program and source is the 
     # option definition string
-    def self.compile(program_name, source)
-      program_name.is_a?(String) or raise Compiler::Error, "Expected String argument, got #{program_name.class}"
+    def self.compile(name, source)
+      name.is_a?(String) or raise Compiler::Error, "Expected String argument, got #{name.class}"
       source.is_a?(String) or raise Compiler::Error, "Expected String argument, got #{source.class}"
-      Compiler.new(program_name, source).call
+      Compiler.new(name, source).call
     end
 
     # Service object for compiling an option definition string. Returns a 
@@ -26,8 +26,8 @@ module ShellOpts
       class Error < RuntimeError; end
 
       # Initialize a Compiler object. source is the option definition string
-      def initialize(program_name, source)
-        @program_name, @tokens = program_name, source.split(/\s+/).reject(&:empty?)
+      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
         # object. The top level Program object has nil as its path.
@@ -54,7 +54,7 @@ module ShellOpts
       end
 
       def compile_program
-        program = @commands_by_path[nil] = Grammar::Program.new(@program_name, compile_options)
+        program = @commands_by_path[nil] = Grammar::Program.new(@name, compile_options)
         while curr_token && curr_token != "--"
           compile_command
         end

data/lib/shellopts/generator.rb

@@ -0,0 +1,15 @@
+
+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)
+    end
+  end
+end
+
+
+
+

data/lib/shellopts/grammar/command.rb

@@ -11,12 +11,8 @@ module ShellOpts
       # Name of command (String). Name doesn't include the exclamation point ('!')
       attr_reader :name
 
-      # Hash from option names (both short and long names) to option. This
-      # means an option can occur more than once as the hash value
-      attr_reader :options 
-
-      # Sub-commands of this command. Is a hash from sub-command name to command object
-      attr_reader :commands 
+      # Same as #name. TODO Define in Grammar::Node instead
+      alias :key_name :name
 
       # List of options in declaration order
       attr_reader :option_list
@@ -24,6 +20,23 @@ module ShellOpts
       # List of commands in declaration order
       attr_reader :command_list
 
+      # Multihash from option key or names (both short and long names) to option. This
+      # means an option can occur more than once as the hash value
+      def options() 
+        @option_multihash ||= @option_list.flat_map { |option| 
+          option.identifiers.map { |ident| [ident, option] }
+        }.to_h
+      end
+
+      # Sub-commands of this command. Is a multihash from sub-command key or
+      # name to command object. Lazily constructed because subcommands are added
+      # after initialization
+      def commands()
+        @command_multihash ||= @command_list.flat_map { |command| 
+          command.identifiers.map { |name| [name, command] }
+        }.to_h
+      end
+
       # Initialize a Command object. parent is the parent Command object or nil
       # if this is the root object. name is the name of the command (without
       # the exclamation mark), and option_list a list of Option objects
@@ -32,11 +45,17 @@ module ShellOpts
         @name = name
         parent.attach(self) if parent
         @option_list = option_list
-        @options = @option_list.flat_map { |opt| opt.names.map { |name| [name, opt] } }.to_h
-        @commands = {}
         @command_list = []
       end
 
+      # Return key for the identifier
+      def identifier2key(ident)
+        options[ident]&.key || commands[ident]&.key
+      end
+
+      # Return list of identifiers for the command
+      def identifiers() [key, name] end
+
       # :nocov:
       def dump(&block)
         puts "#{key.inspect}"
@@ -55,7 +74,6 @@ module ShellOpts
     protected
       def attach(command)
         command.instance_variable_set(:@parent, self)
-        @commands[command.name] = command
         @command_list << command
       end
     end

data/lib/shellopts/grammar/option.rb

@@ -10,6 +10,9 @@ module ShellOpts
       # List of long names (incl. '--')
       attr_reader :long_names
 
+      # Name of the key attribute (eg. if key is :all then key_name is '--all'
+      attr_reader :key_name
+
       # List of flags (Symbol)
       def flags() @flags.keys end
 
@@ -23,7 +26,8 @@ module ShellOpts
       # there's no :string flag, it's status is inferred. label is the optional
       # informal name of the option argument (eg. 'FILE') or nil if not present
       def initialize(short_names, long_names, flags, label = nil)
-        super((long_names.first || short_names.first).sub(/^-+/, "").to_sym)
+        @key_name = long_names.first || short_names.first
+        super(@key_name.sub(/^-+/, "").to_sym)
         @short_names, @long_names = short_names, long_names
         @flags = flags.map { |flag| [flag, true] }.to_h
         @label = label
@@ -32,6 +36,12 @@ module ShellOpts
       # Array of option names with short names first and then the long names
       def names() @short_names + @long_names end
 
+      # Array of names and the key
+      def identifiers() names + [key] end
+
+      # Return true if +ident+ is equal to any name or to key
+      def match?(ident) names.include?(ident) || ident == key end
+
       # Flag query methods. Returns true if the flag is present and otherwise nil
       def repeated?() @flags[:repeated] || false end
       def argument?() @flags[:argument] || false end

data/lib/shellopts/grammar/program.rb

@@ -17,7 +17,7 @@ module ShellOpts
       def usage
         (
           render_options(option_list) + 
-          commands.values.map { |cmd| render_command(cmd) } + 
+          command_list.map { |cmd| render_command(cmd) } + 
           args
         ).flatten.join(" ")
       end
@@ -34,7 +34,7 @@ module ShellOpts
     private
       def render_command(command)
         [command.name] + render_options(command.option_list) + 
-            command.commands.values.map { |cmd| render_command(cmd) }.flatten
+            command.command_list.map { |cmd| render_command(cmd) }.flatten
       end
 
       def render_options(options)

data/lib/shellopts/idr.rb

@@ -0,0 +1,209 @@
+
+module ShellOpts
+  # Idr models the Internal Data Representation of a program. It is the native
+  # representation of a command
+  #
+  # The IDR should ideally be completely detached from the compile-time grammar
+  # and AST but they are only hidden from view in this implementation. Create
+  # a Shellopts object instead to access the compiler data
+  #
+  module Idr
+    # Base class for the Idr class hierarchy. It is constructed from an Ast
+    # object by #generate. Node is modelled as an element of a hash with a key
+    # and a value. Options have their (optional) argument as value while
+    # commands use +self+ as value
+    class Node
+      # Unique key (within context) for the option or command. nil for the
+      # top-level Program object
+      #
+      # It is usually the first long option if present and else the first short
+      # option turned into a Symbol by first removing prefixed dashed, eg.
+      # '--all' becomes :all
+      attr_reader :key
+
+      # Name of command and option as used on the command line
+      attr_reader :name
+
+      # Value of node. This can be a simple value (String, Integer, or Float),
+      # an Array of values, or a Idr::Command object. Note that the value of a
+      # Command object is the object itself
+      #
+      # Repeated options are implemented as an Array with one element for each
+      # use of the option. The element is nil if the option doesn't take
+      # arguments or if an optional argument is missing. 
+      attr_reader :value
+
+    protected
+      # Copy arguments into instance variables
+      def initialize(ast, key, name, value)
+        @ast, @key, @name, @value = ast, key, name, value
+      end
+
+      # The AST node for this Idr object
+      attr_reader :ast
+
+      # Shorthand to the grammar node for this Idr object
+      def grammar() @ast.grammar end
+    end
+
+    # Base class for Options
+    class Option < Node
+    end
+
+    class SimpleOption < Option
+    protected
+      # Initialize with defauls from the Ast. +value+ is set to true if option
+      # doesn't take an argument
+      def initialize(ast)
+        value = ast.grammar.argument? ? ast.value : true
+        super(ast, ast.key, ast.name, value)
+      end
+    end
+
+    # An OptionGroup models repeated options collapsed into a single key. The
+    # name of the group should be set to the name of the key (eg. '--all' if
+    # the key is :all)
+    class OptionGroup < Option
+      # Array of names of the options
+      attr_reader :names
+
+      # Array of values of the options
+      alias :values :value
+
+      # Name is set to the key name and value to an array of option values
+      def initialize(key, name, options)
+        @names = options.map(&:name)
+        super(nil, key, name, options.map(&:value))
+      end
+    end
+
+    class Command < Node
+      # Hash from key to options with repeated option_list collapsed into a
+      # option group. It also include an entry for the subcommand.  Options are
+      # ordered by first use on the command line. The command entry will always
+      # be last
+      attr_reader :options
+
+      # List of command line options in the same order as on the command line
+      attr_reader :option_list
+
+      # Subcommand object. Possibly nil
+      attr_reader :subcommand
+
+      # True if ident is declared
+      def declared?(ident) option?(ident) || command?(ident) end
+
+      # True if ident is declared as an option
+      def option?(ident) grammar.options.key?(ident) end
+
+      # True if ident is declared as a command
+      def command?(ident) grammar.commands.key?(ident) end 
+      
+      # True if ident is present
+      def key?(ident)
+        declared?(ident) or raise InternalError, "Undefined identifier: #{ident.inspect}"
+        key = grammar.identifier2key(ident)
+        @options.key?(key)
+      end
+
+      # Value of ident. Repeated options are collapsed into an OptionGroup object
+      def [](ident)
+        declared?(ident) or raise InternalError, "Undefined identifier: #{ident.inspect}"
+        key = grammar.identifier2key(ident)
+        if @options.key?(key)
+          @options[key].value
+        elsif option?(key)
+          false
+        else
+          nil
+        end
+      end
+
+      # Apply defaults recursively. Values can be lambdas that will be evaluated to
+      # get the default value
+      def apply(defaults = {}) end
+
+      # Return options and command as an array
+      def to_a() @ast.values end
+
+      # Return options and command as a hash. The hash also define the
+      # singleton method #subcommand that returns the key of the subcommand
+      #
+      # +key+ controls the type of keys used: +:key+ (the default) use the
+      # symbolic key, +:name+ use key_name. Note that using +:name+ can cause name collisions between
+      # option and command names and that #to_s raises an exception if it detects a collision
+      #
+      # +aliases+ maps from key to replacement key (which could be any object).
+      # +aliases+ can be used to avoid name collisions between options and
+      # commands
+      #
+      # IDEA: Make subcommand _not_ follow the +key+ setting so that setting key to
+      # IDEA: Add a singleton method #subcommand to the hash
+      #
+      def to_h(use: :key, aliases: {})
+        value = {}
+        value.define_singleton_method(:subcommand) { nil }
+        options.values.each { |opt|
+          ident = aliases[opt.key] || (use == :key ? opt.key : opt.ast.grammar.key_name)
+          !value.key?(ident) or raise ConversionError, "Duplicate key: #{ident.inspect}"
+          case opt
+            when Option
+              value[ident] = opt.value
+            when Command
+              value[ident] = opt.value.to_h
+              value.define_singleton_method(:subcommand) { ident } # Redefine
+          else
+            raise InternalError, "Oops"
+          end
+        }
+        value
+      end
+
+      # Return options and command as a struct
+      def to_struct(key = :key, aliases = {}) OptionStruct.new(self, key, aliases) end
+
+    protected
+      # Initialize an Idr::Command object and all dependent objects
+      def initialize(ast)
+        super(ast, ast.key, ast.name, self)
+        @option_list = ast.options.map { |node| SimpleOption.new(node) }
+        @subcommand = Command.new(ast.command) if ast.command
+        @options = @option_list.group_by { |option| option.key }.map { |key, option_list|
+          option = 
+              if ast.grammar.options[key].repeated?
+                OptionGroup.new(key, ast.grammar.options[key].key_name, option_list)
+              else
+                option_list.first
+              end
+          [key, option]
+        }.to_h
+        @options[subcommand.key] = @subcommand if @subcommand
+      end
+    end
+
+    class Program < Command
+      # #key is nil for the top-level Program object
+      def key() nil end
+
+      # Remaining command line arguments
+      def args() @ast.arguments end
+
+      # Messenger object that is used to emit error messages. It should
+      # implement #error(*args) and #fail(*args)
+      attr_reader :messenger
+
+      # Initialize the top-level Idr::Program object
+      def initialize(ast, messenger)
+        @messenger = messenger
+        super(ast)
+      end
+
+      # Emit error message and a usage description before exiting with status 1
+      def error(*args) messenger.error(*error_messages) end
+
+      # Emit error message before exiting with status 1
+      def fail(*args) messenger.fail(*error_messages) end
+    end
+  end
+end
+

data/lib/shellopts/messenger.rb

@@ -0,0 +1,71 @@
+
+module ShellOpts
+  # Service object for output of messages
+  #
+  # Messages are using the common command line formats
+  #
+  class Messenger
+    # Name of the program. When assigning to +name+ prefixed and suffixed
+    # whitespaces are removed
+    attr_accessor :name
+
+    # :nodoc:
+    def name=(name) @name = name.strip end
+    # :nodoc:
+
+    # Usage string. If not nil the usage string is printed by #error. When
+    # assigning to +usage+ suffixed whitespaces are removed and the format
+    # automatically set to +:custom+
+    attr_accessor :usage
+
+    # :nodoc:
+    def usage=(usage) 
+      @format = :custom
+      @usage = usage&.rstrip
+    end
+    # :nodoc:
+
+    # Format of the usage string: +:default+ prefixes the +usage+ with 'Usage:
+    # #{name} ' before printing. +:custom+ prints +usage+ as is
+    attr_accessor :format
+
+    # Initialize a Messenger object. +name+ is the name of the name and +usage+
+    # is a short description of the options (eg. '-a -b') or a longer multiline
+    # explanation. The +:format+ option selects bewtween the two: +short+ (the
+    # default) or :long. Note that 
+    #
+    def initialize(name, usage, format: :default)
+      @name = name
+      @usage = usage
+      @format = format
+    end
+
+    # Print error message and usage string and exit with status 1. Output is
+    # using the following format
+    #
+    #   <name name>: <message>
+    #   Usage: <name name> <options and arguments>
+    #
+    def error(*msgs)
+      $stderr.print "#{name}: #{msgs.join}\n"
+      if usage
+        $stderr.print "Usage: #{name} " if format == :default
+        $stderr.print "#{usage}\n"
+      end
+      exit 1
+    end
+
+    # Print error message and exit with status 1. It use the current ShellOpts
+    # object if defined. This method should not be called in response to
+    # user-errors but system errors (like disk full). Output is using the
+    # following format:
+    #
+    #   <name name>: <message>
+    #
+    def fail(*msgs)
+      $stderr.puts "#{name}: #{msgs.join}"
+      exit 1
+    end
+  end
+end
+

data/lib/shellopts/option_struct.rb

@@ -0,0 +1,245 @@
+
+require 'shellopts/shellopts.rb'
+require 'shellopts/idr'
+
+module ShellOpts
+  class OptionStruct < BasicObject
+    # +key=:name+ cause command methods to be named without the exclamation
+    # mark. It doesn't change how options are named
+    def self.new(idr, key = :key, aliases = {})
+      ast = idr.instance_variable_get("@ast")
+      grammar = ast.grammar
+      instance = allocate
+
+      # Generate option accessor methods
+      grammar.option_list.each { |option|
+        key = alias_key(option.key, aliases)
+        instance.instance_eval("def #{key}() @#{key} end")
+        present = set_variable(instance, "@#{key}", idr[option.key])
+        instance.instance_eval("def #{key}?() #{present} end")
+      }
+
+      # Generate #subcommand default methods
+      if !idr.subcommand
+        instance.instance_eval("def subcommand() nil end")
+        instance.instance_eval("def subcommand?() false end")
+        instance.instance_eval("def subcommand!() nil end")
+      end
+
+      # Generate subcommand methods
+      grammar.command_list.each { |command|
+        key = alias_key(command.key, aliases)
+        if command.key == idr.subcommand&.key
+          struct = OptionStruct.new(idr.subcommand, aliases[idr.subcommand.key] || {})
+          set_variable(instance, "@subcommand", struct)
+          instance.instance_eval("def #{key}() @subcommand end")
+          instance.instance_eval("def subcommand() :#{key} end")
+          instance.instance_eval("def subcommand?() true end")
+          instance.instance_eval("def subcommand!() @subcommand end")
+        else
+          instance.instance_eval("def #{key}() nil end")
+        end
+      }
+
+      instance
+    end
+
+  private
+    # Return class of object. #class is not defined for BasicObjects so this
+    # method provides an alternative way of getting the class
+    def self.class_of(object) 
+      # https://stackoverflow.com/a/18621313/2130986
+      ::Kernel.instance_method(:class).bind(object).call 
+    end
+
+    # Replace key with alias and check against the list of reserved words
+    def self.alias_key(internal_key, aliases)
+      key = aliases[internal_key] || internal_key
+      !RESERVED_WORDS.include?(key.to_s) or
+        raise ::ShellOpts::ConversionError, "Can't create struct: '#{key}' is a reserved word"
+      key
+    end
+
+    # Shorthand helper method. Substitutes the undefined ObjectStruct#instance_variable_set
+    def self.set_variable(this, var, value)
+      # https://stackoverflow.com/a/18621313/2130986
+      ::Kernel.instance_method(:instance_variable_set).bind(this).call(var, value)
+    end
+
+    BASIC_OBJECT_RESERVED_WORDS = %w(
+         __id__ __send__ instance_eval instance_exec method_missing
+         singleton_method_added singleton_method_removed
+         singleton_method_undefined)
+    OPTIONS_STRUCT_RESERVED_WORDS = %w(subcommand)
+    RESERVED_WORDS = BASIC_OBJECT_RESERVED_WORDS + OPTIONS_STRUCT_RESERVED_WORDS
+  end
+end
+
+
+
+
+
+
+
+
+__END__
+
+module ShellOpts
+  # Struct representation of options. Usually created by ShellOpts::to_struct
+  #
+  # OptionStruct objects give easy access to configuration option values but
+  # meta data are more circuitously accessed through class methods with an
+  # explicit instance argument
+  #
+  # Option values are accessed through a member methods named after the key of
+  # the option. Repeated options have an Array value with one element (possibly
+  # nil) for each use of the option. A query method with a '?' suffixed to the
+  # name returns true or false depending on whether the option was used or not
+  #
+  #   option   - Value of option. Either an object or an Array if the option can
+  #              be repeated
+  #   option?  - True iff option was given
+  #
+  # Command methods return a nested OptionStruct object while the special
+  # #command method returns the key of actual command (if any). Use
+  # +strukt.send(strukt.command)+ to get the subcommand of a OptionStruct. It
+  # is possible to rename #command method to avoid name collisions 
+  #
+  #   name!   - Command. An OptionStruct or nil if not given on the command line
+  #   subcommand - Key of command. Can be renamed
+  #
+  # ---------------------------------
+  #   name!   - Command. An OptionStruct or nil if not given on the command line
+  #
+  #   key!    - Key of command
+  #   value!  - Value of command (a subcommand). Can be renamed
+  #
+  # Note: There is no command query method because option and command names
+  # live in seperate namespaces and could cause colllisions. Check +name!+ for
+  # nil to detect if a command was given
+  #
+  # Meta data are extracted through class methods to avoid polluting the object
+  # namespace. OptionStruct use an OptionsHash object internally and
+  # implements a subset of its meta methods by forwarding to it. The
+  # OptionsHash object can be accessed through the #options_hash method
+  #
+  # Note that #command is defined as both an instance method and a class
+  # method. Use the class method to make the code work with all OptionStruct
+  # objects even if #command has been renamed
+  #
+  # +ShellOpts+ is derived from +BascicObject+ that reserves some words for
+  # internal use (+__id__+, +__send__+, +instance_eval+, +instance_exec+,
+  # +method_missing+, +singleton_method_added+, +singleton_method_removed+,
+  # +singleton_method_undefined+). ShellOpts also define two reserved words of
+  # its own (+__options_hash__+ and +__command__+). ShellOpts raise an
+  # ShellOpts::ConversionError if an option collides with one of the
+  # reserved words or with the special #command method
+  #
+  class OptionStruct < BasicObject
+    # Create a new OptionStruct instance from an AST. The optional
+    # +options_hash+ argument is used to create subcommands without creating a
+    # new options_hash argument. It is not meant for end-users. The
+    # +command_alias+ names the method holding the key for the subcommand (if
+    # any)
+    def self.new(ast, options_hash = OptionsHash.new(ast), command_alias: :command)
+      instance = allocate
+      set_variable(instance, "@__options_hash__", options_hash)
+
+      # Check for reserved words and +command_alias+
+      options_hash.keys.each { |key| 
+        !RESERVED_WORDS.include?(key.to_s) or 
+          raise ::ShellOpts::ConversionError, "Can't create struct: '#{key}' is a reserved word"
+        key != command_alias or
+          raise ::ShellOpts::ConversionError, "Can't create struct: '#{key}' is the command alias"
+      }
+
+      # Create accessor methods
+      ast.grammar.option_list.each { |option|
+        instance.instance_eval("def #{option.key}() @#{option.key} end")
+        instance.instance_eval("def #{option.key}?() false end")
+      }
+      ast.grammar.command_list.each { |command|
+        instance.instance_eval("def #{command.key}() nil end")
+      }
+
+      # Assign values
+      options_hash.each { |key, value|
+        if value.is_a?(OptionsHash)
+          set_variable(instance, "@__command__", OptionStruct.new(value.ast, value))
+          instance.instance_eval("def #{key}() @__command__ end")
+        else
+          set_variable(instance, "@#{key}", value)
+          instance.instance_eval("def #{key}?() true end")
+        end
+      }
+
+      # Command accessor method
+      instance.instance_eval("def #{command_alias}() @__options_hash__.command end")  
+
+      instance
+    end
+
+    # Return the OptionsHash object from the instance
+    def self.options_hash(instance)
+      get_variable(instance, "@__options_hash__")
+    end
+
+    # Return class of object. #class is not defined for BasicObjects so this
+    # method provides an alternative way of getting the class a BasicObject
+    def self.class_of(object) 
+      # https://stackoverflow.com/a/18621313/2130986
+      ::Kernel.instance_method(:class).bind(object).call 
+    end
+
+    # Return the number of options and commands
+    def self.size(instance)
+      options_hash(instance).size
+    end
+
+    # Return the option and command keys. The keys are in order of occurrence
+    # on the command line. A subcommand will always be the last element
+    def self.keys(instance)
+      options_hash(instance).keys
+    end
+
+    # Return the actual option name used on the command line for +name+. Use
+    # +index+ to select between repeated options. Return the name of the
+    # program/subcommand if key is nil
+    def self.name(struct, key = nil, index = nil)
+      options_hash(struct).name(key, index)
+    end
+
+    # Return the AST node for the option key or the AST node for the
+    # OptionStruct if key is nil. Use +index+ to select between repeated
+    # options. Raise InternalError if key doesn't exists
+    def self.node(struct, key = nil, index = nil)
+      options_hash(struct).node(key, index)
+    end
+
+    # Return key of the command of the struct (possibly nil)
+    def self.command(struct)
+      options_hash(struct).command
+    end
+
+  private
+    BASIC_OBJECT_RESERVED_WORDS = %w(
+         __id__ __send__ instance_eval instance_exec method_missing
+         singleton_method_added singleton_method_removed
+         singleton_method_undefined)
+    OPTIONS_STRUCT_RESERVED_WORDS = %w(__options_hash__ __command__)
+    RESERVED_WORDS = BASIC_OBJECT_RESERVED_WORDS + OPTIONS_STRUCT_RESERVED_WORDS 
+
+    # Shorthand helper method. Substitutes the undefined ObjectStruct#instance_variable_set
+    def self.set_variable(this, var, value)
+      # https://stackoverflow.com/a/18621313/2130986
+      ::Kernel.instance_method(:instance_variable_set).bind(this).call(var, value)
+    end
+
+    # Shorthand helper method: Substitutes the undefined ObjectStruct#instance_variable_get
+    def self.get_variable(this, var)
+      # https://stackoverflow.com/a/18621313/2130986
+      ::Kernel.instance_method(:instance_variable_get).bind(this).call(var)
+    end
+  end
+end 
+

data/lib/shellopts/shellopts.rb

@@ -0,0 +1,98 @@
+
+require "shellopts"
+
+# TODO
+#
+# PROCESSING
+#   1. Compile usage string and yield a grammar
+#   2. Parse the options using the grammar and yield an AST
+#   3. Construct the Program model from the AST
+#   4. Apply defaults to the model
+#   6. Run validations on the model
+#   5. Create representation from the model
+#
+
+module ShellOpts
+  # The command line processing object
+  class ShellOpts
+    # One of :key, :name, :option
+    #
+    #         Option   Command
+    # :key    key      #command! (no collision)
+    # :name   name     #command (possible collision)
+    # :option --option #command (multihash, no collision) (TODO)
+    #
+    DEFAULT_USE = :key
+
+    # Name of program
+    attr_reader :name
+
+    # The grammar compiled from the usage string
+    attr_reader :grammar
+
+    # The AST parsed from the command line arguments
+    attr_reader :ast
+
+    # The IDR generated from the Ast
+    attr_reader :idr
+
+    # Object for error & fail messages. Default is to write a message on
+    # standard error and exit with status 1
+    attr_accessor :messenger
+
+    # Compile a usage string into a grammar and use that to parse command line
+    # arguments
+    #
+    # +usage+ is the usage string, and +argv+ the command line (typically the
+    # global ARGV array). +name+ is the name of the program and defaults to the
+    # basename of the program
+    #
+    # Syntax errors in the usage string are caused by the developer and raise a
+    # +ShellOpts::CompilerError+ exception.  Errors in the +argv+ arguments are
+    # caused by the user and terminates the program with an error message and a
+    # short description of its usage
+    def initialize(usage, argv, name: PROGRAM, messenger: nil)
+      @name = name
+      begin
+        @grammar = Grammar.compile(name, usage)
+        @messenger = messenger || Messenger.new(name, @grammar.usage)
+        @ast = Ast.parse(@grammar, argv)
+        @idr = Idr.generate(@ast, @messenger)
+      rescue Grammar::Compiler::Error => ex
+        raise CompilerError.new(5, ex.message)
+      rescue Ast::Parser::Error => ex
+        error(ex.message)
+      end
+    end
+
+    # Return an array representation of options and commands in the same order
+    # as on the command line. Each option or command is represented by a [name,
+    # value] pair. The value of an option is be nil if the option didn't have
+    # an argument and else either a String, Integer, or Float. The value of a
+    # command is an array of its options and commands
+    def to_a() idr.to_a end
+
+    # Return a hash representation of the options. See {ShellOpts::OptionsHash}
+    def to_h(use: :key, aliases: {}) @idr.to_h(use: use, aliases: aliases) end
+
+    # Return a struct representation of the options. See {ShellOpts::OptionStruct}
+    def to_struct(use: :key, aliases: {}) @idr.to_struct(use: use, aliases: aliases) end
+
+    # List of remaining non-option command line arguments. Shorthand for +ast&.arguments+
+    def args() @ast&.arguments end
+
+    # Iterate options and commands as name/value pairs. Same as +to_a.each+
+    def each(&block) to_a.each(&block) end
+
+    # Print error messages and usage string and exit with status 1. This method
+    # should be called in response to user-errors (eg. specifying an illegal
+    # option)
+    def error(*msgs) @messenger.error(*msgs) end
+
+    # Print error message and exit with status 1. This method should called in
+    # response to system errors (like disk full)
+    def fail(*msgs) @messenger.fail(*msgs) end
+  end
+end
+
+

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module Shellopts
-  VERSION = "1.0.0"
+  VERSION = "2.0.0-1"
 end

data/rs

@@ -0,0 +1,40 @@
+#!/usr/bin/bash
+
+PROGRAM=$(basename $0)
+USAGE="SOURCE-FILE"
+
+function error() {
+    echo "$PROGRAM: $@"
+    echo "Usage: $PROGRAM $USAGE"
+    exit 1
+} >&2
+
+[ $# = 1 ] || error "Illegal number of arguments"
+SOURCE_NAME=${1%.rb}.rb
+
+GEM_FILE=$(ls *.gemspec 2>/dev/null)
+[ -n "$GEM_FILE" ] || error "Can't find gemspec file"
+GEM_NAME=${GEM_FILE%.gemspec}
+
+if [ -f lib/$SOURCE_NAME ]; then
+    SOURCE_FILE=lib/$SOURCE_NAME
+elif [ -f lib/$GEM_NAME/$SOURCE_NAME ]; then
+    SOURCE_FILE=lib/$GEM_NAME/$SOURCE_NAME
+else    
+    SOURCE_FILE=$(find lib/$GEM_NAME -type f -path $SOURCE_NAME | head -1)
+    if [ -z "$SOURCE_FILE" ]; then
+        SOURCE_FILE=lib/$GEM_NAME/$SOURCE_NAME
+    fi
+fi
+
+SPEC_FILE=spec/${SOURCE_NAME%.rb}_spec.rb
+[ -f $SPEC_FILE ] || error "Can't find spec file '$SPEC_FILE'"
+
+rspec --fail-fast $SPEC_FILE || { 
+    # rcov forgets a newline when rspec fails
+    status=$?; echo; exit $status;
+}
+
+
+
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shellopts
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0.pre.1
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-20 00:00:00.000000000 Z
+date: 2020-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -111,13 +111,19 @@ files:
 - lib/shellopts/ast/option.rb
 - lib/shellopts/ast/program.rb
 - lib/shellopts/compiler.rb
+- lib/shellopts/generator.rb
 - lib/shellopts/grammar/command.rb
 - lib/shellopts/grammar/node.rb
 - lib/shellopts/grammar/option.rb
 - lib/shellopts/grammar/program.rb
+- lib/shellopts/idr.rb
+- lib/shellopts/messenger.rb
+- lib/shellopts/option_struct.rb
 - lib/shellopts/parser.rb
+- lib/shellopts/shellopts.rb
 - lib/shellopts/utils.rb
 - lib/shellopts/version.rb
+- rs
 - shellopts.gemspec
 homepage: http://github.com/clrgit/shellopts
 licenses: []
@@ -134,9 +140,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.8
 signing_key: