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

executable 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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