Git-Like Interface Command Line Parser
- Author
-
Dave Copeland (davetron5000 at g mail dot com)
- Copyright
-
Copyright © 2009 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 (very) basic scaffold project in ./my_proj
, with a bare-bones main file in ./my_proj/bin/my_proj
. This file demonstrates most of what you need to describe your command line interface
More Detail
This sets you up to use the DSL that GLI defines:
#!/usr/bin/ruby
$: << File.(File.dirname(__FILE__) + '/../lib')
require 'gli'
include GLI
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
This describes a command line flag that is global and has a default value of ‘.
’. It also specifies a short description of its argument. This is used to print command line help. Note that we have specified two different aliases for this flag. -r
(because it is listed first) is the default one and --root
(note two-dash syntax) is also supported. This means that -r some_dir
and --root=some_dir
mean the same thing to the application.
desc 'Root dir in which to create project'
default_value '.'
arg_name 'root_dir'
flag [:r,:root]
Here 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 arg_name
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]
Here we specify the actual actions to take when the command is executed. 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
c.action do |global_options,options,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
You can also specify some global code to run before, after and on errors:
pre do |,command,,args|
puts "After parsing, but before #{command.name} is run"
return true
# return false if we want to skip command execution for some reason
end
post do |,command,,args|
puts "After successful execution of #{command.name}"
end
on_error do |,command,,args|
puts "We go 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)
What this gives you:
-
A reasonably useful help system.
your_program help
will list all the global options and commands (along with command aliases) andyour_program help command_name
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)
What this doesn’t give you:
-
A way to indicate required flags
-
A way to indicate a require argument or required number of arguments
-
A way to do default switches to ‘true’ and therefore accept things like
--no-force
Interface Generated
executable global options and flags command command specific options and flags ‘arguments`
- switch
-
a command line control string that takes no argument. The
-l
inls -l
- flag
-
a switch that takes an argument. The
-d' '
incut -d' ' file
- command
-
the command to execute. The
rebase
ingit rebase
- arguments
-
Anything that’s not a switch, flag, or command. The
main.c
ingit add main.c
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 --
at any time stops processing and sends the rest of the argument to the command as arguments, even if they start with a “–”
Links
- davetron5000.github.com/gli
-
RubyDoc
-
- www.github.com/davetron5000/gli
-
Source on GitHub
-