bake 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4138c750ccdded2e0b36d082d94fecc0ae4afd0cfda6bad6e47179e37450f47
-  data.tar.gz: 236deaa42f0a148e195abdbeca1a8298e252ee335ea5cbceddc97e5c06dce195
+  metadata.gz: c21d6d91f4610a4abdca6e513279db3532f535b879fd284efd0d93f39915bb1c
+  data.tar.gz: 52648fc8729a487d1873eca3c90a5222a0837a5b66934810e197ee75d7740cc6
 SHA512:
-  metadata.gz: 0b249b795b9f91489d0150a5d511d3d22a6d4d2292fba3f2680455a2831c9b3480abed70d107127bf45cf76d5197395b9c9be597902800c39ca95be6e761ade8
-  data.tar.gz: ec9e06a913c3f457b227d077ae7d2e0f19d90ac7a417edcb3f1d721c0d6176dd62a178d5b6e2db5ff66084e60fda446af5c9f0ee013da98435fc15287e2f0726
+  metadata.gz: 6642cfd94507b0654e3cfef28a9c89440bae8f2c28b219d3e742c7eb089f3230596c23e0a7c278cd956dcfa3d664ca90d3becb9ebb041539171d3e093f3885da
+  data.tar.gz: f13b33176b5be8a0bc5083e2832022fbb5e8f11c6242d20679f768a35e03e6e92e0db3fe25ead0da5fe7eb5c5b1f8678debfca8913e0725d8878eeb329eb5fdd

data/README.md

