toys 0.14.7 → 0.15.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -18,12 +18,12 @@ module Toys
18
18
  ##
19
19
  # Create a completion given configuration options.
20
20
  #
21
- # @param complete_subtools [Boolean] Whether to complete subtool names
22
- # @param include_hidden_subtools [Boolean] Whether to include hidden
21
+ # @param complete_subtools [true,false] Whether to complete subtool names
22
+ # @param include_hidden_subtools [true,false] Whether to include hidden
23
23
  # subtools (i.e. those beginning with an underscore)
24
- # @param complete_args [Boolean] Whether to complete positional args
25
- # @param complete_flags [Boolean] Whether to complete flag names
26
- # @param complete_flag_values [Boolean] Whether to complete flag values
24
+ # @param complete_args [true,false] Whether to complete positional args
25
+ # @param complete_flags [true,false] Whether to complete flag names
26
+ # @param complete_flag_values [true,false] Whether to complete flag values
27
27
  # @param delegation_target [Array<String>,nil] Delegation target, or
28
28
  # `nil` if none.
29
29
  #
@@ -35,7 +35,7 @@ module Toys
35
35
 
36
36
  ##
37
37
  # Whether to complete subtool names
38
- # @return [Boolean]
38
+ # @return [true,false]
39
39
  #
40
40
  def complete_subtools?
41
41
  # Source available in the toys-core gem
@@ -43,7 +43,7 @@ module Toys
43
43
 
44
44
  ##
45
45
  # Whether to include hidden subtools
46
- # @return [Boolean]
46
+ # @return [true,false]
47
47
  #
48
48
  def include_hidden_subtools?
49
49
  # Source available in the toys-core gem
@@ -51,7 +51,7 @@ module Toys
51
51
 
52
52
  ##
53
53
  # Whether to complete flags
54
- # @return [Boolean]
54
+ # @return [true,false]
55
55
  #
56
56
  def complete_flags?
57
57
  # Source available in the toys-core gem
@@ -59,7 +59,7 @@ module Toys
59
59
 
60
60
  ##
61
61
  # Whether to complete positional args
62
- # @return [Boolean]
62
+ # @return [true,false]
63
63
  #
64
64
  def complete_args?
65
65
  # Source available in the toys-core gem
@@ -67,7 +67,7 @@ module Toys
67
67
 
68
68
  ##
69
69
  # Whether to complete flag values
70
- # @return [Boolean]
70
+ # @return [true,false]
71
71
  #
72
72
  def complete_flag_values?
73
73
  # Source available in the toys-core gem
@@ -99,7 +99,7 @@ module Toys
99
99
  #
100
100
  # The following settings are supported:
101
101
  #
102
- # * `propagate_helper_methods` (_Boolean_) - Whether subtools should
102
+ # * `propagate_helper_methods` (_boolean_) - Whether subtools should
103
103
  # inherit methods defined by parent tools. Defaults to `false`.
104
104
  #
105
105
  class Settings < ::Toys::Settings
@@ -302,19 +302,33 @@ module Toys
302
302
  attr_reader :completion
303
303
 
304
304
  ##
305
- # The interrupt handler.
305
+ # The run handler.
306
306
  #
307
- # @return [Proc] The interrupt handler proc
308
- # @return [Symbol] The name of a method to call
309
- # @return [nil] if there is no interrupt handler
307
+ # This handler is called to run the tool. Normally it is a method name,
308
+ # represented by a symbol. (The default is `:run`.) It can be set to a
309
+ # different method name, or to a proc that will be called with `self` set
310
+ # to the tool context. Either way, it takes no arguments. The run handler
311
+ # can also be explicitly set to `nil` indicating a non-runnable tool;
312
+ # however, typically a tool is made non-runnable simply by leaving the run
313
+ # handler set to `:run` and not defining the method.
310
314
  #
