shellopts 1.0.0 → 2.0.0.pre.7

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/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,14 +26,14 @@ 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
+        # @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(@program_name, compile_options)
+        program = @subcommands_by_path[nil] = Grammar::Program.new(@name, compile_options)
         while curr_token && curr_token != "--"
-          compile_command
+          compile_subcommand
         end
         program.args.concat(@tokens[1..-1]) if curr_token
         program
       end
 
-      def compile_command
+      def compile_subcommand
         path = curr_token[0..-2]
         ident_list = compile_ident_list(path, ".")
         parent_path = ident_list.size > 1 ? ident_list[0..-2].join(".") : nil
         name = ident_list[-1]
 
-        parent = @commands_by_path[parent_path] or
-            error "No such command: #{parent_path.inspect}"
-        !@commands_by_path.key?(path) or error "Duplicate command: #{path.inspect}"
+        parent = @subcommands_by_path[parent_path] or
+            raise Compiler::Error, "No such subcommand: #{parent_path.inspect}"
+        !@subcommands_by_path.key?(path) or raise Compiler::Error, "Duplicate subcommand: #{path.inspect}"
         next_token
-        @commands_by_path[path] = Grammar::Command.new(parent, name, compile_options)
+        @subcommands_by_path[path] = Grammar::Command.new(parent, name, compile_options)
       end
 
       def compile_options
@@ -81,7 +77,7 @@ module ShellOpts
           option_list << compile_option
         end
         dup = option_list.map(&:names).flatten.find_dup and 
-            error "Duplicate option name: #{dup.inspect}"
+            raise Compiler::Error, "Duplicate option name: #{dup.inspect}"
         option_list
       end
 
@@ -102,7 +98,7 @@ module ShellOpts
         long_names = []
         ident_list = compile_ident_list(names, ",")
         (dup = ident_list.find_dup).nil? or 
-            error "Duplicate identifier #{dup.inspect} in #{curr_token.inspect}"
+            raise Compiler::Error, "Duplicate identifier #{dup.inspect} in #{curr_token.inspect}"
         ident_list.each { |ident|
           if ident.size == 1
             short_names << "-#{ident}"
@@ -115,13 +111,15 @@ module ShellOpts
         Grammar::Option.new(short_names, long_names, flags, label)
       end
 
-      # Compile list of option names or a command path
+      # Compile list of option names or a subcommand path
       def compile_ident_list(ident_list_str, sep)
         ident_list_str.split(sep, -1).map { |str| 
-          !str.empty? or error "Empty identifier in #{curr_token.inspect}"
-          !str.start_with?("-") or error "Identifier can't start with '-' in #{curr_token.inspect}"
+          !str.empty? or 
+              raise Compiler::Error, "Empty identifier in #{curr_token.inspect}"
+          !str.start_with?("-") or 
+              raise Compiler::Error, "Identifier can't start with '-' in #{curr_token.inspect}"
           str !~ /([^\w\d#{sep}-])/ or 
-              error "Illegal character #{$1.inspect} in #{curr_token.inspect}"
+              raise Compiler::Error, "Illegal character #{$1.inspect} in #{curr_token.inspect}"
           str
         }
       end

data/lib/shellopts/generator.rb

@@ -0,0 +1,15 @@
+
+require 'shellopts/idr.rb'
+
+module ShellOpts
+  module Idr
+    # Generates an Idr::Program from a ShellOpts object
+    def self.generate(shellopts)
+      Idr::Program.new(shellopts)
+    end
+  end
+end
+
+
+
+

data/lib/shellopts/grammar/command.rb

@@ -11,32 +11,50 @@ 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
 
       # List of commands in declaration order
-      attr_reader :command_list
+      attr_reader :subcommand_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 subcommands()
+        @subcommand_multihash ||= @subcommand_list.flat_map { |subcommand| 
+          subcommand.identifiers.map { |name| [name, subcommand] }
+        }.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
       def initialize(parent, name, option_list)
-        super("#{name}!".to_sym)
-        @name = name
+        super("#{name}!".to_sym, 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 = []
+        @subcommand_list = []
       end
 
+      # Return key for the identifier
+      def identifier2key(ident)
+        options[ident]&.key || subcommands[ident]&.key
+      end
+
+      # Return list of identifiers for the command
+      def identifiers() [key, name] end
+
       # :nocov:
       def dump(&block)
         puts "#{key.inspect}"
@@ -46,17 +64,16 @@ module ShellOpts
           yield if block_given?
           puts "options:"
           indent { option_list.each { |opt| opt.dump } }
-          puts "commands: "
-          indent { command_list.each { |cmd| cmd.dump } }
+          puts "subcommands: "
+          indent { subcommand_list.each { |cmd| cmd.dump } }
         }
       end
       # :nocov:
 
     protected
-      def attach(command)
-        command.instance_variable_set(:@parent, self)
-        @commands[command.name] = command
-        @command_list << command
+      def attach(subcommand)
+        subcommand.instance_variable_set(:@parent, self)
+        @subcommand_list << subcommand
       end
     end
   end

data/lib/shellopts/grammar/node.rb

@@ -10,14 +10,22 @@ module ShellOpts
       # Key (Symbol) of node. Unique within the enclosing command
       attr_reader :key
 
-      def initialize(key)
-        @key = key
+      # Name of node. The name of an option is without the prefixed '-' or
+      # '--', the name of a command is without the suffixed '!'. Note that name
+      # collisions can happen between options and commands names
+      attr_reader :name
+
+      def initialize(key, name)
+        @key, @name = key, name
       end
 
       # :nocov:
       def dump(&block) 
         puts key.inspect
-        indent { yield } if block_given?
+        indent { 
+          puts "name: #{name.inspect}"
+          yield if block_given?
+        }
       end
       # :nocov:
     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,9 @@ 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
+        name = @key_name.sub(/^-+/, "")
+        super(name.to_sym, name)
         @short_names, @long_names = short_names, long_names
         @flags = flags.map { |flag| [flag, true] }.to_h
         @label = label
@@ -32,6 +37,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) } + 
+          subcommand_list.map { |cmd| render_subcommand(cmd) } + 
           args
         ).flatten.join(" ")
       end
