executable 1.2.0 → 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.rdoc → HISTORY.md}

@@ -1,6 +1,33 @@
-= RELEASE HISTORY
+# RELEASE HISTORY
 
-== 1.2.0 / 2012-01-31
+## 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
+as well as a few helpful additions the the API.
+
+Changes:
+
+* Improve manpage lookup.
+* Improve overall help output.
+* Add alias_switch and alias_accessor helpers.
+
+
+## 1.2.0 / 2012-01-31
 
 Version 1.2.0 is complete rewrite of Executable. Actually it was decided that
 the old design was too simplistic in it design concept, so another library
@@ -20,7 +47,7 @@ Changes:
 * Supports manpage look-up and display.
 
 
-== 1.1.0 / 2011-04-21
+## 1.1.0 / 2011-04-21
 
 This release simplifies Executable, removing the #option_missing method
 and using the standard #method_missing callback instead. Along with this
@@ -44,7 +71,7 @@ Changes:
   * The #method_missing callback takes the value of the option being set.
 
 
-== 1.0.0 / 2011-04-15
+## 1.0.0 / 2011-04-15
 
 This is the initialize release of Executable (as a stand alone project).
 Executable is a mixin that can turn any class into an commandline interface.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+BSD-2-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/{README.rdoc → README.md}

@@ -1,14 +1,10 @@
-= Executable
+# Executable
 
