shellopts 2.0.0.pre.13 → 2.0.1

data/lib/shellopts/args.rb

@@ -3,36 +3,36 @@ module ShellOpts
   # Specialization of Array for arguments lists. Args extends Array with a
   # #extract and an #expect method to extract elements from the array. The
   # methods raise a ShellOpts::UserError exception in case of errors
+  #
   class Args < Array
-    def initialize(shellopts, *args)
-      @shellopts = shellopts
-      super(*args)
-    end
-
     # Remove and return elements from beginning of the array
     #
     # If +count_or_range+ is a number, that number of elements will be
     # returned.  If the count is one, a simple value is returned instead of an
-    # array.  If the count is negative, the elements will be removed from the
+    # array. If the count is negative, the elements will be removed from the
     # end of the array. If +count_or_range+ is a range, the number of elements
     # returned will be in that range. The range can't contain negative numbers 
     #
     # #extract raise a ShellOpts::UserError exception if there's is not enough
     # elements in the array to satisfy the request
+    #
     def extract(count_or_range, message = nil) 
-      if count_or_range.is_a?(Range)
-        range = count_or_range
-        range.min <= self.size or inoa(message)
-        n_extract = [self.size, range.max].min
-        n_extend = range.max > self.size ? range.max - self.size : 0
-        r = self.shift(n_extract) + Array.new(n_extend)
-        range.max <= 1 ? r.first : r
-      else
-        count = count_or_range
-        self.size >= count.abs or inoa(message)
-        start = count >= 0 ? 0 : size + count
-        r = slice!(start, count.abs)
-        r.size <= 0 ? nil : (r.size == 1 ? r.first : r)
+      case count_or_range
+        when Range
+          range = count_or_range
+          range.min <= self.size or inoa(message)
+          n_extract = [self.size, range.max].min
+          n_extend = range.max > self.size ? range.max - self.size : 0
+          r = self.shift(n_extract) + Array.new(n_extend)
+          range.max <= 1 ? r.first : r
+        when Integer
+          count = count_or_range
+          count.abs <= self.size or inoa(message)
+          start = count >= 0 ? 0 : size + count
+          r = slice!(start, count.abs)
+          r.size <= 0 ? nil : (r.size == 1 ? r.first : r)
+        else
+          raise ArgumentError
       end
     end
 
@@ -41,14 +41,22 @@ module ShellOpts
     #
     # #expect raise a ShellOpts::UserError exception if the array is not emptied 
     # by the operation
+    #
     def expect(count_or_range, message = nil)
-      count_or_range === self.size or inoa(message)
+      case count_or_range
+        when Range
+          count_or_range === self.size or inoa(message)
+        when Integer
+          count_or_range >= 0 or raise ArgumentError, "Count can't be negative"
+          count_or_range.abs == self.size or inoa(message)
+      end
       extract(count_or_range) # Can't fail
     end
 
   private
     def inoa(message = nil) 
-      raise ShellOpts::UserError, message || "Illegal number of arguments"
+      raise ArgumentError, message || "Illegal number of arguments"
     end
   end
 end
+

data/lib/shellopts/argument_type.rb

