cogger 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2ff34be63a6d20792b0dad16762afaf0f03226964b2a83ed08194fef2f37a75
-  data.tar.gz: 5fce7ffb39529c8d4c29f10a03d29e3173219f0365428fa10d003501c38a2553
+  metadata.gz: 3226b0b30d4c6a4eba83e9aec637de1938ac852f8a7e1bbd3b4a07d501d67920
+  data.tar.gz: 4e00980079107adbb150c4b03f7d80f63ede92fe6fbbb628642d532dc9d82e9b
 SHA512:
-  metadata.gz: a8d82b63e521610dda3906c998e8533ad6f82920f1294dedc10a8acba2ec63084213c3ab80f37ae50525f83928d628ea7a94a37fd52c9abbb63a7da54cc619c7
-  data.tar.gz: 57e01b5b658f64abc8581a98e95cbb6b6794a787e7b244d79d3aa61f21d157252b19a53a84cbc3e0d18c3058250063d555d5fa133f8ddec67a12fca203657be5
+  metadata.gz: cf70a4540105ad59bc4237c9d654e2db5191eeb00b504391a465957b28d7d2fbb7c418969d30762fc8fe0f57ea97893be8980432ab7c2bd0b5643f9fea81ec02
+  data.tar.gz: d731085187625db4b92c45cc30eaff79c763d47c9e169d3e24a672627f9e2d144b40e4cd49074ce5afb47d05aa1e43c9cd29c0f2c97494d6f91d35e860a8e799

data/README.adoc

@@ -1,24 +1,32 @@
-:pastel_link: link:https://github.com/piotrmurach/pastel[Pastel]
-
 :toc: macro
 :toclevels: 5
 :figure-caption!:
 
+:tone_link: link:https://alchemists.io/projects/tone[Tone]
+:logger_link: link:https://rubyapi.org/o/s?q=Logger[Logger]
+:format_link: link:https://ruby-doc.org/3.2.1/format_specifications_rdoc.html[Format Specification]
+:pattern_matching_link: link:https://alchemists.io/articles/ruby_pattern_matching[pattern matching]
+:refinements_link: link:https://alchemists.io/projects/refinements[Refinements]
+
 = Cogger
 
-Cogger is a portmanteau for colorized logging (i.e. `[c]olorized + l[ogger] = cogger`) which
-decorates Ruby's native logger with colorized output.
+Cogger is a portmanteau for custom logging (i.e. `[c]ustom + l[ogger] = cogger`) which enhances Ruby's native {logger_link} functionality with additional features such as dynamic emojis, colorized text, structured JSON, multiple outputs, and much more. 🚀
 
 toc::[]
 
 == Features
 
-- Decorates Ruby's default `Logger`.
-- Uses color decoration as provided by the {pastel_link} gem.
+* Enhances Ruby's default {logger_link} with additional functionality and firepower.
+* Provides dynamic/specific emoji output.
+* Provides dynamic/specific colorized output via the {tone_link} gem.
+* Provides customizable templates which leverage the native {format_link}.
+* Provides customizable formatters for simple, color, JSON, and/or custom output.
+* Provides multiple streams so you can log the same information to several outputs at once.
+* Provides filtering of sensitive information.
 
 == Screenshot
 
-image::https://alchemists.io/images/projects/cogger/screenshots/console.png[Console,width=552,height=679,role=focal_point]
+image::https://alchemists.io/images/projects/cogger/screenshots/console.png[Console,width=1139,height=211,role=focal_point]
 
 == Requirements
 
@@ -26,98 +34,109 @@ image::https://alchemists.io/images/projects/cogger/screenshots/console.png[Cons
 
 == Setup
 
-To set up the project, run:
+To install _with_ security, run:
 
 [source,bash]
 ----
-bin/setup
+# 💡 Skip this line if you already have the public certificate installed.
+gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
+gem install cogger --trust-policy HighSecurity
 ----
 
-== Usage
-
-All colorized logging is provided by `Cogger` which can be used as follows:
+To install _without_ security, run:
 
-[source,ruby]
+[source,bash]
 ----
-logger = Cogger.init
-
-logger.debug "test"        # true
-logger.debug { "test" }    # true
-logger.info "test"         # true
-logger.info { "test" }     # true
-logger.warn "test"         # true
-logger.warn { "test" }     # true
-logger.error "test"        # true
-logger.error { "test" }    # true
-logger.fatal "test"        # true
-logger.fatal { "test" }    # true
-logger.unknown "test"      # true
-logger.unknown { "test" }  # true
-logger.any "test"          # true
-logger.any { "test" }      # true
+gem install cogger
 ----
 
