console 1.19.0 → 1.29.0

data/lib/console/interface.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright 2024, by Samuel Williams.
+
+require_relative "logger"
+
+module Console
+	# The public logger interface.
+	module Interface
+		# Get the current logger instance.
+		def logger
+			Logger.instance
+		end
+		
+		# Set the current logger instance.
+		#
+		# The current logger instance is assigned per-fiber.
+		def logger= instance
+			Logger.instance= instance
+		end
+		
+		# Emit a debug log message.
+		def debug(...)
+			Logger.instance.debug(...)
+		end
+		
+		# Emit an informational log message.
+		def info(...)
+			Logger.instance.info(...)
+		end
+		
+		# Emit a warning log message.
+		def warn(...)
+			Logger.instance.warn(...)
+		end
+		
+		# Emit an error log message.
+		def error(...)
+			Logger.instance.error(...)
+		end
+		
+		# Emit a fatal log message.
+		def fatal(...)
+			Logger.instance.fatal(...)
+		end
+		
+		# Emit a log message with arbitrary arguments and options.
+		def call(...)
+			Logger.instance.call(...)
+		end
+	end
+end

data/lib/console/logger.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2021, by Bryan Powell.
 # Copyright, 2021, by Robert Schulze.
 
-require_relative 'output'
-require_relative 'filter'
-require_relative 'progress'
+require_relative "output"
+require_relative "output/failure"
 
-require_relative 'resolver'
-require_relative 'terminal/logger'
-require_relative 'serialized/logger'
+require_relative "filter"
+require_relative "event"
+require_relative "resolver"
+require_relative "progress"
 
-require 'fiber/local'
+require "fiber/local"
 
 module Console
 	class Logger < Filter[debug: 0, info: 1, warn: 2, error: 3, fatal: 4]
@@ -23,7 +23,7 @@ module Console
 		# 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)
-			if level = env['CONSOLE_LEVEL']
+			if level = env["CONSOLE_LEVEL"]
 				LEVELS[level.to_sym] || level.to_i
 			elsif $DEBUG
 				DEBUG
@@ -36,7 +36,7 @@ module Console
 		
 		# Controls verbose output using `$VERBOSE`.
 		def self.verbose?(env = ENV)
-			!$VERBOSE.nil? || env['CONSOLE_VERBOSE']
+			!$VERBOSE.nil? || env["CONSOLE_VERBOSE"]
 		end
 		
 		def self.default_logger(output = $stderr, env = ENV, **options)
@@ -49,6 +49,7 @@ module Console
 			end
 			
 			output = Output.new(output, env, **options)
+			
 			logger = self.new(output, **options)
 			
 			Resolver.default_resolver(logger)
@@ -63,16 +64,16 @@ module Console
 		DEFAULT_LEVEL = 1
 		
 		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)
+			
 			super(output, **options)
 		end
 		
 		def progress(subject, total, **options)
-			Progress.new(self, subject, total, **options)
-		end
-		
-		# @deprecated Use `fatal` instead.
-		def failure(subject, exception, *arguments, &block)
-			self.fatal(subject, exception, *arguments, &block)
+			options[:severity] ||= :info
+			
+			Progress.new(subject, total, **options)
 		end
 	end
 end

data/lib/console/output/default.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
-require_relative 'xterm'
-require_relative 'json'
+require_relative "terminal"
+require_relative "serialized"
+require_relative "failure"
 
 module Console
 	module Output
@@ -13,10 +14,12 @@ module Console
 				output ||= $stderr
 				
 				if output.tty?
-					XTerm.new(output, **options)
+					output = Terminal.new(output, **options)
 				else
-					JSON.new(output, **options)
+					output = Serialized.new(output, **options)
 				end
+				
+				return output
 			end
 		end
 	end

data/lib/console/output/failure.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021-2024, by Samuel Williams.
+
+require_relative "wrapper"
+require_relative "../event/failure"
+
+module Console
+	module Output
+		# A wrapper for outputting failure messages, which can include exceptions.
+		class Failure < Wrapper
+			def initialize(output, **options)
+				super(output, **options)
+			end
+			
+			# The exception must be either the last argument or passed as an option.
+			def call(subject = nil, *arguments, exception: nil, **options, &block)
+				if exception.nil?
+					last = arguments.last
+					if last.is_a?(Exception)
+						options[:event] = Event::Failure.for(last)
+					end
+				else
+					options[:event] = Event::Failure.for(exception)
+				end
+				
+				super(subject, *arguments, **options)
+			end
+		end
+	end
+end

data/lib/console/output/null.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2024, by Samuel Williams.
 
 module Console
 	module Output
@@ -9,6 +9,10 @@ module Console
 			def initialize(...)
 			end
 			
+			def last_output
+				self
+			end
+			
 			def call(...)
 				# Do nothing.
 			end

data/lib/console/output/sensitive.rb

@@ -1,19 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
-require_relative '../serialized/logger'
+require_relative "wrapper"
 
 module Console
 	module Output
-		class Sensitive
-			def initialize(output, **options)
-				@output = output
-			end
-			
+		class Sensitive < Wrapper
 			REDACT = /
