refinements 7.8.0 → 7.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd72c4e1fda257b53dcd80a052db0ce99cd5b2987e531bea93f577e6b3b131f9
-  data.tar.gz: 67b83319903a39425640eb0534eab280e7cb138e588476c635c5192afb08758d
+  metadata.gz: 58f24ccfa83d2f2af820c05d19c575e371ed5c6471177c8c58648006cf3ca945
+  data.tar.gz: 7fccb86818487e2de337969b42c8ec81f52e28bc1a3edb1d8cc0bf2c206ee2b0
 SHA512:
-  metadata.gz: 8fab91775e301f8765dd3156ab91e6abdf9395bdf767fbf859f80a5d3ea2bbebabef8dbe9e5e5a65e33443082a13e127ce3d85c1384b3939d753347384dea99e
-  data.tar.gz: 74934f4fbb6336ad4c434961c865b826675a71b76f846faae7635e6e09d3aa99bd74a9c74d6f0289f2d63a0c3352c9e21aecb60e35c2485664879520b20a755d
+  metadata.gz: 773c5bf918f8e7f958dc602b9c6d7edefc29d644d7d928db0f21e2fa93616781e075b1c4743281b025daf8335c13761d460d149caa470c8000a11aecc91f25f8
+  data.tar.gz: 1cbe58132380e683a0e47813fe676440055fa2a9af1bd582bf8661c3778b1aa354cda5d3939f07b69a6190f72b28e9635890aaa6810af7c9255fef27c025e1a5

checksums.yaml.gz.sig

@@ -1,3 +1 @@
-!�������PW�F�nk���~9�z��Z�3�o�GŚ��kw�+�~�� X�P���r4x�vq�p]���Ͱ�?��AMJM�
�Oc�y.π���i�Ql�P^��΅g�7��d �	:�/oJ��ݱ�Fl_N_:kI':�M���KE�W�P!
-�k2����]
-�RC���^��&��.����7W��T8-��:!��	/�?��5"Ix+��nOho�컎��r+���F���6m��%2P��f�
+_����G��M��p@��V}��\0����j���6<ʑR�-^ o�nHŽ�Άw�l��?	�2���B�Qܹ��q��'������ݧ\��]�(�n�O�+N�1
��3_4AN���}&~;��u���

data/LICENSE.adoc

@@ -150,7 +150,7 @@ additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright link:https://www.alchemists.io[Alchemists].
+Copyright 2015 link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
 compliance with the License. You may obtain a link:https://www.apache.org/licenses/LICENSE-2.0[copy]

data/README.adoc

