toys-core 0.7.0 → 0.8.0

data/lib/toys/middleware.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -65,11 +57,11 @@ module Toys
     # This basic implementation does nothing and simply yields to the next
     # middleware.
     #
-    # @param [Toys::Definition::Tool] _tool_definition The tool definition
-    #     to modify.
-    # @param [Toys::Loader] _loader The loader that loaded this tool.
+    # @param tool [Toys::Tool] The tool definition to modify.
+    # @param loader [Toys::Loader] The loader that loaded this tool.
+    # @return [void]
     #
-    def config(_tool_definition, _loader)
+    def config(tool, loader) # rubocop:disable Lint/UnusedMethodArgument
       yield
     end
 
@@ -86,14 +78,15 @@ module Toys
     #
     # Like a tool's `run` method, this method's return value is unused. If
     # you want to output from a tool, write to stdout or stderr. If you want
-    # to set the exit status code, call {Toys::Tool#exit} on the tool object.
+    # to set the exit status code, call {Toys::Context#exit} on the context.
     #
     # This basic implementation does nothing and simply yields to the next
     # middleware.
     #
-    # @param [Toys::Tool] _tool The tool execution instance.
+    # @param context [Toys::Context] The tool execution context.
+    # @return [void]
     #
-    def run(_tool)
+    def run(context) # rubocop:disable Lint/UnusedMethodArgument
       yield
     end
   end

data/lib/toys/mixin.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -36,7 +28,7 @@ module Toys
   # A mixin is a collection of methods that are available to be called from a
   # tool implementation (i.e. its run method). The mixin is added to the tool
   # class, so it has access to the same methods that can be called by the tool,
-  # such as {Toys::Tool#option}.
+  # such as {Toys::Context#get}.
   #
   # ## Usage
   #
@@ -44,19 +36,24 @@ module Toys
   # the methods you want to be available.
   #
   # If you want to perform some initialization specific to the mixin, you can
-  # provide a `to_initialize` block and/or a `to_include` block.
-  #
-  # The `to_initialize` block is called when the tool itself is instantiated.
-  # It has access to tool methods such as {Toys::Tool#option}, and can perform
-  # setup for the tool execution itself, often involving initializing some
-  # persistent state and storing it in the tool using {Toys::Tool#set}. The
-  # `to_initialize` block is passed any extra arguments that were provided to
-  # the `include` directive.
-  #
-  # The `to_include` block is called in the context of your tool class when
-  # your mixin is included. It is also passed any extra arguments that were
-  # provided to the `include` directive. It can be used to issue directives
-  # or define methods on the DSL, specific to the mixin.
+  # provide an *initializer* block and/or an *inclusion* block. These can be
+  # specified by calling the module methods defined in
+  # {Toys::Mixin::ModuleMethods}.
+  #
+  # The initializer block is called when the tool context is instantiated
+  # in preparation for execution. It has access to context methods such as
+  # {Toys::Context#get}, and can perform setup for the tool execution itself,
+  # such as initializing some persistent state and storing it in the tool using
+  # {Toys::Context#set}. The initializer block is passed any extra arguments
+  # that were provided to the `include` directive. Define the initializer by
+  # calling {Toys::Mixin::ModuleMethods#on_initialize}.
+  #
+  # The inclusion block is called in the context of your tool class when your
+  # mixin is included. It is also passed any extra arguments that were provided
+  # to the `include` directive. It can be used to issue directives to define
+  # tools or other objects in the DSL, or even enhance the DSL by defining DSL
+  # methods specific to the mixin. Define the inclusion block by calling
+  # {Toys::Mixin::ModuleMethods#on_include}.
   #
   # ## Example
   #
@@ -68,14 +65,16 @@ module Toys
   #     module MyCounterMixin
   #       include Toys::Mixin
   #
-  #       # Initialize the counter. Called with self set to the tool so it can
-  #       # affect the tool state.
-  #       to_initialize do |start = 0|
+  #       # Initialize the counter. Notice that the initializer is evaluated
+  #       # in the context of the runtime context, so has access to the runtime
+  #       # context state.
+  #       on_initialize do |start = 0|
   #         set(:counter_value, start)
   #       end
   #
-  #       # Mixin methods are called with self set to the tool and can affect
-  #       # the tool state.
+  #       # Mixin methods are evaluated in the runtime context and so have
+  #       # access to the runtime context state, just as if you had defined
+  #       # them in your tool.
   #       def counter_value
   #         get(:counter_value)
   #       end
@@ -100,9 +99,23 @@ module Toys
   #     end
   #
   module Mixin
+    ##
+    # Create a mixin module with the given block.
+    #
+    # @param block [Proc] Defines the mixin module.
+    # @return [Class]
+    #
+    def self.create(&block)
+      mixin_mod = ::Module.new do
+        include ::Toys::Mixin
+      end
+      mixin_mod.module_eval(&block) if block
+      mixin_mod
+    end
+
     ## @private
     def self.included(mod)
