Module: Sord::Logging

Defined in:
lib/sord/logging.rb

Overview

Handles writing logs to stdout and any other classes which request them.

Constant Summary collapse

AVAILABLE_TYPES =

An array of all available logging types.

[:warn, :info, :duck, :error, :infer, :omit, :done].freeze
@@hooks =

This is an Array of callables which are all executed upon a log message. The callables should take three parameters: (kind, msg, item).

[]
@@silent =

Whether log messages should be printed or not.

false
@@enabled_types = 
AVAILABLE_TYPES

Class Method Summary collapse

Class Method Details

.add_hook {|kind, msg, item, indent_level| ... } ⇒ void

This method returns an undefined value.

Adds a hook to the logger.

Yield Parameters:

  • kind (Symbol) —

    The kind of log message this is.

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) —

    The level at which to indent the code.

Yield Returns:

  • (void) 


195
196
197
 
# File 'lib/sord/logging.rb', line 195

def self.add_hook(&blk)
  @@hooks << blk
end

.done(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print a done message. This should be used when a process completes successfully.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



168
169
170
 
# File 'lib/sord/logging.rb', line 168

def self.done(msg, item = nil, indent_level = 0)
  generic(:done, '[DONE ]'.green, msg, item)
end

.duck(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print a duck-typing message. This should be used when the YARD documentation contains duck typing, which isn’t supported by Sorbet, so it is substituted for something different.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



118
119
120
 
# File 'lib/sord/logging.rb', line 118

def self.duck(msg, item = nil, indent_level = 0)
  generic(:duck, '[DUCK ]'.cyan, msg, item, indent_level)
end

.enabled_types ⇒ Array<Symbol>, void

Gets the array of log messages types which should be processed. Any not on this list will be discarded.

Returns:

  • (Array<Symbol>)
  • (void) 


49
50
51
 
# File 'lib/sord/logging.rb', line 49

def self.enabled_types
  @@enabled_types
end

.enabled_types=(value) ⇒ void

This method returns an undefined value.

Sets the array of log messages types which should be processed. Any not on this list will be discarded. This should be a subset of AVAILABLE_TYPES.

Parameters:

  • value (Array<Symbol>) 


40
41
42
43
 
# File 'lib/sord/logging.rb', line 40

def self.enabled_types=(value)
  raise 'invalid types' unless valid_types?(value)
  @@enabled_types = value
end

.error(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print an error message. This should be used for things which require the current process to stop.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



130
131
132
 
# File 'lib/sord/logging.rb', line 130

def self.error(msg, item = nil, indent_level = 0)
  generic(:error, '[ERROR]'.red, msg, item, indent_level)
end

.generic(kind, header, msg, item, indent_level = 0) ⇒ void

This method returns an undefined value.

A generic log message writer which is called by all other specific logging methods. This shouldn’t be called outside of the Logging class itself.

Parameters:

  • kind (Symbol) —

    The kind of log message this is.

  • header (String) —

    The prefix for this log message. For consistency, it should be up to five uppercase characters wrapped in square brackets, with some unique colour applied.

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/sord/logging.rb', line 73

def self.generic(kind, header, msg, item, indent_level = 0)
  return unless enabled_types.include?(kind)

  if item
    puts "#{header} (#{item.path.bold}) #{msg}" unless silent?
  else
    puts "#{header} #{msg}" unless silent?
  end

  invoke_hooks(kind, msg, item, indent_level)
end

.hooks ⇒ Array<Proc>

Returns The hooks registered on the logger.

Returns:

  • (Array<Proc>) —

    The hooks registered on the logger.



11
12
13
 
# File 'lib/sord/logging.rb', line 11

def self.hooks
  @@hooks
end

.infer(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print an infer message. This should be used when the user should be told that some information has been filled in or guessed for them, and that information is likely correct.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



143
144
145
 
# File 'lib/sord/logging.rb', line 143

def self.infer(msg, item = nil, indent_level = 0)
  generic(:infer, '[INFER]'.light_blue, msg, item, indent_level)
end

.info(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print an info message. This should be used for generic informational messages which the user doesn’t need to act on.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



105
106
107
 
# File 'lib/sord/logging.rb', line 105

def self.info(msg, item = nil, indent_level = 0)
  generic(:info, '[INFO ]', msg, item, indent_level)
end

.invoke_hooks(kind, msg, item, indent_level = 0) ⇒ void

This method returns an undefined value.

Invokes all registered hooks on the logger.

Parameters:

  • kind (Symbol) —

    The kind of log message this is.

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



180
181
182
183
184
 
# File 'lib/sord/logging.rb', line 180

def self.invoke_hooks(kind, msg, item, indent_level = 0)
  @@hooks.each do |hook|
    hook.(kind, msg, item, indent_level) rescue nil
  end
end

.omit(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print an omit message. This should be used as a special type of warning to alert the user that there is some information missing, but this information is not critical to the completion of the process.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



156
157
158
 
# File 'lib/sord/logging.rb', line 156

def self.omit(msg, item = nil, indent_level = 0)
  generic(:omit, '[OMIT ]'.magenta, msg, item, indent_level)
end

.silent=(value) ⇒ void

This method returns an undefined value.

Sets whether log messages should be printed or not.

Parameters:

  • value (Boolean) 


27
28
29
 
# File 'lib/sord/logging.rb', line 27

def self.silent=(value)
  @@silent = value
end

.silent? ⇒ Boolean

Returns Whether log messages should be printed or not. This is used for testing.

Returns:

  • (Boolean) —

    Whether log messages should be printed or not. This is used for testing.



20
21
22
 
# File 'lib/sord/logging.rb', line 20

def self.silent?
  @@silent
end

.valid_types?(value) ⇒ void

This method returns an undefined value.

Returns a boolean indicating whether a given array is a valid value for #enabled_types.

Parameters:

  • value (Array<Symbol>) 


57
58
59
 
# File 'lib/sord/logging.rb', line 57

def self.valid_types?(value)
  (value - AVAILABLE_TYPES).empty?
end

.warn(msg, item = nil, indent_level = 0) ⇒ void

This method returns an undefined value.

Print a warning message. This should be used for things which require the user’s attention but do not prevent the process from stopping.

Parameters:

  • msg (String) —

    The log message to write.

  • item (YARD::CodeObjects::Base) (defaults to: nil) —

    The CodeObject which this log is associated with, if any. This is shown before the log message if it is specified.

  • indent_level (Integer) (defaults to: 0) —

    The level at which to indent the code.



93
94
95
 
# File 'lib/sord/logging.rb', line 93

def self.warn(msg, item = nil, indent_level = 0)
  generic(:warn, '[WARN ]'.yellow, msg, item, indent_level)
end