executable 1.1.0 → 1.2.0

data/demo/03_help_text.rdoc

@@ -0,0 +1,109 @@
+== Command Help
+
+Executable Commands can generate help output. It does this by extracting
+the commenst associated with the option methods. A description of the
+command itself is taken from the comment on the `#call` method. Only
+the first line of a comment is used, so the reset of the comment can
+still be catered to documention tools such as YARD and RDoc.
+
+Let's setup an example CLI subclass to demonstrate this.
+
+    class MyCLI < Executable::Command
+
+      # This is global option -g.
+      # Yadda yadda yadda...
+      def g=(bool)
+        @g = bool
+      end
+
+      def g?; @g; end
+
+      # Subcommand `c1`.
+      class C1 < self
+
+        # This does c1.
+        def call(*args)
+        end
+
+        # This is option --o1 for c1.
+        def o1=(value)
+        end
+
+        # This is option --o2 for c1.
+        def o2=(value)
+        end
+
+      end
+
+      # Subcommand `c2`.
+      class C2 < self
+
+        # This does c2.
+        def call(*args)
+        end
+
+        # This is option --o1 for c2.
+        def o1=(value)
+        end
+
+        # This is option --o2 for c2.
+        def o2=(value)
+        end
+
+      end
+
+    end
+
+=== Plain Text
+
+The help output,
+
+    @out = MyCLI::C1.help.to_s
+
+should be clearly laid out as follows:
+
+    Usage: mycli-c1 [options...] [subcommand]
+
+    This does c1.
+
+    OPTIONS
+       -g          This is global option -g.
+      --o1=VALUE   This is option --o1 for c1.
+      --o2=VALUE   This is option --o2 for c1.
+
+    Copyright (c) 2012
+
+=== Markdown
+
+The help feature can also output ronn-style markdown,
+
+    @out = MyCLI::C1.help.markdown
+
+should be clearly laid out as follows:
+
+    mycli-c1(1) - This does c1.
+    ===========================
+
+    ## SYNOPSIS
+
+    `mycli-c1` [options...] [subcommand]
+
+    ## DESCRIPTION
+
+    This does c1.
+
+    ## OPTIONS
+
+      * `-g`:
+        This is global option -g.
+
+      * `--o1=VALUE`:
+        This is option --o1 for c1.
+
+      * `--o2=VALUE`:
+        This is option --o2 for c1.
+
+    ## COPYRIGHT
+
+    Copyright (c) 2012
+

data/demo/04_manpage.rdoc

@@ -0,0 +1,14 @@
+== Manpage
+
+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.assert == sample + '/man/hello.1'
+
+

data/demo/05_optparse_example.rdoc

