Class: Hike::Trail

Inherits:
Object
  • Object
show all
Includes:
FileUtils
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

Methods included from FileUtils

#entries, #stat

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.



50
51
52
53
54
55
 
# File 'lib/hike/trail.rb', line 50

def initialize(root = ".")
  @root       = Pathname.new(root).expand_path
  @paths      = Paths.new(@root)
  @extensions = Extensions.new
  @aliases    = {}
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".



45
46
47
 
# File 'lib/hike/trail.rb', line 45

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.



31
32
33
 
# File 'lib/hike/trail.rb', line 31

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.



20
21
22
 
# File 'lib/hike/trail.rb', line 20

def paths
  @paths
end

Instance Method Details

#alias_extension(new_extension, old_extension) ⇒ Object

Alias new_extension to old_extension



97
98
99
 
# File 'lib/hike/trail.rb', line 97

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



86
87
88
 
# File 'lib/hike/trail.rb', line 86

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

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

Append path to Paths collection



69
70
71
 
# File 'lib/hike/trail.rb', line 69

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"


158
159
160
 
# File 'lib/hike/trail.rb', line 158

def cached
  CachedTrail.new(root, paths, extensions, aliases)
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")


128
129
130
 
# File 'lib/hike/trail.rb', line 128

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


144
145
146
 
# File 'lib/hike/trail.rb', line 144

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



80
81
82
 
# File 'lib/hike/trail.rb', line 80

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

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

Prepend path to Paths collection



63
64
65
 
# File 'lib/hike/trail.rb', line 63

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

#remove_extension(extension) ⇒ Object

Remove extension from Extensions collection



92
93
94
 
# File 'lib/hike/trail.rb', line 92

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

#remove_path(path) ⇒ Object

Remove path from Paths collection



75
76
77
 
# File 'lib/hike/trail.rb', line 75

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

#root ⇒ Object

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



58
59
60
 
# File 'lib/hike/trail.rb', line 58

def root
  @root.to_s
end

#unalias_extension(extension) ⇒ Object

Remove the alias for extension



102
103
104
 
# File 'lib/hike/trail.rb', line 102

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