bake 0.10.0 → 0.14.0

data/lib/bake/base.rb

@@ -22,7 +22,10 @@ require_relative 'recipe'
 require_relative 'scope'
 
 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.
+		# @parameter path [Array(String)] The command path.
 		def self.derive(path = [])
 			klass = Class.new(self)
 			
@@ -31,6 +34,8 @@ module Bake
 			return klass
 		end
 		
+		# Format the class as a command.
+		# @returns [String]
 		def self.to_s
 			if path = self.path
 				path.join(':')
@@ -47,20 +52,31 @@ module Bake
 			end
 		end
 		
+		# The path of this derived base class.
+		# @returns [Array(String)]
 		def self.path
 			self.const_get(:PATH)
 		rescue
 			nil
 		end
 		
+		# The path for this derived base class.
+		# @returns [Array(String)]
 		def path
 			self.class.path
 		end
 		
+		# Proxy a method call using command line arguments through to the {Context} instance.
+		# @parameter arguments [Array(String)]
 		def call(*arguments)
 			self.context.call(*arguments)
 		end
 		
+		# Recipes defined in this scope.
+		#
+		# @yields {|recipe| ...}
+		# 	@parameter recipe [Recipe]
+		# @returns [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -71,6 +87,9 @@ module Bake
 			end
 		end
 		
+		# Look up a recipe with a specific name.
+		#
+		# @parameter name [String] The instance method to look up.
 		def recipe_for(name)
 			Recipe.new(self, name)
 		end

data/lib/bake/command.rb

@@ -21,6 +21,7 @@
 require_relative 'command/top'
 
 module Bake
+	# The command line interface.
 	module Command
 		def self.call(*arguments)
 			Top.call(*arguments)

data/lib/bake/command/call.rb

@@ -26,6 +26,7 @@ require_relative '../context'
 
 module Bake
 	module Command
+		# Execute one or more commands.
 		class Call < Samovar::Command
 			self.description = "Execute one or more commands."
 			

data/lib/bake/command/list.rb

@@ -23,8 +23,11 @@ require 'set'
 
 module Bake
 	module Command
+		# List all available commands.
 		class List < Samovar::Command
-			PARAMETER = /@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\Z/
+			self.description = "List all available commands."
+			
+			one :pattern, "The pattern to filter tasks by."
 			
 			def format_parameters(parameters, terminal)
 				parameters.each do |type, name|
@@ -52,25 +55,39 @@ module Bake
 				end
 			end
 			
-			def print_scope(terminal, scope)
+			def print_scope(terminal, scope, printed: false)
 				format_recipe = self.method(:format_recipe).curry
 				
 				scope.recipes.sort.each do |recipe|
+					if @pattern and !recipe.command.include?(pattern)
+						next
+					end
+					
+					unless printed
+						yield
+						
+						printed = true
+					end
+					
 					terminal.print_line
 					terminal.print_line("\t", format_recipe[recipe])
 					
-					recipe.description.each do |line|
-						if match = line.match(PARAMETER)
-							terminal.print_line("\t\t",
-								:parameter, match[:name], :reset, " [",
-								:type, match[:type], :reset, "] ",
-								:description, match[:details]
-							)
-						else
-							terminal.print_line("\t\t", :description, line)
-						end
+					documentation = recipe.documentation
+					
+					documentation.description do |line|
+						terminal.print_line("\t\t", :description, line)
+					end
+					
+					documentation.parameters do |parameter|
+						terminal.print_line("\t\t",
+							:parameter, parameter[:name], :reset, " [",
+							:type, parameter[:type], :reset, "] ",
+							:description, parameter[:details]
+						)
 					end
 				end
+				
+				return printed
 			end
 			
 			def call
@@ -79,23 +96,30 @@ module Bake
 				context = @parent.context
 				
 				if scope = context.scope
-					terminal.print_line(:context, context)
-					
-					print_scope(terminal, context.scope)
+					printed = print_scope(terminal, context.scope) do
+						terminal.print_line(:context, context)
+					end
 					
-					terminal.print_line
+					if printed
+						terminal.print_line
+					end
 				end
 				
 				context.loaders.each do |loader|
