executable 1.1.0 → 1.2.0

data/HISTORY.rdoc

@@ -0,0 +1,55 @@
+= RELEASE HISTORY
+
+== 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
+that was in the works, called Executioner, and briefly CLI::Base, was
+ported over. And with some API changes, it is now the new Executable project.
+The idea of the project is generally the same, but Executable now offers
+more features, such as good help output and namespace-based subcomamnds.
+Of course, to accommodate all this the API had to change some over
+the previous version, so be sure to read the API documentation.
+
+Changes:
+
+* Deprecate old implementation.
+* Port Executioner project over to become new Executable project.
+* Supports namespace-base subcommmands.
+* Supports formatted help output in plain text and markdown.
+* Supports manpage look-up and display.
+
+
+== 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
+the special error class, +NoOptionError+, has been removed. This release
+also fixes an issue with inconsistent arguments being passed to the callback.
+Finally it renames the #execute_command method to simple #execute!.
+
+Changes:
+
+* Name Changes
+
+  * Renamed `#execute_command` method to `#execute!`.
+
+* Deprecations
+
+  * Rely on #method_missing callback instead of special #option_missing method.
+  * The +NoOptionError+ exception class is no longer needed because of above.
+
+* Bug Fixes
+
+  * The #method_missing callback takes the value of the option being set.
+
+
+== 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.
+
+* 1 Major Enhancement
+
+  * Birthday!
+

data/README.rdoc

@@ -1,94 +1,144 @@
 = 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]
+
+{<img src="http://travis-ci.org/rubyworks/executable.png"/>}[http://travis-ci.org/rubyworks/executable]
+
+
 == DESCRIPTION
 
-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 the method to call, with the subsequent arguments
-passed to the method.
+Executable is to the commandline, what ActiveRecord is the database. 
+You can think of Executable as a *COM*, a Command-line Object Mapper,
+just as ActiveRecord is an ORM (Object Relational Mapper). Any class
+mixing in Executable or subclassing Executable::Command can define
+a complete command line tool using nothing more than Ruby's standard
+syntax. No special DSL is required. 
 
 
 == FEATURES
 
-* Super easy to use, just mixin.
+* Easy to use, just mixin or subclass.
+* Define #call to control the command procedure.
 * Public writers become options.
-* Public methods become subcommands.
+* Namespace children become subcommands.
+* Or easily dispatch subcommands to public methods.
+* Generate help in plain text or markdown.
 
 
-== RESOURCES
+== LIMITATIONS
 
-* http://rubyworks.github.com/executable
-* http://github.com/rubyworks/executable
+* Ruby 1.9+ only.
+* Help doesn't handle aliases well (yet).
 
 
 == RELEASE NOTES
 
-Please see HISTORY file.
+Please see HISTORY.rdoc file.
 
 
 == SYNOPSIS
 
-Simply mixin Executable, then call #execute_command.
+CLIs can be built by using a Executable as a mixin, or by subclassing 
+`Executable::Command`. Methods seemlessly handle command-line options.
+Writer methods (those ending in '=') correspond to options and query
+methods (those ending in '?') modify them to be boolean switches. 
+
+For example, here is a simple "Hello, World!" commandline tool.
+
+    require 'executable'
+
+    class HelloCommand
+      include Executable
+
+      # Say it in uppercase?
+      def load=(bool)
+        @loud = bool
+      end
+
+      #
+      def loud?
+        @loud
+      end
+
+      # Show this message.
+      def help?
+        cli.show_help
+        exit
+      end
+      alias :h? :help?
+
+      # Say hello.
+      def call(name)
+        name = name || 'World'
+        str  = "Hello, #{name}!"
+        str  = str.upcase if loud?
+        puts str
+      end
+    end
 
-  class X
-    include Executable
+To make the command available on the command line, add an executable
+to your project passing ARGV to the #execute or #run methods.
 
-    attr_accessor :quiet
+    #!usr/bin/env ruby
+    require 'hello.rb'
+    HelloCommand.run
 
-    attr_accessor :size
+If we named this file `hello`, set its execute flag and made it available
+on our systems $PATH, then:
 
-    def bread(*args)
-      ["bread", quiet, size, *args]
-    end
+    $ hello
+    Hello, World!
 
-    def butter(*args)
-      ["butter", quiet, size, *args]
-    end
-  end
+    $ hello John
+    Hello, John!
 
-  x = X.new
+    $ hello --loud John
+    HELLO, JOHN!
 
-  x.execute!("butter yum")
-  => ["butter", nil, nil, "yum"]
+Executable can also generate help text for commands.
 
-  x.execute!("bread --quiet --size=big")
-  => ["bread", true, "big"]
+    $ hello --help
+    USAGE: hello [options]
 
+    Say hello.
 
-Notice that Executable requires an equal-sign (<code>=</code>) be used
-when specifying values for non-boolean attributes.
+    --loud      Say it in uppercase?
+    --help      Show this message
 
-To make the command available on the command line, add an executable
-to your project passing ARGV to the #execute_command method.
+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.
 
-  #!usr/bin/env ruby
-  require 'x'
-  x = X.new
-  x.execute_command(ARGV)
+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]
+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.
 
