shellopts 2.0.0.pre.14 → 2.0.0

data/doc/format.rb

@@ -0,0 +1,95 @@
+    # One-line format in prioritized order
+    # ------------------------------------
+    #
+    #   cmd -a -b -c [CMD|CMD] ARGS
+    #   cmd -a -b -c <command> ARGS
+    #   cmd <options> [CMD|CMD] <ARGS>
+    #   cmd <options> <command> <ARGS>
+    #
+    # Multiline format
+    # ----------------
+    #
+    #   cmd -a -b -c [CMD|CMD] ARGS   # <- only if no subcommand options or arguments
+    #
+    #   cmd -a -b -c <command> ARGS
+    #       subcmd -e -f -g ARGS
+    #       subcmd -h -i -j ARGS
+    #
+    #   cmd -a -b -c 
+    #       -d -e
+    #       [CMD|CMD] ARGS
+    #
+    #   cmd -a -b -c 
+    #       -d -e
+    #       <command> ARGS
+    #
+    # Brief format
+    # ------------
+    #
+    #   Name - Brief
+    #
+    #   Usage: 
+    #     cmd -a -b -c [CMD|CMD] ARGS
+    #
+    #   Options:
+    #     -a                    Brief
+    #     -b                    Brief
+    #     -c                    Brief
+    #
+    #   Commands:
+    #     CMD --opts ARGS       Brief
+    #     CMD --opts ARGS_THAT_TAKES_UP_A_LOT_OF_SPACE       
+    #                           Brief
+    #
+    # Brief Command
+    #     CMD --opts ARGS       Brief
+    #     CMD --opts ARGS_THAT_TAKES_UP_A_LOT_OF_SPACE       
+    #                           Brief
+    #
+    # Brief Option
+    #   -a            Brief
+    #   -b=a_very_long_option
+    #                 Brief
+    #    
+    #
+    # Doc format
+    # ----------
+    #
+    #   Name
+    #     Name - Brief
+    #
+    #   Usage:
+    #     cmd -a -b -c [CMD|CMD] ARGS
+    #
+    #   Description
+    #     Descr
+    #
+    #   Options:
+    #     -a
+    #       Descr
+    #     -b
+    #       Descr
+    #     -c, --aliases
+    #       Descr
+    #
+    #   Commands:
+    #     CMD -d -e -f ARGS
+    #       Descr
+    #
+    #       -d
+    #         Descr
+    #       -e
+    #         Descr
+    #       -f 
+    #         Descr
+    #
+    #     CMD -g -h -i ARGS
+    #       Descr
+    #
+    #       -g
+    #         Descr
+    #       -h
+    #         Descr
+    #       -i 
+    #         Descr
+    #

data/doc/grammar.txt

@@ -0,0 +1,27 @@
+
+Optionn Grammar
+  [ "+" ] name-list [ "=" [ label ] [ ":" [ "#" | "$" | enum | special-constant ] ] [ "?" ] ]
+
+  -a=               # Renders as -a=
+  -a=#              # Renders as -a=INT
+  -b=$              # Renders as -b=NUM
+  -c=a,b,c          # Renders as -c=a|b|c
+  -d=3..5           # Renders as -d=3..5
+  -e=:DIR           # Renders as -e=DIR
+  -f=:FILE          # Renders as -f=FILE
+
+  -o=COUNT          
+  -a=COUNT:#
+  -b=COUNT:$
+  -c=COUNT:a,b,c
+  -e=DIR:DIRPATH
+  -f=FILE:FILEPATH
+
+Special constants
+
+          Exist   Missing   Optional
+
+  File    FILE    -         FILEPATH
+  Dir     DIR     -         DIRPATH
+  Node    NODE    NEW       PATH
+

data/doc/syntax.rb

