build-files 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42755d95c3e69cdd6fb72489a512fdd2ac7accb52054f968776812d1c96f8620
-  data.tar.gz: 6500729b61e4e4942d9d328703b992e836efb76712eb56111bbc5c75ab4e34bd
+  metadata.gz: 555dbd01ff6915b1d7a9c11864d95544929e35006094fb0eda4ca7b8d8227006
+  data.tar.gz: 6c17197d4bacc772f1e9aed6bce37cfab7ea4dcfb172c07a7ad955dfd8dc25ce
 SHA512:
-  metadata.gz: 5ac7d461b0edc8cb150b50e33233cacb0bc5c288d648934e5766a01906e87124363486aaf52c4b0d6f67a596c9b816c676f7442d6ac9083959ef2dc4a61dc15a
-  data.tar.gz: 397eae8916a14648b689a708c76b04ab4a6b7c59112e2f2a1ee5d8fc8ae12d07b2c56baa44e95b6cfce287dfc5d61a7ef571197cce5891f2071012541d7d15d7
+  metadata.gz: 8078524f809ad559c7c62de94ac98db9e6129e7d97f268fa2440a4732fbd3cba590d37775d9021b5a118c6957b81d87dbfb2321065fcd0eb32e9ab6e099617e8
+  data.tar.gz: 951b008d3c8a395024acfa3d83db9dc86cedadb3fbc6af4964f48cf23cc61f4f460eb63df40c7fd89efffaa3f6d6a818f2641a6c49b629d790643b01304c8e49

data/lib/build/files/composite.rb

@@ -1,20 +1,24 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Build
 	module Files
+		# Represents a composite list of files from multiple sources.
 		class Composite < List
+			# Initialize a composite list with multiple file lists.
+			# @parameter files [Array] The file lists to combine.
+			# @parameter roots [Array(Path) | Nil] The root paths, if known.
 			def initialize(files, roots = nil)
 				@files = []
 				
 				files.each do |list|
 					if list.kind_of? Composite
 						@files += list.files
-					elsif List.kind_of? List
+					elsif list.kind_of? List
 						@files << list
 					else
 						# Try to convert into a explicit paths list:
@@ -28,12 +32,16 @@ module Build
 			
 			attr :files
 			
+			# Freeze the composite list and its dependencies.
 			def freeze
 				self.roots
 				
 				super
 			end
 			
+			# Iterate over all files in the composite list.
+			# @yields {|path| ...} Each path in all combined lists.
+			#   @parameter path [Path] The current file path.
 			def each
 				return to_enum(:each) unless block_given?
 				
@@ -42,18 +50,28 @@ module Build
 				end
 			end
 			
+			# Get all root paths for all lists in the composite.
+			# @returns [Array(Path)] The unique root paths.
 			def roots
 				@roots ||= @files.collect(&:roots).flatten.uniq
 			end
 			
+			# Check equality with another composite list.
+			# @parameter other [Composite] The other composite to compare.
+			# @returns [Boolean] True if both composites have the same files.
 			def eql?(other)
 				self.class.eql?(other.class) and @files.eql?(other.files)
 			end
-		
+			
+			# Compute the hash value for this composite.
+			# @returns [Integer] The hash value based on files.
 			def hash
 				@files.hash
 			end
 			
+			# Combine this composite with another list.
+			# @parameter list [List] The list to add.
+			# @returns [Composite] A new composite containing both lists.
 			def +(list)
 				if list.kind_of? Composite
 					self.class.new(@files + list.files)
@@ -61,19 +79,29 @@ module Build
 					self.class.new(@files + [list])
 				end
 			end
-		
+			
+			# Check if the composite includes a specific path.
+			# @parameter path [Path] The path to check.
+			# @returns [Boolean] True if any list in the composite includes the path.
 			def include?(path)
 				@files.any? {|list| list.include?(path)}
 			end
