pathutil 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f764aa49d17400ee6d3e613e2d4402dc7ff69de
-  data.tar.gz: d362e2e9d92234bc1bc7dd7b32ee01d69de5b99d
+  metadata.gz: e0379be022c3075e3a84b161087c637460dadf4d
+  data.tar.gz: 835f3036a786ac0096522886b66f11d9b5584e66
 SHA512:
-  metadata.gz: fba4041a94c1abf33246e417ad6fe5361aaf8dddcdaf44eda11468e539e35a62c8e85b4a01e5ffd9665353f4ea3f0b10576bd8ecb23ade4db3099d9c9f6e15b3
-  data.tar.gz: af0114a98b2b63b3dcedcb74fae2e7610b659abf57e1aac225145d951e7c6d281363bb242d3b6f6e3aa50cfc3117bf82642a421fd8631b03a6e6224283572eb9
+  metadata.gz: f2e6321fbcbb23807bc9de1a166c20a3566d481c39240ae48aa6d898834f8d17aeefd206e624061ea0a2d514ad3b688374b9b566c4c348b1dfa9f5a67384c6c0
+  data.tar.gz: be5897bdcdf38edf0494f4dadb9963345c33cb40aa10f73807861702d593660afa74b7352169695ec6e68e6ecf3ee4bee6aedef674524fca80bc33c12a55eef8

data/Gemfile

@@ -1,12 +1,15 @@
+# ----------------------------------------------------------------------------
 # Frozen-string-literal: true
 # Copyright: 2015-2016 Jordon Bedwell - MIT License
 # Encoding: utf-8
+# ----------------------------------------------------------------------------
 
 source "https://rubygems.org"
 gem "rake", :require => false
 gemspec
 
 group :test do
+  gem "luna-rspec-formatters", :require => false
   gem "codeclimate-test-reporter", :require => false
   gem "safe_yaml", :require => false
 end
@@ -16,7 +19,6 @@ group :development do
   gem "rspec-helpers", :require => false
   gem "luna-rubocop-formatters", :require => false
   gem "rubocop", :github => "bbatsov/rubocop", :require => false
-  gem "luna-rspec-formatters", :require => false
   gem "benchmark-ips", :require => false
   gem "simple-ansi", :require => false
   gem "pry", :require => false

data/Rakefile

@@ -1,18 +1,25 @@
+# ----------------------------------------------------------------------------
 # Frozen-string-literal: true
 # Copyright: 2015-2016 Jordon Bedwell - MIT License
 # Encoding: utf-8
+# ----------------------------------------------------------------------------
 
 require "open3"
 require "rspec/core/rake_task"
 require_relative "benchmark/support/task"
+require "luna/rubocop/rake/task"
 require "simple/ansi"
 require "pathutil"
 require "json"
 
+# ----------------------------------------------------------------------------
+
 task :default => [
   ENV["BENCHMARK"] ? :benchmark : :spec
 ]
 
+# ----------------------------------------------------------------------------
+
 BenchmarkTask.new :benchmark
 RSpec::Core::RakeTask.new :spec
 task :test => :spec
@@ -74,10 +81,3 @@ task :methods do
 
   $stdout.puts
 end
-
-# ----------------------------------------------------------------------------
-
-task :rubocop do
-  sh "bundle", "exec", "rubocop", "-DE", "-r", "luna/rubocop/formatters/checks", \
-    "-f", "Luna::RuboCop::Formatters::Checks"
-end

data/lib/pathutil.rb

@@ -8,13 +8,13 @@ require "pathutil/helpers"
 require "forwardable/extended"
 require "find"
 
-#
-
 class Pathutil
   attr_writer :encoding
   extend Forwardable::Extended
   extend Helpers
 
+  # --------------------------------------------------------------------------
+  # Note: A lot of this class can be compatible with Pathname.
   # --------------------------------------------------------------------------
 
   def initialize(path)
@@ -24,15 +24,9 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
+  # Note: It will return all results that it finds across all ascending paths.
+  # Example: Pathutil.new("~/").expand_path.search_backwards(".bashrc") => [#<Pathutil:/home/user/.bashrc>]
   # Search backwards for a file (like Rakefile, _config.yml, opts.yml).