@@ -0,0 +1,139 @@
+module ShellOpts
+  module Grammar
+    class ArgumentType
+      # Name of type
+      def name() self.class.to_s.sub(/.*::/, "").sub(/Argument/, "") end
+
+      # Return truish if value literal (String) match the type. Returns false
+      # and set #message if the value doesn't match. <name> is used to
+      # construct the error message and is the name/alias the user specified on
+      # the command line
+      def match?(name, literal) true end
+
+      # Error message if match? returned false. Note that this method is not
+      # safe for concurrent processing
+      attr_reader :message
+
+      # Return true if .value is an "instance" of self (not used atm. See
+      # Command#[] and Grammar::Option#value?)
+      def value?(value) true end
+
+      # Convert value to Ruby type
+      def convert(value) value end
+
+      # String representation. Equal to #name
+      def to_s() name end
+
+    protected
+      # it is important that #set_message return false
+      def set_message(msg)
+        @message = msg
+        false
+      end
+    end
+
+    class StringType < ArgumentType
+    end
+
+    class IntegerArgument < ArgumentType
+      def match?(name, literal) 
+        literal =~ /^-?\d+$/ or 
+            set_message "Illegal integer value in #{name}: #{literal}" 
+      end
+
+      def value?(value) value.is_a?(Integer) end
+      def convert(value) value.to_i end
+    end
+
+    class FloatArgument < ArgumentType
+      def match?(name, literal) 
+        # https://stackoverflow.com/a/21891705/2130986
+        literal =~ /^[+-]?(?:0|[1-9]\d*)(?:\.(?:\d*[1-9]|0))?$/ or 
+            set_message "Illegal decimal value in #{name}: #{literal}"
+      end
+
+      def value?(value) value.is_a?(Numeric) end
+      def convert(value) value.to_f end
+    end
+
+    class FileArgument < ArgumentType
+      attr_reader :kind
+
+      def initialize(kind)
+        constrain kind, :file, :dir, :path, :efile, :edir, :epath, :nfile, :ndir, :npath
+        @kind = kind 
+      end
+
+      def match?(name, literal)
+        case kind
+          when :file; match_path(name, literal, kind, :file?, :default)
+          when :dir; match_path(name, literal, kind, :directory?, :default)
+          when :path; match_path(name, literal, kind, :exist?, :default)
+
+          when :efile; match_path(name, literal, kind, :file?, :exist)
+          when :edir; match_path(name, literal, kind, :directory?, :exist)
+          when :epath; match_path(name, literal, kind, :exist?, :exist)
+
+          when :nfile; match_path(name, literal, kind, :file?, :new)
+          when :ndir; match_path(name, literal, kind, :directory?, :new)
+          when :npath; match_path(name, literal, kind, :exist?, :new)
+        else
+          raise InternalError, "Illegal kind: #{kind.inspect}"
+        end
+      end
+
+      # Note: No checks done, not sure if it is a feature or a bug
+      def value?(value) value.is_a?(String) end
+
+    protected
+      def match_path(name, literal, kind, method, mode)
+        subject = 
+            case kind
+              when :file, :efile, :nfile; "regular file"
+              when :dir, :edir, :ndir; "directory"
+              when :path, :epath, :npath; "path"
+            else
+              raise ArgumentError
+            end
+
+        if File.send(method, literal) # exists?
+          if mode == :new
+            set_message "#{subject.capitalize} already exists in #{name}: #{literal}"
+          elsif kind == :path || kind == :epath
+            if File.file?(literal) || File.directory?(literal)
+              true
+            else
+              set_message "Expected regular file or directory as #{name} argument: #{literal}"
+            end
+          else
+            true
+          end
+        elsif File.exist?(literal) # exists but not the right type
+          if mode == :new
+            set_message "#{subject.capitalize} already exists"
+          else
+            set_message "Expected #{subject} as #{name} argument: #{literal}"
+          end
+        else # does not exist
+          if [:default, :new].include? mode
+            if File.exist?(File.dirname(literal))
+              true
+            else
+              set_message "Illegal path in #{name}: #{literal}"
+            end
+          else
+            set_message "Error in #{name} argument: Can't find #{literal}"
+          end
+        end
+      end
+    end
+
+    class EnumArgument < ArgumentType
+      attr_reader :values
+      def initialize(values) @values = values.dup end
+      def match?(name, literal) literal?(literal) or set_message "Illegal value in #{name}: '#{literal}'" end
+      def value?(value) @values.include?(value) end
+    end
+  end
+end
+

data/lib/shellopts/dump.rb