@@ -6,75 +6,28 @@
 
 [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 core Ruby objects.
+A collection of refinements (enhancements) to primitive Ruby objects.
 
 toc::[]
 
 == Features
 
-* *Arrays*:
-** `#compress` - Removes `nil` and empty values without modifying itself.
-** `#compress!` - Removes `nil` and empty values while modifying itself.
-** `#include` - Adds given array or elements without modifying itself.
-** `#exclude` - Removes given array or elements without modifying itself.
-** `#ring` - Answers a circular array which can enumerate before, current, after elements.
-* *BigDecimals*:
-** `#inspect` - Allows one to inspect a big decimal with numeric representation.
-* *DateTimes*:
-** `.utc` - Answers new DateTime object for current UTC date/time.
-* *Files*:
-** `#rewrite` - When given a file path and a block, it provides the contents of the recently read
-file for manipulation and immediate writing back to the same file.
-* *Hashes*:
-** `.infinite` - Answers new hash where missing keys, even deeply nested, answer an empty hash.
-** `.with_default` - Answers new hash where every top-level missing key has the same default value.
-** `#except` - Answers new hash with given keys removed without modifying itself.
-** `#except!` - Answers new hash with given keys removed while modifying itself.
-** `#symbolize_keys` - Converts keys to symbols without modifying itself.
-** `#symbolize_keys!` - Converts keys to symbols while modifying itself.
-** `#deep_merge` - Merges deeply nested hashes together without modifying itself.
-** `#deep_merge!` - Merges deeply nested hashes together while modifying itself.
-** `#deep_symbolize_keys` - Symbolizes keys of nested hash without modifying itself. Does not handle
-   nested arrays, though.
-** `#deep_symbolize_keys!` - Symbolizes keys of nested hash while modifying itself. Does not handle
-   nested arrays, though.
-** `#recurse` - Applies block to nested hash. Does not handle nested arrays, though.
-** `#rekey` - Transforms keys per mapping (size of mapping can vary) without modifying itself.
-** `#rekey!` - Transforms keys per mapping (size of mapping can vary) while modifying itself.
-** `#reverse_merge` - Merges calling hash into passed in hash without modifying itself.
-** `#reverse_merge!` - Merges calling hash into passed in hash while modifying itself.
-** `#use` - Passes each hash value as a block argument for further processing.
-* *Pathnames*:
-** `Pathname` - Conversion function (refined from `Kernel`) which can cast `nil` into a pathname.
-** `#name` - Answers file name without extension.
-** `#copy` - Copies file from current location to new location.
-** `#directories` - Answers all or filtered directories for current path.
-** `#extensions` - Answers file extensions as an array.
-** `#files` - Answers all or filtered files for current path.
-** `#gsub` - Same behavior as `String#gsub` but answers a path with patterns replaced with desired
-   substitutes.
-** `#relative_parent` - Answers relative path from parent directory. This is a complement to
-   `#relative_path_from`.
-** `#make_ancestors` - Ensures all ancestor directories are created for a path.
-** `#rewrite` - When given a block, it provides the contents of the recently read file for
-manipulation and immediate writing back to the same file.
-** `#touch` - Updates access and modification times for path. Defaults to current time.
-* *Strings*:
-** `#first` - Answers first character of a string or first set of characters if given a number.
-** `#last` - Answers last character of a string or last set of characters if given a number.
-** `#blank?` - Answers `true`/`false` based on whether string is blank or not
-(i.e. `<space>`, `\n`, `\t`, `\r`).
-** `#up` - Answers string with only first letter upcased.
-** `#down` - Answers string with only first letter downcased.
-** `#camelcase` - Answers a camelcased string.
-** `#snakecase` - Answers a snakecased string.
-** `#titleize` - Answers titleized string.
-** `#to_bool` - Answers string as a boolean.
-* *String IOs*:
-** `#reread` - Answers full string by rewinding to beginning of string and reading all content.
+Enhances the following objects:
+
+* Array
+* BigDecimal
+* DateTime
+* File
+* Hash
+* IO
+* Pathname
+* String
+* StringIO
 
 == Requirements
 
@@ -84,8 +37,6 @@ manipulation and immediate writing back to the same file.
 
 == Setup
 
-=== Production
-
 To install, run:
 
 [source,bash]
@@ -100,24 +51,6 @@ Add the following to your Gemfile file:
 gem "refinements"
 ----
 
-=== Development
-
-To contribute, run:
-
-[source,bash]
-----
-git clone https://github.com/bkuhlmann/refinements.git
-cd refinements
-bin/setup
-----
-
-You can also use the IRB console for direct access to all objects:
-
-[source,bash]
-----
-bin/console
-----
-
 == Usage
 
 === Requires
@@ -129,7 +62,7 @@ If all refinements are not desired, add the following to your `+Gemfile+` instea
 gem "refinements", require: false
 ----
 
-…then require the specific refinement, as needed. Example:
+...then require the specific refinement, as needed. Example:
 
 [source,ruby]
 ----
@@ -138,13 +71,16 @@ require "refinements/big_decimals"
 require "refinements/date_times"
 require "refinements/files"
 require "refinements/hashes"
+require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
+require "refinements/string_ios"
 ----
 
 === Using
 
-Much like including/extending a module, you’ll need modify your object(s) to use the refinement(s):
+Much like including/extending a module, you’ll need to modify your object(s) to use the
+refinement(s):
 
 [source,ruby]
 ----
@@ -154,8 +90,10 @@ class Example
   using Refinements::DateTimes
   using Refinements::Files
   using Refinements::Hashes
+  using Refinements::IOs
   using Refinements::Pathnames
   using Refinements::Strings
+  using Refinements::StringIOs
 end
 ----
 
@@ -165,25 +103,81 @@ The following sections demonstrate how each refinement enriches your objects wit
 
 ==== Array
 
+===== #compress
+
+Removes `nil` and empty values without mutating itself.
+
 [source,ruby]
 ----
 example = ["An", nil, "", "Example"]
-example.compress # => ["An", "Example"]
-example # => ["An", nil, "", "Example"]
+example.compress  # => ["An", "Example"]
+example           # => ["An", nil, "", "Example"]
+----
+
+===== #compress!
+
+Removes `nil` and empty values while mutating itself.
 
+[source,ruby]
+----
 example = ["An", nil, "", "Example"]
-example.compress! # => ["An", "Example"]
-example # => ["An", "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]
+----
+[1, 2, 3].include [4, 5]  # => [1, 2, 3, 4, 5]
+[1, 2, 3].include 4, 5    # => [1, 2, 3, 4, 5]
+----
+
+===== #intersperse
+
+Inserts additional elements or array between all members of given array.
+
+[source,ruby]
+----
+[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]
+----
 
-[1, 2, 3].include [4, 5] # => [1, 2, 3, 4, 5]
-[1, 2, 3].include 4, 5 # => [1, 2, 3, 4, 5]
+===== #mean
 
-[1, 2, 3, 4, 5].exclude [4, 5] # => [1, 2, 3]
-[1, 2, 3, 4, 5].include 4, 5 # => [1, 2, 3, 4, 5]
+Answers mean/average all elements within an array.
 
+[source,ruby]
+----
+[].mean                 # => 0
+[5].mean                # => 5
+[1, 2, 3].mean          # => 2
+[1.25, 1.5, 1.75].mean  # => 1.5
+----
+
+===== #ring
+
+Answers a circular array which can enumerate before, current, after elements.
+
+[source,ruby]
+----
 example = [1, 2, 3]
 example.ring # => #<Enumerator: ...>
 example.ring { |(before, current, after)| puts "#{before} #{current} #{after}" }
+
 # [3 1 2]
 # [1 2 3]
 # [2 3 1]
@@ -191,6 +185,10 @@ example.ring { |(before, current, after)| puts "#{before} #{current} #{after}" }
 
 ==== Big Decimal
 
+===== #inspect
+
+Allows one to inspect a big decimal with numeric representation.
+
 [source,ruby]
 ----
 BigDecimal.new("5.0E-10").inspect # => "#<BigDecimal:3fd3d458fe84 0.0000000005>"
@@ -198,6 +196,10 @@ BigDecimal.new("5.0E-10").inspect # => "#<BigDecimal:3fd3d458fe84 0.0000000005>"
 
 ==== DateTime
 
+===== .utc
+
+Answers new DateTime object for current UTC date/time.
+
 [source,ruby]
 ----
 DateTime.utc # => #<DateTime: 2019-12-31T18:17:00+00:00 ((2458849j,65820s,181867000n),+0s,2299161j)>
@@ -205,6 +207,11 @@ DateTime.utc # => #<DateTime: 2019-12-31T18:17:00+00:00 ((2458849j,65820s,181867
 
 ==== File
 
+===== .rewrite
+
+When given a file path and a block, it provides the contents of the recently read file for
+manipulation and immediate writing back to the same file.
+
 [source,ruby]
 ----
 File.rewrite("/test.txt") { |content| content.gsub "[placeholder]", "example" }
@@ -212,160 +219,647 @@ File.rewrite("/test.txt") { |content| content.gsub "[placeholder]", "example" }
 
 ==== Hash
 
+===== .infinite
+
+Answers new hash where missing keys, even deeply nested, answer an empty hash.
+
 [source,ruby]
 ----
 example = Hash.infinite
-example[:a] # => {}
-example[:a][:b][:c] # => {}
+example[:a]          # => {}
+example[:a][:b][:c]  # => {}
+----
+
+===== .with_default
+
+Answers new hash where every top-level missing key has the same default value.
 
+[source,ruby]
+----
 example = Hash.with_default ""
 example[:a] # => ""
+
 example = Hash.with_default []
 example[:b] # => []
+----
 
-example = {a: 1, b: 2, c: 3}
-example.except :a, :b # => {c: 3}
-example # => {a: 1, b: 2, c: 3}
-
-example = {a: 1, b: 2, c: 3}
-example.except! :a, :b # => {c: 3}
-example # => {c: 3}
+===== #deep_merge
 
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys # => {a: 1, b: 2}
-example # => {"a" => 1, "b" => 2}
+Merges deeply nested hashes together without mutating itself.
 
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys! # => {a: 1, b: 2}
-example # => {a: 1, b: 2}
+[source,ruby]
+----
+example = {a: "A", b: {one: "One", two: "Two"}}
+example.deep_merge b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
+example                         # => {a: "A", b: {one: "One", two: "Two"}}
+----
 
-example = {a: 1, b: 2, c: 3}
-example.slice :a, :c # => {a: 1, c: 3}
-example # => {a: 1, b: 2, c: 3}
+===== #deep_merge!
 
-example = {a: 1, b: 2, c: 3}
-example.slice! :a, :c # => {a: 1, c: 3}
-example # => {a: 1, c: 3}
+Merges deeply nested hashes together while mutating itself.
 
+[source,ruby]
+----
 example = {a: "A", b: {one: "One", two: "Two"}}
-example.deep_merge b: {one: 1} # => {a: "A", b: {one: 1, two: "Two"}}
-example # => {a: "A", b: {one: "One", two: "Two"}}
+example.deep_merge! b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
+example                          # => {a: "A", b: {one: 1, two: "Two"}}
+----
 
-example = {a: "A", b: {one: "One", two: "Two"}}
-example.deep_merge! b: {one: 1} # => {a: "A", b: {one: 1, two: "Two"}}
-example # => {a: "A", b: {one: 1, two: "Two"}}
+===== #deep_stringify_keys
+
+Stringifies keys of nested hash without mutating itself. Does not handle nested arrays, though.
+
+[source,ruby]
+----
+example = {a: {b: 2}}
+example.deep_stringify_keys  # => {"a" => {"b" => 1}}
+example                      # => {a: {b: 2}}
+----
+
+===== #deep_stringify_keys!
+
+Stringifies keys of nested hash while mutating itself. Does not handle nested arrays, though.
+
+[source,ruby]
+----
+example = {a: {b: 2}}
+example.deep_stringify_keys!  # => {"a" => {"b" => 1}}
+example                       # => {"a" => {"b" => 1}}
+----
 
+===== #deep_symbolize_keys
+
+Symbolizes keys of nested hash without mutating itself. Does not handle nested arrays, though.
+
+[source,ruby]
+----
 example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys # => {a: {b: 1}}
-example # => {"a" => {"b" => 2}}
+example.deep_symbolize_keys  # => {a: {b: 1}}
+example                      # => {"a" => {"b" => 2}}
+----
+
+===== #deep_symbolize_keys!
+
+Symbolizes keys of nested hash while mutating itself. Does not handle nested arrays, though.
 
+[source,ruby]
+----
 example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys! # => {a: {b: 1}}
-example # => {a: {b: 1}}
+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.
+
+[source,ruby]
+----
 example = {"a" => {"b" => 1}}
-example.recurse(&:symbolize_keys) # => {a: {b: 1}}
-example.recurse(&:invert) # => {{"b" => 1} => "a"}
+example.recurse(&:symbolize_keys)  # => {a: {b: 1}}
+example.recurse(&:invert)          # => {{"b" => 1} => "a"}
+----
 
+===== #rekey
+
+Transforms keys per mapping (size of mapping can vary) without mutating itself.
+
+[source,ruby]
+----
 example = {a: 1, b: 2, c: 3}
-example.rekey a: :amber, b: :blue # => {amber: 1, blue: 2, c: 3}
-example # => {a: 1, b: 2, c: 3}
+example.rekey a: :amber, b: :blue  # => {amber: 1, blue: 2, c: 3}
+example                            # => {a: 1, b: 2, c: 3}
+----
+
+===== #rekey!
 
+Transforms keys per mapping (size of mapping can vary) while mutating itself.
+
+[source,ruby]
+----
 example = {a: 1, b: 2, c: 3}
-example.rekey! a: :amber, b: :blue # => {amber: 1, blue: 2, c: 3}
-example # => {amber: 1, blue: 2, c: 3}
+example.rekey! a: :amber, b: :blue  # => {amber: 1, blue: 2, c: 3}
+example                             # => {amber: 1, blue: 2, c: 3}
+----
+
+===== #reverse_merge
+
+Merges calling hash into passed in hash without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.reverse_merge a: 0, c: 3  # => {a: 1, b: 2, c: 3}
+example                           # => {a: 1, b: 2}
+----
+
+===== #reverse_merge!
 
+Merges calling hash into passed in hash while mutating itself.
+
+[source,ruby]
+----
+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.reverse_merge a: 0, c: 3 # => {a: 1, b: 2, c: 3}
-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.reverse_merge! a: 0, c: 3 # => {a: 1, b: 2, c: 3}
-example # => {a: 1, b: 2, c: 3}
+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]
+----
 example = {unit: "221B", street: "Baker Street", city: "London", country: "UK"}
 example.use { |unit, street| "#{unit} #{street}" } # => "221B Baker Street"
 ----
 