-  # @note It will return all results that it finds across all ascending paths.
-  # @param backwards how far do you wish to search backwards in that path?
-  # @param file the file you are searching for.
-  #
-  # @example
-  #   Pathutil.new("~/").expand_path.search_backwards(".bashrc") => [
-  #     #<Pathutil:/home/user/.bashrc>
-  #   ]
   # --------------------------------------------------------------------------
 
   def search_backwards(file, backwards: Float::INFINITY)
@@ -64,6 +58,9 @@ class Pathutil
     ary
   end
 
+  # --------------------------------------------------------------------------
+  # See: self.class.load_yaml as this a direct alias of that method.
+  # Read the file as a YAML file turning it into an object.
   # --------------------------------------------------------------------------
 
   def read_yaml(throw_missing: false, **kwd)
@@ -77,6 +74,9 @@ class Pathutil
     )
   end
 
+  # --------------------------------------------------------------------------
+  # See: self.class.read_json as this is a direct alias of that method.
+  # Read the file as a JSON file turning it into an object.
   # --------------------------------------------------------------------------
 
   def read_json(throw_missing: false)
@@ -91,13 +91,9 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
+  # Note: The blank part is intentionally left there so that you can rejoin.
   # Splits the path into all parts so that you can do step by step comparisons
-  # @note The blank part is intentionally left there so that you can rejoin.
-  #
-  # @example
-  #   Pathutil.new("/my/path").split_path # => [
-  #     "", "my", "path"
-  #   ]
+  # Example: Pathutil.new("/my/path").split_path # => ["", "my", "path"]
   # --------------------------------------------------------------------------
 
   def split_path
@@ -107,10 +103,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @see `String#==` for more details.
   # A stricter version of `==` that also makes sure the object matches.
-  # @param [Pathutil] other the comparee.
-  # @return true, false
+  # See: `String#==` for more details.
   # --------------------------------------------------------------------------
 
   def ===(other)
@@ -118,11 +112,9 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @example Pathutil.new("/hello") >= Pathutil.new("/") # => true
-  # @example Pathutil.new("/hello") >= Pathutil.new("/hello") # => true
   # Checks to see if a path falls within a path and deeper or is the other.
-  # @param path the path that should be above the object.
-  # @return true, false
+  # Example: Pathutil.new("/hello") >= Pathutil.new("/hello") # => true
+  # Example: Pathutil.new("/hello") >= Pathutil.new("/") # => true
   # --------------------------------------------------------------------------
 
   def >=(other)
@@ -132,10 +124,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @example Pathutil.new("/hello/world") > Pathutil.new("/hello") # => true
   # Strictly checks to see if a path is deeper but within the path of the other.
-  # @param path the path that should be above the object.
-  # @return true, false
+  # Example: Pathutil.new("/hello/world") > Pathutil.new("/hello") # => true
   # --------------------------------------------------------------------------
 
   def >(other)
@@ -145,10 +135,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @example Pathutil.new("/") < Pathutil.new("/hello") # => true
   # Strictly check to see if a path is behind other path but within it.
-  # @param path the path that should be below the object.
-  # @return true, false
+  # Example: Pathutil.new("/") < Pathutil.new("/hello") # => true
   # --------------------------------------------------------------------------
 
   def <(other)
@@ -158,11 +146,9 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # Check to see if a path is behind the other path butt within it.
-  # @example Pathutil.new("/hello") < Pathutil.new("/hello") # => true
-  # @example Pathutil.new("/") < Pathutil.new("/hello") # => true
-  # @param path the path that should be below the object.
-  # @return true, false
+  # Check to see if a path is behind the other path but within it.
+  # Example: Pathutil.new("/hello") < Pathutil.new("/hello") # => true
+  # Example: Pathutil.new("/") < Pathutil.new("/hello") # => true
   # --------------------------------------------------------------------------
 
   def <=(other)
@@ -172,9 +158,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @note "./" is considered relative.
   # Check to see if the path is absolute, as in: starts with "/"
-  # @return true, false
+  # Note: "./" is considered relative.
   # --------------------------------------------------------------------------
 
   def absolute?
@@ -183,21 +168,8 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Break apart the path and yield each with the previous parts.
-  # @return Enumerator if no block is given.
-  #
-  # @example
-  #   Pathutil.new("/hello/world").ascend.to_a # => [
-  #     "/", "/hello", "/hello/world"
-  #   ]
-  #
-  # @example
-  #   Pathutil.new("/hello/world").ascend do |path|
-  #     $stdout.puts path
-  #   end
-  #
-  #   /
-  #   /hello
-  #   /hello/world
+  # Example: Pathutil.new("/hello/world").ascend.to_a # => ["/", "/hello", "/hello/world"]
+  # Example: Pathutil.new("/hello/world").ascend { |path| $stdout.puts path }
   # --------------------------------------------------------------------------
 
   def ascend
