toys 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f036d1f723d27ed317a4aaac039147badbc21c55
-  data.tar.gz: 72974b402f863e4f07da29411393021c80728128
+SHA256:
+  metadata.gz: e1303b77289f7e37c45866ec22513df6187556c2d7188b97d2706731b73377c5
+  data.tar.gz: 31c4013f235e7fb83575c9b031798dc410ab0bdee2395303f3f54e54fc870c05
 SHA512:
-  metadata.gz: 4d1b8ab307213db7030cceee42c910bb21fa253cdc953654a7bcb611c2cd0ec71c2509c75b5e18bc833394d08b4d4c1bf8f3e8a707c486fe16de277cc6e7a0f1
-  data.tar.gz: 82177adaf1bd37799aaa83a031690fc8e908a0292d3ad618cb51afbc192f269e148a6a192727ed91cc95dd3e042e1660e3d47f338731f4f6db6ebc57b960d44f
+  metadata.gz: 8389b529719c6135483a52a65ec2521e90964be02fac0da56fa7016672da8f4f9a8f7ad24c8a0493db8558040c3c80e47553656f3a567524f4a7e310669cd05a
+  data.tar.gz: 708270b18a969b0adb5aa16c9b517966d82a3531a4a88604b7ee3cae27ecb67c839ef40318378c89d6a3347658c6d3fe590a6482177d0a899d96eaf0847f6366

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+### 0.3.0 / 2018-04-30
+
+* Initial generally usable release

data/README.md

@@ -27,6 +27,14 @@ guidelines will be provided when the software stabilizes further.
 The source can be found on Github at
 [https://github.com/dazuma/toys](https://github.com/dazuma/toys)
 
+### TODO items
+
+* Document methods
+* Write overall documentation
+* Decide about highline integration
+* Output formats middleware
+* System paths tool
+
 ## License
 
 Copyright 2018 Daniel Azuma

data/lib/toys.rb

@@ -35,21 +35,19 @@
 #
 module Toys
   ##
-  # Namespace for common helper modules
+  # Namespace for common utility classes
   #
-  module Helpers; end
-
-  ##
-  # Namespace for common templates
-  #
-  module Templates; end
+  module Utils; end
 end
 
 require "toys/builder"
 require "toys/cli"
 require "toys/context"
 require "toys/errors"
-require "toys/lookup"
+require "toys/helpers"
+require "toys/loader"
+require "toys/middleware"
 require "toys/template"
+require "toys/templates"
 require "toys/tool"
 require "toys/version"

data/lib/toys/builder.rb

@@ -32,17 +32,18 @@ module Toys
   # The object context in effect in a toys configuration file
   #
   class Builder
-    def initialize(path, tool, remaining_words, priority, lookup)
+    def initialize(path, tool, remaining_words, priority, loader, type)
       @path = path
       @tool = tool
       @remaining_words = remaining_words
       @priority = priority
-      @lookup = lookup
+      @loader = loader
+      @type = type
     end
 
-    def name(word, alias_of: nil, &block)
+    def tool(word, alias_of: nil, &block)
       word = word.to_s
-      subtool = @lookup.get_tool(@tool.full_name + [word], @priority)
+      subtool = @loader.get_tool(@tool.full_name + [word], @priority, assume_parent: true)
       return self if subtool.nil?
       if alias_of
         if block
@@ -51,8 +52,26 @@ module Toys
         subtool.make_alias_of_word(alias_of.to_s)
         return self
       end
-      next_remaining = Lookup.next_remaining_words(@remaining_words, word)
-      Builder.build(@path, subtool, next_remaining, @priority, @lookup, block)
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :tool)
+      self
+    end
+    alias name tool
+
+    def append(word, &block)
+      word = word.to_s
+      subtool = @loader.get_tool(@tool.full_name + [word], nil, assume_parent: true)
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :append)
+      self
+    end
+
+    def group(word, &block)
+      word = word.to_s
+      subtool = @loader.get_tool(@tool.full_name + [word], @priority, assume_parent: true)
+      return self if subtool.nil?
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :group)
       self
     end
 
@@ -60,34 +79,40 @@ module Toys
       if @tool.root?
         raise ToolDefinitionError, "Cannot make an alias of the root tool"
       end
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot make an alias of a group"
+      end
       alias_name = @tool.full_name.slice(0..-2) + [word.to_s]
