lapis 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 42e36c63db5206c7f4f826119ef5cf93868aa414
-  data.tar.gz: 6e49dc0ca0f20b9bd81aa2fbbe9c91fbabc1220d
+  metadata.gz: 06aee066a6540c2adc57450a61e7a07189358555
+  data.tar.gz: b2150a91cc8b8539b7cf048c9b58c3ea9b93b210
 SHA512:
-  metadata.gz: b1c5352ecd0c3c1b8c1882b3710c4bf8a46802b64d0fef0c57e9b61c9711aaf24693a4808092066e7613f776278cae10b62b5e78e52dbfa8c06b1fe0a4d15872
-  data.tar.gz: 851d107472c602dd6af27a3f8290450f35cab7eaae279a9e95298ed37ef9a42c9188a41b4c0de015e6b3ea997af4163f6d149bcde5c9e6f80e5e2f919a8e6523
+  metadata.gz: 78a7106706e487a608459d04fd436944bf48ebdf5626f14fe0601e0bf01f3ca4e8f8cf996394bcc1ff78056098e20d21732f37d00dd02240b39d736638100a91
+  data.tar.gz: 0cc90d094243dae821e0c60967acbc015a6a43ed16e3d6fbaff7c5a8f1c1e496db9d0495249154c6a954107807b0073f83bed87ed74717fe455ea02fee17ee3d

data/README.md

@@ -1,4 +1,4 @@
-# Lapis -- A simple, lightweight logging utility
+# Lapis
 
 Lapis is a simple, extensible logging utility. It provides the bare minimum
 needed to function, and lets you do the rest. You can provide your own
@@ -21,50 +21,70 @@ $ gem install lapis
 
 ## Usage
 
-The simplest use case is to simply make an instance of `Lapis::Logger` and start
+The simplest use case is to make an instance of `Lapis::Logger` and start
 using it, which will provide a default formatting function and output to
 `$stdout`:
 ```ruby
 logger = Lapis::Logger.new
-logger.info('Hello, world!')
+logger.info('Hello, world!') # => info: Hello, world!
 ```
-This will print `info: Hello, world!`
 
-If you want more customization, everything about the logger is customizable
-except for the output channel. For instance, to provide your own formatting
-function:
+If you want more customization, everything about the logger is customizable. 
+For instance, you can provide your own formatting function by setting the value
+of `formatter`:
 ```ruby
 logger = Lapis::Logger.new
 logger.formatter = lambda do |level, msg|
   output_channel.puts "[#{level.to_s.upcase}] #{msg}"
 end
 
-logger.info('Hello, world!')
+logger.info('Hello, world!') # => [INFO] Hello, world!
 ```
-This will print `[INFO] Hello, world!`
 
-If you want, you can also set `levels` to an array of your choice. If you do
-this in the constructor, you must also pass in an initial value for `level`:
+You can also customize the severity levels by setting the value of `levels` to
+an array. Levels should be ordered by their relative severity. You can do this
+straight from the constructor, although you will have to pass in the output
+channel explicitly. It is also recommended to set `level` to something sensible
+instead of the default, `:info`:
 ```ruby
+# Doing everything in the constructor
 Lapis::Logger.new($stdout, :bar, [:foo, :bar, :baz, :quux])
+
+# Setting things explicitly
+logger = Lapis::Logger.new
+logger.levels = [:foo, :bar, :baz, :quux]
+logger.level = :bar
 ```
 In the example above, `:foo` is the least important (equivalent to `:debug`),
-and `:quux` is the most important (equivalent to `:fatal`). Because the shortcut
-methods are magic, you can automagically call each value:
+and `:quux` is the most important (equivalent to `:fatal`). Additionally, you 
+can automagically call each value:
 ```ruby
 logger = Lapis::Logger.new($stdout, :bar, [:foo, :bar, :baz, :quux])
 logger.bar('Hello, world!') # => bar: Hello, world!
 logger.foo('Hello, world!') # => No output
 ```
 
-Finally, as a convenience, the `open` factory method is provided to easily log
-output to files:
+The `Logger` class defines two factory methods, `open` and `dummy`.
+
+The `open` factory method is provided to easily log output to files:
 ```ruby
 logger = Lapis::Logger.open('foo.log')
 logger.info('Hello, world!')
 ```
-This is equivalent to using `new`, except output is redirected to the file named
-in the constructor.
+This is just shorthand for the following:
+```ruby
+logger = Lapis::Logger.new(File.open('foo.log'))
+logger.info('Hello, world!')
+```
+
+The `dummy` factory method is provided to create a 'dummy' object which discards
+all output:
+```ruby
+logger = Lapis::Logger.dummy
+logger.info('Hello, world!') # => does nothing
+```
+Internally, the `dummy` method simply makes a new instance of `Logger` and sets
+its formatting function to an 'empty' lambda (i.e., a lambda that does nothing).
 
 ## Contributing
 

data/lib/lapis.rb

@@ -1,6 +1,6 @@
 module Lapis
 
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 
   # +Lapis::Logger+ is a simple, lightweight logging utility. It is fully
   # customizable; in particular, you can customize the following:
@@ -50,10 +50,19 @@ module Lapis
     # +new+ method, expect instead of expecting an IO object, it expects the
     # name of a file.
     # @param file [String] the name of the file to log output to
+    # @return [Lapis::Logger]
     def self.open(file, level=DEFAULT_LEVEL, levels=DEFAULT_LEVELS)
       new(File.open(file, "w"), level, levels)
     end
 
+    # A factory method for getting a dummy instance. Returns a new instance of
+    # Logger with an 'empty' lambda as its formatting function.
+    def self.dummy
+      dummy = new
+      dummy.formatter = lambda { |level, msg| }
+      dummy
+    end
+
     def level=(level)
       if @levels.include?(level)
         @level = level

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lapis
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Citruxy