pleasant_path 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56365c199042c351833d072a2e26985b4aceea7cb37fdd4fe8f21c038bdee6ed
-  data.tar.gz: dea582a2684edab33b60b3f4e3e624ff610d0a23a78fe17c62fbc71476e4c88e
+  metadata.gz: b6e3e6a96f3381618fe73ebb4d09a95cd607f22939398eb4352da162fed9581e
+  data.tar.gz: 995c964b867b1632d22bf58da748afadcb0a2d3824680a1c8fdcbf69fd494d1e
 SHA512:
-  metadata.gz: 9242bc111208a89cad99db62ab0d1b01290ee9d9e59e63e2fe9a15a96fc736b67aea03b0f972cdceac46a0e95680b755db5524033357b711b128a38f0497be84
-  data.tar.gz: 8ee6d00eb11286b9d1e0fce25e69ced19c73e8135d2db58f24c4562184ca5a4baa56e3866f29fe522c1e3c032046e6805095f1717564f5e5beacc51d0f00da9e
+  metadata.gz: 3c0d567cbb4c9579685a4f1923b74787321d03f4118d46af4c863272ec1ef63af48e42c0cd17a6b431043bc43a32d621c810bbae9c05ca9a4933e2d8feecff31
+  data.tar.gz: 10d3683e71e7dc881dde05622bdb1d7d53c83ce853f6376f9dc48bb53cc1150a1f67bf412bb80d7ff8717f1aaf03693c78c64d865c4c8820861b5149ae9fcdad

data/CHANGELOG.md

@@ -1,17 +1,34 @@
+## 1.3.0
+
+* Add `Pathname#find_dirs`
+* Add `Pathname#find_files`
+* Add `Pathname#make_file`
+* Add `Pathname#available_name`
+* Add `Pathname#move_as`
+* Add `Pathname#copy_as`
+* Add `eol` parameter to line-oriented methods (`Pathname#read_lines`,
+  `Pathname#write_lines`, `Pathname#append_lines`, etc)
+* Move Array methods to Enumerable
+* Use `JSON.dump_default_options` and `JSON.load_default_options` in
+  JSON-related API
+
+
 ## 1.2.0
 
-* Added `Pathname#existence`.
-* Added `Pathname#chdir`.
-* Fixed `Object#write_to_yaml` to make parent directories as necessary.
+* Add `Pathname#existence`
+* Add `Pathname#chdir`
+* Fix `Object#write_to_yaml` to make parent directories as necessary
+
 
 ## 1.1.0
 
-* Added `Pathname#copy` and `Pathname#copy_into`.
-* Added `Pathname#rename_basename` and `Pathname#rename_extname`.
-* Added `File.common_path` and `Pathname#common_path`.
-* Added `Pathname::NULL`.
-* Added JSON-related and YAML-related APIs.
-* Fixed `File.edit_text` and `File.edit_lines` to properly truncate.
+* Add `Pathname#copy` and `Pathname#copy_into`
+* Add `Pathname#rename_basename` and `Pathname#rename_extname`
+* Add `File.common_path` and `Pathname#common_path`
+* Add `Pathname::NULL`
+* Add JSON-related and YAML-related APIs
+* Fix `File.edit_text` and `File.edit_lines` to properly truncate
+
 
 ## 1.0.0
 

data/README.md