-{Website}[http://rubyworks.github.com/executable] |
-{Source Code}[http://github.com/rubyworks/executable] |
-{Report Issue}[http://github.com/rubyworks/executable/features] |
-{#rubyworks}[irc://irc.freenode.org/rubyworks]
+[Source Code](https://github.com/rubyworks/executable) |
+[Report Issue](https://github.com/rubyworks/executable/issues)
 
-{<img src="http://travis-ci.org/rubyworks/executable.png"/>}[http://travis-ci.org/rubyworks/executable]
-
-
-== DESCRIPTION
+[![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,
@@ -18,7 +14,7 @@ a complete command line tool using nothing more than Ruby's standard
 syntax. No special DSL is required. 
 
 
-== FEATURES
+## Features
 
 * Easy to use, just mixin or subclass.
 * Define #call to control the command procedure.
@@ -28,18 +24,13 @@ syntax. No special DSL is required.
 * Generate help in plain text or markdown.
 
 
-== LIMITATIONS
+## Limitations
 
 * Ruby 1.9+ only.
 * Help doesn't handle aliases well (yet).
 
 
-== RELEASE NOTES
-
-Please see HISTORY.rdoc file.
-
-
-== SYNOPSIS
+## Overview
 
 CLIs can be built by using a Executable as a mixin, or by subclassing 
 `Executable::Command`. Methods seemlessly handle command-line options.
@@ -48,13 +39,14 @@ methods (those ending in '?') modify them to be boolean switches.
 
 For example, here is a simple "Hello, World!" commandline tool.
 
+```ruby
     require 'executable'
 
     class HelloCommand
       include Executable
 
       # Say it in uppercase?
-      def load=(bool)
+      def loud=(bool)
         @loud = bool
       end
 
@@ -64,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)
@@ -78,17 +70,21 @@ For example, here is a simple "Hello, World!" commandline tool.
         puts str
       end
     end
+```
 
 To make the command available on the command line, add an executable
-to your project passing ARGV to the #execute or #run methods.
+to your project calling the #execute or #run methods.
 
+```ruby
     #!usr/bin/env ruby
     require 'hello.rb'
     HelloCommand.run
+```
 
 If we named this file `hello`, set its execute flag and made it available
 on our systems $PATH, then:
 
+```
     $ hello
     Hello, World!
 
@@ -97,9 +93,11 @@ on our systems $PATH, then:
 
     $ hello --loud John
     HELLO, JOHN!
+```
 
 Executable can also generate help text for commands.
 
+```
     $ hello --help
     USAGE: hello [options]
 
@@ -107,38 +105,75 @@ Executable can also generate help text for commands.
 
     --loud      Say it in uppercase?
     --help      Show this message
+```
 
 If you look back at the class definition you can see it's pulling
 comments from the source to provide descriptions. It pulls the 
-description the command itself from the `#call` method.
+description for the command itself from the `#call` method.
 
 Basic help like this is fine for personal tools, but for public facing
 production applications it is desirable to utilize manpages. To this end,
 Executable provides Markdown formatted help as well. We can access this,
 for example, via `HelloCommand.help.markdown`. The idea with this is that
 we can save the output to `man/hello.ronn` or copy it the top of our `bin/`
-file, edit it to perfection and then use tools such a {ronn}[https://github.com/rtomayko/ronn],
-{binman}[https://github.com/sunaku/binman] or {md2man}[https://github.com/sunaku/md2man]
+file, edit it to perfection and then use tools such a [ronn](https://github.com/rtomayko/ronn),
+[binman](https://github.com/sunaku/binman) or [md2man](https://github.com/sunaku/md2man)
 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
+## Installation
 
 Install with RubyGems in the usual fashion.
 
+```
     $ gem install executable
+```
+
+## 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.
+
+The more of these bullet points a pull request covers, the more likely and quickly it will
+be accepted and merged.
+
+### Testing
+
+[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
+
+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.
 
 
-== LEGAL
+## Copyrights
 
-Copyright (c) 2008 Rubyworks
+Executable is copyrighted open source software.
 
-Distributable in accordance with the *BSD-2-Clause* license.
+    Copyright (c) 2008 Rubyworks (BSD-2-Clause)
 
-See COPYING.rdoc for licensing details.
+It can be distributed and modified in accordance with the **BSD-2-Clause** license.
 
+See LICENSE.txt for details.

data/demo/{00_introduction.rdoc → 00_introduction.md}

@@ -1,4 +1,4 @@
-= Executable
+# Executable
 
 Require Executable library.
 

data/demo/{01_single_command.rdoc → 01_single_command.md}

@@ -1,4 +1,4 @@
-== No Subcommmands
+## No Subcommmands
 
 This example demonstrates using Executable::Command to create a simple command line
 interface without subcommands. (Note the Executable mixin could be used just

data/demo/{02_multiple_commands.rdoc → 02_multiple_commands.md}

@@ -1,4 +1,4 @@
-== Multiple Subcommmands
+## Multiple Subcommmands
 
 Setup an example CLI subclass.
 

data/demo/{03_help_text.rdoc → 03_help_text.md}

@@ -1,4 +1,4 @@
-== Command Help
+## Command Help
 
 Executable Commands can generate help output. It does this by extracting
 the commenst associated with the option methods. A description of the
@@ -62,7 +62,7 @@ The help output,
 
 should be clearly laid out as follows:
 
-    Usage: mycli-c1 [options...] [subcommand]
+    Usage: my c1 [options...] [subcommand]
 
     This does c1.
 
@@ -81,12 +81,12 @@ The help feature can also output ronn-style markdown,
 
 should be clearly laid out as follows:
 
-    mycli-c1(1) - This does c1.
-    ===========================
+    my-c1(1) - This does c1.
+    ========================
 
     ## SYNOPSIS
 
-    `mycli-c1` [options...] [subcommand]
+    `my c1` [options...] [subcommand]
 
     ## DESCRIPTION
 

data/demo/{04_manpage.rdoc → 04_manpage.md}

@@ -1,14 +1,14 @@
-== Manpage
+### Manpages
 
 If a man page is available for a given command using the #show_help
 method will automatically find the manpage and display it.
 
     sample = File.dirname(__FILE__) + '/samples'
 
-    load(sample + '/bin/hello')
-
-    manpage = Hello.cli.manpage
+    manpage = `ruby #{sample}/bin/hello --manpage`.strip
 
     manpage.assert == sample + '/man/hello.1'
 
+Note: Would rather use #load for this, but without a `.rb` on
+the `hello` file, it doesn't seem possible.
 

data/demo/{06_delegate_example.rdoc → 06_delegate_example.md}

@@ -1,4 +1,4 @@
-= Subclass Example
+## Subclass Example
 
 Lets say we have a class that we would like to work with on
 the command line, but want to keep the class itself unchanaged

data/demo/{07_command_methods.rdoc → 07_command_methods.md}

@@ -1,4 +1,4 @@
-= README Example
+## README Example
 
 This is the example used in the documentation.
 

data/demo/{08_dispatach.rdoc → 08_dispatach.md}

@@ -1,4 +1,4 @@
-== Legacy/Dispath
+## Legacy/Dispath
 
 The Dispatch mixin, which is also called Legacy b/c this is how older
 version of Executable worked, provides Executable with a `#call` method

data/demo/{05_optparse_example.rdoc → 09_optparse_example.md}

@@ -1,4 +1,4 @@
-== OptionParser Example
+## OptionParser Example
 
 This example mimics the one given in optparse.rb documentation.
 

data/demo/samples/bin/hello

@@ -1,10 +1,10 @@
-#!/usr/bin/env
+#!/usr/bin/env ruby
 
 require 'executable'
 
 class Hello < Executable::Command
   # Say it in uppercase?
-  def load=(bool)
+  def loud=(bool)
     @loud = bool
   end
 
@@ -27,5 +27,12 @@ class Hello < Executable::Command
     str  = str.upcase if loud?
     puts str
   end
+
+  # Where's the manpage?
+  def manpage!
+    puts cli.manpage
+    exit
+  end
 end
 
+Hello.execute

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