-				  phone
+				phone
 				| email
 				| full_?name
 				| first_?name
@@ -38,8 +34,14 @@ module Console
 				| password
 			/xi
 			
+			def initialize(output, redact: REDACT, **options)
+				super(output, **options)
+				
+				@redact = redact
+			end
+			
 			def redact?(text)
-				text.match?(REDACT)
+				text.match?(@redact)
 			end
 			
 			def redact_hash(arguments, filter)
@@ -96,7 +98,7 @@ module Console
 					arguments = redact_array(arguments, filter)
 				end
 				
-				@output.call(subject, *arguments, **options)
+				super(subject, *arguments, **options)
 			end
 		end
 	end

data/lib/console/{serialized/logger.rb → output/serialized.rb}

@@ -1,34 +1,28 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require_relative '../buffer'
-require_relative '../filter'
-
-require 'time'
-require 'json'
-
-require 'fiber/annotation'
+require_relative "../format"
+require "time"
+require "fiber/annotation"
 
 module Console
-	module Serialized
-		class Logger
-			def initialize(io = $stderr, format: JSON, verbose: false, **options)
+	module Output
+		class Serialized
+			def initialize(io, format: Format.default, **options)
 				@io = io
-				@start = Time.now
 				@format = format
-				@verbose = verbose
+			end
+			
+			# This a final output that then writes to an IO object.
+			def last_output
+				self
 			end
 			
 			attr :io
-			attr :start
 			attr :format
 			
-			def verbose!(value = true)
-				@verbose = true
-			end
-			
 			def dump(record)
 				@format.dump(record)
 			end
@@ -72,41 +66,12 @@ module Console
 					record[:message] = message
 				end
 				
-				if exception = find_exception(message)
-					record[:error] = {
-						kind: exception.class,
-						message: exception.message,
-						stack: format_stack(exception)
-					}
-				end
-				
 				record.update(options)
 				
 				@io.puts(self.dump(record))
 			end
-			
-			private
-			
-			def find_exception(message)
-				message.find{|part| part.is_a?(Exception)}
-			end
-			
-			def format_stack(exception)
-				buffer = StringIO.new
-				format_backtrace(exception, buffer)
-				return buffer.string
-			end
-			
-			def format_backtrace(exception, buffer)
-				buffer.puts exception.backtrace
-				
-				if exception = exception.cause
-					buffer.puts
-					buffer.puts "Caused by: #{exception.class} #{exception.message}"
-
-					format_backtrace(exception, buffer)
-				end
-			end
 		end
+		
+		JSON = Serialized
 	end
 end

data/lib/console/output/split.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
 module Console
 	module Output
@@ -18,9 +18,9 @@ module Console
 				@outputs.each{|output| output.verbose!(value)}
 			end
 			
-			def call(level, subject = nil, *arguments, **options, &block)
+			def call(...)
 				@outputs.each do |output|
-					output.call(level, subject, *arguments, **options, &block)
+					output.call(...)
 				end
 			end
 		end

data/lib/console/{terminal/logger.rb → output/terminal.rb}

@@ -1,53 +1,61 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2021, by Robert Schulze.
 
-require_relative '../buffer'
-require_relative '../event'
-require_relative '../clock'
+require_relative "../clock"
+require_relative "../terminal"
 
-require_relative 'text'
-require_relative 'xterm'
-
-require 'json'
-require 'fiber'
-require 'fiber/annotation'
+require "json"
+require "fiber"
+require "fiber/annotation"
+require "stringio"
 
 module Console
-	module Terminal
-		# This, and all related methods, is considered private.
-		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]
-				start_at = Time.parse(time_string) rescue nil
+	module Output
+		class Terminal
+			class Buffer < StringIO
+				def initialize(prefix = nil)
+					@prefix = prefix
+					
+					super()
+				end
+				
+				attr :prefix
+				
+				def puts(*args, prefix: @prefix)
+					args.each do |arg|
+						self.write(prefix) if prefix
+						super(arg)
+					end
+				end
+				
+				alias << puts
 			end
 			
-			unless start_at
-				start_at = Time.now
-				environment[CONSOLE_START_AT] = start_at.to_s
-			end
+			# This, and all related methods, is considered private.
+			CONSOLE_START_AT = "CONSOLE_START_AT"
 			
-			return start_at
-		end
-		
-		def self.for(io)
-			if io.isatty
-				XTerm.new(io)
-			else
-				Text.new(io)
+			# 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]
+					start_at = Time.parse(time_string) rescue nil
+				end
+				
+				unless start_at
+					start_at = Time.now
+					environment[CONSOLE_START_AT] = start_at.to_s
+				end
+				
+				return start_at
 			end
-		end
-		
-		class Logger
-			def initialize(io = $stderr, verbose: nil, start_at: Terminal.start_at!, format: nil, **options)
-				@io = io
+			
+			def initialize(output, verbose: nil, start_at: Terminal.start_at!, format: nil, **options)
+				@io = output
 				@start_at = start_at
 				
-				@terminal = format.nil? ? Terminal.for(io) : format.new(io)
+				@terminal = format.nil? ? Console::Terminal.for(@io) : format.new(@io)
 				
 				if verbose.nil?
 					@verbose = !@terminal.colors?
