console 1.29.3 → 1.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbf78f2f64af897759c501aafc1635862b9078ae7771cadb9cddff3ecd541d52
-  data.tar.gz: e0d24380b970833df8ff9fbafb020a1b6497c1af48cd7c9d74f7f01192579914
+  metadata.gz: 862a9436f281d40440ce23108fcc28b837c6e78f6046cda2b1a47c5f04279cef
+  data.tar.gz: 83caac86a2643e4aa55c8112d641443e08da95bf958ab02ee6e93fb40df811e6
 SHA512:
-  metadata.gz: dc149294554146885788dff25cbf102b94e1907af62fad7f99c41c82602b46f2eba71a1aa1aa580e377c8615427c602931ce831c1fe2f9118670316d8b685213
-  data.tar.gz: 4ab2099a4714c5a9bcd3f6713d6974f7208c1712b81d406f2be5ee1fc1677f383d9453dc9c74005e5761ae0100bdf99bfd629168fbb0041ebd496d5dc634d47f
+  metadata.gz: 1365c1ee4da61ec465ab197eb6cf4c9d6915427b75784b992129b18314d0a6c0126b7959277e6550d4e63d38d0ccbe42d4460ec4bcb476ba9c46dae124105650
+  data.tar.gz: 426c66c1bf9d50cb22bb7faca214167ecbd4be64b1d7d19ef6d7cecbdb3c06dbe7a483275ac18b14b0d1cb656915741ac5fdfa1b6c44f305818bc638fd30d3db

data/lib/console/capture.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "filter"
 require_relative "output/failure"
 
 module Console
-	# A general sink which captures all events into a buffer.
+	# A buffer which captures all logged messages into a buffer.
 	class Capture
+		# Create a new log capture buffer.
 		def initialize
 			@records = []
 			@verbose = false
 		end
 		
+		# @attribute [Array(Hash)] All records captured by this buffer.
 		attr :records
 		
 		# @deprecated Use {#records} instead of {#buffer}.
@@ -21,44 +23,67 @@ module Console
 		
 		alias to_a records
 		
+		# @attribute [Boolean] If true, the buffer will capture verbose messages.
 		attr :verbose
 		
+		# Whether the buffer includes any records with the given subject or message pattern.
+		#
+		# @returns [Boolean] True if the buffer includes any records with the given pattern.
 		def include?(pattern)
 			@records.any? do |record|
 				record[:subject].to_s&.match?(pattern) or record[:message].to_s&.match?(pattern)
 			end
 		end
 		
+		# Iterate over all records in the buffer.
+		#
+		# @yields {|record| ...} each record in the buffer.
+		# 	@parameter record [Hash] The record itself.
 		def each(&block)
 			@records.each(&block)
 		end
 		
 		include Enumerable
 		
+		# @returns [Hash] The first record in the buffer.
 		def first
 			@records.first
 		end
 		
+		# @returns [Hash] The last record in the buffer.
 		def last
 			@records.last
 		end
 		
+		# Clear all records from the buffer.
 		def clear
 			@records.clear
 		end
 		
+		# @returns [Boolean] True if the buffer is empty.
 		def empty?
 			@records.empty?
 		end
 		
+		# Sets the verbose flag which controls whether verbose messages are captured.
 		def verbose!(value = true)
 			@verbose = value
 		end
 		
+		# @returns [Boolean] True if the buffer is capturing verbose messages.
 		def verbose?
 			@verbose
 		end
 		
