toys-core 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f312d702768f03fa72f49fb33b81b49736aa3095a863878a2eddb70750d27d8
-  data.tar.gz: a3ed6d02218c3e94559178021320603b5ef6d89f0e2d263fa183a583b68caf05
+  metadata.gz: 7e238ba243a2e72d0c04df73414040baf052dae6179f6f81030e5bf96b1bc06a
+  data.tar.gz: 4b711336fca9d960390e523741ddf800674e7657da1677a884679e28fbe9c6f1
 SHA512:
-  metadata.gz: 94ee591039f0191572b66274033dbb3245bdb210e1e93441910c6a7d1e6d5732f1afdd71ba09103a357c52dc8c59fe13b1538ddd53319e03aaea4502e266e452
-  data.tar.gz: 6cc7dfd5d6dc7a87c6e5cee9521d6374b1ec7b462119e7ce2700147d6a384df6d7e7d92a6498139f53dcc5f114cd47588d53e4fb2108757b2d575f46b26f3a4f
+  metadata.gz: 470b8f9c78917c60db54df07c54f43a14b7626cf31f22ab7810756103af41482f34a66a92b09d82587e5ac09f3774f7446275a0f2f131fab5f4a7a0eec6903dc
+  data.tar.gz: 0eb481163a3476ad7fd94146f09ee0b8acc4a02b1a0aadd95d559100756e6793e913091588e35523073e41152b464a5dbb48aba37c86613a34a483afbb50cbe3

data/.yardopts

@@ -7,4 +7,4 @@
 README.md
 LICENSE.md
 CHANGELOG.md
-docs/getting-started.md
+docs/guide.md

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release History
 
+### 0.4.5 / 2018-08-05
+
+* CHANGED: Dropped preload file feature
+
 ### 0.4.4 / 2018-07-21
 
 * FIXED: Utils::Exec wasn't closing streams after copying.

data/README.md

@@ -3,12 +3,99 @@
 Toys is a configurable command line tool. Write commands in config files using
 a simple DSL, and Toys will provide the command line binary and take care of
 all the details such as argument parsing, online help, and error reporting.
-
 Toys-Core is the command line tool framework underlying Toys. It can be used
 to create your own command line binaries using the internal Toys APIs.
 
