toys-core 0.3.2

data/lib/toys/config_dsl.rb

@@ -0,0 +1,356 @@
+# 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
+  ##
+  # This class defines the DSL for a toys configuration file.
+  #
+  # A toys configuration defines one or more named tools. It provides syntax
+  # for setting the description, defining switches and arguments, specifying
+  # how to execute the tool, and requesting helper modules and other services.
+  # It also lets you define subtools, nested arbitrarily deep, using blocks.
+  #
+  # Generally ConfigDSL is invoked from the {Loader}. Applications should not
+  # need to create instances of ConfigDSL directly.
+  #
+  # ## Simple example
+  #
+  # Create a file called `.toys.rb` in the current directory, with the
+  # following contents:
+  #
+  #     tool "greet" do
+  #       desc "Prints a simple greeting"
+  #
+  #       optional_arg :recipient, default: "world"
+  #
+  #       execute do
+  #         puts "Hello, #{self[:recipient]}!"
+  #       end
+  #     end
+  #
+  # Now you can execute it using:
+  #
+  #     toys greet
+  #
+  # or try:
+  #
+  #     toys greet rubyists
+  #
+  class ConfigDSL
+    ##
+    # Create an instance of the DSL.
+    # @private
+    #
+    # @param [Array<String>] words Full name of the current tool.
+    # @param [Array<String>,nil] remaining_words Arguments remaining in the
+    #     current lookup.
+    # @param [Integer] priority Priority of this configuration
+    # @param [Toys::Loader] loader Current active loader
+    # @param [String] path The path to the config file being evaluated
+    #
+    # @return [Toys::ConfigDSL]
+    #
+    def initialize(words, remaining_words, priority, loader, path)
+      @words = words
+      @remaining_words = remaining_words
+      @priority = priority
+      @loader = loader
+      @path = path
+    end
+
+    ##
+    # Create a subtool. You must provide a block defining the subtool.
+    #
+    # If the subtool is already defined (either as a tool or a group), the old
+    # definition is discarded and replaced with the new definition. If the old
+    # tool was a group, all its descendants are also discarded, recursively.
+    #
+    # @param [String] word The name of the subtool
+    #
+    def tool(word, &block)
+      word = word.to_s
+      subtool_words = @words + [word]
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      ConfigDSL.evaluate(subtool_words, next_remaining, @priority, @loader, @path, block)
+      self
+    end
+    alias name tool
+
+    ##
+    # Create an alias in the current group.
+    #
+    # @param [String] word The name of the alias
+    # @param [String] target The target of the alias
+    #
+    def alias_tool(word, target)
+      @loader.make_alias(@words + [word.to_s], @words + [target.to_s], @priority)
+      self
+    end
+
+    ##
+    # Create an alias of the current tool.
+    #
+    # @param [String] word The name of the alias
+    #
+    def alias_as(word)
+      if @words.empty?
+        raise ToolDefinitionError, "Cannot make an alias of the root."
+      end
+      @loader.make_alias(@words[0..-2] + [word.to_s], @words, @priority)
+      self
+    end
+
+    ##
+    # Include another config file or directory at the current location.
+    #
+    # @param [String] path The file or directory to include.
+    #
+    def include(path)
+      @loader.include_path(path, @words, @remaining_words, @priority)
+      self
+    end
+
+    ##
+    # Expand the given template in the current location.
+    #
+    # The template may be specified as a class or a well-known template name.
+    # You may also provide arguments to pass to the template.
+    #
+    # @param [Class,String,Symbol] template_class The template, either as a
+    #     class or a well-known name.
+    # @param [Object...] args Template arguments
+    #
+    def expand(template_class, *args)
+      unless template_class.is_a?(::Class)
+        name = template_class.to_s
+        template_class = Templates.lookup(name)
+        if template_class.nil?
+          raise ToolDefinitionError, "Template not found: #{name.inspect}"
+        end
+      end
+      template = template_class.new(*args)
+      yield template if block_given?
+      instance_exec(template, &template_class.expander)
+      self
+    end
+
+    ##
+    # Set the long description for the current tool. The long description is
+    # displayed in the usage documentation for the tool itself.
+    #
+    # @param [String] desc The long description string.
+    #
+    def long_desc(desc)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.long_desc = desc
+      self
+    end
+
+    ##
+    # Set the short description for the current tool. The short description is
+    # displayed with the tool in a command list. You may also use the
+    # equivalent method `short_desc`.
+    #
+    # @param [String] desc The short description string.
+    #
+    def desc(desc)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.desc = desc
+      self
+    end
+    alias short_desc desc
+
+    ##
+    # Add a switch to the current tool. Each switch must specify a key which
+    # the executor may use to obtain the switch value from the context.
+    # You may then provide the switches themselves in `OptionParser` form.
+    #
+    # @param [Symbol] key The key to use to retrieve the value from the
+    #     execution context.
+    # @param [String...] switches The switches in OptionParser format.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] default The default value. This is the value that will
+    #     be set in the context if this switch is not provided on the command
+    #     line. Defaults to `nil`.
+    # @param [String,nil] doc The documentation for the switch, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    # @param [Boolean] only_unique If true, any switches that are already
+    #     defined in this tool are removed from this switch. For example, if
+    #     an earlier switch uses `-a`, and this switch wants to use both
+    #     `-a` and `-b`, then only `-b` will be assigned to this switch.
+    #     Defaults to false.
+    # @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 }`.
+    #
+    def switch(key, *switches,
+               accept: nil, default: nil, doc: nil, only_unique: false, handler: nil)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.add_switch(key, *switches,
+                           accept: accept, default: default, doc: doc,
+                           only_unique: only_unique, handler: handler)
+      self
+    end
+
+    ##
+    # Add a required positional argument to the current tool. You must specify
+    # a key which the executor may use to obtain the argument value from the
+    # context.
+    #
+    # @param [Symbol] key The key to use to retrieve the value from the
+    #     execution context.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [String,nil] doc The documentation for the switch, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    #
+    def required_arg(key, accept: nil, doc: nil)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.add_required_arg(key, accept: accept, doc: doc)
+      self
+    end
+
+    ##
+    # Add an optional positional argument to the current tool. You must specify
+    # a key which the executor may use to obtain the argument value from the
+    # context. If an optional argument is not given on the command line, the
+    # value is set to the given default.
+    #
+    # @param [Symbol] key The key to use to retrieve the value from the
+    #     execution context.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] default The default value. This is the value that will
+    #     be set in the context if this argument is not provided on the command
+    #     line. Defaults to `nil`.
+    # @param [String,nil] doc The documentation for the argument, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    #
+    def optional_arg(key, accept: nil, default: nil, doc: nil)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.add_optional_arg(key, accept: accept, default: default, doc: doc)
+      self
+    end
+
+    ##
+    # Specify what should be done with unmatched positional arguments. You must
+    # specify a key which the executor may use to obtain the remaining args
+    # from the context.
+    #
+    # @param [Symbol] key The key to use to retrieve the value from the
+    #     execution context.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] default The default value. This is the value that will
+    #     be set in the context if no unmatched arguments are provided on the
+    #     command line. Defaults to the empty array `[]`.
+    # @param [String,nil] doc The documentation for the remaining arguments,
+    #     which appears in the usage documentation. Defaults to `nil` for no
+    #     documentation.
+    #
+    def remaining_args(key, accept: nil, default: [], doc: nil)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.set_remaining_args(key, accept: accept, default: default, doc: doc)
+      self
+    end
+
+    ##
+    # Specify the executor for this tool. This is a block that will be called,
+    # with `self` set to a {Toys::Context}.
+    #
+    def execute(&block)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.executor = block
+      self
+    end
+
+    ##
+    # Define a helper method that may be called from this tool's executor.
+    # You must provide a name for the method, and a block for the method
+    # definition.
+    #
+    # @param [String,Symbol] name Name of the method. May not begin with an
+    #     underscore.
+    #
+    def helper(name, &block)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.add_helper(name, &block)
+      self
+    end
+
+    ##
+    # Specify that the given module should be mixed in to this tool's executor.
+    # Effectively, the module is added to the {Toys::Context} object.
+    # You may either provide a module directly, or specify the name of a
+    # well-known module.
+    #
+    # @param [Module,Symbol] mod Module or name of well-known module.
+    #
+    def use(mod)
+      return self if _cur_tool.nil?
+      _cur_tool.definition_path = @path
+      _cur_tool.use_module(mod)
+      self
+    end
+
+    ## @private
+    def _binding
+      binding
+    end
+
+    ## @private
+    def _cur_tool
+      unless defined? @_cur_tool
+        @_cur_tool = @loader.get_or_create_tool(@words, priority: @priority)
+      end
+      @_cur_tool
+    end
+
+    ## @private
+    def self.evaluate(words, remaining_words, priority, loader, path, source)
+      dsl = new(words, remaining_words, priority, loader, path)
+      case source
+      when String
+        # rubocop:disable Security/Eval
+        eval(source, dsl._binding, path, 1)
+        # rubocop:enable Security/Eval
+      when ::Proc
+        dsl.instance_eval(&source)
+      end
+      nil
+    end
+  end
+end