-By default, all logging is configured to use `INFO` level and writes to `$stdout`. To see what the
-colorized output from the above looks like, please see the screenshot shown in the _Screenshots_
-section as documented earlier.
-
-Beyond the standard log level methods, the following methods are also available:
+You can also add the gem directly to your project:
 
-[source,ruby]
+[source,bash]
 ----
-logger = Cogger.init
-
-logger.formatter  # #<Proc:0x000000010626ebc8 $HOME/OSS/cogger/lib/cogger/client.rb:37 (lambda)>
-logger.level      # 1
-logger.progname   # nil
+bundle add cogger
 ----
 
-=== Customization
+Once the gem is installed, you only need to require it:
 
-Customization of the logger differs, slightly, from what you'd get with the standard `Logger` class.
-The following sections will explain what these differences look like.
+[source,ruby]
+----
+require "cogger"
+----
 
-==== Initialization
+== Usage
 
-For starters, the first argument is a positional argument that defaults to `Logger.new($stdout)` but
-you could swap out the default logger with something that logs to a string. For example:
+All interaction is provided by `Cogger` which can be used as follows:
 
 [source,ruby]
 ----
-logger = Cogger.init Logger.new(StringIO.new)
+logger = Cogger.new
+logger.info "demo"   # "demo"
 ----
 
-You can also create a logger which might use custom colors. Example:
+If you set your logging level to `debug`, you can walk through each level:
 
 [source,ruby]
 ----
-logger = Cogger.init color: MyColor.new
+logger = Cogger.new level: :debug
+
+# Without blocks.
+logger.debug "demo"        # "demo"
+logger.info "demo"         # "demo"
+logger.warn "demo"         # "demo"
+logger.error "demo"        # "demo"
+logger.fatal "demo"        # "demo"
+logger.unknown "demo"      # "demo"
+logger.any "demo"          # "demo"
+
+# With blocks.
+logger.debug { "demo" }    # "demo"
+logger.info { "demo" }     # "demo"
+logger.warn { "demo" }     # "demo"
+logger.error { "demo" }    # "demo"
+logger.fatal { "demo" }    # "demo"
+logger.unknown { "demo" }  # "demo"
+logger.any { "demo" }      # "demo"
 ----
 
-More information on how to customize your colors will be provided shortly. Lastly, you can provide any _setable_ attribute which would normally be used when constructing a
-normal logger. Example:
+...or, if you'd like to display all severities at once, use:
 
 [source,ruby]
 ----
-logger = Cogger.init formatter: ->(severity, _at, _name, message) { "#{message}\n" },
-                     level: :debug,
-                     progname: "Test",
-                     datetime_format: "%Y-%m-%d"
+%i[debug info warn error fatal unknown any].each { |severity| logger.public_send severity, "demo" }
 ----
 
-Alternatively, you can use a block as well:
+=== Initialization
+
+When creating a new logger, you can configure behavior via the following attributes:
+
+* `id`: The program/process ID which shows up in the logs as your `id`. Default: `$PROGRAM_NAME`. For example, if run within a `demo.rb` script, the `id` would be `"demo"`,
+* `io`: The input/output stream. This can be `STDOUT/$stdout`, a file/path, or `nil`. Default: `$stdout`.
+* `level`: The severity level you want to log at. Can be `:debug`, `:info`, `:warn`, `:error`, `:fatal`, or `:unknown`. Default: `:info`.
+* `formatter`: The formatter to use for formatting your log output. Default: `Cogger::Formatter::Color`. See the _Formatters_ section for more info.
+* `mode`: The binary mode which determines if your logs should be written in binary mode or not. Can be `true` or `false` and is identical to the `binmode` functionality found in the {logger_link} class. Default: `false`.
+* `age`: The rotation age of your log. This only applies when logging to a file. This is equivalent to the `shift_age` as found with the {logger_link} class. Default: `0`.
+* `size`: The rotation size of your log. This only applies when logging to a file. This is equivalent to the `shift_size` as found with the {logger_link} class. Default: `1,048,576` (i.e. 1 MB).
+* `suffix`: The rotation suffix. This only applies when logging to a file. This is equivalent to the `shift_period_suffix` as found with the {logger_link} class and is used when creating new rotation files. Default: `%Y-%m-%d`.
+
+Given the above description, here's how'd you create a new logger instance with all attributes:
 
 [source,ruby]
 ----
