shellopts 2.0.0.pre.11 → 2.0.0

data/TODO

@@ -1,136 +1,48 @@
 
-TODO
-  o Rethink #error and #fail <- The use-case is one-file ruby scripts. Idea: Only use in main exe file?
-  o Create exceptions: UserError SystemFail and allow them to be used instead of #error and #fail
-  ? Remove ! from OptionStruct#subcommand return value. We know we're
-    processing commands so there is no need to have a distinct name and it
-    feels a lot more intuitive without it
-  o Add validation block to ShellOpts class methods
-  o Get rid of key_name. Define #name on Grammar::Node instead
-  o Define #name to the string name of the option/command without prefixed '--'
-    for options. This can cause collisions but they can be avoided using aliases
-  o Clean-up
-    o Grammar::options -> Grammar::option_multihash
-    o Clean-up identifiers etc.
-    o Un-multi-izing Grammar::option_multihash and turn it into a regular hash from key to option
-    o subcommand vs. command consistency
-  o Implement ObjectStruct#key! and ObjectStruct#value! (?)
-  o Allow command_alias == nil to suppress the method
-  o Raise on non-existing names/keys. Only return nil for declared names/keys that are not present
-  o Use hash_tree
-  o Also allow assignment to usage string for ShellOpts::ShellOpts objects
-  o Create a ShellOpts.args method? It would be useful when processing commands:
-      case opt
-        when "command"
-          call_command_method(ShellOpts.args[1], ShellOpts.args[2])
-      end
-    ShellOpts.args would be a shorthand for ShellOpts.shellopts.args
-    Another option would be to create an argument-processing method:
-      shellopts.argv(2) -> call error if not exactly two arguments else return elements
-  o Add a ShellOpts.option method:
-      file = ShellOpts.option("--file")
-    This will only work for options on the outermost level... maybe:
-      file = ShellOpts.option("load! --file")
-  o Check on return value from #process block to see if all options was handled:
-      case opt
-        when '-v'; verbose = true # Return value 'true' is ok
-        # Unhandled option means return value is nil
-      end
-  o Consolidate some of the 3 variations of #error and #fail
-  o Add a option flag for solitary options (--help) 
-  o Make a #to_yaml
-  o Make an official dump method for debug
-  o Make a note that all options are processed at once and not as-you-go
-  o Test that arguments with spaces work
-  o Long version usage strings (major release)
-  o Doc: Example of processing of sub-commands and sub-sub-commands
-
-  + Add a 'mandatory' argument to #subcommand
-  + More tests
-  + More doc
-  + Implement value-name-before-flags rule
-  + Kill option array values
-  + Kill key forms
-  + Rename Option#opt to Option#name
-  + Have all Ast objects to be on [key, name, value] form
-  + Change #=>i, $=>f and introduce b (boolean)
-  + Unshift program name to usage definition string before compiling
-  + Rename to UsageCompiler and ArgvParser
-  + Make usage-string handle commands
-  + Change !cmd to cmd!
-  + Clean-up terminology: Option-name is used for names with and without the prefixed dashes
-  + Rename Option#has_argument? and #optional? to something else
-  + Fix location reporting of compiler errors
-  + Allow '--' in usage so that everything after can be used as USAGE in error messages
-  + Handle pretty-printing of usage string in handling of ParserError
-  + Compiler.new.compile(usage), Parser.new(compiled_program).parse(argv)
-  + Check for duplicate option in the parser
-  + Handle CompilerError
-  + Use nil value as the name of the top 'command'
-  + Refactor compilation to avoid having the Command objects throw CompilerErrors
-  + Change to 'parser.parse' / 'parser.parse3'
-  + Use first long option as symbolic key
-  + Use full option names everywhere (eg. '--all' instead of 'all')
-
-  - Revert change from '#' -> 'i'
-  - Guard against reserved 'object_id' name in OpenStruct
-  - Default value ('=' -> ':')
-      Default values are better handled in the calling program
-
-  ? More specialized exceptions: "MissingArgumentError" etc.
-
-LATER
-  o Allow '-a' and '--aa' in usage
-  o Allow single-line comments
-  o Allow multi-line comments
-  o Regex as option value spec
-  o "FILE", "DIR", "NEWFILE", "NEWDIR" as keyword in option value spec
-      RFILE, RDIR
-      WFILE, WDIR
-      EFILE, EDIR
-  o Octal and hexadecimal integers
-  o Escape of separator in lists
-  o Handle output of subcommand usage like "cmd1 cmd1.cmd2 cmd2"
-  o Command-specific arguments: clone! o,opt ++ ARG1 ARG2...
-  o Hostname and email as basic types
-
-ON TO_H BRANCH
-  ShellOpts.process(usage, argv) { |opt,val| ... } => args
-  ShellOpts.process(usage, argv) { |key,opt,val| ... } => args
-
-  opts = ShellOpts.new(usage, argv, defaults = {})
-  opts = ShellOpts.new(usage, argv, defaults = OpenStruct.new)
-
-  opts.args
-  opts.to_a
-  opts.to_h
-  opts.to_openstruct
-
-  opts.each { |opt,val| ... }
-  opts.each { |key,opt,val| ... }
-
-LONG FORMAT
-
-  PROGRAM = File.basename(ARGV.first)
-  USAGE = "-a -f FILE -lvh FILE..."
-  DESCR = %(
-    Short description
-
-    Longer description
-  )
-  OPTIONS = %(
-    -a,--all
-      Process all files
-
-    -f, --file=FILE
-      Process file
-
-    !command
-      This is a command
-
-      --this-is-a-command-option
-        Options for commands are nested
-
+o Ignore all text after ' # ' (doesn't conflict with option flag)
+o Command aliases
+o Add user-defined setions
+o Add a SOURCE section with link to git repo
+o Bullet-lists
+o Allow a USAGE section (and NAME)
+o Find source in code an adjust line number in error messages 
+o Rename line and char to lineno and charno
+o Client-defined argument types
+o Rename Expr -> ?
+o Find clean(er) procedural object model
+o Allow assignment to options (this makes practical stuff easier)
+o Special handling of --help arguments so that '--help command' is possible
+o Support for paging of help:
+    begin 
+      file = Tempfile.new("prick") 
+      file.puts HELP.split("\n").map { |l| l.sub(/^  /, "") } 
+      file.flush 
+      system "less #{file.path}" 
+    ensure 
+      file.close 
+    end 
+
++ Bold text output
++ Recursive format of commands
++ Rename Compiler -> Interpreter
+
+
+OLD
+
+o Fix that it is near unsable when the user doesn't do 'include ShellOpts'
+o Subcommands can be parsed as well: 
+    opts, args = Shellopts.process(OPTIONS, ARGV)
     ...
-  )
-
+    opts, command = opts.process
+    case command
+      when ...
+    end
+o 'help' should list commands in declaration order
+o 'help' should use all levels by default
+o 'help' should always include top-level options (try setting levels: 10 and
+  see top-level options are gone
+o A ShellOpts#shift command that makes it possible for Array#expect to emit
+  relevant error messages
+
++ Somehow escape comments where a line starts with an option name
++ Parse and check enumeration arguments ('--debug=tokens|ast|idr|...')

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

@@ -1,9 +1,62 @@
 
-module XArray
-  refine Array do
-    # Find and return first duplicate. Return nil if not found
-    def find_dup
-      detect { |e| rindex(e) != index(e) }
+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
+