-      return if mod.respond_to?(:to_initialize)
+      return if mod.respond_to?(:on_initialize)
       mod.extend(ModuleMethods)
     end
 
@@ -111,32 +124,50 @@ module Toys
     #
     module ModuleMethods
       ##
-      # Provide a block that initializes this mixin when the tool is
-      # constructed.
+      # Set the initializer for this mixin. This block is evaluated in the
+      # runtime context before execution, and is passed any arguments provided
+      # to the `include` directive. It can perform any runtime initialization
+      # needed by the mixin.
+      #
+      # @param block [Proc] Sets the initializer proc.
+      # @return [self]
       #
-      def to_initialize(&block)
-        self.initialization_callback = block
+      def on_initialize(&block)
+        self.initializer = block
+        self
       end
 
       ##
-      # Provide a block that modifies the tool class when the mixin is
-      # included.
+      # The initializer proc for this mixin. This proc is evaluated in the
+      # runtime context before execution, and is passed any arguments provided
+      # to the `include` directive. It can perform any runtime initialization
+      # needed by the mixin.
       #
-      def to_include(&block)
-        self.inclusion_callback = block
-      end
+      # @return [Proc] The iniitiliazer for this mixin.
+      #
+      attr_accessor :initializer
 
       ##
-      # You may alternately set the initializer block using this accessor.
-      # @return [Proc]
+      # Set an inclusion proc for this mixin. This block is evaluated in the
+      # tool class immediately after the mixin is included, and is passed any
+      # arguments provided to the `include` directive.
       #
-      attr_accessor :initialization_callback
+      # @param block [Proc] Sets the inclusion proc.
+      # @return [self]
+      #
+      def on_include(&block)
+        self.inclusion = block
+        self
+      end
 
       ##
-      # You may alternately set the inclusion block using this accessor.
-      # @return [Proc]
+      # The inclusion proc for this mixin. This block is evaluated in the tool
+      # class immediately after the mixin is included, and is passed any
+      # arguments provided to the `include` directive.
+      #
+      # @return [Proc] The inclusion procedure for this mixin.
       #
-      attr_accessor :inclusion_callback
+      attr_accessor :inclusion
     end
   end
 end

data/lib/toys/module_lookup.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+module Toys
+  ##
+  # A helper module that provides methods to do module lookups. This is
+  # used to obtain named helpers, middleware, and templates from the
+  # respective modules.
+  #
+  class ModuleLookup
+    class << self
+      ##
+      # Convert the given string to a path element. Specifically, converts
+      # to `lower_snake_case`.
+      #
+      # @param str [String,Symbol] String to convert.
+      # @return [String] Converted string
+      #
+      def to_path_name(str)
+        str = str.to_s.sub(/^_/, "").sub(/_$/, "").gsub(/_+/, "_")
+        while str.sub!(/([^_])([A-Z])/, "\\1_\\2") do end
+        str.downcase
+      end
+
+      ##
+      # Convert the given string to a module name. Specifically, converts
+      # to `UpperCamelCase`, and then to a symbol.
+      #
+      # @param str [String,Symbol] String to convert.
+      # @return [Symbol] Converted name
+      #
+      def to_module_name(str)
+        str = str.to_s.sub(/^_/, "").sub(/_$/, "").gsub(/_+/, "_")
+        str.to_s.gsub(/(?:^|_)([a-zA-Z])/) { ::Regexp.last_match(1).upcase }.to_sym
+      end
+
+      ##
+      # Given a require path, return the module expected to be defined.
+      #
+      # @param path [String] File path, delimited by forward slash
+      # @return [Module] The module loaded from that path
+      #
+      def path_to_module(path)
+        path.split("/").reduce(::Object) do |running_mod, seg|
+          mod_name = to_module_name(seg)
+          unless running_mod.constants.include?(mod_name)
+            raise ::NameError, "Module #{running_mod.name}::#{mod_name} not found"
+          end
+          running_mod.const_get(mod_name)
+        end
+      end
+    end
+
+    ##
+    # Create an empty ModuleLookup
+    #
+    def initialize
+      @paths = []
+    end
+
+    ##
+    # Add a lookup path for modules.
+    #
+    # @param path_base [String] The base require path
+    # @param module_base [Module] The base module, or `nil` (the default) to
+    #     infer a default from the path base.
+    # @param high_priority [Boolean] If true, add to the head of the lookup
+    #     path, otherwise add to the end.
+    # @return [self]
+    #
+    def add_path(path_base, module_base: nil, high_priority: false)
+      module_base ||= ModuleLookup.path_to_module(path_base)
+      if high_priority
+        @paths.unshift([path_base, module_base])
+      else
+        @paths << [path_base, module_base]
+      end
+      self
+    end
+
+    ##
+    # Obtain a named module. Returns `nil` if the name is not present.
+    #
+    # @param name [String,Symbol] The name of the module to return.
+    # @return [Module] The specified module
+    #
+    def lookup(name)
+      @paths.each do |path_base, module_base|
+        path = "#{path_base}/#{ModuleLookup.to_path_name(name)}"
+        begin
+          require path
+        rescue ::LoadError
+          next
+        end
+        mod_name = ModuleLookup.to_module_name(name)
+        unless module_base.constants.include?(mod_name)
+          raise ::NameError,
+                "File #{path.inspect} did not define #{module_base.name}::#{mod_name}"
+        end
+        return module_base.const_get(mod_name)
+      end
+      nil
+    end
+  end
+end

