console 1.29.2 → 1.36.0

data/lib/console/output/sensitive.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 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

@@ -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.
 
 require_relative "../format"
 require "time"
@@ -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,21 +26,38 @@ 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,
 					severity: severity,
-					oid: subject.object_id,
-					pid: Process.pid,
+					process_id: Process.pid,
+					fiber_id: Fiber.current.object_id,
 				}
 				
+				# For backwards compatibility:
+				record[:pid] = record[:process_id]
+				
 				# We want to log just a brief subject:
 				if subject.is_a?(String)
 					record[:subject] = subject
@@ -42,6 +65,7 @@ module Console
 					record[:subject] = subject.name
 				else
 					record[:subject] = subject.class.name
+					record[:object_id] = subject.object_id
 				end
 				
 				if annotation = Fiber.current.annotation
@@ -68,10 +92,11 @@ module Console
 				
 				record.update(options)
 				
-				@io.puts(self.dump(record))
+				@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

@@ -1,23 +1,34 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 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

@@ -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.
 
 require_relative "../clock"
@@ -14,48 +14,66 @@ 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
 				
+				# Write a line to the buffer.
 				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 +96,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 +128,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 +173,7 @@ module Console
 					format_options(options, buffer)
 				end
 				
-				@io.write buffer.string
+				@stream.write buffer.string
 			end
 			
 			protected
@@ -242,13 +281,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

data/lib/console/output/wrapper.rb

@@ -1,25 +1,36 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 module Console
 	module Output
+		# A generic wrapper for output handling.
 		class Wrapper
+			# Create a new wrapper output.
+			#
+			# @parameter delegate [Console::Output] The output to delegate to.
+			# @parameter options [Hash] Additional options to customize the output.
 			def initialize(delegate, **options)
 				@delegate = delegate
 			end
 			
+			# @attribute [Console::Output] The output to delegate to.
 			attr :delegate
 			
+			# The last output is the last output of the delegate.
 			def last_output
 				@delegate.last_output
 			end
 			
+			# Set the verbose flag for the delegate.
+			#
+			# @parameter value [Boolean] The new value.
 			def verbose!(value = true)
 				@delegate.verbose!(value)
 			end
 			
+			# Invoke the delegate.
 			def call(...)
 				@delegate.call(...)
 			end

data/lib/console/output.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "output/default"
 require_relative "output/serialized"
@@ -9,16 +9,27 @@ require_relative "output/terminal"
 require_relative "output/null"
 
 module Console
+	# Output handling.
 	module Output
+		# Create a new output based on the environment.
+		#
+		# The environment variable `CONSOLE_OUTPUT` can be used to specify a list of output classes to wrap around the output. If not specified the {Default} output is used.
+		#
+		# The output argument is deliberately unders-specified but can be an IO object or an instance of {Output}.
+		#
+		# @parameter output [Console::Output] The output to wrap OR an IO object.
+		# @parameter env [Hash] The environment to read configuration from.
+		# @parameter options [Hash] Additional options to customize the output.
+		# @returns [Console::Output] The output instance.
 		def self.new(output = nil, env = ENV, **options)
 			if names = env["CONSOLE_OUTPUT"]
 				names = names.split(",").reverse
 				
 				names.inject(output) do |output, name|
-					Output.const_get(name).new(output, **options)
+					Output.const_get(name).new(output, env: env, **options)
 				end
 			else
-				return Output::Default.new(output, **options)
+				return Output::Default.new(output, env: env, **options)
 			end
 		end
 	end

data/lib/console/progress.rb

@@ -1,22 +1,30 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2022, by Anton Sozontov.
 
 require_relative "clock"
 
 module Console
+	# A simple progress indicator
 	class Progress
+		# @deprecated Use {Clock.now} instead.
 		def self.now
-			Process.clock_gettime(Process::CLOCK_MONOTONIC)
+			Clock.now
 		end
 		
+		# Create a new progress indicator.
+		#
+		# @parameter subject [Object] The subject of the progress indicator.
+		# @parameter total [Integer] The total number of steps.
+		# @parameter minimum_output_duration [Numeric] The minimum duration between outputs.
+		# @parameter options [Hash] Additional options to customize the output.
 		def initialize(subject, total = 0, minimum_output_duration: 0.1, **options)
 			@subject = subject
 			@options = options
 			
