console 1.29.2 → 1.36.0

data/lib/console/config.rb

@@ -0,0 +1,96 @@
+# 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).freeze
+		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.
+		#
+		# @parameter env [Hash] The environment to read the log level from.
+		# @returns [Integer | Symbol] The default log level.
+		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,44 @@
 # 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 to_hash
+				{}
+			end
+			
+			# 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

data/lib/console/filter.rb

@@ -1,26 +1,37 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2019, by Bryan Powell.
 # Copyright, 2020, by Michael Adams.
 # Copyright, 2021, by Robert Schulze.
+# Copyright, 2026, by Copilot.
 
 module Console
 	UNKNOWN = :unknown
 	
+	# A log filter which can be used to filter log messages based on severity, subject, and other criteria.
 	class Filter
-		if Object.const_defined?(:Ractor) and RUBY_VERSION >= "3.1"
+		if Object.const_defined?(:Ractor) and RUBY_VERSION >= "3.4"
+			# Define a method which can be shared between ractors.
 			def self.define_immutable_method(name, &block)
 				block = Ractor.make_shareable(block)
 				self.define_method(name, &block)
 			end
 		else
+			# Define a method.
 			def self.define_immutable_method(name, &block)
 				define_method(name, &block)
 			end
 		end
 		
+		# Create a new log filter with specific log levels.
+		#
+		# ```ruby
+		# class MyLogger < Console::Filter[debug: 0, okay: 1, bad: 2, terrible: 3]
+		# ```
+		#
+		# @parameter levels [Hash(Symbol, Integer)] A hash of log levels.
 		def self.[] **levels
 			klass = Class.new(self)
 			minimum_level, maximum_level = levels.values.minmax
@@ -30,6 +41,10 @@ module Console
 				const_set(:MINIMUM_LEVEL, minimum_level)
 				const_set(:MAXIMUM_LEVEL, maximum_level)
 				
+				# The default log level for instances of this filter class.
+				# Set to MINIMUM_LEVEL to allow all messages by default.
+				const_set(:DEFAULT_LEVEL, minimum_level)
+				
 				levels.each do |name, level|
 					const_set(name.to_s.upcase, level)
 					
@@ -54,16 +69,34 @@ module Console
 			return klass
 		end
 		
-		def initialize(output, verbose: true, level: self.class::DEFAULT_LEVEL, **options)
+		# Create a new log filter.
+		#
+		# @parameter output [Console::Output] The output destination.
+		# @parameter verbose [Boolean] Enable verbose output.
+		# @parameter level [Integer] The log level.
+		# @parameter options [Hash] Additional options.
+		def initialize(output, verbose: true, level: nil, **options)
 			@output = output
 			@verbose = verbose
-			@level = level
+			
+			# Set the log level using the behaviour implemented in `level=`:
+			if level
+				self.level = level
+			else
+				@level = self.class::DEFAULT_LEVEL
+			end
 			
 			@subjects = {}
 			
 			@options = options
 		end
 		
+		# Create a new log filter with the given options, from an existing log filter.
+		#
+		# @parameter level [Integer] The log level.
+		# @parameter verbose [Boolean] Enable verbose output.
+		# @parameter options [Hash] Additional options.
+		# @returns [Console::Filter] The new log filter.
 		def with(level: @level, verbose: @verbose, **options)
 			dup.tap do |logger|
 				logger.level = level
@@ -72,14 +105,24 @@ module Console
 			end
 		end
 		
+		# @attribute [Console::Output] The output destination.
 		attr_accessor :output
+		
+		# @attribute [Boolean] Whether to enable verbose output.
 		attr :verbose
+		
+		# @attribute [Integer] The current log level.
 		attr :level
 		
+		# @attribute [Hash(Module, Integer)] The log levels for specific subject (classes).
 		attr :subjects
 		
+		# @attribute [Hash] Additional options.
 		attr_accessor :options
 		
+		# Set the log level.
+		#
+		# @parameter level [Integer | Symbol] The log level.
 		def level= level
 			if level.is_a? Symbol
 				@level = self.class::LEVELS[level]
@@ -88,19 +131,30 @@ module Console
 			end
 		end
 		
+		# Set verbose output (enable by default with no arguments).
+		#
+		# @parameter value [Boolean] Enable or disable verbose output.
 		def verbose!(value = true)
 			@verbose = value
 			@output.verbose!(value)
 		end
 		
+		# Disable all logging.
 		def off!
 			@level = self.class::MAXIMUM_LEVEL + 1
 		end
 		
+		# Enable all logging.
 		def all!
 			@level = self.class::MINIMUM_LEVEL - 1
 		end
 		
+		# Filter log messages based on the subject and log level.
+		#
+		# You must provide the subject's class, not an instance of the class.
+		#
+		# @parameter subject [Module] The subject to filter.
+		# @parameter level [Integer] The log level.
 		def filter(subject, level)
 			unless subject.is_a?(Module)
 				raise ArgumentError, "Expected a class, got #{subject.inspect}"
@@ -109,8 +163,13 @@ module Console
 			@subjects[subject] = level
 		end
 		
+		# Whether logging is enabled for the given subject and log level.
+		#
 		# You can enable and disable logging for classes. This function checks if logging for a given subject is enabled.
-		# @param subject [Object] the subject to check.
+		#
+		# @parameter subject [Module | Object] The subject to check.
+		# @parameter level [Integer] The log level.
+		# @returns [Boolean] Whether logging is enabled.
 		def enabled?(subject, level = self.class::MINIMUM_LEVEL)
 			subject = subject.class unless subject.is_a?(Module)
 			
@@ -124,19 +183,24 @@ module Console
 		end
 		
 		# Enable specific log level for the given class.
+		#
 		# @parameter name [Module] The class to enable.
 		def enable(subject, level = self.class::MINIMUM_LEVEL)
 			# Set the filter level of logging for a given subject which passes all log messages:
 			filter(subject, level)
 		end
 		
+		# Disable logging for the given class.
+		#
+		# @parameter name [Module] The class to disable.
 		def disable(subject)
 			# Set the filter level of the logging for a given subject which filters all log messages:
 			filter(subject, self.class::MAXIMUM_LEVEL + 1)
 		end
 		
 		# Clear any specific filters for the given class.
-		# @parameter name [Module] The class to disable.
+		#
+		# @parameter subject [Module] The class to disable.
 		def clear(subject)
 			unless subject.is_a?(Module)
 				raise ArgumentError, "Expected a class, got #{subject.inspect}"
@@ -145,11 +209,23 @@ module Console
 			@subjects.delete(subject)
 		end
 		
+		# Log a message with the given severity.
+		#
+		# If the severity is not defined in this filter's LEVELS (e.g., when chaining
+		# filters with different severity levels), the message is passed through to the
+		# output without filtering. This allows custom filters to be composed together.
+		#
+		# @parameter subject [Object] The subject of the log message.
+		# @parameter arguments [Array] The arguments to log.
+		# @parameter options [Hash] Additional options to pass to the output.
+		# @parameter block [Proc] A block passed to the output.
+		# @returns [Nil] Always returns nil.
 		def call(subject, *arguments, **options, &block)
 			severity = options[:severity] || UNKNOWN
 			level = self.class::LEVELS[severity]
 			
-			if self.enabled?(subject, level)
+			# If the severity is unknown (level is nil), pass through to output without filtering:
+			if level.nil? || self.enabled?(subject, level)
 				@output.call(subject, *arguments, **options, &block)
 			end