pleasant_path 1.2.0 → 1.3.0

data/lib/pleasant_path/string.rb

@@ -1,6 +1,6 @@
 class String
 
-  # Converts the string to a +Pathname+ object.
+  # Constructs a Pathname from the String.
   #
   # @example
   #   "path/to/file".to_pathname  # == Pathname.new("path/to/file")
@@ -15,8 +15,8 @@ class String
   # @return [Pathname]
   alias :path :to_pathname
 
-  # Joins the string and the argument with a directory separator (a la
-  # +File.join+) and returns the result as a +Pathname+ object.
+  # Constructs a Pathname from the String, and appends +child+ to the
+  # Pathname.
   #
   # @example
   #   "path/to" / "file"  # == Pathname.new("path/to/file")
@@ -27,11 +27,16 @@ class String
     self.path / child
   end
 
-  # Treating the string as a path, joins the parent (+dirname+) of the
-  # path with the argument, and returns the result as a +Pathname+
-  # object.  The mnemonic 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#^}.
+  # @deprecated Use {Pathname#^}.
+  #
+  # Constructs a Pathname from the String, and appends +sibling+ to the
+  # +dirname+ of the Pathname.
+  #
+  # The mnemonic for this operator is that the result is formed by going
+  # up one directory level from the original path, then going back down
+  # to +sibling+.
+  #
+  # @see Pathname#^
   #
   # @example
   #   "path/to/file1" ^ "file2"  # == Pathname.new("path/to/file2")
@@ -42,9 +47,12 @@ class String
     self.path ^ sibling
   end
 
-  # Treats the string as a filename pattern, and expands the pattern
-  # into matching paths as +Pathname+ objects.  See also +Dir.glob+ and
-  # +Pathname.glob+.
+  # @deprecated Use +Pathname.glob+.
+  #
+  # Returns an array of Pathnames which match the filename pattern
+  # contained in the String.
+  #
+  # @see https://docs.ruby-lang.org/en/trunk/Pathname.html#method-i-glob Pathname.glob
   #
   # @example
   #   "*.txt".glob  # == Pathname.glob("*.txt")
@@ -54,24 +62,28 @@ class String
     Pathname.glob(self)
   end
 
-  # Writes the string to the given file, and returns the string.  The
-  # file is overwritten if it already exists.  Any necessary parent
-  # directories are created if they do not exist.
+  # Writes the String 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 String.
+  #
+  # @see Pathname#write_text
   #
   # @example
   #   "hello world".write_to_file("out.txt")  # == "hello world"
   #   File.read("out.txt")                    # == "hello world"
   #
   # @param file [String, Pathname]
-  # @return [String]
+  # @return [self]
   def write_to_file(file)
     file.to_pathname.write_text(self)
     self
   end
 
-  # Appends the string to the given file, and returns the string.  The
-  # file is created if it does not exist.  Any necessary parent
-  # directories are created if they do not exist.
+  # Appends the String to the specified +file+.  Creates the file if it
+  # does not exist, including any necessary parent directories.  Returns
+  # the String.
+  #
+  # @see Pathname#append_text
   #
   # @example
   #   "hello".append_to_file("out.txt")   # == "hello"
@@ -80,7 +92,7 @@ class String
   #   File.read("out.txt")                # == "hello world"
   #
   # @param file [String, Pathname]
-  # @return [String]
+  # @return [self]
   def append_to_file(file)
     file.to_pathname.append_text(self)
     self

data/lib/pleasant_path/version.rb

@@ -1,3 +1,3 @@
 module PleasantPath
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/pleasant_path/yaml/object.rb

@@ -1,10 +1,14 @@
+# frozen_string_literal: true
+
 class Object
 
-  # Dumps the Object as YAML, and writes the YAML to the specified file.
-  # Returns the Object unmodified.
+  # Writes the Object serialized as YAML 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
-  # {https://ruby-doc.org/stdlib/libdoc/psych/rdoc/Psych.html#method-c-dump
+  # For information about +options+ see
+  # {https://docs.ruby-lang.org/en/trunk/Psych.html#method-c-dump
   # +YAML.dump+}.
   #
   # @example
@@ -12,7 +16,7 @@ class Object
   #   File.read("out.yaml")                           # == "---\nkey: value\n"
   #
   # @param file [String, Pathname]
-  # @param options [Hash]
+  # @param options [Hash<Symbol, Object>]
   # @return [self]
   def write_to_yaml(file, options = {})
     file.to_pathname.make_dirname.open("w") do |f|

data/lib/pleasant_path/yaml/pathname.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 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+.
+  # Parses the contents of the file indicated by the Pathname as YAML.
+  # The returned result will composed of only basic data types, e.g.
+  # +nil+, +true+, +false+, +Numeric+, +String+, +Array+, and +Hash+.
   #
   # @example
   #   File.write("in.yaml", "key: value")
@@ -12,14 +13,20 @@ class Pathname
   #
   # @return [nil, true, false, Numeric, String, Array, Hash]
   def read_yaml
-    self.open("r"){|f| YAML.safe_load(f, [], [], false, self) }
+    self.open("r") do |f|
+      # HACK fix Ruby 2.6 warning, but still support Ruby < 2.6
+      if Gem::Version.new(Psych::VERSION) >= Gem::Version.new("3.1.0.pre1")
+        YAML.safe_load(f, filename: self)
+      else
+        YAML.safe_load(f, [], [], false, self)
+      end
+    end
   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.
+  # Parses the contents of the file indicated by the Pathname as YAML,
+  # deserializing arbitrary data types via type information embedded in
+  # the YAML.  This is *UNSAFE* for YAML from an untrusted source.  To
+  # consume untrusted YAML, use {Pathname#read_yaml} instead.
   #
   # @example
   #   Point = Struct.new(:x, :y)
@@ -28,7 +35,7 @@ class Pathname
   #
   #   Pathname.new("in.yaml").load_yaml  # == Point.new(10, 20)
   #
-  # @return deserialized object
+  # @return [Object]
   def load_yaml
     YAML.load_file(self)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pleasant_path
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-18 00:00:00.000000000 Z
+date: 2019-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -81,7 +81,7 @@ files:
 - README.md
 - Rakefile
 - lib/pleasant_path.rb
-- lib/pleasant_path/array.rb
+- lib/pleasant_path/enumerable.rb
 - lib/pleasant_path/file.rb
 - lib/pleasant_path/io.rb
 - lib/pleasant_path/json.rb
@@ -113,8 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: A fluent API for pleasant file IO.

data/lib/pleasant_path/array.rb

@@ -1,37 +0,0 @@
-class Array
-
-  # Writes the array as lines to the given file, and returns the array.
-  # 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.
-  #
-  # @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)
-    file.to_pathname.write_lines(self)
-    self
-  end
-
-  # Appends the array as lines to the given file, and returns the array.
-  # 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.
-  #
-  # @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)
-    file.to_pathname.append_lines(self)
-    self
-  end
-
-end