console 1.29.2 → 1.36.0

data/lib/console/resolver.rb

@@ -1,12 +1,13 @@
 # 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 "filter"
 
 module Console
+	# Represents a class resolver that can be used to set log levels for different classes as they become available.
 	class Resolver
 		# You can change the log level for different classes using CONSOLE_$LEVEL env vars.
 		#
@@ -16,7 +17,6 @@ module Console
 		#
 		# @parameter logger [Logger] A logger instance to set the logging levels on.
 		# @parameter env [Hash] The environment to read levels from.
-		#
 		# @returns [Nil] If there were no custom logging levels specified in the environment.
 		# @returns [Resolver] If there were custom logging levels, then the created resolver is returned.
 		def self.default_resolver(logger, env = ENV)
@@ -59,12 +59,21 @@ module Console
 			return resolver
 		end
 		
+		# Create a new class resolver.
 		def initialize
 			@names = {}
 			
 			@trace_point = TracePoint.new(:class, &self.method(:resolve))
 		end
 		
+		# Bind the given class names to the given block. When the class name is resolved into an actual class, the block will be called with the class as an argument.
+		#
+		# If the class is already defined, the block will be called immediately.
+		#
+		# If the class is not defined, the block will be called when the class is defined, using a trace point.
+		#
+		# @parameter names [Array(String)] The class names to bind.
+		# @parameter block [Proc] The block to call when the class is resolved.
 		def bind(names, &block)
 			names.each do |name|
 				if klass = Object.const_get(name) rescue nil
@@ -81,10 +90,18 @@ module Console
 			end
 		end
 		
+		# @returns [Boolean] True if the resolver is waiting for classes to be defined.
 		def waiting?
 			@trace_point.enabled?
 		end
 		
+		# Invoked by the trace point when a class is defined.
+		#
+		# This will call the block associated with the class name, if any, and remove it from the list of names to resolve.
+		#
+		# If the list of names is empty, the trace point will be disabled.
+		#
+		# @parameter trace_point [TracePoint] The trace point that triggered the event.
 		def resolve(trace_point)
 			if block = @names.delete(trace_point.self.to_s)
 				block.call(trace_point.self)

data/lib/console/terminal/formatter/failure.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 module Console
 	module Terminal
 		module Formatter
+			# Format a failure event, including the exception message and backtrace.
 			class Failure
+				# The key used to identify this formatter.
 				KEY = :failure
 				
+				# Create a new failure formatter.
+				#
+				# @param terminal [Terminal::Text] The terminal to use for formatting.
 				def initialize(terminal)
 					@terminal = terminal
 					
@@ -19,7 +24,14 @@ module Console
 					@terminal[:exception_message] ||= @terminal.style(:default)
 				end
 				
-				def format(event, output, prefix: nil, verbose: false, width: 80)
+				# Format the given event.
+				#
+				# @parameter event [Hash] The event to format.
+				# @parameter stream [IO] The stream to write the formatted event to.
+				# @parameter prefix [String] The prefix to use before the title.
+				# @parameter verbose [Boolean] Whether to include additional information.
+				# @parameter options [Hash] Additional options.
+				def format(event, stream, prefix: nil, verbose: false, **options)
 					title = event[:class]
 					message = event[:message]
 					backtrace = event[:backtrace]
@@ -27,10 +39,10 @@ module Console
 					
 					lines = message.lines.map(&:chomp)
 					
-					output.puts "  #{prefix}#{@terminal[:exception_title]}#{title}#{@terminal.reset}: #{lines.shift}"
+					stream.puts "  #{prefix}#{@terminal[:exception_title]}#{title}#{@terminal.reset}: #{lines.shift}"
 					
 					lines.each do |line|
-						output.puts "  #{@terminal[:exception_detail]}#{line}#{@terminal.reset}"
+						stream.puts "  #{@terminal[:exception_detail]}#{line}#{@terminal.reset}"
 					end
 					
 					root_pattern = /^#{root}\// if root
@@ -44,11 +56,11 @@ module Console
 							style = :exception_backtrace_other
 						end
 						
