toys-core 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/CHANGELOG.md +22 -0
- data/LICENSE.md +1 -1
- data/README.md +4 -1
- data/docs/guide.md +1 -1
- data/lib/toys/acceptor.rb +10 -1
- data/lib/toys/arg_parser.rb +1 -0
- data/lib/toys/cli.rb +127 -107
- data/lib/toys/compat.rb +54 -3
- data/lib/toys/completion.rb +15 -5
- data/lib/toys/context.rb +22 -20
- data/lib/toys/core.rb +6 -2
- data/lib/toys/dsl/base.rb +2 -0
- data/lib/toys/dsl/flag.rb +23 -17
- data/lib/toys/dsl/flag_group.rb +11 -7
- data/lib/toys/dsl/positional_arg.rb +23 -13
- data/lib/toys/dsl/tool.rb +10 -6
- data/lib/toys/errors.rb +63 -8
- data/lib/toys/flag.rb +660 -651
- data/lib/toys/flag_group.rb +19 -6
- data/lib/toys/input_file.rb +9 -3
- data/lib/toys/loader.rb +129 -115
- data/lib/toys/middleware.rb +45 -21
- data/lib/toys/mixin.rb +8 -6
- data/lib/toys/positional_arg.rb +18 -17
- data/lib/toys/settings.rb +81 -67
- data/lib/toys/source_info.rb +33 -24
- data/lib/toys/standard_middleware/add_verbosity_flags.rb +2 -0
- data/lib/toys/standard_middleware/apply_config.rb +1 -0
- data/lib/toys/standard_middleware/handle_usage_errors.rb +1 -0
- data/lib/toys/standard_middleware/set_default_descriptions.rb +1 -0
- data/lib/toys/standard_middleware/show_help.rb +2 -0
- data/lib/toys/standard_middleware/show_root_version.rb +2 -0
- data/lib/toys/standard_mixins/bundler.rb +22 -14
- data/lib/toys/standard_mixins/exec.rb +31 -20
- data/lib/toys/standard_mixins/fileutils.rb +3 -1
- data/lib/toys/standard_mixins/gems.rb +21 -17
- data/lib/toys/standard_mixins/git_cache.rb +5 -7
- data/lib/toys/standard_mixins/highline.rb +8 -8
- data/lib/toys/standard_mixins/terminal.rb +5 -5
- data/lib/toys/standard_mixins/xdg.rb +5 -5
- data/lib/toys/template.rb +9 -7
- data/lib/toys/tool_definition.rb +209 -202
- data/lib/toys/utils/completion_engine.rb +7 -2
- data/lib/toys/utils/exec.rb +158 -127
- data/lib/toys/utils/gems.rb +81 -57
- data/lib/toys/utils/git_cache.rb +674 -45
- data/lib/toys/utils/help_text.rb +27 -3
- data/lib/toys/utils/terminal.rb +10 -2
- data/lib/toys/wrappable_string.rb +9 -2
- data/lib/toys-core.rb +14 -5
- metadata +4 -4
data/lib/toys/flag.rb
CHANGED
@@ -6,6 +6,367 @@ module Toys
|
|
6
6
|
# key. The flags within a single Flag definition are synonyms.
|
7
7
|
#
|
8
8
|
class Flag
|
9
|
+
##
|
10
|
+
# Representation of a single flag.
|
11
|
+
#
|
12
|
+
class Syntax
|
13
|
+
# rubocop:disable Style/PerlBackrefs
|
14
|
+
|
15
|
+
##
|
16
|
+
# Parse flag syntax
|
17
|
+
# @param str [String] syntax.
|
18
|
+
#
|
19
|
+
def initialize(str)
|
20
|
+
case str
|
21
|
+
when /\A(-([?\w]))\z/
|
22
|
+
setup(str, $1, nil, $1, $2, :short, nil, nil, nil, nil)
|
23
|
+
when /\A(-([?\w]))(?:( ?)\[|\[( ))(\w+)\]\z/
|
24
|
+
setup(str, $1, nil, $1, $2, :short, :value, :optional, $3 || $4, $5)
|
25
|
+
when /\A(-([?\w]))( ?)(\w+)\z/
|
26
|
+
setup(str, $1, nil, $1, $2, :short, :value, :required, $3, $4)
|
27
|
+
when /\A--\[no-\](\w[?\w-]*)\z/
|
28
|
+
setup(str, "--#{$1}", "--no-#{$1}", str, $1, :long, :boolean, nil, nil, nil)
|
29
|
+
when /\A(--(\w[?\w-]*))\z/
|
30
|
+
setup(str, $1, nil, $1, $2, :long, nil, nil, nil, nil)
|
31
|
+
when /\A(--(\w[?\w-]*))(?:([= ])\[|\[([= ]))(\w+)\]\z/
|
32
|
+
setup(str, $1, nil, $1, $2, :long, :value, :optional, $3 || $4, $5)
|
33
|
+
when /\A(--(\w[?\w-]*))([= ])(\w+)\z/
|
34
|
+
setup(str, $1, nil, $1, $2, :long, :value, :required, $3, $4)
|
35
|
+
else
|
36
|
+
raise ToolDefinitionError, "Illegal flag: #{str.inspect}"
|
37
|
+
end
|
38
|
+
end
|
39
|
+
|
40
|
+
# rubocop:enable Style/PerlBackrefs
|
41
|
+
|
42
|
+
##
|
43
|
+
# The original string that was parsed to produce this syntax.
|
44
|
+
# @return [String]
|
45
|
+
#
|
46
|
+
attr_reader :original_str
|
47
|
+
|
48
|
+
##
|
49
|
+
# The flags (without values) corresponding to this syntax.
|
50
|
+
# @return [Array<String>]
|
51
|
+
#
|
52
|
+
attr_reader :flags
|
53
|
+
|
54
|
+
##
|
55
|
+
# The flag (without values) corresponding to the normal "positive" form
|
56
|
+
# of this flag.
|
57
|
+
# @return [String]
|
58
|
+
#
|
59
|
+
attr_reader :positive_flag
|
60
|
+
|
61
|
+
##
|
62
|
+
# The flag (without values) corresponding to the "negative" form of this
|
63
|
+
# flag, if any. i.e. if the original string was `"--[no-]abc"`, the
|
64
|
+
# negative flag is `"--no-abc"`.
|
65
|
+
# @return [String] The negative form.
|
66
|
+
# @return [nil] if the flag has no negative form.
|
67
|
+
#
|
68
|
+
attr_reader :negative_flag
|
69
|
+
|
70
|
+
##
|
71
|
+
# The original string with the value (if any) stripped, but retaining
|
72
|
+
# the `[no-]` prefix if present.
|
73
|
+
# @return [String]
|
74
|
+
#
|
75
|
+
attr_reader :str_without_value
|
76
|
+
|
77
|
+
##
|
78
|
+
# A string used to sort this flag compared with others.
|
79
|
+
# @return [String]
|
80
|
+
#
|
81
|
+
attr_reader :sort_str
|
82
|
+
|
83
|
+
##
|
84
|
+
# The style of flag (`:long` or `:short`).
|
85
|
+
# @return [:long] if this is a long flag (i.e. double hyphen)
|
86
|
+
# @return [:short] if this is a short flag (i.e. single hyphen with one
|
87
|
+
# character).
|
88
|
+
#
|
89
|
+
attr_reader :flag_style
|
90
|
+
|
91
|
+
##
|
92
|
+
# The type of flag (`:boolean` or `:value`)
|
93
|
+
# @return [:boolean] if this is a boolean flag (i.e. no value)
|
94
|
+
# @return [:value] if this flag takes a value (even if optional)
|
95
|
+
#
|
96
|
+
attr_reader :flag_type
|
97
|
+
|
98
|
+
##
|
99
|
+
# The type of value (`:required` or `:optional`)
|
100
|
+
# @return [:required] if this flag takes a required value
|
101
|
+
# @return [:optional] if this flag takes an optional value
|
102
|
+
# @return [nil] if this flag is a boolean flag
|
103
|
+
#
|
104
|
+
attr_reader :value_type
|
105
|
+
|
106
|
+
##
|
107
|
+
# The default delimiter used for the value of this flag. This could be
|
108
|
+
# `""` or `" "` for a short flag, or `" "` or `"="` for a long flag.
|
109
|
+
# @return [String] delimiter
|
110
|
+
# @return [nil] if this flag is a boolean flag
|
111
|
+
#
|
112
|
+
attr_reader :value_delim
|
113
|
+
|
114
|
+
##
|
115
|
+
# The default "label" for the value. e.g. in `--abc=VAL` the label is
|
116
|
+
# `"VAL"`.
|
117
|
+
# @return [String] the label
|
118
|
+
# @return [nil] if this flag is a boolean flag
|
119
|
+
#
|
120
|
+
attr_reader :value_label
|
121
|
+
|
122
|
+
##
|
123
|
+
# A canonical string representing this flag's syntax, normalized to match
|
124
|
+
# the type, delimiters, etc. settings of other flag syntaxes. This is
|
125
|
+
# generally used in help strings to represent this flag.
|
126
|
+
# @return [String]
|
127
|
+
#
|
128
|
+
attr_reader :canonical_str
|
129
|
+
|
130
|
+
##
|
131
|
+
# @private
|
132
|
+
#
|
133
|
+
def configure_canonical(canonical_flag_type, canonical_value_type,
|
134
|
+
canonical_value_label, canonical_value_delim)
|
135
|
+
return unless flag_type.nil?
|
136
|
+
@flag_type = canonical_flag_type
|
137
|
+
return unless canonical_flag_type == :value
|
138
|
+
@value_type = canonical_value_type
|
139
|
+
canonical_value_delim = "" if canonical_value_delim == "=" && flag_style == :short
|
140
|
+
canonical_value_delim = "=" if canonical_value_delim == "" && flag_style == :long
|
141
|
+
@value_delim = canonical_value_delim
|
142
|
+
@value_label = canonical_value_label
|
143
|
+
label = @value_type == :optional ? "[#{@value_label}]" : @value_label
|
144
|
+
@canonical_str = "#{str_without_value}#{@value_delim}#{label}"
|
145
|
+
end
|
146
|
+
|
147
|
+
private
|
148
|
+
|
149
|
+
def setup(original_str, positive_flag, negative_flag, str_without_value, sort_str,
|
150
|
+
flag_style, flag_type, value_type, value_delim, value_label)
|
151
|
+
@original_str = original_str
|
152
|
+
@positive_flag = positive_flag
|
153
|
+
@negative_flag = negative_flag
|
154
|
+
@flags = [positive_flag]
|
155
|
+
@flags << negative_flag if negative_flag
|
156
|
+
@str_without_value = str_without_value
|
157
|
+
@sort_str = sort_str
|
158
|
+
@flag_style = flag_style
|
159
|
+
@flag_type = flag_type
|
160
|
+
@value_type = value_type
|
161
|
+
@value_delim = value_delim
|
162
|
+
@value_label = value_label ? value_label.upcase : value_label
|
163
|
+
@canonical_str = original_str
|
164
|
+
end
|
165
|
+
end
|
166
|
+
|
167
|
+
##
|
168
|
+
# The result of looking up a flag by name.
|
169
|
+
#
|
170
|
+
class Resolution
|
171
|
+
##
|
172
|
+
# @private
|
173
|
+
#
|
174
|
+
def initialize(str)
|
175
|
+
@string = str
|
176
|
+
@flags = []
|
177
|
+
@found_exact = false
|
178
|
+
end
|
179
|
+
|
180
|
+
##
|
181
|
+
# The flag string that was looked up
|
182
|
+
# @return [String]
|
183
|
+
#
|
184
|
+
attr_reader :string
|
185
|
+
|
186
|
+
##
|
187
|
+
# Whether an exact match of the string was found
|
188
|
+
# @return [Boolean]
|
189
|
+
#
|
190
|
+
def found_exact?
|
191
|
+
@found_exact
|
192
|
+
end
|
193
|
+
|
194
|
+
##
|
195
|
+
# The number of matches that were found.
|
196
|
+
# @return [Integer]
|
197
|
+
#
|
198
|
+
def count
|
199
|
+
@flags.size
|
200
|
+
end
|
201
|
+
|
202
|
+
##
|
203
|
+
# Whether a single unique match was found.
|
204
|
+
# @return [Boolean]
|
205
|
+
#
|
206
|
+
def found_unique?
|
207
|
+
@flags.size == 1
|
208
|
+
end
|
209
|
+
|
210
|
+
##
|
211
|
+
# Whether no matches were found.
|
212
|
+
# @return [Boolean]
|
213
|
+
#
|
214
|
+
def not_found?
|
215
|
+
@flags.empty?
|
216
|
+
end
|
217
|
+
|
218
|
+
##
|
219
|
+
# Whether multiple matches were found (i.e. ambiguous input).
|
220
|
+
# @return [Boolean]
|
221
|
+
#
|
222
|
+
def found_multiple?
|
223
|
+
@flags.size > 1
|
224
|
+
end
|
225
|
+
|
226
|
+
##
|
227
|
+
# Return the unique {Toys::Flag}, or `nil` if not found or
|
228
|
+
# not unique.
|
229
|
+
# @return [Toys::Flag,nil]
|
230
|
+
#
|
231
|
+
def unique_flag
|
232
|
+
found_unique? ? @flags.first[0] : nil
|
233
|
+
end
|
234
|
+
|
235
|
+
##
|
236
|
+
# Return the unique {Toys::Flag::Syntax}, or `nil` if not found
|
237
|
+
# or not unique.
|
238
|
+
# @return [Toys::Flag::Syntax,nil]
|
239
|
+
#
|
240
|
+
def unique_flag_syntax
|
241
|
+
found_unique? ? @flags.first[1] : nil
|
242
|
+
end
|
243
|
+
|
244
|
+
##
|
245
|
+
# Return whether the unique match was a hit on the negative (`--no-*`)
|
246
|
+
# case, or `nil` if not found or not unique.
|
247
|
+
# @return [Boolean,nil]
|
248
|
+
#
|
249
|
+
def unique_flag_negative?
|
250
|
+
found_unique? ? @flags.first[2] : nil
|
251
|
+
end
|
252
|
+
|
253
|
+
##
|
254
|
+
# Returns an array of the matching full flag strings.
|
255
|
+
# @return [Array<String>]
|
256
|
+
#
|
257
|
+
def matching_flag_strings
|
258
|
+
@flags.map do |_flag, flag_syntax, negative|
|
259
|
+
negative ? flag_syntax.negative_flag : flag_syntax.positive_flag
|
260
|
+
end
|
261
|
+
end
|
262
|
+
|
263
|
+
##
|
264
|
+
# @private
|
265
|
+
#
|
266
|
+
def add!(flag, flag_syntax, negative, exact)
|
267
|
+
@flags = [] if exact && !found_exact?
|
268
|
+
if exact || !found_exact?
|
269
|
+
@flags << [flag, flag_syntax, negative]
|
270
|
+
@found_exact = exact
|
271
|
+
end
|
272
|
+
self
|
273
|
+
end
|
274
|
+
|
275
|
+
##
|
276
|
+
# @private
|
277
|
+
#
|
278
|
+
def merge!(other)
|
279
|
+
raise "String mismatch" unless string == other.string
|
280
|
+
other.instance_variable_get(:@flags).each do |flag, flag_syntax, negative|
|
281
|
+
add!(flag, flag_syntax, negative, other.found_exact?)
|
282
|
+
end
|
283
|
+
self
|
284
|
+
end
|
285
|
+
end
|
286
|
+
|
287
|
+
##
|
288
|
+
# A Completion that returns all possible flags associated with a
|
289
|
+
# {Toys::Flag}.
|
290
|
+
#
|
291
|
+
class DefaultCompletion < Completion::Base
|
292
|
+
##
|
293
|
+
# Create a completion given configuration options.
|
294
|
+
#
|
295
|
+
# @param flag [Toys::Flag] The flag definition.
|
296
|
+
# @param include_short [Boolean] Whether to include short flags.
|
297
|
+
# @param include_long [Boolean] Whether to include long flags.
|
298
|
+
# @param include_negative [Boolean] Whether to include `--no-*` forms.
|
299
|
+
#
|
300
|
+
def initialize(flag:, include_short: true, include_long: true, include_negative: true)
|
301
|
+
super()
|
302
|
+
@flag = flag
|
303
|
+
@include_short = include_short
|
304
|
+
@include_long = include_long
|
305
|
+
@include_negative = include_negative
|
306
|
+
end
|
307
|
+
|
308
|
+
##
|
309
|
+
# Whether to include short flags
|
310
|
+
# @return [Boolean]
|
311
|
+
#
|
312
|
+
def include_short?
|
313
|
+
@include_short
|
314
|
+
end
|
315
|
+
|
316
|
+
##
|
317
|
+
# Whether to include long flags
|
318
|
+
# @return [Boolean]
|
319
|
+
#
|
320
|
+
def include_long?
|
321
|
+
@include_long
|
322
|
+
end
|
323
|
+
|
324
|
+
##
|
325
|
+
# Whether to include negative long flags
|
326
|
+
# @return [Boolean]
|
327
|
+
#
|
328
|
+
def include_negative?
|
329
|
+
@include_negative
|
330
|
+
end
|
331
|
+
|
332
|
+
##
|
333
|
+
# Returns candidates for the current completion.
|
334
|
+
#
|
335
|
+
# @param context [Toys::Completion::Context] the current completion
|
336
|
+
# context including the string fragment.
|
337
|
+
# @return [Array<Toys::Completion::Candidate>] an array of candidates
|
338
|
+
#
|
339
|
+
def call(context)
|
340
|
+
results =
|
341
|
+
if @include_short && @include_long && @include_negative
|
342
|
+
@flag.effective_flags
|
343
|
+
else
|
344
|
+
collect_results
|
345
|
+
end
|
346
|
+
fragment = context.fragment
|
347
|
+
results.find_all { |val| val.start_with?(fragment) }
|
348
|
+
.map { |str| Completion::Candidate.new(str) }
|
349
|
+
end
|
350
|
+
|
351
|
+
private
|
352
|
+
|
353
|
+
def collect_results
|
354
|
+
results = []
|
355
|
+
if @include_short
|
356
|
+
results += @flag.short_flag_syntax.map(&:positive_flag)
|
357
|
+
end
|
358
|
+
if @include_long
|
359
|
+
results +=
|
360
|
+
if @include_negative
|
361
|
+
@flag.long_flag_syntax.flat_map(&:flags)
|
362
|
+
else
|
363
|
+
@flag.long_flag_syntax.map(&:positive_flag)
|
364
|
+
end
|
365
|
+
end
|
366
|
+
results
|
367
|
+
end
|
368
|
+
end
|
369
|
+
|
9
370
|
##
|
10
371
|
# The set handler replaces the previous value.
|
11
372
|
# @return [Proc]
|
@@ -24,30 +385,6 @@ module Toys
|
|
24
385
|
#
|
25
386
|
DEFAULT_HANDLER = SET_HANDLER
|
26
387
|
|
27
|
-
##
|
28
|
-
# Create a Flag definition.
|
29
|
-
# This argument list is subject to change. Use {Toys::Flag.create} instead
|
30
|
-
# for a more stable interface.
|
31
|
-
# @private
|
32
|
-
#
|
33
|
-
def initialize(key, flags, used_flags, report_collisions, acceptor, handler, default,
|
34
|
-
flag_completion, value_completion, desc, long_desc, display_name, group)
|
35
|
-
@group = group
|
36
|
-
@key = key
|
37
|
-
@flag_syntax = Array(flags).map { |s| Syntax.new(s) }
|
38
|
-
@acceptor = Acceptor.create(acceptor)
|
39
|
-
@handler = resolve_handler(handler)
|
40
|
-
@desc = WrappableString.make(desc)
|
41
|
-
@long_desc = WrappableString.make_array(long_desc)
|
42
|
-
@default = default
|
43
|
-
@flag_completion = create_flag_completion(flag_completion)
|
44
|
-
@value_completion = Completion.create(value_completion, **{})
|
45
|
-
create_default_flag if @flag_syntax.empty?
|
46
|
-
remove_used_flags(used_flags, report_collisions)
|
47
|
-
canonicalize
|
48
|
-
summarize(display_name)
|
49
|
-
end
|
50
|
-
|
51
388
|
##
|
52
389
|
# Create a flag definition.
|
53
390
|
#
|
@@ -103,697 +440,369 @@ module Toys
|
|
103
440
|
end
|
104
441
|
|
105
442
|
##
|
106
|
-
# Returns the flag group containing this flag
|
107
|
-
# @return [Toys::FlagGroup]
|
108
|
-
#
|
109
|
-
attr_reader :group
|
110
|
-
|
111
|
-
##
|
112
|
-
# Returns the key.
|
113
|
-
# @return [Symbol]
|
114
|
-
#
|
115
|
-
attr_reader :key
|
116
|
-
|
117
|
-
##
|
118
|
-
# Returns an array of Flag::Syntax for the flags.
|
119
|
-
# @return [Array<Toys::Flag::Syntax>]
|
120
|
-
#
|
121
|
-
attr_reader :flag_syntax
|
122
|
-
|
123
|
-
##
|
124
|
-
# Returns the effective acceptor.
|
125
|
-
# @return [Toys::Acceptor::Base]
|
126
|
-
#
|
127
|
-
attr_reader :acceptor
|
128
|
-
|
129
|
-
##
|
130
|
-
# Returns the default value, which may be `nil`.
|
131
|
-
# @return [Object]
|
132
|
-
#
|
133
|
-
attr_reader :default
|
134
|
-
|
135
|
-
##
|
136
|
-
# The short description string.
|
137
|
-
#
|
138
|
-
# When reading, this is always returned as a {Toys::WrappableString}.
|
139
|
-
#
|
140
|
-
# When setting, the description may be provided as any of the following:
|
141
|
-
# * A {Toys::WrappableString}.
|
142
|
-
# * A normal String, which will be transformed into a
|
143
|
-
# {Toys::WrappableString} using spaces as word delimiters.
|
144
|
-
# * An Array of String, which will be transformed into a
|
145
|
-
# {Toys::WrappableString} where each array element represents an
|
146
|
-
# individual word for wrapping.
|
147
|
-
#
|
148
|
-
# @return [Toys::WrappableString]
|
149
|
-
#
|
150
|
-
attr_reader :desc
|
151
|
-
|
152
|
-
##
|
153
|
-
# The long description strings.
|
154
|
-
#
|
155
|
-
# When reading, this is returned as an Array of {Toys::WrappableString}
|
156
|
-
# representing the lines in the description.
|
157
|
-
#
|
158
|
-
# When setting, the description must be provided as an Array where *each
|
159
|
-
# element* may be any of the following:
|
160
|
-
# * A {Toys::WrappableString} representing one line.
|
161
|
-
# * A normal String representing a line. This will be transformed into a
|
162
|
-
# {Toys::WrappableString} using spaces as word delimiters.
|
163
|
-
# * An Array of String representing a line. This will be transformed into
|
164
|
-
# a {Toys::WrappableString} where each array element represents an
|
165
|
-
# individual word for wrapping.
|
166
|
-
#
|
167
|
-
# @return [Array<Toys::WrappableString>]
|
168
|
-
#
|
169
|
-
attr_reader :long_desc
|
170
|
-
|
171
|
-
##
|
172
|
-
# The handler for setting/updating the value.
|
173
|
-
# @return [Proc]
|
174
|
-
#
|
175
|
-
attr_reader :handler
|
176
|
-
|
177
|
-
##
|
178
|
-
# The proc that determines shell completions for the flag.
|
179
|
-
# @return [Proc,Toys::Completion::Base]
|
180
|
-
#
|
181
|
-
attr_reader :flag_completion
|
182
|
-
|
183
|
-
##
|
184
|
-
# The proc that determines shell completions for the value.
|
185
|
-
# @return [Proc,Toys::Completion::Base]
|
186
|
-
#
|
187
|
-
attr_reader :value_completion
|
188
|
-
|
189
|
-
##
|
190
|
-
# The type of flag.
|
191
|
-
#
|
192
|
-
# @return [:boolean] if the flag is a simple boolean switch
|
193
|
-
# @return [:value] if the flag sets a value
|
194
|
-
#
|
195
|
-
attr_reader :flag_type
|
196
|
-
|
197
|
-
##
|
198
|
-
# The type of value.
|
199
|
-
#
|
200
|
-
# @return [:required] if the flag type is `:value` and the value is
|
201
|
-
# required.
|
202
|
-
# @return [:optional] if the flag type is `:value` and the value is
|
203
|
-
# optional.
|
204
|
-
# @return [nil] if the flag type is not `:value`.
|
205
|
-
#
|
206
|
-
attr_reader :value_type
|
207
|
-
|
208
|
-
##
|
209
|
-
# The string label for the value as it should display in help.
|
210
|
-
# @return [String] The label
|
211
|
-
# @return [nil] if the flag type is not `:value`.
|
212
|
-
#
|
213
|
-
attr_reader :value_label
|
214
|
-
|
215
|
-
##
|
216
|
-
# The value delimiter, which may be `""`, `" "`, or `"="`.
|
217
|
-
#
|
218
|
-
# @return [String] The delimiter
|
219
|
-
# @return [nil] if the flag type is not `:value`.
|
220
|
-
#
|
221
|
-
attr_reader :value_delim
|
222
|
-
|
223
|
-
##
|
224
|
-
# The display name of this flag.
|
225
|
-
# @return [String]
|
226
|
-
#
|
227
|
-
attr_reader :display_name
|
228
|
-
|
229
|
-
##
|
230
|
-
# A string that can be used to sort this flag
|
231
|
-
# @return [String]
|
232
|
-
#
|
233
|
-
attr_reader :sort_str
|
234
|
-
|
235
|
-
##
|
236
|
-
# An array of Flag::Syntax including only short (single dash) flags.
|
237
|
-
# @return [Array<Flag::Syntax>]
|
238
|
-
#
|
239
|
-
def short_flag_syntax
|
240
|
-
@short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short }
|
241
|
-
end
|
242
|
-
|
243
|
-
##
|
244
|
-
# An array of Flag::Syntax including only long (double-dash) flags.
|
245
|
-
# @return [Array<Flag::Syntax>]
|
246
|
-
#
|
247
|
-
def long_flag_syntax
|
248
|
-
@long_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :long }
|
249
|
-
end
|
250
|
-
|
251
|
-
##
|
252
|
-
# The list of all effective flags used.
|
253
|
-
# @return [Array<String>]
|
254
|
-
#
|
255
|
-
def effective_flags
|
256
|
-
@effective_flags ||= flag_syntax.flat_map(&:flags)
|
257
|
-
end
|
258
|
-
|
259
|
-
##
|
260
|
-
# Look up the flag by string. Returns an object that indicates whether
|
261
|
-
# the given string matched this flag, whether the match was unique, and
|
262
|
-
# other pertinent information.
|
263
|
-
#
|
264
|
-
# @param str [String] Flag string to look up
|
265
|
-
# @return [Toys::Flag::Resolution] Information about the match.
|
443
|
+
# Returns the flag group containing this flag
|
444
|
+
# @return [Toys::FlagGroup]
|
266
445
|
#
|
267
|
-
|
268
|
-
resolution = Resolution.new(str)
|
269
|
-
flag_syntax.each do |fs|
|
270
|
-
if fs.positive_flag == str
|
271
|
-
resolution.add!(self, fs, false, true)
|
272
|
-
elsif fs.negative_flag == str
|
273
|
-
resolution.add!(self, fs, true, true)
|
274
|
-
elsif fs.positive_flag.start_with?(str)
|
275
|
-
resolution.add!(self, fs, false, false)
|
276
|
-
elsif fs.negative_flag.to_s.start_with?(str)
|
277
|
-
resolution.add!(self, fs, true, false)
|
278
|
-
end
|
279
|
-
end
|
280
|
-
resolution
|
281
|
-
end
|
446
|
+
attr_reader :group
|
282
447
|
|
283
448
|
##
|
284
|
-
#
|
285
|
-
#
|
286
|
-
# @return [Array<String>]
|
449
|
+
# Returns the key.
|
450
|
+
# @return [Symbol]
|
287
451
|
#
|
288
|
-
|
289
|
-
@canonical_syntax_strings ||= flag_syntax.map(&:canonical_str)
|
290
|
-
end
|
452
|
+
attr_reader :key
|
291
453
|
|
292
454
|
##
|
293
|
-
#
|
294
|
-
#
|
295
|
-
# @return [Boolean]
|
455
|
+
# Returns an array of Flag::Syntax for the flags.
|
456
|
+
# @return [Array<Toys::Flag::Syntax>]
|
296
457
|
#
|
297
|
-
|
298
|
-
!effective_flags.empty?
|
299
|
-
end
|
458
|
+
attr_reader :flag_syntax
|
300
459
|
|
301
460
|
##
|
302
|
-
#
|
303
|
-
#
|
304
|
-
# See {#desc} for details.
|
305
|
-
#
|
306
|
-
# @param desc [Toys::WrappableString,String,Array<String>]
|
461
|
+
# Returns the effective acceptor.
|
462
|
+
# @return [Toys::Acceptor::Base]
|
307
463
|
#
|
308
|
-
|
309
|
-
@desc = WrappableString.make(desc)
|
310
|
-
end
|
464
|
+
attr_reader :acceptor
|
311
465
|
|
312
466
|
##
|
313
|
-
#
|
314
|
-
#
|
315
|
-
# See {#long_desc} for details.
|
316
|
-
#
|
317
|
-
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
467
|
+
# Returns the default value, which may be `nil`.
|
468
|
+
# @return [Object]
|
318
469
|
#
|
319
|
-
|
320
|
-
@long_desc = WrappableString.make_array(long_desc)
|
321
|
-
end
|
470
|
+
attr_reader :default
|
322
471
|
|
323
472
|
##
|
324
|
-
#
|
473
|
+
# The short description string.
|
325
474
|
#
|
326
|
-
#
|
327
|
-
# for details on how each line may be represented.
|
475
|
+
# When reading, this is always returned as a {Toys::WrappableString}.
|
328
476
|
#
|
329
|
-
#
|
330
|
-
#
|
477
|
+
# When setting, the description may be provided as any of the following:
|
478
|
+
# * A {Toys::WrappableString}.
|
479
|
+
# * A normal String, which will be transformed into a
|
480
|
+
# {Toys::WrappableString} using spaces as word delimiters.
|
481
|
+
# * An Array of String, which will be transformed into a
|
482
|
+
# {Toys::WrappableString} where each array element represents an
|
483
|
+
# individual word for wrapping.
|
331
484
|
#
|
332
|
-
|
333
|
-
|
334
|
-
|
335
|
-
end
|
336
|
-
|
337
|
-
private
|
338
|
-
|
339
|
-
def resolve_handler(handler)
|
340
|
-
case handler
|
341
|
-
when ::Proc
|
342
|
-
handler
|
343
|
-
when nil, :default
|
344
|
-
DEFAULT_HANDLER
|
345
|
-
when :set
|
346
|
-
SET_HANDLER
|
347
|
-
when :push, :append
|
348
|
-
PUSH_HANDLER
|
349
|
-
else
|
350
|
-
raise ToolDefinitionError, "Unknown handler: #{handler.inspect}"
|
351
|
-
end
|
352
|
-
end
|
353
|
-
|
354
|
-
def create_flag_completion(spec)
|
355
|
-
spec =
|
356
|
-
case spec
|
357
|
-
when nil, :default
|
358
|
-
{"": DefaultCompletion, flag: self}
|
359
|
-
when ::Hash
|
360
|
-
spec[:""].nil? ? spec.merge({"": DefaultCompletion, flag: self}) : spec
|
361
|
-
else
|
362
|
-
spec
|
363
|
-
end
|
364
|
-
Completion.create(spec, **{})
|
365
|
-
end
|
366
|
-
|
367
|
-
def create_default_flag
|
368
|
-
key_str = key.to_s
|
369
|
-
flag_str =
|
370
|
-
if key_str.length == 1
|
371
|
-
"-#{key_str}" if key_str =~ /[a-zA-Z0-9?]/
|
372
|
-
elsif key_str.length > 1
|
373
|
-
key_str = key_str.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "").sub(/^-+/, "")
|
374
|
-
"--#{key_str}" unless key_str.empty?
|
375
|
-
end
|
376
|
-
if flag_str
|
377
|
-
needs_val = @value_completion != Completion::EMPTY ||
|
378
|
-
![::Object, ::TrueClass, ::FalseClass].include?(@acceptor.well_known_spec) ||
|
379
|
-
![nil, true, false].include?(@default)
|
380
|
-
flag_str = "#{flag_str} VALUE" if needs_val
|
381
|
-
@flag_syntax << Syntax.new(flag_str)
|
382
|
-
end
|
383
|
-
end
|
384
|
-
|
385
|
-
def remove_used_flags(used_flags, report_collisions)
|
386
|
-
return if !used_flags && !report_collisions
|
387
|
-
@flag_syntax.select! do |fs|
|
388
|
-
fs.flags.all? do |f|
|
389
|
-
collision = used_flags&.include?(f)
|
390
|
-
if collision && report_collisions
|
391
|
-
raise ToolDefinitionError,
|
392
|
-
"Cannot use flag #{f.inspect} because it is already assigned or reserved."
|
393
|
-
end
|
394
|
-
!collision
|
395
|
-
end
|
396
|
-
end
|
397
|
-
used_flags&.concat(effective_flags.uniq)
|
398
|
-
end
|
399
|
-
|
400
|
-
def canonicalize
|
401
|
-
@flag_type = nil
|
402
|
-
@value_type = nil
|
403
|
-
@value_label = nil
|
404
|
-
@value_delim = " "
|
405
|
-
short_flag_syntax.reverse_each do |flag|
|
406
|
-
analyze_flag_syntax(flag)
|
407
|
-
end
|
408
|
-
long_flag_syntax.reverse_each do |flag|
|
409
|
-
analyze_flag_syntax(flag)
|
410
|
-
end
|
411
|
-
@flag_type ||= :boolean
|
412
|
-
@value_type ||= :required if @flag_type == :value
|
413
|
-
flag_syntax.each do |flag|
|
414
|
-
flag.configure_canonical(@flag_type, @value_type, @value_label, @value_delim)
|
415
|
-
end
|
416
|
-
end
|
417
|
-
|
418
|
-
def analyze_flag_syntax(flag)
|
419
|
-
return if flag.flag_type.nil?
|
420
|
-
if !@flag_type.nil? && @flag_type != flag.flag_type
|
421
|
-
raise ToolDefinitionError, "Cannot have both value and boolean flags for #{key.inspect}"
|
422
|
-
end
|
423
|
-
@flag_type = flag.flag_type
|
424
|
-
return unless @flag_type == :value
|
425
|
-
if !@value_type.nil? && @value_type != flag.value_type
|
426
|
-
raise ToolDefinitionError,
|
427
|
-
"Cannot have both required and optional values for flag #{key.inspect}"
|
428
|
-
end
|
429
|
-
@value_type = flag.value_type
|
430
|
-
@value_label = flag.value_label
|
431
|
-
@value_delim = flag.value_delim
|
432
|
-
end
|
433
|
-
|
434
|
-
def summarize(name)
|
435
|
-
@display_name =
|
436
|
-
name ||
|
437
|
-
long_flag_syntax.first&.canonical_str ||
|
438
|
-
short_flag_syntax.first&.canonical_str ||
|
439
|
-
key.to_s
|
440
|
-
@sort_str =
|
441
|
-
long_flag_syntax.first&.sort_str ||
|
442
|
-
short_flag_syntax.first&.sort_str ||
|
443
|
-
""
|
444
|
-
end
|
485
|
+
# @return [Toys::WrappableString]
|
486
|
+
#
|
487
|
+
attr_reader :desc
|
445
488
|
|
446
489
|
##
|
447
|
-
#
|
490
|
+
# The long description strings.
|
448
491
|
#
|
449
|
-
|
450
|
-
|
451
|
-
|
452
|
-
|
453
|
-
|
454
|
-
|
455
|
-
|
456
|
-
|
457
|
-
|
458
|
-
|
459
|
-
|
460
|
-
|
461
|
-
|
462
|
-
|
463
|
-
|
464
|
-
when /\A--\[no-\](\w[?\w-]*)\z/
|
465
|
-
setup(str, "--#{$1}", "--no-#{$1}", str, $1, :long, :boolean, nil, nil, nil)
|
466
|
-
when /\A(--(\w[?\w-]*))\z/
|
467
|
-
setup(str, $1, nil, $1, $2, :long, nil, nil, nil, nil)
|
468
|
-
when /\A(--(\w[?\w-]*))(?:([= ])\[|\[([= ]))(\w+)\]\z/
|
469
|
-
setup(str, $1, nil, $1, $2, :long, :value, :optional, $3 || $4, $5)
|
470
|
-
when /\A(--(\w[?\w-]*))([= ])(\w+)\z/
|
471
|
-
setup(str, $1, nil, $1, $2, :long, :value, :required, $3, $4)
|
472
|
-
else
|
473
|
-
raise ToolDefinitionError, "Illegal flag: #{str.inspect}"
|
474
|
-
end
|
475
|
-
end
|
476
|
-
|
477
|
-
# rubocop:enable Style/PerlBackrefs
|
478
|
-
|
479
|
-
##
|
480
|
-
# The original string that was parsed to produce this syntax.
|
481
|
-
# @return [String]
|
482
|
-
#
|
483
|
-
attr_reader :original_str
|
484
|
-
|
485
|
-
##
|
486
|
-
# The flags (without values) corresponding to this syntax.
|
487
|
-
# @return [Array<String>]
|
488
|
-
#
|
489
|
-
attr_reader :flags
|
490
|
-
|
491
|
-
##
|
492
|
-
# The flag (without values) corresponding to the normal "positive" form
|
493
|
-
# of this flag.
|
494
|
-
# @return [String]
|
495
|
-
#
|
496
|
-
attr_reader :positive_flag
|
492
|
+
# When reading, this is returned as an Array of {Toys::WrappableString}
|
493
|
+
# representing the lines in the description.
|
494
|
+
#
|
495
|
+
# When setting, the description must be provided as an Array where *each
|
496
|
+
# element* may be any of the following:
|
497
|
+
# * A {Toys::WrappableString} representing one line.
|
498
|
+
# * A normal String representing a line. This will be transformed into a
|
499
|
+
# {Toys::WrappableString} using spaces as word delimiters.
|
500
|
+
# * An Array of String representing a line. This will be transformed into
|
501
|
+
# a {Toys::WrappableString} where each array element represents an
|
502
|
+
# individual word for wrapping.
|
503
|
+
#
|
504
|
+
# @return [Array<Toys::WrappableString>]
|
505
|
+
#
|
506
|
+
attr_reader :long_desc
|
497
507
|
|
498
|
-
|
499
|
-
|
500
|
-
|
501
|
-
|
502
|
-
|
503
|
-
# @return [nil] if the flag has no negative form.
|
504
|
-
#
|
505
|
-
attr_reader :negative_flag
|
508
|
+
##
|
509
|
+
# The handler for setting/updating the value.
|
510
|
+
# @return [Proc]
|
511
|
+
#
|
512
|
+
attr_reader :handler
|
506
513
|
|
507
|
-
|
508
|
-
|
509
|
-
|
510
|
-
|
511
|
-
|
512
|
-
attr_reader :str_without_value
|
514
|
+
##
|
515
|
+
# The proc that determines shell completions for the flag.
|
516
|
+
# @return [Proc,Toys::Completion::Base]
|
517
|
+
#
|
518
|
+
attr_reader :flag_completion
|
513
519
|
|
514
|
-
|
515
|
-
|
516
|
-
|
517
|
-
|
518
|
-
|
520
|
+
##
|
521
|
+
# The proc that determines shell completions for the value.
|
522
|
+
# @return [Proc,Toys::Completion::Base]
|
523
|
+
#
|
524
|
+
attr_reader :value_completion
|
519
525
|
|
520
|
-
|
521
|
-
|
522
|
-
|
523
|
-
|
524
|
-
|
525
|
-
|
526
|
-
|
526
|
+
##
|
527
|
+
# The type of flag.
|
528
|
+
#
|
529
|
+
# @return [:boolean] if the flag is a simple boolean switch
|
530
|
+
# @return [:value] if the flag sets a value
|
531
|
+
#
|
532
|
+
attr_reader :flag_type
|
527
533
|
|
528
|
-
|
529
|
-
|
530
|
-
|
531
|
-
|
532
|
-
|
533
|
-
|
534
|
+
##
|
535
|
+
# The type of value.
|
536
|
+
#
|
537
|
+
# @return [:required] if the flag type is `:value` and the value is
|
538
|
+
# required.
|
539
|
+
# @return [:optional] if the flag type is `:value` and the value is
|
540
|
+
# optional.
|
541
|
+
# @return [nil] if the flag type is not `:value`.
|
542
|
+
#
|
543
|
+
attr_reader :value_type
|
534
544
|
|
535
|
-
|
536
|
-
|
537
|
-
|
538
|
-
|
539
|
-
|
540
|
-
|
541
|
-
attr_reader :value_type
|
545
|
+
##
|
546
|
+
# The string label for the value as it should display in help.
|
547
|
+
# @return [String] The label
|
548
|
+
# @return [nil] if the flag type is not `:value`.
|
549
|
+
#
|
550
|
+
attr_reader :value_label
|
542
551
|
|
543
|
-
|
544
|
-
|
545
|
-
|
546
|
-
|
547
|
-
|
548
|
-
|
549
|
-
|
552
|
+
##
|
553
|
+
# The value delimiter, which may be `""`, `" "`, or `"="`.
|
554
|
+
#
|
555
|
+
# @return [String] The delimiter
|
556
|
+
# @return [nil] if the flag type is not `:value`.
|
557
|
+
#
|
558
|
+
attr_reader :value_delim
|
550
559
|
|
551
|
-
|
552
|
-
|
553
|
-
|
554
|
-
|
555
|
-
|
556
|
-
#
|
557
|
-
attr_reader :value_label
|
560
|
+
##
|
561
|
+
# The display name of this flag.
|
562
|
+
# @return [String]
|
563
|
+
#
|
564
|
+
attr_reader :display_name
|
558
565
|
|
559
|
-
|
560
|
-
|
561
|
-
|
562
|
-
|
563
|
-
|
564
|
-
#
|
565
|
-
attr_reader :canonical_str
|
566
|
+
##
|
567
|
+
# A string that can be used to sort this flag
|
568
|
+
# @return [String]
|
569
|
+
#
|
570
|
+
attr_reader :sort_str
|
566
571
|
|
567
|
-
|
568
|
-
|
569
|
-
|
570
|
-
|
571
|
-
|
572
|
-
|
573
|
-
|
574
|
-
canonical_value_delim = "" if canonical_value_delim == "=" && flag_style == :short
|
575
|
-
canonical_value_delim = "=" if canonical_value_delim == "" && flag_style == :long
|
576
|
-
@value_delim = canonical_value_delim
|
577
|
-
@value_label = canonical_value_label
|
578
|
-
label = @value_type == :optional ? "[#{@value_label}]" : @value_label
|
579
|
-
@canonical_str = "#{str_without_value}#{@value_delim}#{label}"
|
580
|
-
end
|
572
|
+
##
|
573
|
+
# An array of Flag::Syntax including only short (single dash) flags.
|
574
|
+
# @return [Array<Flag::Syntax>]
|
575
|
+
#
|
576
|
+
def short_flag_syntax
|
577
|
+
@short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short }
|
578
|
+
end
|
581
579
|
|
582
|
-
|
580
|
+
##
|
581
|
+
# An array of Flag::Syntax including only long (double-dash) flags.
|
582
|
+
# @return [Array<Flag::Syntax>]
|
583
|
+
#
|
584
|
+
def long_flag_syntax
|
585
|
+
@long_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :long }
|
586
|
+
end
|
583
587
|
|
584
|
-
|
585
|
-
|
586
|
-
|
587
|
-
|
588
|
-
|
589
|
-
|
590
|
-
@flags << negative_flag if negative_flag
|
591
|
-
@str_without_value = str_without_value
|
592
|
-
@sort_str = sort_str
|
593
|
-
@flag_style = flag_style
|
594
|
-
@flag_type = flag_type
|
595
|
-
@value_type = value_type
|
596
|
-
@value_delim = value_delim
|
597
|
-
@value_label = value_label ? value_label.upcase : value_label
|
598
|
-
@canonical_str = original_str
|
599
|
-
end
|
588
|
+
##
|
589
|
+
# The list of all effective flags used.
|
590
|
+
# @return [Array<String>]
|
591
|
+
#
|
592
|
+
def effective_flags
|
593
|
+
@effective_flags ||= flag_syntax.flat_map(&:flags)
|
600
594
|
end
|
601
595
|
|
602
596
|
##
|
603
|
-
#
|
597
|
+
# Look up the flag by string. Returns an object that indicates whether
|
598
|
+
# the given string matched this flag, whether the match was unique, and
|
599
|
+
# other pertinent information.
|
604
600
|
#
|
605
|
-
|
606
|
-
|
607
|
-
|
608
|
-
|
609
|
-
|
610
|
-
|
601
|
+
# @param str [String] Flag string to look up
|
602
|
+
# @return [Toys::Flag::Resolution] Information about the match.
|
603
|
+
#
|
604
|
+
def resolve(str)
|
605
|
+
resolution = Resolution.new(str)
|
606
|
+
flag_syntax.each do |fs|
|
607
|
+
if fs.positive_flag == str
|
608
|
+
resolution.add!(self, fs, false, true)
|
609
|
+
elsif fs.negative_flag == str
|
610
|
+
resolution.add!(self, fs, true, true)
|
611
|
+
elsif fs.positive_flag.start_with?(str)
|
612
|
+
resolution.add!(self, fs, false, false)
|
613
|
+
elsif fs.negative_flag.to_s.start_with?(str)
|
614
|
+
resolution.add!(self, fs, true, false)
|
615
|
+
end
|
611
616
|
end
|
617
|
+
resolution
|
618
|
+
end
|
612
619
|
|
613
|
-
|
614
|
-
|
615
|
-
|
616
|
-
|
617
|
-
|
618
|
-
|
619
|
-
|
620
|
-
|
621
|
-
# @return [Boolean]
|
622
|
-
#
|
623
|
-
def found_exact?
|
624
|
-
@found_exact
|
625
|
-
end
|
620
|
+
##
|
621
|
+
# A list of canonical flag syntax strings.
|
622
|
+
#
|
623
|
+
# @return [Array<String>]
|
624
|
+
#
|
625
|
+
def canonical_syntax_strings
|
626
|
+
@canonical_syntax_strings ||= flag_syntax.map(&:canonical_str)
|
627
|
+
end
|
626
628
|
|
627
|
-
|
628
|
-
|
629
|
-
|
630
|
-
|
631
|
-
|
632
|
-
|
633
|
-
|
629
|
+
##
|
630
|
+
# Whether this flag is active--that is, it has a nonempty flags list.
|
631
|
+
#
|
632
|
+
# @return [Boolean]
|
633
|
+
#
|
634
|
+
def active?
|
635
|
+
!effective_flags.empty?
|
636
|
+
end
|
634
637
|
|
635
|
-
|
636
|
-
|
637
|
-
|
638
|
-
|
639
|
-
|
640
|
-
|
641
|
-
|
638
|
+
##
|
639
|
+
# Set the short description string.
|
640
|
+
#
|
641
|
+
# See {#desc} for details.
|
642
|
+
#
|
643
|
+
# @param desc [Toys::WrappableString,String,Array<String>]
|
644
|
+
#
|
645
|
+
def desc=(desc)
|
646
|
+
@desc = WrappableString.make(desc)
|
647
|
+
end
|
642
648
|
|
643
|
-
|
644
|
-
|
645
|
-
|
646
|
-
|
647
|
-
|
648
|
-
|
649
|
-
|
649
|
+
##
|
650
|
+
# Set the long description strings.
|
651
|
+
#
|
652
|
+
# See {#long_desc} for details.
|
653
|
+
#
|
654
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
655
|
+
#
|
656
|
+
def long_desc=(long_desc)
|
657
|
+
@long_desc = WrappableString.make_array(long_desc)
|
658
|
+
end
|
650
659
|
|
651
|
-
|
652
|
-
|
653
|
-
|
654
|
-
|
655
|
-
|
656
|
-
|
657
|
-
|
660
|
+
##
|
661
|
+
# Append long description strings.
|
662
|
+
#
|
663
|
+
# You must pass an array of lines in the long description. See {#long_desc}
|
664
|
+
# for details on how each line may be represented.
|
665
|
+
#
|
666
|
+
# @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
|
667
|
+
# @return [self]
|
668
|
+
#
|
669
|
+
def append_long_desc(long_desc)
|
670
|
+
@long_desc.concat(WrappableString.make_array(long_desc))
|
671
|
+
self
|
672
|
+
end
|
658
673
|
|
659
|
-
|
660
|
-
|
661
|
-
|
662
|
-
|
663
|
-
|
664
|
-
|
665
|
-
|
666
|
-
|
674
|
+
##
|
675
|
+
# Create a Flag definition.
|
676
|
+
# This argument list is subject to change. Use {Toys::Flag.create} instead
|
677
|
+
# for a more stable interface.
|
678
|
+
#
|
679
|
+
# @private
|
680
|
+
#
|
681
|
+
def initialize(key, flags, used_flags, report_collisions, acceptor, handler, default,
|
682
|
+
flag_completion, value_completion, desc, long_desc, display_name, group)
|
683
|
+
@group = group
|
684
|
+
@key = key
|
685
|
+
@flag_syntax = Array(flags).map { |s| Syntax.new(s) }
|
686
|
+
@acceptor = Acceptor.create(acceptor)
|
687
|
+
@handler = resolve_handler(handler)
|
688
|
+
@desc = WrappableString.make(desc)
|
689
|
+
@long_desc = WrappableString.make_array(long_desc)
|
690
|
+
@default = default
|
691
|
+
@flag_completion = create_flag_completion(flag_completion)
|
692
|
+
@value_completion = Completion.create(value_completion, **{})
|
693
|
+
create_default_flag if @flag_syntax.empty?
|
694
|
+
remove_used_flags(used_flags, report_collisions)
|
695
|
+
canonicalize
|
696
|
+
summarize(display_name)
|
697
|
+
end
|
667
698
|
|
668
|
-
|
669
|
-
# Return the unique {Toys::Flag::Syntax}, or `nil` if not found
|
670
|
-
# or not unique.
|
671
|
-
# @return [Toys::Flag::Syntax,nil]
|
672
|
-
#
|
673
|
-
def unique_flag_syntax
|
674
|
-
found_unique? ? @flags.first[1] : nil
|
675
|
-
end
|
699
|
+
private
|
676
700
|
|
677
|
-
|
678
|
-
|
679
|
-
|
680
|
-
|
681
|
-
|
682
|
-
|
683
|
-
|
701
|
+
def resolve_handler(handler)
|
702
|
+
case handler
|
703
|
+
when ::Proc
|
704
|
+
handler
|
705
|
+
when nil, :default
|
706
|
+
DEFAULT_HANDLER
|
707
|
+
when :set
|
708
|
+
SET_HANDLER
|
709
|
+
when :push, :append
|
710
|
+
PUSH_HANDLER
|
711
|
+
else
|
712
|
+
raise ToolDefinitionError, "Unknown handler: #{handler.inspect}"
|
684
713
|
end
|
714
|
+
end
|
685
715
|
|
686
|
-
|
687
|
-
|
688
|
-
|
689
|
-
|
690
|
-
|
691
|
-
|
692
|
-
|
716
|
+
def create_flag_completion(spec)
|
717
|
+
spec =
|
718
|
+
case spec
|
719
|
+
when nil, :default
|
720
|
+
{"": DefaultCompletion, flag: self}
|
721
|
+
when ::Hash
|
722
|
+
spec[:""].nil? ? spec.merge({"": DefaultCompletion, flag: self}) : spec
|
723
|
+
else
|
724
|
+
spec
|
693
725
|
end
|
694
|
-
|
726
|
+
Completion.create(spec, **{})
|
727
|
+
end
|
695
728
|
|
696
|
-
|
697
|
-
|
698
|
-
|
699
|
-
if
|
700
|
-
|
701
|
-
|
729
|
+
def create_default_flag
|
730
|
+
key_str = key.to_s
|
731
|
+
flag_str =
|
732
|
+
if key_str.length == 1
|
733
|
+
"-#{key_str}" if key_str =~ /[a-zA-Z0-9?]/
|
734
|
+
elsif key_str.length > 1
|
735
|
+
key_str = key_str.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "").sub(/^-+/, "")
|
736
|
+
"--#{key_str}" unless key_str.empty?
|
702
737
|
end
|
703
|
-
|
738
|
+
if flag_str
|
739
|
+
needs_val = @value_completion != Completion::EMPTY ||
|
740
|
+
![::Object, ::TrueClass, ::FalseClass].include?(@acceptor.well_known_spec) ||
|
741
|
+
![nil, true, false].include?(@default)
|
742
|
+
flag_str = "#{flag_str} VALUE" if needs_val
|
743
|
+
@flag_syntax << Syntax.new(flag_str)
|
704
744
|
end
|
745
|
+
end
|
705
746
|
|
706
|
-
|
707
|
-
|
708
|
-
|
709
|
-
|
710
|
-
|
747
|
+
def remove_used_flags(used_flags, report_collisions)
|
748
|
+
return if !used_flags && !report_collisions
|
749
|
+
@flag_syntax.select! do |fs|
|
750
|
+
fs.flags.all? do |f|
|
751
|
+
collision = used_flags&.include?(f)
|
752
|
+
if collision && report_collisions
|
753
|
+
raise ToolDefinitionError,
|
754
|
+
"Cannot use flag #{f.inspect} because it is already assigned or reserved."
|
755
|
+
end
|
756
|
+
!collision
|
711
757
|
end
|
712
|
-
self
|
713
758
|
end
|
759
|
+
used_flags&.concat(effective_flags.uniq)
|
714
760
|
end
|
715
761
|
|
716
|
-
|
717
|
-
|
718
|
-
|
719
|
-
|
720
|
-
|
721
|
-
|
722
|
-
|
723
|
-
#
|
724
|
-
# @param flag [Toys::Flag] The flag definition.
|
725
|
-
# @param include_short [Boolean] Whether to include short flags.
|
726
|
-
# @param include_long [Boolean] Whether to include long flags.
|
727
|
-
# @param include_negative [Boolean] Whether to include `--no-*` forms.
|
728
|
-
#
|
729
|
-
def initialize(flag:, include_short: true, include_long: true, include_negative: true)
|
730
|
-
super()
|
731
|
-
@flag = flag
|
732
|
-
@include_short = include_short
|
733
|
-
@include_long = include_long
|
734
|
-
@include_negative = include_negative
|
762
|
+
def canonicalize
|
763
|
+
@flag_type = nil
|
764
|
+
@value_type = nil
|
765
|
+
@value_label = nil
|
766
|
+
@value_delim = " "
|
767
|
+
short_flag_syntax.reverse_each do |flag|
|
768
|
+
analyze_flag_syntax(flag)
|
735
769
|
end
|
736
|
-
|
737
|
-
|
738
|
-
# Whether to include short flags
|
739
|
-
# @return [Boolean]
|
740
|
-
#
|
741
|
-
def include_short?
|
742
|
-
@include_short
|
770
|
+
long_flag_syntax.reverse_each do |flag|
|
771
|
+
analyze_flag_syntax(flag)
|
743
772
|
end
|
744
|
-
|
745
|
-
|
746
|
-
|
747
|
-
|
748
|
-
#
|
749
|
-
def include_long?
|
750
|
-
@include_long
|
773
|
+
@flag_type ||= :boolean
|
774
|
+
@value_type ||= :required if @flag_type == :value
|
775
|
+
flag_syntax.each do |flag|
|
776
|
+
flag.configure_canonical(@flag_type, @value_type, @value_label, @value_delim)
|
751
777
|
end
|
778
|
+
end
|
752
779
|
|
753
|
-
|
754
|
-
|
755
|
-
|
756
|
-
|
757
|
-
def include_negative?
|
758
|
-
@include_negative
|
780
|
+
def analyze_flag_syntax(flag)
|
781
|
+
return if flag.flag_type.nil?
|
782
|
+
if !@flag_type.nil? && @flag_type != flag.flag_type
|
783
|
+
raise ToolDefinitionError, "Cannot have both value and boolean flags for #{key.inspect}"
|
759
784
|
end
|
760
|
-
|
761
|
-
|
762
|
-
|
763
|
-
|
764
|
-
|
765
|
-
# context including the string fragment.
|
766
|
-
# @return [Array<Toys::Completion::Candidate>] an array of candidates
|
767
|
-
#
|
768
|
-
def call(context)
|
769
|
-
results =
|
770
|
-
if @include_short && @include_long && @include_negative
|
771
|
-
@flag.effective_flags
|
772
|
-
else
|
773
|
-
collect_results
|
774
|
-
end
|
775
|
-
fragment = context.fragment
|
776
|
-
results.find_all { |val| val.start_with?(fragment) }
|
777
|
-
.map { |str| Completion::Candidate.new(str) }
|
785
|
+
@flag_type = flag.flag_type
|
786
|
+
return unless @flag_type == :value
|
787
|
+
if !@value_type.nil? && @value_type != flag.value_type
|
788
|
+
raise ToolDefinitionError,
|
789
|
+
"Cannot have both required and optional values for flag #{key.inspect}"
|
778
790
|
end
|
791
|
+
@value_type = flag.value_type
|
792
|
+
@value_label = flag.value_label
|
793
|
+
@value_delim = flag.value_delim
|
794
|
+
end
|
779
795
|
|
780
|
-
|
781
|
-
|
782
|
-
|
783
|
-
|
784
|
-
|
785
|
-
|
786
|
-
|
787
|
-
|
788
|
-
|
789
|
-
|
790
|
-
@flag.long_flag_syntax.flat_map(&:flags)
|
791
|
-
else
|
792
|
-
@flag.long_flag_syntax.map(&:positive_flag)
|
793
|
-
end
|
794
|
-
end
|
795
|
-
results
|
796
|
-
end
|
796
|
+
def summarize(name)
|
797
|
+
@display_name =
|
798
|
+
name ||
|
799
|
+
long_flag_syntax.first&.canonical_str ||
|
800
|
+
short_flag_syntax.first&.canonical_str ||
|
801
|
+
key.to_s
|
802
|
+
@sort_str =
|
803
|
+
long_flag_syntax.first&.sort_str ||
|
804
|
+
short_flag_syntax.first&.sort_str ||
|
805
|
+
""
|
797
806
|
end
|
798
807
|
end
|
799
808
|
end
|