-To get started with toys-core, see the
-[Getting Started Guide](https://www.rubydoc.info/gems/toys-core/file/docs/getting-started.md)
+For more detailed information about Toys-Core, see the
+[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
+For background information about Toys itself, see the
+[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+
+## Quick Start
+
+Here's a ten-minute tutorial to get a feel for how to write a basic command
+line binary using Toys-Core.
+
+### Install Toys
+
+Install the **toys-core** gem using:
+
+    gem install toys-core
+
+You may also install the **toys** gem, which brings in **toys-core** as a
+dependency.
+
+### Create a Toys File
+
+A *Toys File* is a configuration file used by Toys to define commands, called
+"tools" in Toys lingo. If you've used the **toys** binary itself, you've
+probably written one already. You use the same file format when you create your
+own command line binary using Toys-Core.
+
+Create a new empty directory. In the directory, using your favorite text
+editor, create a file called `tools.rb`. Copy the following into the file, and
+save it:
+
+    tool "greet" do
+      desc "My first tool!"
+      flag :whom, default: "world"
+      def run
+        puts "Hello, #{whom}!"
+      end
+    end
+
+If you're already familiar with writing Toys Files, feel free to modify and
+experiment with it.
+
+### Create Your Binary
+
+Now we will write a command line binary that uses that Toys File. In the same
+new directory, create a new file called `mycmd`. Copy the following into it:
+
+    #!/usr/bin/env ruby
+    require "toys-core"
+    cli = Toys::CLI.new
+    cli.add_config_path(File.join(__dir__, "tools.rb"))
+    exit(cli.run(ARGV))
+
+Save the file and make it executable:
+
+    chmod +x mycmd
+
+Now you can run your command. Try these, to get a feel for how it behaves by
+default:
+
+    ./mycmd greet
+    ./mycmd greet --whom=Ruby
+    ./mycmd greet --help
+    ./mycmd
+    ./mycmd foo
+
+### Next Steps
+
+A basic command line binary based on Toys-Core consists of just the binary
+itself, and a Toys File (or directory) defining the commands to run. All the
+features of Toys, described in the
+[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md),
+are at your disposal for writing tools for your binary. Or, if you want your
+binary to have a single function rather than support a set of tools, you can
+just write a toplevel tool in your Toys File.
+
+You'll notice that Toys-Core provides a number of features "out of the box",
+such as online help, verbose and quiet flags, and default descriptions. These
+features are controlled by Toys *Middleware*, which are classes that customize
+the base behavior of Toys-Core. Toys-Core defaults to a certain set of
+middleware, but you can customize and change them for your own binary.
+
+Finally, you may want to distribute your binary in a gem. Just make sure you
+include the Toys File or Directory in the gem, and that your binary configures
+`Toys::CLI` with the correct config path. The Toys File does not need to be in
+the require path (i.e. in the `lib` directory), and indeed it is probably best
+for it not to be, to prevent users of your gem from requiring it accidentally.
+
+See the
+[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md)
+for thorough documentation on writing a command line binary using Toys-Core.
 
 ## License
 

data/docs/guide.md

@@ -0,0 +1,16 @@
+# @title Toys-Core User Guide
+
+# Toys-Core User Guide
+
+Toys-Core is the command line tool framework underlying Toys. It can be used
+to create command line binaries using the internal Toys APIs.
+
+This user's guide covers everything you need to know to build your own command
+line binaries in Ruby using the Toys-Core framework.
+
+This guide assumes you are already familiar with Toys itself, including how to
+define tools by writing Toys files, parsing arguments and flags, and how tools
+are executed. For background, please see the
+[Toys User's Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+
+(To be written)

data/lib/toys/cli.rb

@@ -58,12 +58,6 @@ module Toys
     #     loaded first as a standalone configuration file. If not provided,
     #     standalone configuration files are disabled.
     #     The default toys CLI sets this to `".toys.rb"`.
-    # @param [String,nil] preload_file_name A file with this name that appears
-    #     in any configuration directory (not just a toplevel directory) is
-    #     loaded before any configuration files. It is not treated as a
-    #     configuration file in that the configuration DSL is not honored. You
-    #     may use such a file to define auxiliary Ruby modules and classes that
-    #     used by the tools defined in that directory.
     # @param [Array] middleware_stack An array of middleware that will be used
     #     by default for all tools loaded by this CLI. If not provided, uses
     #     {Toys::CLI.default_middleware_stack}.
@@ -88,8 +82,7 @@ module Toys
     #
     def initialize(
       binary_name: nil, middleware_stack: nil,
-      config_dir_name: nil, config_file_name: nil,
-      index_file_name: nil, preload_file_name: nil,
+      config_dir_name: nil, config_file_name: nil, index_file_name: nil,
       mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil,
       logger: nil, base_level: nil, error_handler: nil
     )
@@ -100,12 +93,11 @@ module Toys
       @config_dir_name = config_dir_name
       @config_file_name = config_file_name
       @index_file_name = index_file_name
-      @preload_file_name = preload_file_name
       @mixin_lookup = mixin_lookup || self.class.default_mixin_lookup
       @middleware_lookup = middleware_lookup || self.class.default_middleware_lookup
       @template_lookup = template_lookup || self.class.default_template_lookup
       @loader = Loader.new(
-        index_file_name: index_file_name, preload_file_name: preload_file_name,
+        index_file_name: index_file_name,
         mixin_lookup: @mixin_lookup, template_lookup: @template_lookup,
         middleware_lookup: @middleware_lookup, middleware_stack: @middleware_stack
       )
@@ -259,7 +251,6 @@ module Toys
                     config_dir_name: @config_dir_name,
                     config_file_name: @config_file_name,
                     index_file_name: @index_file_name,
-                    preload_file_name: @preload_file_name,
                     middleware_stack: @middleware_stack,
                     mixin_lookup: @mixin_lookup,
                     middleware_lookup: @middleware_lookup,

data/lib/toys/core_version.rb

@@ -34,5 +34,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.4.4"
+  CORE_VERSION = "0.4.5"
 end

data/lib/toys/loader.rb

@@ -53,12 +53,6 @@ module Toys
     #     in any configuration directory (not just a toplevel directory) is
     #     loaded first as a standalone configuration file. If not provided,
     #     standalone configuration files are disabled.
-    # @param [String,nil] preload_file_name A file with this name that appears
-    #     in any configuration directory (not just a toplevel directory) is
-    #     loaded before any configuration files. It is not treated as a
-    #     configuration file in that the configuration DSL is not honored. You
-    #     may use such a file to define auxiliary Ruby modules and classes that
-    #     used by the tools defined in that directory.
     # @param [Array] middleware_stack An array of middleware that will be used
     #     by default for all tools loaded by this loader.
     # @param [Toys::Utils::ModuleLookup] mixin_lookup A lookup for well-known
@@ -68,19 +62,15 @@ module Toys
     # @param [Toys::Utils::ModuleLookup] template_lookup A lookup for
     #     well-known template classes. Defaults to an empty lookup.
     #
-    def initialize(index_file_name: nil, preload_file_name: nil, middleware_stack: [],
+    def initialize(index_file_name: nil, middleware_stack: [],
                    mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil)
       if index_file_name && ::File.extname(index_file_name) != ".rb"
         raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
-      if preload_file_name && ::File.extname(preload_file_name) != ".rb"
-        raise ::ArgumentError, "Illegal preload file name #{preload_file_name.inspect}"
-      end
       @mixin_lookup = mixin_lookup || Utils::ModuleLookup.new
       @middleware_lookup = middleware_lookup || Utils::ModuleLookup.new
       @template_lookup = template_lookup || Utils::ModuleLookup.new
       @index_file_name = index_file_name
-      @preload_file_name = preload_file_name
       @middleware_stack = middleware_stack
       @worklist = []
       @tool_data = {}
@@ -428,7 +418,6 @@ module Toys
         tool_class = get_tool_definition(words, priority).tool_class
         Toys::InputFile.evaluate(tool_class, remaining_words, path)
       else
-        require_preload_in(path)
         load_index_in(path, words, remaining_words, priority)
         ::Dir.entries(path).each do |child|
           load_child_in(path, child, words, remaining_words, priority)
@@ -436,13 +425,6 @@ module Toys
       end
     end
 
-    def require_preload_in(path)
-      return unless @preload_file_name
-      preload_path = ::File.join(path, @preload_file_name)
-      preload_path = check_path(preload_path, type: :file, lenient: true)
-      require preload_path if preload_path
-    end
-
     def load_index_in(path, words, remaining_words, priority)
       return unless @index_file_name
       index_path = ::File.join(path, @index_file_name)
@@ -452,7 +434,7 @@ module Toys
 
     def load_child_in(path, child, words, remaining_words, priority)
       return if child.start_with?(".")
-      return if [@preload_file_name, @index_file_name].include?(child)
+      return if child == @index_file_name
       child_path = check_path(::File.join(path, child))
       child_word = ::File.basename(child, ".rb")
       next_words = words + [child_word]

data/lib/toys/standard_middleware/set_default_descriptions.rb

@@ -67,7 +67,9 @@ module Toys
       DEFAULT_ROOT_LONG_DESC = [
         "This command line tool was built using the toys-core gem. See" \
           " https://www.rubydoc.info/gems/toys-core for more info.",
-        "To replace this message, configure the SetDefaultDescriptions middleware."
+        "To replace this message, set the description and long description" \
+          " of the root tool, or configure the SetDefaultDescriptions" \
+          " middleware."
       ].freeze
 
       ##

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-22 00:00:00.000000000 Z
+date: 2018-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.57.2
+        version: 0.58.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.57.2
+        version: 0.58.2
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -106,7 +106,7 @@ files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
-- docs/getting-started.md
+- docs/guide.md
 - lib/toys-core.rb
 - lib/toys/cli.rb
 - lib/toys/core_version.rb

data/docs/getting-started.md

@@ -1,8 +0,0 @@
-# @title Getting Started
-
-# Getting Started With Toys-Core
-
-Toys-Core is the command line tool framework underlying Toys. It can be used
-to create command line binaries using the internal Toys APIs.
-
-(To be written)