console 0.5 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6d335e8b78f82a73be6a3cf6ab279594277fe4fd492d82db5da34695643219e
+  data.tar.gz: 22dd7d9b66f54a1bd38e563158d5ff58148e9f744d06a4d391ef8ae01676bb9d
+SHA512:
+  metadata.gz: 9c4947d01b98cf603d14444be28815d4e7b6d3e3b7627be3b6f1d4d4d56f97702e7b61827c7c966533d696b73b9a0138b5a74fb2388fec645b5619b2e741ad2e
+  data.tar.gz: 8ecfe1ee0c30bc99b2662f6095defde0e99c8594a8a49b9c513f14914b80f84c9bc7ee7e13064097ac225a2f9a7a132ebae6b8f31c610cecd4c58e4cbfb77cf7

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+dist: xenial
+cache: bundler
+
+matrix:
+  include:
+    - rvm: 2.3
+    - rvm: 2.4
+    - rvm: 2.5
+    - rvm: 2.6
+    - rvm: 2.6
+      env: COVERAGE=BriefSummary,Coveralls
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - rvm: truffleruby

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in console.gemspec
+gemspec
+
+gem "pry"

data/README.md

@@ -0,0 +1,165 @@
+# Console
+
+Provides beautiful console logging for Ruby applications. Implements fast, buffered log output.
+
+[![Build Status](https://travis-ci.com/socketry/console.svg)](http://travis-ci.com/socketry/console)
+[![Coverage Status](https://coveralls.io/repos/socketry/console/badge.svg)](https://coveralls.io/r/socketry/console)
+
+## Motivation
+
+When Ruby decided to reverse the order of exception backtraces, I finally gave up using the built in logging and decided restore sanity to the output of my programs once and for all!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'console'
+```
+
+And then execute:
+
+	$ bundle
+
+## Usage
+
+As your code executes, it generates interesting events which you want to know about. The general approach is to use an `Console::Logger` which outputs text to the terminal. The text is generated by inspecting the console that occurred.
+
+Capturing structured information allows it to be used in different ways. These events can be sent to a logger or some other system (e.g. web browser, syslog) and analysed in more detail.
+
+### Default Logger
+
+Generally speaking, use `Console.logger` which is suitable for logging to the user's terminal.
+
+### Module Integration
+
+```ruby
+require 'console'
+
+# Set the log level:
+Console.logger.debug!
+
+module MyModule
+	extend Console
+	
+	def self.test_logger
+		logger.debug "GOTO LINE 1."
+		logger.info "5 things your doctor won't tell you!"
+		logger.warn "Something didn't work as expected!"
+		logger.error "The matrix has two cats!"
+	end
+	
+	test_logger
+end
+```
+
+### Class Integration
+
+```ruby
+require 'console'
+
+# Set the log level:
+Console.logger.debug!
+
+class MyObject
+	include Console
+
+	def test_logger
+		logger.debug "GOTO LINE 1."
+		logger.info "5 things your doctor won't tell you!"
+		logger.warn "Something didn't work as expected!"
+		logger.error "The matrix has two cats!"
+	end
+end
+
+MyObject.new.test_logger
+```
+
+### Console Formatting
+
+Console classes are used to wrap data which can generate structured log messages:
+
+```ruby
+require 'console'
+
+class MyConsole < Console::Generic
+	def format(output, terminal, verbose)
+		output.puts "My console text!"
+	end
+end
+
+Console.logger.info("My Console", MyConsole.new)
+```
+
+#### Error Events
+
+`Console::Error` represents an error and will log the message and backtrace recursively.
+
+#### Shell Events
+
+`Console::Shell` represents the execution of a shell command, and will log the environment, arguments and options used to execute it.
+
+### Multiple Loggers
+
+### Custom Log Levels
+
+`Console::Filter` implements support for multiple log levels.
+
+```ruby
+require 'console'
+
+MyLogger = Console::Filter[noise: 0, stuff: 1, broken: 2]
+
+logger = MyLogger.new(Console.logger, name: "Java")
+logger.verbose! # log severity/name/pid etc.
+
+logger.broken("It's so janky.")
+```
+
+### Multiple Outputs
+
+```ruby
+require 'console/terminal'
+require 'console/serialized/logger'
+require 'console/logger'
+require 'console/split'
+
+terminal = Console::Terminal::Logger.new
+file = Console::Serialized::Logger.new(File.open("/tmp/log.json", "w"))
+
+logger = Console::Logger.new(Console::Split[terminal, file])
+
+logger.info "I can go everywhere!"
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Released under the MIT license.
+
+Copyright, 2019, by [Samuel Williams](https://www.codeotaku.com).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+task :console do
+	require 'pry'
+	require 'console'
+	
+	binding.pry
+end

data/console.gemspec

@@ -0,0 +1,24 @@
+
+require_relative "lib/console/version"
+
+Gem::Specification.new do |spec|
+	spec.name = "console"
+	spec.version = Console::VERSION
+	spec.authors = ["Samuel Williams"]
+	spec.email = ["samuel.williams@oriontransfer.co.nz"]
+	
+	spec.summary = "Beautiful logging for Ruby."
+	spec.homepage = "https://github.com/socketry/console"
+	
+	spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+	end
+	
+	spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+	spec.require_paths = ["lib"]
+	
+	spec.add_development_dependency "covered"
+	spec.add_development_dependency "bundler"
+	spec.add_development_dependency "rake", "~> 10.0"
+	spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/console.rb

@@ -0,0 +1,65 @@
+# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'console/logger'
+require_relative 'console/terminal/logger'
+
+module Console
+	class << self
+		attr_accessor :logger
+		
+		LEVELS = {
+			'debug' => Logger::DEBUG,
+			'info' => Logger::INFO,
+		}
+		
+		# Set the default log level based on `$DEBUG` and `$VERBOSE`.
+		# You can also specify CONSOLE_LOG_LEVEL=debug or CONSOLE_LOG_LEVEL=info in environment.
+		def default_log_level(env = ENV)
+			if level = env['CONSOLE_LOG_LEVEL']
+				LEVELS[level] || Logger.warn
+			elsif $DEBUG
+				Logger::DEBUG
+			elsif $VERBOSE
+				Logger::INFO
+			else
+				Logger::WARN
+			end
+		end
+	end
+	
+	# Create the logger instance:
+	@logger = Logger.new(
+		Terminal::Logger.new($stderr),
+		level: self.default_log_level,
+	)
+	
+	def logger= logger
+		@logger = logger
+	end
+	
+	def logger
+		@logger || Console.logger
+	end
+	
+	def self.extended(klass)
+		klass.instance_variable_set(:@logger, nil)
+	end
+end

data/lib/console/buffer.rb

@@ -0,0 +1,40 @@
+# Copyright, 2017, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'stringio'
+
+module Console
+	class Buffer < StringIO
+		def initialize(prefix = nil)
+			@prefix = prefix
+			
+			super()
+		end
+		
+		def puts(*args, prefix: @prefix)
+			args.each do |arg|
+				self.write(prefix) if prefix
+				super(arg)
+			end
+		end
+		
+		alias << puts
+	end
+end

data/lib/console/capture.rb

@@ -0,0 +1,66 @@
+# Copyright, 2017, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'filter'
+
+module Console
+	class Capture
+		def initialize
+			@events = []
+		end
+		
+		attr :events
+		
+		def last
+			@events.last
+		end
+		
+		def verbose!(value = true)
+		end
+		
+		def call(subject = nil, *arguments, severity: UNKNOWN, **options, &block)
+			message = {
+				time: Time.now.iso8601,
+				severity: severity,
+				**options,
+			}
+			
+			if subject
+				message[:subject] = subject
+			end
+			
+			if arguments.any?
+				message[:arguments] = arguments
+			end
+			
+			if block_given?
+				if block.arity.zero?
+					message[:message] = yield
+				else
+					buffer = StringIO.new
+					yield buffer
+					message[:message] = buffer.string
+				end
+			end
+			
+			@events << message
+		end
+	end
+end

data/lib/console/error.rb

@@ -0,0 +1,76 @@
+# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'generic'
+
+module Console
+	class Error < Generic
+		def self.current_working_directory
+			Dir.getwd
+		rescue # e.g. Errno::EMFILE
+			nil
+		end
+		
+		def self.for(exception)
+			self.new(exception, self.current_working_directory)
+		end
+		
+		def initialize(exception, root = nil)
+			@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)
+		end
+		
+		def format(output, terminal, verbose)
+			format_exception(@exception, nil, output, terminal, verbose)
+		end
+		
+		def format_exception(exception, prefix = nil, output, terminal, verbose)
+			lines = exception.message.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
+			
+			exception.backtrace&.each_with_index do |line, index|
+				path, offset, message = line.split(":")
+				
+				# Make the path a bit more readable
+				path.gsub!(/^#{@root}\//, "./") if @root
+				
+				output.puts "  #{index == 0 ? "→" : " "} #{terminal[:exception_backtrace]}#{path}:#{offset}#{terminal.reset} #{message}"
+			end
+			
+			if exception.cause and verbose
+				format_exception(exception.cause, "Caused by ", output, terminal)
+			end
+		end
+	end
+end