-						output.puts "  #{index == 0 ? "→" : " "} #{@terminal[style]}#{path}:#{offset}#{@terminal[:exception_message]} #{message}#{@terminal.reset}"
+						stream.puts "  #{index == 0 ? "→" : " "} #{@terminal[style]}#{path}:#{offset}#{@terminal[:exception_message]} #{message}#{@terminal.reset}"
 					end
 					
 					if cause = event[:cause]
-						format(cause, output, prefix: "Caused by ", verbose: verbose, width: width)
+						format(cause, stream, prefix: "Caused by ", verbose: verbose, **options)
 					end
 				end
 			end

data/lib/console/terminal/formatter/progress.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Console
 	module Terminal
 		module Formatter
+			# Format a progress event, including the current progress and total.
 			class Progress
+				# The key used to identify this formatter.
 				KEY = :progress
 				
+				# The block characters used to render the progress bar.
 				BLOCK = [
 					" ",
 					"▏",
@@ -21,12 +24,21 @@ module Console
 					"█",
 				]
 				
+				# Create a new progress formatter.
+				#
+				# @param terminal [Terminal::Text] The terminal to use for formatting.
 				def initialize(terminal)
 					@terminal = terminal
 					@terminal[:progress_bar] ||= terminal.style(:blue, :white)
 				end
 				
-				def format(event, output, verbose: false, width: 80)
+				# Format the given event.
+				#
+				# @parameter event [Hash] The event to format.
+				# @parameter stream [IO] The stream to write the formatted event to.
+				# @parameter verbose [Boolean] Whether to include additional information.
+				# @parameter width [Integer] The width of the progress bar.
+				def format(event, stream, verbose: false, width: 80)
 					current = event[:current].to_f
 					total = event[:total].to_f
 					value = current / total
@@ -36,11 +48,12 @@ module Console
 						value = 1.0
 					end
 					
-					output.puts "#{@terminal[:progress_bar]}#{self.bar(value, width-10)}#{@terminal.reset} #{sprintf('%6.2f', value * 100)}%"
+					stream.puts "#{@terminal[:progress_bar]}#{self.bar(value, width-10)}#{@terminal.reset} #{sprintf('%6.2f', value * 100)}%"
 				end
 				
 				private
 				
+				# Render a progress bar with the given value and width.
 				def bar(value, width)
 					blocks = width * value
 					full_blocks = blocks.floor

data/lib/console/terminal/formatter/spawn.rb

@@ -1,36 +1,47 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Console
 	module Terminal
 		module Formatter
-			# Format spawn events.
+			# Format a spawn event, including the command and arguments.
 			class Spawn
+				# The key used to identify this formatter.
 				KEY = :spawn
 				
+				# Create a new spawn formatter.
+				#
+				# @param terminal [Terminal::Text] The terminal to use for formatting.
 				def initialize(terminal)
 					@terminal = terminal
 					@terminal[:spawn_command] ||= @terminal.style(:blue, nil, :bold)
 				end
 				
-				def format(event, output, verbose: false, width: 80)
+				# Format the given event.
+				#
+				# @parameter event [Hash] The event to format.
+				# @parameter stream [IO] The stream to write the formatted event to.
+				# @parameter verbose [Boolean] Whether to include additional information.
+				# @parameter width [Integer] The width of the progress bar.
+				def format(event, stream, verbose: false, width: 80)
 					environment, arguments, options = event.values_at(:environment, :arguments, :options)
 					
 					arguments = arguments.flatten.collect(&:to_s)
 					
-					output.puts "#{@terminal[:spawn_command]}#{arguments.join(' ')}#{@terminal.reset}#{chdir_string(options)}"
+					stream.puts "#{@terminal[:spawn_command]}#{arguments.join(' ')}#{@terminal.reset}#{chdir_string(options)}"
 					
 					if verbose and environment
 						environment.each do |key, value|
-							output.puts "export #{key}=#{value}"
+							stream.puts "export #{key}=#{value}"
 						end
 					end
 				end
 				
 				private
 				
