README.md in lager-1.1.3.1 vs README.md in lager-1.1.4.1
- old
+ new
@@ -1,9 +1,20 @@
+[](https://github.com/rickhull/lager/actions/workflows/ci.yaml)
+[](http://badge.fury.io/rb/lager)
+[](https://codeclimate.com/github/rickhull/lager/badges)
+
Lager
=====
-Lager is a logging mixin. It is designed to add class methods for logging, via `extend Lager`. It provides a unified logging instance that you can use in both class and instance methods. It is implemented with the familiar [Logger class](http://ruby-doc.org/stdlib-2.0/libdoc/logger/rdoc/Logger.html) from ruby's [stdlib](http://ruby-doc.org/stdlib/). Only one Logger instance is used for the class. Use #log_to to set the log destination and log level from inside or outside the class.
+Lager is a logging mixin. It is designed to add class methods for logging,
+via `extend Lager`. It provides a unified logging instance that you can use
+in both class and instance methods. It is implemented with the familiar
+[Logger class](http://ruby-doc.org/stdlib-2.0/libdoc/logger/rdoc/Logger.html)
+from ruby's [stdlib](http://ruby-doc.org/stdlib/). Only one Logger instance
+is used for the class. Use `log_to` to set the log destination and log level
+from inside or outside the class.
+
Usage
-----
```ruby
require 'lager'
@@ -11,11 +22,12 @@
extend Lager
log_to $stdout, :debug # sets up @lager at the class layer
# ...
```
-Now, within Foo, you can use the class instance variable @lager for logging.
+Now, within Foo, you can use the class instance variable `@lager` for
+logging.
```ruby
# ...
def self.bar(baz)
unless baz.is_a?(String)
@@ -23,11 +35,12 @@
end
end
# ...
```
-What about instance methods, you ask? Well, you will need to assign @lager yourself, within #initialize.
+What about instance methods, you ask? Well, you will need to assign `@lager`
+yourself, within `#initialize`.
```ruby
# ...
def initialize
# set the instance layer's @lager to the class layer's @lager
@@ -55,11 +68,12 @@
[2013-07-05 15:14:52] DEBUG: baz 15 is a Fixnum, not a string
[2013-07-05 15:14:52] DEBUG: about to do something complicated
[2013-07-05 15:14:52] DEBUG: whew! we made it!
```
-This is because we set the default logging to :debug level, above. Let's calm things down a bit, shall we?
+This is because we set the default logging to `:debug` level, above.
+Let's calm things down a bit, shall we?
```ruby
Foo.log_level = :warn
Foo.new.do_something_complicated
```
@@ -68,58 +82,68 @@
```ruby
Foo.log_to '/tmp/foo.log'
```
-Note that this will replace the class's Logger instance. The old log level will be maintained unless you specify a new one.
+Note that this will replace the class's Logger instance. The old log level
+will be maintained unless you specify a new one.
Best practices
--------------
-* Set default logging inside the class definition by calling log_to just after extend Lager
-* Set the instance layer's @lager within #initialize
-* Only call message methods (debug, info, warn, error, fatal) on @lager in your class and instance methods.
-* Beyond the class default, let the log destination and log level be managed from the outside, by the users of your class.
+* Set default logging inside the class definition by calling `log_to`
+ just after `extend Lager`
+* Set the instance layer's `@lager` within `#initialize`
+* Only call message methods (debug, info, warn, error, fatal) on `@lager`
+ in your class and instance methods.
+* Beyond the class default, let the log destination and log level be
+ managed from the outside, by the users of your class.
For Logger, generally: use block invocation of message methods.
```ruby
@lager.debug { "hi" }
# rather than
@lager.debug "hi"
```
-By using the first form, the block will not be evaluated unless you are logging at DEBUG level. If using the second form, the message is evaluated no matter the current log level. This can be significant when logging heavily processed messages.
+By using the first form, the block will not be evaluated unless you are
+logging at `DEBUG` level. If using the second form, the message is evaluated
+no matter the current log level. This can be significant when logging heavily
+processed messages.
Artifacts
---------
-* By mixing in Lager via extend, you introduce these class methods:
+* By mixing in via `extend Lager`, you introduce these class methods:
* lager
* log_to
* log_level
* log_level=
-* By calling log_to, you introduce the *class instance variable* @lager
-* By assigning @lager within initialize, you introduce the *instance variable* @lager
+* By calling `log_to`, you introduce the *class instance variable* `@lager`
+* By assigning `@lager` within `initialize`, you introduce the
+ *instance variable* `@lager`
Now you have a unified interface for logging at both class and instance layers.
```ruby
@lager.info { "So happy right now!" }
```
Use an existing Logger instance
-------------------------------
-If your project already has an existing Logger, then you can set your class to use that Logger:
+If your project already has an existing Logger, then you can set your class
+to use that Logger:
```ruby
class Foo
extend Lager
log_to $LOG # the global Logger instance
# ...
end
```
-Of course, $LOG will have to have already been defined at requiretime. You can set it the same way at runtime:
+Of course, `$LOG` will have to have already been defined at requiretime.
+You can set it the same way at runtime:
```ruby
class Foo
extend Lager
log_to $stderr
@@ -132,9 +156,10 @@
Foo.log_to Project.log
```
Inheritance
-----------
+
```ruby
class Foo
extend Lager
end