shellopts 2.0.0.pre.13 → 2.0.1

data/lib/shellopts.rb

@@ -1,257 +1,476 @@
-require "shellopts/version"
 
-require 'shellopts/compiler.rb'
+$quiet = nil
+$verb = nil
+$debug = nil
+$shellopts = nil
+
+require 'indented_io'
+
+#$LOAD_PATH.unshift "../constrain/lib"
+require 'constrain'
+include Constrain
+
+require 'ext/array.rb'
+require 'ext/forward_to.rb'
+require 'ext/lcs.rb'
+include ForwardTo
+
+require 'shellopts/version.rb'
+
+require 'shellopts/stack.rb'
+require 'shellopts/token.rb'
+require 'shellopts/grammar.rb'
+require 'shellopts/program.rb'
+require 'shellopts/args.rb'
+require 'shellopts/lexer.rb'
+require 'shellopts/argument_type.rb'
 require 'shellopts/parser.rb'
-require 'shellopts/generator.rb'
-require 'shellopts/option_struct.rb'
-require 'shellopts/main.rb'
-
-# 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 spec 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)
-#
-# +args+ is a ShellOpts::Argv object containing the the remaning command line
-# arguments. Argv is derived from Array
-#
-# 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
-#
-# INCLUDING SHELLOPTS
-# 
-# ShellOpts can optionally be included in your shell application main file but
-# it is not supposed to be included anywhere else
-#
-# Some behind the scenes magic happen if you include the ShellOpts module in your
-# main exe file
-#
+require 'shellopts/analyzer.rb'
+require 'shellopts/interpreter.rb'
+require 'shellopts/ansi.rb'
+require 'shellopts/renderer.rb'
+require 'shellopts/formatter.rb'
+require 'shellopts/dump.rb'
+
+
 module ShellOpts
-  def self.default_name()
-    @default_name || defined?(PROGRAM) ? PROGRAM : File.basename($0)
+  # Base error class
+  #
+  # Note that errors in the usage of the ShellOpts library are reported using
+  # standard exceptions
+  #
+  class ShellOptsError < StandardError
+    attr_reader :token
+    def initialize(token)
+      super
+      @token = token
+    end
   end
 
-  def self.default_name=(name)
-    @default_name = name
-  end
+  # Raised on syntax errors on the command line (eg. unknown option). When
+  # ShellOpts handles the exception a message with the following format is
+  # printed on standard error:
+  #
+  #   <program>: <message>
+  #   Usage: <program> ...
+  #
+  class Error < ShellOptsError; end 
+
+  # Default class for program failures. Failures are raised on missing files or
+  # illegal paths. When ShellOpts handles the exception a message with the
+  # following format is printed on standard error:
+  #
+  #   <program>: <message>
+  #
+  class Failure < Error; end
+
+  # ShellOptsErrors during compilation. These errors are caused by syntax errors in the
+  # source. Messages are formatted as '<file> <lineno>:<charno> <message>' when
+  # handled by ShellOpts
+  class CompilerError < ShellOptsError; end
+  class LexerError < CompilerError; end 
+  class ParserError < CompilerError; end
+  class AnalyzerError < CompilerError; end
+
+  # Internal errors. These are caused by bugs in the ShellOpts library
+  class InternalError < ShellOptsError; end
+
+  class ShellOpts
+    using Ext::Array::ShiftWhile
+    using Ext::Array::PopWhile
+
+    # Name of program. Defaults to the name of the executable
+    attr_reader :name
+
+    # Specification (String). Initialized by #compile
+    attr_reader :spec
+
+    # Array of arguments. Initialized by #interpret
+    attr_reader :argv 
+
+    # Grammar. Grammar::Program object. Initialized by #compile
+    attr_reader :grammar
+
+    # Resulting ShellOpts::Program object containing options and optional
+    # subcommand. Initialized by #interpret
+    def program() @program end
+
+    # Array of remaining arguments. Initialized by #interpret
+    attr_reader :args
+
+    # Compiler flags
+    attr_accessor :stdopts
+    attr_accessor :msgopts
+
+    # Interpreter flags
+    attr_accessor :float
+
+    # True if ShellOpts lets exceptions through instead of writing an error
+    # message and exit
+    attr_accessor :exception
+
+    # File of source
+    attr_reader :file
+
+    # Debug: Internal variables made public
+    attr_reader :tokens
+    alias_method :ast, :grammar # Oops - defined earlier FIXME
+
+    def initialize(name: nil, stdopts: true, msgopts: false, float: true, exception: false)
+      @name = name || File.basename($PROGRAM_NAME)
+      @stdopts, @msgopts, @float, @exception = stdopts, msgopts, float, exception
+    end
 
