executable 1.2.1 → 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd281be8d7d039a36b1628be53a86817d12d30f1d69258d1f5b0dfa84cc99ad4
+  data.tar.gz: 459d53385e0333dd991c4d93f1a2b06e14cf8af188f541d7a0eb50f13b265e45
+SHA512:
+  metadata.gz: c519372eba2ab84e43c919859e52117fbd3d0715ded1721b99f0b471221630ebdd55b8a58485dc6544f3e557a43d71d2fea6e828179dab02a76fbc084388e4a3
+  data.tar.gz: b08c3be0ddf83ac87fb68e29404add4b847b95c6aaaa748bb40bbfd8e585c6a6b126fba8649750776d8d544a5c0600b1e1ee0216bad9990e7a9b4b974bcabeec

data/HISTORY.md

@@ -1,5 +1,20 @@
 # RELEASE HISTORY
 
+## 1.3.0 / 2026-04-05
+
+Maintenance release. Modernized project tooling.
+
+Changes:
+
+* Replace custom Indexer system with standard gemspec.
+* Replace Travis CI with GitHub Actions.
+* Update Rakefile.
+* Fix typo in version.rb module name (Exectuable -> Executable).
+* Switch tests to minitest.
+* Update URLs to HTTPS.
+* Clean up obsolete files and .gitignore.
+
+
 ## 1.2.1 / 2012-12-19
 
 This release imporves the help output and manpage lookup

data/README.md