-					terminal.print_line(:loader, loader)
+					printed = false
 					
 					loader.each do |path|
 						if scope = loader.scope_for(path)
-							print_scope(terminal, scope)
+							print_scope(terminal, scope, printed: printed) do
+								terminal.print_line(:loader, loader)
+								printed = true
+							end
 						end
 					end
 					
-					terminal.print_line
+					if printed
+						terminal.print_line
+					end
 				end
 			end
 		end

data/lib/bake/command/top.rb

@@ -26,6 +26,7 @@ require_relative 'list'
 
 module Bake
 	module Command
+		# The top level command line application.
 		class Top < Samovar::Command
 			self.description = "Execute tasks using Ruby."
 			
@@ -56,12 +57,12 @@ module Bake
 				return terminal
 			end
 			
-			def bakefile
+			def bakefile_path
 				@options[:bakefile] || Dir.pwd
 			end
 			
 			def context
-				Context.load(self.bakefile)
+				Context.load(self.bakefile_path)
 			end
 			
 			def call

data/lib/bake/context.rb

@@ -21,11 +21,14 @@
 require_relative 'base'
 
 module Bake
+	# The default file name for the top level bakefile.
 	BAKEFILE = "bake.rb"
 	
+	# Represents a context of task execution, containing all relevant state.
 	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
@@ -52,7 +55,9 @@ module Bake
 			return nil
 		end
 		
-		def self.load(path)
+		# Load a context from the specified path.
+		# @path [String] A file-system path.
+		def self.load(path = Dir.pwd)
 			if bakefile_path = self.bakefile_path(path)
 				scope = Scope.load(bakefile_path)
 				
@@ -68,6 +73,8 @@ module Bake
 			return self.new(loaders, scope, working_directory)
 		end
 		
+		# Initialize the context with the specified loaders.
+		# @parameter loaders [Loaders]
 		def initialize(loaders, scope = nil, root = nil)
 			@loaders = loaders
 			
@@ -92,10 +99,18 @@ module Bake
 			end
 		end
 		
+		# The loaders which will be used to resolve recipes in this context.
+		attr :loaders
+		
+		# The scope for the root {BAKEFILE}.
 		attr :scope
+		
+		# The root path of this context.
+		# @returns [String | Nil]
 		attr :root
-		attr :loaders
 		
+		# Invoke recipes on the context using command line arguments.
+		# @parameter commands [Array(String)]
 		def call(*commands)
 			last_result = nil
 			
@@ -111,6 +126,8 @@ module Bake
 			return last_result
 		end
 		
+		# Lookup a recipe for the given command name.
+		# @parameter command [String] The command name, e.g. `bundler:release`.
 		def lookup(command)
 			@recipes[command]
 		end
@@ -147,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

@@ -0,0 +1,100 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+require_relative 'scope'
+
+module Bake
+	# Structured access to a set of comment lines.
+	class Documentation
+		# Initialize the documentation with an array of comments.
+		#
+		# @parameter comments [Array(String)] An array of comment lines.
+		def initialize(comments)
+			@comments = comments
+		end
+		
+		DESCRIPTION = /\A\s*([^@\s].*)?\z/
+		
+		# The text-only lines of the comment block.
+		#
+		# @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?
+			
+			# We track empty lines and only yield a single empty line when there is another line of text:
+			gap = false
+			
+			@comments.each do |comment|
+				if match = comment.match(DESCRIPTION)
+					if match[1]
+						if gap
+							yield ""
+							gap = false
+						end
+						
+						yield match[1]
+					else
+						gap = true
+					end
+				else
+					break
+				end
+			end
+		end
+		
+		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
+		
+		# The attribute lines of the comment block.
+		# e.g. `@returns [String]`.
+		#
+		# @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?
+			
+			@comments.each do |comment|
+				if match = comment.match(ATTRIBUTE)
+					yield match
+				end
+			end
+		end
+		
+		PARAMETER = /\A\s*@param(eter)?\s+(?<name>.*?)\s+\[(?<type>.*?)\](\s+(?<details>.*?))?\z/
+		
+		# The parameter lines of the comment block.
+		# e.g. `@parameter value [String] The value.`
+		#
+		# @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?
+			
+			@comments.each do |comment|
+				if match = comment.match(PARAMETER)
+					yield match
+				end
+			end
+		end
+	end
+end

