shellopts 2.0.0.pre.14 → 2.0.0

data/lib/shellopts/renderer.rb

@@ -0,0 +1,227 @@
+require 'terminfo'
+
+# Option rendering
+#   -a, --all                   # Only used in brief and doc formats (enum)
+#   --all                       # Only used in usage (long)
+#   -a                          # Only used in usage (short)
+#
+# Option group rendering
+#   -a, --all  -b, --beta       # Only used in brief formats (enum)
+#   --all --beta                # Used in usage (long)
+#   -a -b                       # Used in usage (short)
+#
+#   -a, --all                   # Only used in doc format (:multi)
+#   -b, --beta
+#
+# Command rendering
+#   cmd --all --beta [cmd1|cmd2] ARG1 ARG2    # Single-line formats (:single)
+#   cmd --all --beta [cmd1|cmd2] ARGS...     
+#   cmd -a -b [cmd1|cmd2] ARG1 ARG2
+#   cmd -a -b [cmd1|cmd2] ARGS...
+#
+#   cmd -a -b [cmd1|cmd2] ARG1 ARG2           # One line for each argument description (:enum)
+#   cmd -a -b [cmd1|cmd2] ARG3 ARG4           # (used in the USAGE section)
+#
+#   cmd --all --beta                          # Multi-line formats (:multi)
+#       [cmd1|cmd2] ARG1 ARG2
+#   cmd --all --beta
+#       <commands> ARGS
+#   
+module ShellOpts
+  module Grammar
+    class Option
+      # Formats:
+      #
+      #   :enum     -a, --all
+      #   :long     --all
+      #   :short    -a
+      #
+      def render(format)
+        constrain format, :enum, :long, :short
+        case format
+          when :enum; names.join(", ")
+          when :long; name
+          when :short; short_names.first || name
+        else
+          raise ArgumentError, "Illegal format: #{format.inspect}"
+        end + (argument? ? "=#{argument_name}" : "")
+      end
+    end
+
+    class OptionGroup
+      # Formats:
+      #     
+      #     :enum   -a, --all -r, --recursive
+      #     :long   --all --recursive
+      #     :short  -a -r
+      #     :multi  -a, --all
+      #             -r, --recursive
+      #
+      def render(format)
+        constrain format, :enum, :long, :short, :multi
+        if format == :multi
+          options.map { |option| option.render(:enum) }.join("\n")
+        else
+          options.map { |option| option.render(format) }.join(" ")
+        end
+      end
+    end
+
+    # brief one-line commands should optionally use compact options
+    class Command
+      using Ext::Array::Wrap
+
+      OPTIONS_ABBR = "[OPTIONS]"
+      COMMANDS_ABBR = "[COMMANDS]"
+      DESCRS_ABBR = "ARGS..."
+
+      # Format can be one of :single, :enum, or :multi. :single force one-line
+      # output and compacts options and commands if needed. :enum outputs a
+      # :single line for each argument specification/description, :multi tries
+      # one-line output but wrap options if needed. Multiple argument
+      # specifications/descriptions are always compacted
+      #
+      def render(format, width, root: false, **opts)
+        case format
+          when :single; render_single(width, **opts)
+          when :enum; render_enum(width, **opts)
+          when :multi; render_multi2(width, **opts)
+        else
+          raise ArgumentError, "Illegal format: #{format.inspect}"
+        end
+      end
+
+      def names(root: false)
+        (root ? ancestors : []) + [self]
+      end
+
+    protected
+      # Force one line. Compact options, commands, arguments if needed
+      def render_single(width, args: nil)
+        long_options = options.map { |option| option.render(:long) }
+        short_options = options.map { |option| option.render(:short) }
+        compact_options = options.empty? ? [] : [OPTIONS_ABBR]
+        short_commands = commands.empty? ? [] : ["[#{commands.map(&:name).join("|")}]"]
+        compact_commands = commands.empty? ? [] : [COMMANDS_ABBR]
+
+        # TODO: Refactor and implement recursive detection of any argument
+        args ||= 
+            case descrs.size
+              when 0; args = []
+              when 1; [descrs.first.text]
+              else [DESCRS_ABBR]
+            end
+
+        begin # to be able to use 'break' below
+          words = [name] + long_options + short_commands + args
+          break if pass?(words, width)
+          words = [name] + short_options + short_commands + args
+          break if pass?(words, width)
+          words = [name] + long_options + compact_commands + args
+          break if pass?(words, width)
+          words = [name] + short_options + compact_commands + args
+          break if pass?(words, width)
+          words = [name] + compact_options + short_commands + args
+          break if pass?(words, width)
+          words = [name] + compact_options + compact_commands + args
+          break if pass?(words, width)
+          words = [name] + compact_options + compact_commands + [DESCRS_ABBR]
+        end while false
+        words.join(" ")
+      end
+
+      # Render one line for each argument specification/description
+      def render_enum(width)
+        # TODO: Also refactor args here
+        args_texts = self.descrs.empty? ? [""] : descrs.map(&:text)
+        args_texts.map { |args_text| render_single(width, args: [args_text]) }
+      end
+
+      # Render the description using the given method (:single, :multi)
+      def render_descr(method, width, descr)
+        send.send method, width, args: descr
+      end
+
+      # Try to keep on one line but wrap options if needed. Multiple argument
+      # specifications/descriptions are always compacted
+      def render_multi(width, args: nil)
+        long_options = options.map { |option| option.render(:long) }
+        short_options = options.map { |option| option.render(:short) }
+        short_commands = commands.empty? ? [] : ["[#{commands.map(&:name).join("|")}]"]
+        compact_commands = [COMMANDS_ABBR]
+        args ||= self.descrs.size != 1 ? [DESCRS_ABBR] : descrs.map(&:text)
+
+        # On one line
+        words = long_options + short_commands + args
+        return [words.join(" ")] if pass?(words, width)
+        words = short_options + short_commands + args
+        return [words.join(" ")] if pass?(words, width)
+
+        # On multiple lines
+        options = long_options.wrap(width)
+        commands = [[short_commands, args].join(" ")]
+        return options + commands if pass?(commands, width)
+        options + [[compact_commands, args].join(" ")]
+      end
+
+      # Try to keep on one line but wrap options if needed. Multiple argument
+      # specifications/descriptions are always compacted
+      def render_multi2(width, args: nil)
+        long_options = options.map { |option| option.render(:long) }
+        short_options = options.map { |option| option.render(:short) }
+        short_commands = commands.empty? ? [] : ["[#{commands.map(&:name).join("|")}]"]
+        compact_commands = [COMMANDS_ABBR]
+
+        # TODO: Refactor and implement recursive detection of any argument
+        args ||= 
+            case descrs.size
+              when 0; args = []
+              when 1; [descrs.first.text]
+              else [DESCRS_ABBR]
+            end
+
+        # On one line
+        words = [name] + long_options + short_commands + args
+        return [words.join(" ")] if pass?(words, width)
+        words = [name] + short_options + short_commands + args
+        return [words.join(" ")] if pass?(words, width)
+
+        # On multiple lines
+        lead = name + " "
+        options = long_options.wrap(width - lead.size)
+        options = [lead + options[0]] + indent_lines(lead.size, options[1..-1])
+
+        begin
+          words = short_commands + args
+          break if pass?(words, width)
+          words = compact_commands + args
+          break if pass?(words, width)
+          words = compact_commands + [DESCRS_ABBR]
+        end while false
+
+        cmdargs = words.empty? ? [] : [words.join(" ")]
+        options + indent_lines(lead.size, cmdargs)
+      end
+
+    protected
+      # Helper method that returns true if words can fit in width characters
+      def pass?(words, width)
+        words.sum(&:size) + words.size - 1 <= width
+      end
+
+      # Indent array of lines
+      def indent_lines(indent, lines)
+        indent = [indent, 0].max
+        lines.map { |line| ' ' * indent + line }
+      end
+    end
+  end
+end
+
+
+
+
+
+
+
+