+				# Generate a string to represent the working directory.
 				def chdir_string(options)
 					if options and chdir = options[:chdir]
 						" in #{chdir}"

data/lib/console/terminal/formatter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "formatter/progress"
+require_relative "formatter/failure"
+require_relative "formatter/spawn"
+
+module Console
+	module Terminal
+		# Formatters for various types of events.
+		module Formatter
+		end
+	end
+end

data/lib/console/terminal/text.rb

@@ -1,82 +1,128 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2025, by Patrik Wenger.
 
 require "io/console"
 
 module Console
 	# Styled terminal output.
 	module Terminal
+		# A simple text-based terminal output.
 		class Text
-			def initialize(output)
-				@output = output
+			# Create a new text terminal output.
+			#
+			# @parameter stream [IO] The stream to write to.
+			def initialize(stream)
+				@stream = stream
 				@styles = {reset: self.reset}
 			end
 			
+			# @attribute [IO] The stream to write to.
+			attr :stream
+			
+			# Get the style associated with the given key.
+			#
+			# @parameter key [Symbol] The key to look up.
+			# @returns [String] The style associated with the key.
 			def [] key
 				@styles[key]
 			end
 			
+			# Set the style associated with the given key.
+			#
+			# @parameter key [Symbol] The key to associate the style with.
+			# @parameter value [String] The style to associate with the key.
 			def []= key, value
 				@styles[key] = value
 			end
 			
+			# @returns [Boolean] Whether the terminal supports colors.
 			def colors?
 				false
 			end
 			
+			# @returns [Tuple(Integer, Integer)] The size of the terminal, or a default value of [24, 80].
+			def size
+				[24, 80]
+			end
+			
+			# @returns [Integer] The width of the terminal.
 			def width
-				80
+				self.size.last
 			end
 			
+			# Generate a style string for the given foreground, background, and attributes.
+			#
+			# @returns [String | Nil] The style string if colors are supported, otherwise nil.
 			def style(foreground, background = nil, *attributes)
 			end
 			
+			# Generate a reset sequence.
+			#
+			# @returns [String | Nil] The reset sequence if colors are supported, otherwise nil.
 			def reset
 			end
 			
+			# Write the given arguments to the output stream using the given style. The reset sequence is automatically appended.
+			#
+			# @parameter arguments [Array] The arguments to write.
+			# @parameter style [Symbol] The style to apply.
 			def write(*arguments, style: nil)
 				if style and prefix = self[style]
-					@output.write(prefix)
-					@output.write(*arguments)
-					@output.write(self.reset)
+					@stream.write(prefix)
+					@stream.write(*arguments)
+					@stream.write(self.reset)
 				else
-					@output.write(*arguments)
+					@stream.write(*arguments)
 				end
 			end
 			
+			# Write the given arguments to the output stream using the given style. The reset sequence is automatically
+			# appended at the end of each line.
+			#
+			# @parameter arguments [Array] The arguments to write, each on a new line.
+			# @parameter style [Symbol] The style to apply.
 			def puts(*arguments, style: nil)
 				if style and prefix = self[style]
-					@output.write(prefix)
-					@output.puts(*arguments)
-					@output.write(self.reset)
+					arguments.each do |argument|
+						argument.to_s.lines.each do |line|
+							@stream.write(prefix, line.chomp)
+							@stream.puts(self.reset)
+						end
+					end
 				else
-					@output.puts(*arguments)
+					@stream.puts(*arguments)
 				end
 			end
 			
-			# Print out the given arguments.
-			# When the argument is a symbol, look up the style and inject it into the output stream.
-			# When the argument is a proc/lambda, call it with self as the argument.
-			# When the argument is anything else, write it directly to the output.
+			# Print rich text to the output stream.
+			#
+			# - When the argument is a symbol, look up the style and inject it into the output stream.
+			# - When the argument is a proc/lambda, call it with self as the argument.
+			# - When the argument is anything else, write it directly to the output.
+			#
+			# @parameter arguments [Array] The arguments to print.
 			def print(*arguments)
 				arguments.each do |argument|
 					case argument
 					when Symbol
