class Pathname

NRSER's extensions to the stdlib's `Pathname` class.

@see ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html

Pathname

Definitions

Public Instance Methods

_core_sub(pattern, *args, &block)

@!method _core_sub *args, &block

An `alias_method` reference to the `#sub` method as we found it, which
we'll use inside our override of {#sub}... and now you can too!

Arguments are the same as [String#sub][].

[String#sub]: https://ruby-doc.org/core/String.html#method-i-sub

@see  https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html#method-i-sub
      Ruby Stdlib Pathname#sub

@return [Pathname]
Alias for: sub
closest_dir() click to toggle source

The “closest” directory - which is `self` if the instance is a {#directory?}, otherwise it's {#dirname}.

@return [Pathname]

# File lib/nrser/core_ext/pathname.rb, line 177
def closest_dir
  directory? ? self : dirname
end
find_up(rel_path, **kwds) click to toggle source

See {NRSER.find_up}.

# File lib/nrser/core_ext/pathname.rb, line 105
def find_up rel_path, **kwds
  NRSER.find_up rel_path, **kwds, from: self
end
find_up!(rel_path, **kwds) click to toggle source

See {NRSER.find_up!}.

# File lib/nrser/core_ext/pathname.rb, line 112
def find_up! rel_path, **kwds
  NRSER.find_up! rel_path, **kwds, from: self
end
start_with?(*prefixes) click to toggle source

override to accept Pathname instances.

@param [String] prefixes

the prefixes to see if the Pathname starts with.

@return [Boolean]

true if the Pathname starts with any of the prefixes.
# File lib/nrser/core_ext/pathname.rb, line 34
def start_with? *prefixes
  to_s.start_with? *prefixes.map { |prefix|
    if Pathname === prefix
      prefix.to_s
    else
      prefix
    end
  }
end
sub(pattern, *args, &block) click to toggle source

Our override of `#sub` to support {Pathname} instances as patterns.

Just calls `#to_s` on `pattern` if it's a {Pathname} before passing down to {#_core_sub}.

@param [String | Regexp | Pathname] pattern

Thing to replace.

@param args

See Ruby core's [String#sub][], which [Pathname#sub][] calls between 
stringifying and re-wrapping in a {Pathname} (core's [String#sub][] is 
overloaded).

[String#sub]: https://ruby-doc.org/core/String.html#method-i-sub
[Pathname#sub]: https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html#method-i-sub

@param [Proc] block

See [String#sub][].

@return [Pathname]

A brand new Pathname boys and girls!
# File lib/nrser/core_ext/pathname.rb, line 83
def sub pattern, *args, &block
  case pattern
  when Pathname
    _core_sub pattern.to_s, *args, &block
  else
    _core_sub pattern, *args, &block
  end
end
Also aliased as: _core_sub
subpath?(other, root: nil, strict: false) click to toggle source

Is `other` a subpath of `self`?

Which - it turns out - is a bit of a ricky question! Who knew?!

Maybe that's why it's not in the stand' lib.

Here's how we gonna go:

  1. Raise a {NRSER::ValueError} unless `self` is a {#directory?} and is {#absolute?}.

    I don't think it make any sense to ask about subpaths of something that is not a directory, and things just get too messy unless it's absolute since we need to expand `other` to make sure it doesn't dot-dot-dig it's way outta there.

2.

@param [Boolean] strict

Decides behavior when `other` expands to the same directory as `self`:

1.  When `strict: false` (the default) a directory **is** considered a 
    subpath of itself.

2.  When `strict: true`, a directory **is not** considered a subpath of
    itself.

@return [Boolean]

`true` if `other` is a path inside `self`.

See the `strict` parameter for behavior when `other` expands to `self`.

@raise [NRSER::ValueError]

If `self` is not a {#directory?}.

@raise [NRSER::ValueError]

If `self` is not {#absolute?}.
# File lib/nrser/core_ext/pathname/subpath.rb, line 62
def subpath? other, root: nil, strict: false
  unless directory?
    raise NRSER::ValueError.new \
      "Receiver {Pathname}", self, "must be a {#directory} in order to test",
      "for subpaths",
      value: self
  end

  unless absolute?
    raise NRSER::ValueError.new \
      "Receiver {Pathname}", self, "must be {#absolute?} in order to test",
      "for subpaths",
      value: self
  end

  abs_other = other.to_pn.expand_path root

  # Deal with easy case first, when they're the same dir
  return !strict if self == abs_other

  # Ok, now see if they prefix match
  abs_other.start_with? self
end
to_dot_rel(**kwds) click to toggle source

Shortcut to call {#to_rel} with `dot_slash=true`.

@param base_dir: (see .to_rel) @return (see .to_rel)

# File lib/nrser/core_ext/pathname.rb, line 145
def to_dot_rel **kwds
  to_rel **kwds, dot_slash: true
end
to_dot_rel_s(**kwds) click to toggle source

Shortcut to call {#to_rel_s} with `dot_slash=true`.

@param base_dir: (see .to_rel_s) @return (see .to_rel_s)

# File lib/nrser/core_ext/pathname.rb, line 167
def to_dot_rel_s **kwds
  to_rel_s( **kwds, dot_slash: true ).to_s
end
to_pn() click to toggle source

Just returns `self`. Implemented to match the {String#to_pn} API so it can be called on an argument that may be either one.

@return [Pathname]

# File lib/nrser/core_ext/pathname.rb, line 98
def to_pn
  self
end
to_rel(base_dir: Pathname.getwd, dot_slash: false) click to toggle source

Shortcut to convert into a relative pathname, by default from the working directory, with option to `./` prefix.

@param [Pathname] base_dir

Directory you want the result to be relative to.

@param [Boolean] dot_slash

When `true` will prepend `./` to the resulting path, unless it already
starts with `../`.

@return [Pathname]

# File lib/nrser/core_ext/pathname.rb, line 129
def to_rel base_dir: Pathname.getwd, dot_slash: false
  rel = relative_path_from base_dir
  
  if dot_slash && !rel.start_with?( /\.\.?\// )
    File.join( '.', rel ).to_pn
  else
    rel
  end
end
to_rel_s(**kwds) click to toggle source

Just a quick cut for `.to_rel.to_s`, since I seem to use that sort of form a lot.

@param (see to_rel)

@return [String]

# File lib/nrser/core_ext/pathname.rb, line 157
def to_rel_s **kwds
  to_rel( **kwds ).to_s
end