data/lib/shellopts/stack.rb

@@ -0,0 +1,7 @@
+module ShellOpts
+  module Stack
+    refine Array do
+      def top() last end
+    end
+  end
+end

data/lib/shellopts/token.rb

@@ -0,0 +1,44 @@
+
+module ShellOpts
+  class Token
+    # Each kind should have a corresponding Grammar class with the same name
+    KINDS = [
+        :program, :section, :option, :command, :spec, :argument, :usage,
+        :usage_string, :brief, :text, :blank 
+    ]
+
+    # Kind of token
+    attr_reader :kind
+
+    # Line number (one-based)
+    attr_reader :lineno
+
+    # Char number (one-based). The lexer may adjust the char number (eg. for
+    # blank lines)
+    attr_accessor :charno
+
+    # Source of the token
+    attr_reader :source
+
+    def initialize(kind, lineno, charno, source)
+      constrain kind, :program, *KINDS
+      @kind, @lineno, @charno, @source = kind, lineno, charno, source
+    end
+
+    forward_to :source, :to_s, :empty?
+
+    def pos(start_lineno = 1, start_charno = 1) 
+      "#{start_lineno + lineno - 1}:#{start_charno + charno - 1}" 
+    end
+
+    def to_s() source end
+
+    def inspect() 
+      "<#{self.class.to_s.sub(/.*::/, "")} #{pos} #{kind.inspect} #{source.inspect}>"
+    end
+
+    def dump
+      puts "#{kind}@#{lineno}:#{charno} #{source.inspect}"
+    end
+  end
+end

