shellopts 0.9.1

data/lib/shellopts/compiler.rb

@@ -0,0 +1,130 @@
+require "ext/array.rb"
+
+require 'shellopts/grammar/node.rb'
+require 'shellopts/grammar/option.rb'
+require 'shellopts/grammar/command.rb'
+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 
+    # 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}"
+      source.is_a?(String) or raise Compiler::Error, "Expected String argument, got #{source.class}"
+      Compiler.new(program_name, source).call
+    end
+
+    # Service object for compiling an option definition string. Returns a 
+    # Grammar::Program object
+    #
+    # Compiler implements a recursive descend algorithm to compile the option
+    # string. The algorithm uses state variables and is embedded in a
+    # Grammar::Compiler service object 
+    class Compiler
+      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+/)
+
+        # @commands_by_path is an hash from command-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 = {}
+      end
+
+      def call
+        compile_program
+      end
+
+    private
+      using XArray # For Array#find_dup
+
+      # Returns the current token
+      def curr_token() @tokens.first end
+
+      # 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)
+        while curr_token && curr_token != "--"
+          compile_command
+        end
+        program.args.concat(@tokens[1..-1]) if curr_token
+        program
+      end
+
+      def compile_command
+        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}"
+        next_token
+        @commands_by_path[path] = Grammar::Command.new(parent, name, compile_options)
+      end
+
+      def compile_options
+        option_list = []
+        while curr_token && curr_token != "--" && !curr_token.end_with?("!")
+          option_list << compile_option
+        end
+        dup = option_list.map(&:names).flatten.find_dup and 
+            error "Duplicate option name: #{dup.inspect}"
+        option_list
+      end
+
+      def compile_option
+        # Match string and build flags
+        flags = []
+        curr_token =~ /^(\+)?(.+?)(?:(=)(\$|\#)?(.*?)(\?)?)?$/
+        flags << :repeated if $1 == "+"
+        names = $2
+        flags << :argument if $3 == "="
+        flags << :integer if $4 == "#"
+        flags << :float if $4 == "$"
+        label = $5 == "" ? nil : $5
+        flags << :optional if $6 == "?"
+
+        # Build names
+        short_names = []
+        long_names = []
+        ident_list = compile_ident_list(names, ",")
+        (dup = ident_list.find_dup).nil? or 
+            error "Duplicate identifier #{dup.inspect} in #{curr_token.inspect}"
+        ident_list.each { |ident|
+          if ident.size == 1
+            short_names << "-#{ident}"
+          else
+            long_names << "--#{ident}"
+          end
+        }
+
+        next_token
+        Grammar::Option.new(short_names, long_names, flags, label)
+      end
+
+      # Compile list of option names or a command 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 !~ /([^\w\d#{sep}-])/ or 
+              error "Illegal character #{$1.inspect} in #{curr_token.inspect}"
+          str
+        }
+      end
+    end
+  end
+end

data/lib/shellopts/grammar/command.rb

@@ -0,0 +1,64 @@
+module ShellOpts
+  module Grammar
+    # A command. Commands are organized hierarchically with a Program object as
+    # the root node
+    #
+    # Sets Node#key to the name of the command incl. the exclamation point
+    class Command < Node
+      # Parent command. Nil if this is the top level command (the program)
+      attr_reader :parent
+
+      # 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 
+
+      # List of options in declaration order
+      # order
+      attr_reader :option_list
+
+      # List of commands in declaration order
+      attr_reader :command_list
+
+      # 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
+        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
+
+      # :nocov:
+      def dump(&block)
+        puts "#{key.inspect}"
+        indent {
+          puts "parent: #{parent&.key.inspect}"
+          puts "name: #{name.inspect}"
+          yield if block_given?
+          puts "options:"
+          indent { option_list.each { |opt| opt.dump } }
+          puts "commands: "
+          indent { command_list.each { |cmd| cmd.dump } }
+        }
+      end
+      # :nocov:
+
+    protected
+      def attach(command)
+        command.instance_variable_set(:@parent, self)
+        @commands[command.name] = command
+        @command_list << command
+      end
+    end
+  end
+end

data/lib/shellopts/grammar/node.rb

@@ -0,0 +1,25 @@
+module ShellOpts
+  module Grammar
+    # Root class for Grammar objects
+    #
+    # Node objects are created by ShellOpts::Grammar.compile that returns a
+    # Program object that in turn contains other node objects in a hierarchical
+    # structure that reflects the grammar of the program. Only
+    # ShellOpts::Grammar.compile should create node objects
+    class Node
+      # Key (Symbol) of node. Unique within the enclosing command
+      attr_reader :key
+
+      def initialize(key)
+        @key = key
+      end
+
+      # :nocov:
+      def dump(&block) 
+        puts key.inspect
+        indent { yield } if block_given?
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/shellopts/grammar/option.rb

@@ -0,0 +1,55 @@
+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
+
+      # 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)
+        super((long_names.first || short_names.first).sub(/^-+/, "").to_sym)
+        @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
+
+      # 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

@@ -0,0 +1,65 @@
+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) + 
+          commands.values.map { |cmd| render_command(cmd) } + 
+          args
+        ).flatten.join(" ")
+      end
+
+      # :nocov:
+      def dump(&block)
+        super { 
+          puts "args: #{args.inspect}" 
+          puts "usage: #{usage.inspect}"
+        }
+      end
+      # :nocov:
+
+    private
+      def render_command(command)
+        [command.name] + render_options(command.option_list) + 
+            command.commands.values.map { |cmd| render_command(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/parser.rb

@@ -0,0 +1,106 @@
+
+require 'shellopts/ast/node.rb'
+require 'shellopts/ast/option.rb'
+require 'shellopts/ast/command.rb'
+require 'shellopts/ast/program.rb'
+
+module ShellOpts
+  module Ast
+    # Parse ARGV according to grammar. Returns a Ast::Program object
+    def self.parse(grammar, argv)
+      grammar.is_a?(Grammar::Program) or 
+          raise InternalError, "Expected Grammar::Program object, got #{grammar.class}"
+      argv.is_a?(Array) or
+          raise InternalError, "Expected Array object, got #{argv.class}"
+      Parser.new(grammar, argv).call
+    end
+
+  private
+    # Parse a command line
+    class Parser
+      class Error < RuntimeError; end
+
+      def initialize(grammar, argv)
+        @grammar, @argv = grammar, argv.dup
+        @seen_options = {} # Used to keep track of repeated options
+      end
+
+      def call
+        program = Ast::Program.new(@grammar)
+        parse_command(program)
+        program.arguments = @argv
+        program
+      end
+
+    private
+      def parse_command(command)
+        @seen_options = {} # Every new command 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]
+            @argv.shift
+            command.command = Ast::Command.new(cmd, arg)
+            parse_command(command.command)
+            break
+          else
+            break
+          end
+        end
+      end
+
+      def parse_option(command)
+        # Split into name and argument
+        case @argv.first
+          when /^(--.+?)(?:=(.*))?$/
+            name, arg, short = $1, $2, false
+          when /^(-.)(.+)?$/
+            name, arg, short = $1, $2, true
+        end
+        @argv.shift
+
+        option = command.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
+
+        # Parse (optional) argument
+        if option.argument?
+          if arg.nil? && !option.optional?
+            if !@argv.empty?
+              arg = @argv.shift
+            else
+              raise Error, "Missing argument for option '#{name}'"
+            end
+          end
+          arg &&= parse_arg(option, name, arg)
+        elsif arg && short
+          @argv.unshift("-#{arg}")
+          arg = nil
+        elsif !arg.nil?
+          raise Error, "No argument allowed for option '#{name}'"
+        end
+
+        command.options << Ast::Option.new(option, name, arg)
+      end
+
+      def parse_arg(option, name, arg)
+        if option.string?
+          arg
+        elsif arg == ""
+          nil
+        elsif option.integer?
+          arg =~ /^-?\d+$/ or raise Error, "Illegal integer in '#{name}' argument: '#{arg}'"
+          arg.to_i
+        else # option.float?
+          # https://stackoverflow.com/a/21891705/2130986
+          arg =~ /^[+-]?(?:0|[1-9]\d*)(?:\.(?:\d*[1-9]|0))?$/ or
+              raise Error, "Illegal float in '#{name}' argument: '#{arg}'"
+          arg.to_f
+        end
+      end
+    end
+  end
+end

data/lib/shellopts/version.rb

@@ -0,0 +1,3 @@
+module Shellopts
+  VERSION = "0.9.1"
+end

data/lib/shellopts.rb

@@ -0,0 +1,195 @@
+require "shellopts/version"
+
+require 'shellopts/compiler.rb'
+require 'shellopts/parser.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}
+#
+module ShellOpts
+  # 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 use the object methods
+  # #error and #fail instead:
+  #
+  #   shellopts = ShellOpts::ShellOpts.new(USAGE, ARGS)
+  #   shellopts.each { |name, value| ... }
+  #   shellopts.args.each { |arg| ... }
+  #   shellopts.error("Something went wrong")
+  #
+  def self.process(usage, argv, program_name: File.basename($0), &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
+    end
+  end
+
+  # Reset the hidden +ShellOpts::ShellOpts+ class variable so that you can process
+  # another command line
+  def self.reset()
+    @shellopts = nil
+  end
+
+  # Print error message and usage string and exit with status 1. Can only be
+  # called after #process. Forwards to {::ShellOpts#error}
+  def self.error(*msgs)
+    @shellopts&.error(*msgs) or raise InternalError, "ShellOpts class variable not initialized"
+  end
+
+  # Print error message and exit with status 1. Forwards to {::ShellOpts#fail}
+  def self.fail(*msgs)
+    @shellopts&.fail(*msgs) or raise InternalError, "ShellOpts class variable not initialized"
+  end
+
+  # The compilation object
+  class ShellOpts
+    # Name of program
+    attr_reader :program_name
+
+    # Usage string. 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
+
+    # Unroll the AST into a nested array
+    def to_a
+      @ast.values
+    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
+
+    # 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)
+      $stderr.puts "#{program_name}: #{msgs.join}"
+      $stderr.puts "Usage: #{program_name} #{usage}"
+      exit 1
+    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)
+      $stderr.puts "#{program_name}: #{msgs.join}"
+      exit 1
+    end
+  end
+
+  # Base class for ShellOpts exceptions
+  class Error < RuntimeError; 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
+  end
+
+  # Raised when an internal error is detected
+  class InternalError < Error; end
+
+private
+  @shellopts = nil
+end
+

data/shellopts.gemspec

@@ -0,0 +1,40 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "shellopts/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "shellopts"
+  spec.version       = Shellopts::VERSION
+  spec.authors       = ["Claus Rasmussen"]
+  spec.email         = ["claus.l.rasmussen@gmail.com"]
+
+  spec.summary       = %q{Parse command line options and arguments}
+  spec.description   = %q{ShellOpts is a simple command line parsing libray
+                          that covers most modern use cases incl. sub-commands.
+                          Options and commands are specified using a
+                          getopt(1)-like string that is interpreted by the
+                          library to process the command line}
+  spec.homepage      = "http://github.com/clrgit/shellopts"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0+ is required to protect against public gem pushes"
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "indented_io"
+  spec.add_development_dependency "simplecov"
+end