311
- attr_reader :interrupt_handler
315
+ # @return [Proc] if the run handler is defined as a Proc
316
+ # @return [Symbol] if the run handler is defined as a method
317
+ # @return [nil] if the tool is explicitly made non-runnable
318
+ #
319
+ attr_reader :run_handler
312
320
 
313
321
  ##
314
322
  # The usage error handler.
315
323
  #
316
- # @return [Proc] The usage error handler proc
317
- # @return [Symbol] The name of a method to call
324
+ # This handler is called when at least one usage error is detected during
325
+ # argument parsing, and is called instead of the `run` method. It can be
326
+ # specified as a Proc, or a Symbol indicating a method to call. It
327
+ # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
328
+ # argument.
329
+ #
330
+ # @return [Proc] if the usage error handler is defined as a Proc
331
+ # @return [Symbol] if the user error handler is defined as a method
318
332
  # @return [nil] if there is no usage error handler
319
333
  #
320
334
  attr_reader :usage_error_handler
@@ -346,9 +360,37 @@ module Toys
346
360
  # Source available in the toys-core gem
347
361
  end
348
362
 
363
+ ##
364
+ # Return the signal handler for the given signal.
365
+ #
366
+ # This handler is called when the given signal is received, immediately
367
+ # taking over the execution as if it were the new run handler. The signal
368
+ # handler can be specified as a Proc, or a Symbol indicating a method to
369
+ # call. It optionally takes the `SignalException` as the sole argument.
370
+ #
371
+ # @param signal [Integer,String,Symbol] The signal number or name
372
+ # @return [Proc] if the signal handler is defined as a Proc
373
+ # @return [Symbol] if the signal handler is defined as a method
374
+ # @return [nil] if there is no handler for the given signal
375
+ #
376
+ def signal_handler(signal)
377
+ # Source available in the toys-core gem
378
+ end
379
+
380
+ ##
381
+ # Return the interrupt handler. This is equivalent to `signal_handler(2)`.
382
+ #
383
+ # @return [Proc] if the interrupt signal handler is defined as a Proc
384
+ # @return [Symbol] if the interrupt signal handler is defined as a method
385
+ # @return [nil] if there is no handler for the interrupt signals
386
+ #
387
+ def interrupt_handler
388
+ # Source available in the toys-core gem
389
+ end
390
+
349
391
  ##
350
392
  # Returns true if this tool is a root tool.
351
- # @return [Boolean]
393
+ # @return [true,false]
352
394
  #
353
395
  def root?
354
396
  # Source available in the toys-core gem
@@ -356,23 +398,35 @@ module Toys
356
398
 
357
399
  ##
358
400
  # Returns true if this tool is marked as runnable.
359
- # @return [Boolean]
401
+ # @return [true,false]
360
402
  #
361
403
  def runnable?
362
404
  # Source available in the toys-core gem
363
405
  end
364
406
 
365
407
  ##
366
- # Returns true if this tool handles interrupts.
367
- # @return [Boolean]
408
+ # Returns true if this tool handles interrupts. This is equivalent to
409
+ # `handles_signal?(2)`.
410
+ #
411
+ # @return [true,false]
368
412
  #
369
413
  def handles_interrupts?
370
414
  # Source available in the toys-core gem
371
415
  end
372
416
 
417
+ ##
418
+ # Returns true if this tool handles the given signal.
419
+ #
420
+ # @param signal [Integer,String,Symbol] The signal number or name
421
+ # @return [true,false]
422
+ #
423
+ def handles_signal?(signal)
424
+ # Source available in the toys-core gem
425
+ end
426
+
373
427
  ##
374
428
  # Returns true if this tool handles usage errors.
375
- # @return [Boolean]
429
+ # @return [true,false]
376
430
  #
377
431
  def handles_usage_errors?
378
432
  # Source available in the toys-core gem
@@ -380,7 +434,7 @@ module Toys
380
434
 
381
435
  ##
382
436
  # Returns true if this tool has at least one included module.
383
- # @return [Boolean]
437
+ # @return [true,false]
384
438
  #