+		# Record a log message in the buffer.
+		#
+		# @parameter subject [Object] The subject of the log message.
+		# @parameter arguments [Array] The arguments to the log message.
+		# @parameter severity [Symbol] The severity of the log message.
+		# @parameter event [Event] The event associated with the log message.
+		# @parameter options [Hash] Additional options to pass to the log message.
+		# @yields {|buffer| ...} A block which can be used to write additional information to the log message.
+		# 	@parameter buffer [IO] The (optional) buffer to write to.
 		def call(subject = nil, *arguments, severity: UNKNOWN, event: nil, **options, &block)
 			record = {
 				time: ::Time.now.iso8601,

data/lib/console/clock.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 module Console
+	# A simple clock utility for tracking and formatting time.
 	module Clock
+		# Format a duration in seconds as a human readable string.
+		#
+		# @parameter duration [Numeric] The duration in seconds.
+		# @returns [String] The formatted duration.
 		def self.formatted_duration(duration)
 			if duration < 60.0
 				return "#{duration.round(2)}s"
@@ -27,7 +32,7 @@ module Console
 			return "#{duration.floor}d"
 		end
 		
-		# Get the current elapsed monotonic time.
+		# @returns [Time] The current monotonic time.
 		def self.now
 			::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
 		end

data/lib/console/compatible/logger.rb

@@ -1,35 +1,54 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "logger"
 
 module Console
+	# @namespace
 	module Compatible
 		# A compatible interface for {::Logger} which can be used with {Console}.
 		class Logger < ::Logger
+			# A compatible log device which can be used with {Console}. Suitable for use with code which (incorrectly) assumes that the log device a public interface and has certain methods/behaviours.
 			class LogDevice
+				# Create a new log device.
+				#
+				# @parameter subject [String] The subject of the log messages.
+				# @parameter output [Console::Interface] The output interface.
 				def initialize(subject, output)
 					@subject = subject
 					@output = output
 				end
 				
+				# Write a message to the log device.
+				#
+				# @parameter message [String] The message to write.
 				def write(message)
 					@output.call(@subject, message)
 				end
 				
+				# Log a message with the given severity.
+				#
+				# @paraemter arguments [Array] The arguments to log.
+				# @parameter options [Hash] Additional options.
 				def call(*arguments, **options)
 					@output.call(*arguments, **options)
 				end
 				
+				# Reopen the log device. This is a no-op.
 				def reopen
 				end
 				
+				# Close the log device. This is a no-op.
 				def close
 				end
 			end
-
+			
+			# Create a new (compatible) logger.
+			#
+			# @parameter subject [String] The subject of the log messages.
+			# @parameter output [Console::Interface] The output interface.
 			def initialize(subject, output = Console)
 				super(nil)
 				
@@ -37,6 +56,12 @@ module Console
 				@logdev = LogDevice.new(subject, output)
 			end
 			
+			# Log a message with the given severity.
+			#
+			# @parameter severity [Integer] The severity of the message.
+			# @parameter message [String] The message to log.
+			# @parameter progname [String] The program name.
+			# @returns [Boolean] True if the message was logged.
 			def add(severity, message = nil, progname = nil)
 				severity ||= UNKNOWN
 				
@@ -65,6 +90,10 @@ module Console
 				return true
 			end
 			
+			# Format the severity.
+			#
+			# @parameter value [Integer] The severity value.
+			# @returns [Symbol] The formatted severity.
 			def format_severity(value)
 				super.downcase.to_sym
 			end

data/lib/console/config.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "filter"
+require_relative "event"
+require_relative "resolver"
+require_relative "output"
+require_relative "logger"
+
+module Console
+	# Represents a configuration for the traces library.
+	class Config
+		PATH = ENV.fetch("CONSOLE_CONFIG_PATH", "config/console.rb")
+		
+		# Load the configuration from the given path.
+		# @parameter path [String] The path to the configuration file.
+		# @returns [Config] The loaded configuration.
+		def self.load(path)
+			config = self.new
+			
+			if File.exist?(path)
+				config.instance_eval(File.read(path), path)
+			end
+			
+			return config
+		end
+		
+		# Load the default configuration.
+		# @returns [Config] The default configuration.
+		def self.default
+			@default ||= self.load(PATH)
+		end
+		
+		# Set the default log level based on `$DEBUG` and `$VERBOSE`.
+		# You can also specify CONSOLE_LEVEL=debug or CONSOLE_LEVEL=info in environment.
+		# https://mislav.net/2011/06/ruby-verbose-mode/ has more details about how it all fits together.
+		def log_level(env = ENV)
+			Logger.default_log_level(env)
+		end
+		
+		# Controls verbose output using `$VERBOSE`.
+		def verbose?(env = ENV)
+			!$VERBOSE.nil? || env["CONSOLE_VERBOSE"]
+		end
+		
+		# Create an output with the given output and options.
+		#
+		# @parameter output [IO] The output to write log messages to.
+		# @parameter env [Hash] The environment to read configuration from.
+		# @parameter options [Hash] Additional options to pass to the output.
+		# @returns [Output] The created output.
+		def make_output(io = nil, env = ENV, **options)
+			Output.new(io, env, **options)
+		end
+		
+		# Create a resolver with the given logger.
+		#
+		# @parameter logger [Logger] The logger to set the log levels on.
+		# @returns [Resolver | Nil] The created resolver.
+		def make_resolver(logger)
+			Resolver.default_resolver(logger)
+		end
+		
+		# Create a logger with the given output and options.
+		#
+		# @parameter output [IO] The output to write log messages to.
+		# @parameter env [Hash] The environment to read configuration from.
+		# @parameter options [Hash] Additional options to pass to the logger.
+		# @returns [Logger] The created logger.
+		def make_logger(io = $stderr, env = ENV, **options)
+			if options[:verbose].nil?
+				options[:verbose] = self.verbose?(env)
+			end
+			
+			if options[:level].nil?
+				options[:level] = self.log_level(env)
+			end
+			
+			output = self.make_output(io, env, **options)
+			
+			logger = Logger.new(output, **options)
+			
+			make_resolver(logger)
+			
+			return logger
+		end
+		
+		# Load the default configuration.
+		DEFAULT = self.default
+	end
+end

data/lib/console/event/failure.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2021, by Robert Schulze.
 # Copyright, 2024, by Patrik Wenger.
 
@@ -9,33 +9,58 @@ require_relative "generic"
 
 module Console
 	module Event
-		# Represents a failure event.
+		# Represents a failure of some kind, usually with an attached exception.
 		#
 		# ```ruby
-		# Console::Event::Failure.for(exception).emit(self)
+		# begin
+		# 	raise "Something went wrong!"
+		# rescue => exception
+		# 	Console::Event::Failure.log("Something went wrong!", exception)
+		# end
 		# ```
+		#
+		# Generally, you should use the {Console.error} method to log failures, as it will automatically create a failure event for you.
 		class Failure < Generic
+			# For the purpose of efficiently formatting backtraces, we need to know the root directory of the project.
+			#
+			# @returns [String | Nil] The root directory of the project, or nil if it could not be determined.
 			def self.default_root
 				Dir.getwd
 			rescue # e.g. Errno::EMFILE
 				nil
 			end
 			
+			# Create a new failure event for the given exception.
+			#
+			# @parameter exception [Exception] The exception to log.
 			def self.for(exception)
 				self.new(exception, self.default_root)
 			end
 			
+			# Log a failure event with the given exception.
+			#
+			# @parameter subject [String] The subject of the log message.
+			# @parameter exception [Exception] The exception to log.
+			# @parameter options [Hash] Additional options pass to the logger output.
 			def self.log(subject, exception, **options)
 				Console.error(subject, **self.for(exception).to_hash, **options)
 			end
 			
+			# @attribute [Exception] The exception which caused the failure.
 			attr_reader :exception
 			
-			def initialize(exception, root = Dir.getwd)
+			# Create a new failure event for the given exception.
+			#
+			# @parameter exception [Exception] The exception to log.
+			# @parameter root [String] The root directory of the project.
+			def initialize(exception, root = self.class.default_root)
 				@exception = exception
 				@root = root
 			end
 			
+			# Convert the failure event to a hash.
+			#
+			# @returns [Hash] The hash representation of the failure event.
 			def to_hash
 				Hash.new.tap do |hash|
 					hash[:type] = :failure
@@ -44,6 +69,10 @@ module Console
 				end
 			end
 			
+			# Log the failure event.
+			#
+			# @parameter arguments [Array] The arguments to log.
+			# @parameter options [Hash] Additional options to pass to the logger output.
 			def emit(*arguments, **options)
 				options[:severity] ||= :error
 				

data/lib/console/event/generic.rb

@@ -1,23 +1,37 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Console
 	module Event
+		# A generic event which can be used to represent structured data.
 		class Generic
+			# Convert the event to a hash suitable for JSON serialization.
+			#
+			# @returns [Hash] The hash representation of the event.
 			def as_json(...)
 				to_hash
 			end
 			
+			# Serialize the event to JSON.
+			#
+			# @returns [String] The JSON representation of the event.
 			def to_json(...)
 				JSON.generate(as_json, ...)
 			end
 			
+			# Convert the event to a string (JSON).
+			#
+			# @returns [String] The string representation of the event.
 			def to_s
 				to_json
 			end
 			
+			# Log the event using the given output interface.
+			#
+			# @parameter arguments [Array] The arguments to log.
+			# @parameter options [Hash] Additional options to pass to the logger output.
 			def emit(*arguments, **options)
 				Console.call(*arguments, event: self, **options)
 			end

data/lib/console/event/spawn.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "generic"
 require_relative "../clock"
 
 module Console
 	module Event
-		# Represents a spawn event.
+		# Represents a child process spawn event.
 		#
 		# ```ruby
 		# Console.info(self, **Console::Event::Spawn.for("ls", "-l"))
@@ -17,6 +17,11 @@ module Console
 		# event.status = Process.wait
 		# ```
 		class Spawn < Generic
+			# Create a new spawn event.
+			#
+			# @parameter arguments [Array] The arguments to the command, similar to how you would pass them to `Kernel.system` or `Process.spawn`.
+			# @parameter options [Hash] The options to pass to the command, similar to how you would pass them to `Kernel.system` or `Process.spawn`.
+			# @returns [Spawn] The new spawn event representing the command.
 			def self.for(*arguments, **options)
 				# Extract out the command environment:
 				if arguments.first.is_a?(Hash)
@@ -27,6 +32,11 @@ module Console
 				end
 			end
 			
+			# Create a new spawn event.
+			#
+			# @parameter environment [Hash] The environment to use when running the command.
+			# @parameter arguments [Array] The arguments used for command execution.
+			# @parameter options [Hash] The options to pass to the command, similar to how you would pass them to `Kernel.system` or `Process.spawn`.
 			def initialize(environment, arguments, options)
 				@environment = environment
 				@arguments = arguments
@@ -38,12 +48,35 @@ module Console
 				@status = nil
 			end
 			
+			# @attribute [Numeric] The start time of the command.
+			attr :start_time
+			
+			# @attribute [Numeric] The end time of the command.
+			attr :end_time
+			
+			# @attribute [Process::Status] The status of the command, if it has completed.
+			attr :status
+			
+			# Set the status of the command, and record the end time.
+			#
+			# @parameter status [Process::Status] The status of the command.
+			def status=(status)
+				@end_time = Time.now
+				@status = status
+			end
+			
+			# Calculate the duration of the command, if it has completed.
+			#
+			# @returns [Numeric] The duration of the command.
 			def duration
 				if @end_time
 					@end_time - @start_time
 				end
 			end
 			
+			# Convert the spawn event to a hash suitable for JSON serialization.
+			#
+			# @returns [Hash] The hash representation of the spawn event.
 			def to_hash
 				Hash.new.tap do |hash|
 					hash[:type] = :spawn
@@ -59,15 +92,14 @@ module Console
 				end
 			end
 			
+			# Log the spawn event.
+			#
+			# @parameter arguments [Array] The arguments to log.
+			# @parameter options [Hash] Additional options to pass to the logger output.
 			def emit(*arguments, **options)
 				options[:severity] ||= :info
 				super
 			end
-			
-			def status=(status)
-				@end_time = Time.now
-				@status = status
-			end
 		end
 	end
 end

data/lib/console/event.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "event/spawn"
 require_relative "event/failure"
+
+module Console
+	# Structured event logging.
+	module Event
+	end
+end