gli_aziz_light 2.8.1

data/features/todo_legacy.feature

@@ -0,0 +1,128 @@
+Feature: The todo app is backwards compatible with legacy subcommand parsing
+  As a user of GLI
+  My apps with subcommands should support the old, legacy way, by default
+
+  Background:
+    Given I have GLI installed
+      And GLI's libs are in my path
+      And my terminal size is "80x24"
+      And todo_legacy's bin directory is in my path
+
+  Scenario: Help completion mode for subcommands
+    When I successfully run `todo help -c list`
+    Then the output should contain:
+    """
+    contexts
+    tasks
+    """
+
+  Scenario: Help completion mode partial match for subcommands
+    When I successfully run `todo help -c list con`
+    Then the output should contain:
+    """
+    contexts
+    """
+
+  Scenario Outline: Getting Help for a top level command of todo
+    When I successfully run `todo <help_invocation>`
+    Then the output should contain:
+    """
+    NAME
+        list - List things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] list [command options] [--flag arg] [-x arg] [tasks]
+        todo [global options] list [command options] [--otherflag arg] [-b] [-f|--foobar] contexts
+
+    DESCRIPTION
+        List a whole lot of things that you might be keeping track of in your
+        overall todo list.
+
+        This is your go-to place or finding all of the things that you might have
+        stored in your todo databases. 
+
+    COMMAND OPTIONS
+        -l, --[no-]long - Show long form
+
+    COMMANDS
+        contexts - List contexts
+        tasks    - List tasks (default)
+    """
+
+    Examples:
+      | help_invocation |
+      | help list       |
+      | list -h         |
+      | list --help     |
+
+
+  Scenario: Getting Help for a sub command of todo list
+    When I successfully run `todo help list tasks`
+    Then the output should contain:
+    """
+    NAME
+        tasks - List tasks
+
+    SYNOPSIS
+        todo [global options] list tasks [command options] 
+        todo [global options] list tasks [command options]  open
+
+    DESCRIPTION
+        Lists all of your tasks that you have, in varying orders, and all that
+        stuff. Yes, this is long, but I need a long description. 
+
+    COMMAND OPTIONS
+        --flag=arg - (default: none)
+        -x arg     - blah blah crud x whatever (default: none)
+    
+    COMMANDS
+        <default> - list all tasks
+        open      - list open tasks
+    """
+
+  Scenario: Getting Help for a sub command with no command options
+    When I successfully run `todo help new`
+    Then the output should contain:
+    """
+    NAME
+        create - Create a new task or context
+
+    SYNOPSIS
+        todo [global options] create 
+        todo [global options] create  contexts [context_name]
+        todo [global options] create  tasks task_name[, task_name]*
+
+    COMMANDS
+        <default> - Makes a new task
+        contexts  - Make a new context
+        tasks     - Make a new task
+    """
+    And the output should not contain "COMMAND OPTIONS"
+
+  Scenario: Running ls w/out subcommand shows help and an error
+    When I run `todo ls`
+    Then the exit status should not be 0
+    And the stderr should contain "error: Command 'ls' requires a subcommand"
+    And the stdout should contain:
+    """
+    NAME
+        ls - LS things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] ls [command options] [-b] [-f|--foobar] contexts
+        todo [global options] ls [command options] [-x arg] tasks
+
+    DESCRIPTION
+        List a whole lot of things that you might be keeping track of in your
+        overall todo list.
+
+        This is your go-to place or finding all of the things that you might have
+        stored in your todo databases. 
+
+    COMMAND OPTIONS
+        -l, --[no-]long - Show long form
+
+    COMMANDS
+        contexts - List contexts
+        tasks    - List tasks
+    """

data/gli.cheat