+==== IO
+
+===== .void
+
+Answers an IO stream which points to `/dev/null` in order to ignore any reads or writes to the
+stream. When given a block, the stream will automatically close upon block exit. When not given a
+block, you'll need to close the stream manually.
+
+[source,ruby]
+----
+io = IO.void
+io.closed? # => false
+
+io = IO.void { |void| void.write "nevermore" }
+io.closed? # => true
+----
+
+===== #redirect
+
+Redirects current stream to other stream when given a block. Without a block, the original stream is
+answered instead.
+
+[source,ruby]
+----
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+other = IO.new IO.sysopen(Pathname("other.txt").to_s, "w+")
+
+io.redirect other # => `io`
+
+io.redirect(other) { |stream| stream.write "test" }
+  .close    # => ""
+other.close # => "test"
+----
+
+===== #reread
+
+Answers full stream by rewinding to beginning of stream and reading all content.
+
+[source,ruby]
+----
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.write "This is a test."
+
+io.reread    # => "This is a test."
+io.reread 4  # => "This"
+
+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
+order to avoid: `TypeError (no implicit conversion of nil into String)`. The pathname is still
+invalid but at least you have an instance of `Pathname`, which behaves like a _Null Object_, that
+can still be used to construct a valid path.
+
 [source,ruby]
 ----
 Pathname(nil) # => Pathname("")