@@ -0,0 +1,152 @@
+== OptionParser Example
+
+This example mimics the one given in optparse.rb documentation.
+
+    require 'ostruct'
+    require 'time'
+
+    class ExampleCLI < Executable::Command
+
+      CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
+      CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
+
+      attr :options
+
+      def initialize
+        super
+        reset
+      end
+
+      def reset
+        @options = OpenStruct.new
+        @options.library = []
+        @options.inplace = false
+        @options.encoding = "utf8"
+        @options.transfer_type = :auto
+        @options.verbose = false
+      end
+
+      # Require the LIBRARY before executing your script
+      def require=(lib)
+        options.library << lib
+      end
+      alias :r= :require=
+
+      # Edit ARGV files in place (make backup if EXTENSION supplied)
+      def inplace=(ext)
+        options.inplace = true
+        options.extension = ext
+        options.extension.sub!(/\A\.?(?=.)/, ".")  # ensure extension begins with dot.
+      end
+      alias :i= :inplace=
+
+      # Delay N seconds before executing
+      # Cast 'delay' argument to a Float.
+      def delay=(n)
+        options.delay = n.to_float
+      end
+
+      # Begin execution at given time
+      # Cast 'time' argument to a Time object.
+      def time=(time)
+        options.time = Time.parse(time)
+      end
+      alias :t= :time=
+
+      # Specify record separator (default \\0)
+      # Cast to octal integer.
+      def irs=(octal)
+        options.record_separator = octal.to_i(8)
+      end
+      alias :F= :irs=
+
+      # Example 'list' of arguments
+      # List of arguments.
+      def list=(args)
+        options.list = list.split(',')
+      end
+
+      # Keyword completion.  We are specifying a specific set of arguments (CODES
+      # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
+      # the shortest unambiguous text.
+      CODE_LIST = (CODE_ALIASES.keys + CODES)
+
+      help.option(:code, "Select encoding (#{CODE_LIST})")
+
+      # Select encoding
+      def code=(code)
+        codes = CODE_LIST.select{ |x| /^#{code}/ =~ x }
+        codes = codes.map{ |x| CODE_ALIASES.key?(x) ? CODE_ALIASES[x] : x }.uniq
+        raise ArgumentError unless codes.size == 1
+        options.encoding = codes.first
+      end
+
+      # Select transfer type (text, binary, auto)
+      # Optional argument with keyword completion.
+      def type=(type)
+        raise ArgumentError unless %w{text binary auto}.include(type.downcase)
+        options.transfer_type = type.downcase
+      end
+
+      # Run verbosely
+      # Boolean switch.
+      def verbose=(bool)
+        options.verbose = bool
+      end
+      def verbose?
+        @options.verbose
+      end
+      alias :v= :verbose=
+      alias :v? :verbose?
+
+      # Show this message
+      # No argument, shows at tail.  This will print an options summary.
+      def help!
+        puts help_text
+        exit
+      end
+      alias :h! :help!
+
+      # Show version
+      # Another typical switch to print the version.
+      def version?
+        puts Executor::VERSION
+        exit
+      end
+
+      #
+      def call
+        # ... main procedure here ...
+      end
+    end
+
+We will run some scenarios on this example to make sure it works.
+
+   cli = ExampleCLI.execute('-r=facets')
+   cli.options.library.assert == ['facets']
+
+Make sure time option parses.
+
+   cli = ExampleCLI.execute('--time=2010-10-10')
+   cli.options.time.assert == Time.parse('2010-10-10')
+
+Make sure code lookup words and is limted to the selections provided.
+
+   cli = ExampleCLI.execute('--code=ji')
+   cli.options.encoding.assert == 'iso-2022-jp'
+
+   expect ArgumentError do
+     ExampleCLI.execute('--code=xxx')
+   end
+
+Ensure +irs+ is set to an octal number.
+
+   cli = ExampleCLI.execute('-F 32')
+   cli.options.record_separator.assert == 032
+
+Ensure extension begins with dot and inplace is set to true.
+
+   cli = ExampleCLI.execute('--inplace txt')
+   cli.options.extension.assert == '.txt'
+   cli.options.inplace.assert == true
+

data/demo/06_delegate_example.rdoc

@@ -0,0 +1,40 @@
+= 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
+without mixin.
+
+    class Hello
+      attr_accessor :name
+
+      def initialize(name="World")
+        @name = name
+      end
+
+      def hello
+        @output = "Hello, #{name}!"
+      end
+
+      def output
+        @output
+      end
+    end
+
+Rather then including Exectuable in the class directly, we can
+create a subclass and use it instead.
+
+    class HelloCommand < Hello
+      include Executable
+
+      def call(*args)
+        hello
+      end
+    end
+
+Now we can execute the command perfectly well.
+
+    cmd = HelloCommand.execute(['hello', '--name=Fred'])
+    cmd.output.assert == "Hello, Fred!"
+
+And the original class remains undisturbed.
+

data/demo/07_command_methods.rdoc

@@ -0,0 +1,36 @@
+= README Example
+
+This is the example used in the documentation.
+
+    class Example
+      include Executable
+
+      attr_switch :quiet
+
+      def bread(*args)
+        ["bread", quiet?, *args]
+      end
+
+      def butter(*args)
+        ["butter", quiet?, *args]
+      end
+
+      # Route call to methods.
+      def call(name, *args)
+        meth = public_method(name)
+        meth.call(*args)
+      end
+    end
+
+Use a subcommand and an argument.
+
+    c, a = Example.parse(['butter', 'yum'])
+    r = c.call(*a)
+    r.assert == ["butter", nil, "yum"]
+
+A subcommand and a boolean option.
+
+    c, a = Example.parse(['bread', '--quiet'])
+    r = c.call(*a)
+    r.assert == ["bread", true]
+

data/demo/08_dispatach.rdoc

@@ -0,0 +1,29 @@
+== 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
+that automatically routes the to a method given by the first argument.
+
+  class DispatchExample < Executable::Command
+    include Legacy
+
+    attr :result
+
+    def foo
+      @result = :foo
+    end
+
+    def bar
+      @result = :bar
+    end
+
+  end
+
+Now when we invoke the command, the 
+
+  eg = DispatchExample.run('foo')
+  eg.result.assert == :foo
+
+  eg = DispatchExample.run('bar')
+  eg.result.assert == :bar
+

data/demo/applique/ae.rb

@@ -0,0 +1 @@
+require 'ae'

data/demo/applique/compare.rb

@@ -0,0 +1,4 @@
+When 'should be clearly laid out as follows' do |text|
+  text = text.sub('$0', File.basename($0))
+  @out.strip.assert == text.strip
+end

data/demo/applique/exec.rb

@@ -0,0 +1 @@
+require 'executable'

data/demo/samples/bin/hello

@@ -0,0 +1,31 @@
+#!/usr/bin/env
+
+require 'executable'
+
+class Hello < Executable::Command
+  # 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
+

data/demo/samples/man/hello.1

@@ -0,0 +1,22 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "HELLOCMD" "1" "January 2012" "" ""
+.
+.SH "NAME"
+\fBhellocmd\fR \- Say hello\.
+.
+.SH "SYNOPSIS"
+\fBhellocmd\fR [options\.\.\.] [subcommand]
+.
+.SH "DESCRIPTION"
+Say hello\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-\-load=BOOL\fR
+Say it in uppercase?
+.
+.SH "COPYRIGHT"
+Copyright (c) 2012