385
439
  def includes_modules?
386
440
  # Source available in the toys-core gem
@@ -388,7 +442,7 @@ module Toys
388
442
 
389
443
  ##
390
444
  # Returns true if there is a specific description set for this tool.
391
- # @return [Boolean]
445
+ # @return [true,false]
392
446
  #
393
447
  def includes_description?
394
448
  # Source available in the toys-core gem
@@ -397,7 +451,7 @@ module Toys
397
451
  ##
398
452
  # Returns true if at least one flag or positional argument is defined
399
453
  # for this tool.
400
- # @return [Boolean]
454
+ # @return [true,false]
401
455
  #
402
456
  def includes_arguments?
403
457
  # Source available in the toys-core gem
@@ -405,7 +459,7 @@ module Toys
405
459
 
406
460
  ##
407
461
  # Returns true if this tool has any definition information.
408
- # @return [Boolean]
462
+ # @return [true,false]
409
463
  #
410
464
  def includes_definition?
411
465
  # Source available in the toys-core gem
@@ -413,7 +467,7 @@ module Toys
413
467
 
414
468
  ##
415
469
  # Returns true if this tool's definition has been finished and is locked.
416
- # @return [Boolean]
470
+ # @return [true,false]
417
471
  #
418
472
  def definition_finished?
419
473
  # Source available in the toys-core gem
@@ -421,7 +475,7 @@ module Toys
421
475
 
422
476
  ##
423
477
  # Returns true if this tool has disabled argument parsing.
424
- # @return [Boolean]
478
+ # @return [true,false]
425
479
  #
426
480
  def argument_parsing_disabled?
427
481
  # Source available in the toys-core gem
@@ -429,7 +483,7 @@ module Toys
429
483
 
430
484
  ##
431
485
  # Returns true if this tool enforces flags before args.
432
- # @return [Boolean]
486
+ # @return [true,false]
433
487
  #
434
488
  def flags_before_args_enforced?
435
489
  # Source available in the toys-core gem
@@ -437,7 +491,7 @@ module Toys
437
491
 
438
492
  ##
439
493
  # Returns true if this tool requires exact flag matches.
440
- # @return [Boolean]
494
+ # @return [true,false]
441
495
  #
442
496
  def exact_flag_match_required?
443
497
  # Source available in the toys-core gem
@@ -648,7 +702,7 @@ module Toys
648
702
  # Enforce that flags must come before args for this tool.
649
703
  # You may disable enforcement by passoing `false` for the state.
650
704
  #
651
- # @param state [Boolean]
705
+ # @param state [true,false]
652
706
  # @return [self]
653
707
  #
654
708
  def enforce_flags_before_args(state = true)
@@ -659,7 +713,7 @@ module Toys
659
713
  # Require that flags must match exactly. (If false, flags can match an
660
714
  # unambiguous substring.)
661
715
  #
662
- # @param state [Boolean]
716
+ # @param state [true,false]
663
717
  # @return [self]
664
718
  #
665
719
  def require_exact_flag_match(state = true)
@@ -686,10 +740,10 @@ module Toys
686
740
  # formats. Defaults to the empty array.
687
741
  # @param name [String,Symbol,nil] The name of the group, or nil for no
688
742
  # name.
689
- # @param report_collisions [Boolean] If `true`, raise an exception if a
743
+ # @param report_collisions [true,false] If `true`, raise an exception if a
690
744
  # the given name is already taken. If `false`, ignore. Default is
691
745
  # `true`.
692
- # @param prepend [Boolean] If `true`, prepend rather than append the
746
+ # @param prepend [true,false] If `true`, prepend rather than append the
693
747
  # group to the list. Default is `false`.
694
748
  # @return [self]
695
749
  #
@@ -733,7 +787,7 @@ module Toys
733
787
  # @param complete_values [Object] A specifier for shell tab completion
734
788
  # for flag values associated with this flag. Pass any spec