-  def self.default_usage()
-    @default_usage || defined?(USAGE) ? USAGE : nil
-  end
+    # Compile source and return grammar object. Also sets #spec and #grammar.
+    # Returns the grammar
+    def compile(spec)
+      handle_exceptions {
+        @oneline = spec.index("\n").nil?
+        @spec = spec.sub(/^\s*\n/, "")
+        @file = find_caller_file
+        @tokens = Lexer.lex(name, @spec, @oneline)
+        ast = Parser.parse(tokens)
+        # TODO: Add standard and message options and their handlers
+        @grammar = Analyzer.analyze(ast)
+      }
+      self
+    end
 
-  def self.default_usage=(usage)
-    @default_usage = usage
-  end
+    # Use grammar to interpret arguments. Return a ShellOpts::Program and
+    # ShellOpts::Args tuple
+    #
+    def interpret(argv)
+      handle_exceptions { 
+        @argv = argv.dup
+        @program, @args = Interpreter.interpret(grammar, argv, float: float, exception: exception)
+      }
+      self
+    end
 
-  def self.default_key_type()
-    @default_key_type || ::ShellOpts::DEFAULT_KEY_TYPE
-  end
+    # Compile +spec+ and interpret +argv+. Returns a tuple of a
+    # ShellOpts::Program and ShellOpts::Args object
+    #
+    def process(spec, argv)
+      compile(spec)
+      interpret(argv)
+      self
+    end
 
-  def self.default_key_type=(type)
-    @default_key_type = type
-  end
+    # Create a ShellOpts object and sets the global instance, then process the
+    # spec and arguments. Returns a tuple of a ShellOpts::Program with the
+    # options and subcommands and a ShellOpts::Args object with the remaining
+    # arguments
+    #
+    def self.process(spec, argv, **opts)
+      ::ShellOpts.instance = shellopts = ShellOpts.new(**opts)
+      shellopts.process(spec, argv)
+      [shellopts.program, shellopts.args]
+    end
+
+    # Write short usage and error message to standard error and terminate
+    # program with status 1
+    #
+    # #error is supposed to be used when the user made an error and the usage
+    # is written to help correcting the error
+    #
+    def error(subject = nil, message)
+      saved = $stdout
+      $stdout = $stderr
+      $stderr.puts "#{name}: #{message}"
+      Formatter.usage(program)
+      exit 1
+    ensure
+      $stdout = saved
+    end
+
+    # Write error message to standard error and terminate program with status 1
+    #
+    # #failure is supposed to be used the used specified the correct arguments
+    # but something went wrong during processing. Since the used didn't cause
+    # the problem, only the error message is written
+    #
+    def failure(message)
+      $stderr.puts "#{name}: #{message}"
+      exit 1
+    end
 
-  # Result of the last as_* command
-  def self.opts() @opts end
-  def self.args() @args end
+    # Print usage
+    def usage() Formatter.usage(@grammar) end
 
-  # Base class for ShellOpts exceptions
-  class Error < RuntimeError; end
+    # Print brief help
+    def brief() Formatter.brief(@grammar) end
 
-  # Raised when a syntax error is detected in the spec string
-  class CompilerError < Error
-    def initialize(start, usage)
-      super(usage)
-      set_backtrace(caller(start))
+    # Print help for the given subject or the full documentation if +subject+
+    # is nil 
+    #
+    def help(subject = nil)
+      node = (subject ? @grammar[subject] : @grammar) or
+          raise ArgumentError, "No such command: '#{subject&.sub(".", " ")}'"
+      Formatter.help(node)
     end
-  end
 