+----
 
-Pathname("example.txt").name # => Pathname("example")
+===== #change_dir
+
+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.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.
+
+[source,ruby]
+----
 Pathname("input.txt").copy Pathname("output.txt")
+----
+
+===== #directories
 
-Pathname("/example").directories # => [Pathname("a"), Pathname("b")]
-Pathname("/example").directories "a*" # => [Pathname("a")]
-Pathname("/example").directories flag: File::FNM_DOTMATCH # => [Pathname(".."), Pathname(".")]
+Answers all or filtered directories for current path.
 
+[source,ruby]
+----
+Pathname("/example").directories                           # => [Pathname("a"), Pathname("b")]
+Pathname("/example").directories "a*"                      # => [Pathname("a")]
+Pathname("/example").directories flag: File::FNM_DOTMATCH  # => [Pathname(".."), Pathname(".")]
+----
+
+===== #extensions
+
+Answers file extensions as an array.
+
+[source,ruby]
+----
 Pathname("example.txt.erb").extensions # => [".txt", ".erb"]
+----
+
+===== #files
+
+Answers all or filtered files for current path.
+
+[source,ruby]
+----
+Pathname("/example").files                           # => [Pathname("a.txt"), Pathname("a.png")]
+Pathname("/example").files "*.png"                   # => [Pathname("a.png")]
+Pathname("/example").files flag: File::FNM_DOTMATCH  # => [Pathname(".ruby-version")]
+----
+
+===== #gsub
+
+Same behavior as `String#gsub` but answers a path with patterns replaced with desired substitutes.
+
+[source,ruby]
+----
+Pathname("/a/path/some/path").gsub("path", "test")
+# => Pathname("/a/test/some/test")
 
