toys-core 0.6.1 → 0.7.0

data/lib/toys/dsl/flag.rb

@@ -40,14 +40,17 @@ module Toys
     #
     class Flag
       ## @private
-      def initialize(flags, accept, default, handler, report_collisions, desc, long_desc)
+      def initialize(flags, accept, default, handler, report_collisions,
+                     group, desc, long_desc, display_name)
         @flags = flags
         @accept = accept
         @default = default
         @handler = handler
         @report_collisions = report_collisions
+        @group = group
         @desc = desc
         @long_desc = long_desc || []
+        @display_name = display_name
       end
 
       ##
@@ -55,7 +58,7 @@ module Toys
       # and the results are cumulative.
       #
       # @param [String...] flags
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def flags(*flags)
         @flags += flags
@@ -66,7 +69,7 @@ module Toys
       # Set the OptionParser acceptor.
       #
       # @param [Object] accept
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def accept(accept)
         @accept = accept
@@ -77,7 +80,7 @@ module Toys
       # Set the default value.
       #
       # @param [Object] default
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def default(default)
         @default = default
@@ -92,7 +95,7 @@ module Toys
       # responding to the `call` method) or you may pass a block.
       #
       # @param [Proc] handler
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def handler(handler = nil, &block)
         @handler = handler || block
@@ -104,7 +107,7 @@ module Toys
       # already in use or marked as disabled.
       #
       # @param [Boolean] setting
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def report_collisions(setting)
         @report_collisions = setting
@@ -116,7 +119,7 @@ module Toys
       # formats.
       #
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def desc(desc)
         @desc = desc
@@ -129,19 +132,42 @@ module Toys
       # allowed formats.
       #
       # @param [String,Array<String>,Toys::Utils::WrappableString...] long_desc
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [Toys::DSL::Flag] self, for chaining.
       #
       def long_desc(*long_desc)
         @long_desc += long_desc
         self
       end
 
+      ##
+      # Set the group. A group may be set by name or group object. Setting
+      # `nil` selects the default group.
+      #
+      # @param [String,Symbol,Toys::Definition::FlagGroup,nil] group
+      # @return [Toys::DSL::Flag] self, for chaining.
+      #
+      def group(group)
+        @group = group
+        self
+      end
+
+      ##
+      # Set the display name. This may be used in help text and error messages.
+      #
+      # @param [String] display_name
+      # @return [Toys::DSL::Flag] self, for chaining.
+      #
+      def display_name(display_name)
+        @display_name = display_name
+        self
+      end
+
       ## @private
       def _add_to(tool, key)
         tool.add_flag(key, @flags,
                       accept: @accept, default: @default, handler: @handler,
-                      report_collisions: @report_collisions,
-                      desc: @desc, long_desc: @long_desc)
+                      report_collisions: @report_collisions, group: @group,
+                      desc: @desc, long_desc: @long_desc, display_name: @display_name)
       end
     end
   end

data/lib/toys/dsl/flag_group.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+;
+
+module Toys
+  module DSL
+    ##
+    # 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} and related methods.
+    #
+    class FlagGroup
+      ## @private
+      def initialize(tool_dsl, tool_definition, flag_group)
+        @tool_dsl = tool_dsl
+        @tool_definition = tool_definition
+        @flag_group = flag_group
+      end
+
+      ##
+      # Add a flag to the current tool. 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::Tool#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.
+      #
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
+      # @param [String...] flags The flags in OptionParser format.
+      # @param [Object] accept 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 [Object] default 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 [Proc,nil] handler An optional handler for setting/updating the
+      #     value. If given, it should take two arguments, the new given value
+      #     and the previous value, and it should return the new value that
+      #     should be set. The default handler simply replaces the previous
+      #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
+      # @param [Boolean] report_collisions Raise an exception if a flag is
+      #     requested that is already in use or marked as unusable. Default is
+      #     true.
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the flag. See {Toys::DSL::Tool#desc} for a
+      #     description of the allowed formats. Defaults to the empty string.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     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 [String] display_name A display name for this flag, used in help
+      #     text and error messages.
+      # @yieldparam flag_dsl [Toys::DSL::Flag] An object that lets you
+      #     configure this flag in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def flag(key, *flags,
+               accept: nil, default: nil, handler: nil,
+               report_collisions: true,
+               desc: nil, long_desc: nil, display_name: nil,
+               &block)
+        flag_dsl = DSL::Flag.new(flags, accept, default, handler, report_collisions,
+                                 @flag_group, desc, long_desc, display_name)
+        flag_dsl.instance_exec(flag_dsl, &block) if block
+        flag_dsl._add_to(@tool_definition, key)
+        DSL::Tool.maybe_add_getter(@tool_dsl, key)
+        self
+      end
+    end
+  end
+end

data/lib/toys/dsl/tool.rb

@@ -324,6 +324,174 @@ module Toys
         self
       end
 