@@ -1,10 +1,10 @@
-[Website](http://rubyworks.github.com/executable) |
-[Report Issue](http://github.com/rubyworks/executable/features) |
-[Source Code](http://github.com/rubyworks/executable)
-( [![Build Status](https://secure.travis-ci.org/rubyworks/indexer.png)](http://travis-ci.org/rubyworks/indexer) )
+# Executable
 
+[Source Code](https://github.com/rubyworks/executable) |
+[Report Issue](https://github.com/rubyworks/executable/issues)
 
-# Executable
+[![Gem Version](https://img.shields.io/gem/v/executable.svg?style=flat)](https://rubygems.org/gems/executable)
+[![Build Status](https://github.com/rubyworks/executable/actions/workflows/test.yml/badge.svg)](https://github.com/rubyworks/executable/actions/workflows/test.yml)
 
 Executable is to the commandline, what ActiveRecord is the database. 
 You can think of Executable as a *COM*, a Command-line Object Mapper,
@@ -30,7 +30,7 @@ syntax. No special DSL is required.
 * Help doesn't handle aliases well (yet).
 
 
-## Instructions
+## Overview
 
 CLIs can be built by using a Executable as a mixin, or by subclassing 
 `Executable::Command`. Methods seemlessly handle command-line options.
@@ -56,11 +56,11 @@ For example, here is a simple "Hello, World!" commandline tool.
       end
 
       # Show this message.
-      def help?
+      def help!
         cli.show_help
         exit
       end
-      alias :h? :help?
+      alias :h! :help!
 
       # Say hello.
       def call(name)
@@ -122,8 +122,9 @@ to generate the manpages. What's particularly cool about Executable,
 is that once we have a manpage in the standard `man/` location in our project,
 the `#show_help` method will use it instead of the plain text.
 
-For a more detail example see [QED](demo.html)
-and [API](http://rubydoc.info/gems/executable/frames) documentation.
+For a more detailed example see [QED](http://rubyworks.github.com/executable/demo.html),
+[API](http://rubydoc.info/gems/executable/frames) documentation and, in particular,
+the [Wiki](http://wiki.github.com/rubyworks/).
 
 
 ## Installation
@@ -134,26 +135,45 @@ Install with RubyGems in the usual fashion.
     $ gem install executable
 ```
 
-## CONTRIBUTING
+## Contributing
+
+Executable is a [Rubyworks](http://rubyworks.github.com) project. As such it largely
+uses in-house tools for development.
+
+### Submitting Patches
+
+If it is a very small change, just pasting it to an issue is fine. For anything more than
+this please send us a traditional patch, but even better use Github pull requests. 
+Good contributions have the following:
+
+* Well documented code following the conventions of the project.
+* Clearly written tests with good test coverage written using the project's chosen test framework.
+* Use of a git topic branch to keep the change set well isolated.
 
-Executable is a Rubyworks project. As such we largely use in house tools
-for development.
+The more of these bullet points a pull request covers, the more likely and quickly it will
+be accepted and merged.
 
 ### Testing
 
-QED and Microtest are being used for this project.
+[QED](http://rubyworks.github.com/qed) and [Microtest](http://rubyworks.github.com/microtest)
+are used for this project. To run the QED demos just run the `qed` command, probably with bundler,
+so `bundle exec qed`. And to run the microtests you can use `rubytest test/`, again with bundler,
+`bundle exec rubytest test/`.
 
 ### Getting In Touch
 
-* [#rubyworks](irc://irc.freenode.org/rubyworks)
+For direct dialog we have an IRC channel, #rubyworks on freenode. But it's not always manned,
+so a [mailing list](http://groups.google.com/groups/rubyworks-mailinglist) is also available.
+Of course these days, the GitHub [issues page](http://github.com/rubyworks/executable) is
+generally the place get in touch for anything specific to this project.
 
 
 ## Copyrights
 
 Executable is copyrighted open source software.
 
-    Copyright (c) 2008 Rubyworks (BSD-2-Clause License)
+    Copyright (c) 2008 Rubyworks (BSD-2-Clause)
 
-It can be distributed and modified in accordance with the *BSD-2-Clause* license.
+It can be distributed and modified in accordance with the **BSD-2-Clause** license.
 
 See LICENSE.txt for details.

data/lib/executable/completion.rb

@@ -0,0 +1,82 @@
+module Executable
+
+  # Encpsulates command completion.
+  #
+  class Completion
+
+    #
+    # Setup new completion object.
+    #
+    def initialize(cli_class)
+      @cli_class = cli_class
+
+      @subcommands = nil
+      @options     = nil
+    end
+
+    #
+    alias_method :inspect, :to_s
+
+    #
+    # The Executable subclass to which this help applies.
+    #
+    attr :cli_class
+
+    #
+    # List of subcommands converted to a printable string.
+    # But will return +nil+ if there are no subcommands.
+    #
+    # @return [String,NilClass] subcommand list text
+    #
+    def subcommands
+      @subcommands ||= @cli_class.subcommands.keys
+    end
+
+    #
+    def options
+      @options ||= (
+        method_list.map do |meth|
+          case meth.name
+          when /^(.*?)[\!\=]$/
+            name = meth.name.to_s.chomp('!').chomp('=')
+            mark = name.to_s.size == 1 ? '-' : '--'
+            mark + name
+          end
+        end.compact.sort
+      )
+    end
+
+    #
+    def to_s
+      (subcommands + options).join(' ')
+    end
+
+    #
+    def call(*args)
+      puts self
+    end
+
+  private
+
+    #
+    # Produce a list relavent methods.
+    #
+    def method_list
+      list      = []
+      methods   = []
+      stop_at   = cli_class.ancestors.index(Executable::Command) ||
+                  cli_class.ancestors.index(Executable) ||
+                  -1
+      ancestors = cli_class.ancestors[0...stop_at]
+      ancestors.reverse_each do |a|
+        a.instance_methods(false).each do |m|
+          list << cli_class.instance_method(m)
+        end
+      end
+      list
+    end
+
+  end
+
+end
+

data/lib/executable/core_ext/unbound_method.rb

@@ -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/core_ext.rb

@@ -1,102 +1 @@
-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
+require 'executable/core_ext/unbound_method'

data/lib/executable/domain.rb

@@ -3,7 +3,7 @@ module Executable
   #
   module Domain
 
-    #
+    # TODO: Should this be in Help class?
     def usage_name
       list = []
       ancestors.each do |ancestor|
@@ -38,18 +38,24 @@ module Executable
     #     @name
     #   end
     #
+    # TODO: Currently there is an unfortunate issue with using
+    # this helper method. If does not correctly record the location
+    # the method is called, so default help message is wrong.
     #
     def attr_switch(name)
-      attr_writer name
-      module_eval %{
+      file, line = *caller[0].split(':')[0..1]
+      module_eval(<<-END, file, line.to_i)
+        def #{name}=(value)
+          @#{name}=(value)
+        end
         def #{name}?
           @#{name}
         end
-      }
+      END
     end
 
     #
-    # 
+    # Alias a switch.
     #
     def alias_switch(name, origin)
       alias_method "#{name}=", "#{origin}="
@@ -57,7 +63,7 @@ module Executable
     end
 
     #
-    #
+    # Alias an accessor.
     #
     def alias_accessor(name, origin)
       alias_method "#{name}=", "#{origin}="
@@ -72,7 +78,8 @@ module Executable
     end
 
     #
-    # Returns `help.to_s`.
+    # Returns `help.to_s`. If you want to provide your own help
+    # text you can override this method in your command subclass.
     #
     def to_s
       cli.to_s

data/lib/executable/help.rb

@@ -5,9 +5,6 @@ module Executable
   # Encpsulates command help for defining and displaying well formated help
   # output in plain text, markdown or via manpages if found.
   #
-  # TODO: Currently doesn't hande aliases/shortcuts well and simply
-  # lists them as separate entries.
-  #
   # Creating text help in the fly is fine for personal projects, but
   # for production app, ideally you want to have man pages. You can
   # use the #markdown method to generate `.ronn` files and use the
@@ -30,7 +27,9 @@ module Executable
       }
     end
 
+    #
     # Setup new help object.
+    #
     def initialize(cli_class)
       @cli_class = cli_class
 
@@ -198,8 +197,8 @@ module Executable
       end
 
       if !options.empty?
-        s << "OPTIONS\n" + options.map{ |max, opt|
-          "  %2s%-#{max}s %s" % [opt.mark, opt.usage, opt.description]
+        s << "OPTIONS\n" + options.map{ |max, opts, desc|
+          "  %-#{max}s %s" % [opts.join(' '), desc]
         }.join("\n")
       end
 
@@ -240,8 +239,8 @@ module Executable
 
       if !options.empty?
         s << "## OPTIONS"
-        s << options.map{ |max, opt|
-          "  * `#{opt.mark}%s`:\n    %s" % [opt.usage, opt.description]
+        s << options.map{ |max, opts, desc|
+          "  * `%s`:\n    %s" % [opts.join(' '), desc]
         }.join("\n\n")
       end
 
@@ -301,10 +300,17 @@ module Executable
         end
       end    
 
-      max = option_list.map{ |opt| opt.usage.size }.max.to_i + 2
+      # if two options have the same description, they must aliases
+      aliased_options = option_list.group_by{ |opt| opt.description }
+
+      list = aliased_options.map do |desc, opts|
+        [opts.map{ |o| "%s%s" % [o.mark, o.usage] }, desc]
+      end
+
+      max = list.map{ |opts, desc| opts.join(' ').size }.max.to_i + 2
 
-      option_list.map do |opt|
-        [max, opt]
+      list.map do |opts, desc|
+        [max, opts, desc]
       end
     end
 
@@ -350,11 +356,11 @@ module Executable
                   -1
       ancestors = cli_class.ancestors[0...stop_at]
       ancestors.reverse_each do |a|
-        a.instance_methods(false).each do |m|
+        a.public_instance_methods(false).each do |m|
           list << cli_class.instance_method(m)
         end
       end
-      list
+      list #.uniq
     end
 
     #

data/lib/executable/parser.rb

@@ -25,7 +25,12 @@ module Executable
 
       cmd, argv = parse_subcommand(argv)
       cli  = cmd.new
-      args = parse_arguments(cli, argv)
+
+      if argv.first == "_"
+        cli = Completion.new(cli.class)
+      else
+        args = parse_arguments(cli, argv)
+      end
 
       return cli, args
     end
@@ -141,8 +146,7 @@ module Executable
       end
     end
 
-    # TODO: parse_flags needs some thought concerning character
-    # spliting and arguments.
+    # TODO: parse_flags needs some thought concerning character spliting and arguments.
 
     #
     # Parse single-dash command-line option.

data/lib/executable/version.rb

@@ -1,20 +1,3 @@
-module Exectuable
-
-  #
-  DIRECTORY = File.dirname(__FILE__)
-
-  #
-  def self.const_missing(name)
-    index[name.to_s.downcase] || super(name)
-  end
-
-  #
-  def self.index
-    @index ||= (
-      require 'yaml'
-      YAML.load(File.new(DIRECTORY + '/../executable.yml'))
-    )
-  end
-
+module Executable
+  VERSION = '1.3.0'
 end
-

data/lib/executable.rb

@@ -3,6 +3,7 @@
 require 'executable/errors'
 require 'executable/parser'
 require 'executable/help'
+require 'executable/completion'
 require 'executable/utils'
 require 'executable/domain'
 require 'executable/dispatch'
@@ -58,7 +59,7 @@ public
   end
 
   #
-  # Access to underlying Help instance.
+  # Access to underlying cli instance.
   #
   def cli
     self.class.cli