@@ -0,0 +1,110 @@
+
+# MAN pages
+#
+# NAME
+#   #{$PROGRAM_NAME} - #{BRIEF || spec.summary}
+#
+# USAGE
+#   #{USAGE || shellopts.usage}
+#
+# DESCRIPTION
+#   #{DESCRIPTION || spec.description}
+#
+# OPTIONS
+#   #{OPTIONS || shellopts.options}
+#
+# COMMANDS
+#   #{COMMANDS || shellopts.commands}
+#   
+
+# Help output
+#
+# #{BRIEF}
+#
+# Usage: #{USAGE || shellopts.usage}
+#
+# Options:
+#   #{OPTIONS_IN_SHORT_FORMAT | shellopts.options_in_short_format}
+#
+# Commands
+#   #{COMMANDS_IN_SHORT_FORMMAT | shellopts.commands_in_short_format}
+#
+
+h = %(
+  -a,all # Include all files
+  -f=FILE # Use this file
+)
+
+# Default options
+#   <defaults>
+#     Can be processed by ShellOpts.process_defaults
+#     ShellOpts.make(SPEC, ARGV, defaults: true)
+#
+# Options
+#   -a,b,long
+#   --long
+#   -a=FILE
+#   -e,env,environment=ENVIRONMENT:p,d,t,prod,dev,test,production,development
+#   -i=# # Integer
+#   -o=optional?
+#   --verbose* # Repeated
+#   -a=V* # Repeated with argument
+#   -a=V?* # Repeated, optionally with argument
+#
+# Arguments
+#   Arguments has to be on one line (per ++ or --)
+#
+#   ++ ARG...
+#     Subcommand arguments
+#   -- ARG...
+#     Command arguments. Multiple -- definitions are allowed
+#
+#   [ARG]
+#     Optional argument
+#   ARG
+#     Mandatory argument
+#   ARG...
+#     Repeated argument. At least one argument is mandatory
+#   [ARG...]
+#     Optionally repeated argument
+#
+# SPECIAL ALTERNATE VALUES OR ARGUMENTS
+#   FILE:EFILE
+#     Existing file. "FILE" will be used as name of the value
+#   PATH:EPATH
+#     Existing file or directory. "PATH" will be used as the name of the value
+#   DIRECTORY:EDIR
+#     Existing directory. "DIRECTORY" will be used as name of the value
+#
+# SPEC = %(
+#   # Common options
+#   -f,file=FILE
+#   -- ARG ARG
+#
+#   # More options
+#   -m,mode=MODE
+#   -- ARG ARG ARG
+# )
+#
+# How to make
+#   cp [OPTION]... [-T] SOURCE DEST
+#   cp [OPTION]... SOURCE... DIRECTORY
+#   cp [OPTION]... -t DIRECTORY SOURCE...
+#
+#   USAGE = %(
+#     cp [OPTION]... [-T] SOURCE DEST
+#     cp [OPTION]... SOURCE... DIRECTORY
+#     cp [OPTION]... -t DIRECTORY SOURCE...
+#   )
+#
+#   SPEC = %(
+#     -r,recursive
+#  
+#     -T,no-target-directory
+#  
+#     -t,target_directory=DIRECTORY:EDIR
+#   )
+#   
+
+
+

data/doc/syntax.txt

@@ -0,0 +1,10 @@
+
+One-line syntax:
+
+  <options> <commands> <spec|descr> # <brief>
+  
+Grammar
+
+  <program> ::= <options-spec> <commands-spec> 
+    
+

data/lib/ext/array.rb

@@ -0,0 +1,62 @@
+
+module Ext
+  module Array
+    module ShiftWhile
+      refine ::Array do
+        # The algorithm ensures that the block sees the array as if the current
+        # element has already been removed
+        def shift_while(&block)
+          r = []
+          while value = self.shift
+            if !block.call(value)
+              self.unshift value
+              break
+            else
+              r << value
+            end
+          end
+          r
+        end
+      end
+    end
+
+    module PopWhile
+      refine ::Array do
+        # The algorithm ensures that the block sees the array as if the current
+        # element has already been removed
+        def pop_while(&block)
+          r = []
+          while value = self.pop
+            if !block.call(value)
+              self.push value
+              break
+            else
+              r << value
+            end
+          end
+          r
+        end
+      end
+    end
+
+    module Wrap
+      refine ::Array do
+        # Concatenate strings into lines that are at most +width+ characters wide
+        def wrap(width, curr = 0)
+          lines = [[]]
+          curr -= 1 # Simplifies conditions below
+          each { |word|
+            if curr + 1 + word.size <= width
+              lines.last << word
+              curr += 1 + word.size
+            else
+              lines << [word]
+              curr = word.size
+            end
+          }
+          lines.map! { |words| words.join(" ") }
+        end
+      end
+    end
+  end
+end

data/lib/ext/forward_to.rb

@@ -0,0 +1,15 @@
+
+require 'forward_to'
+
+module ForwardTo
+  def forward_self_to(target, *methods)
+    for method in Array(methods).flatten
+      if method =~ /=$/
+        class_eval("def self.#{method}(*args) #{target}.#{method}(*args) end")
+      else
+        class_eval("def self.#{method}(*args, &block) #{target}.#{method}(*args, &block) end")
+      end
+    end
+  end
+end
+

data/lib/ext/lcs.rb