-== INSTALL
 
-  $ gem install executable
+== INSTALLATION
 
+Install with RubyGems in the usual fashion.
 
-== LEGAL
+    $ gem install executable
 
-(Apache 2.0)
 
-Copyright (c) 2009 Thomas Sawyer
+== LEGAL
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this program except in compliance with the License.
-You may obtain a copy of the License at
+Copyright (c) 2008 Rubyworks
 
-   http://www.apache.org/licenses/LICENSE-2.0
+Distributable in accordance with the *BSD-2-Clause* license.
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+See COPYING.rdoc for licensing details.
 

data/Schedule.reap

@@ -0,0 +1,17 @@
+task :default => [:test]
+
+desc "run unit tests (needs rubytest)"
+task :test do
+  sh "rubytest -Ilib test/*.rb"
+end
+
+desc "render README.rdoc to web/readme.html (need malt)"
+task :readme do
+  sh "malt README.rdoc > web/readme.html"
+end
+
+# if `README.rdoc` changes generate `web/readme.html`.
+file 'README.rdoc' do
+  sh "malt README.rdoc > web/readme.html"
+end
+

data/demo/00_introduction.rdoc

@@ -0,0 +1,6 @@
+= Executable
+
+Require Executable library.
+
+  require 'executable'
+

data/demo/01_single_command.rdoc

@@ -0,0 +1,44 @@
+== 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
+as well).
+
+    class NoSubCommandCLI < Executable::Command
+
+      attr :result
+
+      def o?
+        @o
+      end
+
+      def o=(flag)
+        @o = flag
+      end
+
+      def call
+        if o?
+          @result = "with"
+        else
+          @result = "without"
+        end
+      end
+
+    end
+
+Execute the CLI on an example command line.
+
+    cli = NoSubCommandCLI.run('')
+    cli.result.assert == 'without'
+
+Execute the CLI on an example command line.
+
+    cli = NoSubCommandCLI.run('-o')
+    cli.result.assert == 'with'
+
+There are two important things to notices heres. Frist, that #main is being
+called in each case. It is the method called with no other subcommands are
+defined. And second, the fact the a `o?` method is defined to compliment the
+`o=` writer, informs Executable that `-o` is an option _flag_, not taking
+any parameters.
+

data/demo/02_multiple_commands.rdoc

@@ -0,0 +1,125 @@
+== Multiple Subcommmands
+
+Setup an example CLI subclass.
+
+    class MyCLI < Executable::Command
+      attr :result
+
+      def initialize
+        @result = []
+      end
+
+      def g=(value)
+        @result << "g" if value
+      end
+
+      def g?
+        @result.include?("g")
+      end
+
+      #
+      class C1 < self
+        def call
+          @result << "c1"
+        end
+
+        def o1=(value)
+          @result << "c1_o1 #{value}"
+        end
+
+        def o2=(value)
+          @result << "c1_o2 #{value}"
+        end
+      end
+
+      #
+      class C2 < Executable::Command
+        attr :result
+
+        def initialize
+          @result = []
+        end
+
+        def call
+          @result << "c2"
+        end
+
+        def o1=(value)
+          @result << "c2_o1 #{value}"
+        end
+
+        def o2=(value)
+          @result << "c2_o2" if value
+        end
+
+        def o2?
+          @result.include?("c2_o2")
+        end
+      end
+
+    end
+
+Instantiate and run the class on an example command line.
+
+Just a command.
+
+    cli = MyCLI.run('c1')
+    cli.result.assert == ['c1']
+
+Command with global option.
+
+    cli = MyCLI.run('c1 -g')
+    cli.result.assert == ['g', 'c1']
+
+Command with an option.
+
+    cli = MyCLI.run('c1 --o1 A')
+    cli.result.assert == ['c1_o1 A', 'c1']
+
+Command with two options.
+
+    cli = MyCLI.run('c1 --o1 A --o2 B')
+    cli.result.assert == ['c1_o1 A', 'c1_o2 B', 'c1']
+
+Try out the second command.
+
+    cli = MyCLI.run('c2')
+    cli.result.assert == ['c2']
+
+Seoncd command with an option.
+
+    cli = MyCLI.run('c2 --o1 A')
+    cli.result.assert == ['c2_o1 A', 'c2']
+
+Second command with two options.
+
+    cli = MyCLI.run('c2 --o1 A --o2')
+    cli.result.assert == ['c2_o1 A', 'c2_o2', 'c2']
+
+Since C1#main takes not arguments, if we try to issue a command
+that will have left over arguments, then an ArgumentError will be raised.
+
+    expect ArgumentError do
+      cli = MyCLI.run('c1 a')
+    end
+
+How about a non-existenct subcommand.
+
+    expect NotImplementedError do
+      cli = MyCLI.run('q')
+      cli.result.assert == ['q']
+    end
+
+How about an option only.
+
+    expect NotImplementedError do
+      cli = MyCLI.run('-g')
+      cli.result.assert == ['-g']
+    end
+
+How about a non-existant options.
+
+    expect Executable::NoOptionError do
+      MyCLI.run('c1 --foo')
+    end
+