build-files 1.9.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abffeac84e2e1e1585743ecdc01742332ae8629865701b306b10f1987c6cae8a
-  data.tar.gz: 03ddfbbc237aa66d472e7cbb108e2e364c0aa95a4ee7b769abcb98c0ba8cb1e4
+  metadata.gz: 555dbd01ff6915b1d7a9c11864d95544929e35006094fb0eda4ca7b8d8227006
+  data.tar.gz: 6c17197d4bacc772f1e9aed6bce37cfab7ea4dcfb172c07a7ad955dfd8dc25ce
 SHA512:
-  metadata.gz: 349d26dd750a8cf993a606502703b22c55b0479ec67b127e64658ac8a44be2ea6a96d0d44bb34751f4a7d1e40659e6af4ce886960ba680b0362316bc02a10a22
-  data.tar.gz: c93a0c33ec66c7862201b2d386f7133eaa874e3b4b5f87f42da427c21c49cdef6bbc82ad8f642134ed140cf5fecc930ba5fc4476f33ce1d7a9e439ddcc69902f
+  metadata.gz: 8078524f809ad559c7c62de94ac98db9e6129e7d97f268fa2440a4732fbd3cba590d37775d9021b5a118c6957b81d87dbfb2321065fcd0eb32e9ab6e099617e8
+  data.tar.gz: 951b008d3c8a395024acfa3d83db9dc86cedadb3fbc6af4964f48cf23cc61f4f460eb63df40c7fd89efffaa3f6d6a818f2641a6c49b629d790643b01304c8e49

data/lib/build/files/composite.rb

@@ -7,14 +7,18 @@ 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

@@ -7,7 +7,11 @@ 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

@@ -7,23 +7,36 @@ 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

@@ -8,12 +8,19 @@ 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

@@ -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

data/lib/build/files/path.rb

@@ -7,10 +7,15 @@ 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)
@@ -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,37 +244,56 @@ 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
@@ -238,14 +305,20 @@ module Build
 				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

@@ -7,7 +7,11 @@ 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

@@ -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

@@ -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.1"
+		VERSION = "1.10.0"
 	end
 end

data/readme.md

@@ -2,7 +2,7 @@
 
 Build::Files is a set of idiomatic classes for dealing with paths and monitoring directories. File paths are represented with both root and relative parts which makes copying directory structures intuitive.
 
-[![Development Status](/workflows/Test/badge.svg)](/actions?workflow=Test)
+[![Development Status](https://github.com/ioquatix/build-files/workflows/Test/badge.svg)](https://github.com/ioquatix/build-files/actions?workflow=Test)
 
 ## Installation
 
@@ -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
 

data/releases.md

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: build-files
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-03-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []
@@ -55,6 +55,7 @@ files:
 - lib/build/files/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/ioquatix/build-files
 licenses:
 - MIT
@@ -68,14 +69,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Abstractions for handling and mapping paths.
 test_files: []