console 1.29.2 → 1.30.0

data/lib/console/terminal/text.rb

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

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

@@ -5,18 +5,16 @@
 
 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

@@ -4,5 +4,5 @@
 # Copyright, 2019-2024, by Samuel Williams.
 
 module Console
-	VERSION = "1.29.2"
+	VERSION = "1.30.0"
 end

data/lib/console/warn.rb

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

@@ -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-2025, by Samuel Williams.  
 Copyright, 2019-2021, by Bryan Powell.  
 Copyright, 2019, by Cyril Roelandt.  
 Copyright, 2020, by Olle Jonsson.  

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,11 +34,27 @@ 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.
+
+### 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.
+
 ### v1.29.0
 
   - 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,11 +1,46 @@
 # 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.
+
+## 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.
+
 ## v1.29.0
 
   - 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:
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console
 version: !ruby/object:Gem::Version
-  version: 1.29.2
+  version: 1.30.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -15,7 +15,6 @@ authors:
 - Olle Jonsson
 - Patrik Wenger
 - William T. Nelson
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -47,7 +46,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-12-09 00:00:00.000000000 Z
+date: 2025-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiber-annotation
@@ -91,8 +90,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -103,6 +100,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
@@ -124,6 +122,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
@@ -139,7 +138,6 @@ licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/console/
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -154,8 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Beautiful logging for Ruby.
 test_files: []