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,329 @@
1
+ module Toys
2
+ ##
3
+ # **_Defined in the toys-core gem_**
4
+ #
5
+ # A Completion is a callable Proc that determines candidates for shell tab
6
+ # completion. You pass a {Toys::Completion::Context} object (which includes
7
+ # the current string fragment and other information) and it returns an array
8
+ # of candidates, represented by {Toys::Completion::Candidate} objects, for
9
+ # completing the fragment.
10
+ #
11
+ # A useful method here is the class method {Toys::Completion.create} which
12
+ # takes a variety of inputs and returns a suitable completion Proc.
13
+ #
14
+ module Completion
15
+ ##
16
+ # **_Defined in the toys-core gem_**
17
+ #
18
+ # The context in which to determine completion candidates.
19
+ #
20
+ class Context
21
+ ##
22
+ # Create a completion context
23
+ #
24
+ # @param cli [Toys::CLI] The CLI being run. Required.
25
+ # @param previous_words [Array<String>] Array of complete strings that
26
+ # appeared prior to the fragment to complete.
27
+ # @param fragment_prefix [String] A prefix in the fragment that does not
28
+ # participate in completion. (e.g. "key=")
29
+ # @param fragment [String] The string fragment to complete.
30
+ # @param params [Hash] Miscellaneous context data
31
+ #
32
+ def initialize(cli:, previous_words: [], fragment_prefix: "", fragment: "", **params)
33
+ # Source available in the toys-core gem
34
+ end
35
+
36
+ ##
37
+ # Create a new completion context with the given modifications.
38
+ #
39
+ # @param delta_params [Hash] Replace context data.
40
+ # @return [Toys::Completion::Context]
41
+ #
42
+ def with(**delta_params)
43
+ # Source available in the toys-core gem
44
+ end
45
+
46
+ ##
47
+ # The CLI being run.
48
+ # @return [Toys::CLI]
49
+ #
50
+ attr_reader :cli
51
+
52
+ ##
53
+ # All previous words.
54
+ # @return [Array<String>]
55
+ #
56
+ attr_reader :previous_words
57
+
58
+ ##
59
+ # A non-completed prefix for the current fragment.
60
+ # @return [String]
61
+ #
62
+ attr_reader :fragment_prefix
63
+
64
+ ##
65
+ # The current string fragment to complete
66
+ # @return [String]
67
+ #
68
+ attr_reader :fragment
69
+
70
+ ##
71
+ # Get data for arbitrary key.
72
+ # @param [Symbol] key
73
+ # @return [Object]
74
+ #
75
+ def [](key)
76
+ # Source available in the toys-core gem
77
+ end
78
+ alias get []
79
+
80
+ ##
81
+ # The tool being invoked, which should control the completion.
82
+ # @return [Toys::ToolDefinition]
83
+ #
84
+ def tool
85
+ # Source available in the toys-core gem
86
+ end
87
+
88
+ ##
89
+ # An array of complete arguments passed to the tool, prior to the
90
+ # fragment to complete.
91
+ # @return [Array<String>]
92
+ #
93
+ def args
94
+ # Source available in the toys-core gem
95
+ end
96
+
97
+ ##
98
+ # Current ArgParser indicating the status of argument parsing up to
99
+ # this point.
100
+ #
101
+ # @return [Toys::ArgParser]
102
+ #
103
+ def arg_parser
104
+ # Source available in the toys-core gem
105
+ end
106
+ end
107
+
108
+ ##
109
+ # **_Defined in the toys-core gem_**
110
+ #
111
+ # A candidate for completing a string fragment.
112
+ #
113
+ # A candidate includes a string representing the potential completed
114
+ # word, as well as a flag indicating whether it is a *partial* completion
115
+ # (i.e. a prefix that could still be added to) versus a *final* word.
116
+ # Generally, tab completion systems should add a trailing space after a
117
+ # final completion but not after a partial completion.
118
+ #
119
+ class Candidate
120
+ include ::Comparable
121
+
122
+ ##
123
+ # Create a new candidate
124
+ # @param string [String] The candidate string
125
+ # @param partial [Boolean] Whether the candidate is partial. Defaults
126
+ # to `false`.
127
+ #
128
+ def initialize(string, partial: false)
129
+ # Source available in the toys-core gem
130
+ end
131
+
132
+ ##
133
+ # Get the candidate string.
134
+ # @return [String]
135
+ #
136
+ attr_reader :string
137
+ alias to_s string
138
+
139
+ ##
140
+ # Determine whether the candidate is partial completion.
141
+ # @return [Boolean]
142
+ #
143
+ def partial?
144
+ # Source available in the toys-core gem
145
+ end
146
+
147
+ ##
148
+ # Determine whether the candidate is a final completion.
149
+ # @return [Boolean]
150
+ #
151
+ def final?
152
+ # Source available in the toys-core gem
153
+ end
154
+
155
+ ##
156
+ # Create an array of candidates given an array of strings.
157
+ #
158
+ # @param array [Array<String>]
159
+ # @return [Array<Toys::Completion::Candidate]
160
+ #
161
+ def self.new_multi(array, partial: false)
162
+ # Source available in the toys-core gem
163
+ end
164
+ end
165
+
166
+ ##
167
+ # **_Defined in the toys-core gem_**
168
+ #
169
+ # A base class that returns no completions.
170
+ #
171
+ # Completions *may* but do not need to subclass this base class. They
172
+ # merely need to duck-type `Proc` by implementing the `call` method.
173
+ #
174
+ class Base
175
+ ##
176
+ # Returns candidates for the current completion.
177
+ # This default implementation returns an empty list.
178
+ #
179
+ # @param context [Toys::Completion::Context] The current completion
180
+ # context including the string fragment.
181
+ # @return [Array<Toys::Completion::Candidate>] An array of candidates
182
+ #
183
+ def call(context)
184
+ # Source available in the toys-core gem
185
+ end
186
+ end
187
+
188
+ ##
189
+ # **_Defined in the toys-core gem_**
190
+ #
191
+ # A Completion that returns candidates from the local file system.
192
+ #
193
+ class FileSystem < Base
194
+ ##
195
+ # Create a completion that gets candidates from names in the local file
196
+ # system.
197
+ #
198
+ # @param cwd [String] Working directory (defaults to the current dir).
199
+ # @param omit_files [Boolean] Omit files from candidates
200
+ # @param omit_directories [Boolean] Omit directories from candidates
201
+ # @param prefix_constraint [String,Regexp] Constraint on the fragment
202
+ # prefix. Defaults to requiring the prefix be empty.
203
+ #
204
+ def initialize(cwd: nil, omit_files: false, omit_directories: false, prefix_constraint: "")
205
+ # Source available in the toys-core gem
206
+ end
207
+
208
+ ##
209
+ # Whether files are included in the completion candidates.
210
+ # @return [Boolean]
211
+ #
212
+ attr_reader :include_files
213
+
214
+ ##
215
+ # Whether directories are included in the completion candidates.
216
+ # @return [Boolean]
217
+ #
218
+ attr_reader :include_directories
219
+
220
+ ##
221
+ # Constraint on the fragment prefix.
222
+ # @return [String,Regexp]
223
+ #
224
+ attr_reader :prefix_constraint
225
+
226
+ ##
227
+ # Path to the starting directory.
228
+ # @return [String]
229
+ #
230
+ attr_reader :cwd
231
+
232
+ ##
233
+ # Returns candidates for the current completion.
234
+ #
235
+ # @param context [Toys::Completion::Context] the current completion
236
+ # context including the string fragment.
237
+ # @return [Array<Toys::Completion::Candidate>] an array of candidates
238
+ #
239
+ def call(context)
240
+ # Source available in the toys-core gem
241
+ end
242
+ end
243
+
244
+ ##
245
+ # **_Defined in the toys-core gem_**
246
+ #
247
+ # A Completion whose candidates come from a static list of strings.
248
+ #
249
+ class Enum < Base
250
+ ##
251
+ # Create a completion from a list of values.
252
+ #
253
+ # @param values [Array<String>]
254
+ # @param prefix_constraint [String,Regexp] Constraint on the fragment
255
+ # prefix. Defaults to requiring the prefix be empty.
256
+ #
257
+ def initialize(values, prefix_constraint: "")
258
+ # Source available in the toys-core gem
259
+ end
260
+
261
+ ##
262
+ # The array of completion candidates.
263
+ # @return [Array<String>]
264
+ #
265
+ attr_reader :values
266
+
267
+ ##
268
+ # Constraint on the fragment prefix.
269
+ # @return [String,Regexp]
270
+ #
271
+ attr_reader :prefix_constraint
272
+
273
+ ##
274
+ # Returns candidates for the current completion.
275
+ #
276
+ # @param context [Toys::Completion::Context] the current completion
277
+ # context including the string fragment.
278
+ # @return [Array<Toys::Completion::Candidate>] an array of candidates
279
+ #
280
+ def call(context)
281
+ # Source available in the toys-core gem
282
+ end
283
+ end
284
+
285
+ ##
286
+ # An instance of the empty completion that returns no candidates.
287
+ # @return [Toys:::Completion::Base]
288
+ #
289
+ EMPTY = Base.new
290
+
291
+ ##
292
+ # Create a completion Proc from a variety of specification formats. The
293
+ # completion is constructed from the given specification object and/or the
294
+ # given block. Additionally, some completions can take a hash of options.
295
+ #
296
+ # Recognized specs include:
297
+ #
298
+ # * `:empty`: Returns the empty completion. Any block or options are
299
+ # ignored.
300
+ #
301
+ # * `:file_system`: Returns a completion that searches the current
302
+ # directory for file and directory names. You may also pass any of the
303
+ # options recognized by {Toys::Completion::FileSystem#initialize}. The
304
+ # block is ignored.
305
+ #
306
+ # * An **Array** of strings. Returns a completion that uses those values
307
+ # as candidates. You may also pass any of the options recognized by
308
+ # {Toys::Completion::Enum#initialize}. The block is ignored.
309
+ #
310
+ # * A **function**, either passed as a Proc (where the block is ignored)
311
+ # or as a block (if the spec is nil). The function must behave as a
312
+ # completion object, taking {Toys::Completion::Context} as the sole
313
+ # argument, and returning an array of {Toys::Completion::Candidate}.
314
+ #
315
+ # * `:default` and `nil` indicate the **default completion**. For this
316
+ # method, the default is the empty completion (i.e. these are synonyms
317
+ # for `:empty`). However, other completion resolution methods might
318
+ # have a different default.
319
+ #
320
+ # @param spec [Object] See the description for recognized values.
321
+ # @param options [Hash] Additional options to pass to the completion.
322
+ # @param block [Proc] See the description for recognized forms.
323
+ # @return [Toys::Completion::Base,Proc]
324
+ #
325
+ def self.create(spec = nil, **options, &block)
326
+ # Source available in the toys-core gem
327
+ end
328
+ end
329
+ end
@@ -0,0 +1,321 @@
1
+ module Toys
2
+ ##
3
+ # **_Defined in the toys-core gem_**
4
+ #
5
+ # This is the base class for tool execution. It represents `self` when your
6
+ # tool's methods (such as `run`) are called, and it defines the methods that
7
+ # can be called by your tool (such as {#logger} and {#exit}.)
8
+ #
9
+ # This class also manages the "data" available to your tool when it runs.
10
+ # This data is a hash of key-value pairs. It consists of values set by flags
11
+ # and arguments defined by the tool, plus some "well-known" values such as
12
+ # the logger and verbosity level.
13
+ #
14
+ # You can obtain a value from the data using the {Toys::Context#get} method.
15
+ # Additionally, convenience methods are provided for many of the well-known
16
+ # keys. For instance, you can call {Toys::Context#verbosity} to obtain the
17
+ # value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
18
+ # positional arguments that store their data here will also typically
19
+ # generate convenience methods. For example, an argument with key `:abc` will
20
+ # add a method called `abc` that you can call to get the value.
21
+ #
22
+ # By convention, flags and arguments defined by your tool should use strings
23
+ # or symbols as keys. Keys that are not strings or symbols should either be
24
+ # well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
25
+ # for internal private information needed by middleware and mixins. The
26
+ # module {Toys::Context::Key} defines a number of well-known keys as
27
+ # constants.
28
+ #
29
+ class Context
30
+ ##
31
+ # **_Defined in the toys-core gem_**
32
+ #
33
+ # Well-known context keys.
34
+ #
35
+ # This module is mixed into the runtime context. This means you can
36
+ # reference any of these constants directly from your run method.
37
+ #
38
+ # ### Example
39
+ #
40
+ # tool "my-name" do
41
+ # def run
42
+ # # TOOL_NAME is available here.
43
+ # puts "My name is #{get(TOOL_NAME)}"
44
+ # end
45
+ # end
46
+ #
47
+ module Key
48
+ ##
49
+ # Context key for the argument list passed to the current tool. Value is
50
+ # an array of strings.
51
+ # @return [Object]
52
+ #
53
+ ARGS = ::Object.new.freeze
54
+
55
+ ##
56
+ # Context key for the currently running {Toys::CLI}. You can use the
57
+ # value to run other tools from your tool by calling {Toys::CLI#run}.
58
+ # @return [Object]
59
+ #
60
+ CLI = ::Object.new.freeze
61
+
62
+ ##
63
+ # Context key for the context directory path. The value is a string
64
+ # @return [Object]
65
+ #
66
+ CONTEXT_DIRECTORY = ::Object.new.freeze
67
+
68
+ ##
69
+ # Context key for the context from which the current call was delegated.
70
+ # The value is either another context object, or `nil` if the current
71
+ # call is not delegated.
72
+ # @return [Object]
73
+ #
74
+ DELEGATED_FROM = ::Object.new.freeze
75
+
76
+ ##
77
+ # Context key for the active `Logger` object.
78
+ # @return [Object]
79
+ #
80
+ LOGGER = ::Object.new.freeze
81
+
82
+ ##
83
+ # Context key for the {Toys::ToolDefinition} object being executed.
84
+ # @return [Object]
85
+ #
86
+ TOOL = ::Object.new.freeze
87
+
88
+ ##
89
+ # Context key for the full name of the tool being executed. Value is an
90
+ # array of strings.
91
+ # @return [Object]
92
+ #
93
+ TOOL_NAME = ::Object.new.freeze
94
+
95
+ ##
96
+ # Context key for the {Toys::SourceInfo} describing the source of this
97
+ # tool.
98
+ # @return [Object]
99
+ #
100
+ TOOL_SOURCE = ::Object.new.freeze
101
+
102
+ ##
103
+ # Context key for all unmatched args in order. The value is an array of
104
+ # strings.
105
+ # @return [Object]
106
+ #
107
+ UNMATCHED_ARGS = ::Object.new.freeze
108
+
109
+ ##
110
+ # Context key for unmatched flags. The value is an array of strings.
111
+ # @return [Object]
112
+ #
113
+ UNMATCHED_FLAGS = ::Object.new.freeze
114
+
115
+ ##
116
+ # Context key for unmatched positional args. The value is an array of
117
+ # strings.
118
+ # @return [Object]
119
+ #
120
+ UNMATCHED_POSITIONAL = ::Object.new.freeze
121
+
122
+ ##
123
+ # Context key for the list of usage errors raised. The value is an array
124
+ # of {Toys::ArgParser::UsageError}.
125
+ # @return [Object]
126
+ #
127
+ USAGE_ERRORS = ::Object.new.freeze
128
+
129
+ ##
130
+ # Context key for the verbosity value. The value is an integer defaulting
131
+ # to 0, with higher values meaning more verbose and lower meaning more
132
+ # quiet.
133
+ # @return [Object]
134
+ #
135
+ VERBOSITY = ::Object.new.freeze
136
+ end
137
+
138
+ ##
139
+ # The raw arguments passed to the tool, as an array of strings.
140
+ # This does not include the tool name itself.
141
+ #
142
+ # This is a convenience getter for {Toys::Context::Key::ARGS}.
143
+ #
144
+ # @return [Array<String>]
145
+ #
146
+ def args
147
+ # Source available in the toys-core gem
148
+ end
149
+
150
+ ##
151
+ # The currently running CLI.
152
+ #
153
+ # This is a convenience getter for {Toys::Context::Key::CLI}.
154
+ #
155
+ # @return [Toys::CLI]
156
+ #
157
+ def cli
158
+ # Source available in the toys-core gem
159
+ end
160
+
161
+ ##
162
+ # Return the context directory for this tool. Generally, this defaults
163
+ # to the directory containing the toys config directory structure being
164
+ # read, but it may be changed by setting a different context directory
165
+ # for the tool.
166
+ #
167
+ # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
168
+ #
169
+ # @return [String] Context directory path
170
+ # @return [nil] if there is no context.
171
+ #
172
+ def context_directory
173
+ # Source available in the toys-core gem
174
+ end
175
+
176
+ ##
177
+ # The logger for this execution.
178
+ #
179
+ # This is a convenience getter for {Toys::Context::Key::LOGGER}.
180
+ #
181
+ # @return [Logger]
182
+ #
183
+ def logger
184
+ # Source available in the toys-core gem
185
+ end
186
+
187
+ ##
188
+ # The full name of the tool being executed, as an array of strings.
189
+ #
190
+ # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
191
+ #
192
+ # @return [Array<String>]
193
+ #
194
+ def tool_name
195
+ # Source available in the toys-core gem
196
+ end
197
+
198
+ ##
199
+ # The source of the tool being executed.
200
+ #
201
+ # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
202
+ #
203
+ # @return [Toys::SourceInfo]
204
+ #
205
+ def tool_source
206
+ # Source available in the toys-core gem
207
+ end
208
+
209
+ ##
210
+ # The (possibly empty) array of errors detected during argument parsing.
211
+ #
212
+ # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
213
+ #
214
+ # @return [Array<Toys::ArgParser::UsageError>]
215
+ #
216
+ def usage_errors
217
+ # Source available in the toys-core gem
218
+ end
219
+
220
+ ##
221
+ # The current verbosity setting as an integer.
222
+ #
223
+ # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
224
+ #
225
+ # @return [Integer]
226
+ #
227
+ def verbosity
228
+ # Source available in the toys-core gem
229
+ end
230
+
231
+ ##
232
+ # Fetch an option or other piece of data by key.
233
+ #
234
+ # @param key [Symbol]
235
+ # @return [Object]
236
+ #
237
+ def [](key)
238
+ # Source available in the toys-core gem
239
+ end
240
+ alias get []
241
+ alias __get []
242
+
243
+ ##
244
+ # Set an option or other piece of context data by key.
245
+ #
246
+ # @param key [Symbol]
247
+ # @param value [Object]
248
+ #
249
+ def []=(key, value)
250
+ # Source available in the toys-core gem
251
+ end
252
+
253
+ ##
254
+ # Set one or more options or other context data by key.
255
+ #
256
+ # @return [self]
257
+ #
258
+ # @overload set(key, value)
259
+ # Set an option or other piece of context data by key.
260
+ # @param key [Symbol]
261
+ # @param value [Object]
262
+ # @return [self]
263
+ #
264
+ # @overload set(hash)
265
+ # Set multiple content data keys and values
266
+ # @param hash [Hash] The keys and values to set
267
+ # @return [self]
268
+ #
269
+ def set(key, value = nil)
270
+ # Source available in the toys-core gem
271
+ end
272
+
273
+ ##
274
+ # The subset of the context that uses string or symbol keys. By convention,
275
+ # this includes keys that are set by tool flags and arguments, but does not
276
+ # include well-known context values such as verbosity or private context
277
+ # values used by middleware or mixins.
278
+ #
279
+ # @return [Hash]
280
+ #
281
+ def options
282
+ # Source available in the toys-core gem
283
+ end
284
+
285
+ ##
286
+ # Find the given data file or directory in this tool's search path.
287
+ #
288
+ # @param path [String] The path to find
289
+ # @param type [nil,:file,:directory] Type of file system object to find,
290
+ # or nil to return any type.
291
+ #
292
+ # @return [String] Absolute path of the result
293
+ # @return [nil] if the data was not found.
294
+ #
295
+ def find_data(path, type: nil)
296
+ # Source available in the toys-core gem
297
+ end
298
+
299
+ ##
300
+ # Exit immediately with the given status code
301
+ #
302
+ # @param code [Integer] The status code, which should be 0 for no error,
303
+ # or nonzero for an error condition. Default is 0.
304
+ # @return [void]
305
+ #
306
+ def exit(code = 0)
307
+ # Source available in the toys-core gem
308
+ end
309
+
310
+ ##
311
+ # Exit immediately with the given status code
312
+ #
313
+ # @param code [Integer] The status code, which should be 0 for no error,
314
+ # or nonzero for an error condition. Default is 0.
315
+ # @return [void]
316
+ #
317
+ def self.exit(code = 0)
318
+ # Source available in the toys-core gem
319
+ end
320
+ end
321
+ end
@@ -0,0 +1,14 @@
1
+ module Toys
2
+ ##
3
+ # **_Defined in the toys-core gem_**
4
+ #
5
+ # The core Toys classes.
6
+ #
7
+ module Core
8
+ ##
9
+ # Current version of Toys core.
10
+ # @return [String]
11
+ #
12
+ VERSION = "0.13.0"
13
+ end
14
+ end
@@ -0,0 +1,56 @@
1
+ ##
2
+ # Create a base class for defining a tool with a given name.
3
+ #
4
+ # This method returns a base class for defining a tool with a given name.
5
+ # This is useful if the naming behavior of {Toys::Tool} is not adequate for
6
+ # your tool.
7
+ #
8
+ # ### Example
9
+ #
10
+ # class FooBar < Toys.Tool("Foo_Bar")
11
+ # desc "This is a tool called Foo_Bar"
12
+ #
13
+ # def run
14
+ # puts "Foo_Bar called"
15
+ # end
16
+ # end
17
+ #
18
+ # @param name [String] Name of the tool. Defaults to a name inferred from the
19
+ # class name. (See {Toys::Tool}.)
20
+ # @param base [Class] Use this tool class as the base class, and inherit helper
21
+ # methods from it.
22
+ # @param args [String,Class] Any string-valued positional argument is
23
+ # interpreted as the name. Any class-valued positional argument is
24
+ # interpreted as the base class.
25
+ #
26
+ def Toys.Tool(*args, name: nil, base: nil)
27
+ # Source available in the toys-core gem
28
+ end
29
+
30
+ module Toys
31
+ ##
32
+ # **_Defined in the toys-core gem_**
33
+ #
34
+ # Base class for defining tools
35
+ #
36
+ # This base class provides an alternative to the {Toys::DSL::Tool#tool}
37
+ # directive for defining tools in the Toys DSL. Creating a subclass of
38
+ # `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
39
+ # name. Subclasses can be created only in the context of a tool configuration
40
+ # DSL. Furthermore, a class-defined tool can be created only at the top level
41
+ # of a configuration file, or within another class-defined tool. It cannot
42
+ # be a subtool of a tool block.
43
+ #
44
+ # ### Example
45
+ #
46
+ # class FooBar < Toys::Tool
47
+ # desc "This is a tool called foo-bar"
48
+ #
49
+ # def run
50
+ # puts "foo-bar called"
51
+ # end
52
+ # end
53
+ #
54
+ class Tool < Context
55
+ end
56
+ end