data/lib/toys/positional_arg.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+module Toys
+  ##
+  # Representation of a formal positional argument
+  #
+  class PositionalArg
+    ##
+    # Create a PositionalArg definition.
+    # This argument list is subject to change. Use {Toys::PositionalArg.create}
+    # instead for a more stable interface.
+    # @private
+    #
+    def initialize(key, type, acceptor, default, completion, desc, long_desc, display_name)
+      @key = key
+      @type = type
+      @acceptor = Acceptor.create(acceptor)
+      @default = default
+      @completion = Completion.create(completion)
+      @desc = WrappableString.make(desc)
+      @long_desc = WrappableString.make_array(long_desc)
+      @display_name = display_name || key.to_s.tr("-", "_").gsub(/\W/, "").upcase
+    end
+
+    ##
+    # Create a PositionalArg definition.
+    #
+    # @param key [String,Symbol] The key to use to retrieve the value from
+    #     the execution context.
+    # @param type [Symbol] The type of arg. Valid values are `:required`,
+    #     `:optional`, and `:remaining`.
+    # @param accept [Object] An acceptor that validates and/or converts the
+    #     value. See {Toys::Acceptor.create} for recognized formats. Optional.
+    #     If not specified, defaults to {Toys::Acceptor::DEFAULT}.
+    # @param complete [Object] A specifier for shell tab completion. See
+    #     {Toys::Completion.create} for recognized formats.
+    # @param display_name [String] A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @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.
+    # @return [Toys::PositionalArg]
+    #
+    def self.create(key, type,
+                    accept: nil, default: nil, complete: nil, desc: nil,
+                    long_desc: nil, display_name: nil)
+      new(key, type, accept, default, complete, desc, long_desc, display_name)
+    end
+
+    ##
+    # The key for this arg.
+    # @return [Symbol]
+    #
+    attr_reader :key
+
+    ##
+    # Type of this argument.
+    # @return [:required,:optional,:remaining]
+    #
+    attr_reader :type
+
+    ##
+    # The effective acceptor.
+    # @return [Toys::Acceptor::Base]
+    #
+    attr_accessor :acceptor
+
+    ##
+    # The default value, which may be `nil`.
+    # @return [Object]
+    #
+    attr_reader :default
+
+    ##
+    # The proc that determines shell completions for the value.
+    # @return [Proc,Toys::Completion::Base]
+    #
+    attr_reader :completion
+
+    ##
+    # The short description string.
+    #
+    # When reading, this is always returned as a {Toys::WrappableString}.
+    #
+    # When setting, the description may be provided as any of the following:
+    #  *  A {Toys::WrappableString}.
+    #  *  A normal String, which will be transformed into a
+    #     {Toys::WrappableString} using spaces as word delimiters.
+    #  *  An Array of String, which will be transformed into a
+    #     {Toys::WrappableString} where each array element represents an
+    #     individual word for wrapping.
+    #
+    # @return [Toys::WrappableString]
+    #
+    attr_reader :desc
+
+    ##
+    # The long description strings.
+    #
+    # When reading, this is returned as an Array of {Toys::WrappableString}
+    # representing the lines in the description.
+    #
+    # When setting, the description must be provided as an Array where *each
+    # element* may be any of the following:
+    #  *  A {Toys::WrappableString} representing one line.
+    #  *  A normal String representing a line. This will be transformed into a
+    #     {Toys::WrappableString} using spaces as word delimiters.
+    #  *  An Array of String representing a line. This will be transformed into
+    #     a {Toys::WrappableString} where each array element represents an
+    #     individual word for wrapping.
+    #
+    # @return [Array<Toys::WrappableString>]
+    #
+    attr_reader :long_desc
+
+    ##
+    # The displayable name.
+    # @return [String]
+    #
+    attr_accessor :display_name
+
+    ##
+    # Set the short description string.
+    #
+    # See {#desc} for details.
+    #
+    # @param desc [Toys::WrappableString,String,Array<String>]
+    #
+    def desc=(desc)
+      @desc = WrappableString.make(desc)
+    end
+
+    ##
+    # Set the long description strings.
+    #
+    # See {#long_desc} for details.
+    #
+    # @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
+    #
+    def long_desc=(long_desc)
+      @long_desc = WrappableString.make_array(long_desc)
+    end
+
+    ##
+    # Append long description strings.
+    #
+    # You must pass an array of lines in the long description. See {#long_desc}
+    # for details on how each line may be represented.
+    #
+    # @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
+    # @return [self]
+    #
+    def append_long_desc(long_desc)
+      @long_desc.concat(WrappableString.make_array(long_desc))
+      self
+    end
+  end
+end