-		
+			
+			# Rebase all lists in the composite to a new root.
+			# @parameter root [Path] The new root path.
+			# @returns [Composite] A new composite with rebased lists.
 			def rebase(root)
 				self.class.new(@files.collect{|list| list.rebase(root)}, [root])
 			end
-		
+			
+			# Convert all lists in the composite to paths.
+			# @returns [Composite] A new composite with all lists converted to paths.
 			def to_paths
 				self.class.new(@files.collect(&:to_paths), roots: @roots)
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing the composite structure.
 			def inspect
 				"<Composite #{@files.inspect}>"
 			end

data/lib/build/files/difference.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Build
 	module Files
+		# Represents a list of files with exclusions applied.
 		class Difference < List
+			# Initialize a difference list.
+			# @parameter list [List] The base list of files.
+			# @parameter excludes [List] The list of files to exclude.
 			def initialize(list, excludes)
 				@list = list
 				@excludes = excludes
@@ -15,6 +19,7 @@ module Build
 			
 			attr :files
 			
+			# Freeze the difference list and its dependencies.
 			def freeze
 				@list.freeze
 				@excludes.freeze
@@ -22,6 +27,9 @@ module Build
 				super
 			end
 			
+			# Iterate over files in the base list, excluding those in the exclusion list.
+			# @yields {|path| ...} Each path not in the exclusion list.
+			#   @parameter path [Path] The current file path.
 			def each
 				return to_enum(:each) unless block_given?
 				
@@ -30,20 +38,31 @@ module Build
 				end
 			end
 			
+			# Subtract additional files from this difference.
+			# @parameter list [List] Additional files to exclude.
+			# @returns [Difference] A new difference with expanded exclusions.
 			def -(list)
-				self.class.new(@list, Composite.new(@excludes, list))
+				self.class.new(@list, Composite.new([@excludes, list]))
 			end
 			
+			# Check if the difference includes a specific path.
+			# @parameter path [Path] The path to check.
+			# @returns [Boolean] True if the path is in the base list but not excluded.
 			def include?(path)
-				@list.includes?(path) and !@excludes.include?(path)
+				@list.include?(path) and !@excludes.include?(path)
 			end
 			
+			# Rebase the difference to a new root.
+			# @parameter root [Path] The new root path.
+			# @returns [Difference] A new difference with rebased files.
 			def rebase(root)
-				self.class.new(@files.collect{|list| list.rebase(root)}, [root])
+				self.class.new(@list.rebase(root), @excludes.rebase(root))
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing the difference structure.
 			def inspect
-				"<Difference #{@files.inspect} - #{@excludes.inspect}>"
+				"<Difference #{@list.inspect} - #{@excludes.inspect}>"
 			end
 		end
 	end

data/lib/build/files/directory.rb

@@ -1,29 +1,42 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Build
 	module Files
+		# Represents a directory of files.
 		class Directory < List
+			# Join path components and create a directory.
+			# @parameter args [Array(String)] The path components to join.
+			# @returns [Directory] A new directory at the joined path.
 			def self.join(*args)
 				self.new(Path.join(*args))
 			end
 			
+			# Initialize a directory with a root path.
+			# @parameter root [Path | String] The root path of the directory.
 			def initialize(root)
 				@root = root
 			end
 			
+			# Get the root path of the directory.
+			# @returns [Path] The root path.
 			def root
 				@root
 			end
 			
+			# Get the root paths as an array.
+			# @returns [Array(Path)] An array containing the single root path.
 			def roots
 				[root]
 			end
 			
+			# Iterate over all files in the directory recursively.
+			# @yields {|path| ...} Each file path in the directory.
+			#   @parameter path [Path] The current file path.
 			def each
 				return to_enum(:each) unless block_given?
 				
@@ -33,32 +46,48 @@ module Build
 				end
 			end
 			
+			# Check equality with another directory.
+			# @parameter other [Directory] The other directory to compare.
+			# @returns [Boolean] True if both directories have the same root.
 			def eql?(other)
 				self.class.eql?(other.class) and @root.eql?(other.root)
 			end
 			