-logger = Cogger.init do |instance|
-  instance.formatter = ->(severity, _at, _name, message) { "#{message}\n" }
-  instance.level = :debug
-  instance.progname = "Test"
-  instance.datetime_format = "%Y-%m-%d"
-end
+# Default
+logger = Cogger.new
+
+# Custom
+logger = Cogger.new id: :demo,
+                    io: "demo.log",
+                    level: :debug,
+                    mode: false,
+                    age: 5,
+                    size: 1_000,
+                    suffix: "%Y"
 ----
 
-==== Environment
+=== Environment
 
 The default log level is `INFO` but can be customized via your environment. For instance, you could
 set the logging level to any of the following:
@@ -130,55 +149,379 @@ export LOG_LEVEL=WARN
 export LOG_LEVEL=ERROR
 export LOG_LEVEL=FATAL
 export LOG_LEVEL=UNKNOWN
-export LOG_LEVEL=ANY
 ----
 
-By default, `Cogger::Client` will automatically use whatever is set via the `LOG_LEVEL` environment
-variable unless overwritten during initialization.
+By default, `Cogger` will automatically use whatever is set via the `LOG_LEVEL` environment variable unless overwritten during initialization.
+
+=== Templates
+
+Templates are used by all formatters and adhere to {format_link} as used by `Kernel#format`. All specifiers, flags, width, and precision are supported except for the following restrictions:
+
+- Use of _reference by name_ is required which means `%<demo>s` is allowed but `%{demo}` is not. This is because _reference by name_ is required for regular expressions and/or {pattern_matching_link}.
+- Use of the `n$` flag is prohibited because this isn't compatible with the above.
+
+In addition to the above, the {format_link} is further enhanced with the use of _universal_ and _individual_ directives which are primarily used by the _color_ formatter but might prove useful for other formatters. Example:
+
+[source,ruby]
+----
+# Universal: Dynamic (color is determined by severity)
+"<dynamic>%<severity>s %<at>s %<id>s %<message>s</dynamic>"
+
+# Universal: Specific (uses the green color only)
+"<green>%<severity>s %<at>s %<id>s %<message>s</green>"
+
+# Individual: Dynamic (color is determined by severity)
+"%<severity:dynamic>s %<at:dynamic>s %<id:dynamic>s %<message:dynamic>s"
+
+# Individual: Specific (uses a rainbow of colors)
+"%<severity:purple>s %<at:yellow>s %<id:cyan>s %<message:green>s"
+----
+
+Here's a detailed breakdown of the above:
+
+* *Universal*: Applies color universally to the _entire_ template and requires you to:
+** Wrap your entire template in a  and start (`<example>`) and end tag (`</example>`) which works much like an HTML tag in this context.
+** Your tag names must either be `<dynamic></dynamic>`, any default color (example: `<green></green>`), or alias (i.e. `<your_alias></your_alias>`) as supported by the {tone_link} gem.
+* *Individual*: Individual templates allow you to apply color to _specific_ attributes and require you to:
+** Format your attributes as `attribute:directive`. The colon delimiter is required to separate your attribute for your color choice.
+** The color value (what follows after the colon) can be `dynamic`, any default color (example: `green`), or alias (i.e. `your_alias`) as supported by the {tone_link} gem.
+
+In addition to the general categorization of universal and individual tags, each support the following directives:
+
+* *Dynamic*: A dynamic directive means that color will be determined by severity level only. This means if info level is used, the associated color (alias) for info will be applied. Same goes for warn, error, etc.
+* *Specific*: A specific directive means the color you use will be applied without any further processing regardless of the severity level. This gives you the ability to customize your colors further in situations where dynamic coloring isn't enough.
+
+At this point, you might have gathered that there are specific keys you can use for the log event metadata in your template and everything else is up to you. This stems from the fact that {logger_link} entries always have the following metadata:
+
+* `id`: This is the program/process ID you created your logger with (i.e. `Cogger.new id: :demo`).
+* `severity`: This is the severity at which you messaged your logger (i.e. `logger.info`).
+* `at`: This is the date/time as which your log event was created.
+
+This also means if you pass in these same keys as a log event (example: `logger.info id: :bad, at: Time.now, severity: :bogus`) they will be ignored.
+
+The last key (or keys) is variable and customizable to your needs which is the log event message. Here a couple of examples to illustrate:
+
+[source,ruby]
+----
+# Available as "%<message>s" in your template.
+logger.info "demo"
+
+# Available as "%<message>s" in your template.
+logger.info message: "demo"
+
+# Available as "%<verb>s" and "%<path>s" in your template.
+logger.info verb: "GET", path: "/"`
+----
+
+💡 In situations where a message hash is logged but the keys of that hash don't match the keys in the template, then an empty message will be logged. This applies to all formatters except the JSON formatter which will log any key/value that doesn't have a `nil` value.
+
+=== Emojis
+
+In addition to coloring to your log output, you can add emojis as well. Here are the defaults:
 
-==== Colorization
+[source,ruby]
+----
+Cogger.emojis
+
+# {
+#   :debug => "🔎",
+#    :info => "🟢",
+#    :warn => "⚠️ ",
+#   :error => "🛑",
+#   :fatal => "🔥"
+# }
+----
 
-Default colors are provided by the `Cogger::Color` class which are keyed by log level:
+To add an emoji, use:
 
 [source,ruby]
 ----
-{
-  debug: %i[white],
-  info: %i[green],
-  warn: %i[yellow],
-  error: %i[red],
-  fatal: %i[white bold on_red],
-  unknown: %i[white bold],
-  any: %i[white bold]
-}
+Cogger.add_emoji(:tada, "🎉")
+      .add_emoji :favorite, "❇️"
 ----
 
-All keys require an array of styles which can then be decorated by {pastel_link}. This means that if
-you wanted to use custom colors, you could create a new instance of the `Color` class and inject it
-into the client as follows:
+By default, the `:emoji` formatter provides dynamic rendering of emojis based on severity level. Example:
 
+[source,ruby]
+----
+logger = Cogger.new formatter: :emoji
+logger.info "demo"
+
+# 🟢 demo
+----
+
+If you wanted to use a specific emoji, you could use the color formatter with a specific template:
 
 [source,ruby]
 ----
-custom_color = Cogger::Color.new(
-  defaults: {
-    debug: %i[white on_black],
-    info: %i[green on_black],
-    warn: %i[yellow on_black],
-    error: %i[red on_black],
-    fatal: %i[red on_black],
-    unknown: %i[white on_black],
-    any: %i[white on_black]
-  }
-)
+logger = Cogger.new formatter: Cogger::Formatters::Color.new("%<emoji:tada>s %<message:dynamic>s")
+logger.info "demo"
 
-logger = Cogger.init color: custom_color
+# 🎉 demo
 ----
 
-The above would ensure all log level colors are displayed on a black background. Basically, any
-style accepted by `Pastel#decorate` method is supported.
+Keep in mind that using a specific, non-dynamic, emoji will _always_ display no matter the current severity level.
+
+=== Aliases
 