@@ -66,7 +74,13 @@ module Console
 				@terminal[:annotation] = @terminal.reset
 				@terminal[:value] = @terminal.style(:blue)
 				
-				self.register_defaults(@terminal)
+				@formatters = {}
+				self.register_formatters
+			end
+			
+			# This a final output that then writes to an IO object.
+			def last_output
+				self
 			end
 			
 			attr :io
@@ -80,20 +94,23 @@ module Console
 				@verbose = value
 			end
 			
-			def register_defaults(terminal)
-				Event.constants.each do |constant|
-					klass = Event.const_get(constant)
-					klass.register(terminal)
+			def register_formatters(namespace = Console::Terminal::Formatter)
+				namespace.constants.each do |name|
+					formatter = namespace.const_get(name)
+					@formatters[formatter::KEY] = formatter.new(@terminal)
 				end
 			end
 			
 			UNKNOWN = :unknown
 			
-			def call(subject = nil, *arguments, name: nil, severity: UNKNOWN, **options, &block)
+			def call(subject = nil, *arguments, name: nil, severity: UNKNOWN, event: nil, **options, &block)
+				width = @terminal.width
+				
 				prefix = build_prefix(name || severity.to_s)
 				indent = " " * prefix.size
 				
 				buffer = Buffer.new("#{indent}| ")
+				indent_size = buffer.prefix.size
 				
 				format_subject(severity, prefix, subject, buffer)
 				
@@ -109,6 +126,10 @@ module Console
 					end
 				end
 				
+				if event
+					format_event(event, buffer, width - indent_size)
+				end
+				
 				if options&.any?
 					format_options(options, buffer)
 				end
@@ -118,20 +139,24 @@ module Console
 			
 			protected
 			
+			def format_event(event, buffer, width)
+				event = event.to_hash
+				type = event[:type]
+				
+				if formatter = @formatters[type]
+					formatter.format(event, buffer, verbose: @verbose, width: width)
+				else
+					format_value(::JSON.pretty_generate(event), buffer)
+				end
+			end
+			
 			def format_options(options, output)
-				format_value(options.to_json, output)
+				format_value(::JSON.pretty_generate(options), output)
 			end
 			
 			def format_argument(argument, output)
-				case argument
-				when Exception
-					Event::Failure.for(argument).format(output, @terminal, @verbose)
-				when Event::Generic
-					argument.format(output, @terminal, @verbose)
-				else
-					argument.to_s.each_line do |line|
-						output.puts line
-					end
+				argument.to_s.each_line do |line|
+					output.puts line
 				end
 			end
 			
@@ -149,8 +174,14 @@ module Console
 				buffer = +""
 				
 				if @verbose
-					if annotation = Fiber.current.annotation and annotation.size > 0
-						buffer << ": #{@terminal[:annotation]}#{annotation}#{@terminal.reset}"
+					if annotation = Fiber.current.annotation
+						# While typically annotations should be strings, that is not always the case.
+						annotation = annotation.to_s
+						
+						# If the annotation is empty, we don't want to print it, as it will look like a formatting bug.
+						if annotation.size > 0
+							buffer << ": #{@terminal[:annotation]}#{annotation}#{@terminal.reset}"
+						end
 					end
 				end
 				
@@ -193,6 +224,7 @@ module Console
 				string = value.to_s
 				
 				string.each_line do |line|
+					line.chomp!
 					output.puts "#{@terminal[:value]}#{line}#{@terminal.reset}"
 				end
 			end
@@ -209,5 +241,17 @@ module Console
 				end
 			end
 		end
+		
+		module Text
+			def self.new(output, **options)
+				Terminal.new(output, format: Console::Terminal::Text, **options)
+			end
+		end
+		
+		module XTerm
+			def self.new(output, **options)
+				Terminal.new(output, format: Console::Terminal::XTerm, **options)
+			end
+		end
 	end
 end

data/lib/console/output/wrapper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021-2024, by Samuel Williams.
+
+module Console
+	module Output
+		class Wrapper
+			def initialize(delegate, **options)
+				@delegate = delegate
+			end
+			
+			attr :delegate
+			
+			def last_output
+				@delegate.last_output
+			end
+			
+			def verbose!(value = true)
+				@delegate.verbose!(value)
+			end
+			
+			def call(...)
+				@delegate.call(...)
+			end
+		end
+	end
+end

data/lib/console/output.rb

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
-require_relative 'output/default'
-require_relative 'output/json'
-require_relative 'output/text'
-require_relative 'output/xterm'
-require_relative 'output/null'
+require_relative "output/default"
+require_relative "output/serialized"
+require_relative "output/terminal"
+require_relative "output/null"
 
 module Console
 	module Output
 		def self.new(output = nil, env = ENV, **options)
-			if names = env['CONSOLE_OUTPUT']
-				names = names.split(',').reverse
+			if names = env["CONSOLE_OUTPUT"]
+				names = names.split(",").reverse
 				
 				names.inject(output) do |output, name|
 					Output.const_get(name).new(output, **options)