RubyGems - executable - Versions diffs - 1.1.0 → 1.2.0 - Mend

executable 1.1.0 → 1.2.0

Files changed (50) hide show

data/.ruby +61 -0
data/.yardopts +7 -0
data/COPYING.rdoc +35 -0
data/DEMO.rdoc +568 -0
data/HISTORY.rdoc +55 -0
data/README.rdoc +101 -51
data/Schedule.reap +17 -0
data/demo/00_introduction.rdoc +6 -0
data/demo/01_single_command.rdoc +44 -0
data/demo/02_multiple_commands.rdoc +125 -0
data/demo/03_help_text.rdoc +109 -0
data/demo/04_manpage.rdoc +14 -0
data/demo/05_optparse_example.rdoc +152 -0
data/demo/06_delegate_example.rdoc +40 -0
data/demo/07_command_methods.rdoc +36 -0
data/demo/08_dispatach.rdoc +29 -0
data/demo/applique/ae.rb +1 -0
data/demo/applique/compare.rb +4 -0
data/demo/applique/exec.rb +1 -0
data/demo/samples/bin/hello +31 -0
data/demo/samples/man/hello.1 +22 -0
data/demo/samples/man/hello.1.html +102 -0
data/demo/samples/man/hello.1.ronn +19 -0
data/lib/executable.rb +67 -128
data/lib/executable/core_ext.rb +102 -0
data/lib/executable/dispatch.rb +30 -0
data/lib/executable/domain.rb +106 -0
data/lib/executable/errors.rb +22 -0
data/lib/executable/help.rb +430 -0
data/lib/executable/parser.rb +208 -0
data/lib/executable/utils.rb +41 -0
data/lib/executable/version.rb +23 -0
data/meta/authors +2 -0
data/meta/copyrights +3 -0
data/meta/created +1 -0
data/meta/description +6 -0
data/meta/name +1 -0
data/meta/organization +1 -0
data/meta/repositories +2 -0
data/meta/requirements +6 -0
data/meta/resources +7 -0
data/meta/summary +1 -0
data/meta/version +1 -0
data/test/test_executable.rb +40 -19
metadata +124 -68
data/History.rdoc +0 -35
data/NOTICE.rdoc +0 -23
data/Profile +0 -30
data/Version +0 -1
data/meta/license/Apache2.txt +0 -177