-  # Raised when an error is detected in the command line
-  class ParserError < Error; end
-
-  # Raised when the command line error is caused by the user. It is raised by
-  # the parser but can also be used by the application if the command line
-  # fails a semantic check
-  class UserError < ParserError; end
-
-  # Raised when the error is caused by a failed assumption about the system. It
-  # is not raised by the ShellOpts library as it only concerns itself with
-  # command line syntax but can be used by the application to report a failure
-  # through ShellOpts#fail method when the ShellOpts module is included
-  class SystemFail < Error; end
-
-  # Raised when an error is detected during conversion from the Idr to array,
-  # hash, or struct
-  class ConversionError < Error; end
-
-  # Raised when an internal error is detected
-  class InternalError < Error; end
-
-  # The current compilation object. It is set by #process
-  def self.shellopts() @shellopts end
-
-  # Name of program
-  def program_name() shellopts!.name end
-  def program_name=(name) shellopts!.name = name end
-
-  # Usage string
-  def usage() shellopts!.spec end
-  def usage=(spec) shellopts!.spec = spec end
-
-  # Process command line, set current shellopts object, and return it.
-  # Remaining arguments from the command line can be accessed through
-  # +shellopts.args+
-  def self.process(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage) 
-    @shellopts.nil? or reset
-    @shellopts = ShellOpts.new(spec, argv, name: name, usage: usage)
-    @shellopts.process
-  end
+    def self.usage() ::ShellOpts.instance.usage end
+    def self.brief() ::ShellOpts.instance.brief end
+    def self.help(subject = nil) ::ShellOpts.instance.help(subject) end
+
+  private
+    def handle_exceptions(&block)
+      return yield if exception
+      begin
+        yield
+      rescue Error => ex
+        error(ex.message)
+      rescue Failure => ex
+        failure(ex.message)
+      rescue CompilerError => ex
+        filename = file =~ /\// ? file : "./#{file}"
+        lineno, charno = find_spec_in_file
+        charno = 1 if !@oneline
+        $stderr.puts "#{filename}:#{ex.token.pos(lineno, charno)} #{ex.message}"
+        exit(1)
+      end
+    end
 