735
789
  # recognized by {Toys::Completion.create}.
736
- # @param report_collisions [Boolean] Raise an exception if a flag is
790
+ # @param report_collisions [true,false] Raise an exception if a flag is
737
791
  # requested that is already in use or marked as disabled. Default is
738
792
  # true.
739
793
  # @param group [Toys::FlagGroup,String,Symbol,nil] Group for
@@ -860,26 +914,56 @@ module Toys
860
914
  end
861
915
 
862
916
  ##
863
- # Set the run handler block
917
+ # Set the run handler.
864
918
  #
865
- # @param proc [Proc] The runnable block
919
+ # This handler is called to run the tool. Normally it is a method name,
920
+ # represented by a symbol. (The default is `:run`.) It can be set to a
921
+ # different method name, or to a proc that will be called with `self` set
922
+ # to the tool context. Either way, it takes no arguments. The run handler
923
+ # can also be explicitly set to `nil` indicating a non-runnable tool;
924
+ # however, typically a tool is made non-runnable simply by leaving the run
925
+ # handler set to `:run` and not defining the method.
866
926
  #
867
- def run_handler=(proc)
927
+ # @param handler [Proc,Symbol,nil] the run handler
928
+ #
929
+ def run_handler=(handler)
868
930
  # Source available in the toys-core gem
869
931
  end
870
932
 
871
933
  ##
872
- # Set the interrupt handler.
934
+ # Set the interrupt handler. This is equivalent to calling
935
+ # {#set_signal_handler} for the `SIGINT` signal.
873
936
  #
874
- # @param handler [Proc,Symbol] The interrupt handler
937
+ # @param handler [Proc,Symbol] The interrupt signal handler
875
938
  #
876
939
  def interrupt_handler=(handler)
877
940
  # Source available in the toys-core gem
878
941
  end
879
942
 
943
+ ##
944
+ # Set the handler for the given signal.
945
+ #
946
+ # This handler is called when the given signal is received, immediately
947
+ # taking over the execution as if it were the new `run` method. The signal
948
+ # handler can be specified as a Proc, or a Symbol indicating a method to
949
+ # call. It optionally takes the `SignalException` as the sole argument.
950
+ #
951
+ # @param signal [Integer,String,Symbol] The signal number or name
952
+ # @param handler [Proc,Symbol] The signal handler
953
+ #
954
+ def set_signal_handler(signal, handler)
955
+ # Source available in the toys-core gem
956
+ end
957
+
880
958
  ##
881
959
  # Set the usage error handler.
882
960
  #
961
+ # This handler is called when at least one usage error is detected during
962
+ # argument parsing, and is called instead of the `run` method. It can be
963
+ # specified as a Proc, or a Symbol indicating a method to call. It
964
+ # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
965
+ # argument.
966
+ #
883
967
  # @param handler [Proc,Symbol] The usage error handler
884
968
  #
885
969
  def usage_error_handler=(handler)
@@ -12,6 +12,27 @@ module Toys
12
12
  # This class is not loaded by default. Before using it directly, you should
13
13
  # `require "toys/utils/exec"`
14
14
  #
15
+ # ### The exec service
16
+ #
17
+ # The main entrypoint class is this one, {Toys::Utils::Exec}. It's a
18
+ # "service" object that provides functionality, primarily methods that
19
+ # spawn processes. Create it like any object:
20
+ #
21
+ # require "toys/utils/exec"
22
+ # exec_service = Toys::Utils::Exec.new
23
+ #
24
+ # There are two "primitive" functions: {#exec} and {#exec_proc}. The {#exec}
25
+ # method spawns an operating system process specified by an executable and
26
+ # a set of arguments. The {#exec_proc} method takes a `Proc` and forks a
27
+ # Ruby process. Both of these can be heavily configured with stream
28
+ # handling, result handling, and numerous other options described below.
29
+ # The class also provides convenience methods for common cases such as
30
+ # spawning a Ruby process, spawning a shell script, or capturing output.
31
+ #
32
+ # The exec service class also stores default configuration that it applies
33
+ # to processes it spawns. You can set these defaults when constructing the
34
+ # service class, or at any time by calling {#configure_defaults}.
35
+ #
15
36
  # ### Controlling processes
