shellopts 2.0.0.pre.7 → 2.0.0.pre.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7ac01e4c6feb1897f74056a36c74db0cf78802d13437908aa18631ead7c97c5
-  data.tar.gz: 5443ff421ceb38fcf07aaf87ae7b3740fd804679ccdec377fb195c688c50b57b
+  metadata.gz: f1e9e2f138c476cb6af3184dd5e43f8a0f82108d05e4170491c5c46dfb547627
+  data.tar.gz: 9990bee10ffe5c6c5db537a416f366ed70c4577a8a3a07658281d9485225d438
 SHA512:
-  metadata.gz: 0d8180a2acc6dac8e234567db9409cd9d01cebe8d4551f6cfa24488ce5d1fb848ec8b42b21d40e7d8f6990bf61e4dc8d482370e9cb4ceb409e3f18fdb70a877c
-  data.tar.gz: f07d22ab7976d5efa317356fc796f8bbe20b8c6a8ee609eb24106f60e8e56d9874181dcab4e873268b1aea5a1aa27ffd1253bb10499052edd995894c6eec9d88
+  metadata.gz: 5a57589ccaf3b2f516727cd6e7b066044d13a49d2c5280a478de162e42574e1eca03c2b013133d9b0ce50b4ac037fef15d12a01f5893b32ec6132d03c121e08f
+  data.tar.gz: bc338066a99d6470bd434d26cf994159ec926c4eb7f3a7d1d8b358303d5850bcdf058b56447ebf6c581bb2295de2d5f57f5637db5ab82fbd47ba618b8988afe6

data/TODO

@@ -1,136 +1,16 @@
-
-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 Somehow escape comments where a line starts with an option name
+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 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 
 

data/lib/ext/algorithm.rb

@@ -0,0 +1,14 @@
+
+module Algorithm
+  def follow(object, sym = nil, &block)
+    sym.nil? == block_given? or raise "Can't use both symbol and block"
+    a = []
+    while object
+      a << object
+      object = block_given? ? yield(object) : object.send(sym)
+    end
+    a
+  end
+
+  module_function :follow
+end

data/lib/ext/ruby_env.rb

@@ -0,0 +1,8 @@
+
+if File.directory?(File.join(File.dirname(File.dirname(File.dirname(__FILE__))), "spec"))
+  RUBY_ENV = "development"
+else
+  RUBY_ENV = "production"
+end
+
+

data/lib/shellopts.rb

@@ -1,242 +1,119 @@
 require "shellopts/version"
 
-require 'shellopts/compiler.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
-#
-module ShellOpts
-  def self.default_name()
-    @default_name || defined?(PROGRAM) ? PROGRAM : File.basename($0)
-  end
+require "ext/algorithm.rb"
+require "ext/ruby_env.rb"
 
-  def self.default_name=(name)
-    @default_name = name
-  end
+require "shellopts/constants.rb"
+require "shellopts/exceptions.rb"
 
-  def self.default_usage()
-    @default_usage || defined?(USAGE) ? USAGE : nil
-  end
+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"
 
-  def self.default_usage=(usage)
-    @default_usage = usage
-  end
+require "shellopts/ast/parser.rb"
+require "shellopts/ast/command.rb"
+require "shellopts/ast/option.rb"
 
-  def self.default_key_type()
-    @default_key_type || ::ShellOpts::DEFAULT_KEY_TYPE
-  end
+require "shellopts/args.rb"
+require "shellopts/formatter.rb"
 
-  def self.default_key_type=(type)
-    @default_key_type = type
-  end
+if RUBY_ENV == "development"
+  require "shellopts/grammar/dump.rb"
+  require "shellopts/ast/dump.rb"
+end
 
-  # Base class for ShellOpts exceptions
-  class Error < RuntimeError; end
+$verb = nil
+$quiet = nil
+$shellopts = nil
 
-  # Raised when a syntax error is detected in the spec string
-  class CompilerError < Error
-    def initialize(start, usage)
-      super(usage)
-      set_backtrace(caller(start))
+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)
+      @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
+        error(ex.subject, ex.message)
+      end
     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)
-  end
+    def error(subject = nil, message)
+      $stderr.puts "#{name}: #{message}"
+      usage(subject, device: $stderr)
+      exit 1
+    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)
-    [shellopts.idr, shellopts.args]
-  end
+    def fail(message)
+      $stderr.puts "#{name}: #{message}"
+      exit 1
+    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)
-    [shellopts.to_a, shellopts.args]
-  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
 
-  # 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)
-    [shellopts.to_h(key_type: key_type, aliases: aliases), shellopts.args]
-  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
 
-  # 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)
-    [shellopts.to_struct(aliases: aliases), shellopts.args]
-  end
+  private
+    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 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)
-    shellopts.each(&block)
+    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
   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)
+  def self.process(spec, argv, name: nil)
+    $shellopts = ShellOpts.new(spec, argv, name: name)
+    [$shellopts.program, $shellopts.arguments]
   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)
+  def self.error(subject = nil, message)
+    $shellopts.error(subject, message)
   end
 
-  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
-      end
-    end
-    super
+  def self.fail(message)
+    $shellopts.fail(message)
   end
 
-private
-  # Default default key type
-  DEFAULT_KEY_TYPE = :name
-
-  # Reset state variables
-  def self.reset()
-    @shellopts = nil
+  def self.help(subject = nil, device: $stdout, levels: 10, margin: "", tab: "  ")
+    $shellopts.help(subject, device: device, levels: levels, margin: margin, tab: tab)
   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.usage(subject = nil, device: $stdout, levels: 1, margin: "")
+    $shellopts.usage(subject, device: device, levels: levels, margin: margin)
   end
-
-  @shellopts = nil
-  @is_included_in_main = false
 end