data/demo/samples/man/hello.1.html ADDED

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv='content-type' value='text/html;charset=utf8'>
+  <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
+  <title>hellocmd(1) - Say hello.</title>
+  <style type='text/css' media='all'>
+  /* style: man */
+  body#manpage {margin:0}
+  .mp {max-width:100ex;padding:0 9ex 1ex 4ex}
+  .mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
+  .mp h2 {margin:10px 0 0 0}
+  .mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
+  .mp h3 {margin:0 0 0 4ex}
+  .mp dt {margin:0;clear:left}
+  .mp dt.flush {float:left;width:8ex}
+  .mp dd {margin:0 0 0 9ex}
+  .mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
+  .mp pre {margin-bottom:20px}
+  .mp pre+h2,.mp pre+h3 {margin-top:22px}
+  .mp h2+pre,.mp h3+pre {margin-top:5px}
+  .mp img {display:block;margin:auto}
+  .mp h1.man-title {display:none}
+  .mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
+  .mp h2 {font-size:16px;line-height:1.25}
+  .mp h1 {font-size:20px;line-height:2}
+  .mp {text-align:justify;background:#fff}
+  .mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
+  .mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
+  .mp u {text-decoration:underline}
+  .mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
+  .mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
+  .mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
+  .mp b.man-ref {font-weight:normal;color:#434241}
+  .mp pre {padding:0 4ex}
+  .mp pre code {font-weight:normal;color:#434241}
+  .mp h2+pre,h3+pre {padding-left:0}
+  ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
+  ol.man-decor {width:100%}
+  ol.man-decor li.tl {text-align:left}
+  ol.man-decor li.tc {text-align:center;letter-spacing:4px}
+  ol.man-decor li.tr {text-align:right;float:right}
+  </style>
+</head>
+<!--
+  The following styles are deprecated and will be removed at some point:
+  div#man, div#man ol.man, div#man ol.head, div#man ol.man.
+  The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
+  .man-navigation should be used instead.
+-->
+<body id='manpage'>
+  <div class='mp' id='man'>
+  <div class='man-navigation' style='display:none'>
+    <a href="#NAME">NAME</a>
+    <a href="#SYNOPSIS">SYNOPSIS</a>
+    <a href="#DESCRIPTION">DESCRIPTION</a>
+    <a href="#OPTIONS">OPTIONS</a>
+    <a href="#COPYRIGHT">COPYRIGHT</a>
+  </div>
+  <ol class='man-decor man-head man head'>
+    <li class='tl'>hellocmd(1)</li>
+    <li class='tc'></li>
+    <li class='tr'>hellocmd(1)</li>
+  </ol>
+  <h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>hellocmd</code> - <span class="man-whatis">Say hello.</span>
+</p>
+<h2 id="SYNOPSIS">SYNOPSIS</h2>
+<p><code>hellocmd</code> [options...] [subcommand]</p>
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+<p>Say hello.</p>
+<h2 id="OPTIONS">OPTIONS</h2>
+<dl>
+<dt><code>--load=BOOL</code></dt><dd>Say it in uppercase?</dd>
+</dl>
+<h2 id="COPYRIGHT">COPYRIGHT</h2>
+<p>Copyright (c) 2012</p>
+  <ol class='man-decor man-foot man foot'>
+    <li class='tl'></li>
+    <li class='tc'>January 2012</li>
+    <li class='tr'>hellocmd(1)</li>
+  </ol>
+  </div>
+</body>
+</html>

data/demo/samples/man/hello.1.ronn ADDED

@@ -0,0 +1,19 @@
+hellocmd(1) - Say hello.
+========================
+## SYNOPSIS
+`hellocmd` [options...] [subcommand]
+## DESCRIPTION
+Say hello.
+## OPTIONS
+  * `--load=BOOL`:
+    Say it in uppercase?
+## COPYRIGHT
+Copyright (c) 2012

data/lib/executable.rb CHANGED

@@ -1,143 +1,82 @@
-# = Executable Mixin
-#
-# The Executable mixin is a very quick and and easy way to make almost
-# any class usable via a command line interface. It simply uses writer
-# methods as option setters, and the first command line argument as a
-# method to call with the subsequent arguments passed to the method.
-#
-# The only limitation of this approach is that non-boolean options must
-# be specified with `key=value` notation.
-#
-#   class Example
-#     include Executable
-#
-#     attr_accessor :quiet
-#
-#     def bread(*args)
-#       ["bread", quiet, *args]
-#     end
-#
-#     def butter(*args)
-#       ["butter", quiet, *args]
-#     end
-#   end
-#
-#   ex = Example.new
-#
-#   ex.execute!("butter yum")
-#   => ["butter", nil, "yum"]
-#
-#   ex.execute!("bread --quiet")
-#   => ["butter", true]
-#
-# Executable also provides #option_missing, which you can overriden to provide
-# suitable results when a given command line option has no corresponding
-# writer method.
+# encoding: utf-8
+require 'executable/errors'
+require 'executable/parser'
+require 'executable/help'
+require 'executable/utils'
+require 'executable/domain'
+require 'executable/dispatch'
+# Executable is a mixin for creating robust, inheritable and
+# reusable command line interfaces.
 #
 module Executable
-  # Used the #excute! method to invoke the command.
-  def execute!(argv=ARGV)
-    Executable.execute(self, argv)
+  #
+  # When Exectuable is included into a class, the class is
+  # also extended by `Executable::Doamin`.
+  #
+  def self.included(base)
+    base.extend Domain
   end
-  ## When no attribute write exists for an option that has been given on
-  ## the command line #option_missing is called. Override #option_missing
-  ## to handle these cases, if needed. Otherwise a NoMethodArgument will be
-  ## raised. This callback method receives the name and value of the option.
-  #def option_missing(opt, arg)
-  #  raise NoMethodError, "undefined option `#{opt}=' for #{self}"
-  #end
-  class << self
-    # Process the arguments as an exectuable against the given object.
-    def execute(obj, argv=ARGV)
-      args   = parse(obj, argv)
-      subcmd = args.first
-      if subcmd && !obj.respond_to?("#{subcmd}=")
-        obj.send(*args)
-      else
-        obj.method_missing(*args)
-      end
+  #
+  # Default initializer, simply takes a hash of settings
+  # to set attributes via writer methods. Not existnt
+  # attributes are simply ignored.
+  #
+  def initialize(settings={})
+    settings.each do |k,v|
+      __send__("#{k}=", v) if respond_to?("#{k}=")
     end
+  end
-    # The original name for #execute.
-    alias_method :run, :execute
+public
-    # Parse command line with respect to +obj+.
-    def parse(obj, argv)
-      case argv
-      when String
-        require 'shellwords'
-        argv = Shellwords.shellwords(argv)
-      else
-        argv = argv.dup
-      end
+  #
+  # Command invocation abstract method.
+  #
+  def call(*args)
+    #puts cli.show_help           # TODO: show help instead of error ?
+    raise NotImplementedError
+  end
-      argv = argv.dup
-      args, opts, i = [], {}, 0
-      while argv.size > 0
-        case opt = argv.shift
-        when /=/
-          parse_equal(obj, opt, argv)
-        when /^--/
-          parse_option(obj, opt, argv)
-        when /^-/
-          parse_flags(obj, opt, argv)
-        else
-          args << opt
-        end
-      end
-      return args
-    end
+  #
+  # Convert Executable to Proc object.
+  #
+  def to_proc
+    lambda { |*args| call(*args) }
+  end
-    # Parse a setting option.
-    def parse_equal(obj, opt, argv)
-      if md = /^[-]*(.*?)=(.*?)$/.match(opt)
-        x, v = md[1], md[2]
-      else
-        raise ArgumentError, "#{x}"
-      end
-      # TODO: to_b if 'true' or 'false' ?
-      #if obj.respond_to?("#{x}=")
-        obj.send("#{x}=", v)
-      #else
-      #  obj.option_missing(x, v)
-      #end
-    end
+  alias_method :inspect, :to_s
-    # Parse a named boolean option.
-    def parse_option(obj, opt, argv)
-      x = opt.sub(/^--/, '')
-      #if obj.respond_to?("#{x}=")
-        obj.send("#{x}=", true)
-      #else
-      #  obj.option_missing(x, true)
-      #end
-    end
+  #
+  # Output command line help.
+  #
+  def to_s
+    self.class.help.to_s  # usage ?
+  end
-    # Parse flags. Each character of a flag set is treated as a separate option.
-    # For example:
-    #
-    #   $ foo -abc
-    #
-    # Would be parsed the same as:
-    #
-    #   $ foo -a -b -c
-    #
-    def parse_flags(obj, opt, args)
-      x = opt.sub(/^-/, '')
-      #c = 0
-      x.split(//).each do |k|
-        #if obj.respond_to?("#{k}=")
-          obj.send("#{k}=", true)
-        #else
-        #  obj.option_missing(x, true)
-        #end
-      end
-    end
+  #
+  # Access to underlying Help instance.
+  #
+  def cli
+    self.class.cli
+  end
-  end #class << self
+  #
+  # Override option_missing if needed. This receives the name of the option
+  # and the remaining arguments list. It must consume any arguments it uses
+  # from the begining of the list (i.e. in-place manipulation).
+  #
+  def option_missing(opt, argv)
+    raise NoOptionError, opt
+  end
+  # Base class alteranative ot using the mixin.
+  #
+  class Command
+    include Executable
+  end
 end

data/lib/executable/core_ext.rb ADDED

@@ -0,0 +1,102 @@
+class UnboundMethod
+  if !method_defined?(:source_location)
+    if Proc.method_defined? :__file__  # /ree/
+      def source_location
+        [__file__, __line__] rescue nil
+      end
+    elsif defined?(RUBY_ENGINE) && RUBY_ENGINE =~ /jruby/
+      require 'java'
+      def source_location
+        to_java.source_location(Thread.current.to_java.getContext())
+      end
+    end
+  end
+  #
+  def comment
+    Source.get_above_comment(*source_location)
+  end
+  # Source lookup.
+  #
+  module Source
+    extend self
+    # Read and cache file.
+    #
+    # @param file [String] filename, should be full path
+    #
+    # @return [Array] file content in array of lines
+    def read(file)
+      @read ||= {}
+      @read[file] ||= File.readlines(file)
+    end
+    # Get comment from file searching up from given line number.
+    #
+    # @param file [String] filename, should be full path
+    # @param line [Integer] line number in file
+    #
+    def get_above_comment(file, line)
+      get_above_comment_lines(file, line).join("\n").strip
+    end
+    # Get comment from file searching up from given line number.
+    #
+    # @param file [String] filename, should be full path
+    # @param line [Integer] line number in file
+    #
+    def get_above_comment_lines(file, line)
+      text  = read(file)
+      index = line - 1
+      while index >= 0 && text[index] !~ /^\s*\#/
+        return [] if text[index] =~ /^\s*end/
+        index -= 1
+      end
+      rindex = index
+      while text[index] =~ /^\s*\#/
+        index -= 1
+      end
+      result = text[index..rindex]
+      result = result.map{ |s| s.strip }
+      result = result.reject{ |s| s[0,1] != '#' }
+      result = result.map{ |s| s.sub(/^#/,'').strip }
+      #result = result.reject{ |s| s == "" }
+      result
+    end
+    # Get comment from file searching down from given line number.
+    #
+    # @param file [String] filename, should be full path
+    # @param line [Integer] line number in file
+    #
+    def get_following_comment(file, line)
+      get_following_comment_lines(file, line).join("\n").strip
+    end
+    # Get comment from file searching down from given line number.
+    #
+    # @param file [String] filename, should be full path
+    # @param line [Integer] line number in file
+    #
+    def get_following_comment_lines(file, line)
+      text  = read(file)
+      index = line || 0
+      while text[index] !~ /^\s*\#/
+        return nil if text[index] =~ /^\s*(class|module)/
+        index += 1
+      end
+      rindex = index
+      while text[rindex] =~ /^\s*\#/
+        rindex += 1
+      end
+      result = text[index..(rindex-2)]
+      result = result.map{ |s| s.strip }
+      result = result.reject{ |s| s[0,1] != '#' }
+      result = result.map{ |s| s.sub(/^#/,'').strip }
+      result.join("\n").strip
+    end
+  end
+end

data/lib/executable/dispatch.rb ADDED

@@ -0,0 +1,30 @@
+module Executable
+  # Variation of Executable which provides basic compatibility with
+  # previous versions of Executable. It provides a call method that
+  # automatically dispatches to publich methods.
+  #
+  # Among other uses, Dispatch can be useful for dropping into any class
+  # as a quick and dirty way to work with it on the command line.
+  #
+  # @since 1.2.0
+  module Dispatch
+    Executable.__send__(:append_features, self)
+    #
+    # When Dispatchable is included into a class, the class is
+    # also extended by `Executable::Domain`.
+    #
+    def self.included(base)
+      base.extend Domain
+    end
+    def call(name, *args)
+      public_method(name).call(*args)
+    end
+  end
+  # Dispatch is Legacy.
+  Legacy = Dispatch
+end