bake 0.10.0 → 0.14.0

data/lib/bake/recipe.rb

@@ -19,37 +19,51 @@
 # THE SOFTWARE.
 
 require_relative 'types'
+require_relative 'documentation'
 
 module Bake
-	PARAMETER = /@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\Z/
-	
+	# Structured access to an instance method in a bakefile.
 	class Recipe
+		# Initialize the recipe.
+		#
+		# @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
 			@command = nil
-			@description = nil
+			@comments = nil
 			@types = nil
+			@documentation = nil
 			
 			@method = method
 			@arity = nil
 		end
 		
+		# The {Base} instance that this recipe is attached to.
 		attr :instance
+		
+		# The name of this recipe.
 		attr :name
 		
+		# Sort by location in source file.
 		def <=> other
 			self.source_location <=> other.source_location
 		end
 		
+		# The method implementation.
 		def method
 			@method ||= @instance.method(@name)
 		end
 		
+		# The source location of this recipe.
 		def source_location
 			self.method.source_location
 		end
 		
+		# The recipe's formal parameters, if any.
+		# @returns [Array | Nil]
 		def parameters
 			parameters = method.parameters
 			
@@ -58,6 +72,8 @@ module Bake
 			end
 		end
 		
+		# Whether this recipe has optional arguments.
+		# @returns [Boolean]
 		def options?
 			if parameters = self.parameters
 				type, name = parameters.last
@@ -66,6 +82,7 @@ module Bake
 			end
 		end
 		
+		# The command name for this recipe.
 		def command
 			@command ||= compute_command
 		end
@@ -74,6 +91,7 @@ module Bake
 			self.command
 		end
 		
+		# The method's arity, the required number of positional arguments.
 		def arity
 			if @arity.nil?
 				@arity = method.parameters.count{|type, name| type == :req}
@@ -82,6 +100,10 @@ module Bake
 			return @arity
 		end
 		
+		# Process command line arguments into the ordered and optional arguments.
+		# @parameter arguments [Array(String)] The command line arguments
+		# @returns ordered [Array]
+		# @returns options [Hash]
 		def prepare(arguments)
 			offset = 0
 			ordered = []
@@ -119,6 +141,7 @@ module Bake
 			return ordered, options
 		end
 		
+		# Call the recipe with the specified arguments and options.
 		def call(*arguments, **options)
 			if options?
 				@instance.send(@name, *arguments, **options)
@@ -128,18 +151,20 @@ module Bake
 			end
 		end
 		
-		def explain(context, *arguments, **options)
-			if options?
-				puts "#{self}(#{arguments.join(", ")}, #{options.inspect})"
-			else
-				puts "#{self}(#{arguments.join(", ")})"
-			end
+		# Any comments associated with the source code which defined the method.
+		# @returns [Array(String)] The comment lines.
+		def comments
+			@comments ||= read_comments
 		end
 		
-		def description
-			@description ||= read_description
+		# The documentation object which provides structured access to the {comments}.
+		# @returns [Documentation]
+		def documentation
+			@documentation ||= Documentation.new(self.comments)
 		end
 		
+		# The documented type signature of the recipe.
+		# @returns [Array] An array of {Types} instances.
 		def types
 			@types ||= read_types
 		end
@@ -158,23 +183,21 @@ module Bake
 			end
 		end
 		
-		def read_description
+		COMMENT = /\A\s*\#\s?(.*?)\Z/
+		
+		def read_comments
 			file, line_number = self.method.source_location
 			
 			lines = File.readlines(file)
 			line_index = line_number - 1
 			
-			# Legacy "recipe" syntax:
-			if match = lines[line_index].match(/description: "(.*?)"/)
-				return [match[1]]
-			end
-			
 			description = []
 			line_index -= 1
 			
 			# Extract comment preceeding method:
 			while line = lines[line_index]
-				if match = line.match(/^\s*\#\s?(.*?)$/)
+				# \Z matches a trailing newline:
+				if match = line.match(COMMENT)
 					description.unshift(match[1])
 				else
 					break
@@ -189,10 +212,8 @@ module Bake
 		def read_types
 			types = {}
 			
-			description.each do |description|
-				if fields = PARAMETER.match(description)
-					types[fields[:name].to_sym] = Types.parse(fields[:type])
-				end
+			self.documentation.parameters do |parameter|
+				types[parameter[:name].to_sym] = Types.parse(parameter[:type])
 			end
 			
 			return types

data/lib/bake/scope.rb

@@ -21,7 +21,9 @@
 require_relative 'recipe'
 
 module Bake
+	# Used for containing all methods defined in a bakefile.
 	module Scope
+		# Load the specified file into a unique scope module, which can then be included into a {Base} instance.
 		def self.load(file_path, path = [])
 			scope = Module.new
 			scope.extend(self)
@@ -38,10 +40,11 @@ module Bake
 			"Bake::Scope<#{self.const_get(:FILE_PATH)}>"
 		end
 		
-		def recipe(name, **options, &block)
-			define_method(name, &block)
-		end
-		
+		# Recipes defined in this scope.
+		#
+		# @yields {|recipe| ...}
+		# 	@parameter recipe [Recipe]
+		# @returns [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -52,10 +55,14 @@ module Bake
 			end
 		end
 		
+		# The path of the file that was used to {load} this scope.
 		def path
 			self.const_get(:PATH)
 		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, self.instance_method(name))
 		end

