console 1.29.3 → 1.30.0

data/lib/console/format/safe.rb

@@ -6,16 +6,27 @@
 require "json"
 
 module Console
+	# @namespace
 	module Format
-		# This class is used to safely dump objects.
-		# It will attempt to dump the object using the given format, but if it fails, it will generate a safe version of the object.
+		# A safe format for converting objects to strings.
+		# 
+		# Handles issues like circular references and encoding errors.
 		class Safe
+			# Create a new safe format.
+			#
+			# @parameter format [JSON] The format to use for serialization.
+			# @parameter limit [Integer] The maximum depth to recurse into objects.
+			# @parameter encoding [Encoding] The encoding to use for strings.
 			def initialize(format: ::JSON, limit: 8, encoding: ::Encoding::UTF_8)
 				@format = format
 				@limit = limit
 				@encoding = encoding
 			end
 			
+			# Dump the given object to a string.
+			#
+			# @parameter object [Object] The object to dump.
+			# @returns [String] The dumped object.
 			def dump(object)
 				@format.dump(object, @limit)
 			rescue SystemStackError, StandardError => error
@@ -24,6 +35,10 @@ module Console
 			
 			private
 			
+			# Filter the backtrace to remove duplicate frames and reduce verbosity.
+			#
+			# @parameter error [Exception] The exception to filter.
+			# @returns [Array(String)] The filtered backtrace.
 			def filter_backtrace(error)
 				frames = error.backtrace
 				filtered = {}
@@ -61,6 +76,13 @@ module Console
 				return frames
 			end
 			
+			# Dump the given object to a string, replacing it with a safe representation if there is an error.
+			#
+			# This is a slow path so we try to avoid it.
+			#
+			# @parameter object [Object] The object to dump.
+			# @parameter error [Exception] The error that occurred while dumping the object.
+			# @returns [Hash] The dumped (truncated) object including error details.
 			def safe_dump(object, error)
 				object = safe_dump_recurse(object)
 				
@@ -74,6 +96,10 @@ module Console
 				return object
 			end
 			
+			# Replace the given object with a safe truncated representation.
+			#
+			# @parameter object [Object] The object to replace.
+			# @returns [String] The replacement string.
 			def replacement_for(object)
 				case object
 				when Array
@@ -85,15 +111,17 @@ module Console
 				end
 			end
 			
+			# Create a new hash with identity comparison.
 			def default_objects
 				Hash.new.compare_by_identity
 			end
 			
-			# This will recursively generate a safe version of the object.
-			# Nested hashes and arrays will be transformed recursively.
-			# Strings will be encoded with the given encoding.
-			# Primitive values will be returned as-is.
-			# Other values will be converted using `as_json` if available, otherwise `to_s`.
+			# This will recursively generate a safe version of the object. Nested hashes and arrays will be transformed recursively. Strings will be encoded with the given encoding. Primitive values will be returned as-is. Other values will be converted using `as_json` if available, otherwise `to_s`.
+			#
+			# @parameter object [Object] The object to dump.
+			# @parameter limit [Integer] The maximum depth to recurse into objects.
+			# @parameter objects [Hash] The objects that have already been visited.
+			# @returns [Object] The dumped object as a primitive representation.
 			def safe_dump_recurse(object, limit = @limit, objects = default_objects)
 				if limit <= 0 || objects[object]
 					return replacement_for(object)

data/lib/console/format.rb

@@ -7,6 +7,9 @@ require_relative "format/safe"
 
 module Console
 	module Format
+		# A safe format for converting objects to strings.
+		#
+		# @returns [Console::Format::Safe]
 		def self.default
 			Safe.new(format: ::JSON)
 		end

data/lib/console/interface.rb

@@ -3,51 +3,59 @@
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
 
-require_relative "logger"
+require "fiber/local"
+require_relative "config"
 
 module Console
 	# The public logger interface.
 	module Interface
+		extend Fiber::Local
+		
+		# Create a new (thread local) logger instance.
+		def self.local
+			Config::DEFAULT.make_logger
+		end
+		
 		# Get the current logger instance.
 		def logger
-			Logger.instance
+			Interface.instance
 		end
 		
 		# Set the current logger instance.
 		#
 		# The current logger instance is assigned per-fiber.
 		def logger= instance
-			Logger.instance= instance
+			Interface.instance= instance
 		end
 		
 		# Emit a debug log message.
 		def debug(...)
