console 1.29.3 → 1.30.1

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,123 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 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.
+			#
+			# @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)
+					@stream.write(prefix)
+					@stream.puts(*arguments)
+					@stream.write(self.reset)
 				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
+				@stream.winsize
 			rescue Errno::ENOTTY
 				# 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-2025, by Samuel Williams.
 
 module Console
-	VERSION = "1.29.3"
+	VERSION = "1.30.1"
 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

@@ -11,6 +11,7 @@ Copyright, 2022, by Anton Sozontov.
 Copyright, 2022, by William T. Nelson.  
 Copyright, 2023, by Felix Yan.  
 Copyright, 2024, by Patrik Wenger.  
+Copyright, 2025, by Shigeru Nakajima.  
 
 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,6 +34,10 @@ 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.30.0
+
+  - [Introduce `Console::Config` for fine grained configuration.](https://socketry.github.io/console/releases/index#introduce-console::config-for-fine-grained-configuration.)
+
 ### v1.29.3
 
   - Serialized output now uses `IO#write` with a single string to reduce the chance of interleaved output.
@@ -48,7 +54,7 @@ Please see the [project releases](https://socketry.github.io/console/releases/in
 
   - 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)
+  - [Consistent handling of exceptions.](https://socketry.github.io/console/releases/index#consistent-handling-of-exceptions.)
 
 ### v1.28.0
 

data/releases.md

@@ -1,5 +1,28 @@
 # Releases
 
+## v1.30.0
+
+### Introduce `Console::Config` for fine grained configuration.
+
+Introduced a new explicit configuration interface via config/console.rb to enhance logging setup in complex applications. This update gives the application code an opportunity to load files if required and control aspects such as log level, output, and more. Users can override default behaviors (e.g., make\_output, make\_logger, and log\_level) for improved customization.
+
+``` ruby
+# config/console.rb
+def log_level(env = ENV)
+	# Set a custom log level, e.g., force debug mode:
+	:debug
+end
+
+def make_logger(output = $stderr, env = ENV, **options)
+	# Custom logger configuration with verbose output:
+	options[:verbose] = true
+	
+	 Logger.new(output, **options)
+end
+```
+
+This approach provides a standard way to hook into the log setup process, allowing tailored adjustments for reliable and customizable logging behavior.
+
 ## v1.29.3
 
   - Serialized output now uses `IO#write` with a single string to reduce the chance of interleaved output.
@@ -17,7 +40,7 @@
   - 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
+### Consistent handling of exceptions.
 
 `Console.call` and all wrapper methods will now consistently handle exceptions that are the last positional argument or keyword argument. This means that the following code will work as expected:
 

data.tar.gz.sig

@@ -1,3 +1,4 @@
-o�?r�q���a-��]�Tx��an%D�i��u���8�!j�J�r>`v��>b�'3��/���
7	f�U�H*��ҟ�X(���-�����C�،)݄Z1���k��B�K�)\K�AY�`����l��h��{P�Ę�$pl���V-��!˩!�v]
-<=k	F��=]��
-ײ�6�L�yP[pG�Ӌ7x�k��#�-��Hu�D�@n�=�Ӄ����64����NKm�$�]��FVKZ��֋0)r�-ن/�boJg�槪m�}�˱t�C���Og��7�����V���Z��㚣5���3v���,?���ԟȜ�MR��-�W!v5穀��9ď8/�&�W�S�N�:��@�rVpsi<��y���
+���
��2D���4*�����]q�>�C]u����Ռ=Op�lr�R�&h�����O&V�N5
(_!�ﷰ��
+���g�Ѳ�����
+A��Cfh\.51<񚹂���yN���%2?l�^�Ħ��a�[���8O�5��T—j���yB_QO�̜�G�Q%����ޥ~��:q�����VиsZ��^j�P>�]���G��p�B���<�J6���ǁk�{ͨ�}I]��;����9X��fI�
+
q���e=�jG-5�(F���~tЍ,�iЇR^��\�d��=�5/�Q��j���>���jp�W^V)$�`Z`=z$�����>p��cG-lg+��0�f&�SDx����D9�\�1�zrD�n"2=(ޒ�c��T�

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console
 version: !ruby/object:Gem::Version
-  version: 1.29.3
+  version: 1.30.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -14,6 +14,7 @@ authors:
 - Felix Yan
 - Olle Jonsson
 - Patrik Wenger
+- Shigeru Nakajima
 - William T. Nelson
 bindir: bin
 cert_chain:
@@ -46,7 +47,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-19 00:00:00.000000000 Z
+date: 2025-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiber-annotation
@@ -100,6 +101,7 @@ files:
 - lib/console/capture.rb
 - lib/console/clock.rb
 - lib/console/compatible/logger.rb
+- lib/console/config.rb
 - lib/console/event.rb
 - lib/console/event/failure.rb
 - lib/console/event/generic.rb
@@ -121,6 +123,7 @@ files:
 - lib/console/progress.rb
 - lib/console/resolver.rb
 - lib/console/terminal.rb
+- lib/console/terminal/formatter.rb
 - lib/console/terminal/formatter/failure.rb
 - lib/console/terminal/formatter/progress.rb
 - lib/console/terminal/formatter/spawn.rb