Class: Hike::Trail

Inherits:
Object
  • Object
show all
Defined in:
lib/hike/trail.rb

Overview

‘Trail` is the public container class for holding paths and extensions.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(root = ".") ⇒ Trail

A Trail accepts an optional root path that defaults to your current working directory. Any relative paths added to ‘Trail#paths` will expanded relative to the root.



48
49
50
51
52
53
 
# File 'lib/hike/trail.rb', line 48

def initialize(root = ".")
  @root       = Pathname.new(root).expand_path
  @paths      = Paths.new(@root)
  @extensions = Extensions.new
  @aliases    = Hash.new { |h, k| h[k] = Extensions.new }
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

‘Trail#aliases` is a mutable `Hash` mapping an extension to an `Array` of aliases.

trail = Hike::Trail.new
trail.paths.push "~/Projects/hike/site"
trail.aliases['.htm']   = 'html'
trail.aliases['.xhtml'] = 'html'
trail.aliases['.php']   = 'html'

Aliases provide a fallback when the primary extension is not matched. In the example above, a lookup for “foo.html” will check for the existence of “foo.htm”, “foo.xhtml”, or “foo.php”.



43
44
45
 
# File 'lib/hike/trail.rb', line 43

def aliases
  @aliases
end

#extensions ⇒ Object (readonly)

‘Trail#extensions` is a mutable `Extensions` collection.

trail = Hike::Trail.new
trail.paths.push "~/Projects/hike/lib"
trail.extensions.push ".rb"

Extensions allow you to find files by just their name omitting their extension. Is similar to Ruby’s require mechanism that allows you to require files with specifiying ‘foo.rb`.



29
30
31
 
# File 'lib/hike/trail.rb', line 29

def extensions
  @extensions
end

#paths ⇒ Object (readonly)

‘Trail#paths` is a mutable `Paths` collection.

trail = Hike::Trail.new
trail.paths.push "~/Projects/hike/lib", "~/Projects/hike/test"

The order of the paths is significant. Paths in the beginning of the collection will be checked first. In the example above, ‘~/Projects/hike/lib/hike.rb` would shadow the existent of `~/Projects/hike/test/hike.rb`.



18
19
20
 
# File 'lib/hike/trail.rb', line 18

def paths
  @paths
end

Instance Method Details

#alias_extension(new_extension, old_extension) ⇒ Object

Alias ‘new_extension` to `old_extension`



95
96
97
 
# File 'lib/hike/trail.rb', line 95

def alias_extension(new_extension, old_extension)
  aliases[normalize_extension(new_extension)] = normalize_extension(old_extension)
end

#append_extensions(*extensions) ⇒ Object Also known as: append_extension

Append ‘extension` to `Extensions` collection



84
85
86
 
# File 'lib/hike/trail.rb', line 84

def append_extensions(*extensions)
  self.extensions.push(*extensions)
end

#append_paths(*paths) ⇒ Object Also known as: append_path

Append ‘path` to `Paths` collection



67
68
69
 
# File 'lib/hike/trail.rb', line 67

def append_paths(*paths)
  self.paths.push(*paths)
end

#cached ⇒ Object Also known as: index

‘Trail#cached` returns an `CachedTrail` object that has the same interface as `Trail`. An `CachedTrail` is a cached `Trail` object that does not update when the file system changes. If you are confident that you are not making changes the paths you are searching, `cached` will avoid excess system calls.

cached = trail.cached
cached.find "hike/trail"
cached.find "test_trail"



156
157
158
 
# File 'lib/hike/trail.rb', line 156

def cached
  CachedTrail.new(root, paths, extensions, aliases)
end

#entries(path) ⇒ Object

‘Trail#entries` is equivalent to `Dir#entries`. It is not recommend to use this method for general purposes. It exists for parity with `CachedTrail#entries`.



166
167
168
169
170
171
172
173
 
# File 'lib/hike/trail.rb', line 166

def entries(path)
  pathname = Pathname.new(path)
  if pathname.directory?
    pathname.entries.reject { |entry| entry.to_s =~ /^\.|~$|^\#.*\#$/ }.sort
  else
    []
  end
end

#find(*args) ⇒ Object

‘Trail#find` returns a the expand path for a logical path in the path collection.

trail = Hike::Trail.new "~/Projects/hike"
trail.extensions.push ".rb"
trail.paths.push "lib", "test"

trail.find "hike/trail"
# => "~/Projects/hike/lib/hike/trail.rb"

trail.find "test_trail"
# => "~/Projects/hike/test/test_trail.rb"

‘find` accepts multiple fallback logical paths that returns the first match.

trail.find "hike", "hike/index"

is equivalent to

trail.find("hike") || trail.find("hike/index")



126
127
128
 
# File 'lib/hike/trail.rb', line 126

def find(*args)
  index.find(*args)
end

#find_all(*args, &block) ⇒ Object

‘Trail#find_all` returns all matching paths including fallbacks and

shadowed matches.

   trail.find_all("hike", "hike/index").each { |path| warn path }

‘find_all` returns an `Enumerator`. This allows you to filter your matches by any condition.

trail.find_all("application").find do |path|
  mime_type_for(path) == "text/css"
end



142
143
144
 
# File 'lib/hike/trail.rb', line 142

def find_all(*args, &block)
  cached.find_all(*args, &block)
end

#prepend_extensions(*extensions) ⇒ Object Also known as: prepend_extension

Prepend ‘extension` to `Extensions` collection



78
79
80
 
# File 'lib/hike/trail.rb', line 78

def prepend_extensions(*extensions)
  self.extensions.unshift(*extensions)
end

#prepend_paths(*paths) ⇒ Object Also known as: prepend_path

Prepend ‘path` to `Paths` collection



61
62
63
 
# File 'lib/hike/trail.rb', line 61

def prepend_paths(*paths)
  self.paths.unshift(*paths)
end

#remove_extension(extension) ⇒ Object

Remove ‘extension` from `Extensions` collection



90
91
92
 
# File 'lib/hike/trail.rb', line 90

def remove_extension(extension)
  self.extensions.delete(extension)
end

#remove_path(path) ⇒ Object

Remove ‘path` from `Paths` collection



73
74
75
 
# File 'lib/hike/trail.rb', line 73

def remove_path(path)
  self.paths.delete(path)
end

#root ⇒ Object

‘Trail#root` returns root path as a `String`. This attribute is immutable.



56
57
58
 
# File 'lib/hike/trail.rb', line 56

def root
  @root.to_s
end

#stat(path) ⇒ Object

‘Trail#stat` is equivalent to `File#stat`. It is not recommend to use this method for general purposes. It exists for parity with `CachedTrail#stat`.



178
179
180
181
182
183
184
 
# File 'lib/hike/trail.rb', line 178

def stat(path)
  if File.exist?(path)
    File.stat(path.to_s)
  else
    nil
  end
end

#unalias_extension(extension) ⇒ Object

Remove the alias for ‘extension`



100
101
102
 
# File 'lib/hike/trail.rb', line 100

def unalias_extension(extension)
  aliases.delete(normalize_extension(extension))
end