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.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +2 -0
  3. data/CHANGELOG.md +35 -0
  4. data/LICENSE.md +1 -1
  5. data/README.md +7 -4
  6. data/builtins/system/git-cache.rb +238 -0
  7. data/builtins/system/test.rb +37 -2
  8. data/core-docs/toys/acceptor.rb +432 -0
  9. data/core-docs/toys/arg_parser.rb +397 -0
  10. data/core-docs/toys/cli.rb +493 -0
  11. data/core-docs/toys/compat.rb +2 -0
  12. data/core-docs/toys/completion.rb +329 -0
  13. data/core-docs/toys/context.rb +321 -0
  14. data/core-docs/toys/core.rb +14 -0
  15. data/core-docs/toys/dsl/base.rb +56 -0
  16. data/core-docs/toys/dsl/flag.rb +261 -0
  17. data/core-docs/toys/dsl/flag_group.rb +259 -0
  18. data/core-docs/toys/dsl/internal.rb +4 -0
  19. data/core-docs/toys/dsl/positional_arg.rb +139 -0
  20. data/core-docs/toys/dsl/tool.rb +1530 -0
  21. data/core-docs/toys/errors.rb +93 -0
  22. data/core-docs/toys/flag.rb +549 -0
  23. data/core-docs/toys/flag_group.rb +186 -0
  24. data/core-docs/toys/input_file.rb +8 -0
  25. data/core-docs/toys/loader.rb +222 -0
  26. data/core-docs/toys/middleware.rb +295 -0
  27. data/core-docs/toys/mixin.rb +142 -0
  28. data/core-docs/toys/module_lookup.rb +75 -0
  29. data/core-docs/toys/positional_arg.rb +145 -0
  30. data/core-docs/toys/settings.rb +507 -0
  31. data/core-docs/toys/source_info.rb +127 -0
  32. data/core-docs/toys/standard_middleware/add_verbosity_flags.rb +49 -0
  33. data/core-docs/toys/standard_middleware/apply_config.rb +24 -0
  34. data/core-docs/toys/standard_middleware/handle_usage_errors.rb +33 -0
  35. data/core-docs/toys/standard_middleware/set_default_descriptions.rb +222 -0
  36. data/core-docs/toys/standard_middleware/show_help.rb +190 -0
  37. data/core-docs/toys/standard_middleware/show_root_version.rb +45 -0
  38. data/core-docs/toys/standard_mixins/bundler.rb +83 -0
  39. data/core-docs/toys/standard_mixins/exec.rb +645 -0
  40. data/core-docs/toys/standard_mixins/fileutils.rb +18 -0
  41. data/core-docs/toys/standard_mixins/gems.rb +48 -0
  42. data/core-docs/toys/standard_mixins/git_cache.rb +41 -0
  43. data/core-docs/toys/standard_mixins/highline.rb +133 -0
  44. data/core-docs/toys/standard_mixins/terminal.rb +135 -0
  45. data/core-docs/toys/standard_mixins/xdg.rb +49 -0
  46. data/core-docs/toys/template.rb +112 -0
  47. data/core-docs/toys/tool_definition.rb +926 -0
  48. data/core-docs/toys/utils/completion_engine.rb +49 -0
  49. data/core-docs/toys/utils/exec.rb +721 -0
  50. data/core-docs/toys/utils/gems.rb +185 -0
  51. data/core-docs/toys/utils/git_cache.rb +353 -0
  52. data/core-docs/toys/utils/help_text.rb +134 -0
  53. data/core-docs/toys/utils/terminal.rb +310 -0
  54. data/core-docs/toys/utils/xdg.rb +253 -0
  55. data/core-docs/toys/wrappable_string.rb +120 -0
  56. data/core-docs/toys-core.rb +63 -0
  57. data/docs/guide.md +497 -156
  58. data/lib/toys/standard_cli.rb +50 -36
  59. data/lib/toys/templates/clean.rb +18 -0
  60. data/lib/toys/templates/gem_build.rb +24 -0
  61. data/lib/toys/templates/minitest.rb +21 -0
  62. data/lib/toys/templates/rake.rb +23 -3
  63. data/lib/toys/templates/rdoc.rb +29 -0
  64. data/lib/toys/templates/rspec.rb +32 -4
  65. data/lib/toys/templates/rubocop.rb +14 -1
  66. data/lib/toys/templates/yardoc.rb +55 -0
  67. data/lib/toys/testing.rb +186 -109
  68. data/lib/toys/version.rb +1 -1
  69. data/lib/toys.rb +4 -2
  70. 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,4 @@
1
+ module Toys
2
+ module DSL
3
+ end
4
+ 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