shellopts 1.0.0 → 2.0.0.pre.7

data/lib/shellopts/option_struct.rb

@@ -0,0 +1,148 @@
+
+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/parser.rb

@@ -16,7 +16,7 @@ module ShellOpts
     end
 
   private
-    # Parse a command line
+    # Parse a subcommand line
     class Parser
       class Error < RuntimeError; end
 
@@ -27,24 +27,24 @@ module ShellOpts
 
       def call
         program = Ast::Program.new(@grammar)
-        parse_command(program)
+        parse_subcommand(program)
         program.arguments = @argv
         program
       end
 
     private
-      def parse_command(command)
-        @seen_options = {} # Every new command resets the seen options
+      def parse_subcommand(subcommand)
+        @seen_options = {} # Every new subcommand resets the seen options
         while arg = @argv.first
           if arg == "--"
             @argv.shift
             break
           elsif arg.start_with?("-")
-            parse_option(command)
-          elsif cmd = command.grammar.commands[arg]
+            parse_option(subcommand)
+          elsif cmd = subcommand.grammar.subcommands[arg]
             @argv.shift
-            command.command = Ast::Command.new(cmd, arg)
-            parse_command(command.command)
+            subcommand.subcommand = Ast::Command.new(cmd, arg)
+            parse_subcommand(subcommand.subcommand)
             break
           else
             break
@@ -52,7 +52,7 @@ module ShellOpts
         end
       end
 
-      def parse_option(command)
+      def parse_option(subcommand)
         # Split into name and argument
         case @argv.first
           when /^(--.+?)(?:=(.*))?$/
@@ -62,7 +62,7 @@ module ShellOpts
         end
         @argv.shift
 
-        option = command.grammar.options[name] or raise Error, "Unknown option '#{name}'"
+        option = subcommand.grammar.options[name] or raise Error, "Unknown option '#{name}'"
         !@seen_options.key?(option.key) || option.repeated? or raise Error, "Duplicate option '#{name}'"
         @seen_options[option.key] = true
 
@@ -83,7 +83,7 @@ module ShellOpts
           raise Error, "No argument allowed for option '#{name}'"
         end
 
-        command.options << Ast::Option.new(option, name, arg)
+        subcommand.options << Ast::Option.new(option, name, arg)
       end
 
       def parse_arg(option, name, arg)

data/lib/shellopts/shellopts.rb

@@ -0,0 +1,116 @@
+
+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 and use that to parse command line
+    # arguments
+    #
+    # +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 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 spec
+    #
+    # 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)
+        @ast = Ast.parse(@grammar, @argv)
+        @idr = Idr.generate(self)
+      rescue Grammar::Compiler::Error => ex
+        raise CompilerError.new(5, ex.message)
+      rescue Ast::Parser::Error => ex
+        raise UserError.new(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(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
+

data/lib/shellopts/version.rb

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

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.7
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-20 00:00:00.000000000 Z
+date: 2020-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -106,17 +106,21 @@ files:
 - doc/stylesheet.css
 - lib/ext/array.rb
 - lib/shellopts.rb
+- lib/shellopts/args.rb
 - lib/shellopts/ast/command.rb
 - lib/shellopts/ast/node.rb
 - 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/option_struct.rb
 - lib/shellopts/parser.rb
-- lib/shellopts/utils.rb
+- lib/shellopts/shellopts.rb
 - lib/shellopts/version.rb
 - shellopts.gemspec
 homepage: http://github.com/clrgit/shellopts
@@ -134,9 +138,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: 

data/lib/shellopts/utils.rb

@@ -1,16 +0,0 @@
-
-module ShellOpts
-  # Use `include ShellOpts::Utils` to include ShellOpts utility methods in the
-  # global namespace
-  module Utils
-    # Forwards to `ShellOpts.error`
-    def error(*msgs)
-      ::ShellOpts.error(*msgs)
-    end
-
-    # Forwards to `ShellOpts.fail`
-    def fail(*msgs)
-      ::ShellOpts.fail(*msgs)
-    end
-  end
-end