build 2.6.2 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76c69fcd958a49d0cf6a3ab9bda243ae4bace5e42e73d126fbbcaaf315a05b18
-  data.tar.gz: eb7f5be1e576b3d00f141bd681819e610a68a196e3634bb1d396aa3cca6dc498
+  metadata.gz: '00349494157af5d057e1ee2a70c3b65c8dd6873fd60419e50f90cb47d2d77018'
+  data.tar.gz: 0131571a8d92702daba61ab85c00ede57e1856505ea06a39e504296759a8e123
 SHA512:
-  metadata.gz: 35f9975fc06d7d01ca2d03326c44d4a86e0ab4765baaae868df450eb2af06833b347b32f46e4b05919de4a1c35957144f9eacf6a7b6c9c6e93ad727efc5cf550
-  data.tar.gz: 11a2f6059d7264aec3cddafc588ebc7778c74f0fd89c734d57c8af8434afc855827033387b86e51b4e3967db9d31202d72428d18745ceac32742c98627431f12
+  metadata.gz: c3196a81c93111aa37ba354b225c5796d6c9600205e229a863865c84c7b29d4bf7e817af4a41a8db50ced349a1b68feb281708ac765e089d9dbe576496576fce
+  data.tar.gz: cce38609f20d57f6d751a5ba2ae80f321bc8d16eca34fb0f512d3b514d5695cc3bc418e9dee904ae1c821d10cd7cf67308fb13f1a28331d28889135f177a10fa

data/lib/build/build_node.rb

@@ -1,30 +1,21 @@
-# Copyright, 2016, 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.
+# frozen_string_literal: true
 
-require 'fileutils'
-require 'build/graph'
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require 'console/event/spawn'
+require "fileutils"
+require "build/graph"
 
+require "console/event/spawn"
+
+# @namespace
 module Build
+	# Represents a build graph node that applies a single provision to produce an output environment.
 	class BuildNode < Graph::Node
+		# Initialize the build node with an environment, provision, and arguments.
+		# @parameter environment [Build::Environment] The environment to build within.
+		# @parameter provision [Build::Dependency::Provision] The provision to apply.
+		# @parameter arguments [Array] Arguments passed to the provision constructor.
 		def initialize(environment, provision, arguments)
 			@environment = environment
 			@provision = provision
@@ -37,6 +28,7 @@ module Build
 		attr :provision
 		attr :arguments
 		
+		# @returns [Boolean] Whether this node is equal to another.
 		def == other
 			super and
 				@environment == other.environment and
@@ -44,22 +36,28 @@ module Build
 				@arguments == other.arguments
 		end
 		
+		# @returns [Integer] A hash value for this node.
 		def hash
 			super ^ @environment.hash ^ @provision.hash ^ @arguments.hash
 		end
 		
+		# @returns [Class] The task class to use for building this node.
 		def task_class(parent_task)
 			task_class = Rulebook.for(@environment).with(BuildTask, environment: @environment)
 		end
 		
+		# @returns [Build::Environment] A fresh copy of the environment for output.
 		def initial_environment
 			Build::Environment.new(@environment)
 		end
 		
+		# @returns [String] The name of the environment.
 		def name
 			@environment.name
 		end
 		
+		# Apply this node to the given task, constructing the output environment.
+		# @parameter task [Build::Task] The task context.
 		def apply!(task)
 			output_environment = self.initial_environment
 			
@@ -71,7 +69,12 @@ module Build
 	
 	# This task class serves as the base class for the environment specific task classes genearted when adding targets.
 	class BuildTask < Task
+		# Represents a failure when a spawned command exits with a non-zero status.
 		class CommandFailure < Graph::TransientError
+			# Initialize the failure with the task, arguments, and exit status.
+			# @parameter task [Build::BuildTask] The task that spawned the command.
+			# @parameter arguments [Array] The command arguments that were run.
+			# @parameter status [Process::Status] The exit status of the command.
 			def initialize(task, arguments, status)
 				@task = task
 				@arguments = arguments
