Separation of output formatting from log generation/schema. (#60)

.github/workflows/documentation.yaml

@@ -40,7 +40,7 @@ jobs:
       run: bundle exec bake utopia:project:static --force no
 
     - name: Upload documentation artifact
-      uses: actions/upload-pages-artifact@v2
+      uses: actions/upload-pages-artifact@v3
       with:
         path: docs
 
@@ -55,4 +55,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v3
+        uses: actions/deploy-pages@v4

.github/workflows/test-external.yaml

@@ -20,7 +20,6 @@ jobs:
           - macos
 
         ruby:
-          - "3.0"
           - "3.1"
           - "3.2"
           - "3.3"

.github/workflows/test.yaml

@@ -21,7 +21,6 @@ jobs:
           - macos
 
         ruby:
-          - "3.0"
           - "3.1"
           - "3.2"
           - "3.3"

config/external.yaml

@@ -1,3 +1,9 @@
+async:
+  url: https://github.com/socketry/async
+  command: bundle exec bake test
 async-dns:
   url: https://github.com/socketry/async-dns
   command: CONSOLE_LEVEL=debug bundle exec rspec
+falcon:
+  url: https://github.com/socketry/falcon
+  command: CONSOLE_LEVEL=debug bundle exec sus

console.gemspec

@@ -13,11 +13,15 @@ Gem::Specification.new do |spec|
 	spec.cert_chain  = ['release.cert']
 	spec.signing_key = File.expand_path('~/.gem/release.pem')
 
-	spec.homepage = "https://socketry.github.io/console/"
+	spec.homepage = "https://socketry.github.io/console"
+
+	spec.metadata = {
+		"documentation_uri" => "https://socketry.github.io/console/",
+	}
 
 	spec.files = Dir.glob(['{bake,lib}/**/*', '*.md'], File::FNM_DOTMATCH, base: __dir__)
 
-	spec.required_ruby_version = ">= 3.0"
+	spec.required_ruby_version = ">= 3.1"
 
 	spec.add_dependency "fiber-annotation"
 	spec.add_dependency "fiber-storage"

fixtures/console/captured_output.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require 'sus/shared'
+
+module Console
+	CapturedOutput = Sus::Shared("captured output") do
+		let(:capture) {Console::Capture.new}
+		let(:logger) {Console::Logger.new(capture)}
+
+		def around
+			Fiber.new do
+				Console.logger = logger
+				super
+			end.resume
+		end	
+	end
+end

gems.rb

@@ -1,24 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in console.gemspec
 gemspec
 
 group :maintenance, optional: true do
 	gem "bake-gem"
 	gem "bake-modernize"
 
-	gem "bake-github-pages"
 	gem "utopia-project"
 end
 
 group :test do
-	gem "covered", "~> 0.18.1"
-	gem "sus", "~> 0.14"
+	gem "sus"
+	gem "covered"
 
 	gem "bake-test"
 	gem "bake-test-external"

lib/console.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2019, by Bryan Powell.
 # Copyright, 2020, by Michael Adams.
 # Copyright, 2021, by Cédric Boutillier.
@@ -43,12 +43,4 @@ def call(...)
 			Logger.instance.call(...)
 		end
 	end
-
-	def logger= logger
-		warn "Setting logger on #{self} is deprecated. Use Console.logger= instead.", uplevel: 1
-	end
-
-	def logger
-		Logger.instance
-	end
 end

lib/console/adapter.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2024, by Samuel Williams.
 
 module Console
+	# This namespace is reserved for logging adapters provided by other gems.
 	module Adapter
 	end
 end

lib/console/capture.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'filter'
 
@@ -40,7 +40,7 @@ def verbose?
 			@verbose
 		end
 
-		def call(subject = nil, *arguments, severity: UNKNOWN, **options, &block)
+		def call(subject = nil, *arguments, severity: UNKNOWN, event: nil,  **options, &block)
 			message = {
 				time: ::Time.now.iso8601,
 				severity: severity,
@@ -51,6 +51,10 @@ def call(subject = nil, *arguments, severity: UNKNOWN, **options, &block)
 				message[:subject] = subject
 			end
 
+			if event
+				message[:event] = event.to_hash
+			end
+
 			if arguments.any?
 				message[:arguments] = arguments
 			end

lib/console/compatible/logger.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
 require 'logger'
 
 module Console
 	module Compatible
+		# A compatible interface for {::Logger} which can be used with {Console}.
 		class Logger < ::Logger
 			class LogDevice
 				def initialize(subject, output)

lib/console/event.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'event/spawn'
 require_relative 'event/failure'
-require_relative 'event/progress'

lib/console/event/failure.rb

@@ -1,83 +1,74 @@
 # 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 'generic'
 
 module Console
 	module Event
+		# Represents a failure event.
+		#
+		# ```ruby
+		# Console::Event::Failure.for(exception).emit(self)
+		# ```
 		class Failure < Generic
-			def self.current_working_directory
+			def self.default_root
 				Dir.getwd
 			rescue # e.g. Errno::EMFILE
 				nil
 			end
 
 			def self.for(exception)
-				self.new(exception, self.current_working_directory)
+				self.new(exception, self.default_root)
 			end
 
-			def initialize(exception, root = nil)
+			def self.log(subject, exception, **options)
+				Console.error(subject, **self.for(exception).to_hash, **options)
+			end
+
+			def initialize(exception, root = Dir.getwd)
 				@exception = exception
 				@root = root
 			end
 
-			attr :exception
-			attr :root
-
-			def self.register(terminal)
-				terminal[:exception_title] ||= terminal.style(:red, nil, :bold)
-				terminal[:exception_detail] ||= terminal.style(:yellow)
-				terminal[:exception_backtrace] ||= terminal.style(:red)
-				terminal[:exception_backtrace_other] ||= terminal.style(:red, nil, :faint)
-				terminal[:exception_message] ||= terminal.style(:default)
+			def to_hash
+				Hash.new.tap do |hash|
+					hash[:type] = :failure
+					hash[:root] = @root if @root
+					extract(@exception, hash)
+				end
 			end
 
-			def to_h
-				{exception: @exception, root: @root}
+			def emit(*arguments, **options)
+				options[:severity] ||= :error
+
+				super
 			end
 
-			def format(output, terminal, verbose)
-				format_exception(@exception, nil, output, terminal, verbose)
-			end
+			private
 
-			if Exception.method_defined?(:detailed_message)
-				def detailed_message(exception)
-					exception.detailed_message
-				end
-			else
-				def detailed_message(exception)
-					exception.message
-				end
-			end
-
-			def format_exception(exception, prefix, output, terminal, verbose)
-				lines = detailed_message(exception).lines.map(&:chomp)
-
-				output.puts "  #{prefix}#{terminal[:exception_title]}#{exception.class}#{terminal.reset}: #{lines.shift}"
-
-				lines.each do |line|
-					output.puts "  #{terminal[:exception_detail]}#{line}#{terminal.reset}"
-				end
+			def extract(exception, hash)
+				hash[:class] = exception.class.name
 
-				root_pattern = /^#{@root}\// if @root
-
-				exception.backtrace&.each_with_index do |line, index|
-					path, offset, message = line.split(":", 3)
-					style = :exception_backtrace
+				if exception.respond_to?(:detailed_message)
+					message = exception.detailed_message
 
-					# Make the path a bit more readable
-					if root_pattern and path.sub!(root_pattern, "").nil?
-						style = :exception_backtrace_other
-					end
+					# We want to remove the trailling exception class as we format it differently:
+					message.sub!(/\s*\(.*?\)$/, '')
 
-					output.puts "  #{index == 0 ? "→" : " "} #{terminal[style]}#{path}:#{offset}#{terminal[:exception_message]} #{message}#{terminal.reset}"
+					hash[:message] = message
+				else
+					hash[:message] = exception.message
 				end
 
-				if exception.cause
-					format_exception(exception.cause, "Caused by ", output, terminal, verbose)
+				hash[:backtrace] = exception.backtrace
+
+				if cause = exception.cause
+					hash[:cause] = Hash.new.tap do |cause_hash|
+						extract(cause, cause_hash)
+					end
 				end
 			end
 		end