clio 0.0.1 → 0.2.0

data/lib/clio/usage/signature.rb

@@ -0,0 +1,55 @@
+module Clio
+
+  module Usage #:nodoc:
+
+    # = Command Signature
+    #
+    # Used by the Usage::Parser as the end result
+    # of parsing a Usage::Command.
+    #
+    class Signature
+      def initialize(c, a, o)
+        @signature  = [c, a, o]
+        @command    = c
+        @arguments  = a
+        @options    = o
+      end
+
+      attr :command
+      attr :arguments
+      attr :options
+      attr :signature
+
+      def to_a; @signature; end
+
+      def parameters
+        @arguments + [@options]
+      end
+
+      def inspect; "#<#{self.class}:" + @signature.inspect + ">"; end
+
+      #
+      def method_missing(s, *a)
+        s = s.to_s
+        case s
+        #when /[=]$/
+        #  n = s.chomp('=')
+        #  usage.option(n).type(*a)
+        #  #parser.parse
+        #  res = parser.options[n.to_sym]
+        #when /[!]$/
+        #  n = s.chomp('!')
+        #  res = parser.parse
+        when /[?]$/
+          options[s.chomp('?').to_sym]
+        else
+          options[s.to_sym]
+        end
+      end
+
+    end#class Signature
+
+  end#module Usage
+
+end#module Clio
+

data/meta/abstract

@@ -0,0 +1,3 @@
+Clio makes commandline interfaces easy.
+It provides both commandline parsing
+as well as console output routines.

data/meta/authors

@@ -0,0 +1 @@
+7rans <transfire@gmail.com>

data/meta/created

@@ -0,0 +1 @@
+Fri Aug 08 23:09:48 -0400 2008

data/meta/homepage

@@ -0,0 +1 @@
+http://clio.rubyforge.org

data/meta/license

@@ -0,0 +1 @@
+LGPLv3

data/meta/repository

@@ -0,0 +1 @@
+git://rubyforge.org/clio.git

data/meta/summary

@@ -0,0 +1 @@
+Clio makes commandline interfaces easy.

data/spec/commandline/autousage.rd

@@ -0,0 +1,56 @@
+= Method Missing "Auto" Usage
+
+Require Commandline library.
+
+    require 'clio/commandline'
+    $0 = 'test'
+
+Handles a toplevel option using method_missing.
+
+    cli = Clio::Commandline.new('--verbose')
+    cli.verbose?
+    cli.to_s.assert == 'test [--verbose]'
+
+Handles a toplevel option with aliases using method_missing.
+
+    cli = Clio::Commandline.new('--verbose')
+    cli.verbose?(:v)
+    cli.to_s.assert == 'test [-v --verbose]'
+
+Returns a toplevel option value"
+
+    cli = Clio::Commandline.new('--verbose')
+    cli.verbose?(:v).assert == true
+
+Create new commandline object.
+
+    cmd = Clio::Commandline.new('--verbose')
+    cmd.usage.command('foo')
+    cmd.parse
+
+== Single Character Option
+
+Create new Commandline object.
+
+    @cmd = Clio::Commandline.new('-V')
+
+Returns a toplevel option value.
+
+    @cmd.verbose?(:V).assert == true
+
+== Option Literal Shorthand
+
+An option and a subcommand parsed statically.
+
+    $0 = 'test'
+    @cli = Clio::Commandline.new('-V foo')
+    @cli.usage.opt('--verbose -V')
+    @cli.usage.command('foo')
+    @cli.parse
+
+Parses the option correctly.
+
+    @cli.options[:verbose].assert == true
+
+QED.
+

data/spec/commandline/bracket.rd

@@ -0,0 +1,64 @@
+= Command Definition using Bracket Notation
+
+Require commandline library.
+
+  require 'clio/commandline'
+
+Since this not a real command line application,
+lets fake one called 'test'.
+
+    $0 = 'test'
+
+We can use a method to define a subcommand.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['doc']
+    cmd.to_s.assert == 'test doc'
+
+We can use a question-method to define a switch.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['doc']
+    cmd.usage['--verbose']
+    cmd.to_s.assert == 'test [--verbose] doc'
+
+The switch method can also take option aliases.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['--verbose -v']
+    cmd.to_s.assert == 'test [-v --verbose]'
+
+The command can take argument to process as suboptions
+and arguments.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['doc']['--output=PATH']
+    cmd.to_s.assert == 'test doc [--output=PATH]'
+    cmd.usage.doc.to_s.assert == 'doc [--output=PATH]'
+
+An option and a subcommand parsed statically.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['--verbose -v']
+    cmd.usage['doc']['--output=PATH']
+    cmd.usage['doc']['<file>']
+    cmd.to_s.assert == 'test [-v --verbose] doc [--output=PATH] <file>'
+
+We can define help for these commands and options using
+a seaprate help! call.
+
+    cmd = Clio::Commandline.new
+    cmd.usage['doc']['--output=PATH']
+    cmd.usage['--verbose -v']
+
+    #cmd.usage['doc'] = 'generate documentation'
+    #cmd.usage['--verbose -v'] = 'verbose mode'
+
+    cmd.usage.help!(
+      'doc', 'generate documentation',
+      '--verbose', 'verbose mode'
+    )
+
+    cmd.usage.options[0].name.assert == 'verbose'
+
+QED.

data/spec/commandline/completion.rd

@@ -0,0 +1,38 @@
+= Commandline Tab Completion
+
+Load commandline library.
+
+  require 'clio/commandline'
+
+Create a new command line object.
+
+  $0 = 'c0'
+  @cli = Clio::Commandline.new
+
+Specify usage for comamndline.
+
+  @cli.usage.option('o0')
+  @cli.usage.command('c1').opt('--o1=TYPE -o')
+  @cli.usage.command('c1 c2').option('o2')
+  @cli.usage.command('c1 c2').argument('a')
+  @cli.usage.command('c1 c2').argument('b')
+  @cli.usage.command('c1 c2').argument('c')
+
+First lets make sure it parses okay.
+
+  @cli.parse('--o0 c1 --o1 atype c2 --o2 a b c')
+
+Now let try some tab completion. First a command.
+
+  #@cli.parse('c1 -')
+  @cli.completion('c1').assert == ['-o --o1=TYPE', 'c2']
+
+Now an option.
+
+  @cli.completion('c1 --o1').assert == ["TYPE"]
+
+QED.
+
+
+
+

data/spec/commandline/define.rd

@@ -0,0 +1,44 @@
+= Commandline Definition using Core Notation
+
+Require commandline library.
+
+  require 'clio/commandline'
+
+Fake that we running an executable called 'test'.
+
+    $0 = 'test'
+
+Create a new commandline object.
+
+    @cmd = Clio::Commandline.new
+
+We can define a subcommand using #command on #usage.
+
+    @cmd.usage.command('foo')
+    @cmd.to_s.assert == 'test foo'
+
+We can define a toplevel switch using #switch.
+
+    @cmd.usage.switch('verbose')
+    @cmd.to_s.assert == 'test [--verbose] foo'
+
+Switches can have aliases.
+
+    @cmd.usage.switch(:verbose, :v)
+    @cmd.to_s.assert == 'test [-v --verbose] foo'
+
+There can be mulitple subcommands.
+
+    @cmd.usage.command('foo bar')
+    @cmd.to_s.assert == 'test [-v --verbose] foo bar'
+
+Let's bring it all together in one example.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.switch(:verbose, :v)
+    cmd.usage.switch(:force, :f)
+    cmd.usage.command('foo')
+    cmd.usage.command('bar')
+    cmd.to_s.assert == 'test [-v --verbose] [-f --force] [foo | bar]'
+
+QED.

data/spec/commandline/method.rd

@@ -0,0 +1,60 @@
+= Command Definition using Method Notation
+
+Require commandline library.
+
+  require 'clio/commandline'
+
+Since this not a real command line application,
+lets fake one called 'test'.
+
+    $0 = 'test'
+
+We can use a method to define a subcommand.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.doc
+    cmd.to_s.assert == 'test doc'
+
+We can use a question-method to define a switch.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.doc
+    cmd.usage.verbose?
+    cmd.to_s.assert == 'test [--verbose] doc'
+
+The switch method can also take option aliases.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.verbose?(:v)
+    cmd.to_s.assert == 'test [-v --verbose]'
+
+The command can take argument to process as suboptions
+and arguments.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.doc('--output=PATH')
+    cmd.to_s.assert == 'test doc [--output=PATH]'
+    cmd.usage.doc.to_s.assert == 'doc [--output=PATH]'
+
+An option and a subcommand parsed statically.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.doc('--output=PATH')
+    cmd.usage.verbose?(:v)
+    cmd.to_s.assert == 'test [-v --verbose] doc [--output=PATH]'
+
+We can define help for these commands and options using
+a seaprate help! call.
+
+    cmd = Clio::Commandline.new
+    cmd.usage.doc('--output=PATH')
+    cmd.usage.verbose?(:v)
+
+    cmd.usage.help!(
+      'doc', 'generate documentation',
+      '--verbose', 'verbose mode'
+    )
+
+    cmd.usage.options[0].name.assert == 'verbose'
+
+QED.

data/spec/commandline/parse.rd

@@ -0,0 +1,72 @@
+= Command Parsing
+
+Require command library.
+
+  require 'clio/commandline'
+
+A single toplevel option.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.option('force')
+  cmd.parse('--force')
+  cmd.options.assert == {:force=>true}
+
+A single toplevel option with an alias.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.option('force', 'f')
+  cmd.parse('-f')
+  cmd.options.assert == {:force=>true}
+
+A subcommand.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.command('foo')
+  cmd.parse('foo')
+  cmd.command.assert == 'foo'
+  cmd.commands.assert == ['foo']
+
+A subcommand with an option.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.command('foo')
+  cmd.usage.command('foo').option('verbose')
+  cmd.parse('foo --verbose')
+
+  cmd.command.assert == 'foo'
+  cmd.commands.assert == ['foo']
+  cmd.options.assert == {:verbose=>true}
+
+  cmd[0].options.assert == {}
+  cmd[1].options.assert == {:verbose=>true}
+
+Multiple subcommands.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.command('foo').command('bar').option('verbose')
+  cmd.parse('foo bar --verbose')
+
+  cmd.command.assert == 'foo bar'
+  cmd.commands.assert == ['foo','bar']
+  cmd.options == {:verbose=>true}
+
+  cmd[0].options.assert == {}
+  cmd[1].options.assert == {}
+  cmd[2].options.assert == {:verbose=>true}
+
+Multiple subcommands.
+
+  cmd = Clio::Commandline.new
+  cmd.usage.command('foo').option('verbose')
+  cmd.usage.command('foo bar')
+  cmd.parse('foo bar --verbose')
+
+  cmd.command.assert == 'foo bar'
+  cmd.commands.assert == ['foo','bar']
+  cmd.options == {:verbose=>true}
+
+  cmd[0].options.assert == {}
+  cmd[1].options.assert == {}
+  cmd[2].options.assert == {:verbose=>true}
+
+QED.

data/spec/commandline/scenario.rd

@@ -0,0 +1,81 @@
+= Commandline Parses Correctly
+
+Load commandline library.
+
+    require 'clio/commandline'
+
+Create a new command line object.
+
+    $0 = 'c0'
+    @cli = Clio::Commandline.new('--o0 c1 --o1 c2 --o2 a b c')
+
+Specify usage for comamndline.
+
+    @cli.usage.option('o0')
+    @cli.usage.command('c1').option('o1')
+    @cli.usage.command('c1 c2').option('o2')
+    @cli.usage.command('c1 c2').argument('a')
+    @cli.usage.command('c1 c2').argument('b')
+    @cli.usage.command('c1 c2').argument('c')
+
+    #@cli.usage.option('o0')
+    #@cliusage.argument('a0')
+    #@cli.usage.command('c1').option('o1')
+    #@cli.usage.command('c1').argument('a1')
+    #@cli.usage.command('c1').command('c2').option('o2')
+    #@cli.usage.command('c1').command('c2').argument('a2')
+
+Usage string is correct.
+
+    @cli.to_s.assert == 'c0 [--o0] c1 [--o1] c2 [--o2] <a> <b> <c>'
+
+Parses without error.
+
+    @cli.parse
+
+Full signature is correct.
+
+    @cli.to_a.assert == [
+      ["c0", [], {:o0=>true}],
+      ["c1", [], {:o1=>true}],
+      ["c2", ["a", "b", "c"], {:o2=>true}]
+    ]
+
+Options provides all options merged together.
+
+    @cli.options.assert == {:o0=>true,:o1=>true,:o2=>true}
+
+Switches method is an alias for options.
+
+    @cli.switches.assert == {:o0=>true,:o1=>true,:o2=>true}
+
+Arguments provides all concated together.
+
+    @cli.arguments.assert == ["a", "b", "c"]
+
+Parameters method provides arguments and options.
+
+    @cli.parameters.assert == ["a", "b", "c", {:o0=>true,:o1=>true,:o2=>true}]
+
+Zeroth signature is correct.
+
+    @cli[0].command.assert == 'c0'
+    @cli[0].options.assert == {:o0=>true}
+    @cli[0].arguments.assert == []
+    @cli[0].parameters.assert == [{:o0=>true}]
+    @cli[0].signature.assert == ["c0", [], {:o0=>true}]
+    @cli[0].to_a.assert == ["c0", [], {:o0=>true}]
+
+First signature is correct.
+
+    @cli[1].to_a.assert == ["c1", [], {:o1=>true}]
+
+Second signature is correct.
+
+    @cli[2].to_a.assert == ["c2", ["a", "b", "c"], {:o2=>true}]
+
+There are no more signatures after the second.
+
+    @cli[3].assert == nil
+
+QED.