16
37
  #
17
38
  # A process can be started in the *foreground* or the *background*. If you
@@ -20,7 +41,7 @@ module Toys
20
41
  # If you start a background process, its streams will be redirected to null
21
42
  # by default, and control will be returned to you immediately.
22
43
  #
23
- # When a process is running, you can control it using a
44
+ # While a process is running, you can control it using a
24
45
  # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
25
46
  # the process's input and output streams, send it signals, or wait for it
26
47
  # to complete.
@@ -0,0 +1,184 @@
1
+ module Toys
2
+ module Utils
3
+ ##
4
+ # **_Defined in the toys-core gem_**
5
+ #
6
+ # An object that implements standard UI elements, such as error reports and
7
+ # logging, as provided by the `toys` command line. Specifically, it
8
+ # implements pretty formatting of log entries and stack traces, and renders
9
+ # using ANSI coloring where available via {Toys::Utils::Terminal}.
10
+ #
11
+ # This object can be used to implement `toys`-style behavior when creating
12
+ # a CLI object. For example:
13
+ #
14
+ # require "toys/utils/standard_ui"
15
+ # ui = Toys::Utils::StandardUI.new
16
+ # cli = Toys::CLI.new(**ui.cli_args)
17
+ #
18
+ class StandardUI
19
+ ##
20
+ # Create a Standard UI.
21
+ #
22
+ # By default, all output is written to `$stderr`, and will share a single
23
+ # {Toys::Utils::Terminal} object, allowing multiple tools and/or threads
24
+ # to interleave messages without interrupting one another.
25
+ #
26
+ # @param output [IO,Toys::Utils::Terminal] Where to write output. You can
27
+ # pass a terminal object, or an IO stream that will be wrapped in a
28
+ # terminal output. Default is `$stderr`.
29
+ #
30
+ def initialize(output: nil)
31
+ # Source available in the toys-core gem
32
+ end
33
+
34
+ ##
35
+ # The terminal underlying this UI
36
+ #
37
+ # @return [Toys::Utils::Terminal]
38
+ #
39
+ attr_reader :terminal
40
+
41
+ ##
42
+ # A hash that maps severities to styles recognized by
43
+ # {Toys::Utils::Terminal}. Used to style the header for each log entry.
44
+ # This hash can be modified in place to adjust the behavior of loggers
45
+ # created by this UI.
46
+ #
47
+ # @return [Hash{String => Array<Symbol>}]
48
+ #
49
+ attr_reader :log_header_severity_styles
50
+
51
+ ##
52
+ # Convenience method that returns a hash of arguments that can be passed
53
+ # to the {Toys::CLI} constructor. Includes the `:error_handler` and
54
+ # `:logger_factory` arguments.
55
+ #
56
+ # @return [Hash]
57
+ #
58
+ def cli_args
59
+ # Source available in the toys-core gem
60
+ end
61
+
62
+ ##
63
+ # Returns an error handler conforming to the `:error_handler` argument to
64
+ # the {Toys::CLI} constructor. Specifically, it returns the
65
+ # {#error_handler_impl} method as a proc.
66
+ #
67
+ # @return [Proc]
68
+ #
69
+ def error_handler
70
+ # Source available in the toys-core gem
71
+ end
72
+
73
+ ##
74
+ # Returns a logger factory conforming to the `:logger_factory` argument
75
+ # to the {Toys::CLI} constructor. Specifically, it returns the
76
+ # {#logger_factory_impl} method as a proc.
77
+ #
78
+ # @return [Proc]
79
+ #
80
+ def logger_factory
81
+ # Source available in the toys-core gem
82
+ end
83
+
84
+ ##
85
+ # Implementation of the error handler. As dictated by the error handler
86
+ # specification in {Toys::CLI}, this must take a {Toys::ContextualError}
87
+ # as an argument, and return an exit code.
88
+ #
89
+ # The base implementation uses {#display_error_notice} and
90
+ # {#display_signal_notice} to print an appropriate message to the UI's
91
+ # terminal, and uses {#exit_code_for} to determine the correct exit code.
92
+ # Any of those methods can be overridden by a subclass to alter their
93
+ # behavior, or this main implementation method can be overridden to
94
+ # change the overall behavior.
95
+ #
96
+ # @param error [Toys::ContextualError] The error received
97
+ # @return [Integer] The exit code
98
+ #
99
+ def error_handler_impl(error)
100
+ # Source available in the toys-core gem
101
+ end
102
+
103
+ ##
104
+ # Implementation of the logger factory. As dictated by the logger factory
105
+ # specification in {Toys::CLI}, this must take a {Toys::ToolDefinition}
106
+ # as an argument, and return a `Logger`.
107
+ #
108
+ # The base implementation returns a logger that writes to the UI's
109
+ # terminal, using {#logger_formatter_impl} as the formatter. It sets the
110
+ # level to `Logger::WARN` by default. Either this method or the helper
111
+ # methods can be overridden to change this behavior.
112
+ #
113
+ # @param _tool {Toys::ToolDefinition} The tool definition of the tool to
114
+ # be executed
115
+ # @return [Logger]
116
+ #
117
+ def logger_factory_impl(_tool)
118
+ # Source available in the toys-core gem
119
+ end
120
+
121
+ ##
122
+ # Returns an exit code appropriate for the given exception. Currently,
123
+ # the logic interprets signals (returning the convention of 128 + signo),
124
+ # usage errors (returning the conventional value of 2), and tool not
125
+ # runnable errors (returning the conventional value of 126), and defaults
126
+ # to 1 for all other error types.
127
+ #
128
+ # This method is used by {#error_handler_impl} and can be overridden to
129
+ # change its behavior.
130
+ #
131
+ # @param error [Exception] The exception raised. This method expects the
132
+ # original exception, rather than a ContextualError.
133
+ # @return [Integer] The appropriate exit code
134
+ #
135
+ def exit_code_for(error)
136
+ # Source available in the toys-core gem
137
+ end
138
+
139
+ ##
140
+ # Displays a default output for a signal received.
141
+ #
142
+ # This method is used by {#error_handler_impl} and can be overridden to
143
+ # change its behavior.
144
+ #
145
+ # @param error [SignalException]
146
+ #
147
+ def display_signal_notice(error)
148
+ # Source available in the toys-core gem
149
+ end
150
+
151
+ ##
152
+ # Displays a default output for an error. Displays the error, the
153
+ # backtrace, and contextual information regarding what tool was run and
154
+ # where in its code the error occurred.
155
+ #
156
+ # This method is used by {#error_handler_impl} and can be overridden to
157
+ # change its behavior.
158
+ #
159
+ # @param error [Toys::ContextualError]
160
+ #
161
+ def display_error_notice(error)
162
+ # Source available in the toys-core gem
163
+ end
164
+
165
+ ##
166
+ # Implementation of the formatter used by loggers created by this UI's
167
+ # logger factory. This interface is defined by the standard `Logger`
168
+ # class.
169
+ #
170
+ # This method can be overridden to change the behavior of loggers created
171
+ # by this UI.
172
+ #
173
+ # @param severity [String]
174
+ # @param time [Time]
175
+ # @param _progname [String]
176
+ # @param msg [Object]
177
+ # @return [String]
178
+ #
179
+ def logger_formatter_impl(severity, time, _progname, msg)
180
+ # Source available in the toys-core gem
181
+ end
182
+ end
183
+ end
184
+ end
@@ -12,12 +12,53 @@
12
12
  # This module contains the command line framework underlying Toys. It can be