-						@output.write(self[argument])
+						@stream.write(self[argument])
 					when Proc
 						argument.call(self)
 					else
-						@output.write(argument)
+						@stream.write(argument)
 					end
 				end
 			end
 			
-			# Print out the arguments as per {#print}, followed by the reset sequence and a newline.
+			# Print rich text to the output stream, followed by the reset sequence and a newline.
+			#
+			# @parameter arguments [Array] The arguments to print.
 			def print_line(*arguments)
 				print(*arguments)
-				@output.puts(self.reset)
+				@stream.puts(self.reset)
 			end
 		end
 	end

data/lib/console/terminal/xterm.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 "io/console"
 
@@ -10,7 +10,9 @@ require_relative "text"
 module Console
 	# Styled terminal output.
 	module Terminal
+		# XTerm style terminal output.
 		class XTerm < Text
+			# XTerm color codes.
 			COLORS = {
 				black: 0,
 				red: 1,
@@ -23,6 +25,7 @@ module Console
 				default: 9,
 			}.freeze
 			
+			# XTerm attribute codes.
 			ATTRIBUTES = {
 				normal: 0,
 				bold: 1,
@@ -35,21 +38,30 @@ module Console
 				hidden: 8,
 			}.freeze
 			
+			# Whether the terminal supports colors.
 			def colors?
 				true
 			end
 			
+			# The size of the terminal.
 			def size
-				@output.winsize
-			rescue Errno::ENOTTY
+				@stream.winsize
+			rescue Errno::ENOTTY, Errno::ENODEV
 				# Fake it...
 				[24, 80]
 			end
 			
+			# The width of the terminal.
 			def width
 				size.last
 			end
 			
+			# Apply the given style to the output.
+			#
+			# @parameter foreground [Symbol] The foreground color.
+			# @parameter background [Symbol] The background color.
+			# @parameter attributes [Array(Symbol)] The attributes to apply.
+			# @returns [String] The style code.
 			def style(foreground, background = nil, *attributes)
 				tokens = []
 				
@@ -68,6 +80,9 @@ module Console
 				return "\e[#{tokens.join(';')}m"
 			end
 			
+			# Reset the style.
+			#
+			# @returns [String] The reset code.
 			def reset
 				"\e[0m"
 			end

data/lib/console/terminal.rb

@@ -1,22 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "terminal/text"
 require_relative "terminal/xterm"
-
-require_relative "terminal/formatter/progress"
-require_relative "terminal/formatter/failure"
-require_relative "terminal/formatter/spawn"
+require_relative "terminal/formatter"
 
 module Console
 	module Terminal
-		def self.for(io)
-			if io.tty?
-				XTerm.new(io)
+		# Create a new terminal output for the given stream.
+		def self.for(stream)
+			if stream.tty?
+				XTerm.new(stream)
 			else
-				Text.new(io)
+				Text.new(stream)
 			end
 		end
 	end

data/lib/console/version.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 module Console
-	VERSION = "1.29.2"
+	VERSION = "1.36.0"
 end

data/lib/console/warn.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "logger"
 
@@ -22,7 +22,7 @@ module Console
 				fiber.console_warn = true
 				message.chomp!
 				
-				Console::Logger.instance.warn(message, **options)
+				Console::Interface.instance.warn(message, **options)
 			ensure
 				fiber.console_warn = false
 			end

data/lib/console.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, 2019, by Bryan Powell.
 # Copyright, 2020, by Michael Adams.
 # Copyright, 2021, by Cédric Boutillier.
@@ -9,6 +9,7 @@
 require_relative "console/version"
 require_relative "console/interface"
 
+# @namespace
 module Console
 	Console.extend(Interface)
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2019-2024, by Samuel Williams.  
+Copyright, 2019-2026, by Samuel Williams.  
 Copyright, 2019-2021, by Bryan Powell.  
 Copyright, 2019, by Cyril Roelandt.  
 Copyright, 2020, by Olle Jonsson.  
@@ -8,9 +8,12 @@ Copyright, 2020, by Michael Adams.
 Copyright, 2021, by Cédric Boutillier.  
 Copyright, 2021, by Robert Schulze.  
 Copyright, 2022, by Anton Sozontov.  
