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

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

Class Method Summary collapse

Class Method Details

.add_hook {|kind, msg, item| ... } ⇒ Object

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) 


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

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

.done(msg, item = nil) ⇒ Object

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

Parameters:

  • 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.done(msg, item=nil)
  generic(:done, '[DONE ]'.green, msg, item)
end

.error(msg, item = nil) ⇒ Object

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.



62
63
64
 
# File 'lib/sord/logging.rb', line 62

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

.generic(kind, header, msg, item) ⇒ Object

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.



36
37
38
39
40
41
42
43
44
 
# File 'lib/sord/logging.rb', line 36

def self.generic(kind, header, msg, item)
  if item
    puts "#{header} (#{item.path.light_white}) #{msg}" unless silent?
  else
    puts "#{header} #{msg}" unless silent?
  end

  invoke_hooks(kind, msg, item)
end

.infer(msg, item = nil) ⇒ Object

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.



73
74
75
 
# File 'lib/sord/logging.rb', line 73

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

.invoke_hooks(kind, msg, item) ⇒ Object

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.



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

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

.omit(msg, item = nil) ⇒ Object

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.



84
85
86
 
# File 'lib/sord/logging.rb', line 84

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

.silent=(value) ⇒ void

This method returns an undefined value.

Sets whether log messages should be printed or not.

Parameters:

  • value (Boolean) 


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

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.



15
16
17
 
# File 'lib/sord/logging.rb', line 15

def self.silent?
  @@silent
end

.warn(msg, item = nil) ⇒ Object

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.



52
53
54
 
# File 'lib/sord/logging.rb', line 52

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