@@ -10,10 +10,8 @@ objects.  See API listing below, or browse the [full documentation].
 ## Examples
 
 ```ruby
-# Filter lines across multiple files
-"logs/*.txt".glob.each do |log|
-  log.read_lines.grep(/^ERROR /).append_to_file("errors.txt")
-end
+# Pluck lines from a file
+"log.txt".path.read_lines.grep(/^ERROR /).append_to_file("errors.txt")
 
 # Dedup lines in a file
 "names.txt".path.edit_lines(&:uniq)
@@ -30,13 +28,14 @@ The following methods are available:
   - [#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)
+  - [#available_name](http://www.rubydoc.info/gems/pleasant_path/Pathname:available_name)
   - [#chdir](http://www.rubydoc.info/gems/pleasant_path/Pathname:chdir)
   - [#common_path](http://www.rubydoc.info/gems/pleasant_path/Pathname:common_path)
   - [#copy](http://www.rubydoc.info/gems/pleasant_path/Pathname:copy)
+  - [#copy_as](http://www.rubydoc.info/gems/pleasant_path/Pathname:copy_as)
   - [#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)
@@ -44,29 +43,30 @@ The following methods are available:
   - [#existence](http://www.rubydoc.info/gems/pleasant_path/Pathname:existence)
   - [#files](http://www.rubydoc.info/gems/pleasant_path/Pathname:files)
   - [#files_r](http://www.rubydoc.info/gems/pleasant_path/Pathname:files_r)
+  - [#find_dirs](http://www.rubydoc.info/gems/pleasant_path/Pathname:find_dirs)
+  - [#find_files](http://www.rubydoc.info/gems/pleasant_path/Pathname:find_files)
   - [#make_dir](http://www.rubydoc.info/gems/pleasant_path/Pathname:make_dir)
   - [#make_dirname](http://www.rubydoc.info/gems/pleasant_path/Pathname:make_dirname)
+  - [#make_file](http://www.rubydoc.info/gems/pleasant_path/Pathname:make_file)
   - [#move](http://www.rubydoc.info/gems/pleasant_path/Pathname:move)
+  - [#move_as](http://www.rubydoc.info/gems/pleasant_path/Pathname:move_as)
   - [#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)
+- [Enumerable](http://www.rubydoc.info/gems/pleasant_path/Enumerable)
+  - [#append_to_file](http://www.rubydoc.info/gems/pleasant_path/Enumerable:append_to_file)
+  - [#write_to_file](http://www.rubydoc.info/gems/pleasant_path/Enumerable: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)

data/lib/pleasant_path.rb

@@ -1,6 +1,6 @@
 require "pathname"
 require_relative "pleasant_path/version"
-require_relative "pleasant_path/array"
+require_relative "pleasant_path/enumerable"
 require_relative "pleasant_path/file"
 require_relative "pleasant_path/io"
 require_relative "pleasant_path/pathname"

data/lib/pleasant_path/enumerable.rb

@@ -0,0 +1,43 @@
+module Enumerable
+
+  # Writes each object in the Enumerable as a string plus end-of-line
+  # (EOL) characters to the specified +file+, overwriting the file if it
+  # exists.  Creates the file if it does not exist, including any
+  # necessary parent directories.  Returns the Enumerable.
+  #
+  # @see Pathname#write_lines
+  #
+  # @example
+  #   [:one, :two].write_to_file("out.txt")  # == [:one, :two]
+  #   File.read("out.txt")                   # == "one\ntwo\n"
+  #
+  # @param file [String, Pathname]
+  # @param eol [String]
+  # @return [self]
+  def write_to_file(file, eol: $/)
+    file.to_pathname.write_lines(self, eol: eol)
+    self
+  end
+
+  # Appends each object in the Enumerable as a string plus end-of-line
+  # (EOL) characters to the specified +file+.  Creates the file if it
+  # does not exist, including any necessary parent directories.  Returns
+  # the Enumerable.
+  #
+  # @see Pathname#append_lines
+  #
+  # @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]
+  # @param eol [String]
+  # @return [self]
+  def append_to_file(file, eol: $/)
+    file.to_pathname.append_lines(self, eol: eol)
+    self
+  end
+
+end

data/lib/pleasant_path/file.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 class File
 
-  # Computes the longest path that every path in a list has in common.
+  # Returns the longest path that all of +paths+ have 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"
+  #   File.common_path(["a/bx", "a/by", "a/bz"])     # == "a/"
+  #   File.common_path(["a/b/x", "a/b", "a"])        # == "a"
   #
   # @param paths [Enumerable<String>]
   # @return [String]
@@ -15,18 +17,18 @@ class File
     i = 0
     last = -1
     while i < short.length && short[i] == long[i]
-      last = i if short[i] == "/".freeze
+      last = i if short[i] == "/"
       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.
+  # Reads the entire contents of the file indicated by +filename+ as a
+  # string, and yields that string to the given block for editing.
+  # Writes the return value of the block back to the file, overwriting
+  # previous contents.  Returns the return value of the block.
   #
-  # @example update JSON data file
+  # @example Update JSON data file
   #   File.read("data.json")  # == '{"nested":{"key":"value"}}'
   #
   #   File.edit_text("data.json") do |text|
@@ -38,9 +40,9 @@ class File
   #   File.read("data.json")  # == '{"nested":{"key":"new value"}}'
   #
   # @param filename [String, Pathname]
-  # @yield [text] edits current file contents
-  # @yieldparam text [String] current contents
-  # @yieldreturn [String] new contents
+  # @yield [text]
+  # @yieldparam text [String]
+  # @yieldreturn [String]
   # @return [String]
   def self.edit_text(filename)
     self.open(filename, "r+") do |f|
@@ -52,14 +54,14 @@ class File
     end
   end
 
-  # Reads from the specified file its contents as an array of lines, and
-  # yields the array to the given block for editing.  Writes the return
-  # value of the block back to the file, 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.
+  # Reads the entire contents of the file indicated by +filename+ as an
+  # array of lines, and yields that array to the given block for
+  # editing.  Writes the return value of the block back to the file,
+  # overwriting previous contents.  End-of-line (EOL) characters are
+  # stripped when reading, and appended after each line when writing.
+  # Returns the return value of the block.
   #
-  # @example dedup lines of file
+  # @example Dedup lines of file
   #   File.read("entries.txt")  # == "AAA\nBBB\nBBB\nCCC\nAAA\n"
   #
   #   File.edit_lines("entries.txt", &:uniq)
@@ -68,15 +70,16 @@ class File
   #   File.read("entries.txt")  # == "AAA\nBBB\nCCC\n"
   #
   # @param filename [String, Pathname]
-  # @yield [lines] edits current file contents
-  # @yieldparam lines [Array<String>] current contents
-  # @yieldreturn [Array<String>] new contents
+  # @param eol [String]
+  # @yield [lines]
+  # @yieldparam lines [Array<String>]
+  # @yieldreturn [Array<String>]
   # @return [Array<String>]
-  def self.edit_lines(filename)
+  def self.edit_lines(filename, eol: $/)
     self.open(filename, "r+") do |f|
-      lines = yield f.read_lines
+      lines = yield f.read_lines(eol: eol)
       f.seek(0, IO::SEEK_SET)
-      f.write_lines(lines)
+      f.write_lines(lines, eol: eol)
       f.truncate(f.pos)
       lines
     end

data/lib/pleasant_path/io.rb

@@ -1,45 +1,46 @@
+# frozen_string_literal: true
+
 class IO
 
-  # Writes each object as a string plus a succeeding new line character
-  # (<code>$/</code>) to the IO.  Returns the objects unmodified.
+  # Writes each object in +lines+ as a string plus end-of-line (EOL)
+  # characters to the IO.  Returns +lines+, unmodified.
   #
   # @example
-  #   # NOTE File inherits from IO
-  #   File.open("out.txt") do |file|
-  #     file.write_lines([:one, :two])  # == [:one, :two]
-  #   end                               # == [:one, :two]
+  #   File.open("out.txt") do |io|
+  #     io.write_lines([:one, :two])  # == [:one, :two]
+  #   end                             # == [:one, :two]
   #
-  #   File.read("out.txt")              # == "one\ntwo\n"
+  #   File.read("out.txt")            # == "one\ntwo\n"
   #
   # @param lines [Enumerable<#to_s>]
+  # @param eol [String]
   # @return [Enumerable<#to_s>]
-  def write_lines(lines)
+  def write_lines(lines, eol: $/)
     lines.each do |line|
       self.write(line)
-      self.write($/)
+      self.write(eol)
     end
     self.write("") # write something even if no lines
     lines
   end
 
-  # 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 exclude.
+  # Reads all lines from the IO, and returns them with all end-of-line
+  # (EOL) characters stripped.
   #
-  # (Not to be confused with +IO#readlines+ which retains end-of-line
-  # characters in every string it returns.)
+  # @note Not to be confused with +IO#readlines+, which retains
+  #   end-of-line (EOL) characters.
   #
   # @example
-  #   # NOTE File inherits from IO
-  #   File.read("in.txt")            # == "one\ntwo\n"
+  #   File.read("in.txt")          # == "one\ntwo\n"
   #
-  #   File.open("in.txt") do |file|
-  #     file.read_lines              # == ["one", "two"]
-  #   end                            # == ["one", "two"]
+  #   File.open("in.txt") do |io|
+  #     io.read_lines              # == ["one", "two"]
+  #   end                          # == ["one", "two"]
   #
+  # @param eol [String]
   # @return [Array<String>]
-  def read_lines
-    self.readlines.each(&:chomp!)
+  def read_lines(eol: $/)
+    self.readlines(eol, chomp: true)
   end
 
 end

data/lib/pleasant_path/json/object.rb

@@ -1,26 +1,26 @@
 class Object
 
-  # Dumps the Object as JSON, and writes the JSON to the specified file.
-  # Returns the Object unmodified.
+  # Writes the Object serialized as JSON to the specified +file+,
+  # overwriting the file if it exists.  Creates the file if it does not
+  # exist, including any necessary parent directories.  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+}.
+  # For information about +options+ see
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#method-i-generate
+  # +JSON.generate+}.  By default, this method uses
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#attribute-c-dump_default_options
+  # +JSON.dump_default_options+}.
   #
   # @example
   #   { "key" => "value" }.write_to_json("out.json")  # == { "key" => "value" }
   #   File.read("out.json")                           # == '{"key":"value"}'
   #
   # @param file [String, Pathname]
-  # @param options [Hash]
+  # @param options [Hash<Symbol, Object>]
   # @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))
+    options = JSON.dump_default_options.merge(options)
+    file.to_pathname.write_text(self.to_json(options))
     self
   end
 

data/lib/pleasant_path/json/pathname.rb

@@ -1,41 +1,38 @@
+# frozen_string_literal: true
+
 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+.
+  # Parses the contents of the file indicated by the Pathname as JSON.
+  # The returned result will composed of only basic data types, e.g.
+  # +nil+, +true+, +false+, +Numeric+, +String+, +Array+, and +Hash+.
   #
-  # For information about available options, see
-  # {http://ruby-doc.org/stdlib/libdoc/json/rdoc/JSON.html#method-i-parse
-  # +JSON.parse+}.
+  # For information about +options+, see
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#method-i-parse
+  # +JSON.parse+}.  By default, this method uses
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#attribute-c-load_default_options
+  # +JSON.load_default_options+} plus +create_additions: false+.
   #
   # @example
   #   File.write("in.json", '{"key": "value"}')
   #
   #   Pathname.new("in.json").read_json  # == { "key" => "value" }
   #
-  # @param options [Hash]
+  # @param options [Hash<Symbol, Object>]
   # @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)
+    JSON.load(self, nil, { create_additions: false, **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.
+  # Parses the contents of the file indicated by the Pathname as JSON,
+  # deserializing arbitrary data types via type information embedded in
+  # the JSON.  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 +options+, see
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#method-i-parse
+  # +JSON.parse+}.  By default, this method uses
+  # {https://docs.ruby-lang.org/en/trunk/JSON.html#attribute-c-load_default_options
+  # +JSON.load_default_options+}.
   #
   # For information about serializing custom types to JSON, see the
   # {https://github.com/flori/json/blob/master/README.md#more-examples
@@ -49,10 +46,10 @@ class Pathname
   #
   #   Pathname.new("in.json").load_json  # == Point.new(10, 20)
   #
-  # @param options [Hash]
-  # @return deserialized object
+  # @param options [Hash<Symbol, Object>]
+  # @return [Object]
   def load_json(options = {})
-    self.open("r"){|f| JSON.load(f, nil, options) }
+    JSON.load(self, nil, options)
   end
 
 end