-Copyright, 2022, by William T. Nelson.  
+Copyright, 2022-2026, by William T. Nelson.  
 Copyright, 2023, by Felix Yan.  
-Copyright, 2024, by Patrik Wenger.  
+Copyright, 2024-2025, by Patrik Wenger.  
+Copyright, 2025, by Shigeru Nakajima.  
+Copyright, 2025, by Yasha Krasnou.  
+Copyright, 2026, by Copilot.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -24,6 +24,8 @@ Please see the [project documentation](https://socketry.github.io/console/) for
 
   - [Command Line](https://socketry.github.io/console/guides/command-line/index) - This guide explains how the `console` gem can be controlled using environment variables.
 
+  - [Configuration](https://socketry.github.io/console/guides/configuration/index) - This guide explains how to implement per-project configuration for the `console` gem.
+
   - [Integration](https://socketry.github.io/console/guides/integration/index) - This guide explains how to integrate the `console` output into different systems.
 
   - [Events](https://socketry.github.io/console/guides/events/index) - This guide explains how to log structured events with a well-defined schema.
@@ -32,15 +34,51 @@ Please see the [project documentation](https://socketry.github.io/console/) for
 
 Please see the [project releases](https://socketry.github.io/console/releases/index) for all releases.
 
-### v1.29.0
+### v1.36.0
+
+  - Add a `size_limit` to `Console::Format::Safe` (default 16KiB) which rebuilds oversized records field-by-field, keeping as many top-level fields as fit within the limit.
+  - Degraded fields are recorded in a `truncated` object that maps each field name to why it was truncated: `true` (dropped for size) or the error (the value could not be serialized directly and a safe representation was kept in its place).
+  - Rename `Console::Format::Safe`'s `limit:` to `depth_limit:` (with a deprecated `limit:` alias) to clarify its purpose alongside the new `size_limit:`.
+
+### v1.35.0
+
+  - Fix handling of `Errno::ENODEV` errors when calculating the width of a terminal that was been re-opened to `File::NULL`.
+
+### v1.34.1
+
+  - Add `process_id` to serialized output records for clarity (`pid` is still included for backwards compatibility).
+      - Add `object_id` to serialized output records **only** when the subject is not a string or class/module.
+
+### v1.34.0
+
+  - Allow `Console::Compatible::Logger#add` to accept `**options`.
+
+### v1.32.0
+
+  - Add `fiber_id` to serialized output records to help identify which fiber logged the message.
+  - Ractor support appears broken in older Ruby versions, so we now require Ruby 3.4 or later for Ractor compatibility, if you need Ractor support.
+
+### v1.31.0
+
+  - [Ractor compatibility.](https://socketry.github.io/console/releases/index#ractor-compatibility.)
+  - [Symbol log level compatibility.](https://socketry.github.io/console/releases/index#symbol-log-level-compatibility.)
+  - [Improved output format selection for cron jobs and email contexts.](https://socketry.github.io/console/releases/index#improved-output-format-selection-for-cron-jobs-and-email-contexts.)
 
-  - Don't make `Kernel#warn` redirection to `Console.warn` the default behavior, you must `require 'console/warn'` to enable it.
-  - Remove deprecated `Console::Logger#failure`.
-  - [Consistent Handling of Exceptions](https://socketry.github.io/console/releases/index#consistent-handling-of-exceptions)
+### v1.30.0
 
-### v1.28.0
+  - [Introduce `Console::Config` for fine grained configuration.](https://socketry.github.io/console/releases/index#introduce-console::config-for-fine-grained-configuration.)
 
-  - Add support for `Kernel#warn` redirection to `Console.warn`.
+### v1.29.3
+
+  - Serialized output now uses `IO#write` with a single string to reduce the chance of interleaved output.
+
+### v1.29.2
+
+  - Always return `nil` from `Console::Filter` logging methods.
+
+### v1.29.1
+
+  - Fix logging `exception:` keyword argument when the value was not an exception.
 
 ## Contributing
 
@@ -52,6 +90,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.