From b6be188dbd922dc354b7dfe60928987d11fa7c80 Mon Sep 17 00:00:00 2001
From: Holger Just <hello@holgerjust.de>
Date: Mon, 14 Jan 2019 11:50:18 +0100
Subject: [PATCH] Use Logger#capture instead of with_buffer as a more intention
 revealing name

---
 lib/rackstash/logger.rb       | 27 +++++++++++++++++----------
 spec/rackstash/logger_spec.rb | 14 +++++++++-----
 2 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/lib/rackstash/logger.rb b/lib/rackstash/logger.rb
index 03d054c..d80df51 100644
--- a/lib/rackstash/logger.rb
+++ b/lib/rackstash/logger.rb
@@ -314,7 +314,7 @@ module Rackstash
     # {#warn}, {#error}, or {#fatal}.
     #
     # The message will be added to the current log buffer. If we are currently
-    # buffering (i.e. if we are inside a {#with_buffer} block), the message is
+    # buffering (i.e. if we are inside a {#capture} block), the message is
     # merely added but not flushed to the underlying logger. Else, the message
     # along with any previously defined fields and tags will be flushed to the
     # base logger immediately.
@@ -373,7 +373,7 @@ module Rackstash
     # sure that the Buffer is only ever used by the calling Thread to retain the
     # thread-safety guarantees of Rackstash.
     #
-    # Most of the time, you should use {#with_buffer} instead to ensure that the
+    # Most of the time, you should use {#capture} instead to ensure that the
     # Buffer is reliably removed again when the execution leaves the block.
     # The only sensible use of the manual buffer management is when you need
     # to flush the Buffer outside of its active scope after it was poped.
@@ -421,7 +421,7 @@ module Rackstash
     # only happen if the code execution was non-linear and stepped outside the
     # block scope), we return `nil` and not change the BufferStack.
     #
-    # @note In contrast to {#with_buffer}, the poped Buffer is not flushed
+    # @note In contrast to {#capture}, the poped Buffer is not flushed
     #   automatically. You *MUST* call `buffer.flush` yourself to write the
     #   buffered log data to the log adapter(s).
     # @see #push_buffer
@@ -432,13 +432,17 @@ module Rackstash
       buffer_stack.pop
     end
 
-    # Create a new buffering {Buffer} and put in on the {BufferStack} for the
-    # current Thread. For the duration of the block, all new logged messages
-    # and any access to fields and tags will be sent to this new buffer.
-    # Previous buffers will only be visible after the execution left the block.
+    # Capture all messages and fields logged for the duration of the provided
+    # block in the current thread.
     #
-    # Note that the created {Buffer} is only valid for the current Thread. In
-    # other Threads, it will neither be used not visible.
+    # Create a new {Buffer} and put in on the {BufferStack} for the current
+    # thread. For the duration of the block, all new logged messages and any
+    # access to fields and tags will be sent to this new buffer. Previous
+    # buffers created in the same thread will only be visible after the
+    # execution left the block.
+    #
+    # Note that the created {Buffer} is only valid for the current thread. In
+    # other threads, it not visible and will thus not be used.
     #
     # @param buffer_args [Hash<Symbol => Object>] optional arguments for the new
     #   {Buffer}. See {Buffer#initialize} for allowed values.
@@ -447,7 +451,7 @@ module Rackstash
     #   removed from the {BufferStack} again and is always flushed
     #   automatically.
     # @return [Object] the return value of the block
-    def with_buffer(buffer_args = {})
+    def capture(buffer_args = {})
       raise ArgumentError, 'block required' unless block_given?
 
       buffer_stack.push(buffer_args)
@@ -458,6 +462,9 @@ module Rackstash
       end
     end
 
+    # TODO: This alias should be deprecated
+    alias with_buffer capture
+
     private
 
     def buffer_stack
diff --git a/spec/rackstash/logger_spec.rb b/spec/rackstash/logger_spec.rb
index adffcc4..c3c3e0c 100644
--- a/spec/rackstash/logger_spec.rb
+++ b/spec/rackstash/logger_spec.rb
@@ -513,9 +513,9 @@ RSpec.describe Rackstash::Logger do
     end
   end
 
-  describe '#with_buffer' do
+  describe '#capture' do
     it 'requires a block' do
-      expect { logger.with_buffer }.to raise_error ArgumentError
+      expect { logger.capture }.to raise_error ArgumentError
     end
 
     it 'adds a new buffer' do
@@ -523,7 +523,7 @@ RSpec.describe Rackstash::Logger do
       expect(logger.send(:buffer_stack)).to receive(:flush_and_pop).and_call_original
 
       logger.fields['key'] = 'outer'
-      logger.with_buffer do
+      logger.capture do
         expect(logger.fields['key']).to be nil
         logger.fields['key'] = 'inner'
       end
@@ -533,14 +533,18 @@ RSpec.describe Rackstash::Logger do
     it 'buffers multiple messages' do
       expect(logger.flows).to receive(:flush).once
 
-      logger.with_buffer do
+      logger.capture do
         logger.add 1, 'Hello World'
         logger.add 0, 'I feel great'
       end
     end
 
     it 'returns the yielded value' do
-      expect(logger.with_buffer { :hello }).to eql :hello
+      expect(logger.capture { :hello }).to eql :hello
+    end
+
+    it 'can use thew #with_buffer alias' do
+      expect(logger.method(:with_buffer)).to eql logger.method(:capture)
     end
   end