@@ -0,0 +1,158 @@
+module ShellOpts
+  module Grammar
+    class IdrNode
+      def dump_doc
+        puts "#{self.class} #{ident}"
+        indent {
+          children.each(&:dump_doc)
+        }
+      end
+    end
+  end
+
+  module Grammar
+    class Command
+      # Usable after parsing
+      def render_structure
+        io = StringIO.new
+        dump_structure(io)
+        io.string
+      end
+
+      def dump_structure(device = $stdout)
+        device.puts ident
+        device.indent { |dev|
+          option_groups.each { |group| dev.puts group.options.map(&:name).join(" ") }
+          commands.each { |command| command.dump_structure(dev) }
+          descrs.each { |descr| dev.puts descr.text }
+        }
+      end
+    end
+  end
+
+  module Grammar
+    class Node
+      def dump_ast
+        puts "#{classname} @ #{token.pos} #{token.source}"
+        indent { children.each(&:dump_ast) }
+      end
+
+      def dump_idr(short = false)
+        puts "#{classname}" if !short
+      end
+
+      def dump_attrs(*attrs)
+        indent {
+          Array(attrs).flatten.select { |attr| attr.is_a?(Symbol) }.each { |attr|
+            value = self.send(attr)
+            case value
+              when Brief
+                puts "#{attr}: #{value.text}"
+              when Node
+                puts "#{attr}:"
+                indent { value.dump_idr }
+              when Array
+                case value.first
+                  when nil
+                    puts "#{attr}: []"
+                  when Node
+                    puts "#{attr}:"
+                    indent { value.each(&:dump_idr) }
+                else
+                  puts "#{attr}: #{value.inspect}"
+                end
+              when ArgumentType
+                puts "#{attr}: #{value}"
+            else
+#             value = value.inspect if value.nil? || !value.respond_to?(:to_s)
+              puts "#{attr}: #{value.inspect}"
+            end
+          }
+        }
+      end
+
+    protected
+      def classname() self.class.to_s.sub(/.*::/, "") end
+    end
+
+    class Option
+      def dump_idr(short = false)
+        if short
+          s = [
+              name, 
+              argument? ? argument_type.name : nil, 
+              optional? ? "?" : nil, 
+              repeatable? ? "*" : nil
+          ].compact.join(" ")
+          puts s
+        else
+          puts "#{name}: #{classname}"
+          dump_attrs(
+              :uid, :path, :attr, :ident, :name, :idents, :names,
+              :repeatable?, 
+              :argument?, argument? && :argument_name, argument? && :argument_type, 
+              :enum?, enum? && :argument_enum, 
+              :optional?)
+          indent { puts "brief: #{group.brief}" }
+        end
+      end
+    end
+
+    class Command
+      def dump_idr(short = false)
+        if short
+          puts name
+          indent { 
+            options.each { |option| option.dump_idr(short) }
+            commands.each { |command| command.dump_idr(short) }
+            descrs.each { |descr| descr.dump_idr(short) }
+          } 
+        else
+          puts "#{name}: #{classname}"
+          dump_attrs :uid, :path, :ident, :name, :options, :commands, :specs, :descrs, :brief
+        end
+      end
+    end
+
+    class ArgDescr
+      def dump_idr(short = false)
+        super
+        indent { puts token.to_s }
+      end
+    end
+
+    class ArgSpec < Node
+      def dump_idr(short = false)
+        super
+        dump_attrs :arguments
+      end
+    end
+
+    class Arg < Node
+      def dump_idr(short = false)
+        puts "<type>"
+      end
+    end
+  end
+
+class Command
+    def __dump__(argv = [])
+      ::Kernel.puts __name__
+      ::Kernel.indent {
+        __options__.each { |ident, value| ::Kernel.puts "#{ident}: #{value.inspect}" }
+        __subcommand__!&.__dump__
+        ::Kernel.puts argv.map(&:inspect).join(" ") if !argv.empty?
+      }
+    end
+
+    # Class-level accessor methods
+    def self.dump(expr, argv = []) expr.__dump__(argv) end
+  end
+
+  class Option
+    def dump
+      ::Kernel.puts [name, argument].compact.join(" ")
+    end
+  end
+end
+

data/lib/shellopts/formatter.rb

