I was born out of a need for a simple option and command parser, while still providing an API that allows you to quickly create a full featured command-line interface.
$ [sudo] gem install claide
For full documentation, on the API of CLAide, visit rubydoc.info.
At its core, a library, such as myself, needs to parse the parameters specified by the user.
Working with parameters is done through the CLAide::ARGV class. It takes an
array of parameters and parses them as either flags, options, or arguments.
| Parameter | Description |
|---|---|
--milk, --no-milk |
A boolean ‘flag’, which may be negated. |
--sweetener=honey |
An ‘option’ consists of a key, a ‘=’, and a value. |
tea |
An ‘argument’ is just a value. |
Accessing flags, options, and arguments, with the following methods, will also remove the parameter from the remaining unprocessed parameters.
argv = CLAide::ARGV.new(['tea', '--no-milk', '--sweetener=honey'])
argv.shift_argument # => 'tea'
argv.shift_argument # => nil
argv.flag?('milk') # => false
argv.flag?('milk') # => nil
argv.option('sweetener') # => 'honey'
argv.option('sweetener') # => nilIn case the requested flag or option is not present, nil is returned. You can
specify a default value to be used as the optional second method parameter:
argv = CLAide::ARGV.new(['tea'])
argv.flag?('milk', true) # => true
argv.option('sweetener', 'sugar') # => 'sugar'Unlike flags and options, accessing all of the arguments can be done in either a preserving or mutating way:
argv = CLAide::ARGV.new(['tea', 'coffee'])
argv.arguments # => ['tea', 'coffee']
argv.arguments! # => ['tea', 'coffee']
argv.arguments # => []Commands are actions that a tool can perform. Every command is represented by its own command class.
Commands may be nested, in which case they inherit from the ‘super command’ class. Some of these nested commands may not actually perform any work themselves, but are rather used as ‘super commands’ only, in which case they are ‘abtract commands’.
Running commands is typically done through the CLAide::Command.run(argv)
method, which performs the following three steps:
-
Parses the given parameters, finds the command class matching the parameters, and instantiates it with the remaining parameters. It’s each nested command class’ responsibility to remove the parameters it handles from the remaining parameters, before calling the
superimplementation. -
Asks the command instance to validate its parameters, but only after calling the
superimplementation. Thesuperimplementation will show a help banner in case the--helpflag is specified, not all parameters were removed from the parameter list, or the command is an abstract command. -
Calls the
runmethod on the command instance, where it may do its work. -
Catches any uncaught exception and shows it to user in a meaningful way.
- A
Helpexception triggers a help banner to be shown for the command. - A exception that includes the
InformativeErrormodule will show only the message, unless disabled with the--verboseflag; and in red, depending on the color configuration. - Any other type of exception will be passed to
Command.report_error(error)for custom error reporting (such as the one in CocoaPods).
- A
In case you want to call commands from inside other commands, you should use
the CLAide::Command.parse(argv) method to retrieve an instance of the command
and call run on it. Unless you are using user-supplied parameters, there
should not be a need to validate the parameters.
See the example for a illustration of how to define commands.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent