Class: Brandish::PathSet

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/brandish/path_set.rb

Overview

A set of paths that can be searched for a certain file. This is used for looking for certain files, like sources or templates. This can allow Brandish to provide "default" files.

Despite its name, the order in which the paths are added to the pathset are important.

Constant Summary collapse

DEFAULT_FIND_OPTIONS =

The default options for #find and #find_all.

Returns:

  • ({::Symbol => ::Object}) 
{ file: true, allow_absolute: false }.freeze

Instance Method Summary collapse

Constructor Details

#initialize ⇒ PathSet

Initialize the pathset.



37
38
39
 
# File 'lib/brandish/path_set.rb', line 37

def initialize
  @paths = []
end

Instance Method Details

#<<(path) ⇒ self

Adds a path to this pathset.

Parameters:

  • path (::String, ::Pathname)

Returns:

  • (self) 


45
46
47
 
# File 'lib/brandish/path_set.rb', line 45

def <<(path)
  @paths << ::Pathname.new(path)
end

#clear ⇒ void

This method returns an undefined value.

Removes all of the paths from this pathset.



21
 
# File 'lib/brandish/path_set.rb', line 21

def_delegator :@paths, :clear

#each ⇒ ::Enumerable<::Pathname> #each {|path| ... } ⇒ void

Overloads:

  • #each ⇒ ::Enumerable<::Pathname>

    Returns an enumerable over all of the paths in the pathset.

    Returns:

    • (::Enumerable<::Pathname>)
  • #each {|path| ... } ⇒ void

    This method returns an undefined value.

    Iterates over all of the paths in this pathset.

    Yields:

    • path For each path in the pathset.

    Yield Parameters:

    • path (::Pathname) —

      The path.



34
 
# File 'lib/brandish/path_set.rb', line 34

def_delegator :@paths, :each

#find(short, options = {}) ⇒ ::Pathname

Finds a file in the pathset. If the file is returned, it is guarenteed to exist. Relative paths, that do not expand out of the relative path, are handled like you would expect - the path is appended to one of the paths in the set, and checked for existance. However, for a file that expands out of the relative path (e.g. ../a or a/../../b), the behavior for expansion depends on the allow_absolute option. If allow_absolute is false (default), the path is expanded against / before it is joind with the paths in the set (e.g. ../a, against /path/to, with allow_absolute=false, expands to /path/to/a). If allow_absolute is true, it directly expanding against the path (e.g. ../a, against /path/to, with allow_absolute=true, expands to /path/a). allow_absolute should only be used if the given path is trusted. Absolute paths are handled in a similar manner; if allow_absolute=false, for /a against /path/to, it expands to /path/to/a; with allow_absolute=true, for /a against /path/to, it expands to /a.

Examples:

pathset
# => #<PathSet ...>
pathset.find("some/file")
# => #<Pathname /path/to/some/file>
pathset.find("not/real")
# !> NoFileError
pathset.find("/path/to/some/file")
# !> NoFileError
pathset.find("/path/to/some/file", allow_absolute: true)
# => #<Pathname /path/to/some/file>
pathset.find("../to/some/file")
# !> NoFileError
pathset.find("../to/some/file", allow_absolute: true)
# => #<Pathname /path/to/some/file>

Parameters:

  • short (::String, ::Pathname) —

    The "short" path to resolve.

  • options ({::Symbol => ::Object}) (defaults to: {}) —

    The options for finding.

Options Hash (options):

  • :allow_absolute (Boolean) — default: false
  • :file (Boolean) — default: true —

    Whether or not the full path must be a file for it to be considered existant. This should be set to true, because in most cases, it's the desired behavior.

Returns:

  • (::Pathname) —

    The full absolute path to the file.

Raises:



119
120
121
122
123
 
# File 'lib/brandish/path_set.rb', line 119

def find(short, options = {})
  find_all(short, options).next
rescue ::StopIteration
  fail NoFileError, "Could not find `#{short}' in any of the given paths (paths: #{@paths})"
end

#find_all(short, options = {}) {|path| ... } ⇒ void

This method returns an undefined value.

Finds all versions of the short path name in the paths in the path sets. If no block is given, it returns an enumerable; otherwise, if a block is given, it yields the joined path if it exists.

Parameters:

  • short (::String, ::Pathname) —

    The "short" path to resolve.

  • options ({::Symbol => ::Object}) (defaults to: {}) —

    The options for finding.

Options Hash (options):

  • :allow_absolute (Boolean) — default: false
  • :file (Boolean) — default: true —

    Whether or not the full path must be a file for it to be considered existant. This should be set to true, because in most cases, it's the desired behavior.

Yields:

  • (path) —

    For every file that exists.

Yield Parameters:

  • path (::Pathname) —

    The path to the file. This is guarenteed to exist.

Raises:

  • NoFileError If no file could be found.



140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/brandish/path_set.rb', line 140

def find_all(short, options = {})
  return to_enum(:find_all, short, options) unless block_given?
  short = ::Pathname.new(short)
  options = DEFAULT_FIND_OPTIONS.merge(options)

  @paths.reverse.each do |path|
    joined = path_join(path, short, options)
    yield joined if (options[:file] && joined.file?) || joined.exist?
  end

  nil
end

#replace(path) ⇒ self

Calls #clear, and then uses #<< to append the given path to the pathset, effectively replacing all of the paths in the pathset with the one given.

Parameters:

  • path (::String, ::Pathname)

Returns:

  • (self) 


55
56
57
58
 
# File 'lib/brandish/path_set.rb', line 55

def replace(path)
  clear
  self << path
end

#resolve(path, options = {}) ⇒ ::Pathname

"Resolves" a path. This is resolved the exact same way that #find and #find_all are (with some slight variations), and so can be used as a sort of "name" for a certain path.

Parameters:

  • path (::String, ::Pathname) —

    The path to the file.

  • options ({::Symbol => ::Object}) (defaults to: {}) —

    The options for resolution.

Returns:

  • (::Pathname) —

    The resolved path.



72
73
74
75
76
77
78
79
80
 
# File 'lib/brandish/path_set.rb', line 72

def resolve(path, options = {})
  options = DEFAULT_FIND_OPTIONS.merge(options)
  path = ::Pathname.new(path)
  if options[:allow_absolute]
    path.cleanpath
  else
    ::Pathname.new(path.expand_path("/").to_s.gsub(%r{\A(/|\\)}, ""))
  end
end