shellopts 2.0.0.pre.13 → 2.0.1

data/lib/shellopts/grammar/option.rb

@@ -1,66 +0,0 @@
-module ShellOpts
-  module Grammar
-    # Models an Option
-    #
-    # Sets Node#key to the first long option name if present or else the first short option
-    class Option < Node
-      # List of short names (incl. '-')
-      attr_reader :short_names
-
-      # 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
-
-      # Informal name of argument (eg. 'FILE'). nil if not present
-      attr_reader :label
-
-      # Initialize an option. Short and long names are arrays of the short/long
-      # option names (incl. the '-'/'--' prefix). It is assumed that at least
-      # one name is given. Flags is a list of symbolic flags. Allowed flags are
-      # :repeated, :argument, :optional, :integer, and :float. Note that
-      # 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)
-        @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
-      end
-
-      # 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
-      def optional?() argument? && @flags[:optional] || false end
-      def string?() argument? && !integer? && !float? end
-      def integer?() argument? && @flags[:integer] || false end
-      def float?() argument? && @flags[:float] || false end
-
-      # :nocov:
-      def dump
-        super {
-          puts "short_names: #{short_names.inspect}"
-          puts "long_names: #{long_names.inspect}"
-          puts "flags: #{flags.inspect}"
-          puts "label: #{label.inspect}"
-        }
-      end
-      # :nocov:
-    end
-  end
-end

data/lib/shellopts/grammar/program.rb

@@ -1,65 +0,0 @@
-module ShellOpts
-  module Grammar
-    # Program is the root object of the grammar
-    class Program < Command
-      # Array of non-option litteral arguments (ie. what comes after the double dash ('+--+') in
-      # the usage definition). Initially empty but filled out during compilation
-      attr_reader :args
-
-      # Initialize a top-level Program object
-      def initialize(name, option_list)
-        super(nil, name, option_list)
-        @args = []
-      end
-
-      # Usage string to be used in error messages. The string is kept short by
-      # only listing the shortest option (if there is more than one)
-      def usage
-        (
-          render_options(option_list) + 
-          subcommand_list.map { |cmd| render_subcommand(cmd) } + 
-          args
-        ).flatten.join(" ")
-      end
-
-      # :nocov:
-      def dump(&block)
-        super { 
-          puts "args: #{args.inspect}" 
-          puts "usage: #{usage.inspect}"
-        }
-      end
-      # :nocov:
-
-    private
-      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)
-        options.map { |opt|
-          s = opt.names.first
-          if opt.argument?
-            arg_string = 
-                if opt.label
-                  opt.label
-                elsif opt.integer?
-                  "INT"
-                elsif opt.float?
-                  "FLOAT"
-                else
-                  "ARG"
-                end
-            if opt.optional?
-              s += "[=#{arg_string}]"
-            else
-              s += "=#{arg_string}"
-            end
-          end
-          s
-        }
-      end
-    end
-  end
-end

data/lib/shellopts/idr.rb

@@ -1,236 +0,0 @@
-
-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
-

data/lib/shellopts/main.rb

