README.adoc in refinements-7.12.0 vs README.adoc in refinements-7.13.0
- old
+ new
@@ -4,10 +4,12 @@
= Refinements
[link=http://badge.fury.io/rb/refinements]
image::https://badge.fury.io/rb/refinements.svg[Gem Version]
+[link=https://www.alchemists.io/projects/code_quality]
+image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
[link=https://circleci.com/gh/bkuhlmann/refinements]
image::https://circleci.com/gh/bkuhlmann/refinements.svg?style=svg[Circle CI Status]
A collection of refinements (enhancements) to primitive Ruby objects.
@@ -121,10 +123,20 @@
example = ["An", nil, "", "Example"]
example.compress! # => ["An", "Example"]
example # => ["An", "Example"]
----
+===== #exclude
+
+Removes given array or elements without mutating itself.
+
+[source,ruby]
+----
+[1, 2, 3, 4, 5].exclude [4, 5] # => [1, 2, 3]
+[1, 2, 3, 4, 5].exclude 4, 5 # => [1, 2, 3]
+----
+
===== #include
Adds given array or elements without mutating itself.
[source,ruby]
@@ -142,20 +154,10 @@
[1, 2, 3].intersperse :a # => [1, :a, 2, :a, 3]
[1, 2, 3].intersperse :a, :b # => [1, :a, :b, 2, :a, :b, 3]
[1, 2, 3].intersperse %i[a b c] # => [1, :a, :b, :c, 2, :a, :b, :c, 3]
----
-===== #exclude
-
-Removes given array or elements without mutating itself.
-
-[source,ruby]
-----
-[1, 2, 3, 4, 5].exclude [4, 5] # => [1, 2, 3]
-[1, 2, 3, 4, 5].exclude 4, 5 # => [1, 2, 3]
-----
-
===== #mean
Answers mean/average all elements within an array.
[source,ruby]
@@ -239,106 +241,10 @@
example = Hash.with_default []
example[:b] # => []
----
-===== #except
-
-Answers new hash with given keys removed without mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2, c: 3}
-example.except :a, :b # => {c: 3}
-example # => {a: 1, b: 2, c: 3}
-----
-
-===== #except!
-
-Answers new hash with given keys removed while mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2, c: 3}
-example.except! :a, :b # => {c: 3}
-example # => {c: 3}
-----
-
-===== #flatten_keys
-
-Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
-though.
-
-[source,ruby]
-----
-{a: {b: 1}}.flatten_keys prefix: :test # => {test_a_b: 1}
-{a: {b: 1}}.flatten_keys delimiter: :| # => {:"a|b" => 1}
-
-{a: {b: 1}}.flatten_keys cast: :to_s # => {"a_b" => 1}
-{"a" => {"b" => 1}}.flatten_keys cast: :to_sym # => {a_b: 1}
-
-example = {a: {b: 1}}
-example.flatten_keys # => {a_b: 1}
-example # => {a: {b: 1}}
-----
-
-===== #flatten_keys!
-
-Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
-though.
-
-[source,ruby]
-----
-example = {a: {b: 1}}
-example.flatten_keys! # => {a_b: 1}
-example # => {a_b: 1}
-----
-
-===== #stringify_keys
-
-Converts keys to strings without mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2}
-example.stringify_keys # => {"a" => 1, "b" => 2}
-example # => {a: 1, b: 2}
-----
-
-===== #stringify_keys!
-
-Converts keys to strings while mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2}
-example.stringify_keys! # => {"a" => 1, "b" => 2}
-example # => {"a" => 1, "b" => 2}
-----
-
-===== #symbolize_keys
-
-Converts keys to symbols without mutating itself.
-
-[source,ruby]
-----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys # => {a: 1, b: 2}
-example # => {"a" => 1, "b" => 2}
-----
-
-===== #symbolize_keys!
-
-Converts keys to symbols while mutating itself.
-
-[source,ruby]
-----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys! # => {a: 1, b: 2}
-example # => {a: 1, b: 2}
-----
-
===== #deep_merge
Merges deeply nested hashes together without mutating itself.
[source,ruby]
@@ -401,10 +307,62 @@
example = {"a" => {"b" => 2}}
example.deep_symbolize_keys! # => {a: {b: 1}}
example # => {a: {b: 1}}
----
+===== #except
+
+Answers new hash with given keys removed without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2, c: 3}
+example.except :a, :b # => {c: 3}
+example # => {a: 1, b: 2, c: 3}
+----
+
+===== #except!
+
+Answers new hash with given keys removed while mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2, c: 3}
+example.except! :a, :b # => {c: 3}
+example # => {c: 3}
+----
+
+===== #flatten_keys
+
+Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
+though.
+
+[source,ruby]
+----
+{a: {b: 1}}.flatten_keys prefix: :test # => {test_a_b: 1}
+{a: {b: 1}}.flatten_keys delimiter: :| # => {:"a|b" => 1}
+
+{a: {b: 1}}.flatten_keys cast: :to_s # => {"a_b" => 1}
+{"a" => {"b" => 1}}.flatten_keys cast: :to_sym # => {a_b: 1}
+
+example = {a: {b: 1}}
+example.flatten_keys # => {a_b: 1}
+example # => {a: {b: 1}}
+----
+
+===== #flatten_keys!
+
+Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
+though.
+
+[source,ruby]
+----
+example = {a: {b: 1}}
+example.flatten_keys! # => {a_b: 1}
+example # => {a_b: 1}
+----
+
===== #recurse
Recursively iterates over the hash and any hash value by applying the given block to it. Does not
handle nested arrays, though.
@@ -457,10 +415,54 @@
example = {a: 1, b: 2}
example.reverse_merge! a: 0, c: 3 # => {a: 1, b: 2, c: 3}
example # => {a: 1, b: 2, c: 3}
----
+===== #stringify_keys
+
+Converts keys to strings without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys # => {"a" => 1, "b" => 2}
+example # => {a: 1, b: 2}
+----
+
+===== #stringify_keys!
+
+Converts keys to strings while mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys! # => {"a" => 1, "b" => 2}
+example # => {"a" => 1, "b" => 2}
+----
+
+===== #symbolize_keys
+
+Converts keys to symbols without mutating itself.
+
+[source,ruby]
+----
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys # => {a: 1, b: 2}
+example # => {"a" => 1, "b" => 2}
+----
+
+===== #symbolize_keys!
+
+Converts keys to symbols while mutating itself.
+
+[source,ruby]
+----
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys! # => {a: 1, b: 2}
+example # => {a: 1, b: 2}
+----
+
===== #use
Passes each hash value as a block argument for further processing.
[source,ruby]
@@ -484,22 +486,10 @@
io = IO.void { |void| void.write "nevermore" }
io.closed? # => true
----
-===== #squelch
-
-Temporarily ignores any reads/writes for current stream for all code executed within the block. When
-not given a block, it answers itself.
-
-[source,ruby]
-----
-io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
-io.squelch { io.write "Test" }
-io.reread # => ""
-----
-
===== #redirect
Redirects current stream to other stream when given a block. Without a block, the original stream is
answered instead.
@@ -530,10 +520,22 @@
buffer = "".dup
io.reread(buffer: buffer)
buffer # => "This is a test."
----
+===== #squelch
+
+Temporarily ignores any reads/writes for current stream for all code executed within the block. When
+not given a block, it answers itself.
+
+[source,ruby]
+----
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.squelch { io.write "Test" }
+io.reread # => ""
+----
+
==== Pathname
===== Pathname
Enhances the conversion function -- refined from `Kernel` -- which casts `nil` into a pathname in
@@ -544,17 +546,24 @@
[source,ruby]
----
Pathname(nil) # => Pathname("")
----
-===== #name
+===== #change_dir
-Answers file name without extension.
+Inherits and wraps `Dir.chdir` behavior by changing to directory of current path. See
+link:https://rubyapi.org/2.7/o/s?q=Dir.chdir[Dir.chdir] for details.
[source,ruby]
----
-Pathname("example.txt").name # => Pathname("example")
+Pathname.pwd # => "/"
+Pathname("/test").make_dir.change_dir # => Pathname "/test"
+Pathname.pwd # => "/test"
+
+Pathname.pwd # => "/"
+Pathname("/test").make_dir.change_dir { # Implementation details } # => Pathname "/test"
+Pathname.pwd # => "/"
----
===== #copy
Copies file from current location to new location.
@@ -606,99 +615,132 @@
Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test")
# => Pathname("/test/some/test")
----
-===== #relative_parent
+===== #make_ancestors
-Answers relative path from parent directory. This is a complement to `#relative_path_from`.
+Ensures all ancestor directories are created for a path.
[source,ruby]
----
-Pathname("/one/two/three").relative_parent("/one") # => Pathname "two"
+Pathname("/one/two").make_ancestors
+Pathname("/one").exist? # => true
+Pathname("/one/two").exist? # => false
----
-===== #make_ancestors
+===== #make_dir
-Ensures all ancestor directories are created for a path.
+Provides alternative `#mkdir` behavior by always answering itself (even when directory exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
[source,ruby]
----
-Pathname("/one/two").make_ancestors
-Pathname("/one").exist? # => true
-Pathname("/one/two").exist? # => false
+Pathname("/one").make_dir # => Pathname("/one")
+Pathname("/one").make_dir.make_dir # => Pathname("/one")
----
-===== #mkdir
+===== #make_path
-Modifies default behavior by always answering itself (even when directory exists) and not throwing
-errors when directory exists.
+Provides alternative `#mkpath` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
[source,ruby]
----
-Pathname("/one").mkdir # => Pathname("/one")
-Pathname("/one").mkdir.mkdir # => Pathname("/one")
+Pathname("/one/two/three").make_path # => Pathname("/one/two/three")
+Pathname("/one/two/three").make_path.make_path # => Pathname("/one/two/three")
----
-===== #rewrite
+===== #name
-When given a block, it provides the contents of the recently read file for manipulation and
-immediate writing back to the same file.
+Answers file name without extension.
[source,ruby]
----
-Pathname("/test.txt").rewrite { |content| content.sub "[placeholder]", "example" }
+Pathname("example.txt").name # => Pathname("example")
----
-===== #touch
+===== #relative_parent
-Updates access and modification times for path. Defaults to current time.
+Answers relative path from parent directory. This is a complement to `#relative_path_from`.
[source,ruby]
----
-Pathname("example.txt").touch
-Pathname("example.txt").touch at: Time.now - 1
+Pathname("/one/two/three").relative_parent("/one") # => Pathname "two"
----
-==== String
+===== #remove_dir
-===== #first
+Provides alternative `#rmdir` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
-Answers first character of a string or first set of characters if given a number.
+[source,ruby]
+----
+Pathname("/test").make_dir.remove_dir.exist? # => false
+Pathname("/test").remove_dir # => Pathname("/test")
+Pathname("/test").remove_dir.remove_dir # => Pathname("/test")
+----
+===== #remove_tree
+
+Provides alternative `#rmtree` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
+
[source,ruby]
----
-"example".first # => "e"
-"example".first 4 # => "exam"
+parent_path = Pathname "/one"
+child_path = parent_path.join "two"
+
+child_path.make_path
+child_path.remove_tree # => Pathname "/one/two"
+child_path.exist? # => false
+paremt_path.exist? # => true
+
+child_path.make_path
+parent_path.remove_tree # => Pathname "/one"
+child_path.exist? # => false
+parent_path.exist? # => false
----
-===== #last
+===== #rewrite
-Answers last character of a string or last set of characters if given a number.
+When given a block, it provides the contents of the recently read file for manipulation and
+immediate writing back to the same file.
[source,ruby]
----
-"instant".last # => "t"
-"instant".last 3 # => "ant"
+Pathname("/test.txt").rewrite { |content| content.sub "[placeholder]", "example" }
----
+===== #touch
+
+Updates access and modification times for path. Defaults to current time.
+
+[source,ruby]
+----
+Pathname("example.txt").touch
+Pathname("example.txt").touch at: Time.now - 1
+----
+
+==== String
+
===== #blank?
Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`, and/or `\r`.
[source,ruby]
----
" \n\t\r".blank? # => true
----
-===== #up
+===== #camelcase
-Answers string with only first letter upcased.
+Answers a camelcased string.
[source,ruby]
----
-"example".up # => "Example"
+"this_is_an_example".camelcase # => "ThisIsAnExample"
----
===== #down
Answers string with only first letter downcased.
@@ -706,10 +748,20 @@
[source,ruby]
----
"EXAMPLE".down # => "eXAMPLE"
----
+===== #first
+
+Answers first character of a string or first set of characters if given a number.
+
+[source,ruby]
+----
+"example".first # => "e"
+"example".first 4 # => "exam"
+----
+
===== #indent
Answers string indented by two spaces by default.
[source,ruby]
@@ -719,17 +771,18 @@
"example".indent -1 # => "example"
"example".indent 2 # => " example"
"example".indent 3, padding: " " # => " example"
----
-===== #camelcase
+===== #last
-Answers a camelcased string.
+Answers last character of a string or last set of characters if given a number.
[source,ruby]
----
-"this_is_an_example".camelcase # => "ThisIsAnExample"
+"instant".last # => "t"
+"instant".last 3 # => "ant"
----
===== #snakecase
Answers a snakecased string.
@@ -757,9 +810,18 @@
"true".to_bool # => true
"yes".to_bool # => true
"1".to_bool # => true
"".to_bool # => false
"example".to_bool # => false
+----
+
+===== #up
+
+Answers string with only first letter upcased.
+
+[source,ruby]
+----
+"example".up # => "Example"
----
==== String IO
===== #reread