-==== Testing
+Aliases are specific to the {tone_link} gem which allows you _alias_ specific colors/styles via a new name. Here's how you can use them:
+
+[source,ruby]
+----
+Cogger.add_alias :haze, :bold, :white, :on_purple
+Cogger.aliases
+----
+
+The above would add a `:haze` alias which consists of bold white text on a purple background. Once added, you'd then be able to view a list of all default and custom aliases. You can also override an existing alias if you'd like something else.
+
+Aliases are a powerful way to customize your colors and use short syntax in your templates. Building upon the alias, added above, you'd be able to use it in your templates as follows:
+
+[source,ruby]
+----
+# Universal
+"<haze>%<message></haze>"
+
+# Individual
+"%<message:haze>"
+----
+
+Check out the {tone_link} documentation for further examples.
+
+=== Formatters
+
+Multiple formatters are provided for you which can be further customized as needed. Here's what is provided by default:
+
+[source,ruby]
+----
+Cogger.formatters
+
+# {
+#    :color => [
+#     Cogger::Formatters::Color < Object,
+#     nil
+#   ],
+#   :detail => [
+#     Cogger::Formatters::Simple < Object,
+#     "[%<id>s] [%<severity>s] [%<at>s] %<message>s"
+#   ],
+#    :emoji => [
+#     Cogger::Formatters::Color < Object,
+#     "%<emoji:dynamic>s% <message:dynamic>s"
+#   ],
+#     :json => [
+#     Cogger::Formatters::JSON < Object,
+#     nil
+#   ],
+#   :simple => [
+#     Cogger::Formatters::Simple < Object,
+#     nil
+#   ],
+#     :rack => [
+#     Cogger::Formatters::Simple < Object,
+#     "[%<id>s] [%<severity>s] [%<at>s] %<verb>s %<status>s %<duration>s %<ip>s %<path>s %<length>s # %<params>s"
+#   ]
+# }
+----
+
+You can add a formatter by providing a key, class, and _optional_ template. If a template isn't supplied, then the formatter's default template will be used instead (more on that shortly). Example:
+
+[source,ruby]
+----
+# Add
+Cogger.add_formatter :basic, Cogger::Formatters::Simple, "%<severity>s %<message>s"
+
+# Get
+Cogger.get_formatter :basic
+# [Cogger::Formatters::Simple, "%<severity>s %<message>s"]
+----
+
+Symbols or strings can be used interchangeably when adding/getting formatters. As mentioned above, a template doesn't have to be supplied if you want to use the formatter's default template which can be inspected as follows:
+
+[source,ruby]
+----
+Cogger::Formatters::Simple::TEMPLATE
+# "%<message>s"
+----
+
+💡 When you find yourself customizing any of the default formatters, you can reduce typing by adding your custom configuration to the registry and then referring to it via it's associated key when initializing a new logger.
+
+==== Simple
+
+The simple formatter is a bare bones formatter that uses no color information, doesn't support the universal/dynamic template syntax, and only supports the {format_link} as mentioned in the _Templates_ section earlier. This formatter can be used via the following template variations:
+
+[source,ruby]
+----
+logger = Cogger.new formatter: :detail
+logger = Cogger.new formatter: :simple
+logger = Cogger.new formatter: :rack
+----
+
+==== Color
+
+The color formatter is enabled by default and is the equivalent of initializing with either of the following:
+
+[source,ruby]
+----
+logger = Cogger.new
+logger = Cogger.new formatter: Cogger::Formatters::Color.new
+logger = Cogger.new formatter: Cogger::Formatters::Color.new("%<message:dynamic>s")
+----
+
+All three of the above examples are identical so you can start to see how different formatters can be used and customized further. Please refer back to the _Templates_ section on how to customize this formatter with more sophisticated templates.
+
+In addition to template customization, you can customize your color aliases as well. Default colors are provided by {tone_link} which are _aliased_ by log level:
+
+[source,ruby]
+----
+Cogger.aliases
+
+# {
+#   debug: :white,
+#   info: :green,
+#   warn: :yellow,
+#   error: :red,
+#   fatal: %i[bold white on_red],
+#   unknown: %i[bold white],
+#   any: %i[bold white]
+# }
+----
+
+This allows a color -- or combination of color styles (i.e. foreground + background) -- to be dynamically applied based on log severity. You can add additional aliases via:
+
+[source,ruby]
+----
+Cogger.add_alias :mystery, :white, :on_purple
+----
+
+Once an alias is added, it can be immediately applied via the template of your formatter. Example:
+
+[source,ruby]
+----
+# Applies the `mystery` alias universally to your template.
+logger = Cogger.new formatter: Cogger::Formatters::Color.new("<mystery>%<message>s</mystery>")
+----
+
+==== JSON
+
+This formatter is similar in behavior to the _simple_ formatter except the template allows you to order the layout of your keys only. All other information is ignored. To use:
+
+[source,ruby]
+----
+# Default order
+logger = Cogger.new formatter: :json
+logger.info verb: "GET", path: "/"
+
+# {"id":"console","severity":"INFO","at":"2023-04-10 09:03:55 -0600","verb":"GET","path":"/"}
+
+# Custom order
+logger = Cogger.new formatter: Cogger::Formatters::JSON.new("%<severity>s %<verb>s")
+logger.info verb: "GET", path: "/"
+
+# {"severity":"INFO","verb":"GET","id":"console","at":"2023-04-10 09:05:03 -0600","path":"/"}
+----
+
+Your template can be a full or partial match of keys. If no keys match what is defined in the template, then the original order of the keys will be used instead.
+
+==== Custom
+
+Should none of the built-in formatters be to your liking, you can implement, use, and/or register a custom formatter as well. The most minimum, bare bones, skeleton would be:
+
+[source,ruby]
+----
+class MyFormatter
+  TEMPLATE = "%<message>s"
+
+  def initialize template = TEMPLATE, sanitizer: Kit::Sanitizer.new
+    @template = template
+    @sanitizer = sanitizer
+  end
+
+  def call(*entry) = "#{format template, sanitizer.call(*entry)}\n"
+
+  private
+
+  attr_reader :template, :sanitizer
+end
+----
+
+There is no restriction on what dependency you might want to initialize your custom formatter with but -- as a bare minimum -- you'll want to provide a default template and inject the sanitizer which sanitizes the raw log entry into a hash you can interact with in your implementation. The only other requirement is that you must implement `#call` which takes a log entry which is an array of positional arguments (i.e. `severity`, `at`, `id`, `message`) and answers back a formatted string. If you need more examples you can either read the link:https://rubyapi.org/o/logger/formatter#method-i-call[Logger::Formatter] documentation or look at any of the formatters provided within this gem.
+
+=== Filters
+
+Filters allow you to mask sensitive information you don't want showing up in your logs. Here are the defaults:
+
+[source,ruby]
+----
+Cogger.filters
+
+# [
+#   :_csrf,
+#   :password,
+#   :password_confirmation
+# ]
+----
+
+To add additional filters, use:
+
+[source,ruby]
+----
+Cogger.add_filter(:login)
+      .add_filter "email"
+
+# [
+#   :_csrf,
+#   :password,
+#   :password_confirmation,
+#   :login,
+#   :email
+# ]
+----
+
+Symbols and strings can be used interchangeably but are stored as symbols since symbols are used when filtering log entries. Once your filters are in place, you can immediately see their effects:
+
+[source,ruby]
+----
+logger = Cogger.new formatter: :json
+logger.info login: "jayne", password: "secret"
+
+# {"id":"console","severity":"INFO","at":"2023-04-09 17:33:00 -0600","login":"[FILTERED]","password":"[FILTERED]"}
+----
+
+=== Streams
+
+You can add multiple log streams (outputs) by using:
+
+[source,ruby]
+----
+logger = Cogger.new
+               .add_stream(io: "tmp/demo.log")
+               .add_stream(io: nil)
+
+logger.info "Demo."
+----
+
+The above would log the `"Demo."` message to `$stdout` (i.e. the default stream), to the `tmp/demo.log` file, and to `/dev/null`. All of the attributes you would use to construct your default logger apply to any stream. This also means any custom template/formatter can be applied to your streams. Here's another example:
+
+[source,ruby]
+----
+logger = Cogger.new.add_stream(io: "tmp/demo.log", formatter: :json)
+logger.info "Demo."
+----
+
+In this situation, you'd get colorized output to `$stdout` and JSON output to the `tmp/demo.log` file.
+
+=== Defaults
+
+Should you ever need quick access to the defaults, you can use:
+
+[source,ruby]
+----
+Cogger.defaults
+----
+
+This is primarily meant for display/inspection purposes, though.
+
+=== Testing
 
 When testing the Cogger client, you might find it convenient to use `StringIO`, or a file, for
 logging purposes in order to not pollute your test output but also have a convenient way to see what
@@ -187,7 +530,7 @@ was logged. Example:
 [source,ruby]
 ----
 class Demo
-  def initialize logger: Cogger.init
+  def initialize logger: Cogger.new
     @logger = logger
   end
 
@@ -199,22 +542,24 @@ class Demo
 end
 
 RSpec.describe Demo do
+  using Refinements::StringIOs
+
   subject(:demo) { described_class.new logger: }
 
-  let(:logger) { Cogger.init Logger.new(StringIO.new) }
+  let(:logger) { Cogger.new io: }
+  let(:io) { StringIO.new }
 
   describe "#say" do
     it "logs text" do
       demo.say "test"
-      expect(logger.reread).to include("test")
+      expect(io.reread).to include("test")
     end
   end
 end
 ----
 
 Notice that when testing the instance of `Demo` and injecting a logger which logs to a string I/O
-object, you can conveniently reread that string to see what was logged. This makes your specs easier
-to write while also not adding additional noise to your test suite's output.
+object, you can conveniently _reread_ the string -- provided by the {refinements_link} gem -- to see what was logged. This makes your specs easier to write while avoiding additional noise in your test suite's output.
 
 == Development