Module: Loba

Defined in:
lib/loba.rb,
lib/loba/error.rb,
lib/loba/value.rb,
lib/loba/version.rb,
lib/loba/internal.rb,
lib/loba/timestamp.rb,
lib/loba/internal/value.rb,
lib/loba/internal/platform.rb,
lib/loba/internal/settings.rb,
lib/loba/internal/time_keeper.rb,
lib/loba/internal/platform/formatter.rb,
lib/loba/internal/value/value_helper.rb,
lib/loba/internal/platform/within_rails.rb

Overview

rubocop:disable Style/Documentation

Defined Under Namespace

Modules: Internal Classes: Error, InvalidLogdevOptionError, InvalidLoggerOptionError, InvalidOutOptionError

Constant Summary collapse

VERSION =

Semantic version number

'2.1.0'.freeze

Class Method Summary collapse

Class Method Details

.timestamp(production: false, log: false, logger: nil, logdev: nil, out: true) ⇒ NilClass

Note:

To avoid doubled output, if a non-Rails logger is to be logged to and logdev is set to $stdout, then output will be suppressed (i.e., settings.out is false). Doubled output can still occur; in that case, explicitly use out: false.

Outputs a timestamped notice, useful for quick traces to see the code path. Also does a simple elapsed time check since the previous timestamp notice to help with quick, minimalist profiling.

Examples:

Basic use

def hello
  Loba.timestamp
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'

Forced to output when in production environment

def hello
  Loba.ts production: true # Loba.ts is a shorthand alias for Loba.timestamp
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'

Forced to output to log in addition to $stdout

def hello
  Loba.timestamp log: true
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/loba/timestamp.rb', line 38