13
13
  # used to create command line executables using the Toys DSL and classes.
14
14
  #
15
+ # ## Common starting points
16
+ #
17
+ # Some of the most commonly needed class documentation is listed below:
18
+ #
19
+ # * For information on the DSL used to write tools, start with
20
+ # {Toys::DSL::Tool}.
21
+ # * The base class for tool runtime (i.e. that defines the basic methods
22
+ # available to a tool's implementation) is {Toys::Context}.
23
+ # * For information on writing mixins, see {Toys::Mixin}.
24
+ # * For information on writing templates, see {Toys::Template}.
25
+ # * For information on writing acceptors, see {Toys::Acceptor}.
26
+ # * For information on writing custom shell completions, see {Toys::Completion}.
27
+ # * Standard mixins are defined under the {Toys::StandardMixins} module.
28
+ # * Various utilities are defined under {Toys::Utils}. Some of these serve as
29
+ # the implementations of corresponding mixins.
30
+ # * The main entrypoint for the command line framework is {Toys::CLI}.
31
+ #
32
+ # Other important internal classes are listed below.
33
+ #
34
+ # * The definition of a tool is represented by {Toys::ToolDefinition} along
35
+ # the helpers {Toys::Flag}, {Toys::PositionalArg}, and {Toys::FlagGroup}.
36
+ # * Argument parsing is implemented by {Toys::ArgParser}.
37
+ # * The process of finding and loading a tool definition given a tool name, is
38
+ # implemented by {Toys::Loader}.
39
+ # * Text wrapping is handled by {Toys::WrappableString}.
40
+ # * The settings system is implemented by {Toys::Settings}.
41
+ #
15
42
  module Toys