+			# Compute the hash value for this directory.
+			# @returns [Integer] The hash value based on the root.
 			def hash
 				@root.hash
 			end
-		
+			
+			# Check if the directory includes a specific path.
+			# @parameter path [Path] The path to check.
+			# @returns [Boolean] True if the path is within this directory.
 			def include?(path)
 				# Would be true if path is a descendant of full_path.
 				path.start_with?(@root)
 			end
-		
+			
+			# Rebase the directory to a new root.
+			# @parameter root [Path] The new root path.
+			# @returns [Directory] A new directory with the rebased root.
 			def rebase(root)
 				self.class.new(@root.rebase(root))
 			end
 			
-			# Convert a Directory into a String, can be used as an argument to a command.
+			# Convert the directory to a string for use as a command argument.
+			# @returns [String] The root path as a string.
 			def to_str
 				@root.to_str
 			end
 			
+			# Convert the directory to a string.
+			# @returns [String] The root path as a string.
 			def to_s
 				to_str
 			end
 			
+			# Convert the directory to a path object.
+			# @returns [Path] The root path.
 			def to_path
 				@root
 			end

data/lib/build/files/glob.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Build
 	module Files
 		class Path
+			# Create a glob pattern matcher for files under this path.
+			# @parameter pattern [String] The glob pattern to match.
+			# @returns [Glob] A glob matcher for the pattern.
 			def glob(pattern)
 				Glob.new(self, pattern)
 			end
 		end
 		
+		# Represents a glob pattern for matching files.
 		class Glob < List
+			# Initialize a glob with a root path and pattern.
+			# @parameter root [Path] The root directory for the glob.
+			# @parameter pattern [String] The glob pattern to match.
 			def initialize(root, pattern)
 				@root = root
 				@pattern = pattern
@@ -22,10 +29,14 @@ module Build
 			attr :root
 			attr :pattern
 			
+			# Get the root paths for this glob.
+			# @returns [Array(Path)] An array containing the root path.
 			def roots
 				[@root]
 			end
 			
+			# Get the full pattern including the root path.
+			# @returns [String] The complete glob pattern.
 			def full_pattern
 				Path.join(@root, @pattern)
 			end
@@ -42,22 +53,35 @@ module Build
 				end
 			end
 			
+			# Check equality with another glob.
+			# @parameter other [Glob] The other glob to compare.
+			# @returns [Boolean] True if both globs have the same root and pattern.
 			def eql?(other)
 				self.class.eql?(other.class) and @root.eql?(other.root) and @pattern.eql?(other.pattern)
 			end
 			
+			# Compute the hash value for this glob.
+			# @returns [Integer] The hash value based on root and pattern.
 			def hash
 				[@root, @pattern].hash
 			end
 			
+			# Check if a path matches this glob pattern.
+			# @parameter path [Path] The path to check.
+			# @returns [Boolean] True if the path matches the pattern.
 			def include?(path)
 				File.fnmatch(full_pattern, path)
 			end
 			
+			# Rebase the glob to a new root.
+			# @parameter root [Path] The new root path.
+			# @returns [Glob] A new glob with the same pattern under the new root.
 			def rebase(root)
 				self.class.new(root, @pattern)
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing the full pattern.
 			def inspect
 				"<Glob #{full_pattern.inspect}>"
 			end

data/lib/build/files/list.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'path'
+require_relative "path"
 
 module Build
 	module Files
@@ -11,6 +11,8 @@ module Build
 		class List
 			include Enumerable
 			
+			# Get all unique root paths from the list.
+			# @returns [Array(Path)] Sorted unique root paths.
 			def roots
 				collect{|path| path.root}.sort.uniq
 			end
@@ -20,6 +22,9 @@ module Build
 				Composite.new([self, list])
 			end
 			
+			# Subtract a list from this list.
+			# @parameter list [List] The list to subtract.
+			# @returns [Difference] A difference list excluding the given paths.
 			def -(list)
 				Difference.new(self, list)
 			end
@@ -40,6 +45,8 @@ module Build
 				other.any?{|path| include?(path)}
 			end
 			
