pleasant_path 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6e26d3eb1ea19b636f25d9920be3aeb772175ce
-  data.tar.gz: 46c754d3523b1436d029fe0a0877e70a508becf7
+  metadata.gz: ddfbea700d9c72193add267fe9a09e88bc5d99ff
+  data.tar.gz: 7b5bce70e3faad80ac3296767a6cbd8b398a454e
 SHA512:
-  metadata.gz: 35f15a1f476b2dc68a1979fe72df5feed7b7cf41949eb98391379a36d92a40d1a3d6c72ea193965401796fa59b3e9021e70448321c6c7c7573c3d19d65ad563a
-  data.tar.gz: 69be2fb1dcfa1362aac1d56fedc5558b7800506ab1b5ae58c5b3e573cbc39188c0641323a0f1cdbe7f2396b6ecf67aca76d867169cecfb3c05ba28000ef8ac25
+  metadata.gz: fdf0eb05a7e27313ec2f0a9016319952c65a0931371b575fa4b72dd8959efc124db7272d3fd4c2d9bc35bde095839594110ce52be48de2ec467a6439f1b0a9bc
+  data.tar.gz: e67312af4aa40ed25954d05979983fe45a38f727c9810184e2a63eb45e7b6fb0c340ea5d765c10848143ad46cdccdd01ebefa199d06cbc576cc35fd0ae3df195

data/README.md

@@ -1,7 +1,7 @@
 # pleasant_path
 
 A [fluent API] for pleasant file IO, written as extensions to core Ruby
-objects.  See method listing below or browse the [full documentation].
+objects.  See API listing below, or browse the [full documentation].
 
 [fluent API]: https://en.wikipedia.org/wiki/Fluent_interface
 [full documentation]: http://www.rubydoc.info/gems/pleasant_path/
@@ -10,65 +10,115 @@ objects.  See method listing below or browse the [full documentation].
 ## Examples
 
 ```ruby
-# Dedup lines in a file
-"line_items.txt".path.edit_lines(&:uniq)
-
 # Filter lines across multiple files
 "logs/*.txt".glob.each do |log|
-  log.read_lines.grep(/Error/).append_to_file('errors.txt')
+  log.read_lines.grep(/^ERROR /).append_to_file("errors.txt")
 end
+
+# Dedup lines in a file
+"names.txt".path.edit_lines(&:uniq)
 ```
 
 