16
43
  ##
17
44
  # **_Defined in the toys-core gem_**
18
45
  #
19
46
  # Namespace for DSL classes. These classes provide the directives that can be
20
- # used in configuration files. Most are defined in {Toys::DSL::Tool}.
47
+ # used in configuration files.
48
+ #
49
+ # DSL directives that can appear at the top level of Toys files and tool
50
+ # blocks are defined by the {Toys::DSL::Tool} module.
51
+ #
52
+ # Directives that can appear within a block passed to {Toys::DSL::Tool#flag}
53
+ # are defined by the {Toys::DSL::Flag} class.
54
+ #
55
+ # Directives that can appear within a {Toys::DSL::Tool#flag_group} block or
56
+ # any of its related directives, are defined by the {Toys::DSL::FlagGroup}
57
+ # class.
58
+ #
59
+ # Directives that can appear within a {Toys::DSL::Tool#required_arg},
60
+ # {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args} block,
61
+ # are defined by the {Toys::DSL::PositionalArg} class.
21
62
  #
22
63
  module DSL
23
64
  end
@@ -27,6 +68,9 @@ module Toys
27
68
  #
28
69
  # Namespace for standard middleware classes.
29
70
  #
71
+ # These middleware are provided by Toys-Core and can be referenced by name
72
+ # when creating a {Toys::CLI}.
73
+ #
30
74
  module StandardMiddleware
31
75
  end
32
76
 
@@ -35,6 +79,9 @@ module Toys
35
79
  #
36
80
  # Namespace for standard mixin classes.
37
81
  #
82
+ # These mixins are provided by Toys-Core and can be included by name by
83
+ # passing a symbol to {Toys::DSL::Tool#include}.
84
+ #
38
85
  module StandardMixins
39
86
  end
40
87
 
@@ -44,8 +91,9 @@ module Toys
44
91
  # Namespace for common utility classes.
45
92
  #
46
93
  # These classes are not loaded by default, and must be required explicitly.
47
- # For example, before using {Toys::Utils::Exec}, you must
48
- # `require "toys/utils/exec"`.
94
+ # For example, before using {Toys::Utils::Exec}, you must:
95
+ #
96
+ # require "toys/utils/exec"
49
97
  #
50
98
  module Utils
51
99
  end