@@ -225,21 +197,8 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Break apart the path in reverse order and descend into the path.
-  # @return Enumerator if no block is given.
-  #
-  # @example
-  #   Pathutil.new("/hello/world").descend.to_a # => [
-  #     "/hello/world", "/hello", "/"
-  #   ]
-  #
-  # @example
-  #   Pathutil.new("/hello/world").descend do |path|
-  #     $stdout.puts path
-  #   end
-  #
-  #   /hello/world
-  #   /hello
-  #   /
+  # Example: Pathutil.new("/hello/world").descend.to_a # => ["/hello/world", "/hello", "/"]
+  # Example: Pathutil.new("/hello/world").descend { |path| $stdout.puts path }
   # --------------------------------------------------------------------------
 
   def descend
@@ -257,15 +216,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
+  # Example: Pathutil.new("/hello/world").each_line { |line| $stdout.puts line }
   # Wraps `readlines` and allows you to yield on the result.
-  #
-  # @example
-  #   Pathutil.new("/hello/world").each_line do |line|
-  #     $stdout.puts line
-  #   end
-  #
-  #   Hello
-  #   World
   # --------------------------------------------------------------------------
 
   def each_line
@@ -278,12 +230,10 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @see `File#fnmatch` for more information.
+  # Example: Pathutil.new("/hello").fnmatch?("/hello") # => true
   # Unlike traditional `fnmatch`, with this one `Regexp` is allowed.
-  # @param [String, Regexp] matcher the matcher used, can be a `Regexp`
-  # @example Pathutil.new("/hello").fnmatch?("/hello") # => true
-  # @example Pathutil.new("/hello").fnmatch?(/h/) # => true
-  # @return true, false
+  # Example: Pathutil.new("/hello").fnmatch?(/h/) # => true
+  # See: `File#fnmatch` for more information.
   # --------------------------------------------------------------------------
 
   def fnmatch?(matcher)
@@ -293,7 +243,6 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Allows you to quickly determine if the file is the root folder.
-  # @return true, false
   # --------------------------------------------------------------------------
 
   def root?
@@ -301,9 +250,7 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @param [Pathutil, String] path the reference.
   # Allows you to check if the current path is in the path you want.
-  # @return true, false
   # --------------------------------------------------------------------------
 
   def in_path?(path)
@@ -321,7 +268,6 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Grab all of the children from the current directory, including hidden.
-  # @return Array<Pathutils>
   # --------------------------------------------------------------------------
 
   def children
@@ -343,11 +289,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @see `File::Constants` for a list of flags.
-  # Allows you to glob however you wish to glob in the current `Pathutils`
-  # @param [String] flags the flags you want to ship to the glob.
-  # @param [String] pattern the pattern A.K.A: "**/*"
-  # @return Enumerator unless a  block is given.
+  # Allows you to glob however you wish to glob in the current `Pathutil`
+  # See: `File::Constants` for a list of flags.
   # --------------------------------------------------------------------------
 
   def glob(pattern, flags = 0)
@@ -369,9 +312,8 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @note you do not need to ship a block at all.
   # Move to the current directory temporarily (or for good) and do work son.
-  # @return 0, 1 if no block given
+  # Note: you do not need to ship a block at all.
   # --------------------------------------------------------------------------
 
   def chdir
@@ -388,9 +330,7 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @return Enumerator if no block is given.
   # Find all files without care and yield the given block.
-  # @see Find.find
   # --------------------------------------------------------------------------
 
   def find
@@ -402,7 +342,6 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Splits the path returning each part (filename) back to you.
-  # @return Enumerator if no block is given.
   # --------------------------------------------------------------------------
 
   def each_filename
@@ -412,6 +351,9 @@ class Pathutil
     end
   end
 
+  # --------------------------------------------------------------------------
+  # Note: This will simply return self if "/".
+  # Get the parent of the current path.
   # --------------------------------------------------------------------------
 
   def parent
@@ -423,7 +365,6 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Split the file into its dirname and basename, so you can do stuff.
-  # @return File.dirname, File.basename
   # --------------------------------------------------------------------------
 
   def split