-## API Methods
+## Core API
+
+The following methods are available:
+
+- [Pathname](http://www.rubydoc.info/gems/pleasant_path/Pathname)
+  - [::NULL](http://www.rubydoc.info/gems/pleasant_path/Pathname#NULL-constant)
+  - [#^](http://www.rubydoc.info/gems/pleasant_path/Pathname:%5E)
+  - [#append_file](http://www.rubydoc.info/gems/pleasant_path/Pathname:append_file)
+  - [#append_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname:append_lines)
+  - [#append_text](http://www.rubydoc.info/gems/pleasant_path/Pathname:append_text)
+  - [#common_path](http://www.rubydoc.info/gems/pleasant_path/Pathname:common_path)
+  - [#copy](http://www.rubydoc.info/gems/pleasant_path/Pathname:copy)
+  - [#copy_into](http://www.rubydoc.info/gems/pleasant_path/Pathname:copy_into)
+  - [#delete!](http://www.rubydoc.info/gems/pleasant_path/Pathname:delete%21)
+  - [#dir?](http://www.rubydoc.info/gems/pleasant_path/Pathname:dir%3F)
+  - [#dir_empty?](http://www.rubydoc.info/gems/pleasant_path/Pathname:dir_empty%3F)
+  - [#dirs](http://www.rubydoc.info/gems/pleasant_path/Pathname:dirs)
+  - [#dirs_r](http://www.rubydoc.info/gems/pleasant_path/Pathname:dirs_r)
+  - [#edit_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname:edit_lines)
+  - [#edit_text](http://www.rubydoc.info/gems/pleasant_path/Pathname:edit_text)
+  - [#files](http://www.rubydoc.info/gems/pleasant_path/Pathname:files)
+  - [#files_r](http://www.rubydoc.info/gems/pleasant_path/Pathname:files_r)
+  - [#make_dir](http://www.rubydoc.info/gems/pleasant_path/Pathname:make_dir)
+  - [#make_dirname](http://www.rubydoc.info/gems/pleasant_path/Pathname:make_dirname)
+  - [#move](http://www.rubydoc.info/gems/pleasant_path/Pathname:move)
+  - [#move_into](http://www.rubydoc.info/gems/pleasant_path/Pathname:move_into)
+  - [#parentname](http://www.rubydoc.info/gems/pleasant_path/Pathname:parentname)
+  - [#read_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname:read_lines)
+  - [#rename_basename](http://www.rubydoc.info/gems/pleasant_path/Pathname:rename_basename)
+  - [#rename_extname](http://www.rubydoc.info/gems/pleasant_path/Pathname:rename_extname)
+  - [#to_pathname](http://www.rubydoc.info/gems/pleasant_path/Pathname:to_pathname)
+  - [#touch_file](http://www.rubydoc.info/gems/pleasant_path/Pathname:touch_file)
+  - [#write_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname:write_lines)
+  - [#write_text](http://www.rubydoc.info/gems/pleasant_path/Pathname:write_text)
+- [String](http://www.rubydoc.info/gems/pleasant_path/String)
+  - [#/](http://www.rubydoc.info/gems/pleasant_path/String:%2F)
+  - [#^](http://www.rubydoc.info/gems/pleasant_path/String:%5E)
+  - [#append_to_file](http://www.rubydoc.info/gems/pleasant_path/String:append_to_file)
+  - [#glob](http://www.rubydoc.info/gems/pleasant_path/String:glob)
+  - [#path](http://www.rubydoc.info/gems/pleasant_path/String:path)
+  - [#to_pathname](http://www.rubydoc.info/gems/pleasant_path/String:to_pathname)
+  - [#write_to_file](http://www.rubydoc.info/gems/pleasant_path/String:write_to_file)
+- [Array](http://www.rubydoc.info/gems/pleasant_path/Array)
+  - [#append_to_file](http://www.rubydoc.info/gems/pleasant_path/Array:append_to_file)
+  - [#write_to_file](http://www.rubydoc.info/gems/pleasant_path/Array:write_to_file)
+- [File](http://www.rubydoc.info/gems/pleasant_path/File)
+  - [.common_path](http://www.rubydoc.info/gems/pleasant_path/File.common_path)
+  - [.edit_lines](http://www.rubydoc.info/gems/pleasant_path/File.edit_lines)
+  - [.edit_text](http://www.rubydoc.info/gems/pleasant_path/File.edit_text)
+- [IO](http://www.rubydoc.info/gems/pleasant_path/IO)
+  - [#read_lines](http://www.rubydoc.info/gems/pleasant_path/IO:read_lines)
+  - [#write_lines](http://www.rubydoc.info/gems/pleasant_path/IO:write_lines)
+
+
+## JSON-related and YAML-related API
+
+*pleasant_path* also includes methods for interacting with JSON and YAML
+files, using the [JSON module] and [YAML module] that are part of Ruby's
+standard library.  Because Ruby does not load these modules by default,
+*pleasant_path* does not load its JSON-related and YAML-related API by
+default either.  To load these *pleasant_path* APIs **and** the relevant
+standard library modules, use:
+
+```ruby
+require "pleasant_path/json"
+require "pleasant_path/yaml"
+```
+
+[JSON module]: https://ruby-doc.org/stdlib/libdoc/json/rdoc/JSON.html
+[YAML module]: https://ruby-doc.org/stdlib/libdoc/yaml/rdoc/YAML.html
 
+The following methods are available:
+
+- Object
+  - [write_to_json](http://www.rubydoc.info/gems/pleasant_path/Object:write_to_json)
+  - [write_to_yaml](http://www.rubydoc.info/gems/pleasant_path/Object:write_to_yaml)
 - Pathname
-  - [^](http://www.rubydoc.info/gems/pleasant_path/Pathname%3A%5E)
-  - [append_file](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aappend_file)
-  - [append_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aappend_lines)
-  - [append_text](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aappend_text)
-  - [delete!](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Adelete%21)
-  - [dir_empty?](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Adir_empty%3F)
-  - [dirs](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Adirs)
-  - [dirs_r](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Adirs_r)
-  - [edit_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aedit_lines)
-  - [edit_text](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aedit_text)
-  - [files](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Afiles)
-  - [files_r](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Afiles_r)
-  - [make_dir](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Amake_dir)
-  - [make_dirname](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Amake_dirname)
-  - [move](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Amove)
-  - [move_into](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Amove_into)
-  - [parentname](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aparentname)
-  - [read_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Aread_lines)
-  - [to_pathname](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Ato_pathname)
-  - [touch_file](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Atouch_file)
-  - [write_lines](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Awrite_lines)
-  - [write_text](http://www.rubydoc.info/gems/pleasant_path/Pathname%3Awrite_text)
-- String
-  - [/](http://www.rubydoc.info/gems/pleasant_path/String%3A%2F)
-  - [^](http://www.rubydoc.info/gems/pleasant_path/String%3A%5E)
-  - [append_to_file](http://www.rubydoc.info/gems/pleasant_path/String%3Aappend_to_file)
-  - [glob](http://www.rubydoc.info/gems/pleasant_path/String%3Aglob)
-  - [to_pathname](http://www.rubydoc.info/gems/pleasant_path/String%3Ato_pathname)
-  - [write_to_file](http://www.rubydoc.info/gems/pleasant_path/String%3Awrite_to_file)
-- Array
-  - [append_to_file](http://www.rubydoc.info/gems/pleasant_path/Array%3Aappend_to_file)
-  - [write_to_file](http://www.rubydoc.info/gems/pleasant_path/Array%3Awrite_to_file)
-- File
-  - [edit_lines](http://www.rubydoc.info/gems/pleasant_path/File.edit_lines)
-  - [edit_text](http://www.rubydoc.info/gems/pleasant_path/File.edit_text)
-- IO
-  - [read_lines](http://www.rubydoc.info/gems/pleasant_path/IO%3Aread_lines)
-  - [write_lines](http://www.rubydoc.info/gems/pleasant_path/IO%3Awrite_lines)
+  - [load_json](http://www.rubydoc.info/gems/pleasant_path/Pathname:load_json)
+  - [load_yaml](http://www.rubydoc.info/gems/pleasant_path/Pathname:load_yaml)
+  - [read_json](http://www.rubydoc.info/gems/pleasant_path/Pathname:read_json)
+  - [read_yaml](http://www.rubydoc.info/gems/pleasant_path/Pathname:read_yaml)
 
 
 ## Installation
 
-    $ gem install pleasant_path
+Install from [Ruby Gems](https://rubygems.org/gems/pleasant_path):
+
+```bash
+$ gem install pleasant_path
+```
+
+Then require in your Ruby script:
+
+```ruby
+require "pleasant_path"
+```
 
 
-## Development
+## Contributing
 
 Run `rake test` to run the tests.  You can also run `rake irb` for an
 interactive prompt that pre-loads the project code.
@@ -76,4 +126,4 @@ interactive prompt that pre-loads the project code.
 
 ## License
 
-[MIT License](http://opensource.org/licenses/MIT)
+[MIT License](https://opensource.org/licenses/MIT)

data/lib/pleasant_path/array.rb

@@ -5,6 +5,10 @@ class Array
   # The file is overwritten if it already exists.  Any necessary parent
   # directories are created if they do not exist.
   #
+  # @example
+  #   [:one, :two].write_to_file("out.txt")  # == [:one, :two]
+  #   File.read("out.txt")                   # == "one\ntwo\n"
+  #
   # @param file [String, Pathname]
   # @return [Array]
   def write_to_file(file)
@@ -17,6 +21,12 @@ class Array
   # The file is created if it does not exist.  Any necessary parent
   # directories are created if they do not exist.
   #
+  # @example
+  #   [:one, :two].append_to_file("out.txt")     # == [:one, :two]
+  #   File.read("out.txt")                       # == "one\ntwo\n"
+  #   [:three, :four].append_to_file("out.txt")  # == [:three, :four]
+  #   File.read("out.txt")                       # == "one\ntwo\nthree\nfour\n"
+  #
   # @param file [String, Pathname]
   # @return [Array]
   def append_to_file(file)

data/lib/pleasant_path/file.rb

@@ -1,10 +1,42 @@
 class File
 
+  # Computes the longest path that every path in a list has in common.
+  #
+  # @example
+  #   File.common_path(["a/b/x", "a/b/y", "a/b/z"])  # == "a/b/"
+  #   File.common_path(["a/b/x", "a/b/y", "a/z"])    # == "a/"
+  #   File.common_path(["a/b/x", "a/b/y", "a"])      # == "a"
+  #
+  # @param paths [Enumerable<String>]
+  # @return [String]
+  def self.common_path(paths)
+    return paths.first if paths.length <= 1
+    short, long = paths.minmax
+    i = 0
+    last = -1
+    while i < short.length && short[i] == long[i]
+      last = i if short[i] == "/".freeze
+      i += 1
+    end
+    short[0, i == short.length ? i : (last + 1)]
+  end
+
   # Reads from the specified file its contents as a string, and yields
   # the string to the given block for editing.  Writes the return value
   # of the block back to the file, overwriting previous contents.
   # Returns the file's new contents.
   #
+  # @example update JSON data file
+  #   File.read("data.json")  # == '{"nested":{"key":"value"}}'
+  #
+  #   File.edit_text("data.json") do |text|
+  #     data = JSON.parse(text)
+  #     data["nested"]["key"] = "new value"
+  #     data.to_json
+  #   end                     # == '{"nested":{"key":"new value"}}'
+  #
+  #   File.read("data.json")  # == '{"nested":{"key":"new value"}}'
+  #
   # @param filename [String, Pathname]
   # @yield [text] edits current file contents
   # @yieldparam text [String] current contents
@@ -15,6 +47,7 @@ class File
       text = yield f.read
       f.seek(0, IO::SEEK_SET)
       f.write(text)
+      f.truncate(f.pos)
       text
     end
   end
@@ -26,6 +59,14 @@ class File
   # characters to use for both reading and writing.  Returns the array
   # of lines that comprises the file's new contents.
   #
+  # @example dedup lines of file
+  #   File.read("entries.txt")  # == "AAA\nBBB\nBBB\nCCC\nAAA\n"
+  #
+  #   File.edit_lines("entries.txt", &:uniq)
+  #     # == ["AAA", "BBB", "CCC"]
+  #
+  #   File.read("entries.txt")  # == "AAA\nBBB\nCCC\n"
+  #
   # @param filename [String, Pathname]
   # @yield [lines] edits current file contents
   # @yieldparam lines [Array<String>] current contents
@@ -36,6 +77,8 @@ class File
       lines = yield f.read_lines
       f.seek(0, IO::SEEK_SET)
       f.write_lines(lines)
+      f.truncate(f.pos)
+      lines
     end
   end
 

data/lib/pleasant_path/io.rb

@@ -1,10 +1,18 @@
 class IO
 
-  # Writes each string plus a succeeding new line character
-  # (<code>$/</code>) to the IO.  Returns the lines unmodified.
+  # Writes each object as a string plus a succeeding new line character
+  # (<code>$/</code>) to the IO.  Returns the objects unmodified.
   #
-  # @param lines [Array<String>]
-  # @return [Array<String>]
+  # @example
+  #   # NOTE File inherits from IO
+  #   File.open("out.txt") do |file|
+  #     file.write_lines([:one, :two])  # == [:one, :two]
+  #   end                               # == [:one, :two]
+  #
+  #   File.read("out.txt")              # == "one\ntwo\n"
+  #
+  # @param lines [Enumerable<#to_s>]
+  # @return [Enumerable<#to_s>]
   def write_lines(lines)
     lines.each do |line|
       self.write(line)
@@ -16,11 +24,19 @@ class IO
 
   # Reads from the IO all lines, and returns them as an array,
   # end-of-line characters excluded.  The <code>$/</code> global string
-  # specifies what end-of-line characters to look for.
+  # specifies what end-of-line characters to exclude.
   #
   # (Not to be confused with +IO#readlines+ which retains end-of-line
   # characters in every string it returns.)
   #
+  # @example
+  #   # NOTE File inherits from IO
+  #   File.read("in.txt")            # == "one\ntwo\n"
+  #
+  #   File.open("in.txt") do |file|
+  #     file.read_lines              # == ["one", "two"]
+  #   end                            # == ["one", "two"]
+  #
   # @return [Array<String>]
   def read_lines
     self.readlines.each(&:chomp!)

data/lib/pleasant_path/json/object.rb

@@ -0,0 +1,27 @@
+class Object
+
+  # Dumps the Object as JSON, and writes the JSON to the specified file.
+  # Returns the Object unmodified.
+  #
+  # For information about available options see
+  # {http://ruby-doc.org/stdlib/libdoc/json/rdoc/JSON.html#method-i-generate
+  # +JSON.generate+}.
+  #
+  # @example
+  #   { "key" => "value" }.write_to_json("out.json")  # == { "key" => "value" }
+  #   File.read("out.json")                           # == '{"key":"value"}'
+  #
+  # @param file [String, Pathname]
+  # @param options [Hash]
+  # @return [self]
+  def write_to_json(file, options = {})
+    options = {
+      quirks_mode: true,
+      allow_nan: true,
+    }.merge(options)
+
+    file.to_pathname.write_text(JSON.generate(self, options))
+    self
+  end
+
+end

data/lib/pleasant_path/json/pathname.rb

@@ -0,0 +1,58 @@
+class Pathname
+
+  # Reads the contents of the file indicated by the Pathname, and parses
+  # it as JSON.  The returned result will be a basic Ruby data
+  # structure, namely, one of: +nil+, +true+, +false+, a +Numeric+, a
+  # +String+, an +Array+, or a +Hash+.
+  #
+  # For information about available options, see
+  # {http://ruby-doc.org/stdlib/libdoc/json/rdoc/JSON.html#method-i-parse
+  # +JSON.parse+}.
+  #
+  # @example
+  #   File.write("in.json", '{"key": "value"}')
+  #
+  #   Pathname.new("in.json").read_json  # == { "key" => "value" }
+  #
+  # @param options [Hash]
+  # @return [nil, true, false, Numeric, String, Symbol, Array, Hash]
+  def read_json(options = {})
+    options = {
+      quirks_mode: true,
+      allow_nan: true,
+      max_nesting: false,
+      create_additions: false,
+    }.merge(options)
+
+    JSON.parse(self.read_text, options)
+  end
+
+  # Reads the contents of the file indicated by the Pathname, and parses
+  # it as JSON.  The parser will use type information embedded in the
+  # JSON to deserialize custom types.  This is *UNSAFE* for JSON from
+  # an untrusted source.  To consume untrusted JSON, use
+  # {Pathname#read_json} instead.
+  #
+  # For information about available options, see
+  # {http://ruby-doc.org/stdlib/libdoc/json/rdoc/JSON.html#method-i-parse
+  # +JSON.parse+}.
+  #
+  # For information about serializing custom types to JSON, see the
+  # {https://github.com/flori/json/blob/master/README.md#more-examples
+  # JSON readme}.
+  #
+  # @example
+  #   require "json/add/core" # provides Struct#to_json
+  #   Point = Struct.new(:x, :y)
+  #   point = Point.new(10, 20)
+  #   File.write("in.json", point.to_json)
+  #
+  #   Pathname.new("in.json").load_json  # == Point.new(10, 20)
+  #
+  # @param options [Hash]
+  # @return deserialized object
+  def load_json(options = {})
+    self.open('r'){|f| JSON.load(f, nil, options) }
+  end
+
+end

data/lib/pleasant_path/json.rb

@@ -0,0 +1,4 @@
+require "json"
+require "pleasant_path"
+require_relative "json/object"
+require_relative "json/pathname"

data/lib/pleasant_path/pathname.rb

@@ -1,7 +1,12 @@
 class Pathname
 
+  # {https://ruby-doc.org/core/File/Constants.html#NULL +File::NULL+} as
+  # a Pathname.  On POSIX systems, this should be equivalent to
+  # +Pathname.new("/dev/null")+.
+  NULL = Pathname.new(File::NULL)
+
   # Returns the Pathname unmodified.  Exists for parity with
-  # +String#to_pathname+.
+  # {String#to_pathname}.
   #
   # @return [Pathname]
   def to_pathname
@@ -14,7 +19,7 @@ class Pathname
   # specified by the argument.
   #
   # @example
-  #   (Pathname.new("path/to/file1") ^ "file2").to_s #=> "path/to/file2"
+  #   Pathname.new("path/to/file1") ^ "file2"  # == Pathname.new("path/to/file2")
   #
   # @param sibling [Pathname, String]
   # @return [Pathname]
@@ -25,13 +30,34 @@ class Pathname
   # Returns the +basename+ of the Pathname's parent directory.
   #
   # @example
-  #   Pathname.new("path/to/file").parentname.to_s #=> "to"
+  #   Pathname.new("path/to/file").parentname  # == Pathname.new("to")
   #
   # @return [Pathname]
   def parentname
     self.dirname.basename
   end
 
+  # Computes the longest path that the Pathname and +other+ have in
+  # common.  See also {File.common_path}.
+  #
+  # @example
+  #   f1 = Pathname.new("dir1/file1")
+  #   f2 = Pathname.new("dir1/subdir1/file2")
+  #   f3 = Pathname.new("dir1/subdir1/file3")
+  #   f4 = Pathname.new("dir2/file4")
+  #
+  #   f1.common_path(f2)  # == Pathname.new("dir1/")
+  #   f2.common_path(f3)  # == Pathname.new("dir1/subdir1/")
+  #   f3.common_path(f4)  # == Pathname.new("")
+  #
+  #   [f1, f2, f3].reduce(&:common_path)  # == Pathname.new("dir1/")
+  #
+  # @param other [Pathname]
+  # @return [Pathname]
+  def common_path(other)
+    File.common_path([self.to_s, other.to_s]).to_pathname
+  end
+
   # Alias of +Pathname#directory?+.
   #
   # @return [Boolean]
@@ -40,6 +66,13 @@ class Pathname
   # True if the directory indicated by the Pathname contains no other
   # directories or files.
   #
+  # @example
+  #   FileUtils.mkdir("parent")
+  #   FileUtils.mkdir("parent/dir1")
+  #
+  #   Pathname.new("parent").dir_empty?       # == false
+  #   Pathname.new("parent/dir1").dir_empty?  # == true
+  #
   # @return [Boolean]
   def dir_empty?
     self.children(false).empty?
@@ -49,6 +82,18 @@ class Pathname
   # directory indicated by the Pathname.  Returned Pathnames are
   # prefixed by the original Pathname.
   #
+  # @example
+  #   FileUtils.mkdir("parent")
+  #   FileUtils.mkdir("parent/dir1")
+  #   FileUtils.mkdir("parent/dir2")
+  #   FileUtils.touch("parent/file1")
+  #
+  #   Pathname.new("parent").dirs
+  #     # == [
+  #     #      Pathname.new("parent/dir1"),
+  #     #      Pathname.new("parent/dir2")
+  #     #    ]
+  #
   # @return [Array<Pathname>]
   def dirs
     self.children.tap{|c| c.select!(&:dir?) }
@@ -58,6 +103,20 @@ class Pathname
   # directory indicated by the Pathname.  Returned Pathnames are
   # prefixed by the original Pathname.
   #
+  # @example
+  #   FileUtils.mkdir("parent")
+  #   FileUtils.mkdir("parent/dir1")
+  #   FileUtils.mkdir("parent/dir1/dir1")
+  #   FileUtils.mkdir("parent/dir2")
+  #   FileUtils.touch("parent/dir2/file1")
+  #
+  #   Pathname.new("parent").dirs_r
+  #     # == [
+  #     #      Pathname.new("parent/dir1"),
+  #     #      Pathname.new("parent/dir1/dir1"),
+  #     #      Pathname.new("parent/dir2")
+  #     #    ]
+  #
   # @return [Array<Pathname>]
   def dirs_r
     self.find.select(&:dir?).tap(&:shift)
@@ -67,6 +126,18 @@ class Pathname
   # indicated by the Pathname.  Returned Pathnames are prefixed by the
   # original Pathname.
   #
+  # @example
+  #   FileUtils.mkdir("parent")
+  #   FileUtils.touch("parent/file1")
+  #   FileUtils.touch("parent/file2")
+  #   FileUtils.mkdir("parent/dir1")
+  #
+  #   Pathname.new("parent").files
+  #     # == [
+  #     #      Pathname.new("parent/file1"),
+  #     #      Pathname.new("parent/file2")
+  #     #    ]
+  #
   # @return [Array<Pathname>]
   def files
     self.children.tap{|c| c.select!(&:file?) }
@@ -76,6 +147,18 @@ class Pathname
   # indicated by the Pathname.  Returned Pathnames are prefixed by the
   # original Pathname.
   #
+  # @example
+  #   FileUtils.mkdir("parent")
+  #   FileUtils.mkdir("parent/dir1")
+  #   FileUtils.touch("parent/dir1/file1")
+  #   FileUtils.touch("parent/file1")
+  #
+  #   Pathname.new("parent").files_r
+  #     # == [
+  #     #      Pathname.new("parent/dir1/file1"),
+  #     #      Pathname.new("parent/file1")
+  #     #    ]
+  #
   # @return [Array<Pathname>]
   def files_r
     self.find.select(&:file?)
@@ -83,6 +166,15 @@ class Pathname
 
   # Alias of +Pathname#mkpath+, but this method returns the Pathname.
   #
+  # @example
+  #   Dir.exist?("path")                # == false
+  #   Dir.exist?("path/to")             # == false
+  #
+  #   Pathname.new("path/to").make_dir  # == Pathname.new("path/to")
+  #
+  #   Dir.exist?("path")                # == true
+  #   Dir.exist?("path/to")             # == true
+  #
   # @return [Pathname]
   def make_dir
     self.mkpath
@@ -92,6 +184,16 @@ class Pathname
   # Creates the parent (+dirname+) directories of the Pathname if they
   # do not exist, and returns the Pathname.
   #
+  # @example
+  #   Dir.exist?("path")                         # == false
+  #   Dir.exist?("path/to")                      # == false
+  #
+  #   Pathname.new("path/to/file").make_dirname  # == Pathname.new("path/to/file")
+  #
+  #   Dir.exist?("path")                         # == true
+  #   Dir.exist?("path/to")                      # == true
+  #   Dir.exist?("path/to/file")                 # == false
+  #
   # @return [Pathname]
   def make_dirname
     self.dirname.make_dir
@@ -103,6 +205,16 @@ class Pathname
   # the file and any necessary parent directories if they do not exist.
   # See also +FileUtils.touch+.
   #
+  # @example
+  #   Dir.exist?("path")                       # == false
+  #   Dir.exist?("path/to")                    # == false
+  #
+  #   Pathname.new("path/to/file").touch_file  # == Pathname.new("path/to/file")
+  #
+  #   Dir.exist?("path")                       # == true
+  #   Dir.exist?("path/to")                    # == true
+  #   File.exist?("path/to/file")              # == true
+  #
   # @return [Pathname]
   def touch_file
     self.make_dirname
@@ -114,28 +226,66 @@ class Pathname
   # and returns the Pathname.  Similar to +Pathname#rmtree+, but does
   # not raise an exception if the file does not exist.
   #
+  # @example
+  #   File.exist?("path/to/file")   # == true
+  #
+  #   Pathname.new("path").delete!  # == Pathname.new("path")
+  #
+  #   Dir.exist?("path")            # == false
+  #   Dir.exist?("path/to")         # == false
+  #   File.exist?("path/to/file")   # == false
+  #
   # @return [Pathname]
   def delete!
     self.rmtree if self.exist?
     self
   end
 
-  # Moves the file indicated by Pathname to the given destination, and
-  # returns that destination as a Pathname.  Creates any necessary
-  # parent directories if they do not exist.
+  # Moves the file or directory indicated by the Pathname to the given
+  # destination, and returns that destination as a Pathname.  Creates
+  # any necessary parent directories if they do not exist.  See also
+  # +FileUtils.mv+.
+  #
+  # @example
+  #   File.exist?("path/to/file")      # == true
+  #   Dir.exist?("some")               # == false
+  #   Dir.exist?("some/other")         # == false
+  #   File.exist?("some/other/thing")  # == false
+  #
+  #   Pathname.new("path/to/file").move("some/other/thing")
+  #     # == Pathname.new("some/other/thing")
+  #
+  #   File.exist?("path/to/file")      # == false
+  #   Dir.exist?("some")               # == true
+  #   Dir.exist?("some/other")         # == true
+  #   File.exist?("some/other/thing")  # == true
   #
   # @param destination [Pathname, String]
   # @return [Pathname]
   def move(destination)
     destination = destination.to_pathname
     destination.make_dirname
-    self.rename(destination)
+    FileUtils.mv(self, destination)
     destination
   end
 
-  # Moves the file indicated by Pathname into the given directory, and
-  # returns the resultant path to the file as a Pathname.  Creates any
-  # necessary parent directories if they do not exist.
+  # Moves the file or directory indicated by the Pathname into the given
+  # directory, and returns the resultant path as a Pathname.  Creates
+  # any necessary parent directories if they do not exist.
+  #
+  # @example
+  #   File.exist?("path/to/file")     # == true
+  #   Dir.exist?("other")             # == false
+  #   Dir.exist?("other/path")        # == false
+  #   File.exist?("other/path/file")  # == false
+  #
+  #   Pathname.new("path/to/file").move_into("other/path")
+  #     # == Pathname.new("other/path/file")
+  #
+  #   File.exist?("path/to/file")     # == false
+  #   Dir.exist?("other")             # == true
+  #   Dir.exist?("other/path")        # == true
+  #   File.exist?("other/path/file")  # == true
   #
   # @param directory [Pathname, String]
   # @return [Pathname]
@@ -143,10 +293,121 @@ class Pathname
     self.move(directory / self.basename)
   end
 
+  # Copies the file or directory indicated by the Pathname to the given
+  # destination, and returns that destination as a Pathname.  Creates
+  # any necessary parent directories if they do not exist.  See also
+  # +FileUtils.cp_r+.
+  #
+  # @example
+  #   File.exist?("path/to/file")      # == true
+  #   Dir.exist?("some")               # == false
+  #   Dir.exist?("some/other")         # == false
+  #   File.exist?("some/other/thing")  # == false
+  #
+  #   Pathname.new("path/to/file").copy("some/other/thing")
+  #     # == Pathname.new("some/other/thing")
+  #
+  #   File.exist?("path/to/file")      # == true
+  #   Dir.exist?("some")               # == true
+  #   Dir.exist?("some/other")         # == true
+  #   File.exist?("some/other/thing")  # == true
+  #
+  # @param destination [Pathname, String]
+  # @return [Pathname]
+  def copy(destination)
+    destination = destination.to_pathname
+    destination.make_dirname
+    FileUtils.cp_r(self, destination)
+    destination
+  end
+
+  # Copies the file or directory indicated by the Pathname into the
+  # given directory, and returns the resultant path as a Pathname.
+  # Creates any necessary parent directories if they do not exist.
+  #
+  # @example
+  #   File.exist?("path/to/file")     # == true
+  #   Dir.exist?("other")             # == false
+  #   Dir.exist?("other/path")        # == false
+  #   File.exist?("other/path/file")  # == false
+  #
+  #   Pathname.new("path/to/file").copy_into("other/path")
+  #     # == Pathname.new("other/path/file")
+  #
+  #   File.exist?("path/to/file")     # == true
+  #   Dir.exist?("other")             # == true
+  #   Dir.exist?("other/path")        # == true
+  #   File.exist?("other/path/file")  # == true
+  #
+  # @param directory [Pathname, String]
+  # @return [Pathname]
+  def copy_into(directory)
+    self.copy(directory / self.basename)
+  end
+
+  # Renames the file or directory indicated by the Pathname, but
+  # preserves its location as indicated by +dirname+.  Returns the
+  # resultant path as a Pathname.
+  #
+  # @example
+  #   File.exist?("path/to/file")   # == true
+  #
+  #   Pathname.new("path/to/file").rename_basename("other")
+  #     # == Pathname.new("path/to/other")
+  #
+  #   File.exist?("path/to/file")   # == false
+  #   File.exist?("path/to/other")  # == true
+  #
+  # @param new_basename [String]
+  # @return [Pathname]
+  def rename_basename(new_basename)
+    self.move(self.dirname / new_basename)
+  end
+
+  # Renames the file extension of the file indicated by the Pathname.
+  # If the file has no extension, the new extension is appended.
+  #
+  # @example replace extension
+  #   File.exist?("path/to/file.abc")   # == true
+  #
+  #   Pathname.new("path/to/file.abc").rename_extname(".xyz")
+  #     # == Pathname.new("path/to/file.xyz")
+  #
+  #   File.exist?("path/to/file.abc")   # == false
+  #   File.exist?("path/to/file.xyz")   # == true
+  #
+  # @example remove extension
+  #   File.exist?("path/to/file.abc")   # == true
+  #
+  #   Pathname.new("path/to/file.abc").rename_extname("")
+  #     # == Pathname.new("path/to/file")
+  #
+  #   File.exist?("path/to/file.abc")   # == false
+  #   File.exist?("path/to/file")       # == true
+  #
+  # @param new_extname [String]
+  # @return [Pathname]
+  def rename_extname(new_extname)
+    unless new_extname.start_with?(".") || new_extname.empty?
+      new_extname = ".#{new_extname}"
+    end
+    self.move(self.sub_ext(new_extname))
+  end
+
   # Writes given text to the file indicated by the Pathname, and returns
   # the Pathname.  The file is overwritten if it already exists.  Any
   # necessary parent directories are created if they do not exist.
   #
+  # @example
+  #   Dir.exist?("path")           # == false
+  #   Dir.exist?("path/to")        # == false
+  #   File.exist?("path/to/file")  # == false
+  #
+  #   Pathname.new("path/to/file").write_text("hello world")
+  #     # == Pathname.new("path/to/file")
+  #
+  #   File.read("path/to/file")    # == "hello world"
+  #
   # @param text [String]
   # @return [Pathname]
   def write_text(text)
@@ -158,6 +419,16 @@ class Pathname
   # returns the Pathname.  The file is created if it does not exist.
   # Any necessary parent directories are created if they do not exist.
   #
+  # @example
+  #   Dir.exist?("path")           # == false
+  #   Dir.exist?("path/to")        # == false
+  #   File.exist?("path/to/file")  # == false
+  #
+  #   Pathname.new("path/to/file").append_text("hello").append_text(" world")
+  #     # == Pathname.new("path/to/file")
+  #
+  #   File.read("path/to/file")    # == "hello world"
+  #
   # @param text [String]
   # @return [Pathname]
   def append_text(text)
@@ -165,25 +436,40 @@ class Pathname
     self
   end
 
-  # Writes given lines of text to the file indicated by the Pathname,
-  # and returns the Pathname.  A new line character (<code>$/</code>) is
-  # written after each line.  The file is overwritten if it already
-  # exists.  Any necessary parent directories are created if they do not
-  # exist.
+  # Writes each object as a string plus a succeeding new line character
+  # (<code>$/</code>) to the file indicated by the Pathname.  Returns
+  # the Pathname.  The file is overwritten if it already exists.  Any
+  # necessary parent directories are created if they do not exist.
   #
-  # @param lines [Array<String>]
+  # @example
+  #   File.exist?("path/to/file")  # false
+  #
+  #   Pathname.new("path/to/file").write_lines([:one, :two])
+  #     # == Pathname.new("path/to/file")
+  #
+  #   File.read("path/to/file")    # == "one\ntwo\n"
+  #
+  # @param lines [Enumerable<#to_s>]
   # @return [Pathname]
   def write_lines(lines)
     self.make_dirname.open('w'){|f| f.write_lines(lines) }
     self
   end
 
-  # Appends given lines of text to the file indicated by the Pathname,
-  # and returns the Pathname.  A new line character (<code>$/</code>) is
-  # written after each line.  The file is created if it does not exist.
-  # Any necessary parent directories are created if they do not exist.
+  # Appends each object as a string plus a succeeding new line character
+  # (<code>$/</code>) to the file indicated by the Pathname.  Returns
+  # the Pathname.  The file is created if it does not exist.  Any
+  # necessary parent directories are created if they do not exist.
   #
-  # @param lines [Array<String>]
+  # @example
+  #   File.exist?("path/to/file")  # false
+  #
+  #   Pathname.new("path/to/file").append_lines([:one, :two]).append_lines([:three, :four])
+  #     # == Pathname.new("path/to/file")
+  #
+  #   File.read("path/to/file")    # == "one\ntwo\nthree\nfour\n"
+  #
+  # @param lines [Enumerable<#to_s>]
   # @return [Pathname]
   def append_lines(lines)
     self.make_dirname.open('a'){|f| f.write_lines(lines) }
@@ -198,11 +484,16 @@ class Pathname
   # Reads from the file indicated by the Pathname all lines, and returns
   # them as an array, end-of-line characters excluded.  The
   # <code>$/</code> global string specifies what end-of-line characters
-  # to look for.  See also +IO#read_lines+.
+  # to look for.  See also {IO#read_lines}.
   #
   # (Not to be confused with +Pathname#readlines+ which retains
   # end-of-line characters in every string it returns.)
   #
+  # @example
+  #   File.read("path/to/file")                # == "one\ntwo\n"
+  #
+  #   Pathname.new("path/to/file").read_lines  # == ["one", "two"]
+  #
   # @return [Array<String>]
   def read_lines
     self.open('r'){|f| f.read_lines }
@@ -212,14 +503,18 @@ class Pathname
   # as a string, and yields the string to the given block for editing.
   # Writes the return value of the block back to the file, overwriting
   # previous contents.  Returns the file's new contents.  See also
-  # +File.edit_text+.
+  # {File.edit_text}.
+  #
+  # @example update JSON data file
+  #   File.read("data.json")  # == '{"nested":{"key":"value"}}'
   #
-  # @example Update YAML data file
-  #   path.edit_text do |text|
-  #     data = YAML.load(text)
-  #     data['deeply']['nested']['key'] = 'new value'
-  #     data.to_yaml
-  #   end
+  #   Pathname.new("data.json").edit_text do |text|
+  #     data = JSON.parse(text)
+  #     data["nested"]["key"] = "new value"
+  #     data.to_json
+  #   end                     # == '{"nested":{"key":"new value"}}'
+  #
+  #   File.read("data.json")  # == '{"nested":{"key":"new value"}}'
   #
   # @yield [text] edits current file contents
   # @yieldparam text [String] current contents
@@ -235,10 +530,15 @@ class Pathname
   # overwriting previous contents.  The <code>$/</code> global string
   # specifies what end-of-line characters to use for both reading and
   # writing.  Returns the array of lines that comprises the file's new
-  # contents.  See also +File.edit_lines+.
+  # contents.  See also {File.edit_lines}.
+  #
+  # @example dedup lines of file
+  #   File.read("entries.txt")  # == "AAA\nBBB\nBBB\nCCC\nAAA\n"
   #
-  # @example Dedup lines of file
-  #   path.edit_lines(&:uniq)
+  #   Pathname.new("entries.txt").edit_lines(&:uniq)
+  #     # == ["AAA", "BBB", "CCC"]
+  #
+  #   File.read("entries.txt")  # == "AAA\nBBB\nCCC\n"
   #
   # @yield [lines] edits current file contents
   # @yieldparam lines [Array<String>] current contents
@@ -251,6 +551,15 @@ class Pathname
   # Appends the contents of another file to the destination indicated by
   # Pathname.  Returns the destination Pathname.
   #
+  # @example
+  #   File.read("yearly.log")  # == "one\ntwo\n"
+  #   File.read("daily.log")   # == "three\nfour\n"
+  #
+  #   Pathname.new("yearly.log").append_file("daily.log")
+  #     # == Pathname.new("yearly.log")
+  #
+  #   File.read("yearly.log")  # == "one\ntwo\nthree\nfour\n"
+  #
   # @param source [String, Pathname]
   # @return [Pathname]
   def append_file(source)

data/lib/pleasant_path/string.rb

@@ -2,12 +2,15 @@ class String
 
   # Converts the string to a +Pathname+ object.
   #
+  # @example
+  #   "path/to/file".to_pathname  # == Pathname.new("path/to/file")
+  #
   # @return [Pathname]
   def to_pathname
     Pathname.new(self)
   end
 
-  # Alias of +String#to_pathname+.
+  # Alias of {String#to_pathname}.
   #
   # @return [Pathname]
   alias :path :to_pathname
@@ -16,7 +19,7 @@ class String
   # +File.join+) and returns the result as a +Pathname+ object.
   #
   # @example
-  #   ("path/to" / "file").to_s #=> "path/to/file"
+  #   "path/to" / "file"  # == Pathname.new("path/to/file")
   #
   # @param child [String]
   # @return [Pathname]
@@ -28,10 +31,10 @@ class String
   # path with the argument, and returns the result as a +Pathname+
   # object.  The mnenomic for this operator is that the resultant path
   # goes up one directory level from the original, then goes down to the
-  # directory specified by the argument.  See also +Pathname#^+.
+  # directory specified by the argument.  See also {Pathname#^}.
   #
   # @example
-  #   ("path/to/file1" ^ "file2").to_s #=> "path/to/file2"
+  #   "path/to/file1" ^ "file2"  # == Pathname.new("path/to/file2")
   #
   # @param sibling [Pathname, String]
   # @return [Pathname]
@@ -43,6 +46,9 @@ class String
   # into matching paths as +Pathname+ objects.  See also +Dir.glob+ and
   # +Pathname.glob+.
   #
+  # @example
+  #   "*.txt".glob  # == Pathname.glob("*.txt")
+  #
   # @return [Array<Pathname>]
   def glob
     Pathname.glob(self)
@@ -52,6 +58,10 @@ class String
   # file is overwritten if it already exists.  Any necessary parent
   # directories are created if they do not exist.
   #
+  # @example
+  #   "hello world".write_to_file("out.txt")  # == "hello world"
+  #   File.read("out.txt")                    # == "hello world"
+  #
   # @param file [String, Pathname]
   # @return [String]
   def write_to_file(file)
@@ -63,6 +73,12 @@ class String
   # file is created if it does not exist.  Any necessary parent
   # directories are created if they do not exist.
   #
+  # @example
+  #   "hello".append_to_file("out.txt")   # == "hello"
+  #   File.read("out.txt")                # == "hello"
+  #   " world".append_to_file("out.txt")  # == " world"
+  #   File.read("out.txt")                # == "hello world"
+  #
   # @param file [String, Pathname]
   # @return [String]
   def append_to_file(file)

data/lib/pleasant_path/version.rb

@@ -1,3 +1,3 @@
 module PleasantPath
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/pleasant_path/yaml/object.rb

@@ -0,0 +1,22 @@
+class Object
+
+  # Dumps the Object as YAML, and writes the YAML to the specified file.
+  # Returns the Object unmodified.
+  #
+  # For information about available options see
+  # {https://ruby-doc.org/stdlib/libdoc/psych/rdoc/Psych.html#method-c-dump
+  # +YAML.dump+}.
+  #
+  # @example
+  #   { "key" => "value" }.write_to_yaml("out.yaml")  # == { "key" => "value" }
+  #   File.read("out.yaml")                           # == "---\nkey: value\n"
+  #
+  # @param file [String, Pathname]
+  # @param options [Hash]
+  # @return [self]
+  def write_to_yaml(file, options = {})
+    File.open(file, 'w'){|f| YAML.dump(self, f, options) }
+    self
+  end
+
+end

data/lib/pleasant_path/yaml/pathname.rb

@@ -0,0 +1,36 @@
+class Pathname
+
+  # Reads the contents of the file indicated by the Pathname, and parses
+  # it as YAML.  The returned result will be a basic Ruby data
+  # structure, namely, one of: +nil+, +true+, +false+, a +Numeric+, a
+  # +String+, an +Array+, or a +Hash+.
+  #
+  # @example
+  #   File.write("in.yaml", "key: value")
+  #
+  #   Pathname.new("in.yaml").read_yaml  # == { "key" => "value" }
+  #
+  # @return [nil, true, false, Numeric, String, Array, Hash]
+  def read_yaml
+    self.open('r'){|f| YAML.safe_load(f, [], [], false, self) }
+  end
+
+  # Reads the contents of the file indicated by the Pathname, and parses
+  # it as YAML.  The parser will use type information embedded in the
+  # YAML to deserialize custom types.  This is *UNSAFE* for YAML from
+  # an untrusted source.  To consume untrusted YAML, use
+  # {Pathname#read_yaml} instead.
+  #
+  # @example
+  #   Point = Struct.new(:x, :y)
+  #   point = Point.new(10, 20)
+  #   File.write("in.yaml", point.to_yaml)
+  #
+  #   Pathname.new("in.yaml").load_yaml  # == Point.new(10, 20)
+  #
+  # @return deserialized object
+  def load_yaml
+    YAML.load_file(self)
+  end
+
+end

data/lib/pleasant_path/yaml.rb

@@ -0,0 +1,4 @@
+require "yaml"
+require "pleasant_path"
+require_relative "yaml/object"
+require_relative "yaml/pathname"

data/lib/pleasant_path.rb

@@ -1,7 +1,7 @@
-require 'pathname'
-require 'pleasant_path/version'
-require 'pleasant_path/array'
-require 'pleasant_path/file'
-require 'pleasant_path/io'
-require 'pleasant_path/pathname'
-require 'pleasant_path/string'
+require "pathname"
+require_relative "pleasant_path/version"
+require_relative "pleasant_path/array"
+require_relative "pleasant_path/file"
+require_relative "pleasant_path/io"
+require_relative "pleasant_path/pathname"
+require_relative "pleasant_path/string"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pleasant_path
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-04 00:00:00.000000000 Z
+date: 2017-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -83,9 +83,15 @@ files:
 - lib/pleasant_path/array.rb
 - lib/pleasant_path/file.rb
 - lib/pleasant_path/io.rb
+- lib/pleasant_path/json.rb
+- lib/pleasant_path/json/object.rb
+- lib/pleasant_path/json/pathname.rb
 - lib/pleasant_path/pathname.rb
 - lib/pleasant_path/string.rb
 - lib/pleasant_path/version.rb
+- lib/pleasant_path/yaml.rb
+- lib/pleasant_path/yaml/object.rb
+- lib/pleasant_path/yaml/pathname.rb
 - pleasant_path.gemspec
 homepage: https://github.com/jonathanhefner/pleasant_path
 licenses:
@@ -107,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: A fluent API for pleasant file IO.