-			@start_time = Progress.now
+			@start_time = Clock.now
 			
 			@last_output_time = nil
 			@minimum_output_duration = minimum_output_duration
@@ -25,34 +33,53 @@ module Console
 			@total = total
 		end
 		
+		# @attribute [Object] The subject of the progress indicator.
 		attr :subject
+		
+		# @attribute [Numeric] The minimum duration between outputs.
+		attr :minimum_output_duration
+		
+		# @attribute [Time] The time the progress indicator was started.
+		attr :start_time
+		
+		# @attribute [Numeric] The current number of steps completed.
 		attr :current
+		
+		# @attribute [Numeric] The total number of steps.
 		attr :total
 		
+		# @returns [Numeric] The duration since the progress indicator was started.
 		def duration
-			Progress.now - @start_time
+			Clock.now - @start_time
 		end
 		
+		# @returns [Rational] The ratio of steps completed to total steps.
 		def ratio
 			Rational(@current.to_f, @total.to_f)
 		end
 		
+		# @returns [Numeric] The number of steps remaining.
 		def remaining
 			@total - @current
 		end
 		
+		# @returns [Numeric | Nil] The average duration per step, or `nil` if no steps have been completed.
 		def average_duration
 			if @current > 0
 				duration / @current
 			end
 		end
 		
+		# @returns [Numeric | Nil] The estimated remaining time, or `nil` if no steps have been completed.
 		def estimated_remaining_time
 			if average_duration = self.average_duration
 				average_duration * remaining
 			end
 		end
 		
+		# Generate an appropriate event for the progress indicator.
+		#
+		# @returns [Hash] The progress indicator as a hash.
 		def to_hash
 			Hash.new.tap do |hash|
 				hash[:type] = :progress
@@ -64,30 +91,44 @@ module Console
 			end
 		end
 		
+		# Increment the progress indicator by the given amount.
+		#
+		# @parameter amount [Numeric] The amount to increment by.
+		# @returns [Progress] The progress indicator itself.
 		def increment(amount = 1)
 			@current += amount
 			
 			if output?
 				Console.call(@subject, self.to_s, event: self.to_hash, **@options)
-				@last_output_time = Progress.now
+				@last_output_time = Clock.now
 			end
 			
 			return self
 		end
 		
+		# Resize the progress indicator to the given total.
+		#
+		# @parameter total [Numeric] The new total number of steps.
+		# @returns [Progress] The progress indicator itself.
 		def resize(total)
 			@total = total
 			
 			Console.call(@subject, self.to_s, event: self.to_hash, **@options)
-			@last_output_time = Progress.now
+			@last_output_time = Clock.now
 			
 			return self
 		end
 		
-		def mark(*arguments, **options)
-			Console.call(@subject, *arguments, **options, **@options)
+		# Augment the progress indicator with additional information.
+		#
+		# @parameter *arguments [Array] The arguments to log.
+		# @parameter **options [Hash] Additional options to log.
+		# @parameter &block [Proc] An optional block used to generate the log message.
+		def mark(*arguments, **options, &block)
+			Console.call(@subject, *arguments, **options, **@options, &block)
 		end
 		
+		# @returns [String] A human-readable representation of the progress indicator.
 		def to_s
 			if estimated_remaining_time = self.estimated_remaining_time
 				"#{@current}/#{@total} completed in #{Clock.formatted_duration(self.duration)}, #{Clock.formatted_duration(estimated_remaining_time)} remaining."
@@ -98,12 +139,18 @@ module Console
 		
 		private
 		
+		# Compute a time delta since the last output, used for rate limiting the output.
+		#
+		# @returns [Numeric | Nil] The duration since the last output.
 		def duration_since_last_output
 			if @last_output_time
-				Progress.now - @last_output_time
+				Clock.now - @last_output_time
 			end
 		end
 		
+		# Whether an output should be generated at this time, taking into account the remaining steps, and the duration since the last output.
+		#
+		# @returns [Boolean] Whether an output should be generated.
 		def output?
 			if remaining.zero?
 				return true