data/lib/bake/types.rb

@@ -24,8 +24,10 @@ require_relative 'types/boolean'
 require_relative 'types/decimal'
 require_relative 'types/float'
 require_relative 'types/hash'
+require_relative 'types/input'
 require_relative 'types/integer'
 require_relative 'types/nil'
+require_relative 'types/output'
 require_relative 'types/string'
 require_relative 'types/symbol'
 require_relative 'types/tuple'

data/lib/bake/types/any.rb

@@ -20,43 +20,70 @@
 
 module Bake
 	module Types
-		module Type
-			def | other
-				Any.new([self, other])
-			end
-		end
-		
+		# An ordered list of types. The first type to match the input is used.
+		#
+		#	```ruby
+		#	type = Bake::Types::Any(Bake::Types::String, Bake::Types::Integer)
+		#	```
+		#
 		class Any
+			# Initialize the instance with an 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.
+			# @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.
+			# @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.
+			# @parameter input [String] the input to parse, e.g. `"5"`.
 			def parse(input)
 				@types.each do |type|
 					return type.parse(input)
 				rescue
-					# Ignore
+					# Ignore.
 				end
 			end
 			
+			# As a class type, accepts any value.
 			def self.parse(value)
 				value
 			end
 			
+			# Generate a readable string representation of the listed types.
 			def to_s
 				"any of #{@types.join(', ')}"
 			end
 		end
 		
-		def self.Any(types)
+		# An extension module which allows constructing `Any` types using the `|` operator.
+		module Type
+			# Create an instance of `Any` with the arguments as types.
+			# @parameter other [Type] the alternative type to match.
+			def | other
+				Any.new([self, other])
+			end
+		end
+		
+		# A type constructor.
+		#
+		#	```ruby
+		#	Any(Integer, String)
+		#	```
+		#
+		# See [Any.initialize](#Bake::Types::Any::initialize).
+		#
+		def self.Any(*types)
 			Any.new(types)
 		end
 	end

data/lib/bake/types/input.rb

@@ -0,0 +1,42 @@
+# 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 'any'
+
+module Bake
+	module Types
+		module Input
+			extend Type
+			
+			def self.composite?
+				false
+			end
+			
+			def self.parse(input)
+				case input
+				when '-'
+					return $stdin
+				else
+					File.open(input)
+				end
+			end
+		end
+	end
+end

data/lib/bake/types/output.rb

@@ -0,0 +1,42 @@
+# 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 'any'
+
+module Bake
+	module Types
+		module Output
+			extend Type
+			
+			def self.composite?
+				false
+			end
+			
+			def self.parse(input)
+				case input
+				when '-'
+					return $stdout
+				else
+					File.open(input, "w")
+				end
+			end
+		end
+	end
+end

data/lib/bake/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bake
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-23 00:00:00.000000000 Z
+date: 2020-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: samovar
@@ -24,20 +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: covered
   requirement: !ruby/object:Gem::Requirement
@@ -80,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:
@@ -109,8 +81,12 @@ files:
 - bake.gemspec
 - bake.rb
 - bin/bake
-- example.png
 - 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
 - lib/bake/command.rb
@@ -118,6 +94,7 @@ files:
 - lib/bake/command/list.rb
 - lib/bake/command/top.rb
 - lib/bake/context.rb
+- lib/bake/documentation.rb
 - lib/bake/loader.rb
 - lib/bake/loaders.rb
 - lib/bake/recipe.rb
@@ -129,8 +106,10 @@ files:
 - lib/bake/types/decimal.rb
 - lib/bake/types/float.rb
 - lib/bake/types/hash.rb
+- lib/bake/types/input.rb
 - lib/bake/types/integer.rb
 - lib/bake/types/nil.rb
+- lib/bake/types/output.rb
 - lib/bake/types/string.rb
 - lib/bake/types/symbol.rb
 - lib/bake/types/tuple.rb
@@ -140,7 +119,7 @@ licenses:
 - MIT
 metadata:
   donation_uri: https://github.com/sponsors/ioquatix
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -156,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: []