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| ... } ⇒ 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.

Yield Returns:

  • (void) 


187
188
189
 
# File 'lib/sord/logging.rb', line 187

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

.done(msg, item = nil, **opts) ⇒ 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.



162
163
164
 
# File 'lib/sord/logging.rb', line 162

def self.done(msg, item = nil, **opts)
  generic(:done, Rainbow('[DONE ]').green, msg, item, **opts)
end

.duck(msg, item = nil, **opts) ⇒ 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.



116
117
118
 
# File 'lib/sord/logging.rb', line 116

def self.duck(msg, item = nil, **opts)
  generic(:duck, Rainbow('[DUCK ]').cyan, msg, item, **opts)
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) 


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

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


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

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

.error(msg, item = nil, **opts) ⇒ 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.



127
128
129
 
# File 'lib/sord/logging.rb', line 127

def self.error(msg, item = nil, **opts)
  generic(:error, Rainbow('[ERROR]').red, msg, item, **opts)
end

.generic(kind, header, msg, item, **opts) ⇒ 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.



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

def self.generic(kind, header, msg, item, **opts)
  return unless enabled_types.include?(kind)

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

  invoke_hooks(kind, msg, item, **opts)
end

.hooks ⇒ Array<Proc>

Returns The hooks registered on the logger.

Returns:

  • (Array<Proc>) —

    The hooks registered on the logger.



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

def self.hooks
  @@hooks
end

.infer(msg, item = nil, **opts) ⇒ 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.



139
140
141
 
# File 'lib/sord/logging.rb', line 139

def self.infer(msg, item = nil, **opts)
  generic(:infer, Rainbow('[INFER]').blue, msg, item, **opts)
end

.info(msg, item = nil, **opts) ⇒ 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.



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

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

.invoke_hooks(kind, msg, item, **opts) ⇒ 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.



173
174
175
176
177
 
# File 'lib/sord/logging.rb', line 173

def self.invoke_hooks(kind, msg, item, **opts)
  @@hooks.each do |hook|
    hook.(kind, msg, item, **opts)
  end
end

.omit(msg, item = nil, **opts) ⇒ 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.



151
152
153
 
# File 'lib/sord/logging.rb', line 151

def self.omit(msg, item = nil, **opts)
  generic(:omit, Rainbow('[OMIT ]').magenta, msg, item, **opts)
end

.silent=(value) ⇒ void

This method returns an undefined value.

Sets whether log messages should be printed or not.

Parameters:

  • value (Boolean) 


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

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.



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

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


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

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

.warn(msg, item = nil, **opts) ⇒ 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.



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

def self.warn(msg, item = nil, **opts)
  generic(:warn, Rainbow('[WARN ]').yellow, msg, item, **opts)
end