+			# Check if the list is empty.
+			# @returns [Boolean] True if the list contains no paths.
 			def empty?
 				each do
 					return false
@@ -48,6 +55,12 @@ module Build
 				return true
 			end
 			
+			# Transform paths with modified attributes.
+			# @parameter options [Hash] Options to pass to {Path#with}.
+			# @yields {|path, updated_path| ...} Each original and updated path.
+			#   @parameter path [Path] The original path.
+			#   @parameter updated_path [Path] The modified path.
+			# @returns [Paths] A new paths list with transformed paths.
 			def with(**options)
 				return to_enum(:with, **options) unless block_given?
 				
@@ -64,18 +77,30 @@ module Build
 				return Paths.new(paths)
 			end
 			
+			# Rebase all paths in the list to a new root.
+			# @parameter root [Path] The new root path.
+			# @returns [Paths] A new paths list with rebased paths.
 			def rebase(root)
 				Paths.new(self.collect{|path| path.rebase(root)}, [root])
 			end
 			
+			# Convert the list to a Paths instance.
+			# @returns [Paths] A paths list containing all items.
 			def to_paths
 				Paths.new(each.to_a)
 			end
 			
+			# Map over the list and return a Paths instance.
+			# @yields {|path| ...} Each path in the list.
+			#   @parameter path [Path] The current path.
+			# @returns [Paths] A new paths list with mapped values.
 			def map
 				Paths.new(super)
 			end
 			
+			# Coerce an argument to a List instance.
+			# @parameter arg [List | Object] The object to coerce.
+			# @returns [List] A list instance.
 			def self.coerce(arg)
 				if arg.kind_of? self
 					arg
@@ -84,6 +109,8 @@ module Build
 				end
 			end
 			
+			# Convert the list to a string.
+			# @returns [String] The string representation.
 			def to_s
 				inspect
 			end
@@ -91,4 +118,4 @@ module Build
 	end
 end
 
-require_relative 'difference'
+require_relative "difference"

data/lib/build/files/path.rb

@@ -1,20 +1,25 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
 module Build
 	module Files
 		# Represents a file path with an absolute root and a relative offset:
 		class Path
+			# Get the current working directory as a path.
+			# @returns [Path] The current directory path.
 			def self.current
 				self.new(::Dir.pwd)
 			end
 			
+			# Split a path into directory, filename, and extension components.
+			# @parameter path [String] The path to split.
+			# @returns [Array(String, String, String)] The directory, filename, and extension.
 			def self.split(path)
 				# Effectively dirname and basename:
 				dirname, separator, filename = path.rpartition(File::SEPARATOR)
-				filename, dot, extension = filename.rpartition('.')
+				filename, dot, extension = filename.rpartition(".")
 				
 				return dirname + separator, filename, dot + extension
 			end
@@ -33,6 +38,9 @@ module Build
 				end
 			end
 			
+			# Get the root directory of a path.
+			# @parameter path [Path | String] The path to get the root from.
+			# @returns [String] The root directory.
 			def self.root(path)
 				if Path === path
 					path.root
@@ -41,7 +49,10 @@ module Build
 				end
 			end
 			
-			# Return the shortest relative path to get to path from root. Root should be a directory with which you are computing the relative path.
+			# Compute the shortest relative path from root to path.
+			# @parameter path [Path | String] The target path.
+			# @parameter root [Path | String] The root directory.
+			# @returns [String] The shortest relative path.
 			def self.shortest_path(path, root)
 				path_components = Path.components(path)
 				root_components = Path.components(root)
@@ -61,6 +72,10 @@ module Build
 				end
 			end
 			
+			# Compute the relative path from root to full path.
+			# @parameter root [String] The root directory.
+			# @parameter full_path [String] The full path.
+			# @returns [String] The relative path.
 			def self.relative_path(root, full_path)
 				relative_offset = root.length
 				
@@ -70,6 +85,9 @@ module Build
 				return full_path.slice(relative_offset..-1)
 			end
 			
