gli 1.2.1 → 1.2.2

data/CHANGELOG.rdoc

@@ -1,4 +1,8 @@
 == Changelog
+=== 1.2.2 - 12/11/2010
+
+* Changed uses of <code>map(&:symbol)</code> to older form, since this doesn't work on 100% of Ruby 1.8.7s.
+
 === 1.2.1 - 11/26/2010
 
 * Changed default data structure of options *back* to a <tt>Hash</tt>.  If you want to use the <tt>OpenStruct</tt> subclass <tt>Options</tt>, simply put <tt>use_openstruct true</tt> in your command line definition.

data/README.rdoc

@@ -35,269 +35,16 @@ Known to work on
 * 1.8.7
 * 1.9.2
 
-Though likely works on various other versions
+Though likely works on various other versions.
 
-=== Example
+== Documentation
 
-This example demonstrates most of the features of GLI.
-
-The following sets you up to use the DSL that GLI defines:
-
-    #!/usr/bin/ruby
-    $: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib') 
-
-    require 'gli'
-    require 'gli_version'
-
-    include GLI
-
-The following sets the version of your application for exposure in the default <tt>help</tt> subcommand (the VERSION constant was created by the scaffolding):
-
-    version GLI::VERSION
-
-The following sets a description of your program.  This can be as long as you want.
-
-    program_description 'Support program for bootstrapping GLI-based programs'
-
-The following 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'
-
-The following 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>.  Note that if you gave multiple values for one flag, e.g. <tt>flag [:f,:force]</tt>
-then both <tt>:f</tt> and <tt>:force</tt> would be set to the same value; this lets you use more readable 
-keynames in your code when parsing options, but still provide terse flags to the user.
-
-      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],
-                                 options[: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}[http://davetron5000.github.com/gli] 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).
-
-== Bash Completion
-
-The +help+ command takes an optional switch, +-c+, that will list all the commands (including aliases) in sorted order suitable for use in a bash completion script.  When +-c+ is specified, the argument can be a partial command, and +help+ will only list the commands matching.  Put this in your +.bashrc+:
-
-    complete -F get_myapp_targets myapp
-    function get_myapp_targets() 
-    {
-        if [ -z $2 ] ; then
-            COMPREPLY=(`myapp help -c`)
-        else
-            COMPREPLY=(`myapp help -c $2`)
-        fi
-    }
-
-Now, suppose your app takes the commands +list+, +ls+, +rm+, +add+, and +init+:
-
-    > myapp <TAB>
-    add init list ls rm
-    > myapp l<TAB>
-    list ls
-
-== 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, String or array of symbols/Strings 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, String, or an array of symbols/Strings.  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, String or array of symbols/Strings.  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>)
-[+version+] Indicate the verison of your application/library.  This is used by the default <tt>help</tt> command to allow users to see the version of your application.
-
-== 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
-
-:include:CHANGELOG.rdoc
-
-== Developing
-
-    gem install bundler
-    bundle install
-    rake test
-    rake rcov
-
-GLI currently has 100% test coverage, and I'd like to keep it that way.  If you submit patches, please have a test, that makes it easier for me to know if anything's broken.
+Extensive documentation is {available at the wiki}[https://github.com/davetron5000/gli/wiki]
 
 == Links
 
 * [http://davetron5000.github.com/gli] - RubyDoc
 * [http://www.github.com/davetron5000/gli] - Source on GitHub
+* [http://www.github.com/davetron5000/gli/wiki] - Documentation Wiki
 
+:include:gli.rdoc

data/lib/gli/command_line_token.rb

@@ -35,7 +35,7 @@ module GLI
     # it into the primary name and aliases list
     def parse_names(names)
       # Allow strings; convert to symbols
-      names = [names].flatten.map(&:to_sym)
+      names = [names].flatten.map { |name| name.to_sym } 
       names_hash = Hash.new
       names.each do |n| 
         raise ArgumentError.new("#{n} has spaces; they are not allowed") if n.to_s =~ /\s/

data/lib/gli_version.rb

@@ -1,3 +1,3 @@
 module GLI
-  VERSION = '1.2.1'
+  VERSION = '1.2.2'
 end

data/lib/support/help.rb

@@ -25,7 +25,7 @@ module GLI
           memo << obj[1].aliases
           memo = memo.flatten
         end
-        names.map!(&:to_s)
+        names.map! { |name| name.to_s } 
         if arguments && arguments.size > 0
           names = names.select { |name| name =~ /^#{arguments[0]}/ }
         end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: gli
 version: !ruby/object:Gem::Version 
-  hash: 29
   prerelease: false
   segments: 
   - 1
   - 2
-  - 1
-  version: 1.2.1
+  - 2
+  version: 1.2.2
 platform: ruby
 authors: 
 - David Copeland
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-26 00:00:00 -05:00
+date: 2010-12-11 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -64,7 +63,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -73,7 +71,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"