From 72dae8e2228b7db9cac513f295e74ea3132611d1 Mon Sep 17 00:00:00 2001 From: Holger Just Date: Sun, 8 Oct 2017 21:54:32 +0200 Subject: [PATCH] Clarify the behavior of Fields::Hash#set with different force values --- lib/rackstash/fields/hash.rb | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/lib/rackstash/fields/hash.rb b/lib/rackstash/fields/hash.rb index e5a9096..4084941 100644 --- a/lib/rackstash/fields/hash.rb +++ b/lib/rackstash/fields/hash.rb @@ -412,9 +412,15 @@ module Rackstash alias reverse_update reverse_merge! # Set a `key` of `self` to the returned value of the passed block. - # If the key is forbidden from being set or already exists with a value - # other than `nil`, the block will not be called and the value will not be - # set. + # + # With `force: true`, we call the given block and set the normalized + # result to the `key`, overwriting any existing value. If the key is + # forbidden from being set, we raise an `ArgumentError` without calling + # the block. + # + # With `force: false`, if the key is forbidden from being set or already + # exists with a value other than `nil`, the block will not be called and + # the value will not be set / overwritten. # # @param key [#to_s] the field name. When setting the field, this name # will be normalized as a frozen UTF-8 string.