-  # Process command line, set current shellopts object, and return a
-  # [Idr::Program, argv] tuple. Automatically includes the ShellOpts module
-  # if called from the main Ruby object (ie. your executable)
-  def self.as_program(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage) 
-    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
-    process(spec, argv, name: name, usage: usage)
-    @opts = shellopts.idr
-    @args = shellopts.args
-    [@opts, @args]
-  end
+    def find_caller_file
+      caller.reverse.select { |line| line !~ /^\s*#{__FILE__}:/ }.last.sub(/:.*/, "").sub(/^\.\//, "")
+    end
 
-  # Process command line, set current shellopts object, and return a [array,
-  # argv] tuple. Automatically includes the ShellOpts module if called from the
-  # main Ruby object (ie. your executable)
-  def self.as_array(spec, argv, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage)
-    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
-    process(spec, argv, name: name, usage: usage)
-    @opts = shellopts.to_a
-    @args = shellopts.args
-    [@opts, @args]
-  end
+    def self.compare_lines(text, spec)
+      return true if text == spec
+      return true if text =~ /[#\$\\]/
+      false
+    end
 
-  # Process command line, set current shellopts object, and return a [hash,
-  # argv] tuple. Automatically includes the ShellOpts module if called from the
-  # main Ruby object (ie. your executable)
-  def self.as_hash(
-      spec, argv, 
-      name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, 
-      key_type: ::ShellOpts.default_key_type, 
-      aliases: {})
-    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
-    process(spec, argv, name: name, usage: usage)
-    @opts = shellopts.to_h(key_type: key_type, aliases: aliases)
-    @args = shellopts.args
-    [@opts, @args]
-  end
+  public
+    # Find line and char index of spec in text. Returns [nil, nil] if not found
+    def self.find_spec_in_text(text, spec, oneline)
+      text_lines = text.split("\n")
+      spec_lines = spec.split("\n")
+      spec_lines.pop_while { |line| line =~ /^\s*$/ }
+
+      if oneline
+        line_i = nil
+        char_i = nil
+        char_z = 0
+
+        (0 ... text_lines.size).each { |text_i|
+          curr_char_i, curr_char_z = 
+              LCS.find_longest_common_substring_index(text_lines[text_i], spec_lines.first.strip)
+          if curr_char_z > char_z
+            line_i = text_i
+            char_i = curr_char_i
+            char_z = curr_char_z
+          end
+        }
+        line_i ? [line_i, char_i] : [nil, nil]
+      else
+        spec_string = spec_lines.first.strip
+        line_i = (0 ... text_lines.size - spec_lines.size + 1).find { |text_i|
+          (0 ... spec_lines.size).all? { |spec_i|
+            compare_lines(text_lines[text_i + spec_i], spec_lines[spec_i])
+          }
+        } or return [nil, nil]
+        char_i, char_z = 
+            LCS.find_longest_common_substring_index(text_lines[line_i], spec_lines.first.strip)
+        [line_i, char_i || 0]
+      end
+    end
+
+    def find_spec_in_file
+      self.class.find_spec_in_text(IO.read(@file), @spec, @oneline).map { |i| (i || 0) + 1 }
+    end
+
+    def lookup(name)
+      a = name.split(".")
+      cmd = grammar
+      while element = a.shift
+        cmd = cmd.commands[element]
+      end
+      cmd
+    end
 
-  # Process command line, set current shellopts object, and return a [struct,
-  # argv] tuple. Automatically includes the ShellOpts module if called from the
-  # main Ruby object (ie. your executable)
-  def self.as_struct(
-      spec, argv, 
-      name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, 
-      aliases: {})
-    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
-    process(spec, argv, name: name, usage: usage)
-    @opts = shellopts.to_struct(aliases: aliases)
-    @args = shellopts.args
-    [@opts, @args]
+    def find_subject(obj)
+      case obj
+        when String; lookup(obj)
+        when Ast::Command; Command.grammar(obj) # FIXME
+        when Grammar::Command; obj
+        when NilClass; grammar
+      else
+        raise Internal, "Illegal object: #{obj.class}"
+      end
+    end
   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. Automatically includes the ShellOpts module if called from the
-  # main Ruby object (ie. your executable)
-  def self.each(spec = nil, argv = nil, name: ::ShellOpts.default_name, usage: ::ShellOpts.default_usage, &block)
-    Main.main.send(:include, ::ShellOpts) if caller.last =~ Main::CALLER_RE
-    process(spec, argv, name: name, usage: usage)
-    @opts = shellopts.to_a
-    @args = shellopts.args
-    shellopts.each(&block)
+  def self.process(spec, argv, msgopts: false, **opts)
+    msgopts ||= Messages.is_included?
+    ShellOpts.process(spec, argv, msgopts: msgopts, **opts)
   end
 
-  # Print error usage and spec 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, exit: true)
-    shellopts!.error(msgs, exit: exit)
+  @instance = nil
+  def self.instance?() !@instance.nil? end
+  def self.instance() @instance or raise Error, "ShellOpts is not initialized" end
+  def self.instance=(instance) @instance = instance end
+
+  forward_self_to :instance, :error, :failure
+
+  # The Include module brings the reporting methods into the namespace when
+  # included
+  module Messages
+    @is_included = false
+    def self.is_included?() @is_included end
+    def self.include(...)
+      @is_included = true
+      super
+    end
+
+    def notice(message)
+      $stderr.puts "#{name}: #{message}" if !quiet?
+    end
+
+    def mesg(message)
+      $stdout.puts message if !quiet?
+    end
+
+    def verb(level = 1, message)
+      $stdout.puts message if level <= @verbose
+    end
+
+    def debug(message)
+      $stdout.puts message if debug?
+    end
   end
 
-  # Print error usage and exit with status 1. This method should not be
-  # called in response to system errors (eg. disk full)
-  def self.fail(*msgs, exit: true)
-    shellopts!.fail(*msgs, exit: exit)
+  module ErrorHandling
+    # TODO: Set up global exception handlers
   end
+end
+
+
+
+
+
+
+
+
+__END__
+
+require "shellopts/version"
+
+require "ext/algorithm.rb"
+require "ext/ruby_env.rb"
+
+require "shellopts/constants.rb"
+require "shellopts/exceptions.rb"
+
+require "shellopts/grammar/analyzer.rb"
+require "shellopts/grammar/lexer.rb"
+require "shellopts/grammar/parser.rb"
+require "shellopts/grammar/command.rb"
+require "shellopts/grammar/option.rb"
+
+require "shellopts/ast/parser.rb"
+require "shellopts/ast/command.rb"
+require "shellopts/ast/option.rb"
+
+require "shellopts/args.rb"
+require "shellopts/formatter.rb"
 
-  def self.included(base)
-    # base.equal?(Object) is only true when included in main (we hope)
-    if !@is_included_in_main && base.equal?(Object) 
-      @is_included_in_main = true
-      at_exit do
-        case $!
-          when ShellOpts::UserError
-            ::ShellOpts.error($!.message, exit: false)
-            exit!(1)
-          when ShellOpts::SystemFail
-            ::ShellOpts.fail($!.message)
-            exit!(1)
-        end
+if RUBY_ENV == "development"
+  require "shellopts/grammar/dump.rb"
+  require "shellopts/ast/dump.rb"
+end
+
+$verb = nil
+$quiet = nil
+$shellopts = nil
+
+module ShellOpts
+  class ShellOpts
+    attr_reader :name # Name of program. Defaults to the name of the executable
+    attr_reader :spec
+    attr_reader :argv
+
+    attr_reader :grammar
+    attr_reader :program
+    attr_reader :arguments
+
+    def initialize(spec, argv, name: nil, exception: false)
+      @name = name || File.basename($PROGRAM_NAME)
+      @spec, @argv = spec, argv.dup
+      exprs = Grammar::Lexer.lex(@spec)
+      commands = Grammar::Parser.parse(@name, exprs)
+      @grammar = Grammar::Analyzer.analyze(commands)
+
+      begin
+        @program, @arguments = Ast::Parser.parse(@grammar, @argv)
+      rescue Error => ex
+        raise if exception
+        error(ex.subject, ex.message)
+      end
+    end
+
+    def error(subject = nil, message)
+      $stderr.puts "#{name}: #{message}"
+      usage(subject, device: $stderr)
+      exit 1
+    end
+
+    def fail(message)
+      $stderr.puts "#{name}: #{message}"
+      exit 1
+    end
+
+    def usage(subject = nil, device: $stdout, levels: 1, margin: "")
+      subject = find_subject(subject)
+      device.puts Formatter.usage_string(subject, levels: levels, margin: margin)
+    end
+
+    def help(subject = nil, device: $stdout, levels: 10, margin: "", tab: "  ")
+      subject = find_subject(subject)
+      device.puts Formatter.help_string(subject, levels: levels, margin: margin, tab: tab)
+    end
+
+  private
+    def lookup(name)
+      a = name.split(".")
+      cmd = grammar
+      while element = a.shift
+        cmd = cmd.commands[element]
+      end
+      cmd
+    end
+
+    def find_subject(obj)
+      case obj
+        when String; lookup(obj)
+        when Ast::Command; Command.grammar(obj)
+        when Grammar::Command; obj
+        when NilClass; grammar
+      else
+        raise Internal, "Illegal object: #{obj.class}"
       end
     end
-    super
   end
 
-private
-  # Default default key type
-  DEFAULT_KEY_TYPE = :name
+  def self.process(spec, argv, name: nil, exception: false)
+    $shellopts = ShellOpts.new(spec, argv, name: name, exception: exception)
+    [$shellopts.program, $shellopts.arguments]
+  end
 
-  # Reset state variables
-  def self.reset()
-    @shellopts = nil
+  def self.error(subject = nil, message)
+    $shellopts.error(subject, message)
   end
 
-  # (shorthand) Raise an InternalError if shellopts is nil. Return shellopts
-  def self.shellopts!
-    ::ShellOpts.shellopts or raise UserError, "No ShellOpts.shellopts object"
+  def self.fail(message)
+    $shellopts.fail(message)
   end
 
-  @shellopts = nil
-  @is_included_in_main = false
+  def self.help(subject = nil, device: $stdout, levels: 10, margin: "", tab: "  ")
+    $shellopts.help(subject, device: device, levels: levels, margin: margin, tab: tab)
+  end
+
+  def self.usage(subject = nil, device: $stdout, levels: 1, margin: "")
+    $shellopts.usage(subject, device: device, levels: levels, margin: margin)
+  end
 end