+			# Convert a path-like object to a Path instance.
+			# @parameter path [Path | String] The path to convert.
+			# @returns [Path] A Path instance.
 			def self.[] path
 				self === path ? path : self.new(path.to_s)
 			end
@@ -91,20 +109,28 @@ module Build
 			attr :root
 			attr :full_path
 			
+			# Get the length of the full path.
+			# @returns [Integer] The number of characters in the path.
 			def length
 				@full_path.length
 			end
 			
 			alias size length
 			
+			# Get the path components as an array.
+			# @returns [Array(String)] The path split by directory separator.
 			def components
 				@components ||= @full_path.split(File::SEPARATOR).freeze
 			end
 			
+			# Get the basename of the path.
+			# @returns [String] The last component of the path.
 			def basename
 				self.parts.last
 			end
 			
+			# Get the parent directory path.
+			# @returns [Path] The parent directory.
 			def parent
 				root = @root
 				full_path = File.dirname(@full_path)
@@ -120,22 +146,32 @@ module Build
 				self.class.new(full_path, root)
 			end
 			
+			# Check if the path starts with the given prefix.
+			# @parameter args [Array(String)] The prefix strings to check.
+			# @returns [Boolean] True if the path starts with any of the prefixes.
 			def start_with?(*args)
 				@full_path.start_with?(*args)
 			end
 			
 			alias parts components
 			
+			# Get the relative path from the root.
+			# @returns [String] The path relative to the root.
 			def relative_path
 				@relative_path ||= Path.relative_path(@root.to_s, @full_path.to_s).freeze
 			end
 			
+			# Split the relative path into directory and basename components.
+			# @returns [Array(String, String)] The directory and basename.
 			def relative_parts
 				dirname, _, basename = self.relative_path.rpartition(File::SEPARATOR)
 				
 				return dirname, basename
 			end
 			
+			# Append an extension to the path.
+			# @parameter extension [String] The extension to append.
+			# @returns [Path] A new path with the extension appended.
 			def append(extension)
 				self.class.new(@full_path + extension, @root)
 			end
@@ -160,10 +196,18 @@ module Build
 				end
 			end
 			
+			# Rebase the path to a new root directory.
+			# @parameter root [Path | String] The new root.
+			# @returns [Path] A new path with the same relative path under the new root.
 			def rebase(root)
 				self.class.new(File.join(root, relative_path), root)
 			end
 			
+			# Create a modified path with new root, extension, or basename.
+			# @parameter root [Path | String] The new root directory.
+			# @parameter extension [String | Nil] An extension to add.
+			# @parameter basename [String | Boolean | Nil] A new basename or `true` to keep existing.
+			# @returns [Path] A new path with the specified modifications.
 			def with(root: @root, extension: nil, basename: false)
 				relative_path = self.relative_path
 				
@@ -183,6 +227,10 @@ module Build
 				self.class.new(File.join(root, relative_path), root, relative_path)
 			end
 			
+			# Join a root and relative path to create a new Path.
+			# @parameter root [String] The root directory.
+			# @parameter relative_path [String] The relative path.
+			# @returns [Path] A new path combining root and relative path.
 			def self.join(root, relative_path)
 				self.new(File.join(root, relative_path), root)
 			end
@@ -196,56 +244,81 @@ module Build
 				end
 			end
 			
+			# Compute the shortest path from this path to a root.
+			# @parameter root [Path | String] The root directory.
+			# @returns [String] The shortest relative path.
 			def shortest_path(root)
 				self.class.shortest_path(self, root)
 			end
 			
+			# Convert the path to a string.
+			# @returns [String] The full path as a string.
 			def to_str
 				@full_path.to_str
 			end
 			
+			# Convert the path to a path string.
+			# @returns [String] The full path.
 			def to_path
 				@full_path
 			end
 			
+			# Convert the path to a string representation.
+			# @returns [String] The full path as a string.
 			def to_s
 				# It's not guaranteed to be string.
 				@full_path.to_s
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing root and relative path.
 			def inspect
 				"#{@root.inspect}/#{relative_path.inspect}"
 			end
 			
