chickadee » pathfinder » path-find

Find the best (first) match for PATHNAME using pathfinder PF, and returns the absolute pathname if a match occurs or #f if not.

PATHNAME may be a filename such as "bar", which is looked for in each search path, or a relative path such as "foo/bar", in which "bar" is looked for in subdirectory "foo" under each search path. It can also be an absolute path; in this case, it is considered relative to the pathfinder root, confining the search to a single directory in the search path. If the resulting directory is not in or under the search path, #f is returned.

MATCHER is an optional pathfinder matcher which indicates the matching method; if #f or not present, the matcher assocated with the pathfinder object is used.

TEST is an optional pathfinder test which performs an additional test before admitting the file. If #f or not present, the test associated with the pathfinder object is used.

A very simple example:

; The file tree:
; /usr/bin/ls
; /usr/bin/rsync
; /usr/local/bin/rsync

(define pf (make-pathfinder '("/usr/local/bin" "/usr/bin")))
(path-find pf "ls")
  ; => "/usr/bin/ls"
(path-find pf "rsync")
  ; => "/usr/local/bin/rsync"
(path-find pf "flotz")
  ; #f

A more complicated example. Here we add a pathfinder root, relative search paths and absolute pathnames into the mix:

; The file tree:
; /home/hacker/usr/bin/ls
; /home/hacker/usr/local/bin/ls
; /home/hacker/usr/sbin/fsck

(define pf (make-pathfinder '("local/bin" "bin") root: "/home/hacker/usr")
(path-find pf "ls")
  ; => "/home/hacker/usr/local/bin/ls"
(path-find pf "/local/bin/ls")
  ; => "/home/hacker/usr/local/bin/ls"
(path-find pf "/bin/ls")         ;; Absolute search of /home/hacker/usr/bin
  ; => "/home/hacker/usr/bin/ls"
(path-find pf "/sbin/fsck")      ;; Maps to /home/hacker/usr/sbin, but it's not in search path
  ; => #f

For further examples, see the matchers pf:exact, pf:extensions and pf:compound.