-Pathname("/example").files # => [Pathname("a.txt"), Pathname("a.png")]
-Pathname("/example").files "*.png" # => [Pathname("a.png")]
-Pathname("/example").files flag: File::FNM_DOTMATCH # => [Pathname(".ruby-version")]
+Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test")
+# => Pathname("/test/some/test")
+----
 
-Pathname("/a/path/some/path").gsub("path", "test") # => Pathname("/a/test/some/test")
-Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test") # => Pathname("/test/some/test")
+===== #make_ancestors
 
-Pathname("/one/two/three").relative_parent_from("/one") # => Pathname "two"
+Ensures all ancestor directories are created for a path.
 
+[source,ruby]
+----
 Pathname("/one/two").make_ancestors
-Pathname("/one").exist? # => true
-Pathname("/one/two").exist? # => false
+Pathname("/one").exist?      # => true
+Pathname("/one/two").exist?  # => false
+----
+
+===== #make_dir
+
+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").make_dir           # => Pathname("/one")
+Pathname("/one").make_dir.make_dir  # => Pathname("/one")
+----
+
+===== #make_path
+
+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/two/three").make_path            # => Pathname("/one/two/three")
+Pathname("/one/two/three").make_path.make_path  # => Pathname("/one/two/three")
+----
+
+===== #name
+
+Answers file name without extension.
+
+[source,ruby]
+----
+Pathname("example.txt").name # => Pathname("example")
+----
+
+===== #relative_parent
+
+Answers relative path from parent directory. This is a complement to `#relative_path_from`.
+
+[source,ruby]
+----
+Pathname("/one/two/three").relative_parent("/one") # => Pathname "two"
+----
 