@@ -0,0 +1,34 @@
+
+# https://gist.github.com/Joseph-N/fbf061aa2347ed2c104f0b3fe1a5b9f2
+#
+# TODO: Move to String and make find_longest_command_substring_index return a
+# range
+module LCS
+  def self.find_longest_common_substring(s1, s2)
+    i, z = find_longest_command_substring_index(s1, s2)
+    s1[i .. i + z]
+  end
+
+  def self.find_longest_common_substring_index(s1, s2)
+    if (s1 == "" || s2 == "")
+      return [0,0]
+    end
+    m = Array.new(s1.length){ [0] * s2.length }
+    longest_length, longest_end_pos = 0,0
+    (0 .. s1.length - 1).each do |x|
+      (0 .. s2.length - 1).each do |y|
+        if s1[x] == s2[y]
+          m[x][y] = 1
+          if (x > 0 && y > 0)
+            m[x][y] += m[x-1][y-1]
+          end
+          if m[x][y] > longest_length
+            longest_length = m[x][y]
+            longest_end_pos = x
+          end
+        end
+      end
+    end
+    [longest_end_pos - longest_length + 1, longest_length]
+  end
+end

data/lib/shellopts/analyzer.rb

@@ -0,0 +1,130 @@
+
+module ShellOpts
+  module Grammar
+    class Node
+      def remove_brief_nodes
+        children.delete_if { |node| node.is_a?(Brief) }
+      end
+
+      def remove_arg_descr_nodes
+        children.delete_if { |node| node.is_a?(ArgDescr) }
+      end
+
+      def remove_arg_spec_nodes
+        children.delete_if { |node| node.is_a?(ArgSpec) }
+      end
+
+      def analyzer_error(token, message) 
+        raise AnalyzerError.new(token), message 
+      end
+    end
+
+    class Command
+      def set_supercommand
+        commands.each { |child| child.instance_variable_set(:@supercommand, self) }
+      end
+
+      def collect_options
+        @options = option_groups.map(&:options).flatten
+      end
+
+      # Move options before first command
+      def reorder_options
+        if commands.any?
+          if i = children.find_index { |child| child.is_a?(Command) }
+            options, rest = children[i+1..-1].partition { |child| child.is_a?(OptionGroup) }
+            @children = children[0, i] + options + children[i..i] + rest
+          end
+        end
+      end
+
+      def compute_option_hashes
+        options.each { |option|
+          option.idents.zip(option.names).each { |ident, name|
+            !@options_hash.key?(name) or 
+                analyzer_error option.token, "Duplicate option name: #{name}"
+            @options_hash[name] = option
+            !@options_hash.key?(ident) or 
+                analyzer_error option.token, "Can't use both #{@options_hash[ident].name} and #{name}"
+            @options_hash[ident] = option
+          }
+        }
+      end
+
+      def compute_command_hashes
+        commands.each { |command|
+          # TODO Check for dash-collision
+          !@commands_hash.key?(command.name) or 
+              analyzer_error command.token, "Duplicate command name: #{command.name}"
+          @commands_hash[command.name] = command
+          @commands_hash[command.ident] = command
+          command.compute_command_hashes
+        }
+      end
+    end
+  end
+
+  class Analyzer
+    include Grammar
+
+    attr_reader :grammar
+
+    def initialize(grammar)
+      @grammar = grammar
+    end
+
+    # Move commands that are nested within a different command than it belongs to
+    def move_commands
+      # We can't use Command#[] at this point so we collect the commands here
+      h = {}
+      @grammar.traverse(Grammar::Command) { |command|
+        h[command.path] = command
+      }
+
+      # Find commands to move
+      #
+      # Commands are moved in two steps because the behaviour of #traverse is
+      # not defined when the data structure changes beneath it
+      move = []
+      @grammar.traverse(Grammar::Command) { |command|
+        if command.path.size > 1 && command.parent && command.parent.path != command.path[0..-2]
+          move << command
+        else
+          command.instance_variable_set(:@command, command.parent)
+        end
+      }
+
+      # Move commands but do not change parent/child relationship
+      move.each { |command|
+        supercommand = h[command.path[0..-2]] or analyzer_error "Can't find #{command.ident}!"
+        command.parent.commands.delete(command)
+        supercommand.commands << command
+        command.instance_variable_set(:@command, supercommand)
+      }
+    end
+
+    def analyze()
+      move_commands
+
+      @grammar.traverse(Grammar::Command) { |command|
+        command.set_supercommand
+        command.reorder_options
+        command.collect_options
+        command.compute_option_hashes
+      }
+
+      @grammar.compute_command_hashes
+
+      @grammar.traverse { |node| 
+        node.remove_brief_nodes 
+        node.remove_arg_descr_nodes
+        node.remove_arg_spec_nodes
+      }
+
+      @grammar
+    end
+
+    def Analyzer.analyze(source) self.new(source).analyze end
+  end
+end
+

data/lib/shellopts/ansi.rb

@@ -0,0 +1,8 @@
+module ShellOpts
+  class Ansi
+    def self.bold(bold = true, s) 
+      bold && $stdout.tty? ? "#{s}" : s 
+    end
+  end
+end
+

data/lib/shellopts/args.rb

@@ -13,26 +13,29 @@ module ShellOpts
     #
     # 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
 
@@ -42,7 +45,13 @@ 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
 
@@ -52,3 +61,4 @@ module ShellOpts
     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
+