-			Logger.instance.debug(...)
+			Interface.instance.debug(...)
 		end
 		
 		# Emit an informational log message.
 		def info(...)
-			Logger.instance.info(...)
+			Interface.instance.info(...)
 		end
 		
 		# Emit a warning log message.
 		def warn(...)
-			Logger.instance.warn(...)
+			Interface.instance.warn(...)
 		end
 		
 		# Emit an error log message.
 		def error(...)
-			Logger.instance.error(...)
+			Interface.instance.error(...)
 		end
 		
 		# Emit a fatal log message.
 		def fatal(...)
-			Logger.instance.fatal(...)
+			Interface.instance.fatal(...)
 		end
 		
 		# Emit a log message with arbitrary arguments and options.
 		def call(...)
-			Logger.instance.call(...)
+			Interface.instance.call(...)
 		end
 	end
 end

data/lib/console/logger.rb

@@ -8,61 +8,40 @@
 require_relative "output"
 require_relative "output/failure"
 
-require_relative "filter"
-require_relative "event"
-require_relative "resolver"
 require_relative "progress"
-
-require "fiber/local"
+require_relative "config"
 
 module Console
+	# The standard logger interface with support for log levels and verbosity.
+	#
+	# The log levels are: `debug`, `info`, `warn`, `error`, and `fatal`.
 	class Logger < Filter[debug: 0, info: 1, warn: 2, error: 3, fatal: 4]
-		extend Fiber::Local
-		
 		# 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 self.default_log_level(env = ENV)
+		#
+		# @parameter env [Hash] The environment to read the log level from.
+		# @parameter verbose [Boolean] The verbose flag.
+		# @parameter debug [Boolean] The debug flag.
+		# @returns [Integer] The default log level.
+		def self.default_log_level(env = ENV, verbose: $VERBOSE, debug: $DEBUG)
 			if level = env["CONSOLE_LEVEL"]
 				LEVELS[level.to_sym] || level.to_i
-			elsif $DEBUG
+			elsif debug
 				DEBUG
-			elsif $VERBOSE.nil?
+			elsif verbose.nil?
 				WARN
 			else
 				INFO
 			end
 		end
 		
-		# Controls verbose output using `$VERBOSE`.
-		def self.verbose?(env = ENV)
-			!$VERBOSE.nil? || env["CONSOLE_VERBOSE"]
-		end
-		
-		def self.default_logger(output = $stderr, env = ENV, **options)
-			if options[:verbose].nil?
-				options[:verbose] = self.verbose?(env)
-			end
-			
-			if options[:level].nil?
-				options[:level] = self.default_log_level(env)
-			end
-			
-			output = Output.new(output, env, **options)
-			
-			logger = self.new(output, **options)
-			
-			Resolver.default_resolver(logger)
-			
-			return logger
-		end
-		
-		def self.local
-			self.default_logger
-		end
-		
 		DEFAULT_LEVEL = 1
 		
+		# Create a new logger.
+		#
+		# @parameter output [Console::Output] The output destination.
+		# @parameter options [Hash] Additional options.
 		def initialize(output, **options)
 			# This is the expected default behaviour, but it may be nice to have a way to override it.
 			output = Output::Failure.new(output, **options)
@@ -70,6 +49,12 @@ module Console
 			super(output, **options)
 		end
 		
+		# Create a progress indicator for the given subject.
+		#
+		# @parameter subject [String] The subject of the progress indicator.
+		# @parameter total [Integer] The total number of items to process.
+		# @parameter options [Hash] Additional options passed to {Progress}.
+		# @returns [Progress] The progress indicator.
 		def progress(subject, total, **options)
 			options[:severity] ||= :info
 			

data/lib/console/output/default.rb

@@ -9,14 +9,20 @@ require_relative "failure"
 
 module Console
 	module Output
+		# Default output format selection.
 		module Default
-			def self.new(output, **options)
-				output ||= $stderr
+			# Create a new output format based on the given stream.
+			#
+			# @parameter io [IO] The output stream.
+			# @parameter options [Hash] Additional options to customize the output.
+			# @returns [Console::Output::Terminal | Console::Output::Serialized] The output instance, depending on whether the `io` is a terminal or not.
+			def self.new(stream, **options)
+				stream ||= $stderr
 				
-				if output.tty?
-					output = Terminal.new(output, **options)
+				if stream.tty?
+					output = Terminal.new(stream, **options)
 				else
-					output = Serialized.new(output, **options)
+					output = Serialized.new(stream, **options)
 				end
 				
 				return output

