console 1.29.3 → 1.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbf78f2f64af897759c501aafc1635862b9078ae7771cadb9cddff3ecd541d52
-  data.tar.gz: e0d24380b970833df8ff9fbafb020a1b6497c1af48cd7c9d74f7f01192579914
+  metadata.gz: 567d08376aa5cdd7b561679f5a5ff1d1fea42f69c0d3f78bc56f7e98fe712c35
+  data.tar.gz: 23131e3a9cf8812a62b07bca63189b83e127906ca7ed7eeaf6343bd6c2279fba
 SHA512:
-  metadata.gz: dc149294554146885788dff25cbf102b94e1907af62fad7f99c41c82602b46f2eba71a1aa1aa580e377c8615427c602931ce831c1fe2f9118670316d8b685213
-  data.tar.gz: 4ab2099a4714c5a9bcd3f6713d6974f7208c1712b81d406f2be5ee1fc1677f383d9453dc9c74005e5761ae0100bdf99bfd629168fbb0041ebd496d5dc634d47f
+  metadata.gz: 88aa81d06babd53bd475a01ea2c09949c5fb54a69d0cab8a8387fc1ce44d3567eab7ad99c9387ddf20c02ff0028b0adb685f17fffef48370099b0cc45548fc2f
+  data.tar.gz: 31af053996e9b306c0cf63e54181c84760ad72f8fb5562b51dc58caaae50c0c6d5189659e771df89ce2f94b252883cdf30b2ab95ee6ec8bcf7dba4d016a4c2f9

data/lib/console/capture.rb

@@ -7,13 +7,15 @@ 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

@@ -4,7 +4,12 @@
 # Copyright, 2021-2022, 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

@@ -6,30 +6,49 @@
 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

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

@@ -5,19 +5,33 @@
 
 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

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

@@ -5,3 +5,9 @@
 
 require_relative "event/spawn"
 require_relative "event/failure"
+
+module Console
+	# Structured event logging.
+	module Event
+	end
+end

data/lib/console/filter.rb

@@ -9,18 +9,28 @@
 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"
+			# 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
@@ -54,6 +64,12 @@ module Console
 			return klass
 		end
 		
+		# 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: self.class::DEFAULT_LEVEL, **options)
 			@output = output
 			@verbose = verbose
@@ -64,6 +80,12 @@ module Console
 			@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 +94,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 +120,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 +152,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] 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 +172,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,6 +198,13 @@ module Console
 			@subjects.delete(subject)
 		end
 		
+		# Log a message with the given severity.
+		#
+		# @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]