command_kit 0.1.0.pre1 → 0.1.0.pre2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +37 -140
- data/examples/colors.rb +30 -0
- data/examples/command.rb +65 -0
- data/examples/pager.rb +30 -0
- data/lib/command_kit/arguments.rb +49 -18
- data/lib/command_kit/arguments/argument.rb +14 -44
- data/lib/command_kit/arguments/argument_value.rb +1 -30
- data/lib/command_kit/command.rb +45 -3
- data/lib/command_kit/commands.rb +6 -0
- data/lib/command_kit/commands/auto_load/subcommand.rb +3 -0
- data/lib/command_kit/commands/subcommand.rb +3 -0
- data/lib/command_kit/description.rb +3 -1
- data/lib/command_kit/examples.rb +3 -1
- data/lib/command_kit/help.rb +3 -0
- data/lib/command_kit/help/man.rb +74 -39
- data/lib/command_kit/main.rb +2 -0
- data/lib/command_kit/options.rb +46 -9
- data/lib/command_kit/options/option.rb +35 -5
- data/lib/command_kit/options/option_value.rb +40 -3
- data/lib/command_kit/pager.rb +6 -0
- data/lib/command_kit/version.rb +1 -1
- data/lib/command_kit/xdg.rb +8 -1
- data/spec/arguments/argument_spec.rb +3 -39
- data/spec/arguments/argument_value_spec.rb +1 -61
- data/spec/arguments_spec.rb +7 -0
- data/spec/help/man_spec.rb +348 -0
- data/spec/options/option_spec.rb +45 -6
- data/spec/options/option_value_spec.rb +52 -3
- data/spec/pager_spec.rb +2 -4
- metadata +10 -8
- data/lib/command_kit/arguments/usage.rb +0 -6
- data/lib/command_kit/options/usage.rb +0 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: baf0cab5c4519bef85a5ac27597c1c67b28a77cbe86d6c34b72687a91e1ef906
|
4
|
+
data.tar.gz: 1b816bb979dcff48caf5c09ac7f4dcd9006871c94b9fd3bee5a7c2ce1763815a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 284c9a6ff6bb1584add29558658054fc0814cfc0b1a1609b16a577154bc85e7011d9989abc75418bbd631f00a5f6c444dd104b3d938be347ad32ddf08e84ec83
|
7
|
+
data.tar.gz: f0df98d7654058aa5be0aa884703ef540be3a1b7e2be52cd4a975913731ee4572d30cfc1a7b5213b9a165e7a18f95f4bbd3d9eb1a217362370a6c3b9e6c7ea93
|
data/README.md
CHANGED
@@ -14,6 +14,7 @@ classes.
|
|
14
14
|
|
15
15
|
* Supports defining commands as Classes.
|
16
16
|
* Supports defining options and arguments as attributes.
|
17
|
+
* Supports extending commands via inheritance.
|
17
18
|
* Supports subcommands (explicit or lazy-loaded) and command aliases.
|
18
19
|
* Correctly handles Ctrl^C and SIGINT interrupts (aka exit 130).
|
19
20
|
* Correctly handles broken pipes (aka `mycmd | head`).
|
@@ -22,36 +23,38 @@ classes.
|
|
22
23
|
* Supports optionally displaying a man-page instead of `--help`
|
23
24
|
(see {CommandKit::Help::Man}).
|
24
25
|
* Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
|
25
|
-
* Easy to test:
|
26
|
-
|
27
|
-
|
28
|
-
###
|
29
|
-
|
30
|
-
*
|
31
|
-
*
|
32
|
-
*
|
33
|
-
*
|
34
|
-
|
35
|
-
*
|
36
|
-
*
|
37
|
-
*
|
38
|
-
*
|
39
|
-
|
40
|
-
*
|
41
|
-
*
|
42
|
-
*
|
43
|
-
*
|
44
|
-
|
45
|
-
*
|
46
|
-
*
|
47
|
-
|
48
|
-
*
|
49
|
-
*
|
50
|
-
*
|
51
|
-
*
|
52
|
-
*
|
53
|
-
*
|
54
|
-
*
|
26
|
+
* Easy to test (ex: `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`)
|
27
|
+
* Modular design (everything is a module).
|
28
|
+
|
29
|
+
### API
|
30
|
+
|
31
|
+
* [CommandKit::Arguments](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Arguments)
|
32
|
+
* [CommandKit::Colors](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Colors)
|
33
|
+
* [CommandKit::Command](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Command)
|
34
|
+
* [CommandKit::CommandName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/CommandName)
|
35
|
+
* [CommandKit::Commands](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands)
|
36
|
+
* [CommandKit::Commands::AutoLoad](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoLoad)
|
37
|
+
* [CommandKit::Commands::AutoRequire](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoRequire)
|
38
|
+
* [CommandKit::Console](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Console)
|
39
|
+
* [CommandKit::Description](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Description)
|
40
|
+
* [CommandKit::Env](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env)
|
41
|
+
* [CommandKit::Env::Home](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Home)
|
42
|
+
* [CommandKit::Env::Path](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Path)
|
43
|
+
* [CommandKit::Examples](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Examples)
|
44
|
+
* [CommandKit::ExceptionHandler](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ExceptionHandler)
|
45
|
+
* [CommandKit::Help](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help)
|
46
|
+
* [CommandKit::Help::Man](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help/Man)
|
47
|
+
* [CommandKit::Main](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Main)
|
48
|
+
* [CommandKit::Options](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options)
|
49
|
+
* [CommandKit::Options::Quiet](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Quiet)
|
50
|
+
* [CommandKit::Options::Verbose](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Verbose)
|
51
|
+
* [CommandKit::Pager](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Pager)
|
52
|
+
* [CommandKit::Printing](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing)
|
53
|
+
* [CommandKit::Printing::Indent](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing/Indent)
|
54
|
+
* [CommandKit::ProgramName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ProgramName)
|
55
|
+
* [CommandKit::Stdio](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Stdio)
|
56
|
+
* [CommandKit::Usage](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Usage)
|
57
|
+
* [CommandKit::XDG](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/XDG)
|
55
58
|
|
56
59
|
## Anti-Features
|
57
60
|
|
@@ -61,9 +64,7 @@ classes.
|
|
61
64
|
|
62
65
|
## Examples
|
63
66
|
|
64
|
-
###
|
65
|
-
|
66
|
-
#### lib/foo/cli/my_cmd.rb
|
67
|
+
### lib/foo/cli/my_cmd.rb
|
67
68
|
|
68
69
|
require 'command_kit'
|
69
70
|
|
@@ -91,8 +92,7 @@ classes.
|
|
91
92
|
@verbose += 1
|
92
93
|
end
|
93
94
|
|
94
|
-
argument :file,
|
95
|
-
required: true,
|
95
|
+
argument :file, required: true,
|
96
96
|
usage: 'FILE',
|
97
97
|
desc: "Input file"
|
98
98
|
|
@@ -120,7 +120,7 @@ classes.
|
|
120
120
|
end
|
121
121
|
end
|
122
122
|
|
123
|
-
|
123
|
+
### bin/my_cmd
|
124
124
|
|
125
125
|
#!/usr/bin/env ruby
|
126
126
|
|
@@ -129,7 +129,7 @@ classes.
|
|
129
129
|
|
130
130
|
Foo::CLI::MyCmd.start
|
131
131
|
|
132
|
-
|
132
|
+
### --help
|
133
133
|
|
134
134
|
Usage: my_cmd [OPTIONS] [-o OUTPUT] FILE
|
135
135
|
|
@@ -148,109 +148,6 @@ classes.
|
|
148
148
|
|
149
149
|
Example command
|
150
150
|
|
151
|
-
### Options
|
152
|
-
|
153
|
-
Define an option:
|
154
|
-
|
155
|
-
option :foo, desc: "Foo option"
|
156
|
-
|
157
|
-
With a custom short option:
|
158
|
-
|
159
|
-
option :foo, short: '-f',
|
160
|
-
desc: "Foo option"
|
161
|
-
|
162
|
-
With a custom long option:
|
163
|
-
|
164
|
-
option :foo, short: '--foo-opt',
|
165
|
-
desc: "Foo option"
|
166
|
-
|
167
|
-
With a custom usage string:
|
168
|
-
|
169
|
-
option :foo, value: {usage: 'FOO'},
|
170
|
-
desc: "Foo option"
|
171
|
-
|
172
|
-
With a custom block:
|
173
|
-
|
174
|
-
option :foo, desc: "Foo option" do |value|
|
175
|
-
@foo = Foo.new(value)
|
176
|
-
end
|
177
|
-
|
178
|
-
With a custom type:
|
179
|
-
|
180
|
-
option :foo, value: {type: Integer},
|
181
|
-
desc: "Foo option"
|
182
|
-
|
183
|
-
With a default value:
|
184
|
-
|
185
|
-
option :foo, value: {type: Integer, default: 1},
|
186
|
-
desc: "Foo option"
|
187
|
-
|
188
|
-
With a required value:
|
189
|
-
|
190
|
-
option :foo, value: {type: String, required: true},
|
191
|
-
desc: "Foo option"
|
192
|
-
|
193
|
-
With a custom option value Hash map:
|
194
|
-
|
195
|
-
option :flag, value: {
|
196
|
-
type: {
|
197
|
-
'enabled' => :enabled,
|
198
|
-
'yes' => :enabled,
|
199
|
-
'disabled' => :disabled,
|
200
|
-
'no' => :disabled
|
201
|
-
}
|
202
|
-
},
|
203
|
-
desc: "Flag option"
|
204
|
-
|
205
|
-
With a custom option value Array enum:
|
206
|
-
|
207
|
-
option :enum, value: {type: %w[yes no]},
|
208
|
-
desc: "Enum option"
|
209
|
-
|
210
|
-
With a custom option value Regexp:
|
211
|
-
|
212
|
-
option :date, value: {type: /(\d+)-(\d+)-(\d{2,4})/},
|
213
|
-
desc: "Regexp optin" do |date,d,m,y|
|
214
|
-
# ...
|
215
|
-
end
|
216
|
-
|
217
|
-
### Arguments
|
218
|
-
|
219
|
-
Define an argument:
|
220
|
-
|
221
|
-
argument :bar, desc: "Bar argument"
|
222
|
-
|
223
|
-
With a custom usage string:
|
224
|
-
|
225
|
-
option :bar, usage: 'BAR',
|
226
|
-
desc: "Bar argument"
|
227
|
-
|
228
|
-
With a custom block:
|
229
|
-
|
230
|
-
argument :bar, desc: "Bar argument" do |bar|
|
231
|
-
# ...
|
232
|
-
end
|
233
|
-
|
234
|
-
With a custom type:
|
235
|
-
|
236
|
-
argument :bar, type: Integer,
|
237
|
-
desc: "Bar argument"
|
238
|
-
|
239
|
-
With a default value:
|
240
|
-
|
241
|
-
argument :bar, default: "bar.txt",
|
242
|
-
desc: "Bar argument"
|
243
|
-
|
244
|
-
An optional argument:
|
245
|
-
|
246
|
-
argument :bar, required: true,
|
247
|
-
desc: "Bar argument"
|
248
|
-
|
249
|
-
A repeating argument:
|
250
|
-
|
251
|
-
argument :bar, repeats: true,
|
252
|
-
desc: "Bar argument"
|
253
|
-
|
254
151
|
## Requirements
|
255
152
|
|
256
153
|
* [ruby] >= 2.7.0
|
data/examples/colors.rb
ADDED
@@ -0,0 +1,30 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
|
4
|
+
require 'command_kit/command'
|
5
|
+
require 'command_kit/colors'
|
6
|
+
|
7
|
+
class ColorsCmd < CommandKit::Command
|
8
|
+
|
9
|
+
include CommandKit::Colors
|
10
|
+
|
11
|
+
description "Prints all of the standard ANSI colors"
|
12
|
+
|
13
|
+
def run
|
14
|
+
colors do |c|
|
15
|
+
puts c.black("Black") + "\t" + c.bold(c.black("Bold"))
|
16
|
+
puts c.red("Red") + "\t" + c.bold(c.red("Bold"))
|
17
|
+
puts c.green("Green") + "\t" + c.bold(c.green("Bold"))
|
18
|
+
puts c.yellow("Yellow") + "\t" + c.bold(c.yellow("Bold"))
|
19
|
+
puts c.blue("Blue") + "\t" + c.bold(c.blue("Bold"))
|
20
|
+
puts c.magenta("Magenta") + "\t" + c.bold(c.magenta("Bold"))
|
21
|
+
puts c.cyan("Cyan") + "\t" + c.bold(c.cyan("Bold"))
|
22
|
+
puts c.cyan("White") + "\t" + c.bold(c.white("Bold"))
|
23
|
+
end
|
24
|
+
end
|
25
|
+
|
26
|
+
end
|
27
|
+
|
28
|
+
if __FILE__ == $0
|
29
|
+
ColorsCmd.start
|
30
|
+
end
|
data/examples/command.rb
ADDED
@@ -0,0 +1,65 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
|
4
|
+
require 'command_kit/command'
|
5
|
+
|
6
|
+
class Command < CommandKit::Command
|
7
|
+
|
8
|
+
usage '[OPTIONS] [-o OUTPUT] FILE'
|
9
|
+
|
10
|
+
option :count, short: '-c',
|
11
|
+
value: {
|
12
|
+
type: Integer,
|
13
|
+
default: 1
|
14
|
+
},
|
15
|
+
desc: "Number of times"
|
16
|
+
|
17
|
+
option :output, value: {
|
18
|
+
type: String,
|
19
|
+
usage: 'FILE',
|
20
|
+
},
|
21
|
+
short: '-o',
|
22
|
+
desc: "Optional output file"
|
23
|
+
|
24
|
+
option :verbose, short: '-v', desc: "Increase verbose level" do
|
25
|
+
@verbose += 1
|
26
|
+
end
|
27
|
+
|
28
|
+
argument :file, required: true,
|
29
|
+
usage: 'FILE',
|
30
|
+
desc: "Input file"
|
31
|
+
|
32
|
+
examples [
|
33
|
+
'-o path/to/output.txt path/to/input.txt',
|
34
|
+
'-v -c 2 -o path/to/output.txt path/to/input.txt'
|
35
|
+
]
|
36
|
+
|
37
|
+
description "Example command"
|
38
|
+
|
39
|
+
def initialize
|
40
|
+
super
|
41
|
+
|
42
|
+
@verbose = 0
|
43
|
+
end
|
44
|
+
|
45
|
+
def run(file)
|
46
|
+
unless options.empty?
|
47
|
+
puts "Options:"
|
48
|
+
options.each do |name,value|
|
49
|
+
puts " #{name.inspect} => #{value.inspect}"
|
50
|
+
end
|
51
|
+
puts
|
52
|
+
end
|
53
|
+
|
54
|
+
puts "Arguments:"
|
55
|
+
puts " file = #{file.inspect}"
|
56
|
+
puts
|
57
|
+
|
58
|
+
puts "Custom Variables:"
|
59
|
+
puts " version = #{@verbose.inspect}"
|
60
|
+
end
|
61
|
+
end
|
62
|
+
|
63
|
+
if __FILE__ == $0
|
64
|
+
Command.start
|
65
|
+
end
|
data/examples/pager.rb
ADDED
@@ -0,0 +1,30 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
|
4
|
+
require 'command_kit/command'
|
5
|
+
require 'command_kit/pager'
|
6
|
+
|
7
|
+
class PagerCmd < CommandKit::Command
|
8
|
+
|
9
|
+
include CommandKit::Pager
|
10
|
+
|
11
|
+
description "Demos using the pager"
|
12
|
+
|
13
|
+
def run
|
14
|
+
puts "Starting pager ..."
|
15
|
+
|
16
|
+
pager do |io|
|
17
|
+
10.times do |i|
|
18
|
+
io.puts i
|
19
|
+
sleep 0.5
|
20
|
+
end
|
21
|
+
end
|
22
|
+
|
23
|
+
puts "Exiting pager ..."
|
24
|
+
end
|
25
|
+
|
26
|
+
end
|
27
|
+
|
28
|
+
if __FILE__ == $0
|
29
|
+
PagerCmd.start
|
30
|
+
end
|
@@ -1,3 +1,4 @@
|
|
1
|
+
require 'command_kit/main'
|
1
2
|
require 'command_kit/help'
|
2
3
|
require 'command_kit/arguments/argument'
|
3
4
|
|
@@ -9,13 +10,40 @@ module CommandKit
|
|
9
10
|
#
|
10
11
|
# include CommandKit::Arguments
|
11
12
|
#
|
12
|
-
# argument :output,
|
13
|
-
# desc: 'The output file'
|
13
|
+
# argument :output, desc: 'The output file'
|
14
14
|
#
|
15
|
-
# argument :input,
|
16
|
-
#
|
15
|
+
# argument :input, desc: 'The input file(s)'
|
16
|
+
#
|
17
|
+
# def run(output,input)
|
18
|
+
# end
|
19
|
+
#
|
20
|
+
# ### Optional Arguments
|
21
|
+
#
|
22
|
+
# argument :dir, required: false,
|
23
|
+
# desc: 'Can be omitted'
|
24
|
+
#
|
25
|
+
# def run(dir=nil)
|
26
|
+
# end
|
27
|
+
#
|
28
|
+
# ### Repeating Arguments
|
29
|
+
#
|
30
|
+
# argument :files, repeats: true,
|
31
|
+
# desc: 'Can be repeated one or more times'
|
32
|
+
#
|
33
|
+
# def run(*files)
|
34
|
+
# end
|
35
|
+
#
|
36
|
+
# ### Optional Repeating Arguments
|
37
|
+
#
|
38
|
+
# argument :files, required: true,
|
39
|
+
# repeats: true,
|
40
|
+
# desc: 'Can be repeated one or more times'
|
41
|
+
#
|
42
|
+
# def run(*files)
|
43
|
+
# end
|
17
44
|
#
|
18
45
|
module Arguments
|
46
|
+
include Main
|
19
47
|
include Help
|
20
48
|
|
21
49
|
module ModuleMethods
|
@@ -61,13 +89,22 @@ module CommandKit
|
|
61
89
|
# Defines an argument for the class.
|
62
90
|
#
|
63
91
|
# @param [Symbol] name
|
64
|
-
# The argument
|
92
|
+
# The name of the argument.
|
93
|
+
#
|
94
|
+
# @param [Hash{Symbol => Object}] kwargs
|
95
|
+
# Keyword arguments.
|
96
|
+
#
|
97
|
+
# @option kwargs [String, nil] usage
|
98
|
+
# The usage string for the argument. Defaults to the argument's name.
|
65
99
|
#
|
66
|
-
# @
|
67
|
-
#
|
100
|
+
# @option kwargs [Boolean] required
|
101
|
+
# Specifies whether the argument is required or optional.
|
68
102
|
#
|
69
|
-
# @
|
70
|
-
#
|
103
|
+
# @option kwargs [Boolean] repeats
|
104
|
+
# Specifies whether the argument can be repeated multiple times.
|
105
|
+
#
|
106
|
+
# @option kwargs [String] desc
|
107
|
+
# The description for the argument.
|
71
108
|
#
|
72
109
|
# @return [Argument]
|
73
110
|
# The newly defined argument.
|
@@ -79,14 +116,8 @@ module CommandKit
|
|
79
116
|
# option :bar, usage: 'BAR',
|
80
117
|
# desc: "Bar argument"
|
81
118
|
#
|
82
|
-
# @example With a custom block:
|
83
|
-
# argument :bar, desc: "Bar argument" do |bar|
|
84
|
-
# # ...
|
85
|
-
# end
|
86
|
-
#
|
87
119
|
# @example With a custom type:
|
88
|
-
# argument :bar,
|
89
|
-
# desc: "Bar argument"
|
120
|
+
# argument :bar, desc: "Bar argument"
|
90
121
|
#
|
91
122
|
# @example With a default value:
|
92
123
|
# argument :bar, default: "bar.txt",
|
@@ -100,8 +131,8 @@ module CommandKit
|
|
100
131
|
# argument :bar, repeats: true,
|
101
132
|
# desc: "Bar argument"
|
102
133
|
#
|
103
|
-
def argument(name,**kwargs
|
104
|
-
arguments[name] = Argument.new(name,**kwargs
|
134
|
+
def argument(name,**kwargs)
|
135
|
+
arguments[name] = Argument.new(name,**kwargs)
|
105
136
|
end
|
106
137
|
end
|
107
138
|
|