hike 0.7.1 → 1.0.0

data/lib/hike.rb

@@ -1,5 +1,5 @@
 module Hike
-  VERSION = "0.7.1"
+  VERSION = "1.0.0"
 
   autoload :Extensions,      "hike/extensions"
   autoload :Index,           "hike/index"

data/lib/hike/extensions.rb

@@ -1,7 +1,17 @@
 require 'hike/normalized_array'
 
 module Hike
+  # `Extensions` is an internal collection for tracking extension names.
   class Extensions < NormalizedArray
+    # Extensions added to this array are normalized with a leading
+    # `.`.
+    #
+    #     extensions << "js"
+    #     extensions << ".css"
+    #
+    #     extensions
+    #     # => [".js", ".css"]
+    #
     def normalize_element(extension)
       if extension[/^\./]
         extension

data/lib/hike/index.rb

@@ -1,11 +1,24 @@
 require 'pathname'
 
 module Hike
+  # `Index` is an internal cached variant of `Trail`. It assumes the
+  # file system does not change between `find` calls. All `stat` and
+  # `entries` calls are cached for the lifetime of the `Index` object.
   class Index
-    attr_reader :paths, :extensions
+    # `Index#paths` is an immutable `Paths` collection.
+    attr_reader :paths
 
+    # `Index#extensions` is an immutable `Extensions` collection.
+    attr_reader :extensions
+
+    # `Index.new` is an internal method. Instead of constructing it
+    # directly, create a `Trail` and call `Trail#index`.
     def initialize(root, paths, extensions)
-      @root       = root
+      @root = root
+
+      # Freeze is used here so an error is throw if a mutator method
+      # is called on the array. Mutating `@paths` or `@extensions`
+      # would have unpredictable results.
       @paths      = paths.dup.freeze
       @extensions = extensions.dup.freeze
       @pathnames  = paths.map { |path| Pathname.new(path) }
@@ -15,14 +28,20 @@ module Hike
       @patterns = {}
     end
 
+    # `Index#root` returns root path as a `String`. This attribute is immutable.
     def root
       @root.to_s
     end
 
+    # `Index#index` returns `self` to be compatable with the `Trail` interface.
     def index
       self
     end
 
+    # The real implementation of `find`. `Trail#find` generates a one
+    # time index and delegates here.
+    #
+    # See `Trail#find` for usage.
     def find(*logical_paths, &block)
       if block_given?
         options = extract_options!(logical_paths)
@@ -55,6 +74,7 @@ module Hike
         logical_path.to_s =~ /^\.\.?\//
       end
 
+      # Finds logical path across all `paths`
       def find_in_paths(logical_path, &block)
         dirname, basename = logical_path.split
         @pathnames.each do |base_path|
@@ -62,13 +82,18 @@ module Hike
         end
       end
 
+      # Finds relative logical path, `../test/test_trail`. Requires a
+      # `base_path` for reference.
       def find_in_base_path(logical_path, base_path, &block)
         candidate = base_path.join(logical_path)
         dirname, basename = candidate.split
         match(dirname, basename, &block) if paths_contain?(dirname)
       end
 
+      # Checks if the path is actually on the file system and performs
+      # any syscalls if necessary.
       def match(dirname, basename)
+        # Potential `entries` syscall
         matches = entries(dirname)
 
         pattern = pattern_for(basename)
@@ -76,14 +101,19 @@ module Hike
 
         sort_matches(matches, basename).each do |path|
           pathname = dirname.join(path)
-          stat     = stat(pathname)
 
+          # Potential `stat` syscall
+          stat = stat(pathname)
+
+          # Exclude directories
           if stat && stat.file?
             yield pathname.to_s
           end
         end
       end
 
+      # A cached version of `File.stat`. Returns nil if the file does
+      # not exist.
       def stat(pathname)
         if @stats.key?(pathname)
           @stats[pathname]
@@ -96,16 +126,22 @@ module Hike
         end
       end
 
+      # A cached version of `Dir.entries` that filters out `.` and
+      # `..`. Returns an empty `Array` if the directory does not exist.
       def entries(pathname)
         @entries[pathname] ||= pathname.entries.reject { |entry| entry.to_s =~ /^\.\.?$/ }
       rescue Errno::ENOENT
         @entries[pathname] = []
       end
 
+      # Returns true if `dirname` is a subdirectory of any of the `paths`
       def paths_contain?(dirname)
         paths.any? { |path| dirname.to_s[0, path.length] == path }
       end
 
+      # Returns a `Regexp` that matches the allowed extensions.
+      #
+      #     pattern_for("index.html") #=> /^index.html(.builder|.erb)+$/
       def pattern_for(basename)
         @patterns[basename] ||= begin
           extension_pattern = extensions.map { |e| Regexp.escape(e) }.join("|")
@@ -113,6 +149,9 @@ module Hike
         end
       end
 
+      # Sorts candidate matches by their extension
+      # priority. Extensions in the front of the `extensions` carry
+      # more weight.
       def sort_matches(matches, basename)
         matches.sort_by do |match|
           extnames = match.to_s[basename.to_s.length..-1].scan(/.[^.]+/)

data/lib/hike/normalized_array.rb

@@ -1,4 +1,9 @@
 module Hike
+  # `NormalizedArray` is an internal abstract wrapper class that calls
+  # a callback `normalize_element` anytime an element is added to the
+  # Array.
+  #
+  # `Extensions` and `Paths` are subclasses of `NormalizedArray`.
   class NormalizedArray < Array
     def initialize
       super()

data/lib/hike/paths.rb

@@ -2,12 +2,22 @@ require 'pathname'
 require 'hike/normalized_array'
 
 module Hike
+  # `Paths` is an internal collection for tracking path strings.
   class Paths < NormalizedArray
     def initialize(root = ".")
       @root = Pathname.new(root)
       super()
     end
 
+    # Relative paths added to this array are expanded relative to `@root`.
+    #
+    #     paths = Paths.new("/usr/local")
+    #     paths << "tmp"
+    #     paths << "/tmp"
+    #
+    #     paths
+    #     # => ["/usr/local/tmp", "/tmp"]
+    #
     def normalize_element(path)
       path = Pathname.new(path)
       path = @root.join(path) if path.relative?

data/lib/hike/trail.rb

@@ -4,25 +4,94 @@ require 'hike/index'
 require 'hike/paths'
 
 module Hike
+  # `Trail` is the public container class for holding paths and extensions.
   class Trail
-    attr_reader :paths, :extensions
+    # `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`.
+    attr_reader :paths
 
+    # `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`.
+    attr_reader :extensions
+
+    # 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.
     def initialize(root = ".")
       @root       = Pathname.new(root).expand_path
       @paths      = Paths.new(@root)
       @extensions = Extensions.new
     end
 
+    # `Trail#root` returns root path as a `String`. This attribute is immutable.
     def root
       @root.to_s
     end
 
-    def index
-      Index.new(root, paths, extensions)
-    end
-
+    # `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")
+    #
+    # Though `find` always returns the first match, it is possible
+    # to iterate over all shadowed matches and fallbacks by supplying
+    # a block.
+    #
+    #     trail.find("hike", "hike/index") { |path| warn path }
+    #
+    # This allows you to filter your matches by any condition.
+    #
+    #     trail.find("application") do |path|
+    #       return path if mime_type_for(path) == "text/css"
+    #     end
+    #
     def find(*args, &block)
       index.find(*args, &block)
     end
+
+    # `Trail#index` returns an `Index` object that has the same
+    # interface as `Trail`. An `Index` 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, `index` will avoid excess system calls.
+    #
+    #     index = trail.index
+    #     index.find "hike/trail"
+    #     index.find "test_trail"
+    #
+    def index
+      Index.new(root, paths, extensions)
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: hike
 version: !ruby/object:Gem::Version 
-  hash: 1
+  hash: 23
   prerelease: 
   segments: 
-  - 0
-  - 7
   - 1
-  version: 0.7.1
+  - 0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Sam Stephenson
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-05 00:00:00 -05:00
+date: 2011-04-28 00:00:00 -05:00
 default_executable: 
 dependencies: []