+      ##
+      # Create a flag group. If a block is given, flags defined in the block
+      # belong to the group. The flags in the group are listed together in
+      # help screens.
+      #
+      # Example:
+      #
+      #     flag_group desc: "Debug Flags" do
+      #       flag :debug, "-D", desc: "Enable debugger"
+      #       flag :warnings, "-W[VAL]", desc: "Enable warnings"
+      #     end
+      #
+      # @param [Symbol] type The type of group. Allowed values: `:required`,
+      #     `:optional`, `:exactly_one`, `:at_most_one`, `:at_least_one`.
+      #     Default is `:optional`.
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
+      #     add flags to this group in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def flag_group(type: :optional, desc: nil, long_desc: nil, name: nil,
+                     report_collisions: true, prepend: false, &block)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        return self if cur_tool.nil?
+        cur_tool.add_flag_group(type: type, desc: desc, long_desc: long_desc, name: name,
+                                report_collisions: report_collisions, prepend: prepend)
+        group = prepend ? cur_tool.flag_groups.first : cur_tool.flag_groups.last
+        flag_group_dsl = DSL::FlagGroup.new(self, cur_tool, group)
+        flag_group_dsl.instance_exec(flag_group_dsl, &block) if block
+        self
+      end
+
+      ##
+      # Create a flag group of type `:required`. If a block is given, flags
+      # defined in the block belong to the group. All flags in this group are
+      # required.
+      #
+      # Example:
+      #
+      #     all_required do
+      #       flag :username, "--username=VAL", desc: "Set the username (required)"
+      #       flag :password, "--password=VAL", desc: "Set the password (required)"
+      #     end
+      #
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
+      #     add flags to this group in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def all_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                       prepend: false, &block)
+        flag_group(type: :required, desc: desc, long_desc: long_desc,
+                   name: name, report_collisions: report_collisions, prepend: prepend, &block)
+      end
+
+      ##
+      # Create a flag group of type `:at_most_one`. If a block is given, flags
+      # defined in the block belong to the group. At most one flag in this
+      # group must be provided on the command line.
+      #
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
+      #     add flags to this group in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def at_most_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                               prepend: false, &block)
+        flag_group(type: :at_most_one, desc: desc, long_desc: long_desc,
+                   name: name, report_collisions: report_collisions, prepend: prepend, &block)
+      end
+
+      ##
+      # Create a flag group of type `:at_least_one`. If a block is given, flags
+      # defined in the block belong to the group. At least one flag in this
+      # group must be provided on the command line.
+      #
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
+      #     add flags to this group in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def at_least_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                                prepend: false, &block)
+        flag_group(type: :at_least_one, desc: desc, long_desc: long_desc,
+                   name: name, report_collisions: report_collisions, prepend: prepend, &block)
+      end
+
+      ##
+      # Create a flag group of type `:exactly_one`. If a block is given, flags
+      # defined in the block belong to the group. Exactly one flag in this
+      # group must be provided on the command line.
+      #
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
+      #     add flags to this group in a block.
+      # @return [Toys::DSL::Tool] self, for chaining.
+      #
+      def exactly_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                               prepend: false, &block)
+        flag_group(type: :exactly_one, desc: desc, long_desc: long_desc,
+                   name: name, report_collisions: report_collisions, prepend: prepend, &block)
+      end
+
       ##
       # Add a flag to the current tool. Each flag must specify a key which
       # the script may use to obtain the flag value from the context.
@@ -356,6 +524,9 @@ module Toys
       # @param [Boolean] report_collisions Raise an exception if a flag is
       #     requested that is already in use or marked as unusable. Default is
       #     true.
+      # @param [Toys::Definition::FlagGroup,String,Symbol,nil] group Group for
+      #     this flag. You may provide a group name, a FlagGroup object, or
+      #     `nil` which denotes the default group.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
       #     description for the flag. See {Toys::DSL::Tool#desc} for a
       #     description of the allowed formats. Defaults to the empty string.
@@ -364,19 +535,21 @@ module Toys
       #     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 [String] display_name A display name for this flag, used in help
+      #     text and error messages.
       # @yieldparam flag_dsl [Toys::DSL::Flag] An object that lets you
       #     configure this flag in a block.
       # @return [Toys::DSL::Tool] self, for chaining.
       #
       def flag(key, *flags,
                accept: nil, default: nil, handler: nil,
-               report_collisions: true,
-               desc: nil, long_desc: nil,
+               report_collisions: true, group: nil,
+               desc: nil, long_desc: nil, display_name: nil,
                &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        flag_dsl = DSL::Flag.new(flags, accept, default, handler,
-                                 report_collisions, desc, long_desc)
+        flag_dsl = DSL::Flag.new(flags, accept, default, handler, report_collisions,
+                                 group, desc, long_desc, display_name)
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
         DSL::Tool.maybe_add_getter(self, key)

data/lib/toys/runner.rb

@@ -88,8 +88,9 @@ module Toys
     end
 
     def parse_args(args, data)
-      optparse = create_option_parser(data)
+      optparse, seen = create_option_parser(data)
       remaining = optparse.parse(args)
+      validate_flags(args, seen)
       remaining = parse_required_args(remaining, args, data)
       remaining = parse_optional_args(remaining, data)
       parse_remaining_args(remaining, args, data)
@@ -98,6 +99,7 @@ module Toys
     end
 
     def create_option_parser(data)
+      seen = []
       optparse = ::OptionParser.new
       # The following clears out the Officious (hidden default flags).
       optparse.remove
@@ -106,13 +108,21 @@ module Toys
       optparse.new
       @tool_definition.flag_definitions.each do |flag|
         optparse.on(*flag.optparser_info) do |val|
+          seen << flag.key
           data[flag.key] = flag.handler.call(val, data[flag.key])
         end
       end
       @tool_definition.custom_acceptors do |accept|
         optparse.accept(accept)
       end
-      optparse
+      [optparse, seen]
+    end
+
+    def validate_flags(args, seen)
+      @tool_definition.flag_groups.each do |group|
+        error = group.validation_error(seen)
+        raise create_parse_error(args, error) if error
+      end
     end
 
     def parse_required_args(remaining, args, data)
@@ -148,7 +158,7 @@ module Toys
     end
 
     def create_parse_error(path, reason)
-      OptionParser::ParseError.new(*path).tap do |e|
+      ::OptionParser::ParseError.new(*path).tap do |e|
         e.reason = reason
       end
     end