@@ -4,7 +4,7 @@ Bake is a task execution tool, inspired by Rake, but codifying many of the use c
 
 [![Development](https://github.com/ioquatix/bake/workflows/Development/badge.svg)](https://github.com/ioquatix/bake/actions?workflow=Development)
 
-## Motivation
+## Features
 
 Rake is an awesome tool and loved by the community. So, why reinvent it? Bake provides the following features that Rake does not:
 
@@ -15,23 +15,20 @@ Rake is an awesome tool and loved by the community. So, why reinvent it? Bake pr
 
 That being said, Rake and Bake can exist side by side in the same project.
 
-## Installation
-
-Execute the following in your project:
-
-	bundle add bake
-
 ## Usage
 
-Please see the <a href="https://ioquatix.github.io/bake/">project documentation</a> or run it locally using `bake utopia:project:serve`.
+Please see the [project documentation](https://ioquatix.github.io/bake/).
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
 
 ## See Also
 

data/bake.gemspec

@@ -23,11 +23,7 @@ Gem::Specification.new do |spec|
 	
 	spec.add_dependency 'samovar', '~> 2.1'
 	
-	spec.add_development_dependency 'bake-bundler'
-	
-	spec.add_development_dependency 'utopia-project'
 	spec.add_development_dependency 'covered'
 	spec.add_development_dependency 'bundler'
 	spec.add_development_dependency 'rspec'
-	spec.add_development_dependency 'rake'
 end

data/gems.rb

@@ -2,3 +2,10 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in bake.gemspec
 gemspec
+
+group :maintenance, optional: true do
+	gem 'bake-modernize'
+	gem 'bake-bundler'
+	
+	gem 'utopia-project'
+end

data/guides/getting-started/README.md

@@ -0,0 +1,109 @@
+# Getting Started
+
+This guide gives a general overview of `bake` and how to use it.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add bake
+~~~
+
+## Core Concepts
+
+`bake` has several core concepts:
+
+- A `bake` executable used for invoking one or more tasks.
+- A {ruby Bake::Context} instance which is bound to a project or gem and exposes a hierarchy of runnable tasks.
+- A {ruby Bake::Loaders} instance which is used for on-demand loading of bake files from the current project and all available gems.
+
+## Executing Tasks
+
+The `bake` executable can be used to execute tasks in a `bake.rb` file in the same directory.
+
+``` ruby
+# bake.rb
+
+def add(x, y)
+	puts Integer(x) + Integer(y)
+end
+```
+
+You can execute this task from the command line:
+
+``` shell
+% bake add 10 20
+30
+```
+
+### Using Types
+
+You can annotate your task with a type signature and `bake` will coerce your arguments to these types:
+
+``` ruby
+# bake.rb
+
+# @parameter x [Integer]
+# @parameter y [Integer]
+def add(x, y)
+	puts x + y
+end
+```
+
+You can execute this task from the command line:
+
+``` shell
+% bake add 10 20
+30
+```
+
+The values are automatically coerced to `Integer`.
+
+### Extending With Documentation
+
+You can add documentation to your tasks and parameters (using Markdown formatting).
+
+``` ruby
+# bake.rb
+
+# Add the x and y coordinate together and print the result.
+# @parameter x [Integer] The x offset.
+# @parameter y [Integer] The y offset.
+def add(x, y)
+	puts x + y
+end
+```
+
+You can see this documentation in the task listing:
+
+``` shell
+% bake list add
+Bake::Context getting-started
+
+	add x y
+		Add the x and y coordinate together and print the result.
+		x [Integer] The x offset.
+		y [Integer] The y offset.
+```
+
+### Private Methods
+
+If you want to add helper methods which don't show up as tasks, define them as `protected` or `private`.
+
+``` ruby
+# bake.rb
+
+# Add the x and y coordinate together and print the result.
+# @parameter x [Integer] The x offset.
+# @parameter y [Integer] The y offset.
+def add(x, y)
+	puts x + y
+end
+
+private
+
+def puts(*arguments)
+	$stdout.puts arguments.inspect
+end
+```

data/guides/links.yaml

@@ -0,0 +1,8 @@
+getting-started:
+  order: 1
+command-line-interface:
+  order: 2
+project-integration:
+  order: 3
+gem-integration:
+  order: 4

data/lib/bake/base.rb

@@ -25,7 +25,7 @@ module Bake
 	# The base class for including {Scope} instances which define {Recipe} instances.
 	class Base < Struct.new(:context)
 		# Generate a base class for the specified path.
-		# @param path [Array(String)] The command path.
+		# @parameter path [Array(String)] The command path.
 		def self.derive(path = [])
 			klass = Class.new(self)
 			
@@ -35,7 +35,7 @@ module Bake
 		end
 		
 		# Format the class as a command.
-		# @return [String]
+		# @returns [String]
 		def self.to_s
 			if path = self.path
 				path.join(':')
@@ -53,7 +53,7 @@ module Bake
 		end
 		
 		# The path of this derived base class.
-		# @return [Array(String)]
+		# @returns [Array(String)]
 		def self.path
 			self.const_get(:PATH)
 		rescue
@@ -61,22 +61,22 @@ module Bake
 		end
 		
 		# The path for this derived base class.
-		# @return [Array(String)]
+		# @returns [Array(String)]
 		def path
 			self.class.path
 		end
 		
 		# Proxy a method call using command line arguments through to the {Context} instance.
-		# @param arguments [Array(String)]
+		# @parameter arguments [Array(String)]
 		def call(*arguments)
 			self.context.call(*arguments)
 		end
 		
 		# Recipes defined in this scope.
 		#
-		# @block `{|recipe| ...}`
-		# @yield recipe [Recipe]
-		# @return [Enumerable]
+		# @yields {|recipe| ...}
+		# 	@parameter recipe [Recipe]
+		# @returns [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -89,7 +89,7 @@ module Bake
 		
 		# Look up a recipe with a specific name.
 		#
-		# @param name [String] The instance method to look up.
+		# @parameter name [String] The instance method to look up.
 		def recipe_for(name)
 			Recipe.new(self, name)
 		end

data/lib/bake/context.rb

@@ -28,7 +28,7 @@ module Bake
 	class Context
 		# Search upwards from the specified path for a {BAKEFILE}.
 		# If path points to a file, assume it's a `bake.rb` file. Otherwise, recursively search up the directory tree starting from `path` to find the specified bakefile.
-		# @return [String | Nil] The path to the bakefile if it could be found.
+		# @returns [String | Nil] The path to the bakefile if it could be found.
 		def self.bakefile_path(path, bakefile: BAKEFILE)
 			if File.file?(path)
 				return path
@@ -74,7 +74,7 @@ module Bake
 		end
 		
 		# Initialize the context with the specified loaders.
-		# @param loaders [Loaders]
+		# @parameter loaders [Loaders]
 		def initialize(loaders, scope = nil, root = nil)
 			@loaders = loaders
 			
@@ -106,11 +106,11 @@ module Bake
 		attr :scope
 		
 		# The root path of this context.
-		# @return [String | Nil]
+		# @returns [String | Nil]
 		attr :root
 		
 		# Invoke recipes on the context using command line arguments.
-		# @param commands [Array(String)]
+		# @parameter commands [Array(String)]
 		def call(*commands)
 			last_result = nil
 			
@@ -127,7 +127,7 @@ module Bake
 		end
 		
 		# Lookup a recipe for the given command name.
-		# @param command [String] The command name, e.g. `bundler:release`.
+		# @parameter command [String] The command name, e.g. `bundler:release`.
 		def lookup(command)
 			@recipes[command]
 		end
@@ -164,7 +164,7 @@ module Bake
 			end
 		end
 		
-		# @param path [Array<String>] the path for the scope.
+		# @parameter path [Array<String>] the path for the scope.
 		def base_for(path)
 			base = nil
 			

data/lib/bake/documentation.rb

@@ -25,7 +25,7 @@ module Bake
 	class Documentation
 		# Initialize the documentation with an array of comments.
 		#
-		# @param comments [Array(String)] An array of comment lines.
+		# @parameter comments [Array(String)] An array of comment lines.
 		def initialize(comments)
 			@comments = comments
 		end
@@ -34,8 +34,9 @@ module Bake
 		
 		# The text-only lines of the comment block.
 		#
-		# @yield [String]
-		# @return [Enumerable]
+		# @yields {|match| ...}
+		# 	@parameter match [MatchData] The regular expression match for each line of documentation.
+		# @returns [Enumerable] If no block given.
 		def description
 			return to_enum(:description) unless block_given?
 			
@@ -63,10 +64,11 @@ module Bake
 		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
 		
 		# The attribute lines of the comment block.
-		# e.g. `@return [String]`.
+		# e.g. `@returns [String]`.
 		#
-		# @yield [String]
-		# @return [Enumerable]
+		# @yields {|match| ...}
+		# 	@parameter match [MatchData] The regular expression match with `name` and `value` keys.
+		# @returns [Enumerable] If no block given.
 		def attributes
 			return to_enum(:attributes) unless block_given?
 			
@@ -77,13 +79,14 @@ module Bake
 			end
 		end
 		
-		PARAMETER = /\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/
+		PARAMETER = /\A\s*@param(eter)?\s+(?<name>.*?)\s+\[(?<type>.*?)\](\s+(?<details>.*?))?\z/
 		
 		# The parameter lines of the comment block.
-		# e.g. `@param value [String] The value.`
+		# e.g. `@parameter value [String] The value.`
 		#
-		# @yield [String]
-		# @return [Enumerable]
+		# @yields {|match| ...}
+		# 	@parameter match [MatchData] The regular expression match with `name`, `type` and `details` keys.
+		# @returns [Enumerable] If no block given.
 		def parameters
 			return to_enum(:parameters) unless block_given?
 			

data/lib/bake/loader.rb

@@ -24,7 +24,7 @@ module Bake
 	# Represents a directory which contains bakefiles.
 	class Loader
 		# Initialize the loader with the specified root path.
-		# @param root [String] A file-system path.
+		# @parameter root [String] A file-system path.
 		def initialize(root, name: nil)
 			@root = root
 			@name = name
@@ -38,8 +38,8 @@ module Bake
 		attr :root
 		
 		# Enumerate all bakefiles within the loaders root directory.
-		# @block `{|path| ...}`
-		# @yield path [String] The Ruby source file path.
+		# @yields {|path| ...}
+		# 	@parameter path [String] The Ruby source file path.
 		def each
 			return to_enum unless block_given?
 			
@@ -49,7 +49,7 @@ module Bake
 		end
 		
 		# Load the {Scope} for the specified relative path within this loader, if it exists.
-		# @param path [Array(String)] A relative path.
+		# @parameter path [Array(String)] A relative path.
 		def scope_for(path)
 			*directory, file = *path
 			

data/lib/bake/loaders.rb

@@ -28,7 +28,7 @@ module Bake
 		include Enumerable
 		
 		# Create a loader using the specified working directory.
-		# @param working_directory [String]
+		# @parameter working_directory [String]
 		def self.default(working_directory)
 			loaders = self.new
 			
@@ -44,13 +44,13 @@ module Bake
 		end
 		
 		# Whether any loaders are defined.
-		# @return [Boolean]
+		# @returns [Boolean]
 		def empty?
 			@ordered.empty?
 		end
 		
 		# Add loaders according to the current working directory and loaded gems.
-		# @param working_directory [String]
+		# @parameter working_directory [String]
 		def append_defaults(working_directory)
 			# Load recipes from working directory:
 			self.append_path(working_directory)
@@ -66,7 +66,7 @@ module Bake
 		
 		# Append a specific project path to the search path for recipes.
 		# The computed path will have `bake` appended to it.
-		# @param current [String] The path to add.
+		# @parameter current [String] The path to add.
 		def append_path(current = Dir.pwd, **options)
 			bake_path = File.join(current, "bake")
 			
@@ -78,7 +78,7 @@ module Bake
 		end
 		
 		# Search from the current working directory until a suitable bakefile is found and add it.
-		# @param current [String] The path to start searching from.
+		# @parameter current [String] The path to start searching from.
 		def append_from_root(current = Dir.pwd, **options)
 			while current
 				append_path(current, **options)

data/lib/bake/recipe.rb

@@ -26,9 +26,9 @@ module Bake
 	class Recipe
 		# Initialize the recipe.
 		#
-		# @param instance [Base] The instance this recipe is attached to.
-		# @param name [String] The method name.
-		# @param method [Method | Nil] The method if already known.
+		# @parameter instance [Base] The instance this recipe is attached to.
+		# @parameter name [String] The method name.
+		# @parameter method [Method | Nil] The method if already known.
 		def initialize(instance, name, method = nil)
 			@instance = instance
 			@name = name
@@ -63,7 +63,7 @@ module Bake
 		end
 		
 		# The recipe's formal parameters, if any.
-		# @return [Array | Nil]
+		# @returns [Array | Nil]
 		def parameters
 			parameters = method.parameters
 			
@@ -73,7 +73,7 @@ module Bake
 		end
 		
 		# Whether this recipe has optional arguments.
-		# @return [Boolean]
+		# @returns [Boolean]
 		def options?
 			if parameters = self.parameters
 				type, name = parameters.last
@@ -101,9 +101,9 @@ module Bake
 		end
 		
 		# Process command line arguments into the ordered and optional arguments.
-		# @param arguments [Array(String)] The command line arguments
-		# @return ordered [Array]
-		# @return options [Hash]
+		# @parameter arguments [Array(String)] The command line arguments
+		# @returns ordered [Array]
+		# @returns options [Hash]
 		def prepare(arguments)
 			offset = 0
 			ordered = []
@@ -152,19 +152,19 @@ module Bake
 		end
 		
 		# Any comments associated with the source code which defined the method.
-		# @return [Array(String)] The comment lines.
+		# @returns [Array(String)] The comment lines.
 		def comments
 			@comments ||= read_comments
 		end
 		
 		# The documentation object which provides structured access to the {comments}.
-		# @return [Documentation]
+		# @returns [Documentation]
 		def documentation
 			@documentation ||= Documentation.new(self.comments)
 		end
 		
 		# The documented type signature of the recipe.
-		# @return [Array] An array of {Types} instances.
+		# @returns [Array] An array of {Types} instances.
 		def types
 			@types ||= read_types
 		end

data/lib/bake/scope.rb

@@ -42,9 +42,9 @@ module Bake
 		
 		# Recipes defined in this scope.
 		#
-		# @block `{|recipe| ...}`
-		# @yield recipe [Recipe]
-		# @return [Enumerable]
+		# @yields {|recipe| ...}
+		# 	@parameter recipe [Recipe]
+		# @returns [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -62,7 +62,7 @@ module Bake
 		
 		# Look up a recipe with a specific name.
 		#
-		# @param name [String] The instance method to look up.
+		# @parameter name [String] The instance method to look up.
 		def recipe_for(name)
 			Recipe.new(self, name, self.instance_method(name))
 		end

data/lib/bake/types/any.rb

@@ -28,25 +28,25 @@ module Bake
 		#
 		class Any
 			# Initialize the instance with an array of types.
-			# @param types [Array] the array of types.
+			# @parameter types [Array] the array of types.
 			def initialize(types)
 				@types = types
 			end
 			
 			# Create a copy of the current instance with the other type appended.
-			# @param other [Type] the type instance to append.
+			# @parameter other [Type] the type instance to append.
 			def | other
 				self.class.new([*@types, other])
 			end
 			
 			# Whether any of the listed types is a composite type.
-			# @return [Boolean] true if any of the listed types is `composite?`.
+			# @returns [Boolean] true if any of the listed types is `composite?`.
 			def composite?
 				@types.any?{|type| type.composite?}
 			end
 			
 			# Parse an input string, trying the listed types in order, returning the first one which doesn't raise an exception.
-			# @param input [String] the input to parse, e.g. `"5"`.
+			# @parameter input [String] the input to parse, e.g. `"5"`.
 			def parse(input)
 				@types.each do |type|
 					return type.parse(input)
@@ -69,7 +69,7 @@ module Bake
 		# An extension module which allows constructing `Any` types using the `|` operator.
 		module Type
 			# Create an instance of `Any` with the arguments as types.
-			# @param other [Type] the alternative type to match.
+			# @parameter other [Type] the alternative type to match.
 			def | other
 				Any.new([self, other])
 			end

data/lib/bake/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Bake
-	VERSION = "0.13.0"
+	VERSION = "0.14.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bake
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-04 00:00:00.000000000 Z
+date: 2020-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: samovar
@@ -24,34 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
-- !ruby/object:Gem::Dependency
-  name: bake-bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: utopia-project
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: covered
   requirement: !ruby/object:Gem::Requirement
@@ -94,21 +66,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: 
+description:
 email:
 - samuel.williams@oriontransfer.co.nz
 executables:
@@ -126,6 +84,8 @@ files:
 - gems.rb
 - guides/command-line-interface/README.md
 - guides/gem-integration/README.md
+- guides/getting-started/README.md
+- guides/links.yaml
 - guides/project-integration/README.md
 - lib/bake.rb
 - lib/bake/base.rb
@@ -159,7 +119,7 @@ licenses:
 - MIT
 metadata:
   donation_uri: https://github.com/sponsors/ioquatix
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -175,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A replacement for rake with a simpler syntax.
 test_files: []