@@ -0,0 +1,95 @@
+gli - create command-suite apps, a la git, using this awesome Ruby DSL
+======================================================================
+
+Setup and Usage
+---------------
+
+Installation:
+$ gem install gli
+
+Show list of commands
+$ gli help [command]
+
+Show help for one command
+$ gli help init
+
+Create a new GLI-based project with the commands foo and bar
+$ gli init project_name foo bar
+
+Create a new GLI-based project with an ext directory
+$ gli init -e project_name foo bar
+
+Create a new GLI-based project without a test directory (bad!)
+$ gli init --notest project_name foo bar
+
+Create a new GLI-based project somewhere else than .
+$ gli -r /tmp init project_name foo bar
+
+Just see what GLI would create
+$ gli -n init -e project_name foo bar
+
+
+Using GLI's DSL
+---------------
+
+Create a switch (option that takes no args)
+
+  desc 'Dry-run; don't change the disk
+  switch [:n,'dry-run']
+  # Both -n and --dry-run will work
+  * --no-dry-run will set the switch to false
+  # Access in code via global_options[:n]
+  # or global_options[:'dry-run']
+
+Create it on one line
+  switch :n,'dry-run', :desc => 'Dry-run; don't change the disk
+
+Don't create a negatable version
+  switch :n,'dry-run', :negatable => false, :desc => 'Dry-run; don't change the disk
+  # --no-dry-run is not accepted 
+
+Create a flag (option that takes an argument)
+
+  desc 'Location of the config file'
+  arg_name 'path_to_file'
+  default_value '~/.glirc'
+  flag [:c,:conf], :must_match => /^\..*rc$/
+  # Both -c and --conf work, if this flag is omitted
+  # then the default of ~/.glirc is avaialble to the code
+  # The argument must match the given regex
+  # Access in code via global_options[:c] (or :conf)
+
+Create a flag in a more compact style
+
+  flag :c,:conf, :desc => 'Location of the config file', 
+                 :arg_name => 'path_to_file', :default_value =>  '~/.glirc'
+
+Create a command
+
+  desc 'Get the list of open tickets'
+  command [:tickets] do |c|
+    c.desc 'Only assigned to me'
+    c.switch [:m,:me]
+
+    c.desc 'Show only tickets for one project'
+    c.flag [:p,:project,'only-project']
+
+    c.action do |global_options,options,args|
+      # global_options has the global options as a hash
+      # options are the command specific ones (e.g. options[:p])
+      # args are the command line arguments that weren't parsed
+      # raise an exception or exit_now! if things go wrong
+    end
+  end
+
+Set up stuff ahead of time
+
+  pre do |global_options,command,options,args|
+    return true if things_are_ok
+    return false if we_should_abort_the_command
+  end
+
+Use GLI
+
+  exit run(ARGV)
+  # run returns a suitable exit status

data/gli.gemspec

@@ -0,0 +1,34 @@
+# Make sure we get the gli that's local
+require File.join([File.dirname(__FILE__),'lib','gli','version.rb'])
+
+spec = Gem::Specification.new do |s| 
+  s.name = 'gli_aziz_light'
+  s.version = GLI::VERSION
+  s.authors = ['David Copeland', 'Aziz Light']
+  s.email = 'davidcopeland@naildrivin5.com'
+  s.homepage = 'http://davetron5000.github.com/gli'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'Build command-suite CLI apps that are awesome.'
+  s.description = 'Build command-suite CLI apps that are awesome.  Bootstrap your app, add commands, options and documentation while maintaining a well-tested idiomatic command-line app'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   =  'gli'
+  s.require_paths = ["lib"]
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README.rdoc', 'gli.rdoc']
+  s.rdoc_options << '--title' << 'Git Like Interface' << '--main' << 'README.rdoc'
+  s.bindir = 'bin'
+  s.rubyforge_project = 'gli'
+  s.add_development_dependency('rake', '~> 0.9.2.2')
+  s.add_development_dependency('rdoc', '~> 3.11')
+  s.add_development_dependency('rainbow', '~> 1.1.1')
+  s.add_development_dependency('clean_test')
+  s.add_development_dependency('cucumber', '1.2.3')
+  s.add_development_dependency('gherkin', '<= 2.11.6')
+  s.add_development_dependency('aruba', '0.5.1') # 0.5.3 randomly breaks with "LaunchError: no such file or directory" and only sometimes.
+  s.add_development_dependency('sdoc')
+  s.add_development_dependency('faker','1.0.0')
+end
+

data/gli.rdoc

