toys 0.15.6 → 0.16.0

data/core-docs/toys/dsl/flag.rb

@@ -1,284 +0,0 @@
-module Toys
-  module DSL
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # DSL for a flag definition block. Lets you set flag attributes in a block
-    # instead of a long series of keyword arguments.
-    #
-    # These directives are available inside a block passed to
-    # {Toys::DSL::Tool#flag}.
-    #
-    # ### Example
-    #
-    #     tool "mytool" do
-    #       flag :value do
-    #         # The directives in here are defined by this class
-    #         flags "--value=VAL"
-    #         accept Integer
-    #         desc "An integer value"
-    #       end
-    #       # ...
-    #     end
-    #
-    class Flag
-      ##
-      # Add flags in OptionParser format. This may be called multiple times,
-      # and the results are cumulative.
-      #
-      # Following are examples of valid syntax.
-      #
-      #  *  `-a` : A short boolean switch. When this appears as an argument,
-      #     the value is set to `true`.
-      #  *  `--abc` : A long boolean switch. When this appears as an argument,
-      #     the value is set to `true`.
-      #  *  `-aVAL` or `-a VAL` : A short flag that takes a required value.
-      #     These two forms are treated identically. If this argument appears
-      #     with a value attached (e.g. `-afoo`), the attached string (e.g.
-      #     `"foo"`) is taken as the value. Otherwise, the following argument
-      #     is taken as the value (e.g. for `-a foo`, the value is set to
-      #     `"foo"`.) The following argument is treated as the value even if it
-      #     looks like a flag (e.g. `-a -a` causes the string `"-a"` to be
-      #     taken as the value.)
-      #  *  `-a[VAL]` : A short flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `-afoo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the value
-      #     is set to `true`. The following argument is never interpreted as
-      #     the value. (Compare with `-a [VAL]`.)
-      #  *  `-a [VAL]` : A short flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `-afoo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, if the
-      #     following argument does not look like a flag (i.e. it does not
-      #     begin with a hyphen), it is taken as the value. (e.g. `-a foo`
-      #     causes the string `"foo"` to be taken as the value.). If there is
-      #     no following argument, or the following argument looks like a flag,
-      #     the value is set to `true`. (Compare with `-a[VAL]`.)
-      #  *  `--abc=VAL` or `--abc VAL` : A long flag that takes a required
-      #     value. These two forms are treated identically. If this argument
-      #     appears with a value attached (e.g. `--abc=foo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the
-      #     following argument is taken as the value (e.g. for `--abc foo`, the
-      #     value is set to `"foo"`.) The following argument is treated as the
-      #     value even if it looks like a flag (e.g. `--abc --def` causes the
-      #     string `"--def"` to be taken as the value.)
-      #  *  `--abc[=VAL]` : A long flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `--abc=foo`), the
-      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise,
-      #     the value is set to `true`. The following argument is never
-      #     interpreted as the value. (Compare with `--abc [VAL]`.)
-      #  *  `--abc [VAL]` : A long flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `--abc=foo`), the
-      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise, if
-      #     the following argument does not look like a flag (i.e. it does not
-      #     begin with a hyphen), it is taken as the value. (e.g. `--abc foo`
-      #     causes the string `"foo"` to be taken as the value.). If there is
-      #     no following argument, or the following argument looks like a flag,
-      #     the value is set to `true`. (Compare with `--abc=[VAL]`.)
-      #  *  `--[no-]abc` : A long boolean switch that can be turned either on
-      #     or off. This effectively creates two flags, `--abc` which sets the
-      #     value to `true`, and `--no-abc` which sets the falue to `false`.
-      #
-      # @param flags [String...]
-      # @return [self]
-      #
-      def flags(*flags)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the acceptor for this flag's values.
-      # You can pass either the string name of an acceptor defined in this tool
-      # or any of its ancestors, or any other specification recognized by
-      # {Toys::Acceptor.create}.
-      #
-      # @param spec [Object]
-      # @param options [Hash]
-      # @param block [Proc]
-      # @return [self]
-      #
-      def accept(spec = nil, **options, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the default value.
-      #
-      # @param default [Object]
-      # @return [self]
-      #
-      def default(default)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the optional handler for setting/updating the value when a flag is
-      # parsed. A handler should be a Proc taking two arguments, the new given
-      # value and the previous value, and it should return the new value that
-      # should be set. You may pass the handler as a Proc (or an object
-      # responding to the `call` method) or you may pass a block.
-      #
-      # You can also pass one of the special values `:set` or `:push` as the
-      # handler. The `:set` handler replaces the previous value (equivalent to
-      # `-> (val, _prev) { val }`.) The `:push` handler expects the previous
-      # value to be an array and pushes the given value onto it; it should be
-      # combined with setting the default value to `[]` and is intended for
-      # "multi-valued" flags.
-      #
-      # @param handler [Proc,:set,:push]
-      # @param block [Proc]
-      # @return [self]
-      #
-      def handler(handler = nil, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the shell completion strategy for flag names.
-      # You can pass one of the following:
-      #
-      #  *  The string name of a completion defined in this tool or any of its
-      #     ancestors.
-      #  *  A hash of options to pass to the constructor of
-      #     {Toys::Flag::DefaultCompletion}.
-      #  *  `nil` or `:default` to select the standard completion strategy
-      #     (which is {Toys::Flag::DefaultCompletion} with no extra options).
-      #  *  Any other specification recognized by {Toys::Completion.create}.
-      #
-      # @param spec [Object]
-      # @param options [Hash]
-      # @param block [Proc]
-      # @return [self]
-      #
-      def complete_flags(spec = nil, **options, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the shell completion strategy for flag values.
-      # You can pass either the string name of a completion defined in this
-      # tool or any of its ancestors, or any other specification recognized by
-      # {Toys::Completion.create}.
-      #
-      # @param spec [Object]
-      # @param options [Hash]
-      # @param block [Proc]
-      # @return [self]
-      #
-      def complete_values(spec = nil, **options, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set whether to raise an exception if a flag is requested that is
-      # already in use or marked as disabled.
-      #
-      # @param setting [Boolean]
-      # @return [self]
-      #
-      def report_collisions(setting)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the short description for the current flag. The short description
-      # is displayed with the flag in online help.
-      #
-      # The description is a {Toys::WrappableString}, which may be word-wrapped
-      # when displayed in a help screen. You may pass a {Toys::WrappableString}
-      # directly to this method, or you may pass any input that can be used to
-      # construct a wrappable string:
-      #
-      #  *  If you pass a String, its whitespace will be compacted (i.e. tabs,
-      #     newlines, and multiple consecutive whitespace will be turned into a
-      #     single space), and it will be word-wrapped on whitespace.
-      #  *  If you pass an Array of Strings, each string will be considered a
-      #     literal word that cannot be broken, and wrapping will be done
-      #     across the strings in the array. In this case, whitespace is not
-      #     compacted.
-      #
-      # ### Examples
-      #
-      # If you pass in a sentence as a simple string, it may be word wrapped
-      # when displayed:
-      #
-      #     desc "This sentence may be wrapped."
-      #
-      # To specify a sentence that should never be word-wrapped, pass it as the
-      # sole element of a string array:
-      #
-      #     desc ["This sentence will not be wrapped."]
-      #
-      # @param desc [String,Array<String>,Toys::WrappableString]
-      # @return [self]
-      #
-      def desc(desc)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Add to the long description for the current flag. The long description
-      # is displayed with the flag in online help. This directive may be given
-      # multiple times, and the results are cumulative.
-      #
-      # A long description is a series of descriptions, which are generally
-      # displayed in a series of lines/paragraphs. Each individual description
-      # uses the form described in the {#desc} documentation, and may be
-      # word-wrapped when displayed. To insert a blank line, include an empty
-      # string as one of the descriptions.
-      #
-      # ### Example
-      #
-      #     long_desc "This initial paragraph might get word wrapped.",
-      #               "This next paragraph is followed by a blank line.",
-      #               "",
-      #               ["This line will not be wrapped."],
-      #               ["    This indent is preserved."]
-      #     long_desc "This line is appended to the description."
-      #
-      # @param long_desc [String,Array<String>,Toys::WrappableString...]
-      # @return [self]
-      #
-      def long_desc(*long_desc)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the group. A group may be set by name or group object. Setting
-      # `nil` selects the default group.
-      #
-      # @param group [String,Symbol,Toys::FlagGroup,nil]
-      # @return [self]
-      #
-      def group(group)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the display name for this flag. This may be used in help text and
-      # error messages.
-      #
-      # @param display_name [String]
-      # @return [self]
-      #
-      def display_name(display_name)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Specify whether to add a method for this flag.
-      #
-      # Recognized values are true to force creation of a method, false to
-      # disable method creation, and nil for the default behavior. The default
-      # checks the name and adds a method if the name is a symbol representing
-      # a legal method name that starts with a letter and does not override any
-      # public method in the Ruby Object class or collide with any method
-      # directly defined in the tool class.
-      #
-      # @param value [true,false,nil]
-      #
-      def add_method(value)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/dsl/flag_group.rb

@@ -1,267 +0,0 @@
-module Toys
-  module DSL
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # DSL for a flag group definition block. Lets you create flags in a group.
-    #
-    # These directives are available inside a block passed to
-    # {Toys::DSL::Tool#flag_group}, {Toys::DSL::Tool#all_required},
-    # {Toys::DSL::Tool#at_most_one}, {Toys::DSL::Tool#at_least_one}, or
-    # {Toys::DSL::Tool#exactly_one}.
-    #
-    # ### Example
-    #
-    #     tool "login" do
-    #       all_required do
-    #         # The directives in here are defined by this class
-    #         flag :username, "--username=VAL", desc: "Set username (required)"
-    #         flag :password, "--password=VAL", desc: "Set password (required)"
-    #       end
-    #       # ...
-    #     end
-    #
-    class FlagGroup
-      ##
-      # Add a flag to the current group. Each flag must specify a key which
-      # the script may use to obtain the flag value from the context.
-      # You may then provide the flags themselves in OptionParser form.
-      #
-      # If the given key is a symbol representing a valid method name, then a
-      # helper method is automatically added to retrieve the value. Otherwise,
-      # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Context#get}.
-      #
-      # Attributes of the flag may be passed in as arguments to this method, or
-      # set in a block passed to this method. If you provide a block, you can
-      # use directives in {Toys::DSL::Flag} within the block.
-      #
-      # ### Flag syntax
-      #
-      # The flags themselves should be provided in OptionParser form. Following
-      # are examples of valid syntax.
-      #
-      #  *  `-a` : A short boolean switch. When this appears as an argument,
-      #     the value is set to `true`.
-      #  *  `--abc` : A long boolean switch. When this appears as an argument,
-      #     the value is set to `true`.
-      #  *  `-aVAL` or `-a VAL` : A short flag that takes a required value.
-      #     These two forms are treated identically. If this argument appears
-      #     with a value attached (e.g. `-afoo`), the attached string (e.g.
-      #     `"foo"`) is taken as the value. Otherwise, the following argument
-      #     is taken as the value (e.g. for `-a foo`, the value is set to
-      #     `"foo"`.) The following argument is treated as the value even if it
-      #     looks like a flag (e.g. `-a -a` causes the string `"-a"` to be
-      #     taken as the value.)
-      #  *  `-a[VAL]` : A short flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `-afoo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the value
-      #     is set to `true`. The following argument is never interpreted as
-      #     the value. (Compare with `-a [VAL]`.)
-      #  *  `-a [VAL]` : A short flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `-afoo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, if the
-      #     following argument does not look like a flag (i.e. it does not
-      #     begin with a hyphen), it is taken as the value. (e.g. `-a foo`
-      #     causes the string `"foo"` to be taken as the value.). If there is
-      #     no following argument, or the following argument looks like a flag,
-      #     the value is set to `true`. (Compare with `-a[VAL]`.)
-      #  *  `--abc=VAL` or `--abc VAL` : A long flag that takes a required
-      #     value. These two forms are treated identically. If this argument
-      #     appears with a value attached (e.g. `--abc=foo`), the attached
-      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the
-      #     following argument is taken as the value (e.g. for `--abc foo`, the
-      #     value is set to `"foo"`.) The following argument is treated as the
-      #     value even if it looks like a flag (e.g. `--abc --def` causes the
-      #     string `"--def"` to be taken as the value.)
-      #  *  `--abc[=VAL]` : A long flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `--abc=foo`), the
-      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise,
-      #     the value is set to `true`. The following argument is never
-      #     interpreted as the value. (Compare with `--abc [VAL]`.)
-      #  *  `--abc [VAL]` : A long flag that takes an optional value. If this
-      #     argument appears with a value attached (e.g. `--abc=foo`), the
-      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise, if
-      #     the following argument does not look like a flag (i.e. it does not
-      #     begin with a hyphen), it is taken as the value. (e.g. `--abc foo`
-      #     causes the string `"foo"` to be taken as the value.). If there is
-      #     no following argument, or the following argument looks like a flag,
-      #     the value is set to `true`. (Compare with `--abc=[VAL]`.)
-      #  *  `--[no-]abc` : A long boolean switch that can be turned either on
-      #     or off. This effectively creates two flags, `--abc` which sets the
-      #     value to `true`, and `--no-abc` which sets the falue to `false`.
-      #
-      # ### Default flag syntax
-      #
-      # If no flag syntax strings are provided, a default syntax will be
-      # inferred based on the key and other options.
-      #
-      # Specifically, if the key has one character, then that character will be
-      # chosen as a short flag. If the key has multiple characters, a long flag
-      # will be generated.
-      #
-      # Furthermore, if a custom completion, a non-boolean acceptor, or a
-      # non-boolean default value is provided in the options, then the flag
-      # will be considered to take a value. Otherwise, it will be considered to
-      # be a boolean switch.
-      #
-      # For example, the following pairs of flags are identical:
-      #
-      #     flag :a
-      #     flag :a, "-a"
-      #
-      #     flag :abc_def
-      #     flag :abc_def, "--abc-def"
-      #
-      #     flag :number, accept: Integer
-      #     flag :number, "--number=VAL", accept: Integer
-      #
-      # ### More examples
-      #
-      # A flag that sets its value to the number of times it appears on the
-      # command line:
-      #
-      #     flag :verbose, "-v", "--verbose",
-      #          default: 0, handler: ->(_val, count) { count + 1 }
-      #
-      # An example using block form:
-      #
-      #     flag :shout do
-      #       flags "-s", "--shout"
-      #       default false
-      #       desc "Say it louder"
-      #       long_desc "This flag says it lowder.",
-      #                 "You might use this when people can't hear you.",
-      #                 "",
-      #                 "Example:",
-      #                 ["    toys say --shout hello"]
-      #     end
-      #
-      # @param key [String,Symbol] The key to use to retrieve the value from
-      #     the execution context.
-      # @param flags [String...] The flags in OptionParser format.
-      # @param accept [Object] An acceptor that validates and/or converts the
-      #     value. You may provide either the name of an acceptor you have
-      #     defined, or one of the default acceptors provided by OptionParser.
-      #     Optional. If not specified, accepts any value as a string.
-      # @param default [Object] The default value. This is the value that will
-      #     be set in the context if this flag is not provided on the command
-      #     line. Defaults to `nil`.
-      # @param handler [Proc,nil,:set,:push] An optional handler for
-      #     setting/updating the value. A handler is a proc taking two
-      #     arguments, the given value and the previous value, returning the
-      #     new value that should be set. You may also specify a predefined
-      #     named handler. The `:set` handler (the default) replaces the
-      #     previous value (effectively `-> (val, _prev) { val }`). The
-      #     `:push` handler expects the previous value to be an array and
-      #     pushes the given value onto it; it should be combined with setting
-      #     `default: []` and is intended for "multi-valued" flags.
-      # @param complete_flags [Object] A specifier for shell tab completion
-      #     for flag names associated with this flag. By default, a
-      #     {Toys::Flag::DefaultCompletion} is used, which provides the flag's
-      #     names as completion candidates. To customize completion, set this
-      #     to the name of a previously defined completion, a hash of options
-      #     to pass to the constructor for {Toys::Flag::DefaultCompletion}, or
-      #     any other spec recognized by {Toys::Completion.create}.
-      # @param complete_values [Object] A specifier for shell tab completion
-      #     for flag values associated with this flag. This is the empty
-      #     completion by default. To customize completion, set this to the
-      #     name of a previously defined completion, or any spec recognized by
-      #     {Toys::Completion.create}.
-      # @param report_collisions [Boolean] Raise an exception if a flag is
-      #     requested that is already in use or marked as unusable. Default is
-      #     true.
-      # @param desc [String,Array<String>,Toys::WrappableString] Short
-      #     description for the flag. See {Toys::DSL::Tool#desc} for a
-      #     description of the allowed formats. Defaults to the empty string.
-      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-      #     Long description for the flag. See {Toys::DSL::Tool#long_desc} for
-      #     a description of the allowed formats. (But note that this param
-      #     takes an Array of description lines, rather than a series of
-      #     arguments.) Defaults to the empty array.
-      # @param display_name [String] A display name for this flag, used in help
-      #     text and error messages.
-      # @param add_method [true,false,nil] Whether to add a method for this
-      #     flag. If omitted or set to nil, uses the default behavior, which
-      #     adds the method if the key is a symbol representing a legal method
-      #     name that starts with a letter and does not override any public
-      #     method in the Ruby Object class or collide with any method directly
-      #     defined in the tool class.
-      # @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
-      #     directives that can be called in this block.
-      # @return [self]
-      #
-      def flag(key, *flags,
-               accept: nil, default: nil, handler: nil,
-               complete_flags: nil, complete_values: nil,
-               report_collisions: true, desc: nil, long_desc: nil,
-               display_name: nil, add_method: nil,
-               &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Set the short description for the current flag group. The short
-      # description is displayed as the group title in online help.
-      #
-      # The description is a {Toys::WrappableString}, which may be word-wrapped
-      # when displayed in a help screen. You may pass a {Toys::WrappableString}
-      # directly to this method, or you may pass any input that can be used to
-      # construct a wrappable string:
-      #
-      #  *  If you pass a String, its whitespace will be compacted (i.e. tabs,
-      #     newlines, and multiple consecutive whitespace will be turned into a
-      #     single space), and it will be word-wrapped on whitespace.
-      #  *  If you pass an Array of Strings, each string will be considered a
-      #     literal word that cannot be broken, and wrapping will be done
-      #     across the strings in the array. In this case, whitespace is not
-      #     compacted.
-      #
-      # ### Examples
-      #
-      # If you pass in a sentence as a simple string, it may be word wrapped
-      # when displayed:
-      #
-      #     desc "This sentence may be wrapped."
-      #
-      # To specify a sentence that should never be word-wrapped, pass it as the
-      # sole element of a string array:
-      #
-      #     desc ["This sentence will not be wrapped."]
-      #
-      # @param desc [String,Array<String>,Toys::WrappableString]
-      # @return [self]
-      #
-      def desc(desc)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Add to the long description for the current flag group. The long
-      # description is displayed with the flag group in online help. This
-      # directive may be given multiple times, and the results are cumulative.
-      #
-      # A long description is a series of descriptions, which are generally
-      # displayed in a series of lines/paragraphs. Each individual description
-      # uses the form described in the {#desc} documentation, and may be
-      # word-wrapped when displayed. To insert a blank line, include an empty
-      # string as one of the descriptions.
-      #
-      # ### Example
-      #
-      #     long_desc "This initial paragraph might get word wrapped.",
-      #               "This next paragraph is followed by a blank line.",
-      #               "",
-      #               ["This line will not be wrapped."],
-      #               ["    This indent is preserved."]
-      #     long_desc "This line is appended to the description."
-      #
-      # @param long_desc [String,Array<String>,Toys::WrappableString...]
-      # @return [self]
-      #
-      def long_desc(*long_desc)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/dsl/internal.rb

@@ -1,4 +0,0 @@
-module Toys
-  module DSL
-  end
-end