@@ -434,6 +375,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Replace a files extension with your given extension.
+  # Note: Your extension should start with "."
   # --------------------------------------------------------------------------
 
   def sub_ext(ext)
@@ -442,20 +384,18 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # A less complex version of `relative_path_from` that simply uses a
-  # `Regexp` and returns the full path if it cannot be relatively determined.
-  # @return Pathutils the relative path if it can be determined or is relative.
-  # @return Pathutils the full path if relative path cannot be determined
+  # `Regexp` and returns the full path if it cannot be determined.
   # --------------------------------------------------------------------------
 
   def relative_path_from(from)
     from = self.class.new(from).expand_path.gsub(%r!/$!, "")
-    self.class.new(expand_path.gsub(%r!^#{from.regexp_escape}/!, ""))
+    self.class.new(expand_path.gsub(%r!^#{
+      from.regexp_escape
+    }/!, ""))
   end
 
   # --------------------------------------------------------------------------
   # Expands the path and left joins the root to the path.
-  # @param [String, Pathutil] root the root you wish to enforce on it.
-  # @return Pathutil the enforced path with given root.
   # --------------------------------------------------------------------------
 
   def enforce_root(root)
@@ -472,19 +412,28 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Copy a directory, allowing symlinks if the link falls inside of the root.
+  # This is indented for people who wish some safety to their copies.
   # --------------------------------------------------------------------------
 
   def safe_copy(to, root: nil)
     raise ArgumentError, "must give a root" unless root
-    to = self.class.new(to)
-
     root = self.class.new(root)
-    return safe_copy_directory(to, :root => root) if directory?
-    safe_copy_file(to, :root => root)
+    to   = self.class.new(to)
+
+    if directory?
+      safe_copy_directory(to, {
+        :root => root
+      })
+
+    else
+      safe_copy_file(to, {
+        :root => root
+      })
+    end
   end
 
   # --------------------------------------------------------------------------
-  # @see `self.class.normalize` as this is an alias.
+  # See: `self.class.normalize` as this is an alias.
   # --------------------------------------------------------------------------
 
   def normalize
@@ -494,7 +443,7 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @see `self.class.encoding` as this is an alias.
+  # See: `self.class.encoding` as this is an alias.
   # --------------------------------------------------------------------------
 
   def encoding
@@ -505,6 +454,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Read took two steroid shots: it can normalize your string, and encode.
+  # Note: You can set the default encodings via the class.
   # --------------------------------------------------------------------------
 
   def read(*args, **kwd)
@@ -524,6 +474,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Binread took two steroid shots: it can normalize your string, and encode.
+  # Note: You can set the default encodings via the class.
   # --------------------------------------------------------------------------
 
   def binread(*args, **kwd)
@@ -543,6 +494,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Readlines took two steroid shots: it can normalize your string, and encode.
+  # Note: You can set the default encodings via the class.
   # --------------------------------------------------------------------------
 
   def readlines(*args, **kwd)
@@ -562,6 +514,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Write took two steroid shots: it can normalize your string, and encode.
+  # Note: You can set the default encodings via the class.
   # --------------------------------------------------------------------------
 
   def write(data, *args, **kwd)
@@ -581,6 +534,7 @@ class Pathutil
 
   # --------------------------------------------------------------------------
   # Binwrite took two steroid shots: it can normalize your string, and encode.
+  # Note: You can set the default encodings via the class.
   # --------------------------------------------------------------------------
 
   def binwrite(data, *args, **kwd)
@@ -599,7 +553,7 @@ class Pathutil
   end
 
   # --------------------------------------------------------------------------
-  # @api returns the current objects expanded path and their expanded path.
+  # Expand the paths and return.
   # --------------------------------------------------------------------------
 
   private
@@ -607,6 +561,8 @@ class Pathutil
     return expand_path, self.class.new(path).expand_path
   end
 
+  # --------------------------------------------------------------------------
+  # Safely copy a file.
   # --------------------------------------------------------------------------
 
   private
@@ -617,6 +573,8 @@ class Pathutil
     })
   end
 
+  # --------------------------------------------------------------------------
+  # Safely copy a directory and it's sub-files.
   # --------------------------------------------------------------------------
 
   private
@@ -649,13 +607,12 @@ class Pathutil
     end
   end
 