@@ -0,0 +1,73 @@
+== gli - create scaffolding for a GLI-powered application
+
+v2.2.1
+
+=== Global Options
+=== -r|--root arg
+
+Root dir of project
+
+[Default Value] .
+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'
+
+=== --help
+Show this message
+
+
+
+=== -n
+Dry run; dont change the disk
+
+
+
+=== -v
+Be verbose
+
+
+
+=== --version
+
+
+
+
+=== Commands
+==== Command: <tt>help  command</tt>
+Shows a list of commands or help for one command
+
+Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
+===== Options
+===== -c
+List commands one per line, to assist with shell completion
+
+
+
+==== Command: <tt>init|scaffold  project_name [command[ command]*]</tt>
+Create a new GLI-based project
+
+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
+===== -e|--[no-]ext
+Create an ext dir
+
+
+
+===== --[no-]force
+Overwrite/ignore existing files and directories
+
+
+
+===== --notest
+Do not create a test or features dir
+
+
+
+===== --[no-]rvmrc
+Create an .rvmrc based on your current RVM setup
+
+
+

data/lib/gli.rb

@@ -0,0 +1,35 @@
+require 'gli/command_finder.rb'
+require 'gli/gli_option_block_parser.rb'
+require 'gli/option_parser_factory.rb'
+require 'gli/option_parsing_result.rb'
+require 'gli/gli_option_parser.rb'
+require 'gli/app_support.rb'
+require 'gli/app.rb'
+require 'gli/command_support.rb'
+require 'gli/command.rb'
+require 'gli/command_line_token.rb'
+require 'gli/command_line_option.rb'
+require 'gli/exceptions.rb'
+require 'gli/flag.rb'
+require 'gli/options.rb'
+require 'gli/switch.rb'
+require 'gli/dsl.rb'
+require 'gli/version.rb'
+require 'gli/commands/help'
+require 'gli/commands/compound_command'
+require 'gli/commands/initconfig'
+require 'gli/commands/rdoc_document_listener'
+require 'gli/commands/doc'
+
+module GLI
+  include GLI::App
+  def self.included(klass)
+    warn "You should include GLI::App instead"
+  end
+
+  def self.run(*args)
+    warn "GLI.run no longer works for GLI-2, you must just call `run(ARGV)' instead"
+    warn "either fix your app, or use the latest GLI in the 1.x family"
+    1
+  end
+end

data/lib/gli/app.rb