@@ -80,6 +83,7 @@ module Build
 				super "#{File.basename(executable_name).inspect} exited with status #{@status.to_i}"
 			end
 			
+			# @returns [String] The name of the executable that failed.
 			def executable_name
 				if @arguments[0].kind_of? Hash
 					@arguments[1]
@@ -95,13 +99,17 @@ module Build
 		
 		attr_accessor :output_environment
 		
+		# @returns [Boolean] Whether the node is dirty and commands should actually be executed.
 		def wet?
 			@node.dirty?
 		end
 		
+		# Spawn a process if the node is dirty, raising {CommandFailure} on non-zero exit.
+		# @parameter arguments [Array] The command and its arguments.
+		# @parameter options [Hash] Options forwarded to the process group.
 		def spawn(*arguments, **options)
 			if wet?
-				@logger&.info(self) {Console::Event::Spawn.for(*arguments, **options)}
+				Console.info(self){Console::Event::Spawn.for(*arguments, **options)}
 				status = @group.spawn(*arguments, **options)
 				
 				if status != 0
@@ -110,70 +118,94 @@ module Build
 			end
 		end
 		
+		# @returns [Hash] A flattened, exported shell environment hash.
 		def shell_environment
 			@shell_environment ||= environment.flatten.export
 		end
 		
+		# Run a shell command within the task's environment.
+		# @parameter arguments [Array] The command and its arguments.
+		# @parameter options [Hash] Options forwarded to the process group.
 		def run!(*arguments, **options)
 			self.spawn(shell_environment, *arguments, **options)
 		end
 		
+		# Touch a file, creating or updating its modification time.
+		# @parameter path [String] The file path to touch.
 		def touch(path)
 			return unless wet?
 			
-			Console::Event::Spawn.for('touch', path).emit(self)
+			Console::Event::Spawn.for("touch", path).emit(self)
 			FileUtils.touch(path)
 		end
 		
+		# Copy a file from source to destination.
+		# @parameter source_path [String] The source file path.
+		# @parameter destination_path [String] The destination file path.
 		def cp(source_path, destination_path)
 			return unless wet?
 			
-			Console::Event::Spawn.for('cp', source_path, destination_path).emit(self)
+			Console::Event::Spawn.for("cp", source_path, destination_path).emit(self)
 			FileUtils.copy(source_path, destination_path)
 		end
 		
+		# Remove a file or directory recursively.
+		# @parameter path [String] The path to remove.
 		def rm(path)
 			return unless wet?
 			
-			Console::Event::Spawn.for('rm', '-rf', path).emit(self)
+			Console::Event::Spawn.for("rm", "-rf", path).emit(self)
 			FileUtils.rm_rf(path)
 		end
 		
+		# Create a directory and all intermediate directories.
+		# @parameter path [String] The directory path to create.
 		def mkpath(path)
 			return unless wet?
 			
 			unless File.exist?(path)
-				Console::Event::Spawn.for('mkdir', '-p', path).emit(self)
+				Console::Event::Spawn.for("mkdir", "-p", path).emit(self)
 				FileUtils.mkpath(path)
 			end
 		end
 		
+		# Install a file to a destination path.
+		# @parameter source_path [String] The source file path.
+		# @parameter destination_path [String] The destination file path.
 		def install(source_path, destination_path)
 			return unless wet?
 			
-			Console::Event::Spawn.for('install', source_path, destination_path).emit(self)
+			Console::Event::Spawn.for("install", source_path, destination_path).emit(self)
 			FileUtils.install(source_path, destination_path)
 		end
 		
+		# Write data to a file.
+		# @parameter path [String] The destination file path.
+		# @parameter data [String] The data to write.
+		# @parameter mode [String] The file open mode.
 		def write(path, data, mode = "w")
 			return unless wet?
 			
-			Console::Event::Spawn.for('write', path).emit(self, size: data.size)
+			Console::Event::Spawn.for("write", path).emit(self, size: data.size)
 			File.open(path, mode) do |file|
 				file.write(data)
 			end
 		end
 		