+			# Compute the hash value for this path.
+			# @returns [Integer] The hash value based on root and full path.
 			def hash
 				[@root, @full_path].hash
 			end
 			
+			# Check equality with another path.
+			# @parameter other [Path] The other path to compare.
+			# @returns [Boolean] True if both paths have the same root and full path.
 			def eql?(other)
 				self.class.eql?(other.class) and @root.eql?(other.root) and @full_path.eql?(other.full_path)
 			end
 			
 			include Comparable
 			
+			# Compare this path with another for sorting.
+			# @parameter other [Path] The other path to compare.
+			# @returns [Integer] -1, 0, or 1 for less than, equal, or greater than.
 			def <=>(other)
 				self.to_s <=> other.to_s
 			end
 			
 			# Match a path with a given pattern, using `File#fnmatch`.
 			def match(pattern, flags = 0)
-				path = pattern.start_with?('/') ? full_path : relative_path
+				path = pattern.start_with?("/") ? full_path : relative_path
 				
 				return File.fnmatch(pattern, path, flags)
 			end
 			
+			# Get file opening arguments for reading.
+			# @returns [Array] The path and file mode for reading.
 			def for_reading
 				[@full_path, File::RDONLY]
 			end
 			
+			# Get file opening arguments for writing.
+			# @returns [Array] The path and file mode for writing.
 			def for_writing
 				[@full_path, File::CREAT|File::TRUNC|File::WRONLY]
 			end
 			
+			# Get file opening arguments for appending.
+			# @returns [Array] The path and file mode for appending.
 			def for_appending
 				[@full_path, File::CREAT|File::APPEND|File::WRONLY]
 			end

data/lib/build/files/paths.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Build
 	module Files
+		# Represents an explicit list of file paths.
 		class Paths < List
+			# Initialize a paths list.
+			# @parameter list [Array] The array of paths.
+			# @parameter roots [Array(Path) | Nil] The root paths, if known.
 			def initialize(list, roots = nil)
 				@list = Array(list).freeze
 				@roots = roots
@@ -20,32 +24,50 @@ module Build
 				@roots ||= super
 			end
 			
+			# Get the count of paths in the list.
+			# @returns [Integer] The number of paths.
 			def count
 				@list.count
 			end
 			
+			# Iterate over all paths in the list.
+			# @yields {|path| ...} Each path in the list.
+			#   @parameter path [Path] The current path.
 			def each
 				return to_enum(:each) unless block_given?
 				
 				@list.each{|path| yield path}
 			end
 			
+			# Check equality with another paths list.
+			# @parameter other [Paths] The other paths list to compare.
+			# @returns [Boolean] True if both have the same paths.
 			def eql?(other)
 				self.class.eql?(other.class) and @list.eql?(other.list)
 			end
-		
+			
+			# Compute the hash value for this paths list.
+			# @returns [Integer] The hash value based on the list.
 			def hash
 				@list.hash
 			end
 			
+			# Return this paths list unchanged.
+			# @returns [Paths] Self.
 			def to_paths
 				self
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing the paths.
 			def inspect
 				"<Paths #{@list.inspect}>"
 			end
 			
+			# Create a paths list from a directory root and relative paths.
+			# @parameter root [Path] The root directory.
+			# @parameter relative_paths [Array(String)] The relative paths.
+			# @returns [Paths] A new paths list.
 			def self.directory(root, relative_paths)
 				paths = relative_paths.collect do |path|
 					Path.join(root, path)
@@ -56,6 +78,9 @@ module Build
 		end
 		
 		class Path
+			# Create a paths list from relative paths under this path.
+			# @parameter relative_paths [Array(String)] The relative paths.
+			# @returns [Paths] A new paths list.
 			def list(*relative_paths)
 				Paths.directory(self, relative_paths)
 			end

data/lib/build/files/state.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
-require 'forwardable'
+require "forwardable"
 
 module Build
 	module Files