data/lib/shellopts/version.rb

@@ -1,3 +1,3 @@
 module ShellOpts
-  VERSION = "2.0.0.pre.14"
+  VERSION = "2.0.0"
 end

data/lib/shellopts.rb

@@ -1,3 +1,358 @@
+
+$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/lexer.rb'
+require 'shellopts/argument_type.rb'
+require 'shellopts/parser.rb'
+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
+  # 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
+
+  # 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
+
+    # 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
+
+    # 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
+
+    # 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
+
+    # 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.argv]
+    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
+
+    # Print usage
+    def usage() Formatter.usage(@grammar) end
+
+    # Print brief help
+    def brief() Formatter.brief(@grammar) end
+
+    # 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
+
+    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
+
+    def find_caller_file
+      caller.reverse.select { |line| line !~ /^\s*#{__FILE__}:/ }.last.sub(/:.*/, "").sub(/^\.\//, "")
+    end
+
+    def self.compare_lines(text, spec)
+      return true if text == spec
+      return true if text =~ /[#\$\\]/
+      false
+    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
+
+    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
+
+  def self.process(spec, argv, msgopts: false, **opts)
+    msgopts ||= Messages.is_included?
+    ShellOpts.process(spec, argv, msgopts: msgopts, **opts)
+  end
+
+  @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
+
+  module ErrorHandling
+    # TODO: Set up global exception handlers
+  end
+end
+
+
+
+
+
+
+
+
+__END__
+
 require "shellopts/version"
 
 require "ext/algorithm.rb"
@@ -38,7 +393,7 @@ module ShellOpts
     attr_reader :program
     attr_reader :arguments
 
-    def initialize(spec, argv, name: nil)
+    def initialize(spec, argv, name: nil, exception: false)
       @name = name || File.basename($PROGRAM_NAME)
       @spec, @argv = spec, argv.dup
       exprs = Grammar::Lexer.lex(@spec)
@@ -48,6 +403,7 @@ module ShellOpts
       begin
         @program, @arguments = Ast::Parser.parse(@grammar, @argv)
       rescue Error => ex
+        raise if exception
         error(ex.subject, ex.message)
       end
     end
@@ -95,8 +451,8 @@ module ShellOpts
     end
   end
 
-  def self.process(spec, argv, name: nil)
-    $shellopts = ShellOpts.new(spec, argv, name: name)
+  def self.process(spec, argv, name: nil, exception: false)
+    $shellopts = ShellOpts.new(spec, argv, name: name, exception: exception)
     [$shellopts.program, $shellopts.arguments]
   end