-      alias_tool = @lookup.get_tool(alias_name, @priority)
+      alias_tool = @loader.get_tool(alias_name, @priority)
       alias_tool.make_alias_of(@tool.simple_name) if alias_tool
       self
     end
 
     def alias_of(word)
+      if @tool.root?
+        raise ToolDefinitionError, "Cannot make the root tool an alias"
+      end
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot make a group an alias"
+      end
       @tool.make_alias_of(word.to_s)
       self
     end
 
     def include(path)
       @tool.yield_definition do
-        @lookup.include_path(path, @tool.full_name, @remaining_words, @priority)
+        @loader.include_path(path, @tool.full_name, @remaining_words, @priority)
       end
       self
     end
 
     def expand(template_class, *args)
       unless template_class.is_a?(::Class)
-        template_class = template_class.to_s
-        file_name =
-          template_class
-          .gsub(/([a-zA-Z])([A-Z])/) { |_m| "#{$1}_#{$2.downcase}" }
-          .downcase
-        require "toys/templates/#{file_name}"
-        const_name = template_class.gsub(/(^|_)([a-zA-Z0-9])/) { |_m| $2.upcase }
-        template_class = Templates.const_get(const_name)
+        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?
@@ -96,46 +121,77 @@ module Toys
     end
 
     def long_desc(desc)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot set the description when appending"
+      end
       @tool.long_desc = desc
       self
     end
 
-    def short_desc(desc)
-      @tool.short_desc = desc
+    def desc(desc)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot set the description when appending"
+      end
+      @tool.desc = desc
       self
     end
+    alias short_desc desc
 