-  # --------------------------------------------------------------------------
-
   class << self
     attr_writer :encoding
 
     # ------------------------------------------------------------------------
     # Get the current directory that Ruby knows about.
+    # Note: We do nothing special here.
     # ------------------------------------------------------------------------
 
     def pwd
@@ -668,9 +625,9 @@ class Pathutil
     alias cwd  pwd
 
     # ------------------------------------------------------------------------
+    # Note: you are encouraged to override this if you need to.
     # Aliases the default system encoding to us so that we can do most read
     # and write operations with that encoding, instead of being crazy.
-    # @note you are encouraged to override this if you need to.
     # ------------------------------------------------------------------------
 
     def encoding
@@ -680,8 +637,8 @@ class Pathutil
     end
 
     # ------------------------------------------------------------------------
-    # Normalize CRLF -> LF on Windows reads, to ease  your troubles.
-    # Normalize LF -> CLRF on Windows write, to ease their troubles.
+    # Normalize CRLF -> LF   on Windows reads, to ease  your troubles.
+    # Normalize LF   -> CLRF on Windows write, to ease  your troubles.
     # ------------------------------------------------------------------------
 
     def normalize
@@ -691,6 +648,10 @@ class Pathutil
       }
     end
 
+    # ------------------------------------------------------------------------
+    # Make a temporary directory.
+    # Note: if you adruptly exit it will not remove the dir.
+    # Note: this directory is removed on exit.
     # ------------------------------------------------------------------------
 
     def tmpdir(*args)
@@ -702,6 +663,10 @@ class Pathutil
       rtn
     end
 
+    # ------------------------------------------------------------------------
+    # Make a temporary file.
+    # Note: if you adruptly exit it will not remove the dir.
+    # Note: this file is removed on exit.
     # ------------------------------------------------------------------------
 
     def tmpfile(*args)
@@ -812,8 +777,6 @@ class Pathutil
   rb_delegate :shellescape, :to => :Shellwords, :args => :@path
   rb_delegate :mkdir, :to => :Dir, :args => :@path
 
-  # --------------------------------------------------------------------------
-  # alias last basename, alias first dirname, alias ext extname
   # --------------------------------------------------------------------------
 
   alias + join

data/lib/pathutil/helpers.rb

@@ -4,7 +4,7 @@ class Pathutil
 
     # ------------------------------------------------------------------------
     # Wraps around YAML and SafeYAML to provide alternatives to Rubies.
-    # @note We default aliases to yes so we can detect if you explicit true.
+    # Note: We default aliases to yes so we can detect if you explicit true.
     # ------------------------------------------------------------------------
 
     def load_yaml(data, safe: true, whitelist_classes: [], whitelist_symbols: [], aliases: :yes)
@@ -32,6 +32,8 @@ class Pathutil
       end
     end
 
+    # ------------------------------------------------------------------------
+    # Make a temporary name suitable for temporary files and directories.
     # ------------------------------------------------------------------------
 
     def make_tmpname(prefix = "", suffix = nil, root = nil)
@@ -46,6 +48,7 @@ class Pathutil
 
     # ------------------------------------------------------------------------
 
+    private
     def tmpname_suffix(suffix)
       suffix = suffix.join("-") if suffix.is_a?(Array)
       suffix = suffix.gsub(/\A\-/, "") unless !suffix || suffix.empty?
@@ -53,6 +56,7 @@ class Pathutil
     end
 
     # ------------------------------------------------------------------------
+    # Cleanup the temp name prefix, joining if necessary.
     # rubocop:disable Style/ParallelAssignment
     # ------------------------------------------------------------------------
 
@@ -73,6 +77,7 @@ class Pathutil
     end
 
     # ------------------------------------------------------------------------
+    # Wrap around, cleanup, deprecate and use SafeYAML.
     # rubocop:enable Style/ParallelAssignment
     # ------------------------------------------------------------------------
 

data/lib/pathutil/version.rb

@@ -5,5 +5,5 @@
 # ----------------------------------------------------------------------------
 
 class Pathutil
-  VERSION = "0.4.2"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pathutil
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Jordon Bedwell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-05 00:00:00.000000000 Z
+date: 2016-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwardable-extended
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
 description: Like Pathname but a little less insane.
 email:
 - jordon@envygeeks.io
@@ -57,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.2
 signing_key: 
 specification_version: 4
 summary: Almost like Pathname but just a little less insane.