toys 0.12.2 → 0.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.yardopts +2 -0
- data/CHANGELOG.md +35 -0
- data/LICENSE.md +1 -1
- data/README.md +7 -4
- data/builtins/system/git-cache.rb +238 -0
- data/builtins/system/test.rb +37 -2
- data/core-docs/toys/acceptor.rb +432 -0
- data/core-docs/toys/arg_parser.rb +397 -0
- data/core-docs/toys/cli.rb +493 -0
- data/core-docs/toys/compat.rb +2 -0
- data/core-docs/toys/completion.rb +329 -0
- data/core-docs/toys/context.rb +321 -0
- data/core-docs/toys/core.rb +14 -0
- data/core-docs/toys/dsl/base.rb +56 -0
- data/core-docs/toys/dsl/flag.rb +261 -0
- data/core-docs/toys/dsl/flag_group.rb +259 -0
- data/core-docs/toys/dsl/internal.rb +4 -0
- data/core-docs/toys/dsl/positional_arg.rb +139 -0
- data/core-docs/toys/dsl/tool.rb +1530 -0
- data/core-docs/toys/errors.rb +93 -0
- data/core-docs/toys/flag.rb +549 -0
- data/core-docs/toys/flag_group.rb +186 -0
- data/core-docs/toys/input_file.rb +8 -0
- data/core-docs/toys/loader.rb +222 -0
- data/core-docs/toys/middleware.rb +295 -0
- data/core-docs/toys/mixin.rb +142 -0
- data/core-docs/toys/module_lookup.rb +75 -0
- data/core-docs/toys/positional_arg.rb +145 -0
- data/core-docs/toys/settings.rb +507 -0
- data/core-docs/toys/source_info.rb +127 -0
- data/core-docs/toys/standard_middleware/add_verbosity_flags.rb +49 -0
- data/core-docs/toys/standard_middleware/apply_config.rb +24 -0
- data/core-docs/toys/standard_middleware/handle_usage_errors.rb +33 -0
- data/core-docs/toys/standard_middleware/set_default_descriptions.rb +222 -0
- data/core-docs/toys/standard_middleware/show_help.rb +190 -0
- data/core-docs/toys/standard_middleware/show_root_version.rb +45 -0
- data/core-docs/toys/standard_mixins/bundler.rb +83 -0
- data/core-docs/toys/standard_mixins/exec.rb +645 -0
- data/core-docs/toys/standard_mixins/fileutils.rb +18 -0
- data/core-docs/toys/standard_mixins/gems.rb +48 -0
- data/core-docs/toys/standard_mixins/git_cache.rb +41 -0
- data/core-docs/toys/standard_mixins/highline.rb +133 -0
- data/core-docs/toys/standard_mixins/terminal.rb +135 -0
- data/core-docs/toys/standard_mixins/xdg.rb +49 -0
- data/core-docs/toys/template.rb +112 -0
- data/core-docs/toys/tool_definition.rb +926 -0
- data/core-docs/toys/utils/completion_engine.rb +49 -0
- data/core-docs/toys/utils/exec.rb +721 -0
- data/core-docs/toys/utils/gems.rb +185 -0
- data/core-docs/toys/utils/git_cache.rb +353 -0
- data/core-docs/toys/utils/help_text.rb +134 -0
- data/core-docs/toys/utils/terminal.rb +310 -0
- data/core-docs/toys/utils/xdg.rb +253 -0
- data/core-docs/toys/wrappable_string.rb +120 -0
- data/core-docs/toys-core.rb +63 -0
- data/docs/guide.md +497 -156
- data/lib/toys/standard_cli.rb +50 -36
- data/lib/toys/templates/clean.rb +18 -0
- data/lib/toys/templates/gem_build.rb +24 -0
- data/lib/toys/templates/minitest.rb +21 -0
- data/lib/toys/templates/rake.rb +23 -3
- data/lib/toys/templates/rdoc.rb +29 -0
- data/lib/toys/templates/rspec.rb +32 -4
- data/lib/toys/templates/rubocop.rb +14 -1
- data/lib/toys/templates/yardoc.rb +55 -0
- data/lib/toys/testing.rb +186 -109
- data/lib/toys/version.rb +1 -1
- data/lib/toys.rb +4 -2
- metadata +56 -6
@@ -0,0 +1,261 @@
|
|
1
|
+
module Toys
|
2
|
+
module DSL
|
3
|
+
##
|
4
|
+
# **_Defined in the toys-core gem_**
|
5
|
+
#
|
6
|
+
# DSL for a flag definition block. Lets you set flag attributes in a block
|
7
|
+
# instead of a long series of keyword arguments.
|
8
|
+
#
|
9
|
+
# These directives are available inside a block passed to
|
10
|
+
# {Toys::DSL::Tool#flag}.
|
11
|
+
#
|
12
|
+
# ### Example
|
13
|
+
#
|
14
|
+
# tool "mytool" do
|
15
|
+
# flag :value do
|
16
|
+
# # The directives in here are defined by this class
|
17
|
+
# flags "--value=VAL"
|
18
|
+
# accept Integer
|
19
|
+
# desc "An integer value"
|
20
|
+
# end
|
21
|
+
# # ...
|
22
|
+
# end
|
23
|
+
#
|
24
|
+
class Flag
|
25
|
+
##
|
26
|
+
# Add flags in OptionParser format. This may be called multiple times,
|
27
|
+
# and the results are cumulative.
|
28
|
+
#
|
29
|
+
# Following are examples of valid syntax.
|
30
|
+
#
|
31
|
+
# * `-a` : A short boolean switch. When this appears as an argument,
|
32
|
+
# the value is set to `true`.
|
33
|
+
# * `--abc` : A long boolean switch. When this appears as an argument,
|
34
|
+
# the value is set to `true`.
|
35
|
+
# * `-aVAL` or `-a VAL` : A short flag that takes a required value.
|
36
|
+
# These two forms are treated identically. If this argument appears
|
37
|
+
# with a value attached (e.g. `-afoo`), the attached string (e.g.
|
38
|
+
# `"foo"`) is taken as the value. Otherwise, the following argument
|
39
|
+
# is taken as the value (e.g. for `-a foo`, the value is set to
|
40
|
+
# `"foo"`.) The following argument is treated as the value even if it
|
41
|
+
# looks like a flag (e.g. `-a -a` causes the string `"-a"` to be
|
42
|
+
# taken as the value.)
|
43
|
+
# * `-a[VAL]` : A short flag that takes an optional value. If this
|
44
|
+
# argument appears with a value attached (e.g. `-afoo`), the attached
|
45
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, the value
|
46
|
+
# is set to `true`. The following argument is never interpreted as
|
47
|
+
# the value. (Compare with `-a [VAL]`.)
|
48
|
+
# * `-a [VAL]` : A short flag that takes an optional value. If this
|
49
|
+
# argument appears with a value attached (e.g. `-afoo`), the attached
|
50
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, if the
|
51
|
+
# following argument does not look like a flag (i.e. it does not
|
52
|
+
# begin with a hyphen), it is taken as the value. (e.g. `-a foo`
|
53
|
+
# causes the string `"foo"` to be taken as the value.). If there is
|
54
|
+
# no following argument, or the following argument looks like a flag,
|
55
|
+
# the value is set to `true`. (Compare with `-a[VAL]`.)
|
56
|
+
# * `--abc=VAL` or `--abc VAL` : A long flag that takes a required
|
57
|
+
# value. These two forms are treated identically. If this argument
|
58
|
+
# appears with a value attached (e.g. `--abc=foo`), the attached
|
59
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, the
|
60
|
+
# following argument is taken as the value (e.g. for `--abc foo`, the
|
61
|
+
# value is set to `"foo"`.) The following argument is treated as the
|
62
|
+
# value even if it looks like a flag (e.g. `--abc --def` causes the
|
63
|
+
# string `"--def"` to be taken as the value.)
|
64
|
+
# * `--abc[=VAL]` : A long flag that takes an optional value. If this
|
65
|
+
# argument appears with a value attached (e.g. `--abc=foo`), the
|
66
|
+
# attached string (e.g. `"foo"`) is taken as the value. Otherwise,
|
67
|
+
# the value is set to `true`. The following argument is never
|
68
|
+
# interpreted as the value. (Compare with `--abc [VAL]`.)
|
69
|
+
# * `--abc [VAL]` : A long flag that takes an optional value. If this
|
70
|
+
# argument appears with a value attached (e.g. `--abc=foo`), the
|
71
|
+
# attached string (e.g. `"foo"`) is taken as the value. Otherwise, if
|
72
|
+
# the following argument does not look like a flag (i.e. it does not
|
73
|
+
# begin with a hyphen), it is taken as the value. (e.g. `--abc foo`
|
74
|
+
# causes the string `"foo"` to be taken as the value.). If there is
|
75
|
+
# no following argument, or the following argument looks like a flag,
|
76
|
+
# the value is set to `true`. (Compare with `--abc=[VAL]`.)
|
77
|
+
# * `--[no-]abc` : A long boolean switch that can be turned either on
|
78
|
+
# or off. This effectively creates two flags, `--abc` which sets the
|
79
|
+
# value to `true`, and `--no-abc` which sets the falue to `false`.
|
80
|
+
#
|
81
|
+
# @param flags [String...]
|
82
|
+
# @return [self]
|
83
|
+
#
|
84
|
+
def flags(*flags)
|
85
|
+
# Source available in the toys-core gem
|
86
|
+
end
|
87
|
+
|
88
|
+
##
|
89
|
+
# Set the acceptor for this flag's values.
|
90
|
+
# You can pass either the string name of an acceptor defined in this tool
|
91
|
+
# or any of its ancestors, or any other specification recognized by
|
92
|
+
# {Toys::Acceptor.create}.
|
93
|
+
#
|
94
|
+
# @param spec [Object]
|
95
|
+
# @param options [Hash]
|
96
|
+
# @param block [Proc]
|
97
|
+
# @return [self]
|
98
|
+
#
|
99
|
+
def accept(spec = nil, **options, &block)
|
100
|
+
# Source available in the toys-core gem
|
101
|
+
end
|
102
|
+
|
103
|
+
##
|
104
|
+
# Set the default value.
|
105
|
+
#
|
106
|
+
# @param default [Object]
|
107
|
+
# @return [self]
|
108
|
+
#
|
109
|
+
def default(default)
|
110
|
+
# Source available in the toys-core gem
|
111
|
+
end
|
112
|
+
|
113
|
+
##
|
114
|
+
# Set the optional handler for setting/updating the value when a flag is
|
115
|
+
# parsed. A handler should be a Proc taking two arguments, the new given
|
116
|
+
# value and the previous value, and it should return the new value that
|
117
|
+
# should be set. You may pass the handler as a Proc (or an object
|
118
|
+
# responding to the `call` method) or you may pass a block.
|
119
|
+
#
|
120
|
+
# @param handler [Proc]
|
121
|
+
# @param block [Proc]
|
122
|
+
# @return [self]
|
123
|
+
#
|
124
|
+
def handler(handler = nil, &block)
|
125
|
+
# Source available in the toys-core gem
|
126
|
+
end
|
127
|
+
|
128
|
+
##
|
129
|
+
# Set the shell completion strategy for flag names.
|
130
|
+
# You can pass one of the following:
|
131
|
+
#
|
132
|
+
# * The string name of a completion defined in this tool or any of its
|
133
|
+
# ancestors.
|
134
|
+
# * A hash of options to pass to the constructor of
|
135
|
+
# {Toys::Flag::DefaultCompletion}.
|
136
|
+
# * `nil` or `:default` to select the standard completion strategy
|
137
|
+
# (which is {Toys::Flag::DefaultCompletion} with no extra options).
|
138
|
+
# * Any other specification recognized by {Toys::Completion.create}.
|
139
|
+
#
|
140
|
+
# @param spec [Object]
|
141
|
+
# @param options [Hash]
|
142
|
+
# @param block [Proc]
|
143
|
+
# @return [self]
|
144
|
+
#
|
145
|
+
def complete_flags(spec = nil, **options, &block)
|
146
|
+
# Source available in the toys-core gem
|
147
|
+
end
|
148
|
+
|
149
|
+
##
|
150
|
+
# Set the shell completion strategy for flag values.
|
151
|
+
# You can pass either the string name of a completion defined in this
|
152
|
+
# tool or any of its ancestors, or any other specification recognized by
|
153
|
+
# {Toys::Completion.create}.
|
154
|
+
#
|
155
|
+
# @param spec [Object]
|
156
|
+
# @param options [Hash]
|
157
|
+
# @param block [Proc]
|
158
|
+
# @return [self]
|
159
|
+
#
|
160
|
+
def complete_values(spec = nil, **options, &block)
|
161
|
+
# Source available in the toys-core gem
|
162
|
+
end
|
163
|
+
|
164
|
+
##
|
165
|
+
# Set whether to raise an exception if a flag is requested that is
|
166
|
+
# already in use or marked as disabled.
|
167
|
+
#
|
168
|
+
# @param setting [Boolean]
|
169
|
+
# @return [self]
|
170
|
+
#
|
171
|
+
def report_collisions(setting)
|
172
|
+
# Source available in the toys-core gem
|
173
|
+
end
|
174
|
+
|
175
|
+
##
|
176
|
+
# Set the short description for the current flag. The short description
|
177
|
+
# is displayed with the flag in online help.
|
178
|
+
#
|
179
|
+
# The description is a {Toys::WrappableString}, which may be word-wrapped
|
180
|
+
# when displayed in a help screen. You may pass a {Toys::WrappableString}
|
181
|
+
# directly to this method, or you may pass any input that can be used to
|
182
|
+
# construct a wrappable string:
|
183
|
+
#
|
184
|
+
# * If you pass a String, its whitespace will be compacted (i.e. tabs,
|
185
|
+
# newlines, and multiple consecutive whitespace will be turned into a
|
186
|
+
# single space), and it will be word-wrapped on whitespace.
|
187
|
+
# * If you pass an Array of Strings, each string will be considered a
|
188
|
+
# literal word that cannot be broken, and wrapping will be done
|
189
|
+
# across the strings in the array. In this case, whitespace is not
|
190
|
+
# compacted.
|
191
|
+
#
|
192
|
+
# ### Examples
|
193
|
+
#
|
194
|
+
# If you pass in a sentence as a simple string, it may be word wrapped
|
195
|
+
# when displayed:
|
196
|
+
#
|
197
|
+
# desc "This sentence may be wrapped."
|
198
|
+
#
|
199
|
+
# To specify a sentence that should never be word-wrapped, pass it as the
|
200
|
+
# sole element of a string array:
|
201
|
+
#
|
202
|
+
# desc ["This sentence will not be wrapped."]
|
203
|
+
#
|
204
|
+
# @param desc [String,Array<String>,Toys::WrappableString]
|
205
|
+
# @return [self]
|
206
|
+
#
|
207
|
+
def desc(desc)
|
208
|
+
# Source available in the toys-core gem
|
209
|
+
end
|
210
|
+
|
211
|
+
##
|
212
|
+
# Add to the long description for the current flag. The long description
|
213
|
+
# is displayed with the flag in online help. This directive may be given
|
214
|
+
# multiple times, and the results are cumulative.
|
215
|
+
#
|
216
|
+
# A long description is a series of descriptions, which are generally
|
217
|
+
# displayed in a series of lines/paragraphs. Each individual description
|
218
|
+
# uses the form described in the {#desc} documentation, and may be
|
219
|
+
# word-wrapped when displayed. To insert a blank line, include an empty
|
220
|
+
# string as one of the descriptions.
|
221
|
+
#
|
222
|
+
# ### Example
|
223
|
+
#
|
224
|
+
# long_desc "This initial paragraph might get word wrapped.",
|
225
|
+
# "This next paragraph is followed by a blank line.",
|
226
|
+
# "",
|
227
|
+
# ["This line will not be wrapped."],
|
228
|
+
# [" This indent is preserved."]
|
229
|
+
# long_desc "This line is appended to the description."
|
230
|
+
#
|
231
|
+
# @param long_desc [String,Array<String>,Toys::WrappableString...]
|
232
|
+
# @return [self]
|
233
|
+
#
|
234
|
+
def long_desc(*long_desc)
|
235
|
+
# Source available in the toys-core gem
|
236
|
+
end
|
237
|
+
|
238
|
+
##
|
239
|
+
# Set the group. A group may be set by name or group object. Setting
|
240
|
+
# `nil` selects the default group.
|
241
|
+
#
|
242
|
+
# @param group [String,Symbol,Toys::FlagGroup,nil]
|
243
|
+
# @return [self]
|
244
|
+
#
|
245
|
+
def group(group)
|
246
|
+
# Source available in the toys-core gem
|
247
|
+
end
|
248
|
+
|
249
|
+
##
|
250
|
+
# Set the display name for this flag. This may be used in help text and
|
251
|
+
# error messages.
|
252
|
+
#
|
253
|
+
# @param display_name [String]
|
254
|
+
# @return [self]
|
255
|
+
#
|
256
|
+
def display_name(display_name)
|
257
|
+
# Source available in the toys-core gem
|
258
|
+
end
|
259
|
+
end
|
260
|
+
end
|
261
|
+
end
|
@@ -0,0 +1,259 @@
|
|
1
|
+
module Toys
|
2
|
+
module DSL
|
3
|
+
##
|
4
|
+
# **_Defined in the toys-core gem_**
|
5
|
+
#
|
6
|
+
# DSL for a flag group definition block. Lets you create flags in a group.
|
7
|
+
#
|
8
|
+
# These directives are available inside a block passed to
|
9
|
+
# {Toys::DSL::Tool#flag_group}, {Toys::DSL::Tool#all_required},
|
10
|
+
# {Toys::DSL::Tool#at_most_one}, {Toys::DSL::Tool#at_least_one}, or
|
11
|
+
# {Toys::DSL::Tool#exactly_one}.
|
12
|
+
#
|
13
|
+
# ### Example
|
14
|
+
#
|
15
|
+
# tool "login" do
|
16
|
+
# all_required do
|
17
|
+
# # The directives in here are defined by this class
|
18
|
+
# flag :username, "--username=VAL", desc: "Set username (required)"
|
19
|
+
# flag :password, "--password=VAL", desc: "Set password (required)"
|
20
|
+
# end
|
21
|
+
# # ...
|
22
|
+
# end
|
23
|
+
#
|
24
|
+
class FlagGroup
|
25
|
+
##
|
26
|
+
# Add a flag to the current group. Each flag must specify a key which
|
27
|
+
# the script may use to obtain the flag value from the context.
|
28
|
+
# You may then provide the flags themselves in OptionParser form.
|
29
|
+
#
|
30
|
+
# If the given key is a symbol representing a valid method name, then a
|
31
|
+
# helper method is automatically added to retrieve the value. Otherwise,
|
32
|
+
# if the key is a string or does not represent a valid method name, the
|
33
|
+
# tool can retrieve the value by calling {Toys::Context#get}.
|
34
|
+
#
|
35
|
+
# Attributes of the flag may be passed in as arguments to this method, or
|
36
|
+
# set in a block passed to this method. If you provide a block, you can
|
37
|
+
# use directives in {Toys::DSL::Flag} within the block.
|
38
|
+
#
|
39
|
+
# ### Flag syntax
|
40
|
+
#
|
41
|
+
# The flags themselves should be provided in OptionParser form. Following
|
42
|
+
# are examples of valid syntax.
|
43
|
+
#
|
44
|
+
# * `-a` : A short boolean switch. When this appears as an argument,
|
45
|
+
# the value is set to `true`.
|
46
|
+
# * `--abc` : A long boolean switch. When this appears as an argument,
|
47
|
+
# the value is set to `true`.
|
48
|
+
# * `-aVAL` or `-a VAL` : A short flag that takes a required value.
|
49
|
+
# These two forms are treated identically. If this argument appears
|
50
|
+
# with a value attached (e.g. `-afoo`), the attached string (e.g.
|
51
|
+
# `"foo"`) is taken as the value. Otherwise, the following argument
|
52
|
+
# is taken as the value (e.g. for `-a foo`, the value is set to
|
53
|
+
# `"foo"`.) The following argument is treated as the value even if it
|
54
|
+
# looks like a flag (e.g. `-a -a` causes the string `"-a"` to be
|
55
|
+
# taken as the value.)
|
56
|
+
# * `-a[VAL]` : A short flag that takes an optional value. If this
|
57
|
+
# argument appears with a value attached (e.g. `-afoo`), the attached
|
58
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, the value
|
59
|
+
# is set to `true`. The following argument is never interpreted as
|
60
|
+
# the value. (Compare with `-a [VAL]`.)
|
61
|
+
# * `-a [VAL]` : A short flag that takes an optional value. If this
|
62
|
+
# argument appears with a value attached (e.g. `-afoo`), the attached
|
63
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, if the
|
64
|
+
# following argument does not look like a flag (i.e. it does not
|
65
|
+
# begin with a hyphen), it is taken as the value. (e.g. `-a foo`
|
66
|
+
# causes the string `"foo"` to be taken as the value.). If there is
|
67
|
+
# no following argument, or the following argument looks like a flag,
|
68
|
+
# the value is set to `true`. (Compare with `-a[VAL]`.)
|
69
|
+
# * `--abc=VAL` or `--abc VAL` : A long flag that takes a required
|
70
|
+
# value. These two forms are treated identically. If this argument
|
71
|
+
# appears with a value attached (e.g. `--abc=foo`), the attached
|
72
|
+
# string (e.g. `"foo"`) is taken as the value. Otherwise, the
|
73
|
+
# following argument is taken as the value (e.g. for `--abc foo`, the
|
74
|
+
# value is set to `"foo"`.) The following argument is treated as the
|
75
|
+
# value even if it looks like a flag (e.g. `--abc --def` causes the
|
76
|
+
# string `"--def"` to be taken as the value.)
|
77
|
+
# * `--abc[=VAL]` : A long flag that takes an optional value. If this
|
78
|
+
# argument appears with a value attached (e.g. `--abc=foo`), the
|
79
|
+
# attached string (e.g. `"foo"`) is taken as the value. Otherwise,
|
80
|
+
# the value is set to `true`. The following argument is never
|
81
|
+
# interpreted as the value. (Compare with `--abc [VAL]`.)
|
82
|
+
# * `--abc [VAL]` : A long flag that takes an optional value. If this
|
83
|
+
# argument appears with a value attached (e.g. `--abc=foo`), the
|
84
|
+
# attached string (e.g. `"foo"`) is taken as the value. Otherwise, if
|
85
|
+
# the following argument does not look like a flag (i.e. it does not
|
86
|
+
# begin with a hyphen), it is taken as the value. (e.g. `--abc foo`
|
87
|
+
# causes the string `"foo"` to be taken as the value.). If there is
|
88
|
+
# no following argument, or the following argument looks like a flag,
|
89
|
+
# the value is set to `true`. (Compare with `--abc=[VAL]`.)
|
90
|
+
# * `--[no-]abc` : A long boolean switch that can be turned either on
|
91
|
+
# or off. This effectively creates two flags, `--abc` which sets the
|
92
|
+
# value to `true`, and `--no-abc` which sets the falue to `false`.
|
93
|
+
#
|
94
|
+
# ### Default flag syntax
|
95
|
+
#
|
96
|
+
# If no flag syntax strings are provided, a default syntax will be
|
97
|
+
# inferred based on the key and other options.
|
98
|
+
#
|
99
|
+
# Specifically, if the key has one character, then that character will be
|
100
|
+
# chosen as a short flag. If the key has multiple characters, a long flag
|
101
|
+
# will be generated.
|
102
|
+
#
|
103
|
+
# Furthermore, if a custom completion, a non-boolean acceptor, or a
|
104
|
+
# non-boolean default value is provided in the options, then the flag
|
105
|
+
# will be considered to take a value. Otherwise, it will be considered to
|
106
|
+
# be a boolean switch.
|
107
|
+
#
|
108
|
+
# For example, the following pairs of flags are identical:
|
109
|
+
#
|
110
|
+
# flag :a
|
111
|
+
# flag :a, "-a"
|
112
|
+
#
|
113
|
+
# flag :abc_def
|
114
|
+
# flag :abc_def, "--abc-def"
|
115
|
+
#
|
116
|
+
# flag :number, accept: Integer
|
117
|
+
# flag :number, "--number=VAL", accept: Integer
|
118
|
+
#
|
119
|
+
# ### More examples
|
120
|
+
#
|
121
|
+
# A flag that sets its value to the number of times it appears on the
|
122
|
+
# command line:
|
123
|
+
#
|
124
|
+
# flag :verbose, "-v", "--verbose",
|
125
|
+
# default: 0, handler: ->(_val, count) { count + 1 }
|
126
|
+
#
|
127
|
+
# An example using block form:
|
128
|
+
#
|
129
|
+
# flag :shout do
|
130
|
+
# flags "-s", "--shout"
|
131
|
+
# default false
|
132
|
+
# desc "Say it louder"
|
133
|
+
# long_desc "This flag says it lowder.",
|
134
|
+
# "You might use this when people can't hear you.",
|
135
|
+
# "",
|
136
|
+
# "Example:",
|
137
|
+
# [" toys say --shout hello"]
|
138
|
+
# end
|
139
|
+
#
|
140
|
+
# @param key [String,Symbol] The key to use to retrieve the value from
|
141
|
+
# the execution context.
|
142
|
+
# @param flags [String...] The flags in OptionParser format.
|
143
|
+
# @param accept [Object] An acceptor that validates and/or converts the
|
144
|
+
# value. You may provide either the name of an acceptor you have
|
145
|
+
# defined, or one of the default acceptors provided by OptionParser.
|
146
|
+
# Optional. If not specified, accepts any value as a string.
|
147
|
+
# @param default [Object] The default value. This is the value that will
|
148
|
+
# be set in the context if this flag is not provided on the command
|
149
|
+
# line. Defaults to `nil`.
|
150
|
+
# @param handler [Proc,nil,:set,:push] An optional handler for
|
151
|
+
# setting/updating the value. A handler is a proc taking two
|
152
|
+
# arguments, the given value and the previous value, returning the
|
153
|
+
# new value that should be set. You may also specify a predefined
|
154
|
+
# named handler. The `:set` handler (the default) replaces the
|
155
|
+
# previous value (effectively `-> (val, _prev) { val }`). The
|
156
|
+
# `:push` handler expects the previous value to be an array and
|
157
|
+
# pushes the given value onto it; it should be combined with setting
|
158
|
+
# `default: []` and is intended for "multi-valued" flags.
|
159
|
+
# @param complete_flags [Object] A specifier for shell tab completion
|
160
|
+
# for flag names associated with this flag. By default, a
|
161
|
+
# {Toys::Flag::DefaultCompletion} is used, which provides the flag's
|
162
|
+
# names as completion candidates. To customize completion, set this
|
163
|
+
# to the name of a previously defined completion, a hash of options
|
164
|
+
# to pass to the constructor for {Toys::Flag::DefaultCompletion}, or
|
165
|
+
# any other spec recognized by {Toys::Completion.create}.
|
166
|
+
# @param complete_values [Object] A specifier for shell tab completion
|
167
|
+
# for flag values associated with this flag. This is the empty
|
168
|
+
# completion by default. To customize completion, set this to the
|
169
|
+
# name of a previously defined completion, or any spec recognized by
|
170
|
+
# {Toys::Completion.create}.
|
171
|
+
# @param report_collisions [Boolean] Raise an exception if a flag is
|
172
|
+
# requested that is already in use or marked as unusable. Default is
|
173
|
+
# true.
|
174
|
+
# @param desc [String,Array<String>,Toys::WrappableString] Short
|
175
|
+
# description for the flag. See {Toys::DSL::Tool#desc} for a
|
176
|
+
# description of the allowed formats. Defaults to the empty string.
|
177
|
+
# @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
|
178
|
+
# Long description for the flag. See {Toys::DSL::Tool#long_desc} for
|
179
|
+
# a description of the allowed formats. (But note that this param
|
180
|
+
# takes an Array of description lines, rather than a series of
|
181
|
+
# arguments.) Defaults to the empty array.
|
182
|
+
# @param display_name [String] A display name for this flag, used in help
|
183
|
+
# text and error messages.
|
184
|
+
# @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
|
185
|
+
# directives that can be called in this block.
|
186
|
+
# @return [self]
|
187
|
+
#
|
188
|
+
def flag(key, *flags,
|
189
|
+
accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil,
|
190
|
+
report_collisions: true, desc: nil, long_desc: nil, display_name: nil,
|
191
|
+
&block)
|
192
|
+
# Source available in the toys-core gem
|
193
|
+
end
|
194
|
+
|
195
|
+
##
|
196
|
+
# Set the short description for the current flag group. The short
|
197
|
+
# description is displayed as the group title in online help.
|
198
|
+
#
|
199
|
+
# The description is a {Toys::WrappableString}, which may be word-wrapped
|
200
|
+
# when displayed in a help screen. You may pass a {Toys::WrappableString}
|
201
|
+
# directly to this method, or you may pass any input that can be used to
|
202
|
+
# construct a wrappable string:
|
203
|
+
#
|
204
|
+
# * If you pass a String, its whitespace will be compacted (i.e. tabs,
|
205
|
+
# newlines, and multiple consecutive whitespace will be turned into a
|
206
|
+
# single space), and it will be word-wrapped on whitespace.
|
207
|
+
# * If you pass an Array of Strings, each string will be considered a
|
208
|
+
# literal word that cannot be broken, and wrapping will be done
|
209
|
+
# across the strings in the array. In this case, whitespace is not
|
210
|
+
# compacted.
|
211
|
+
#
|
212
|
+
# ### Examples
|
213
|
+
#
|
214
|
+
# If you pass in a sentence as a simple string, it may be word wrapped
|
215
|
+
# when displayed:
|
216
|
+
#
|
217
|
+
# desc "This sentence may be wrapped."
|
218
|
+
#
|
219
|
+
# To specify a sentence that should never be word-wrapped, pass it as the
|
220
|
+
# sole element of a string array:
|
221
|
+
#
|
222
|
+
# desc ["This sentence will not be wrapped."]
|
223
|
+
#
|
224
|
+
# @param desc [String,Array<String>,Toys::WrappableString]
|
225
|
+
# @return [self]
|
226
|
+
#
|
227
|
+
def desc(desc)
|
228
|
+
# Source available in the toys-core gem
|
229
|
+
end
|
230
|
+
|
231
|
+
##
|
232
|
+
# Add to the long description for the current flag group. The long
|
233
|
+
# description is displayed with the flag group in online help. This
|
234
|
+
# directive may be given multiple times, and the results are cumulative.
|
235
|
+
#
|
236
|
+
# A long description is a series of descriptions, which are generally
|
237
|
+
# displayed in a series of lines/paragraphs. Each individual description
|
238
|
+
# uses the form described in the {#desc} documentation, and may be
|
239
|
+
# word-wrapped when displayed. To insert a blank line, include an empty
|
240
|
+
# string as one of the descriptions.
|
241
|
+
#
|
242
|
+
# ### Example
|
243
|
+
#
|
244
|
+
# long_desc "This initial paragraph might get word wrapped.",
|
245
|
+
# "This next paragraph is followed by a blank line.",
|
246
|
+
# "",
|
247
|
+
# ["This line will not be wrapped."],
|
248
|
+
# [" This indent is preserved."]
|
249
|
+
# long_desc "This line is appended to the description."
|
250
|
+
#
|
251
|
+
# @param long_desc [String,Array<String>,Toys::WrappableString...]
|
252
|
+
# @return [self]
|
253
|
+
#
|
254
|
+
def long_desc(*long_desc)
|
255
|
+
# Source available in the toys-core gem
|
256
|
+
end
|
257
|
+
end
|
258
|
+
end
|
259
|
+
end
|
@@ -0,0 +1,139 @@
|
|
1
|
+
module Toys
|
2
|
+
module DSL
|
3
|
+
##
|
4
|
+
# **_Defined in the toys-core gem_**
|
5
|
+
#
|
6
|
+
# DSL for an arg definition block. Lets you set arg attributes in a block
|
7
|
+
# instead of a long series of keyword arguments.
|
8
|
+
#
|
9
|
+
# These directives are available inside a block passed to
|
10
|
+
# {Toys::DSL::Tool#required_arg}, {Toys::DSL::Tool#optional_arg}, or
|
11
|
+
# {Toys::DSL::Tool#remaining_args}.
|
12
|
+
#
|
13
|
+
# ### Example
|
14
|
+
#
|
15
|
+
# tool "mytool" do
|
16
|
+
# optional_arg :value do
|
17
|
+
# # The directives in here are defined by this class
|
18
|
+
# accept Integer
|
19
|
+
# desc "An integer value"
|
20
|
+
# end
|
21
|
+
# # ...
|
22
|
+
# end
|
23
|
+
#
|
24
|
+
class PositionalArg
|
25
|
+
##
|
26
|
+
# Set the acceptor for this argument's values.
|
27
|
+
# You can pass either the string name of an acceptor defined in this tool
|
28
|
+
# or any of its ancestors, or any other specification recognized by
|
29
|
+
# {Toys::Acceptor.create}.
|
30
|
+
#
|
31
|
+
# @param spec [Object]
|
32
|
+
# @param options [Hash]
|
33
|
+
# @param block [Proc]
|
34
|
+
# @return [self]
|
35
|
+
#
|
36
|
+
def accept(spec = nil, **options, &block)
|
37
|
+
# Source available in the toys-core gem
|
38
|
+
end
|
39
|
+
|
40
|
+
##
|
41
|
+
# Set the default value.
|
42
|
+
#
|
43
|
+
# @param default [Object]
|
44
|
+
# @return [self]
|
45
|
+
#
|
46
|
+
def default(default)
|
47
|
+
# Source available in the toys-core gem
|
48
|
+
end
|
49
|
+
|
50
|
+
##
|
51
|
+
# Set the shell completion strategy for arg values.
|
52
|
+
# You can pass either the string name of a completion defined in this
|
53
|
+
# tool or any of its ancestors, or any other specification recognized by
|
54
|
+
# {Toys::Completion.create}.
|
55
|
+
#
|
56
|
+
# @param spec [Object]
|
57
|
+
# @param options [Hash]
|
58
|
+
# @param block [Proc]
|
59
|
+
# @return [self]
|
60
|
+
#
|
61
|
+
def complete(spec = nil, **options, &block)
|
62
|
+
# Source available in the toys-core gem
|
63
|
+
end
|
64
|
+
|
65
|
+
##
|
66
|
+
# Set the name of this arg as it appears in help screens.
|
67
|
+
#
|
68
|
+
# @param display_name [String]
|
69
|
+
# @return [self]
|
70
|
+
#
|
71
|
+
def display_name(display_name)
|
72
|
+
# Source available in the toys-core gem
|
73
|
+
end
|
74
|
+
|
75
|
+
##
|
76
|
+
# Set the short description for the current positional argument. The
|
77
|
+
# short description is displayed with the argument in online help.
|
78
|
+
#
|
79
|
+
# The description is a {Toys::WrappableString}, which may be word-wrapped
|
80
|
+
# when displayed in a help screen. You may pass a {Toys::WrappableString}
|
81
|
+
# directly to this method, or you may pass any input that can be used to
|
82
|
+
# construct a wrappable string:
|
83
|
+
#
|
84
|
+
# * If you pass a String, its whitespace will be compacted (i.e. tabs,
|
85
|
+
# newlines, and multiple consecutive whitespace will be turned into a
|
86
|
+
# single space), and it will be word-wrapped on whitespace.
|
87
|
+
# * If you pass an Array of Strings, each string will be considered a
|
88
|
+
# literal word that cannot be broken, and wrapping will be done
|
89
|
+
# across the strings in the array. In this case, whitespace is not
|
90
|
+
# compacted.
|
91
|
+
#
|
92
|
+
# ### Examples
|
93
|
+
#
|
94
|
+
# If you pass in a sentence as a simple string, it may be word wrapped
|
95
|
+
# when displayed:
|
96
|
+
#
|
97
|
+
# desc "This sentence may be wrapped."
|
98
|
+
#
|
99
|
+
# To specify a sentence that should never be word-wrapped, pass it as the
|
100
|
+
# sole element of a string array:
|
101
|
+
#
|
102
|
+
# desc ["This sentence will not be wrapped."]
|
103
|
+
#
|
104
|
+
# @param desc [String,Array<String>,Toys::WrappableString]
|
105
|
+
# @return [self]
|
106
|
+
#
|
107
|
+
def desc(desc)
|
108
|
+
# Source available in the toys-core gem
|
109
|
+
end
|
110
|
+
|
111
|
+
##
|
112
|
+
# Add to the long description for the current positional argument. The
|
113
|
+
# long description is displayed with the argument in online help. This
|
114
|
+
# directive may be given multiple times, and the results are cumulative.
|
115
|
+
#
|
116
|
+
# A long description is a series of descriptions, which are generally
|
117
|
+
# displayed in a series of lines/paragraphs. Each individual description
|
118
|
+
# uses the form described in the {#desc} documentation, and may be
|
119
|
+
# word-wrapped when displayed. To insert a blank line, include an empty
|
120
|
+
# string as one of the descriptions.
|
121
|
+
#
|
122
|
+
# ### Example
|
123
|
+
#
|
124
|
+
# long_desc "This initial paragraph might get word wrapped.",
|
125
|
+
# "This next paragraph is followed by a blank line.",
|
126
|
+
# "",
|
127
|
+
# ["This line will not be wrapped."],
|
128
|
+
# [" This indent is preserved."]
|
129
|
+
# long_desc "This line is appended to the description."
|
130
|
+
#
|
131
|
+
# @param long_desc [String,Array<String>,Toys::WrappableString...]
|
132
|
+
# @return [self]
|
133
|
+
#
|
134
|
+
def long_desc(*long_desc)
|
135
|
+
# Source available in the toys-core gem
|
136
|
+
end
|
137
|
+
end
|
138
|
+
end
|
139
|
+
end
|