@@ -17,6 +17,9 @@ module Build
 			class FileTime
 				include Comparable
 				
+				# Initialize a file time record.
+				# @parameter path [Path] The file path.
+				# @parameter time [Time] The modification time.
 				def initialize(path, time)
 					@path = path
 					@time = time
@@ -25,15 +28,23 @@ module Build
 				attr :path
 				attr :time
 				
+				# Compare file times for ordering.
+				# @parameter other [FileTime] The other file time to compare.
+				# @returns [Integer] -1, 0, or 1 for less than, equal, or greater than.
 				def <=> other
 					@time <=> other.time
 				end
 				
+				# Generate a string representation for debugging.
+				# @returns [String] A debug string showing path and time.
 				def inspect
 					"<FileTime #{@path.inspect} #{@time.inspect}>"
 				end
 			end
 			
+			# Initialize file state tracking.
+			# @parameter files [List] The list of files to track.
+			# @raises [ArgumentError] If files is not a Files::List.
 			def initialize(files)
 				raise ArgumentError.new("Invalid files list: #{files}") unless Files::List === files
 				
@@ -55,6 +66,8 @@ module Build
 			
 			def_delegators :@files, :each, :roots, :count
 			
+			# Update the state by checking all files for changes.
+			# @returns [Boolean] True if any files were added, changed, removed, or are missing.
 			def update!
 				last_times = @times
 				@times = {}
@@ -72,7 +85,7 @@ module Build
 					
 					if File.exist?(path)
 						modified_time = File.mtime(path)
-					
+						
 						if last_time = last_times.delete(path)
 							# Path was valid last update:
 							if modified_time != last_time
@@ -86,9 +99,9 @@ module Build
 							
 							# puts "Added: #{path}"
 						end
-					
+						
 						@times[path] = modified_time
-					
+						
 						unless File.directory?(path)
 							file_times << FileTime.new(path, modified_time)
 						end
@@ -111,14 +124,20 @@ module Build
 			attr :oldest_time
 			attr :newest_time
 			
+			# Check if any files are missing.
+			# @returns [Boolean] True if any files do not exist.
 			def missing?
 				!@missing.empty?
 			end
 			
+			# Check if the state is empty.
+			# @returns [Boolean] True if no files are being tracked.
 			def empty?
 				@times.empty?
 			end
 			
+			# Generate a string representation for debugging.
+			# @returns [String] A debug string showing state changes.
 			def inspect
 				"<State Added:#{@added} Removed:#{@removed} Changed:#{@changed} Missing:#{@missing}>"
 			end
@@ -149,6 +168,10 @@ module Build
 				return true
 			end
 			
+			# Check if outputs are dirty with respect to inputs.
+			# @parameter inputs [State] The input files state.
+			# @parameter outputs [State] The output files state.
+			# @returns [Boolean] True if outputs need to be regenerated.
 			def self.dirty?(inputs, outputs)
 				outputs.dirty?(inputs)
 			end

data/lib/build/files/system.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require 'fileutils'
+require "fileutils"
 
-require_relative 'path'
-require_relative 'list'
+require_relative "path"
+require_relative "list"
 
 module Build
 	module Files
@@ -30,6 +30,8 @@ module Build
 				end
 			end
 			
+			# Copy the path to a destination.
+			# @parameter destination [Path] The destination path.
 			def copy(destination)
 				if directory?
 					destination.create
@@ -43,6 +45,8 @@ module Build
 				FileUtils.touch(self.to_s)
 			end
 			
+			# Get file statistics.
+			# @returns [File::Stat] The file statistics.
 			def stat
 				File.stat(self.to_s)
 			end
@@ -57,14 +61,20 @@ module Build
 				File.directory?(self.to_s)
 			end
 			
+			# Check if the path refers to a regular file.
+			# @returns [Boolean] True if the path is a file.
 			def file?
 				File.file?(self.to_s)
 			end
 			
+			# Check if the path is a symbolic link.
+			# @returns [Boolean] True if the path is a symlink.
 			def symlink?
 				File.symlink?(self.to_s)
 			end
 			
+			# Check if the file is readable.
+			# @returns [Boolean] True if the file can be read.
 			def readable?
 				File.readable?(self.to_s)
 			end
@@ -110,6 +120,8 @@ module Build
 				each(&:delete)
 			end
 			
+			# Copy all files in the list to a destination.
+			# @parameter destination [Path] The destination root path.
 			def copy(destination)
 				each do |path|
 					path.copy(destination / path.relative_path)

data/lib/build/files/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
+# @namespace
 module Build
+	# @namespace
 	module Files
-		VERSION = "1.9.0"
+		VERSION = "1.10.0"
 	end
 end

data/lib/build/files.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2023, by Samuel Williams.
+# Copyright, 2014-2025, by Samuel Williams.
 
-require_relative 'files/list'
-require_relative 'files/composite'
-require_relative 'files/paths'
-require_relative 'files/glob'
-require_relative 'files/directory'
+require_relative "files/list"
+require_relative "files/composite"
+require_relative "files/paths"
+require_relative "files/glob"
+require_relative "files/directory"
 
-require_relative 'files/system'
+require_relative "files/system"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2014-2023, by Samuel Williams.  
+Copyright, 2014-2025, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -20,19 +20,13 @@ Or install it yourself as:
 
 ## Usage
 
-The basic structure is the `Path`. Paths are stored with a root and relative part. By default, if no root is specified, it is the `dirname` part.
+Please see the [project documentation](https://github.com/ioquatix/build-files) for more details.
 
-    require 'build/files'
-    
-    path = Build::Files::Path("/foo/bar/baz")
-    => "/foo/bar"/"baz"
-    
-    > path.root
-    => "/foo/bar"
-    > path.relative_path
-    => "baz"
+## Releases
 
-Paths can be coerced to strings and thus are suitable arguments to `exec`/`system` functions.
+Please see the [project releases](https://github.com/ioquatix/build-filesreleases/index) for all releases.
+
+### v1.10.0
 
 ## Contributing
 
@@ -43,3 +37,11 @@ We welcome contributions to this project.
 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.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v1.10.0

data.tar.gz.sig

@@ -1,2 +1 @@
-z�0��\��7L�j�bǷ_mvd_Y�̬�ֵ���:,n��h��,�͂k� A.(�ͯE�9-15��%��
���'���l������3��V!B7QĔüy���\��U��_+���n,�h�
���
��93+H���ZG�SM�~)���9��ئٴI/�ݛ�K4q���F˚��"�%G�0�}/;��j�i	T�;���(� o_������_ݼ�"ꗘ�����m��S�i*�Gj/e8��x|�c��D�uZ�JE��VP�L�?!dep\@������5�����rS���<C��XΪ}���*%��Ue�	bp�e������*E��j'B�O�T
-n��k�[�����
+M�H�A��*L�ʌ��E%HH${�}��rE}��!�'ӄ�0�5�F�#Zw�3�ʡ�`�ON���^��\��k�ɾ |����,X�/�|�i�%{>|�i��@.��Hjǂg��_�4��hQ~��P�\����9!wG}���`AT�DŽ��!>��x�o��"���/��

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: build-files
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,57 +36,12 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2023-06-17 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: 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
-    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: sus
-  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:
-email:
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- conduct.md
 - lib/build/files.rb
 - lib/build/files/composite.rb
 - lib/build/files/difference.rb
@@ -101,12 +55,13 @@ files:
 - lib/build/files/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/ioquatix/build-files
 licenses:
 - MIT
 metadata:
   funding_uri: https://github.com/sponsors/ioquatix/
-post_install_message:
+  source_code_uri: https://github.com/ioquatix/build-files.git
 rdoc_options: []
 require_paths:
 - lib
@@ -114,15 +69,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Abstractions for handling and mapping paths.
 test_files: []

data/conduct.md

@@ -1,133 +0,0 @@
-
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations