bbcloud 0.8 → 0.8.1

data/lib/bbcloud/vendor/gli-1.1.2/README.rdoc

@@ -0,0 +1,260 @@
+= Git-Like Interface Command Line Parser
+
+Author::  Dave Copeland (mailto:davetron5000 at g mail dot com)
+Copyright:: Copyright (c) 2010 by Dave Copeland
+License:: Distributes under the Apache License, see LICENSE.txt in the source distro
+
+This is a DSL you can use to create a command line interface like git, gem or svn, in that the first argument is a command, and there are global and command specific flags.
+
+== Use
+
+Install if you need to:
+
+    sudo gem install gli
+
+The simplest way to get started is to create a scaffold project
+
+    gli init my_proj command_name other_command_name
+
+This will create a basic scaffold project in <tt>./my_proj</tt> with:
+
+* executable in <tt>./my_proj/bin/my_proj</tt>.  This file demonstrates most of what you need to describe your command line interface.
+* an empty test in <tt>./my_proj/test/tc_nothing.rb</tt> that can bootstrap your tests
+* a gemspec shell
+* a README shell
+* Rakefile that can generate RDoc, package your Gem and run tests
+
+== Supported Platforms
+
+Known to work on
+
+* 1.8.7
+* 1.9.2
+
+Though likely works on various other versions
+
+=== Example
+
+This example demonstrates most of the features of GLI.
+
+This sets you up to use the DSL that GLI defines:
+
+    #!/usr/bin/ruby
+    $: << File.expand_path(File.dirname(__FILE__) + '/../lib') 
+
+    require 'gli'
+
+    include GLI
+
+This sets a description of your program.  This can be as long as you want.
+
+    program_description 'Support program for bootstrapping GLI-based programs'
+
+This sets a config file for your program.  The config file can be used to store default values for command
+line options and command-specific options on a per-user (or per-site) basis.  The format is YAML-based.  
+Using an absolute path will result in the configuraiton file being located there.  Without an absolute path,
+the file will be located relative to the current user's home directory (which is what is being done here).
+
+    config_file '.glirc'
+
+This describes a command line switch "-n" that is global to all commands and specified before
+the command name on the command line.
+
+    desc 'Dry run; don\'t change the disk'
+    switch :n
+
+The following describes a command line flag that is global and has a default value of '<tt>.</tt>' (in GLI parlance,
+a "flag" is a command line switch that takes an option).  It also
+specifies a short and long description of its argument.  This is used to print command line help and to generate
+rdoc documentation.  Note that we
+have specified two different aliases for this flag.  <tt>-r</tt> (because it is listed first) is the default
+one and <tt>--root</tt> (note two-dash syntax) is also supported.  This means that <tt>-r some_dir</tt> and <tt>--root=some_dir</tt> mean
+the same thing to the application, but that your code should look for <tt>:r</tt>.
+
+    desc 'Root dir in which to create project'
+    long_desc 'This is the location where your project ill be created.  A subdirectory named for your project will be created here, and THAT directory will contain the generated files'
+    default_value '.'
+    arg_name 'root_dir'
+    flag [:r,:root]
+
+Next, we specify a command.  Inside the block we can use the same sorts of things as we did above to define flags
+and switches specific to the command.  These must come after the command name.  Also note that we use <tt>arg_name</tt>
+here to describe the arguments this command accepts.
+
+    desc 'Create a new GLI-based project'
+    arg_name 'project_name [command[ command]*]'
+    command [:init,:scaffold] do |c|
+
+      c.desc 'Create an ext dir'
+      c.switch [:e,:ext]
+
+      c.desc 'Overwrite/ignore existing files and directories'
+      c.switch [:force]
+
+Next, while we are still inside the <tt>command</tt> block,
+we specify the actual code to execute when the command is chosen by the user.  We define a block that
+will be given the global options (as a Hash), the command-specific options (as a Hash) and the command
+line arguments.  The hashes keys are symbols based upon the switches and flags.  For a switch or
+flag named "-r", we would use <tt>:r</tt>.
+
+      c.action do |global_options,options,args|
+        if args.length < 1
+          raise 'You must specify the name of your project'
+        end
+        Scaffold.create_scaffold(global_options[:r],
+                                 !options[:notest],
+                                 options[:e],
+                                 args[0],
+                                 args[1..-1],
+                                 ooptions[:force],
+                                 global_options[:n])
+      end
+    end
+
+You can also specify some global code to run before, after and on errors:
+
+    pre do |global_options,command,options,args|
+      puts "After parsing, but before #{command.name} is run"
+      return true
+      # return false if we want to skip command execution for some reason,
+      # such as some global precondition not having been met
+    end
+
+    post do |global_options,command,options,args|
+      puts "After successful execution of #{command.name}"
+    end
+
+    on_error do |ex|
+      puts "We got an error"
+      return true    # does the standard error handling code
+      # return false # this would skip standard error handling code
+    end
+
+Now, we run the program using the arguments the user provided on the command line
+
+    run(ARGV)
+
+Note that by using <tt>gli init</tt> you can create a shell with all of this already there for you.
+
+What this gives you:
+
+* A reasonably useful help system.  <tt>your_program help</tt> will list all the global options and commands (along with command aliases) and <tt>your_program help command_name</tt> will list help for that given command.
+* Error handling when flags do not receive arguments or unknown flags or switches are given
+* Error handling when an unknown command is specified
+* Default values for flags if they are not specified by the user (switches all default to false)
+* An easy way to allow user or site-specific defaults for options via a config file for your app
+* Nice RDoc describing how to use your application (you can see an example in the rdoc version of this file for the <tt>gli</tt> command)
+
+What this doesn't give you:
+
+* A way to indicate required flags
+* A way to indicate a required argument or required number of arguments
+* A way to do default switches to 'true' and therefore accept things like <tt>--no-force</tt>
+* A way to have repeated flags turn into an array or other type-transforming things
+
+== Configuration File
+
+The configuration file format is a very simple means of customizing the execution of your command on a per-user
+or per-site basis.  The idea is that commonly used values that aren't the commands' default can be stored in the configuration
+file so that users do not need to specify them on the command line.  The search order for the value of a particular
+flag then becomes:
+
+1. Command line invocation
+2. Configuration File value
+3. Default value in the application
+
+Note that since there is no way to switch _off_ switches, setting them to default to true in the configuration file
+cannot be "undone" on the command line.  A future version may allow this.
+
+The configuration file format is YAML based and can be bootstrapped via the +initconfig+ command to your application.  
+This command is automatically created and added to your application's commands when you declare that there is a 
+config file.  When invoked, all global options set on the command line are configured 
+inside the configuration file.  Further, a blank area for each
+command of your application is created, to allow the user edit the config file  ith command-specific default values.
+
+    --- 
+    # Global options are here
+    :f: foo
+    :g: blah
+    # Command-specific options are under 'commands'
+    commands: 
+      # defaults for the "doit" command
+      :doit: 
+        :g: bar
+        :s: true
+      # defaults for the "gonow" command
+      :gonow: 
+        :g: foobar
+        :f: barfoo
+
+This allows you to design your application to have it's behavior _entirely_ affected by command line options, with sensible
+defaults stored in a configuration file.
+
+== Generating RDoc
+
+All gli-based applications include a "hidden" command named <tt>rdoc</tt>.  When you execute this command, a file called <tt>yourapp.rdoc</tt>
+is created in the current directory.  This contains a rdoc-formatted helpfile for your command line application.  This can be useful
+in packaging your application to share with others. This is also the only place in which the <tt>long_desc</tt> values are currently
+used.
+
+If your application has a <tt>README.rdoc</tt> already, you can simply add <tt>:include:yourapp.rdoc</tt> to the bottom and it will
+be included when you generate and publish your rdoc (note that it will *not* show up on github).
+
+== Reference
+
+
+[+action+] Specify the action to take when a command is executed from the command line.  This is only usable in a command block on the command object (e.g. <tt>c.action</tt>).  This takes a block that yields three parameters: a hash of global options specified on the commandline, a hash of command-specific options specified on the command line, and an array of arguments parsed after the options were set on the command line.  So, a command like <tt>git --git-dir=/tmp commit -a -m 'Foo bar' foo.c bar.c</tt> would result in the global hash containing <tt>:'git-dir' => '/tmp'</tt>, the options hash containing <tt>:a => true, :m => 'Foo bar'</tt> and the arguments array being <tt>['foo.c', 'bar.c']</tt>
+[+arg_name+] Describe the name of the argument to the next flag or command.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.arg_name</tt>)
+[+config_file+] Name the configuration file for your applicaiton.  This can either be an absolute path to where the applicaiton will find the configuration file, or a relative path, that will be interpretted as relative to the user's home directory.  Default is +nil+, which means no configuration file will be used.  Declaring this creates a special +initconfig+ command that can bootstrap this configuration file for your users.
+[+command+] Declare a command.  This takes a symbol or array of symbols and a block.  The block yields one argument, the command itself.  
+[+default_value+] Indicate the default value of the next flag.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.default_value</tt>)
+[+desc+] Describe the next flag, switch, or command you will declare.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.desc</tt>)
+[+flag+] Declare a flag, which is a command line switch that takes an argument.  This takes either a symbol or an array of symbols.  The first symbol decared is used in your program to determine the flag's value at runtime.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.flag</tt>)
+[+long_desc+] Provide a more lengthy description of the next flag, switch, or command you will declare.  This will appear in command line output for commands when you get help for a command.  For flags and switches, this will only appear in the generated rdoc and *not* on the command line.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.long_desc</tt>)
+[+on_error+] Declare an error handling routine that will be called if any command (or other GLI processing) encouters an exception.  This is a block that will receive the exception that was caught.  All exceptions are routed through this block. If the block evaluates to true, the built-in error handling will be called after, otherwise, nothing will happen.
+[+post+] Declare code to run after every command that didn't experience an error.  This is not available inside a command block.  This takes a block that will receive four arguments: the global argument hash (as in <tt>action</tt>), the command (instance of Command), the command-specific options (as in <tt>action</tt>, and the parsed command line arguments (as in <tt>action</tt>).  
+[+pre+] Declare code to run before every command.  This is not available inside a command block.  This takes a block that will receive four arguments: the global argument hash (as in <tt>action</tt>), the command (instance of Command), the command-specific options (as in <tt>action</tt>, and the parsed command line arguments (as in <tt>action</tt>).  If this block evaluates to false, the command will not be executed and the program will stop.
+[+switch+] Declare a switch, which is a command-line switch taking no argument that indicates a boolean "true" when specified on the command line.  This takes either a symbol or array of symbols.  The first symbol declared is used in your program to determine if the switch was set.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.switch</tt>)
+
+== Interface Generated
+
+The command line interface that is created with the GLI DSL is:
+
+*executable* <i>global options and flags</i> *command* <i>command specific options and flags</i> `arguments`
+
+[switch]    a command line control string that takes no argument.  The <tt>-l</tt> in <tt>ls -l</tt>
+[flag]      a switch that takes an argument.  The <tt>-d' '</tt> in <tt>cut -d' ' file</tt>
+[command]   the command to execute.  The <tt>rebase</tt> in <tt>git rebase</tt>
+[arguments] Anything that's not a switch, flag, or command.  The <tt>main.c</tt> in <tt>git add main.c</tt>
+
+=== Switches
+
+Switches can be specified one at a time in either a long or short format:
+
+    git add -i
+    git add --interactive
+
+Switches can also be combined in their short form:
+
+    ls -l -a    
+    ls -la
+
+=== Flags
+
+Flags can be specified in long or short form, and with or without an equals:
+
+    git merge -s resolve
+    git merge --strategy=resolve
+
+=== Stop Switch
+
+A <tt>--</tt> at any time stops processing and sends the rest of the argument to the command as arguments, even if
+they start with a "--"
+
+:include:gli.rdoc
+
+== Links
+
+* [http://davetron5000.github.com/gli] - RubyDoc
+* [http://www.github.com/davetron5000/gli] - Source on GitHub
+

data/lib/bbcloud/vendor/gli-1.1.2/bin/gli

@@ -0,0 +1,64 @@
+#!/usr/bin/ruby
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib') 
+
+require 'gli'
+require 'support/scaffold'
+
+include GLI
+
+desc 'Be verbose'
+switch :v
+
+desc 'Show version'
+switch :version
+
+desc 'Dry run; don''t change the disk'
+switch :n
+
+desc 'Root dir of project'
+long_desc 'This is the directory where the project''s directory will be made, so if you specify a project name ''foo'' and the root dir of ''.'', the directory ''./foo'' will be created'
+default_value '.'
+flag [:r,:root]
+
+desc 'Create a new GLI-based project'
+long_desc <<EOS
+This will create a scaffold command line project that uses GLI
+for command line processing.  Specifically, this will create
+an executable ready to go, as well as a lib and test directory, all
+inside the directory named for your project
+EOS
+arg_name 'project_name [command[ command]*]'
+command [:init,:scaffold] do |c|
+
+  c.desc 'Create an ext dir'
+  c.switch [:e,:ext]
+
+  c.desc 'Do not create a test dir'
+  c.switch [:notest]
+
+  c.desc 'Overwrite/ignore existing files and directories'
+  c.switch [:force]
+
+  c.action do |g,o,args|
+    if args.length < 1
+      raise 'You must specify the name of your project'
+    end
+    Scaffold.create_scaffold(g[:r],!o[:notest],o[:e],args[0],args[1..-1],o[:force],g[:n])
+  end
+end
+
+pre do |global,command,options,args|
+  if (!command || command.name == :help) && global[:version]
+    puts "#{$0} v#{GLI::VERSION}"
+    false
+  else
+    puts "Executing #{command.name}" if global[:v]
+    true
+  end
+end
+
+post do |global,command,options,args|
+  puts "Executed #{command.name}" if global[:v]
+end
+
+run(ARGV)

data/lib/bbcloud/vendor/gli-1.1.2/gli.rdoc

@@ -0,0 +1,45 @@
+= <tt>gli</tt>
+
+    gli [global options] command_name [command-specific options] [--] arguments...
+
+* Use the command +help+ to get a summary of commands
+* Use the command <tt>help command_name</tt> to get a help for +command_name+
+* Use <tt>--</tt> to stop command line argument processing; useful if your arguments have dashes in them
+
+== Global Options
+These options are available for any command and are specified before the name of the command
+
+[<tt>-n</tt>] Dry run; dont change the disk
+[<tt>-r, --root=arg</tt>] Root dir of project <i>( default: <tt>.</tt>)</i>
+
+                          This is the directory where the projects directory will be made, so if you specify a project name foo and the root dir of ., the directory ./foo will be created
+
+[<tt>-v</tt>] Be verbose
+[<tt>--version</tt>] Show version
+== Commands
+[<tt>help</tt>] Shows list of commands or help for one command
+[<tt>init</tt>] Create a new GLI-based project
+
+=== <tt>help [command]</tt>
+
+Shows list of commands or help for one command
+
+=== <tt>init project_name [command[ command]*]</tt>
+
+Create a new GLI-based project
+
+*Aliases*
+* <tt><b>scaffold</b></tt>
+
+This will create a scaffold command line project that uses GLI
+for command line processing.  Specifically, this will create
+an executable ready to go, as well as a lib and test directory, all
+inside the directory named for your project
+
+
+==== Options
+These options are specified *after* the command.
+
+[<tt>-e, --ext</tt>] Create an ext dir
+[<tt>--force</tt>] Overwrite/ignore existing files and directories
+[<tt>--notest</tt>] Do not create a test dir

data/lib/bbcloud/vendor/gli-1.1.2/lib/gli/command.rb

@@ -0,0 +1,74 @@
+require 'gli/command_line_token.rb'
+
+module GLI
+  # A command to be run, in context of global flags and switches
+  class Command < CommandLineToken
+
+    # Create a new command
+    #
+    # [names] the name or names of this command (symbol or Array of symbols)
+    # [description] description of this command
+    # [arguments_name] description of the arguments, or nil if this command doesn't take arguments
+    # [long_desc] a longer description of the command, possibly with multiple lines and text formatting
+    #
+    def initialize(names,description,arguments_name=nil,long_desc=nil)
+      super(names,description,long_desc)
+      @arguments_description = arguments_name || ''
+      clear_nexts
+    end
+
+    def arguments_description; @arguments_description; end
+
+    def names
+      all_forms
+    end
+
+    def usage
+      usage = name.to_s
+      usage += ' [options]' if !flags.empty? || !switches.empty?
+      usage += ' ' + @arguments_description if @arguments_description
+      usage
+    end
+
+    def flags; @flags ||= {}; end
+    def switches; @switches ||= {}; end
+
+    # describe the next switch or flag
+    def desc(description); @next_desc = description; end
+    # describe the argument name of the next flag
+    def arg_name(name); @next_arg_name = name; end
+    # set the default value of the next flag
+    def default_value(val); @next_default_value = val; end
+
+    def flag(*names)
+      flag = Flag.new([names].flatten,@next_desc,@next_arg_name,@next_default_value)
+      flags[flag.name] = flag
+      clear_nexts
+    end
+
+    # Create a switch
+    def switch(*names)
+      switch = Switch.new([names].flatten,@next_desc)
+      switches[switch.name] = switch
+      clear_nexts
+    end
+
+    def action(&block)
+      @action = block
+    end
+
+    def self.name_as_string(name)
+      name.to_s
+    end
+
+    def clear_nexts
+      @next_desc = nil
+      @next_arg_name = nil
+      @next_default_value = nil
+    end
+
+    def execute(global_options,options,arguments)
+      @action.call(global_options,options,arguments)
+    end
+  end
+end

data/lib/bbcloud/vendor/gli-1.1.2/lib/gli/command_line_token.rb

@@ -0,0 +1,53 @@
+module GLI
+  # Logical element of a command line, mostly so that subclasses can have similar
+  # initialization and interface
+  class CommandLineToken
+    attr_reader :name
+    attr_reader :aliases
+    attr_reader :description
+    attr_reader :long_description
+
+    def initialize(names,description,long_description=nil)
+      @description = description
+      @long_description = long_description
+      @name,@aliases,@names = parse_names(names)
+    end
+
+    def usage
+      all_forms
+    end
+
+    def <=>(other)
+      self.name.to_s <=> other.name.to_s
+    end
+
+    private
+    # Returns a string of all possible forms
+    # of this flag.  Mostly intended for printing
+    # to the user.
+    def all_forms(joiner=', ')
+      forms = all_forms_a
+      forms.join(joiner)
+    end
+
+
+    # Handles dealing with the "names" param, parsing
+    # it into the primary name and aliases list
+    def parse_names(names)
+      names_hash = Hash.new
+      names = names.is_a?(Array) ? names : [names]
+      names.each { |n| names_hash[self.class.name_as_string(n)] = true }
+      name = names.shift
+      aliases = names.length > 0 ? names : nil
+      [name,aliases,names_hash]
+    end
+
+    def all_forms_a
+      forms = [self.class.name_as_string(name)]
+      if aliases
+        forms |= aliases.collect { |a| self.class.name_as_string(a) }.sort { |x,y| y.length <=> x.length }
+      end
+      forms
+    end
+  end
+end

data/lib/bbcloud/vendor/gli-1.1.2/lib/gli/flag.rb

@@ -0,0 +1,66 @@
+require 'gli/command_line_token.rb'
+
+module GLI
+  # Defines a flag, which is to say a switch that takes an argument
+  class Flag < Switch
+
+    attr_reader :default_value
+
+    def initialize(names,description,argument_name=nil,default=nil,long_desc=nil)
+      super(names,description,long_desc)
+      @argument_name = argument_name || "arg"
+      @default_value = default
+    end
+
+    def get_value!(args)
+      args.each_index() do |index|
+        arg = args[index]
+        present,matched,value = find_me(arg)
+        if present
+          args.delete_at index
+          if !value || value == ''
+            if args[index]
+              value = args[index]
+              args.delete_at index
+              return value
+            else
+              raise "#{matched} requires an argument"
+            end
+          else
+            return value
+          end
+        end
+      end
+      return @default_value
+    end
+
+    def find_me(arg)
+      if @names[arg]
+        return [true,arg,nil] if arg.length == 2
+        # This means we matched the long-form, but there's no argument
+        raise "#{arg} requires an argument via #{arg}=argument"
+      end
+      @names.keys.each() do |name|
+        match_string = "^#{name}=(.*)$"
+        match_data = arg.match(match_string)
+        return [true,name,$1] if match_data;
+      end
+      [false,nil,nil]
+    end
+
+    # Returns a string of all possible forms
+    # of this flag.  Mostly intended for printing
+    # to the user.
+    def all_forms(joiner=', ')
+      forms = all_forms_a
+      string = forms.join(joiner)
+      if forms[-1] =~ /^\-\-/
+        string += '='
+      else
+        string += ' '
+      end
+      string += @argument_name
+      return string
+    end
+  end
+end

data/lib/bbcloud/vendor/gli-1.1.2/lib/gli/options.rb

@@ -0,0 +1,14 @@
+require 'ostruct'
+
+class Options < OpenStruct
+
+  def[](k)
+    @table[k.to_sym]
+  end
+
+  def[]=(k, v)
+    @table[k.to_sym] = v
+  end
+
+end
+

data/lib/bbcloud/vendor/gli-1.1.2/lib/gli/switch.rb

@@ -0,0 +1,56 @@
+require 'gli/command_line_token.rb'
+
+module GLI
+  # Defines a command line switch
+  class Switch < CommandLineToken
+
+    def initialize(names,description,long_desc=nil)
+      super(names,description,long_desc)
+    end
+
+    # Given the argument list, scans it looking for this switch
+    # returning true if it's in the argumennt list (and removing it from the argument list)
+    def get_value!(args)
+      idx = -1
+      args.each_index do |i|
+        result = find_me(args[i])
+        if result[0]
+          if result[1]
+            args[i] = result[1]
+          else
+            args.delete_at i
+          end
+          return result[0]
+        end
+      end
+      false
+    end
+
+    # Finds the switch in the given arg, returning the arg to keep.
+    # Returns an array of size 2:
+    # [0] true or false if the arg was found
+    # [1] the remaining arg to keep in the command line or nil to remove it
+    def find_me(arg)
+      if @names[arg]
+        return [true,nil]
+      end
+      @names.keys.each() do |name|
+        if name =~ /^-(\w)$/
+          match_string = "^\\-(\\w*)#{$1}(\\w*)$"
+          match_data = arg.match(match_string)
+          if match_data
+            # Note that if [1] and [2] were both empty 
+            # we'd have returned above
+            return [true, "-" + match_data[1] + match_data[2]]
+          end
+        end
+      end
+      [false]
+    end
+
+    def self.name_as_string(name)
+      string = name.to_s
+      string.length == 1 ? "-#{string}" : "--#{string}"
+    end
+  end
+end