@@ -0,0 +1,286 @@
+require 'etc'
+require 'optparse'
+require 'gli/dsl'
+require 'pathname'
+
+module GLI
+  # A means to define and parse a command line interface that works as
+  # Git's does, in that you specify global options, a command name, command
+  # specific options, and then command arguments.
+  module App
+    include DSL
+    include AppSupport
+
+    # Loads ruby files in the load path that start with
+    # +path+, which are presumed to be commands for your executable.
+    # This is useful for decomposing your bin file into different classes, but
+    # can also be used as a plugin mechanism, allowing users to provide additional
+    # commands for your app at runtime.  All that being said, it's basically
+    # a glorified +require+.
+    #
+    # path:: a path from which to load <code>.rb</code> files that, presumably, contain commands.  If this is an absolute path,
+    #        any files in that path are loaded.  If not, it is interpretted as relative to somewhere
+    #        in the <code>LOAD_PATH</code>.
+    #
+    # == Example:
+    #
+    #     # loads *.rb from your app's install - great for decomposing your bin file
+    #     commands_from "my_app/commands"
+    #
+    #     # loads *.rb files from the user's home dir - great and an extension/plugin mechanism
+    #     commands_from File.join(ENV["HOME"],".my_app","plugins")
+    def commands_from(path)
+      if Pathname.new(path).absolute? and File.exists?(path)
+        load_commands(path)
+      else
+        $LOAD_PATH.each do |load_path|
+          commands_path = File.join(load_path,path)
+          load_commands(commands_path)
+        end
+      end
+    end
+
+    # Describe the overall application/programm.  This should be a one-sentence summary
+    # of what your program does that will appear in the help output.
+    #
+    # +description+:: A String of the short description of your program's purpose
+    def program_desc(description=nil)
+      if description
+        @program_desc = description
+      end
+      @program_desc
+    end
+
+    # Provide a longer description of the program.  This can be as long as needed, and use double-newlines
+    # for paragraphs.  This will show up in the help output.
+    #
+    # description:: A String for the description
+    def program_long_desc(description=nil)
+      if description
+        @program_long_desc = description
+      end
+      @program_long_desc
+    end
+
+    # Use this if the following command should not have the pre block executed.
+    # By default, the pre block is executed before each command and can result in
+    # aborting the call.  Using this will avoid that behavior for the following command
+    def skips_pre
+      @skips_pre = true
+    end
+
+    # Use this if the following command should not have the post block executed.
+    # By default, the post block is executed after each command.
+    # Using this will avoid that behavior for the following command
+    def skips_post
+      @skips_post = true
+    end
+
+    # Use this if the following command should not have the around block executed.
+    # By default, the around block is executed, but for commands that might not want the
+    # setup to happen, this can be handy
+    def skips_around
+      @skips_around = true
+    end
+
+    # Sets that this app uses a config file as well as the name of the config file.  
+    #
+    # +filename+:: A String representing the path to the file to use for the config file.  If it's an absolute
+    #              path, this is treated as the path to the file.  If it's *not*, it's treated as relative to the user's home
+    #              directory as produced by <code>File.expand_path('~')</code>.
+    def config_file(filename)
+      if filename =~ /^\//
+        @config_file = filename
+      else
+        @config_file = File.join(File.expand_path(ENV['HOME']),filename)
+      end
+      commands[:initconfig] = InitConfig.new(@config_file,commands,flags,switches)
+      @commands_declaration_order << commands[:initconfig]
+      @config_file
+    end
+
+    # Define a block to run after command line arguments are parsed
+    # but before any command is run.  If this block raises an exception
+    # the command specified will not be executed.
+    # The block will receive the global-options,command,options, and arguments
+    # If this block evaluates to true, the program will proceed; otherwise
+    # the program will end immediately and exit nonzero
+    def pre(&a_proc)
+      @pre_block = a_proc
+    end
+
+    # Define a block to run after the command was executed, <b>only
+    # if there was not an error</b>.
+    # The block will receive the global-options,command,options, and arguments
+    def post(&a_proc)
+      @post_block = a_proc
+    end
+
+    # This inverts the pre/post concept.  This is useful when you have a global shared resource that is governed by a block
+    # instead of separate open/close methods.  The block you pass here will be given four parameters:
+    #
+    # global options:: the parsed global options
+    # command:: The GLI::Command that the user is going to invoke
+    # options:: the command specific options
+    # args:: unparsed command-line args
+    # code:: a block that you must +call+ to execute the command.
+    #
+    # #help_now! and #exit_now! work as expected; you can abort the command call by simply not calling it.
+    #
+    # You can declare as many #around blocks as you want.  They will be called in the order in which they are defined.
+    #
+    # Note that if you declare #around blocks, #pre and #post blocks will still work.  The #pre is called first, followed by
+    # the around, followed by the #post.
+    #
+    # Call #skips_around before a command that should not have this hook fired
+    def around(&a_proc)
+      @around_blocks ||= []
+      @around_blocks << a_proc
+    end
+
+    # Define a block to run if an error occurs.
+    # The block will receive any Exception that was caught.
+    # It should evaluate to false to avoid the built-in error handling (which basically just
+    # prints out a message). GLI uses a variety of exceptions that you can use to find out what 
+    # errors might've occurred during command-line parsing:
+    # * GLI::CustomExit
+    # * GLI::UnknownCommandArgument
+    # * GLI::UnknownGlobalArgument
+    # * GLI::UnknownCommand
+    # * GLI::BadCommandLine
+    def on_error(&a_proc)
+      @error_block = a_proc
+    end
+
+    # Indicate the version of your application
+    #
+    # +version+:: String containing the version of your application.  
+    def version(version)
+      @version = version
+      desc 'Display the program version'
+      switch :version, :negatable => false
+    end
+
+    # By default, GLI mutates the argument passed to it.  This is
+    # consistent with +OptionParser+, but be less than ideal.  Since
+    # that value, for scaffolded apps, is +ARGV+, you might want to
+    # refer to the entire command-line via +ARGV+ and thus not want it mutated.
+    def preserve_argv(preserve=true)
+      @preserve_argv = preserve
+    end
+
+    # Call this with +true+ will cause the +global_options+ and
+    # +options+ passed to your code to be wrapped in
+    # Options, which is a subclass of +OpenStruct+ that adds
+    # <tt>[]</tt> and <tt>[]=</tt> methods.
+    #
+    # +use_openstruct+:: a Boolean indicating if we should use OpenStruct instead of Hashes
+    def use_openstruct(use_openstruct)
+      @use_openstruct = use_openstruct
+    end
+
+    # Configure a type conversion not already provided by the underlying OptionParser.
+    # This works more or less like the OptionParser version.
+    #
+    # object:: the class (or whatever) that triggers the type conversion
+    # block:: the block that will be given the string argument and is expected
+    #         to return the converted value
+    #
+    # Example
+    #
+    #     accept(Hash) do |value|
+    #       result = {}
+    #       value.split(/,/) do |pair|
+    #         k,v = pair.split(/:/)
+    #         result[k] = v
+    #       end
+    #       result
+    #     end
+    #
+    #     flag :properties, :type => Hash
+    def accept(object,&block)
+      accepts[object] = block
+    end
+
+    # Simpler means of exiting with a custom exit code.  This will 
+    # raise a CustomExit with the given message and exit code, which will ultimatley
+    # cause your application to exit with the given exit_code as its exit status
+    # Use #help_now! if you want to show the help in addition to the error message
+    #
+    # message:: message to show the user
+    # exit_code:: exit code to exit as, defaults to 1
+    def exit_now!(message,exit_code=1)
+      raise CustomExit.new(message,exit_code)
+    end
+
+    # Exit now, showing the user help for the command they executed.  Use #exit_now! to just show the error message
+    #
+    # message:: message to indicate how the user has messed up the CLI invocation or nil to just simply show help
+    def help_now!(message=nil)
+      exception = OptionParser::ParseError.new(message)
+      class << exception
+        def exit_code; 64; end
+      end
+      raise exception
+    end
+
+    # Control how commands and options are sorted in help output.  By default, they are sorted alphabetically.
+    #
+    # sort_type:: How you want help commands/options sorted:
+    #             +:manually+:: help commands/options are ordered in the order declared.
+    #             +:alpha+:: sort alphabetically (default)
+    def sort_help(sort_type)
+      @help_sort_type = sort_type
+    end
+
+    # Set how help text is wrapped.
+    #
+    # wrap_type:: Symbol indicating how you'd like text wrapped:
+    #             +:to_terminal+:: Wrap text based on the width of the terminal (default)
+    #             +:verbatim+:: Format text exactly as it was given to the various methods.  This is useful if your output has
+    #                           formatted output, e.g. ascii tables and you don't want it messed with.
+    #             +:one_line+:: Do not wrap text at all.  This will bring all help content onto one line, removing any newlines
+    #             +:tty_only+:: Wrap like +:to_terminal+ if this output is going to a TTY, otherwise don't wrap (like +:one_line+)
+    def wrap_help_text(wrap_type)
+      @help_text_wrap_type = wrap_type
+    end
+
+    def program_name(override=nil) #:nodoc:
+      warn "#program_name has been deprecated"
+    end
+
+    # Sets a default command to run when none is specified on the command line.  Note that
+    # if you use this, you won't be able to pass arguments, flags, or switches
+    # to the command when run in default mode.  All flags and switches are treated
+    # as global, and any argument will be interpretted as the command name and likely
+    # fail.
+    #
+    # +command+:: Command as a Symbol to run as default
+    def default_command(command)
+      @default_command = command.to_sym
+    end
+
+    # How to handle subcommand options.  In general, you want to set this to +:normal+, which
+    # treats each subcommand as establishing its own namespace for options.  This is what
+    # the scaffolding should generate, but it is *not* what GLI 2.5.x and lower apps had as a default.
+    # To maintain backwards compatibility, the default is +:legacy+, which is that all subcommands of
+    # a particular command share a namespace for options, making it impossible for two subcommands
+    # to have options of the same name.
+    def subcommand_option_handling(handling_strategy)
+      @subcommand_option_handling_strategy = handling_strategy
+    end
+
+    private
+
+    def load_commands(path)
+      if File.exists? path
+        Dir.entries(path).sort.each do |entry|
+          file = File.join(path,entry)
+          if file =~ /\.rb$/
+            require file
+          end
+        end
+      end
+    end
+  end
+end