-    def switch(key, *switches, accept: nil, default: nil, doc: nil)
-      @tool.add_switch(key, *switches, accept: accept, default: default, doc: doc)
+    def switch(key, *switches,
+               accept: nil, default: nil, doc: nil, only_unique: false, handler: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add a switch when appending"
+      end
+      @tool.add_switch(key, *switches,
+                       accept: accept, default: default, doc: doc,
+                       only_unique: only_unique, handler: handler)
       self
     end
 
     def required_arg(key, accept: nil, doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
       @tool.add_required_arg(key, accept: accept, doc: doc)
       self
     end
 
     def optional_arg(key, accept: nil, default: nil, doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
       @tool.add_optional_arg(key, accept: accept, default: default, doc: doc)
       self
     end
 
     def remaining_args(key, accept: nil, default: [], doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
       @tool.set_remaining_args(key, accept: accept, default: default, doc: doc)
       self
     end
 
     def execute(&block)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot set the executor of a group"
+      end
       @tool.executor = block
       self
     end
 
     def helper(name, &block)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot define a helper method to a group"
+      end
       @tool.add_helper(name, &block)
       self
     end
 
     def use(mod)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot use a helper module in a group"
+      end
       @tool.use_module(mod)
       self
     end
@@ -144,19 +200,28 @@ module Toys
       binding
     end
 
-    def self.build(path, tool, remaining_words, priority, lookup, source)
-      builder = new(path, tool, remaining_words, priority, lookup)
-      tool.defining_from(path) do
-        case source
-        when String
-          # rubocop:disable Security/Eval
-          eval(source, builder._binding, path, 1)
-          # rubocop:enable Security/Eval
-        when ::Proc
-          builder.instance_eval(&source)
+    def self.build(path, tool, remaining_words, priority, loader, source, type)
+      builder = new(path, tool, remaining_words, priority, loader, type)
+      if type == :append
+        eval_source(builder, path, source)
+      else
+        tool.defining_from(path) do
+          eval_source(builder, path, source)
+          tool.finish_definition
         end
       end
       tool
     end
+
+    def self.eval_source(builder, path, source)
+      case source
+      when String
+        # rubocop:disable Security/Eval
+        eval(source, builder._binding, path, 1)
+        # rubocop:enable Security/Eval
+      when ::Proc
+        builder.instance_eval(&source)
+      end
+    end
   end
 end

data/lib/toys/builtins/do.rb

@@ -0,0 +1,44 @@
+# 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.
+;
+
+desc "Run multiple tools in order"
+
+switch(:delim, "-d", "--delim=VALUE", default: ",", doc: "Set the delimiter")
+
+remaining_args(:args)
+
+execute do
+  delim = self[:delim]
+  self[:args]
+    .chunk { |arg| arg == delim ? :_separator : true }
+    .each do |_, action|
+      code = run(action)
+      exit(code) unless code.zero?
+    end
+end

data/lib/toys/builtins/system.rb

@@ -27,18 +27,18 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-short_desc "A collection of system commands for toys"
+desc "A group of system commands for toys"
 
-name "version" do
-  short_desc "Print current toys version"
+tool "version" do
+  desc "Print current toys version."
 
   execute do
     puts ::Toys::VERSION
   end
 end
 
-name "update" do
-  short_desc "Update toys if a newer version is available"
+tool "update" do
+  desc "Update toys if a newer version is available."
 
   use :exec
 

data/lib/toys/cli.rb

@@ -64,34 +64,50 @@ module Toys
     #
     DEFAULT_BINARY_NAME = "toys".freeze
 
+    ##
+    # Default help text for the root tool
+    # @return [String]
+    #
+    DEFAULT_ROOT_DESC =
+      "Toys is your personal command line tool. You can add to the list of" \
+      " commands below by writing scripts in Ruby using a simple DSL, and" \
+      " toys will organize and document them, and make them available" \
+      " globally or scoped to specific directories that you choose." \
+      " For detailed information, see https://www.rubydoc.info/gems/toys".freeze
+
     def initialize(
       binary_name: nil,
       logger: nil,
       config_dir_name: nil,
       config_file_name: nil,
       index_file_name: nil,
-      preload_file_name: nil
+      preload_file_name: nil,
+      middleware: [],
+      root_desc: nil
     )
-      @lookup = Lookup.new(
+      logger ||= self.class.default_logger
+      @loader = Loader.new(
         config_dir_name: config_dir_name,
         config_file_name: config_file_name,
         index_file_name: index_file_name,
-        preload_file_name: preload_file_name
+        preload_file_name: preload_file_name,
+        middleware: middleware,
+        root_desc: root_desc
       )
-      @context_base = Context::Base.new(@lookup, binary_name, logger || self.class.default_logger)
+      @context_base = Context::Base.new(@loader, binary_name, logger)
     end
 
-    def add_paths(paths)
-      @lookup.add_paths(paths)
+    def add_config_paths(paths)
+      @loader.add_config_paths(paths)
       self
     end
 
-    def add_config_paths(paths)
-      @lookup.add_config_paths(paths)
+    def add_paths(paths)
+      @loader.add_paths(paths)
       self
     end
 
-    def add_config_path_hierarchy(path = nil, base = "/")
+    def add_path_hierarchy(path = nil, base = "/")
       path ||= ::Dir.pwd
       paths = []
       loop do
@@ -101,21 +117,22 @@ module Toys
         break if next_path == path
         path = next_path
       end
-      @lookup.add_config_paths(paths)
+      @loader.add_paths(paths)
       self
     end
 
-    def add_standard_config_paths
+    def add_standard_paths
       toys_path = ::ENV["TOYS_PATH"].to_s.split(::File::PATH_SEPARATOR)
       if toys_path.empty?
         toys_path << ::ENV["HOME"] if ::ENV["HOME"]
-        toys_path << "/etc" if File.directory?("/etc") && ::File.readable?("/etc")
+        toys_path << "/etc" if ::File.directory?("/etc") && ::File.readable?("/etc")
       end
-      @lookup.add_config_paths(toys_path)
+      @loader.add_paths(toys_path)
+      self
     end
 
     def run(*args)
-      @context_base.run(*args)
+      exit(@context_base.run(args.flatten, verbosity: 0))
     end
 
     class << self
@@ -125,14 +142,25 @@ module Toys
           config_dir_name: DEFAULT_DIR_NAME,
           config_file_name: DEFAULT_FILE_NAME,
           index_file_name: DEFAULT_FILE_NAME,
-          preload_file_name: DEFAULT_PRELOAD_NAME
+          preload_file_name: DEFAULT_PRELOAD_NAME,
+          middleware: default_middleware_stack,
+          root_desc: DEFAULT_ROOT_DESC
         )
-        cli.add_config_path_hierarchy
-        cli.add_standard_config_paths
-        cli.add_paths(BUILTINS_PATH)
+        cli.add_path_hierarchy
+        cli.add_standard_paths
+        cli.add_config_paths(BUILTINS_PATH)
         cli
       end
 
+      def default_middleware_stack
+        [
+          Middleware.lookup(:show_usage_errors).new,
+          Middleware.lookup(:group_default).new,
+          Middleware.lookup(:show_tool_help).new,
+          Middleware.lookup(:set_verbosity).new
+        ]
+      end
+
       def default_logger
         logger = ::Logger.new(::STDERR)
         logger.formatter = proc do |severity, time, _progname, msg|