data/lib/console/output/failure.rb

@@ -10,11 +10,18 @@ module Console
 	module Output
 		# A wrapper for outputting failure messages, which can include exceptions.
 		class Failure < Wrapper
+			# Create a new failure output wrapper.
 			def initialize(output, **options)
 				super(output, **options)
 			end
 			
 			# The exception must be either the last argument or passed as an option.
+			#
+			# @parameter subject [String] The subject of the message.
+			# @parameter arguments [Array] The arguments to output.
+			# @parameter exception [Exception] The exception to output.
+			# @parameter options [Hash] Additional options to pass to the output.
+			# @parameter block [Proc] An optional block to pass to the output.
 			def call(subject = nil, *arguments, exception: nil, **options, &block)
 				if exception.nil?
 					last = arguments.last
@@ -28,7 +35,7 @@ module Console
 					options[:exception] = exception
 				end
 				
-				super(subject, *arguments, **options)
+				super(subject, *arguments, **options, &block)
 			end
 		end
 	end

data/lib/console/output/null.rb

@@ -5,16 +5,19 @@
 
 module Console
 	module Output
+		# A null output that does nothing.
 		class Null
+			# Create a new null output.
 			def initialize(...)
 			end
 			
+			# The last output is always self.
 			def last_output
 				self
 			end
 			
+			# Do nothing.
 			def call(...)
-				# Do nothing.
 			end
 		end
 	end

data/lib/console/output/sensitive.rb

@@ -7,7 +7,9 @@ require_relative "wrapper"
 
 module Console
 	module Output
+		# Redact sensitive information from output.
 		class Sensitive < Wrapper
+			# Default redaction pattern.
 			REDACT = /
 				phone
 				| email
@@ -34,28 +36,52 @@ module Console
 				| password
 			/xi
 			
+			# Create a new sensitive output wrapper.
+			#
+			# @parameter output [Console::Output] The output to wrap.
+			# @parameter redact [Regexp] The pattern to redact.
+			# @parameter options [Hash] Additional options to pass to the output.
 			def initialize(output, redact: REDACT, **options)
 				super(output, **options)
 				
 				@redact = redact
 			end
 			
+			# Check if the given text should be redacted.
+			#
+			# @parameter text [String] The text to check.
+			# @returns [Boolean] Whether the text should be redacted.
 			def redact?(text)
 				text.match?(@redact)
 			end
 			
+			# Redact sensitive information from a hash.
+			#
+			# @parameter arguments [Hash] The hash to redact.
+			# @parameter filter [Proc] An optional filter to apply to redacted text.
+			# @returns [Hash] The redacted hash.
 			def redact_hash(arguments, filter)
 				arguments.transform_values do |value|
 					redact(value, filter)
 				end
 			end
 			
+			# Redact sensitive information from an array.
+			#
+			# @parameter array [Array] The array to redact.
+			# @parameter filter [Proc] An optional filter to apply to redacted text.
+			# @returns [Array] The redacted array.
 			def redact_array(array, filter)
 				array.map do |value|
 					redact(value, filter)
 				end
 			end
 			
+			# Redact sensitive information from the given argument.
+			#
+			# @parameter argument [String | Array | Hash] The argument to redact.
+			# @parameter filter [Proc] An optional filter to apply to redacted text.
+			# @returns [String | Array | Hash] The redacted argument.
 			def redact(argument, filter)
 				case argument
 				when String
@@ -75,17 +101,32 @@ module Console
 				end
 			end
 			
+			# A simple filter for redacting sensitive information.
 			class Filter
+				# Create a new filter.
+				#
+				# @parameter substitutions [Hash] The substitutions to apply.
 				def initialize(substitutions)
 					@substitutions = substitutions
 					@pattern = Regexp.union(substitutions.keys)
 				end
 				
+				# Apply the filter to the given text. This will replace all occurrences of the pattern with the corresponding substitution.
+				#
+				# @parameter text [String] The text to filter.
+				# @returns [String] The filtered text.
 				def call(text)
 					text.gsub(@pattern, @substitutions)
 				end
 			end
 			
+			# Write a message to the output, filtering sensitive information if necessary.
+			#
+			# @parameter subject [String] The subject of the message.
+			# @parameter arguments [Array] The arguments to output.
+			# @parameter sensitive [Boolean | Filter | Hash] Whether to filter sensitive information.
+			# @parameter options [Hash] Additional options to pass to the output.
+			# @parameter block [Proc] An optional block to pass to the output.
 			def call(subject = nil, *arguments, sensitive: true, **options, &block)
 				if sensitive
 					if sensitive.respond_to?(:call)