@@ -0,0 +1,325 @@
+require 'terminfo'
+
+# TODO: Move to ext/indented_io.rb
+module IndentedIO
+  class IndentedIO
+    def margin() combined_indent.size end
+  end
+end
+
+module ShellOpts
+  module Grammar
+    class Node
+      def puts_help() end
+      def puts_usage() end
+    end
+
+    class Option
+    end
+
+    class OptionGroup
+      def puts_descr
+        puts Ansi.bold(render(:multi))
+        indent {
+          if description.any?
+            description.each { |descr|
+              descr.puts_descr
+              puts if descr != description.last
+            }
+          elsif brief
+            brief.puts_descr
+          end
+        }
+      end
+    end
+
+    # brief one-line commands should optionally use compact options
+    class Command
+      using Ext::Array::Wrap
+
+      def puts_usage(bol: false)
+        if descrs.size == 0
+          print (lead = Formatter.command_prefix || "")
+          indent(lead.size, ' ', bol: bol && lead == "") { 
+            puts render(:multi, Formatter::USAGE_MAX_WIDTH) 
+          }
+        else
+          lead = Formatter.command_prefix || ""
+          descrs.each { |descr|
+            print lead
+            puts render(:single, Formatter::USAGE_MAX_WIDTH, args: [descr.text]) 
+          } 
+        end
+      end
+
+      def puts_brief
+        width = Formatter.rest
+        option_briefs = option_groups.map { |group| [group.render(:enum), group.brief&.words] }
+        command_briefs = commands.map { |command| [command.render(:single, width), command.brief&.words] }
+        widths = Formatter::compute_columns(width, option_briefs + command_briefs)
+
+        if brief
+          puts brief
+          puts
+        end
+
+        puts "Usage"
+        indent { puts_usage(bol: true) }
+
+        if options.any?
+          puts
+          puts "Options"
+          indent { Formatter::puts_columns(widths, option_briefs) }
+        end
+
+        if commands.any?
+          puts
+          puts "Commands"
+          indent { Formatter::puts_columns(widths, command_briefs) }
+        end
+      end
+
+      def puts_descr(prefix, brief: !self.brief.nil?, name: :path)
+        puts Ansi.bold([prefix, render(:single, Formatter.rest)].flatten.compact.join(" "))
+        indent {
+          if brief
+            puts self.brief.words.wrap(Formatter.rest)
+          else
+            newline = false
+            children.each { |child|
+              puts if newline
+              newline = true
+
+              if child.is_a?(Command)
+                child.puts_descr(prefix, name: :path)
+               else
+                child.puts_descr
+              end
+            }
+          end
+        }
+      end
+
+      def puts_help
+        puts Ansi.bold "NAME"
+        full_name = [Formatter::command_prefix, name].join
+        indent { puts brief ? "#{full_name} - #{brief}" : full_name }
+        puts
+
+        puts Ansi.bold "USAGE"
+        indent { puts_usage(bol: true) }
+
+        section = {
+          Paragraph => "DESCRIPTION",
+          OptionGroup => "OPTIONS",
+          Command => "COMMANDS"
+        }
+
+        newline = false # True if a newline should be printed before child 
+        indent {
+          children.each { |child|
+            if child.is_a?(Section) # Explicit section
+#             p :A
+              puts
+              indent(-1).puts Ansi.bold child.name
+              section.delete_if { |_,v| v == child.name }
+              section.delete(Paragraph)
+              newline = false
+              next
+            elsif s = section[child.class] # Implicit section
+#             p :B
+              puts  
+              indent(-1).puts Ansi.bold s
+              section.delete(child.class)
+              section.delete(Paragraph)
+              newline = false
+            else # Any other node add a newline
+#             p :C
+              puts if newline
+              newline = true
+            end
+
+            if child.is_a?(Command)
+#             prefix = child.parent != self ? nil : child.supercommand&.name
+              prefix = child.supercommand == self ? nil : child.supercommand&.name
+              child.puts_descr(prefix, brief: false, name: :path)
+              newline = true
+             else
+              child.puts_descr
+              newline = true
+            end
+          }
+
+          # Also emit commands not declared in nested scope
+          (commands - children.select { |child| child.is_a?(Command) }).each { |cmd|
+            puts if newline
+            newline = true
+            prefix = cmd.supercommand == self ? nil : cmd.supercommand&.name
+            cmd.puts_descr(prefix, brief: false, name: path)
+          }
+        }
+      end
+    end
+
+    class Program
+      using Ext::Array::Wrap
+    end
+
+    class DocNode
+      def puts_descr() puts lines end
+    end
+
+    module WrappedNode
+      def puts_descr(width = Formatter.rest) puts lines(width) end
+    end
+
+    class Code
+      def puts_descr() indent { super } end
+    end
+  end
+
+  class Formatter
+    using Ext::Array::Wrap
+
+    # Right margin
+    MARGIN_RIGHT = 3
+
+    # String for 'Usage' in error messages
+    USAGE_STRING = "Usage"
+
+    # Indent to use in usage output
+    USAGE_INDENT = USAGE_STRING.size
+
+    # Width of usage (after usage string)
+    USAGE_MAX_WIDTH = 70
+
+    # Indent to use in brief output
+    BRIEF_INDENT = 2
+
+    # Number of characters between columns in brief output
+    BRIEF_COL_SEP = 2
+
+    # Maximum width of first column in brief option and command lists
+    BRIEF_COL1_MIN_WIDTH = 6
+
+    # Maximum width of first column in brief option and command lists
+    BRIEF_COL1_MAX_WIDTH = 40
+
+    # Minimum width of second column in brief option and command lists
+    BRIEF_COL2_MAX_WIDTH = 50
+
+    # Indent to use in help output
+    HELP_INDENT = 4
+
+    # Command prefix when subject is a sub-command
+    def self.command_prefix() @command_prefix end
+
+    # Usage string in error messages
+    def self.usage(subject)
+      subject = Grammar::Command.command(subject)
+      @command_prefix = subject.ancestors.map { |node| node.name + " " }.join
+      setup_indent(1) {
+        print lead = "#{USAGE_STRING}: "
+        indent(lead.size, ' ', bol: false) { subject.puts_usage }
+      }
+    end
+
+#   # TODO
+#   def self.usage=(usage_lambda)
+#   end
+
+    # When the user gives a -h option
+    def self.brief(command)
+      command = Grammar::Command.command(command)
+      @command_prefix = command.ancestors.map { |node| node.name + " " }.join
+      setup_indent(BRIEF_INDENT) { command.puts_brief }
+    end
+
+#   # TODO
+#   def self.brief=(brief_lambda)
+#   end
+
+    # When the user gives a --help option
+    def self.help(subject)
+      subject = Grammar::Command.command(subject)
+      @command_prefix = subject.ancestors.map { |node| node.name + " " }.join
+      setup_indent(HELP_INDENT) { subject.puts_help }
+    end
+
+    # Short-hand to get the Grammar::Command object
+    def self.command_of(obj)
+      constrain obj, Grammar::Command, ::ShellOpts::Program
+      obj.is_a?(Grammar::Command) ? obj : obj.__grammar__
+    end
+
+#   # TODO
+#   def self.help_w_lambda(program)
+#     if @help_lambda
+#       #
+#     else
+#       program = Grammar::Command.command(program)
+#       setup_indent(HELP_INDENT) { program.puts_descr }
+#     end
+#   end
+#
+#   def self.help=(help_lambda) @help_lambda end
+
+    def self.puts_columns(widths, fields)
+      l = []
+      first_width, second_width = *widths
+      second_col = first_width + 2
+
+      for (first, second) in fields
+        if first.size > first_width
+          puts first
+          indent(first_width + BRIEF_COL_SEP, ' ') { puts second.wrap(second_width) } if second
+        elsif second
+          printf "%-#{first_width + BRIEF_COL_SEP}s", first
+          indent(first_width, bol: false) { puts second.wrap(second_width) }
+        else
+          puts first
+        end
+      end
+    end
+
+    def self.compute_columns(width, fields)
+      first_max = [
+        (fields.map { |first, _| first.size } + [BRIEF_COL1_MIN_WIDTH]).max, 
+        BRIEF_COL1_MAX_WIDTH
+      ].min
+      second_max = fields.map { |_, second| second ? second&.map(&:size).sum + second.size - 1: 0 }.max
+
+      if first_max + BRIEF_COL_SEP + second_max <= width
+        first_width = first_max
+        second_width = second_max
+      elsif first_max + BRIEF_COL_SEP + BRIEF_COL2_MAX_WIDTH <= width
+        first_width = first_max
+        second_width = width - first_width - BRIEF_COL_SEP
+      else
+        first_width = [width - BRIEF_COL_SEP - BRIEF_COL2_MAX_WIDTH, BRIEF_COL1_MAX_WIDTH].min
+        second_width = BRIEF_COL2_MAX_WIDTH
+      end
+
+      [first_width, second_width]
+    end
+
+    def self.width()
+      @width ||= TermInfo.screen_width - MARGIN_RIGHT
+    end
+
+    def self.rest() width - $stdout.margin end
+
+  private
+    # TODO Get rid of?
+    def self.setup_indent(indent, &block)
+      default_indent = IndentedIO.default_indent
+      begin
+        IndentedIO.default_indent = " " * indent
+        indent(0) { yield } # Ensure IndentedIO is on the top of the stack so we can use $stdout.levels
+      ensure
+        IndentedIO.default_indent = default_indent
+      end
+    end
+  end
+end
+