data/lib/toys/context.rb

@@ -0,0 +1,278 @@
+# 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.
+;
+
+require "logger"
+
+module Toys
+  ##
+  # The object context in effect during the execution of a tool.
+  #
+  # The context is generally a hash of key-value pairs.
+  # Keys that begin with two underscores are reserved common elements of the
+  # context such as the tool being executed, or the verbosity level.
+  # Other keys are available for use by your tool. Generally, they are set
+  # by switches and arguments in your tool. Context values may also be set
+  # by middleware. By convention, middleware-set keys begin with a single
+  # underscore.
+  #
+  class Context
+    ##
+    # Context key for the verbosity value. Verbosity is an integer defaulting
+    # to 0, with higher values meaning more verbose and lower meaning quieter.
+    # @return [Symbol]
+    #
+    VERBOSITY = :__verbosity
+
+    ##
+    # Context key for the `Toys::Tool` object being executed.
+    # @return [Symbol]
+    #
+    TOOL = :__tool
+
+    ##
+    # Context key for the full name of the tool being executed. Value is an
+    # array of strings.
+    # @return [Symbol]
+    #
+    TOOL_NAME = :__tool_name
+
+    ##
+    # Context key for the active `Toys::Loader` object.
+    # @return [Symbol]
+    #
+    LOADER = :__loader
+
+    ##
+    # Context key for the active `Logger` object.
+    # @return [Symbol]
+    #
+    LOGGER = :__logger
+
+    ##
+    # Context key for the name of the toys binary. Value is a string.
+    # @return [Symbol]
+    #
+    BINARY_NAME = :__binary_name
+
+    ##
+    # Context key for the argument list passed to the current tool. Value is
+    # an array of strings.
+    # @return [Symbol]
+    #
+    ARGS = :__args
+
+    ##
+    # Context key for the usage error raised. Value is a string if there was
+    # an error, or nil if there was no error.
+    # @return [Symbol]
+    #
+    USAGE_ERROR = :__usage_error
+
+    ##
+    # Context key for whether nonzero exit codes from subprocesses should cause
+    # an immediate exit. Value is a truthy or falsy value.
+    # @return [Symbol]
+    #
+    EXIT_ON_NONZERO_STATUS = :__exit_on_nonzero_status
+
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    # @private
+    #
+    # @param [Toys::CLI] cli
+    # @param [Hash] data
+    #
+    def initialize(cli, data)
+      @_cli = cli
+      @_data = data
+      @_data[LOADER] = cli.loader
+      @_data[BINARY_NAME] = cli.binary_name
+      @_data[LOGGER] = cli.logger
+    end
+
+    ##
+    # Return the verbosity as an integer.
+    # @return [Integer]
+    #
+    def verbosity
+      @_data[VERBOSITY]
+    end
+
+    ##
+    # Return the tool being executed.
+    # @return [Toys::Tool]
+    #
+    def tool
+      @_data[TOOL]
+    end
+
+    ##
+    # Return the name of the tool being executed, as an array of strings.
+    # @return [Array[String]]
+    #
+    def tool_name
+      @_data[TOOL_NAME]
+    end
+
+    ##
+    # Return the raw arguments passed to the tool, as an array of strings.
+    # This does not include the tool name itself.
+    # @return [Array[String]]
+    #
+    def args
+      @_data[ARGS]
+    end
+
+    ##
+    # Return any usage error detected during argument parsing, or `nil` if
+    # no error was detected.
+    # @return [String,nil]
+    #
+    def usage_error
+      @_data[USAGE_ERROR]
+    end
+
+    ##
+    # Return the logger for this execution.
+    # @return [Logger]
+    #
+    def logger
+      @_data[LOGGER]
+    end
+
+    ##
+    # Return the active loader that can be used to get other tools.
+    # @return [Toys::Loader]
+    #
+    def loader
+      @_data[LOADER]
+    end
+
+    ##
+    # Return the name of the binary that was executed.
+    # @return [String]
+    #
+    def binary_name
+      @_data[BINARY_NAME]
+    end
+
+    ##
+    # Return an option or other piece of data by key.
+    #
+    # @param [Symbol] key
+    # @return [Object]
+    #
+    def [](key)
+      @_data[key]
+    end
+    alias get []
+
+    ##
+    # Set an option or other piece of data by key.
+    #
+    # @param [Symbol] key
+    # @param [Object] value
+    #
+    def []=(key, value)
+      @_data[key] = value
+    end
+
+    ##
+    # Set an option or other piece of data by key.
+    #
+    # @param [Symbol] key
+    # @param [Object] value
+    #
+    def set(key, value = nil)
+      if key.is_a?(::Hash)
+        @_data.merge!(key)
+      else
+        @_data[key] = value
+      end
+      self
+    end
+
+    ##
+    # Returns the subset of the context that does not include well-known keys
+    # such as tool and verbosity. Technically, this includes all keys that do
+    # not begin with two underscores.
+    #
+    # @return [Hash]
+    #
+    def options
+      @_data.select do |k, _v|
+        !k.is_a?(::Symbol) || !k.to_s.start_with?("__")
+      end
+    end
+
+    ##
+    # Execute another tool, given by the provided arguments.
+    #
+    # @param [String...] args Command line arguments defining another tool
+    #     to run, along with parameters and switches.
+    # @param [Toys::CLI,nil] cli The CLI to use to execute the tool. If `nil`
+    #     (the default), uses the current CLI.
+    # @param [Boolean] exit_on_nonzero_status If true, exit immediately if the
+    #     run returns a nonzero error code.
+    # @return [Integer] The resulting status code
+    #
+    def run(*args, cli: nil, exit_on_nonzero_status: nil)
+      cli ||= @_cli
+      exit_on_nonzero_status = @_data[EXIT_ON_NONZERO_STATUS] if exit_on_nonzero_status.nil?
+      code = cli.run(args.flatten, verbosity: @_data[VERBOSITY])
+      exit(code) if exit_on_nonzero_status && !code.zero?
+      code
+    end
+
+    ##
+    # Return a new CLI with the same settings as the currnet CLI but no paths.
+    # This can be used to run a toys "sub-instance". Add any new paths to the
+    # returned CLI, then call {#run}, passing in the CLI, to execute a tool.
+    #
+    # @return [Toys::CLI]
+    #
+    def new_cli
+      cli = @_cli.empty_clone
+      yield cli if block_given?
+      cli
+    end
+
+    ##
+    # Exit immediately with the given status code
+    #
+    # @param [Integer] code The status code, which should be 0 for no error,
+    #     or nonzero for an error condition.
+    #
+    def exit(code)
+      throw :result, code
+    end
+  end
+end