data/lib/console/output/serialized.rb

@@ -9,9 +9,15 @@ require "fiber/annotation"
 
 module Console
 	module Output
+		# Serialize log messages in a structured format.
 		class Serialized
-			def initialize(io, format: Format.default, **options)
-				@io = io
+			# Create a new serialized output.
+			#
+			# @parameter io [IO] The output stream.
+			# @parameter format [Console::Format] The format to use for serializing log messages.
+			# @parameter options [Hash] Additional options to customize the output.
+			def initialize(stream, format: Format.default, **options)
+				@stream = stream
 				@format = format
 			end
 			
@@ -20,13 +26,27 @@ module Console
 				self
 			end
 			
-			attr :io
+			# @attribute [IO] The output stream.
+			attr :stream
+			
+			# @attribute [Console::Format] The format to use for serializing log messages.
 			attr :format
 			
+			# Serialize the given record.
+			#
+			# @parameter record [Hash] The record to serialize.
+			# @returns [String] The serialized record.
 			def dump(record)
 				@format.dump(record)
 			end
 			
+			# Output the given log message.
+			#
+			# @parameter subject [String] The subject of the log message.
+			# @parameter arguments [Array] The arguments to log.
+			# @parameter severity [Symbol] The severity of the log message.
+			# @parameter options [Hash] Additional options.
+			# @parameter block [Proc] An optional block used to generate the log message.
 			def call(subject = nil, *arguments, severity: UNKNOWN, **options, &block)
 				record = {
 					time: Time.now.iso8601,
@@ -68,10 +88,11 @@ module Console
 				
 				record.update(options)
 				
-				@io.write(self.dump(record) << "\n")
+				@stream.write(self.dump(record) << "\n")
 			end
 		end
 		
+		# @deprecated This is a legacy constant, please use `Serialized` instead.
 		JSON = Serialized
 	end
 end

data/lib/console/output/split.rb

@@ -5,19 +5,30 @@
 
 module Console
 	module Output
+		# Split output into multiple outputs.
 		class Split
+			# Create a new split output.
+			#
+			# @parameter outputs [Array(Console::Output)] The outputs to split into.
 			def self.[](*outputs)
 				self.new(outputs)
 			end
 			
+			# Create a new split output.
+			#
+			# @parameter outputs [Array(Console::Output)] The outputs to split into.
 			def initialize(outputs)
 				@outputs = outputs
 			end
 			
+			# Set the verbose flag for all outputs.
+			#
+			# @parameter value [Boolean] The new value.
 			def verbose!(value = true)
 				@outputs.each{|output| output.verbose!(value)}
 			end
 			
+			# Invoke the outputs. If a block is used, it may be invoked multiple times.
 			def call(...)
 				@outputs.each do |output|
 					output.call(...)

data/lib/console/output/terminal.rb

@@ -14,48 +14,65 @@ require "stringio"
 
 module Console
 	module Output
+		# Represents a terminal output, and formats log messages for display.
 		class Terminal
+			# Represents an output buffer that formats lines with a prefix.
 			class Buffer < StringIO
+				# Create a new buffer with the given prefix.
+				#
+				# @parameter prefix [String] The prefix to use for each line.
 				def initialize(prefix = nil)
 					@prefix = prefix
 					
 					super()
 				end
 				
+				# @attribute [String] The prefix to use for each line.
 				attr :prefix
 				
-				def puts(*args, prefix: @prefix)
-					args.each do |arg|
+				# Write lines using the given prefix.
+				#
+				# @parameter lines [Array] The lines to write.
+				# @parameter prefix [String] The prefix to use for each line.
+				def puts(*lines, prefix: @prefix)
+					lines.each do |line|
 						self.write(prefix) if prefix
-						super(arg)
+						super(line)
 					end
 				end
 				
 				alias << puts
 			end
 			
-			# This, and all related methods, is considered private.
+			# The environment variable used to store the start time of the console terminal output.
 			CONSOLE_START_AT = "CONSOLE_START_AT"
 			
-			# Exports CONSOLE_START which can be used to synchronize the start times of all child processes when they log using delta time.
-			def self.start_at!(environment = ENV)
-				if time_string = environment[CONSOLE_START_AT]
+			# Exports CONSOLE_START_AT which can be used to synchronize the start times of all child processes when they log using delta time.
+			def self.start_at!(env = ENV)
+				if time_string = env[CONSOLE_START_AT]
 					start_at = Time.parse(time_string) rescue nil
 				end
 				
 				unless start_at
 					start_at = Time.now
-					environment[CONSOLE_START_AT] = start_at.to_s
+					env[CONSOLE_START_AT] = start_at.to_s
 				end
 				
 				return start_at
 			end
 			
-			def initialize(output, verbose: nil, start_at: Terminal.start_at!, format: nil, **options)
-				@io = output
+			# Create a new terminal output.
+			#
+			# @parameter stream [IO] The output stream.
+			# @parameter verbose [Boolean] Whether to print verbose output.
+			# @parameter start_at [Time] The start time of the terminal output.
+			# @parameter format [Console::Terminal::Format] The format to use for terminal output.
+			# @parameter options [Hash] Additional options to customize the output.
+			def initialize(stream, verbose: nil, start_at: Terminal.start_at!, format: nil, **options)
+				@stream = stream
 				@start_at = start_at
 				
-				@terminal = format.nil? ? Console::Terminal.for(@io) : format.new(@io)
+				@terminal = format.nil? ? Console::Terminal.for(@stream) : format.new(@stream)
 				
 				if verbose.nil?
 					@verbose = !@terminal.colors?
@@ -78,22 +95,31 @@ module Console
 				self.register_formatters
 			end
 			
-			# This a final output that then writes to an IO object.
+			# This a final output.
 			def last_output
 				self
 			end
 			
-			attr :io
+			# @attribute [IO] The output stream.
+			attr :stream
 			
+			# @attribute [Boolean] Whether to print verbose output.
 			attr_accessor :verbose
 			
+			# @attribute [Time] The start time of the terminal output.
 			attr :start
+			
+			# @attribute [Console::Terminal::Format] The format to use for terminal output.
 			attr :terminal
 			
+			# Set the verbose output.
+			#
+			# @parameter value [Boolean] Whether to print verbose output.
 			def verbose!(value = true)
 				@verbose = value
 			end
 			
+			# Register all formatters in the given namespace.
 			def register_formatters(namespace = Console::Terminal::Formatter)
 				namespace.constants.each do |name|
 					formatter = namespace.const_get(name)
@@ -101,8 +127,20 @@ module Console
 				end
 			end
 			
+			# The default severity for log messages, if not specified.
 			UNKNOWN = :unknown
 			
+			# Log a message with the given severity.
+			#
+			# @parameter subject [String] The subject of the log message.
+			# @parameter arguments [Array] The arguments to log.
+			# @parameter name [String | Nil] The optional name of the log message, used as a prefix, otherwise defaults to the severity name.
+			# @parameter severity [Symbol] The severity of the log message.
+			# @parameter event [Hash] The event to log.
+			# @parameter options [Hash] Additional options.
+			# @yields {|buffer, terminal| ...} An optional block used to generate the log message.
+			# 	@parameter buffer [Console::Output::Terminal::Buffer] The output buffer.
+			# 	@parameter terminal [Console::Terminal] The terminal instance.
 			def call(subject = nil, *arguments, name: nil, severity: UNKNOWN, event: nil, **options, &block)
 				width = @terminal.width
 				
@@ -134,7 +172,7 @@ module Console
 					format_options(options, buffer)
 				end
 				
-				@io.write buffer.string
+				@stream.write buffer.string
 			end
 			
 			protected
@@ -242,13 +280,27 @@ module Console
 			end
 		end
 		
+		# Terminal text output.
 		module Text
+			# Create a new terminal output.
+			#
+			# @parameter output [IO] The output stream.
+			# @parameter options [Hash] Additional options to customize the output.
+			# @returns [Console::Output::Terminal] The terminal output instance.
 			def self.new(output, **options)
 				Terminal.new(output, format: Console::Terminal::Text, **options)
 			end
 		end
 		
+		# Terminal XTerm output.
 		module XTerm
+			# Create a new terminal output.
+			#
+			# You can use this to force XTerm output on a non-TTY output streams that support XTerm escape codes.
+			#
+			# @parameter output [IO] The output stream.
+			# @parameter options [Hash] Additional options to customize the output.
+			# @returns [Console::Output::Terminal] The terminal output instance.
 			def self.new(output, **options)
 				Terminal.new(output, format: Console::Terminal::XTerm, **options)
 			end