+===== #remove_dir
+
+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.
+
+[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]
+----
+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
+----
+
+===== #rewrite
+
+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]
+----
 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]
 ----
-"example".first # => "e"
-"example".first 4 # => "exam"
+" \n\t\r".blank? # => true
+----
 
-"instant".last # => "t"
-"instant".last 3 # => "ant"
+===== #camelcase
 
-" \n\t\r".blank? # => true
+Answers a camelcased string.
 
-"example".up # => "Example"
+[source,ruby]
+----
+"this_is_an_example".camelcase # => "ThisIsAnExample"
+----
 
+===== #down
+
+Answers string with only first letter downcased.
+
+[source,ruby]
+----
 "EXAMPLE".down # => "eXAMPLE"
+----
 
-"this_is_an_example".camelcase # => "ThisIsAnExample"
+===== #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]
+----
+"example".indent                  # => "  example"
+"example".indent 0                # => "example"
+"example".indent -1               # => "example"
+"example".indent 2                # => "    example"
+"example".indent 3, padding: " "  # => "   example"
+----
+
+===== #last
+
+Answers last character of a string or last set of characters if given a number.
+
+[source,ruby]
+----
+"instant".last    # => "t"
+"instant".last 3  # => "ant"
+----
+
+===== #snakecase
 
+Answers a snakecased string.
+
+[source,ruby]
+----
 "ThisIsAnExample".snakecase # => "this_is_an_example"
+----
+
+===== #titleize
+
+Answers titleized string.
 
+[source,ruby]
+----
 "ThisIsAnExample".titleize # => "This Is An Example"
+----
+
+===== #to_bool
+
+Answers string as a boolean.
+
+[source,ruby]
+----
+"true".to_bool     # => true
+"yes".to_bool      # => true
+"1".to_bool        # => true
+"".to_bool         # => false
+"example".to_bool  # => false
+----
 
-"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
+
+Answers full string by rewinding to beginning of string and reading all content.
+
 [source,ruby]
 ----
 io = StringIO.new
 io.write "This is a test."
-io.reread # => "This is a test."
 
-io.reread(4) => "This"
+io.reread    # => "This is a test."
+io.reread 4  # => "This"
 
 buffer = "".dup
 io.reread(buffer: buffer)
 buffer # => "This is a test."
 ----
 
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/refinements.git
+cd refinements
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
 == Tests
 
 To test, run: