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,33 @@
1
+ module Toys
2
+ module StandardMiddleware
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # This middleware handles the case of a usage error. If a usage error, such
7
+ # as an unrecognized flag or an unfulfilled required argument, is detected,
8
+ # this middleware intercepts execution and displays the error along with
9
+ # the short help string, and terminates execution with an error code.
10
+ #
11
+ class HandleUsageErrors
12
+ ##
13
+ # Exit code for usage error. (2 by convention)
14
+ # @return [Integer]
15
+ #
16
+ USAGE_ERROR_EXIT_CODE = 2
17
+
18
+ ##
19
+ # Create a HandleUsageErrors middleware.
20
+ #
21
+ # @param exit_code [Integer] The exit code to return if a usage error
22
+ # occurs. Default is {USAGE_ERROR_EXIT_CODE}.
23
+ # @param stream [IO] Output stream to write to. Default is stderr.
24
+ # @param styled_output [Boolean,nil] Cause the tool to display help text
25
+ # with ansi styles. If `nil`, display styles if the output stream is
26
+ # a tty. Default is `nil`.
27
+ #
28
+ def initialize(exit_code: nil, stream: $stderr, styled_output: nil)
29
+ # Source available in the toys-core gem
30
+ end
31
+ end
32
+ end
33
+ end
@@ -0,0 +1,222 @@
1
+ module Toys
2
+ module StandardMiddleware
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # This middleware sets default description fields for tools and command
7
+ # line arguments and flags that do not have them set otherwise.
8
+ #
9
+ # You can modify the static descriptions for tools, namespaces, and the
10
+ # root tool by passing parameters to this middleware. For finer control,
11
+ # you can override methods to modify the description generation logic.
12
+ #
13
+ class SetDefaultDescriptions
14
+ ##
15
+ # The default description for tools.
16
+ # @return [String]
17
+ #
18
+ DEFAULT_TOOL_DESC = "(No tool description available)"
19
+
20
+ ##
21
+ # The default description for delegating tools.
22
+ # @return [String]
23
+ #
24
+ DEFAULT_DELEGATE_DESC = '(Delegates to "%<target>s")'
25
+
26
+ ##
27
+ # The default description for namespaces.
28
+ # @return [String]
29
+ #
30
+ DEFAULT_NAMESPACE_DESC = "(A namespace of tools)"
31
+
32
+ ##
33
+ # The default description for the root tool.
34
+ # @return [String]
35
+ #
36
+ DEFAULT_ROOT_DESC = "Command line tool built using the toys-core gem."
37
+
38
+ ##
39
+ # The default long description for the root tool.
40
+ # @return [String]
41
+ #
42
+ DEFAULT_ROOT_LONG_DESC = [
43
+ "This command line tool was built using the toys-core gem. See" \
44
+ " https://dazuma.github.io/toys/gems/toys-core for more info.",
45
+ "To replace this message, set the description and long description" \
46
+ " of the root tool, or configure the SetDefaultDescriptions" \
47
+ " middleware.",
48
+ ].freeze
49
+
50
+ ##
51
+ # Create a SetDefaultDescriptions middleware given default descriptions.
52
+ #
53
+ # @param default_tool_desc [String,nil] The default short description for
54
+ # runnable tools, or `nil` not to set one. Defaults to
55
+ # {DEFAULT_TOOL_DESC}.
56
+ # @param default_tool_long_desc [Array<String>,nil] The default long
57
+ # description for runnable tools, or `nil` not to set one. Defaults
58
+ # to `nil`.
59
+ # @param default_namespace_desc [String,nil] The default short
60
+ # description for non-runnable tools, or `nil` not to set one.
61
+ # Defaults to {DEFAULT_TOOL_DESC}.
62
+ # @param default_namespace_long_desc [Array<String>,nil] The default long
63
+ # description for non-runnable tools, or `nil` not to set one.
64
+ # Defaults to `nil`.
65
+ # @param default_root_desc [String,nil] The default short description for
66
+ # the root tool, or `nil` not to set one. Defaults to
67
+ # {DEFAULT_ROOT_DESC}.
68
+ # @param default_root_long_desc [Array<String>,nil] The default long
69
+ # description for the root tool, or `nil` not to set one. Defaults to
70
+ # {DEFAULT_ROOT_LONG_DESC}.
71
+ # @param default_delegate_desc [String,nil] The default short description
72
+ # for delegate tools, or `nil` not to set one. May include an sprintf
73
+ # field for the `target` name. Defaults to {DEFAULT_DELEGATE_DESC}.
74
+ #
75
+ def initialize(default_tool_desc: DEFAULT_TOOL_DESC,
76
+ default_tool_long_desc: nil,
77
+ default_namespace_desc: DEFAULT_NAMESPACE_DESC,
78
+ default_namespace_long_desc: nil,
79
+ default_root_desc: DEFAULT_ROOT_DESC,
80
+ default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
81
+ default_delegate_desc: DEFAULT_DELEGATE_DESC)
82
+ # Source available in the toys-core gem
83
+ end
84
+
85
+ protected
86
+
87
+ ##
88
+ # This method implements the logic for generating a tool description.
89
+ # By default, it uses the parameters given to the middleware object.
90
+ # Override this method to provide different logic.
91
+ #
92
+ # @param tool [Toys::ToolDefinition] The tool to document.
93
+ # @param data [Hash] Additional data that might be useful. Currently,
94
+ # the {Toys::Loader} is passed with key `:loader`. Future versions
95
+ # of Toys may provide additional information.
96
+ # @return [String,Array<String>,Toys::WrappableString] The default
97
+ # description. See {Toys::DSL::Tool#desc} for info on the format.
98
+ # @return [nil] if this middleware should not set the description.
99
+ #
100
+ def generate_tool_desc(tool, data)
101
+ # Source available in the toys-core gem
102
+ end
103
+
104
+ ##
105
+ # This method implements logic for generating a tool long description.
106
+ # By default, it uses the parameters given to the middleware object.
107
+ # Override this method to provide different logic.
108
+ #
109
+ # @param tool [Toys::ToolDefinition] The tool to document
110
+ # @param data [Hash] Additional data that might be useful. Currently,
111
+ # the {Toys::Loader} is passed with key `:loader`. Future versions of
112
+ # Toys may provide additional information.
113
+ # @return [Array<Toys::WrappableString,String,Array<String>>] The default
114
+ # long description. See {Toys::DSL::Tool#long_desc} for info on the
115
+ # format.
116
+ # @return [nil] if this middleware should not set the long description.
117
+ #
118
+ def generate_tool_long_desc(tool, data)
119
+ # Source available in the toys-core gem
120
+ end
121
+
122
+ ##
123
+ # This method implements the logic for generating a flag description.
124
+ # Override this method to provide different logic.
125
+ #
126
+ # @param flag [Toys::Flag] The flag to document
127
+ # @param data [Hash] Additional data that might be useful. Currently,
128
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
129
+ # versions of Toys may provide additional information.
130
+ # @return [String,Array<String>,Toys::WrappableString] The default
131
+ # description. See {Toys::DSL::Tool#desc} for info on the format.
132
+ # @return [nil] if this middleware should not set the description.
133
+ #
134
+ def generate_flag_desc(flag, data)
135
+ # Source available in the toys-core gem
136
+ end
137
+
138
+ ##
139
+ # This method implements logic for generating a flag long description.
140
+ # Override this method to provide different logic.
141
+ #
142
+ # @param flag [Toys::Flag] The flag to document
143
+ # @param data [Hash] Additional data that might be useful. Currently,
144
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
145
+ # versions of Toys may provide additional information.
146
+ # @return [Array<Toys::WrappableString,String,Array<String>>] The default
147
+ # long description. See {Toys::DSL::Tool#long_desc} for info on the
148
+ # format.
149
+ # @return [nil] if this middleware should not set the long description.
150
+ #
151
+ def generate_flag_long_desc(flag, data)
152
+ # Source available in the toys-core gem
153
+ end
154
+
155
+ ##
156
+ # This method implements the logic for generating an arg description.
157
+ # Override this method to provide different logic.
158
+ #
159
+ # @param arg [Toys::PositionalArg] The arg to document
160
+ # @param data [Hash] Additional data that might be useful. Currently,
161
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
162
+ # versions of Toys may provide additional information.
163
+ # @return [String,Array<String>,Toys::WrappableString] The default
164
+ # description. See {Toys::DSL::Tool#desc} for info on the format.
165
+ # @return [nil] if this middleware should not set the description.
166
+ #
167
+ def generate_arg_desc(arg, data)
168
+ # Source available in the toys-core gem
169
+ end
170
+
171
+ ##
172
+ # This method implements logic for generating an arg long description.
173
+ # Override this method to provide different logic.
174
+ #
175
+ # @param arg [Toys::PositionalArg] The arg to document
176
+ # @param data [Hash] Additional data that might be useful. Currently,
177
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
178
+ # versions of Toys may provide additional information.
179
+ # @return [Array<Toys::WrappableString,String,Array<String>>] The default
180
+ # long description. See {Toys::DSL::Tool#long_desc} for info on the
181
+ # format.
182
+ # @return [nil] if this middleware should not set the long description.
183
+ #
184
+ def generate_arg_long_desc(arg, data)
185
+ # Source available in the toys-core gem
186
+ end
187
+
188
+ ##
189
+ # This method implements the logic for generating a flag group
190
+ # description. Override this method to provide different logic.
191
+ #
192
+ # @param group [Toys::FlagGroup] The flag group to document
193
+ # @param data [Hash] Additional data that might be useful. Currently,
194
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
195
+ # versions of Toys may provide additional information.
196
+ # @return [String,Array<String>,Toys::WrappableString] The default
197
+ # description. See {Toys::DSL::Tool#desc} for info on the format.
198
+ # @return [nil] if this middleware should not set the description.
199
+ #
200
+ def generate_flag_group_desc(group, data)
201
+ # Source available in the toys-core gem
202
+ end
203
+
204
+ ##
205
+ # This method implements the logic for generating a flag group long
206
+ # description. Override this method to provide different logic.
207
+ #
208
+ # @param group [Toys::FlagGroup] The flag group to document
209
+ # @param data [Hash] Additional data that might be useful. Currently,
210
+ # the {Toys::ToolDefinition} is passed with key `:tool`. Future
211
+ # versions of Toys may provide additional information.
212
+ # @return [Array<Toys::WrappableString,String,Array<String>>] The default
213
+ # long description. See {Toys::DSL::Tool#long_desc} for info on the
214
+ # format.
215
+ # @return [nil] if this middleware should not set the long description.
216
+ #
217
+ def generate_flag_group_long_desc(group, data)
218
+ # Source available in the toys-core gem
219
+ end
220
+ end
221
+ end
222
+ end
@@ -0,0 +1,190 @@
1
+ module Toys
2
+ module StandardMiddleware
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # A middleware that shows help text for the tool when a flag (typically
7
+ # `--help`) is provided. It can also be configured to show help by
8
+ # default if the tool is a namespace that is not runnable.
9
+ #
10
+ # If a tool is not runnable, this middleware can also add a
11
+ # `--[no-]recursive` flag, which, when set to `true` (the default), shows
12
+ # all subtools recursively rather than only immediate subtools. This
13
+ # middleware can also search for keywords in its subtools.
14
+ #
15
+ class ShowHelp
16
+ ##
17
+ # Default help flags
18
+ # @return [Array<String>]
19
+ #
20
+ DEFAULT_HELP_FLAGS = ["-?", "--help"].freeze
21
+
22
+ ##
23
+ # Default usage flags
24
+ # @return [Array<String>]
25
+ #
26
+ DEFAULT_USAGE_FLAGS = ["--usage"].freeze
27
+
28
+ ##
29
+ # Default list subtools flags
30
+ # @return [Array<String>]
31
+ #
32
+ DEFAULT_LIST_FLAGS = ["--tools"].freeze
33
+
34
+ ##
35
+ # Default recursive flags
36
+ # @return [Array<String>]
37
+ #
38
+ DEFAULT_RECURSIVE_FLAGS = ["-r", "--[no-]recursive"].freeze
39
+
40
+ ##
41
+ # Default search flags
42
+ # @return [Array<String>]
43
+ #
44
+ DEFAULT_SEARCH_FLAGS = ["-s WORD", "--search=WORD"].freeze
45
+
46
+ ##
47
+ # Default show-all-subtools flags
48
+ # @return [Array<String>]
49
+ #
50
+ DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS = ["--all"].freeze
51
+
52
+ ##
53
+ # Key set when the show help flag is present
54
+ # @return [Object]
55
+ #
56
+ SHOW_HELP_KEY = Object.new.freeze
57
+
58
+ ##
59
+ # Key set when the show usage flag is present
60
+ # @return [Object]
61
+ #
62
+ SHOW_USAGE_KEY = Object.new.freeze
63
+
64
+ ##
65
+ # Key set when the show subtool list flag is present
66
+ # @return [Object]
67
+ #
68
+ SHOW_LIST_KEY = Object.new.freeze
69
+
70
+ ##
71
+ # Key for the recursive setting
72
+ # @return [Object]
73
+ #
74
+ RECURSIVE_SUBTOOLS_KEY = Object.new.freeze
75
+
76
+ ##
77
+ # Key for the search string
78
+ # @return [Object]
79
+ #
80
+ SEARCH_STRING_KEY = Object.new.freeze
81
+
82
+ ##
83
+ # Key for the show-all-subtools setting
84
+ # @return [Object]
85
+ #
86
+ SHOW_ALL_SUBTOOLS_KEY = Object.new.freeze
87
+
88
+ ##
89
+ # Key for the tool name
90
+ # @return [Object]
91
+ #
92
+ TOOL_NAME_KEY = Object.new.freeze
93
+
94
+ ##
95
+ # Create a ShowHelp middleware.
96
+ #
97
+ # @param help_flags [Boolean,Array<String>,Proc] Specify flags to
98
+ # display help. The value may be any of the following:
99
+ #
100
+ # * An array of flags.
101
+ # * The `true` value to use {DEFAULT_HELP_FLAGS}.
102
+ # * The `false` value for no flags. (Default)
103
+ # * A proc that takes a tool and returns any of the above.
104
+ #
105
+ # @param usage_flags [Boolean,Array<String>,Proc] Specify flags to
106
+ # display usage. The value may be any of the following:
107
+ #
108
+ # * An array of flags.
109
+ # * The `true` value to use {DEFAULT_USAGE_FLAGS}.
110
+ # * The `false` value for no flags. (Default)
111
+ # * A proc that takes a tool and returns any of the above.
112
+ #
113
+ # @param list_flags [Boolean,Array<String>,Proc] Specify flags to
114
+ # display subtool list. The value may be any of the following:
115
+ #
116
+ # * An array of flags.
117
+ # * The `true` value to use {DEFAULT_LIST_FLAGS}.
118
+ # * The `false` value for no flags. (Default)
119
+ # * A proc that takes a tool and returns any of the above.
120
+ #
121
+ # @param recursive_flags [Boolean,Array<String>,Proc] Specify flags
122
+ # to control recursive subtool search. The value may be any of the
123
+ # following:
124
+ #
125
+ # * An array of flags.
126
+ # * The `true` value to use {DEFAULT_RECURSIVE_FLAGS}.
127
+ # * The `false` value for no flags. (Default)
128
+ # * A proc that takes a tool and returns any of the above.
129
+ #
130
+ # @param search_flags [Boolean,Array<String>,Proc] Specify flags
131
+ # to search subtools for a search term. The value may be any of
132
+ # the following:
133
+ #
134
+ # * An array of flags.
135
+ # * The `true` value to use {DEFAULT_SEARCH_FLAGS}.
136
+ # * The `false` value for no flags. (Default)
137
+ # * A proc that takes a tool and returns any of the above.
138
+ #
139
+ # @param show_all_subtools_flags [Boolean,Array<String>,Proc] Specify
140
+ # flags to show all subtools, including hidden tools and non-runnable
141
+ # namespaces. The value may be any of the following:
142
+ #
143
+ # * An array of flags.
144
+ # * The `true` value to use {DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS}.
145
+ # * The `false` value for no flags. (Default)
146
+ # * A proc that takes a tool and returns any of the above.
147
+ #
148
+ # @param default_recursive [Boolean] Whether to search recursively for
149
+ # subtools by default. Default is `false`.
150
+ # @param default_show_all_subtools [Boolean] Whether to show all subtools
151
+ # by default. Default is `false`.
152
+ # @param fallback_execution [Boolean] Cause the tool to display its own
153
+ # help text if it is not otherwise runnable. This is mostly useful
154
+ # for namespaces, which have children are not runnable. Default is
155
+ # `false`.
156
+ # @param allow_root_args [Boolean] If the root tool includes flags for
157
+ # help or usage, and doesn't otherwise use positional arguments,
158
+ # then a tool name can be passed as arguments to display help for
159
+ # that tool.
160
+ # @param show_source_path [Boolean] Show the source path section. Default
161
+ # is `false`.
162
+ # @param separate_sources [Boolean] Split up tool list by source root.
163
+ # Defaults to false.
164
+ # @param use_less [Boolean] If the `less` tool is available, and the
165
+ # output stream is a tty, then use `less` to display help text.
166
+ # @param stream [IO] Output stream to write to. Default is stdout.
167
+ # @param styled_output [Boolean,nil] Cause the tool to display help text
168
+ # with ansi styles. If `nil`, display styles if the output stream is
169
+ # a tty. Default is `nil`.
170
+ #
171
+ def initialize(help_flags: false,
172
+ usage_flags: false,
173
+ list_flags: false,
174
+ recursive_flags: false,
175
+ search_flags: false,
176
+ show_all_subtools_flags: false,
177
+ default_recursive: false,
178
+ default_show_all_subtools: false,
179
+ fallback_execution: false,
180
+ allow_root_args: false,
181
+ show_source_path: false,
182
+ separate_sources: false,
183
+ use_less: false,
184
+ stream: $stdout,
185
+ styled_output: nil)
186
+ # Source available in the toys-core gem
187
+ end
188
+ end
189
+ end
190
+ end
@@ -0,0 +1,45 @@
1
+ module Toys
2
+ module StandardMiddleware
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # A middleware that displays a version string for the root tool if the
7
+ # `--version` flag is given.
8
+ #
9
+ class ShowRootVersion
10
+ ##
11
+ # Default version flags
12
+ # @return [Array<String>]
13
+ #
14
+ DEFAULT_VERSION_FLAGS = ["--version"].freeze
15
+
16
+ ##
17
+ # Default description for the version flags
18
+ # @return [String]
19
+ #
20
+ DEFAULT_VERSION_FLAG_DESC = "Display the version"
21
+
22
+ ##
23
+ # Key set when the version flag is present
24
+ # @return [Object]
25
+ #
26
+ SHOW_VERSION_KEY = Object.new.freeze
27
+
28
+ ##
29
+ # Create a ShowVersion middleware
30
+ #
31
+ # @param version_string [String] The string that should be displayed.
32
+ # @param version_flags [Array<String>] A list of flags that should
33
+ # trigger displaying the version. Default is
34
+ # {DEFAULT_VERSION_FLAGS}.
35
+ # @param stream [IO] Output stream to write to. Default is stdout.
36
+ #
37
+ def initialize(version_string: nil,
38
+ version_flags: DEFAULT_VERSION_FLAGS,
39
+ version_flag_desc: DEFAULT_VERSION_FLAG_DESC,
40
+ stream: $stdout)
41
+ # Source available in the toys-core gem
42
+ end
43
+ end
44
+ end
45
+ end
@@ -0,0 +1,83 @@
1
+ module Toys
2
+ module StandardMixins
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # Ensures that a bundle is installed and set up when this tool is run.
7
+ #
8
+ # The following parameters can be passed when including this mixin:
9
+ #
10
+ # * `:static` (Boolean) If `true`, installs the bundle immediately, when
11
+ # defining the tool. If `false` (the default), installs the bundle just
12
+ # before the tool runs.
13
+ #
14
+ # * `:groups` (Array\<String\>) The groups to include in setup.
15
+ #
16
+ # * `:gemfile_path` (String) The path to the Gemfile to use. If `nil` or
17
+ # not given, the `:search_dirs` will be searched for a Gemfile.
18
+ #
19
+ # * `:search_dirs` (String,Symbol,Array\<String,Symbol\>) Directories to
20
+ # search for a Gemfile.
21
+ #
22
+ # You can pass full directory paths, and/or any of the following:
23
+ # * `:context` - the current context directory.
24
+ # * `:current` - the current working directory.
25
+ # * `:toys` - the Toys directory containing the tool definition, and
26
+ # any of its parents within the Toys directory hierarchy.
27
+ #
28
+ # The default is to search `[:toys, :context, :current]` in that order.
29
+ # See {DEFAULT_SEARCH_DIRS}.
30
+ #
31
+ # For most directories, the bundler mixin will look for the files
32
+ # ".gems.rb", "gems.rb", and "Gemfile", in that order. In `:toys`
33
+ # directories, it will look only for ".gems.rb" and "Gemfile", in that
34
+ # order. These can be overridden by setting the `:gemfile_names` and/or
35
+ # `:toys_gemfile_names` arguments.
36
+ #
37
+ # * `:gemfile_names` (Array\<String\>) File names that are recognized as
38
+ # Gemfiles when searching in directories other than Toys directories.
39
+ # Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
40
+ #
41
+ # * `:toys_gemfile_names` (Array\<String\>) File names that are
42
+ # recognized as Gemfiles when wearching in Toys directories.
43
+ # Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
44
+ #
45
+ # * `:on_missing` (Symbol) What to do if a needed gem is not installed.
46
+ #
47
+ # Supported values:
48
+ # * `:confirm` - prompt the user on whether to install (default).
49
+ # * `:error` - raise an exception.
50
+ # * `:install` - just install the gem.
51
+ #
52
+ # * `:on_conflict` (Symbol) What to do if bundler has already been run
53
+ # with a different Gemfile.
54
+ #
55
+ # Supported values:
56
+ # * `:error` - raise an exception (default).
57
+ # * `:ignore` - just silently proceed without bundling again.
58
+ # * `:warn` - print a warning and proceed without bundling again.
59
+ #
60
+ # * `:retries` (Integer) Number of times to retry bundler operations
61
+ # (optional)
62
+ #
63
+ # * `:terminal` (Toys::Utils::Terminal) Terminal to use (optional)
64
+ # * `:input` (IO) Input IO (optional, defaults to STDIN)
65
+ # * `:output` (IO) Output IO (optional, defaults to STDOUT)
66
+ #
67
+ module Bundler
68
+ include Mixin
69
+
70
+ ##
71
+ # Default search directories for Gemfiles.
72
+ # @return [Array<String,Symbol>]
73
+ #
74
+ DEFAULT_SEARCH_DIRS = [:toys, :context, :current].freeze
75
+
76
+ ##
77
+ # The gemfile names that are searched by default in Toys directories.
78
+ # @return [Array<String>]
79
+ #
80
+ DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
81
+ end
82
+ end
83
+ end