Module: GLI::App
Overview
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.
Instance Method Summary collapse
-
#accept(object, &block) ⇒ Object
Configure a type conversion not already provided by the underlying OptionParser.
-
#around(&a_proc) ⇒ Object
This inverts the pre/post concept.
-
#commands_from(path) ⇒ Object
Loads ruby files in the load path that start with
path
, which are presumed to be commands for your executable. -
#config_file(filename) ⇒ Object
Sets that this app uses a config file as well as the name of the config file.
-
#default_command(command) ⇒ Object
Sets a default command to run when none is specified on the command line.
-
#exit_now!(message, exit_code = 1) ⇒ Object
Simpler means of exiting with a custom exit code.
-
#help_now!(message) ⇒ Object
Exit now, showing the user help for the command they executed.
-
#on_error(&a_proc) ⇒ Object
Define a block to run if an error occurs.
-
#post(&a_proc) ⇒ Object
Define a block to run after the command was executed, only if there was not an error.
-
#pre(&a_proc) ⇒ Object
Define a block to run after command line arguments are parsed but before any command is run.
-
#preserve_argv(preserve = true) ⇒ Object
By default, GLI mutates the argument passed to it.
-
#program_desc(description = nil) ⇒ Object
Describe the overall application/programm.
-
#program_name(override = nil) ⇒ Object
:nodoc:.
-
#skips_around ⇒ Object
Use this if the following command should not have the around block executed.
-
#skips_post ⇒ Object
Use this if the following command should not have the post block executed.
-
#skips_pre ⇒ Object
Use this if the following command should not have the pre block executed.
-
#use_openstruct(use_openstruct) ⇒ Object
Call this with
true
will cause theglobal_options
andoptions
passed to your code to be wrapped in Options, which is a subclass ofOpenStruct
that adds[]
and[]=
methods. -
#version(version) ⇒ Object
Indicate the version of your application.
Methods included from AppSupport
#accepts, #around_blocks, #clear_nexts, #commands, #config_file_name, #context_description, #copy_options_to_aliased_versions, #error_device=, #flags, #get_default_command, included, #override_command_defaults, #override_default, #override_defaults_based_on_config, #parse_config, #post_block, #pre_block, #reset, #run, #stderr, #switches, #version_string
Methods included from DSL
#arg_name, #clear_nexts, #command, #default_value, #desc, #flag, #long_desc, #switch
Methods included from CopyOptionsToAliases
Instance Method Details
#accept(object, &block) ⇒ Object
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
181 182 183 |
# File 'lib/gli/app.rb', line 181 def accept(object,&block) accepts[object] = block end |
#around(&a_proc) ⇒ Object
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
117 118 119 120 |
# File 'lib/gli/app.rb', line 117 def around(&a_proc) @around_blocks ||= [] @around_blocks << a_proc end |
#commands_from(path) ⇒ Object
Loads ruby files in the load path that start with path
, which are presumed to be commands for your executable. This is a glorified require
, but could also be used as a plugin mechanism. You could manipualte the load path at runtime and this call would find those files
- path
-
a path relative to somewhere in the
LOAD_PATH
, from which all.rb
files will be required.
22 23 24 25 26 27 28 29 30 31 32 33 34 |
# File 'lib/gli/app.rb', line 22 def commands_from(path) $LOAD_PATH.each do |load_path| commands_path = File.join(load_path,path) if File.exists? commands_path Dir.entries(commands_path).each do |entry| file = File.join(commands_path,entry) if file =~ /\.rb$/ require file end end end end end |
#config_file(filename) ⇒ Object
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
File.expand_path('~')
.
73 74 75 76 77 78 79 80 81 |
# File 'lib/gli/app.rb', line 73 def config_file(filename) if filename =~ /^\// @config_file = filename else @config_file = File.join(File.(ENV['HOME']),filename) end commands[:initconfig] = InitConfig.new(@config_file,commands,flags,switches) @config_file end |
#default_command(command) ⇒ Object
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
218 219 220 |
# File 'lib/gli/app.rb', line 218 def default_command(command) @default_command = command.to_sym end |
#exit_now!(message, exit_code = 1) ⇒ Object
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
192 193 194 |
# File 'lib/gli/app.rb', line 192 def exit_now!(,exit_code=1) raise CustomExit.new(,exit_code) end |
#help_now!(message) ⇒ Object
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
199 200 201 202 203 204 205 |
# File 'lib/gli/app.rb', line 199 def help_now!() exception = OptionParser::ParseError.new() class << exception def exit_code; 64; end end raise exception end |
#on_error(&a_proc) ⇒ Object
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
132 133 134 |
# File 'lib/gli/app.rb', line 132 def on_error(&a_proc) @error_block = a_proc end |
#post(&a_proc) ⇒ Object
Define a block to run after the command was executed, only if there was not an error. The block will receive the global-options,command,options, and arguments
96 97 98 |
# File 'lib/gli/app.rb', line 96 def post(&a_proc) @post_block = a_proc end |
#pre(&a_proc) ⇒ Object
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
89 90 91 |
# File 'lib/gli/app.rb', line 89 def pre(&a_proc) @pre_block = a_proc end |
#preserve_argv(preserve = true) ⇒ Object
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.
148 149 150 |
# File 'lib/gli/app.rb', line 148 def preserve_argv(preserve=true) @preserve_argv = preserve end |
#program_desc(description = nil) ⇒ Object
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
40 41 42 43 44 45 |
# File 'lib/gli/app.rb', line 40 def program_desc(description=nil) if description @program_desc = description end @program_desc end |
#program_name(override = nil) ⇒ Object
:nodoc:
207 208 209 |
# File 'lib/gli/app.rb', line 207 def program_name(override=nil) #:nodoc: warn "#program_name has been deprecated" end |
#skips_around ⇒ Object
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
64 65 66 |
# File 'lib/gli/app.rb', line 64 def skips_around @skips_around = true end |
#skips_post ⇒ Object
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
57 58 59 |
# File 'lib/gli/app.rb', line 57 def skips_post @skips_post = true end |
#skips_pre ⇒ Object
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
50 51 52 |
# File 'lib/gli/app.rb', line 50 def skips_pre @skips_pre = true end |
#use_openstruct(use_openstruct) ⇒ Object
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 []
and []=
methods.
use_openstruct
-
a Boolean indicating if we should use OpenStruct instead of Hashes
158 159 160 |
# File 'lib/gli/app.rb', line 158 def use_openstruct(use_openstruct) @use_openstruct = use_openstruct end |
#version(version) ⇒ Object
Indicate the version of your application
version
-
String containing the version of your application.
139 140 141 142 |
# File 'lib/gli/app.rb', line 139 def version(version) @version = version switch :version, :negatable => false end |