+		# Invoke a rule with the given arguments, normalising them and invoking the rule node.
+		# @parameter rule [Build::Rule] The rule to invoke.
+		# @parameter arguments [Hash] The arguments to pass to the rule.
+		# @returns [Object] The result of the rule, typically a file path.
 		def invoke_rule(rule, arguments, &block)
 			arguments = rule.normalize(arguments, self)
 			
-			@logger&.debug(self) {"-> #{rule}(#{arguments.inspect})"}
+			Console.debug(self){"-> #{rule}(#{arguments.inspect})"}
 			
 			invoke(
 				RuleNode.new(rule, arguments, &block)
 			)
 			
-			@logger&.debug(self) {"<- #{rule}(...) -> #{rule.result(arguments)}"}
+			Console.debug(self){"<- #{rule}(...) -> #{rule.result(arguments)}"}
 			
 			return rule.result(arguments)
 		end

data/lib/build/chain_node.rb

@@ -1,35 +1,20 @@
-# Copyright, 2018, 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.
+# frozen_string_literal: true
 
-require 'build/files'
-require 'build/graph'
+# Released under the MIT License.
+# Copyright, 2016-2019, by Samuel Williams.
 
-require_relative 'task'
-require_relative 'dependency_node'
+require "build/files"
+require "build/graph"
+
+require_relative "task"
+require_relative "dependency_node"
 
 module Build
 	# Responsible for processing a chain into a series of dependency nodes.
 	class ChainNode < Graph::Node
-		# @param chain [Chain] the chain to build.
-		# @param arguments [Array] the arguments to pass to the output environment constructor.
-		# @param anvironment [Build::Environment] the root environment to prepend into the chain.
+		# @parameter chain [Chain] the chain to build.
+		# @parameter arguments [Array] the arguments to pass to the output environment constructor.
+		# @parameter environment [Build::Environment] the root environment to prepend into the chain.
 		def initialize(chain, arguments, environment)
 			@chain = chain
 			@arguments = arguments
@@ -43,6 +28,7 @@ module Build
 		attr :arguments
 		attr :environment
 		
+		# @returns [Boolean] Whether this node is equal to another.
 		def == other
 			super and
 				@chain == other.chain and
@@ -50,14 +36,17 @@ module Build
 				@environment == other.environment
 		end
 		
+		# @returns [Integer] A hash value for this node.
 		def hash
 			super ^ @chain.hash ^ @arguments.hash ^ @environment.hash
 		end
 		
+		# @returns [Class] The task class to use for this node.
 		def task_class(parent_task)
 			Task
 		end
 		
+		# @returns [String] The name of the environment.
 		def name
 			@environment.name
 		end
@@ -72,6 +61,7 @@ module Build
 			end
 		end
 		
+		# @returns [String] A human-readable representation of this node.
 		def inspect
 			"#<#{self.class} #{@environment.inspect}>"
 		end

data/lib/build/controller.rb

@@ -1,44 +1,30 @@
-# Copyright, 2012, 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.
+# frozen_string_literal: true
 
-require 'build/files'
-require 'build/makefile'
-require 'build/environment'
-require 'process/group'
+# Released under the MIT License.
+# Copyright, 2015-2019, by Samuel Williams.
 
-require_relative 'rulebook'
-require_relative 'name'
+require "build/files"
+require "build/makefile"
+require "build/environment"
+require "process/group"
 
-require_relative 'rule_node'
-require_relative 'chain_node'
-require_relative 'task'
+require_relative "rulebook"
+require_relative "name"
 
-require 'console'
+require_relative "rule_node"
+require_relative "chain_node"
+require_relative "task"
+
+require "console"
 
 module Build
+	# Represents the top-level build controller that manages the walker and process group.
 	class Controller
-		def initialize(logger: Console.logger, limit: nil)
+		# Initialize the controller, yielding self to allow adding chain nodes.
+		# @parameter limit [Integer | Nil] Maximum number of concurrent processes.
+		def initialize(limit: nil)
 			@module = Module.new
 			
-			@logger = logger
-			
 			# Top level nodes, for sanity this is a static list.
 			@nodes = []
 			yield self
@@ -49,23 +35,26 @@ module Build
 			# The task class is captured as we traverse all the top level targets:
 			@task_class = nil
 			
-			@walker = Graph::Walker.new(logger: @logger, &self.method(:step))
+			@walker = Graph::Walker.new(&self.method(:step))
 		end
 		
-		attr :logger
-		
 		attr :nodes
 		attr :walker
 		
+		# Execute a single step of the build graph for the given node.
+		# @parameter walker [Build::Graph::Walker] The graph walker.
+		# @parameter node [Build::Graph::Node] The node to process.
+		# @parameter parent_task [Build::Task | Nil] The parent task, if any.
 		def step(walker, node, parent_task = nil)
 			task_class = node.task_class(parent_task) || Task
-			task = task_class.new(walker, node, @group, logger: @logger)
+			task = task_class.new(walker, node, @group)
 			
 			task.visit do
 				task.update
 			end
 		end
 		
+		# @returns [Boolean] Whether the build has failed.
 		def failed?
 			@walker.failed?
 		end
@@ -75,6 +64,7 @@ module Build
 			@nodes << ChainNode.new(chain, arguments, environment)
 		end
 		
+		# Execute all top-level nodes, waiting for each to complete.
 		def update
 			@nodes.each do |node|
 				# We wait for all processes to complete within each node. The result is that we don't execute top level nodes concurrently, but we do execute within each node concurrently where possible. Ideally, some node could be executed concurrently, but right now expressing non-file dependencies between nodes is not possible.

data/lib/build/dependency_node.rb

@@ -1,29 +1,20 @@
-# Copyright, 2012, 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.
+# frozen_string_literal: true
 
-require 'build/graph'
+# Released under the MIT License.
+# Copyright, 2019, by Samuel Williams.
 
-require_relative 'provision_node'
+require "build/graph"
+
+require_relative "provision_node"
 
 module Build
+	# Represents a build graph node for resolving and building a single dependency.
 	class DependencyNode < Graph::Node
+		# Initialize the dependency node.
+		# @parameter chain [Build::Dependency::Chain] The dependency chain.
+		# @parameter dependency [Build::Dependency] The dependency to resolve.
+		# @parameter environment [Build::Environment] The root environment.
+		# @parameter arguments [Array] Arguments passed down the build chain.
 		def initialize(chain, dependency, environment, arguments)
 			@chain = chain
 			@dependency = dependency
@@ -39,6 +30,7 @@ module Build
 		attr :environment
 		attr :arguments
 		
+		# @returns [Boolean] Whether this node is equal to another.
 		def == other
 			super and
 				@chain == other.chain and
@@ -47,38 +39,50 @@ module Build
 				@arguments == other.arguments
 		end
 		
+		# @returns [Integer] A hash value for this node.
 		def hash
 			super ^ @chain.hash ^ @dependency.hash ^ @environment.hash ^ @arguments.hash
 		end
 		
+		# @returns [Class] The task class to use for this node.
 		def task_class(parent_task)
 			DependencyTask
 		end
 		
+		# @returns [String] The name of the dependency.
 		def name
 			@dependency.name
 		end
 		
+		# @returns [Array] The provisions resolved for this dependency.
 		def provisions
 			@chain.resolved[@dependency]
 		end
 		
+		# @returns [Boolean] Whether this dependency is public.
 		def public?
 			@dependency.public?
 		end
 		
+		# Build a {ProvisionNode} for the given provision.
+		# @parameter provision [Build::Dependency::Provision] The provision to wrap.
+		# @returns [Build::ProvisionNode] The corresponding provision node.
 		def provision_node_for(provision)
 			ProvisionNode.new(@chain, provision, @environment, @arguments)
 		end
 	end
 	
+	# @namespace
 	module ProvisionsFailed
+		# @returns [String] A description of the failure.
 		def self.to_s
 			"Failed to build all provisions!"
 		end
 	end
 	
+	# Represents a task that resolves and builds all provisions for a dependency.
 	class DependencyTask < Task
+		# Initialize the dependency task.
 		def initialize(*arguments, **options)
 			super
 			
@@ -90,12 +94,14 @@ module Build
 		
 		attr :environment
 		
+		# @returns [Build::Dependency] The dependency being resolved by this task.
 		def dependency
 			@node.dependency
 		end
 		
+		# Build all provisions for the dependency and combine the resulting environments.
 		def update
-			logger.debug(self) do |buffer|
+			Console.debug(self) do |buffer|
 				buffer.puts "building #{@node} which #{@node.dependency}"
 				@node.provisions.each do |provision|
 					buffer.puts "\tbuilding #{provision.provider.name} which #{provision}"

data/lib/build/graphviz.rb

@@ -1,37 +1,25 @@
-# Copyright, 2015, 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.
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2015, by Samuel Williams.
 
 module Build
+	# Generate a Graphviz graph visualisation of the build graph.
+	# @parameter walker [Build::Graph::Walker] The completed walker containing tasks.
+	# @returns [Graphviz::Graph] A graph object ready for rendering.
 	def self.graph_visualisation(walker)
-		viz = Graphviz::Graph.new('G', rankdir: "LR")
+		graph = Graphviz::Graph.new("G", rankdir: "LR")
 		
 		walker.tasks.each do |node, task|
 			input_nodes = []
 			output_nodes = []
 			
 			task.inputs.each do |path|
-				input_nodes << viz.add_node(path.basename)
+				input_nodes << graph.add_node(path.basename)
 			end
 			
 			task.outputs.each do |path|
-				output_nodes << viz.add_node(path.basename)
+				output_nodes << graph.add_node(path.basename)
 			end
 			
 			if output_nodes.size == 1
@@ -41,9 +29,7 @@ module Build
 				end
 			end
 		end
-
-		return viz
-		#Graphviz::output(viz, path: ENV['BUILD_GRAPH_PDF']) rescue nil
-		#`dot -Tpdf graph.dot > graph.pdf && open graph.pdf`
+		
+		return graph
 	end
 end

data/lib/build/name.rb

@@ -1,25 +1,13 @@
-# Copyright, 2013, 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.
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2015-2019, by Samuel Williams.
 
 module Build
+	# Represents a human-readable name with helpers for generating identifiers, target names, and macros.
 	class Name
+		# Initialize the name with the given text.
+		# @parameter text [String] The human-readable name text.
 		def initialize(text)
 			@text = text
 			
@@ -28,6 +16,9 @@ module Build
 			@key = nil
 		end
 		
+		# Construct a {Name} from a hyphen-separated target name string.
+		# @parameter string [String] A target name such as `"foo-bar"`.
+		# @returns [Build::Name] The corresponding name instance.
 		def self.from_target(string)
 			self.new(string.gsub(/(^|[ \-_])(.)/){" " + $2.upcase}.strip)
 		end
@@ -36,27 +27,27 @@ module Build
 		
 		# @return [String] suitable for constant identifier.
 		def identifier
-			@identifier ||= @text.gsub(/\s+/, '')
+			@identifier ||= @text.gsub(/\s+/, "")
 		end
 		
 		# @return [String] suitable for target name.
 		def target
-			@target ||= @text.gsub(/\s+/, '-').downcase
+			@target ||= @text.gsub(/\s+/, "-").downcase
 		end
 		
 		# @return [String] suitable for variable name.
 		def key(*postfix)
-			@key ||= ([@text] + postfix).collect{|part| part.downcase.gsub(/\s+/, '_')}.join('_')
+			@key ||= ([@text] + postfix).collect{|part| part.downcase.gsub(/\s+/, "_")}.join("_")
 		end
 		
 		# @return [String] suitable for C macro name.
 		def macro(prefix = [])
-			(Array(prefix) + [@text]).collect{|name| name.upcase.gsub(/\s+/, '_')}.join('_')
+			(Array(prefix) + [@text]).collect{|name| name.upcase.gsub(/\s+/, "_")}.join("_")
 		end
 		
 		# @return [String] suitable for C header guard macro.
 		def header_guard(path)
-			macro(path) + '_H'
+			macro(path) + "_H"
 		end
 	end
 end