def timestamp( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
  production: false,
  log: false,
  logger: nil,
  logdev: nil,
  out: true
)
  settings = Internal::Settings.new(
    log: log, logger: logger, logdev: logdev, out: out, production: production
  )

  return unless settings.enabled?

  # NOTE: while tempting, memoizing loba_logger can lead to surprises if
  #   Rails presence isn't constant
  writer = Internal::Platform.writer(settings: settings)

  begin
    stats = Internal::TimeKeeper.instance.ping
    writer.call(
      # 60: light_black / grey
      "#{Rainbow('[TIMESTAMP]').black.bg(60)}" \
      "#{Rainbow(' #=').yellow.bg(:default)}" \
      "#{format('%04d', stats[:number])}" \
      "#{Rainbow(', diff=').yellow}" \
      "#{format('%.6f', stats[:change])}" \
      "#{Rainbow(', at=').yellow}" \
      "#{format('%.6f', stats[:now].round(6).to_f)}" \
      "#{Rainbow("    \t(in #{caller(1..1).first})").color(60)}" # warning: nested interpolation
    )
  rescue StandardError => e
    writer.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
  end

  nil
end

.ts(production: false, log: false, logger: nil, logdev: nil, out: true) ⇒ NilClass

Note:

To avoid doubled output, if a non-Rails logger is to be logged to and logdev is set to $stdout, then output will be suppressed (i.e., settings.out is false). Doubled output can still occur; in that case, explicitly use out: false.

Outputs a timestamped notice, useful for quick traces to see the code path. Also does a simple elapsed time check since the previous timestamp notice to help with quick, minimalist profiling. Shorthand alias for Loba.timestamp.

Examples:

Basic use

def hello
  Loba.timestamp
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'

Forced to output when in production environment

def hello
  Loba.ts production: true # Loba.ts is a shorthand alias for Loba.timestamp
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'

Forced to output to log in addition to $stdout

def hello
  Loba.timestamp log: true
end
#=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/loba/timestamp.rb', line 78

def timestamp( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
  production: false,
  log: false,
  logger: nil,
  logdev: nil,
  out: true
)
  settings = Internal::Settings.new(
    log: log, logger: logger, logdev: logdev, out: out, production: production
  )

  return unless settings.enabled?

  # NOTE: while tempting, memoizing loba_logger can lead to surprises if
  #   Rails presence isn't constant
  writer = Internal::Platform.writer(settings: settings)

  begin
    stats = Internal::TimeKeeper.instance.ping
    writer.call(
      # 60: light_black / grey
      "#{Rainbow('[TIMESTAMP]').black.bg(60)}" \
      "#{Rainbow(' #=').yellow.bg(:default)}" \
      "#{format('%04d', stats[:number])}" \
      "#{Rainbow(', diff=').yellow}" \
      "#{format('%.6f', stats[:change])}" \
      "#{Rainbow(', at=').yellow}" \
      "#{format('%.6f', stats[:now].round(6).to_f)}" \
      "#{Rainbow("    \t(in #{caller(1..1).first})").color(60)}" # warning: nested interpolation
    )
  rescue StandardError => e
    writer.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
  end

  nil
end

.val(argument, label: nil, inspect: true, production: false, log: false, logger: nil, logdev: nil, out: true) ⇒ NilClass

Note:

To avoid doubled output, if a non-Rails logger is to be logged to and logdev is set to $stdout, then output will be suppressed (i.e., settings.out is false). Doubled output can still occur; in that case, explicitly use out: false.

Outputs a value notice showing value of provided argument including method and class identification. rubocop:disable Layout/LineLength Shorthand alias for Loba.value.

Examples:

Using Symbol as argument

class HelloWorld
  def hello(name)
Loba.value :name # putting Loba statement to far left helps remember to remove later
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!

Using non-Symbol as argument

class HelloWorld
  def hello(name)
Loba.val name # Loba.val is a shorthand alias for Loba.value
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!

Using non-Symbol as argument with a label

class HelloWorld
  def hello(name)
Loba.value name, "Name:"
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] Name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/loba/value.rb', line 101

def value( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
  argument,
  label: nil,
  inspect: true,
  production: false,
  log: false,
  logger: nil,
  logdev: nil,
  out: true
)
  settings = Internal::Settings.new(
    log: log, logger: logger, logdev: logdev, out: out, production: production
  )

  return unless settings.enabled?

  text = Internal::Value.phrases(
    argument: (argument.nil? ? :nil : argument),
    label: label,
    inspect: inspect,
    depth_offset: 1
  )

  Internal::Platform.writer(settings: settings).call(
    # NOTE: while tempting, memoizing Internal::Platform.logger can lead to surprises
    #   if Rails presence isn't constant
    #
    # warning: nested interpolation below (slight help to performance)
    # 60: light_black
    # 62: light_green
    "#{Rainbow("#{text[:tag]} ").green.bg(:default)}" \
    "#{Rainbow("#{text[:label]} ").color(62)}" \
    "#{text[:value]}" \
    "#{Rainbow("    \t(in #{text[:line]})").color(60)}"
  )

  nil
end

.value(argument, label: nil, inspect: true, production: false, log: false, logger: nil, logdev: nil, out: true) ⇒ NilClass

Note:

To avoid doubled output, if a non-Rails logger is to be logged to and logdev is set to $stdout, then output will be suppressed (i.e., settings.out is false). Doubled output can still occur; in that case, explicitly use out: false.

Outputs a value notice showing value of provided argument including method and class identification.

Examples:

Using Symbol as argument

class HelloWorld
  def hello(name)
Loba.value :name # putting Loba statement to far left helps remember to remove later
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!

Using non-Symbol as argument

class HelloWorld
  def hello(name)
Loba.val name # Loba.val is a shorthand alias for Loba.value
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!

Using non-Symbol as argument with a label

class HelloWorld
  def hello(name)
Loba.value name, "Name:"
    puts "Hello, #{name}!"
  end
end
HelloWorld.new.hello("Charlie")
#=> [HelloWorld#hello] Name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
#=> Hello, Charlie!



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/loba/value.rb', line 58

def value( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
  argument,
  label: nil,
  inspect: true,
  production: false,
  log: false,
  logger: nil,
  logdev: nil,
  out: true
)
  settings = Internal::Settings.new(
    log: log, logger: logger, logdev: logdev, out: out, production: production
  )

  return unless settings.enabled?

  text = Internal::Value.phrases(
    argument: (argument.nil? ? :nil : argument),
    label: label,
    inspect: inspect,
    depth_offset: 1
  )

  Internal::Platform.writer(settings: settings).call(
    # NOTE: while tempting, memoizing Internal::Platform.logger can lead to surprises
    #   if Rails presence isn't constant
    #
    # warning: nested interpolation below (slight help to performance)
    # 60: light_black
    # 62: light_green
    "#{Rainbow("#{text[:tag]} ").green.bg(:default)}" \
    "#{Rainbow("#{text[:label]} ").color(62)}" \
    "#{text[:value]}" \
    "#{Rainbow("    \t(in #{text[:line]})").color(60)}"
  )

  nil
end