@@ -32,9 +32,9 @@ module ShellOpts
       # :nocov:
 
     private
-      def render_command(command)
-        [command.name] + render_options(command.option_list) + 
-            command.commands.values.map { |cmd| render_command(cmd) }.flatten
+      def render_subcommand(subcommand)
+        [subcommand.name] + render_options(subcommand.option_list) + 
+            subcommand.subcommand_list.map { |cmd| render_subcommand(cmd) }.flatten
       end
 
       def render_options(options)

data/lib/shellopts/idr.rb

@@ -0,0 +1,236 @@
+
+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
+      # Parent node. nil for the top-level Program object
+      attr_reader :parent
+
+      # Unique key (within context) for the option or command. nil for the
+      # top-level Program object
+      attr_reader :key
+
+      # Name of command or 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
+
+      # The top-level Program object
+      def program() @program ||= (parent&.program || self) end
+
+    protected
+      # Copy arguments into instance variables
+      def initialize(parent, ast, key, name, value)
+        @parent, @ast, @key, @name, @value = parent, 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(parent, ast)
+        value = ast.grammar.argument? ? ast.value : true
+        super(parent, 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(parent, key, name, options)
+        @names = options.map(&:name)
+        super(parent, 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) || subcommand?(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 subcommand?(ident) grammar.subcommands.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. TODO
+      def apply(defaults = {}) raise InternalError, "Not implemented" 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_type+ controls the type of keys used: +:key+ (the default) use the
+      # symbolic key, +:name+ use #name. Note that using +:name+ can cause
+      # name collisions between option and command names
+      #
+      # +aliases+ maps from key to replacement key (which could be any object).
+      # +aliases+ can be used to avoid name collisions between options and
+      # commands when using key_format: :name
+      #
+      # IDEA: Add a singleton methods to the hash with #name, #usage, etc.
+      #
+      def to_h(key_type: ::ShellOpts.default_key_type, aliases: {})
+        keys = map_keys(key_type, aliases)
+        value = {}
+        value.define_singleton_method(:subcommand) { nil }
+        options.values.each { |opt| # includes subcommand
+          key = keys[opt.key]
+          case opt
+            when Option
+              value[key] = opt.value
+            when Command
+              value[key] = opt.value.to_h(key_type: key_type, aliases: aliases[opt.key] || {})
+              value.define_singleton_method(:subcommand) { key } # Redefine
+          else
+            # :nocov:
+            raise InternalError, "Oops"
+            # :nocov:
+          end
+        }
+        value
+      end
+
+      # Return options and command as a struct
+      def to_struct(key_type: ::ShellOpts.default_key_type, aliases: {})
+        OptionStruct.new(self, key_type, aliases) 
+      end
+
+    protected
+      # Initialize an Idr::Command object and all dependent objects
+      def initialize(parent, ast)
+        super(parent, ast, ast.key, ast.name, self)
+        @option_list = ast.options.map { |node| SimpleOption.new(self, node) }
+        @subcommand = Command.new(self, ast.subcommand) if ast.subcommand
+        @options = @option_list.group_by { |option| option.key }.map { |key, option_list|
+          option = 
+              if ast.grammar.options[key].repeated?
+                OptionGroup.new(self, 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
+
+      # Internal-key to used-key map. Checks for reserved words and
+      # name-collisions
+      def map_keys(key_type, aliases, reserved_words = [])
+        keys = {}
+        used_keys = {}
+        (grammar.option_list + grammar.subcommand_list).each { |node|
+          internal_key = node.key
+          key = aliases[internal_key] || (key_type == :name ? node.name.to_sym : internal_key)
+          !reserved_words.include?(key) or
+              raise ::ShellOpts::ConversionError, "'#{key}' is a reserved word"
+          !used_keys.key?(key) or 
+              raise ::ShellOpts::ConversionError, "Name collision between '--#{key}' and '#{key}!'"
+          keys[internal_key] = key
+          used_keys[key] = true
+        }
+        keys
+      end
+    end
+
+    class Program < Command
+      # Name of program
+      def name() @shellopts.name end
+      def name=(name) @shellopts.name = name end
+
+      # Usage string
+      def usage() @shellopts.usage end
+      def usage=(usage) @shellopts.usage = usage end
+
+      # #key is nil for the top-level Program object
+      def key() nil end
+
+      # Remaining command line arguments
+      def args() @shellopts.args end
+
+      # Initialize the top-level Idr::Program object
+      def initialize(shellopts)
+        @shellopts = shellopts
+        super(nil, shellopts.ast)
+      end
+
+      # Emit error message and a usage description before exiting with status 1
+      def error(*args) @shellopts.error(*error_messages) end
+
+      # Emit error message before exiting with status 1
+      def fail(*args) @shellopts.fail(*error_messages) end
+    end
+  end
+end
+