data/lib/bake/loader.rb

@@ -21,7 +21,10 @@
 require_relative 'scope'
 
 module Bake
+	# Represents a directory which contains bakefiles.
 	class Loader
+		# Initialize the loader with the specified root path.
+		# @parameter root [String] A file-system path.
 		def initialize(root, name: nil)
 			@root = root
 			@name = name
@@ -31,8 +34,12 @@ module Bake
 			"#{self.class} #{@name || @root}"
 		end
 		
+		# The root path for this loader.
 		attr :root
 		
+		# Enumerate all bakefiles within the loaders root directory.
+		# @yields {|path| ...}
+		# 	@parameter path [String] The Ruby source file path.
 		def each
 			return to_enum unless block_given?
 			
@@ -41,18 +48,8 @@ module Bake
 			end
 		end
 		
-		def recipe_for(path)
-			if book = lookup(path)
-				return book.lookup(path.last)
-			else
-				*path, name = *path
-				
-				if book = lookup(path)
-					return book.lookup(name)
-				end
-			end
-		end
-		
+		# Load the {Scope} for the specified relative path within this loader, if it exists.
+		# @parameter path [Array(String)] A relative path.
 		def scope_for(path)
 			*directory, file = *path
 			

data/lib/bake/loaders.rb

@@ -23,9 +23,12 @@ require 'console'
 require_relative 'loader'
 
 module Bake
+	# Structured access to the working directory and loaded gems for loading bakefiles.
 	class Loaders
 		include Enumerable
 		
+		# Create a loader using the specified working directory.
+		# @parameter working_directory [String]
 		def self.default(working_directory)
 			loaders = self.new
 			
@@ -34,15 +37,20 @@ module Bake
 			return loaders
 		end
 		
+		# Initialize an empty array of loaders.
 		def initialize
 			@roots = {}
 			@ordered = Array.new
 		end
 		
+		# Whether any loaders are defined.
+		# @returns [Boolean]
 		def empty?
 			@ordered.empty?
 		end
 		
+		# Add loaders according to the current working directory and loaded gems.
+		# @parameter working_directory [String]
 		def append_defaults(working_directory)
 			# Load recipes from working directory:
 			self.append_path(working_directory)
@@ -51,32 +59,26 @@ module Bake
 			self.append_from_gems
 		end
 		
+		# Enumerate the loaders in order.
 		def each(&block)
-			return to_enum unless block_given?
-			
 			@ordered.each(&block)
 		end
 		
+		# Append a specific project path to the search path for recipes.
+		# The computed path will have `bake` appended to it.
+		# @parameter current [String] The path to add.
 		def append_path(current = Dir.pwd, **options)
-			recipes_path = File.join(current, "recipes")
 			bake_path = File.join(current, "bake")
 			
 			if File.directory?(bake_path)
 				return insert(bake_path, **options)
 			end
 			
-			if File.directory?(recipes_path)
-				Console.logger.warn(self) do |buffer|
-					buffer.puts "Recipes path: #{recipes_path.inspect} is deprecated."
-					buffer.puts "Please use #{bake_path.inspect} instead."
-				end
-				
-				return insert(recipes_path, **options)
-			end
-			
 			return false
 		end
 		
+		# Search from the current working directory until a suitable bakefile is found and add it.
+		# @parameter current [String] The path to start searching from.
 		def append_from_root(current = Dir.pwd, **options)
 			while current
 				append_path(current, **options)
@@ -91,6 +93,7 @@ module Bake
 			end
 		end
 		
+		# Enumerate all loaded gems and add them.
 		def append_from_gems
 			Gem.loaded_specs.each do |name, spec|
 				Console.logger.debug(self) {"Checking gem #{name}: #{spec.full_gem_path}..."}
@@ -101,12 +104,6 @@ module Bake
 			end
 		end
 		
-		def append_from_paths(paths, **options)
-			paths.each do |path|
-				append_path(path, **options)
-			end
-		end
-		
 		protected
 		
 		def insert(directory, **options)