@@ -1,10 +0,0 @@
-
-module ShellOpts
-  # Gives access to the ruby main object
-  module Main
-    CALLER_RE = /^.*:in `<main>'$/
-    def self.main() TOPLEVEL_BINDING.eval("self") end
-  end
-end
-
-

data/lib/shellopts/option_struct.rb

@@ -1,148 +0,0 @@
-
-require 'shellopts/shellopts.rb'
-require 'shellopts/idr'
-
-module ShellOpts
-  # FIXME: Outdated
-  #
-  # 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 OptionStruct object recursively from an Idr::Command object
-    def self.new(idr, key_type, aliases = {})
-      # Shorthands
-      ast = idr.instance_variable_get("@ast")
-      grammar = ast.grammar
-
-      # Get key map
-      keys = idr.send(:map_keys, key_type, aliases, RESERVED_WORDS)
-
-      # Allocate OptionStruct instance
-      instance = allocate
-
-      # Set reference to Idr object. Is currently unused
-      set_variable(instance, "@__idr__", idr)
-
-      # Generate general option accessor methods
-      grammar.option_list.each { |option|
-        key = keys[option.key]
-        instance.instance_eval("def #{key}() @#{key} end")
-        instance.instance_eval("def #{key}?() false end")
-      }
-
-      # Generate accessor method for present options
-      idr.option_list.each { |option|
-        key = keys[option.key]
-        set_variable(instance, "@#{key}", idr[option.key])
-        instance.instance_eval("def #{key}?() true end")
-      }
-
-      # Generate general #subcommand methods
-      if !idr.subcommand
-        instance.instance_eval("def subcommand() nil end")
-        instance.instance_eval("def subcommand?() false end")
-        instance.instance_eval %(
-            def subcommand!(*msgs)
-              $stderr.puts "in subcommand!"
-              ::Kernel.raise ::ShellOpts::UserError, (msgs.empty? ? 'No command' : msgs.join)
-            end
-        )
-      end
-
-      # Generate individual subcommand methods
-      grammar.subcommand_list.each { |subcommand|
-        key = keys[subcommand.key]
-        if subcommand.key == idr.subcommand&.key
-          struct = OptionStruct.new(idr.subcommand, key_type, 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!(*msgs) :#{key} 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
-
-    # Class method implementation of ObjectStruct#instance_variable_set that is
-    # not defined in a BasicObject
-    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
-
-    # Class method implementation of ObjectStruct#instance_variable_get that is
-    # not defined in a BasicObject
-    def self.get_variable(this, var)
-      # https://stackoverflow.com/a/18621313/2130986
-      ::Kernel.instance_method(:instance_variable_get).bind(this).call(var)
-    end
-
-    BASIC_OBJECT_RESERVED_WORDS = %w(
-         __id__ __send__ instance_eval instance_exec method_missing
-         singleton_method_added singleton_method_removed
-         singleton_method_undefined).map(&:to_sym)
-    OPTIONS_STRUCT_RESERVED_WORDS = %w(__idr__ subcommand).map(&:to_sym)
-    RESERVED_WORDS = BASIC_OBJECT_RESERVED_WORDS + OPTIONS_STRUCT_RESERVED_WORDS
-  end
-end
-

data/lib/shellopts/shellopts.rb

@@ -1,123 +0,0 @@
-
-require "shellopts"
-
-require "shellopts/args.rb"
-
-# TODO
-#
-# PROCESSING
-#   1. Compile spec 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
-    # Name of program
-    attr_accessor :name
-
-    # Usage string. If #usage is nil, the auto-generated default is used
-    def usage() @usage || @grammar.usage end
-    def usage=(usage) @usage = usage end
-
-    # Specification of the command
-    attr_reader :spec
-
-    # Original argv argument
-    attr_reader :argv
-
-    # The grammar compiled from the spec string
-    attr_reader :grammar
-
-    # The AST parsed from the command line arguments
-    attr_reader :ast
-
-    # The IDR generated from the Ast
-    attr_reader :idr
-
-    # Compile a spec string into a grammar
-    #
-    # +spec+ is the spec 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 spec string are caused by the developer and cause
-    # #initialize to raise a +ShellOpts::CompilerError+ exception. Errors in
-    # the +argv+ arguments are caused by the user and cause #process to raise
-    # ShellOpts::UserError exception
-    #
-    # TODO: Change to (name, spec, argv, usage: nil) because
-    # ShellOpts::ShellOpts isn't a magician like the ShellOpts module
-    def initialize(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage)
-      @name = name
-      @spec = spec
-      @usage = usage
-      @argv = argv
-      begin
-        @grammar = Grammar.compile(@name, @spec)
-      rescue Grammar::Compiler::Error => ex
-        raise CompilerError.new(5, ex.message)
-      end
-    end
-
-    # Process command line arguments and return self. Raises a
-    # ShellOpts::UserError in case of an error
-    def process
-      begin
-        @ast = Ast.parse(@grammar, @argv)
-        @idr = Idr.generate(self)
-      rescue Ast::Parser::Error => ex
-        raise UserError.new(ex.message)
-      end
-      self
-    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(key_type: ::ShellOpts.default_key_type, aliases: {})
-      @idr.to_h(key_type: :key_type, aliases: aliases) 
-    end
-
-    # TODO
-    # Return OptionHash object
-    # def to_hash(...)
-
-    # Return a struct representation of the options. See {ShellOpts::OptionStruct}
-    def to_struct(key_type: ::ShellOpts.default_key_type, aliases: {}) 
-      @idr.to_struct(key_type: key_type, aliases: aliases) 
-    end
-
-    # List of remaining non-option command line arguments. Returns a Argv object
-    def args() Args.new(self, 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 spec string and exit with status 1. This method
-    # should be called in response to user-errors (eg. specifying an illegal
-    # option)
-    def error(*msgs, exit: true)
-      msg = "#{name}: #{msgs.join}\n" + (@usage ? usage : "Usage: #{name} #{usage}")
-      $stderr.puts msg.rstrip
-      exit(1) if exit
-    end
-
-    # Print error message and exit with status 1. This method should called in
-    # response to system errors (like disk full)
-    def fail(*msgs, exit: true)
-      $stderr.puts "#{name}: #{msgs.join}"
-      exit(1) if exit
-    end
-  end
-end
-