src/cmd/godoc/filesystem.go - go - Git at Google

 // Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // This file defines types for abstract file system access and
 // provides an implementation accessing the file system of the
 // underlying OS.

 package main

 import (
 	"fmt"
 	"io"
 	"io/ioutil"
 	"net/http"
 	"os"
 	pathpkg "path"
 	"path/filepath"
 	"sort"
 	"strings"
 	"time"
 )

 // fs is the file system that godoc reads from and serves.
 // It is a virtual file system that operates on slash-separated paths,
 // and its root corresponds to the Go distribution root: /src/pkg
 // holds the source tree, and so on.  This means that the URLs served by
 // the godoc server are the same as the paths in the virtual file
 // system, which helps keep things simple.
 //
 // New file trees - implementations of FileSystem - can be added to
 // the virtual file system using nameSpace's Bind method.
 // The usual setup is to bind OS(runtime.GOROOT) to the root
 // of the name space and then bind any GOPATH/src directories
 // on top of /src/pkg, so that all sources are in /src/pkg.
 //
 // For more about name spaces, see the nameSpace type's
 // documentation below.
 //
 // The use of this virtual file system means that most code processing
 // paths can assume they are slash-separated and should be using
 // package path (often imported as pathpkg) to manipulate them,
 // even on Windows.
 //
 var fs = nameSpace{} // the underlying file system for godoc

 // Setting debugNS = true will enable debugging prints about
 // name space translations.
 const debugNS = false

 // The FileSystem interface specifies the methods godoc is using
 // to access the file system for which it serves documentation.
 type FileSystem interface {
 	Open(path string) (readSeekCloser, error)
 	Lstat(path string) (os.FileInfo, error)
 	Stat(path string) (os.FileInfo, error)
 	ReadDir(path string) ([]os.FileInfo, error)
 	String() string
 }

 type readSeekCloser interface {
 	io.Reader
 	io.Seeker
 	io.Closer
 }

 // ReadFile reads the file named by path from fs and returns the contents.
 func ReadFile(fs FileSystem, path string) ([]byte, error) {
 	rc, err := fs.Open(path)
 	if err != nil {
 		return nil, err
 	}
 	defer rc.Close()
 	return ioutil.ReadAll(rc)
 }

 // OS returns an implementation of FileSystem reading from the
 // tree rooted at root.  Recording a root is convenient everywhere
 // but necessary on Windows, because the slash-separated path
 // passed to Open has no way to specify a drive letter.  Using a root
 // lets code refer to OS(`c:\`), OS(`d:\`) and so on.
 func OS(root string) FileSystem {
 	return osFS(root)
 }

 type osFS string

 func (root osFS) String() string { return "os(" + string(root) + ")" }

 func (root osFS) resolve(path string) string {
 	// Clean the path so that it cannot possibly begin with ../.
 	// If it did, the result of filepath.Join would be outside the
 	// tree rooted at root.  We probably won't ever see a path
 	// with .. in it, but be safe anyway.
 	path = pathpkg.Clean("/" + path)

 	return filepath.Join(string(root), path)
 }

 func (root osFS) Open(path string) (readSeekCloser, error) {
 	f, err := os.Open(root.resolve(path))
 	if err != nil {
 		return nil, err
 	}
 	fi, err := f.Stat()
 	if err != nil {
 		return nil, err
 	}
 	if fi.IsDir() {
 		return nil, fmt.Errorf("Open: %s is a directory", path)
 	}
 	return f, nil
 }

 func (root osFS) Lstat(path string) (os.FileInfo, error) {
 	return os.Lstat(root.resolve(path))
 }

 func (root osFS) Stat(path string) (os.FileInfo, error) {
 	return os.Stat(root.resolve(path))
 }

 func (root osFS) ReadDir(path string) ([]os.FileInfo, error) {
 	return ioutil.ReadDir(root.resolve(path)) // is sorted
 }

 // hasPathPrefix returns true if x == y or x == y + "/" + more
 func hasPathPrefix(x, y string) bool {
 	return x == y || strings.HasPrefix(x, y) && (strings.HasSuffix(y, "/") || strings.HasPrefix(x[len(y):], "/"))
 }

 // A nameSpace is a file system made up of other file systems
 // mounted at specific locations in the name space.
 //
 // The representation is a map from mount point locations
 // to the list of file systems mounted at that location.  A traditional
 // Unix mount table would use a single file system per mount point,
 // but we want to be able to mount multiple file systems on a single
 // mount point and have the system behave as if the union of those
 // file systems were present at the mount point.
 // For example, if the OS file system has a Go installation in
 // c:\Go and additional Go path trees in  d:\Work1 and d:\Work2, then
 // this name space creates the view we want for the godoc server:
 //
 //	nameSpace{
 //		"/": {
 //			{old: "/", fs: OS(`c:\Go`), new: "/"},
 //		},
 //		"/src/pkg": {
 //			{old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
 //			{old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
 //			{old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
 //		},
 //	}
 //
 // This is created by executing:
 //
 //	ns := nameSpace{}
 //	ns.Bind("/", OS(`c:\Go`), "/", bindReplace)
 //	ns.Bind("/src/pkg", OS(`d:\Work1`), "/src", bindAfter)
 //	ns.Bind("/src/pkg", OS(`d:\Work2`), "/src", bindAfter)
 //
 // A particular mount point entry is a triple (old, fs, new), meaning that to
 // operate on a path beginning with old, replace that prefix (old) with new
 // and then pass that path to the FileSystem implementation fs.
 //
 // Given this name space, a ReadDir of /src/pkg/code will check each prefix
 // of the path for a mount point (first /src/pkg/code, then /src/pkg, then /src,
 // then /), stopping when it finds one.  For the above example, /src/pkg/code
 // will find the mount point at /src/pkg:
 //
 //	{old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
 //	{old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
 //	{old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
 //
 // ReadDir will when execute these three calls and merge the results:
 //
 //	OS(`c:\Go`).ReadDir("/src/pkg/code")
 //	OS(`d:\Work1').ReadDir("/src/code")
 //	OS(`d:\Work2').ReadDir("/src/code")
 //
 // Note that the "/src/pkg" in "/src/pkg/code" has been replaced by
 // just "/src" in the final two calls.
 //
 // OS is itself an implementation of a file system: it implements
 // OS(`c:\Go`).ReadDir("/src/pkg/code") as ioutil.ReadDir(`c:\Go\src\pkg\code`).
 //
 // Because the new path is evaluated by fs (here OS(root)), another way
 // to read the mount table is to mentally combine fs+new, so that this table:
 //
 //	{old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
 //	{old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
 //	{old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
 //
 // reads as:
 //
 //	"/src/pkg" -> c:\Go\src\pkg
 //	"/src/pkg" -> d:\Work1\src
 //	"/src/pkg" -> d:\Work2\src
 //
 // An invariant (a redundancy) of the name space representation is that
 // ns[mtpt][i].old is always equal to mtpt (in the example, ns["/src/pkg"]'s
 // mount table entries always have old == "/src/pkg").  The 'old' field is
 // useful to callers, because they receive just a []mountedFS and not any
 // other indication of which mount point was found.
 //
 type nameSpace map[string][]mountedFS

 // A mountedFS handles requests for path by replacing
 // a prefix 'old' with 'new' and then calling the fs methods.
 type mountedFS struct {
 	old string
 	fs  FileSystem
 	new string
 }

 // translate translates path for use in m, replacing old with new.
 //
 // mountedFS{"/src/pkg", fs, "/src"}.translate("/src/pkg/code") == "/src/code".
 func (m mountedFS) translate(path string) string {
 	path = pathpkg.Clean("/" + path)
 	if !hasPathPrefix(path, m.old) {
 		panic("translate " + path + " but old=" + m.old)
 	}
 	return pathpkg.Join(m.new, path[len(m.old):])
 }

 func (nameSpace) String() string {
 	return "ns"
 }

 // Fprint writes a text representation of the name space to w.
 func (ns nameSpace) Fprint(w io.Writer) {
 	fmt.Fprint(w, "name space {\n")
 	var all []string
 	for mtpt := range ns {
 		all = append(all, mtpt)
 	}
 	sort.Strings(all)
 	for _, mtpt := range all {
 		fmt.Fprintf(w, "\t%s:\n", mtpt)
 		for _, m := range ns[mtpt] {
 			fmt.Fprintf(w, "\t\t%s %s\n", m.fs, m.new)
 		}
 	}
 	fmt.Fprint(w, "}\n")
 }

 // clean returns a cleaned, rooted path for evaluation.
 // It canonicalizes the path so that we can use string operations
 // to analyze it.
 func (nameSpace) clean(path string) string {
 	return pathpkg.Clean("/" + path)
 }

 // Bind causes references to old to redirect to the path new in newfs.
 // If mode is bindReplace, old redirections are discarded.
 // If mode is bindBefore, this redirection takes priority over existing ones,
 // but earlier ones are still consulted for paths that do not exist in newfs.
 // If mode is bindAfter, this redirection happens only after existing ones
 // have been tried and failed.

 const (
 	bindReplace = iota
 	bindBefore
 	bindAfter
 )

 func (ns nameSpace) Bind(old string, newfs FileSystem, new string, mode int) {
 	old = ns.clean(old)
 	new = ns.clean(new)
 	m := mountedFS{old, newfs, new}
 	var mtpt []mountedFS
 	switch mode {
 	case bindReplace:
 		mtpt = append(mtpt, m)
 	case bindAfter:
 		mtpt = append(mtpt, ns.resolve(old)...)
 		mtpt = append(mtpt, m)
 	case bindBefore:
 		mtpt = append(mtpt, m)
 		mtpt = append(mtpt, ns.resolve(old)...)
 	}

 	// Extend m.old, m.new in inherited mount point entries.
 	for i := range mtpt {
 		m := &mtpt[i]
 		if m.old != old {
 			if !hasPathPrefix(old, m.old) {
 				// This should not happen.  If it does, panic so
 				// that we can see the call trace that led to it.
 				panic(fmt.Sprintf("invalid Bind: old=%q m={%q, %s, %q}", old, m.old, m.fs.String(), m.new))
 			}
 			suffix := old[len(m.old):]
 			m.old = pathpkg.Join(m.old, suffix)
 			m.new = pathpkg.Join(m.new, suffix)
 		}
 	}

 	ns[old] = mtpt
 }

 // resolve resolves a path to the list of mountedFS to use for path.
 func (ns nameSpace) resolve(path string) []mountedFS {
 	path = ns.clean(path)
 	for {
 		if m := ns[path]; m != nil {
 			if debugNS {
 				fmt.Printf("resolve %s: %v\n", path, m)
 			}
 			return m
 		}
 		if path == "/" {
 			break
 		}
 		path = pathpkg.Dir(path)
 	}
 	return nil
 }

 // Open implements the FileSystem Open method.
 func (ns nameSpace) Open(path string) (readSeekCloser, error) {
 	var err error
 	for _, m := range ns.resolve(path) {
 		if debugNS {
 			fmt.Printf("tx %s: %v\n", path, m.translate(path))
 		}
 		r, err1 := m.fs.Open(m.translate(path))
 		if err1 == nil {
 			return r, nil
 		}
 		if err == nil {
 			err = err1
 		}
 	}
 	if err == nil {
 		err = &os.PathError{Op: "open", Path: path, Err: os.ErrNotExist}
 	}
 	return nil, err
 }

 // stat implements the FileSystem Stat and Lstat methods.
 func (ns nameSpace) stat(path string, f func(FileSystem, string) (os.FileInfo, error)) (os.FileInfo, error) {
 	var err error
 	for _, m := range ns.resolve(path) {
 		fi, err1 := f(m.fs, m.translate(path))
 		if err1 == nil {
 			return fi, nil
 		}
 		if err == nil {
 			err = err1
 		}
 	}
 	if err == nil {
 		err = &os.PathError{Op: "stat", Path: path, Err: os.ErrNotExist}
 	}
 	return nil, err
 }

 func (ns nameSpace) Stat(path string) (os.FileInfo, error) {
 	return ns.stat(path, FileSystem.Stat)
 }

 func (ns nameSpace) Lstat(path string) (os.FileInfo, error) {
 	return ns.stat(path, FileSystem.Lstat)
 }

 // dirInfo is a trivial implementation of os.FileInfo for a directory.
 type dirInfo string

 func (d dirInfo) Name() string       { return string(d) }
 func (d dirInfo) Size() int64        { return 0 }
 func (d dirInfo) Mode() os.FileMode  { return os.ModeDir | 0555 }
 func (d dirInfo) ModTime() time.Time { return startTime }
 func (d dirInfo) IsDir() bool        { return true }
 func (d dirInfo) Sys() interface{}   { return nil }

 var startTime = time.Now()

 // ReadDir implements the FileSystem ReadDir method.  It's where most of the magic is.
 // (The rest is in resolve.)
 //
 // Logically, ReadDir must return the union of all the directories that are named
 // by path.  In order to avoid misinterpreting Go packages, of all the directories
 // that contain Go source code, we only include the files from the first,
 // but we include subdirectories from all.
 //
 // ReadDir must also return directory entries needed to reach mount points.
 // If the name space looks like the example in the type nameSpace comment,
 // but c:\Go does not have a src/pkg subdirectory, we still want to be able
 // to find that subdirectory, because we've mounted d:\Work1 and d:\Work2
 // there.  So if we don't see "src" in the directory listing for c:\Go, we add an
 // entry for it before returning.
 //
 func (ns nameSpace) ReadDir(path string) ([]os.FileInfo, error) {
 	path = ns.clean(path)

 	var (
 		haveGo   = false
 		haveName = map[string]bool{}
 		all      []os.FileInfo
 		err      error
 		first    []os.FileInfo
 	)

 	for _, m := range ns.resolve(path) {
 		dir, err1 := m.fs.ReadDir(m.translate(path))
 		if err1 != nil {
 			if err == nil {
 				err = err1
 			}
 			continue
 		}

 		if dir == nil {
 			dir = []os.FileInfo{}
 		}

 		if first == nil {
 			first = dir
 		}

 		// If we don't yet have Go files in 'all' and this directory
 		// has some, add all the files from this directory.
 		// Otherwise, only add subdirectories.
 		useFiles := false
 		if !haveGo {
 			for _, d := range dir {
 				if strings.HasSuffix(d.Name(), ".go") {
 					useFiles = true
 					haveGo = true
 					break
 				}
 			}
 		}

 		for _, d := range dir {
 			name := d.Name()
 			if (d.IsDir() || useFiles) && !haveName[name] {
 				haveName[name] = true
 				all = append(all, d)
 			}
 		}
 	}

 	// We didn't find any directories containing Go files.
 	// If some directory returned successfully, use that.
 	if !haveGo {
 		for _, d := range first {
 			if !haveName[d.Name()] {
 				haveName[d.Name()] = true
 				all = append(all, d)
 			}
 		}
 	}

 	// Built union.  Add any missing directories needed to reach mount points.
 	for old := range ns {
 		if hasPathPrefix(old, path) && old != path {
 			// Find next element after path in old.
 			elem := old[len(path):]
 			if strings.HasPrefix(elem, "/") {
 				elem = elem[1:]
 			}
 			if i := strings.Index(elem, "/"); i >= 0 {
 				elem = elem[:i]
 			}
 			if !haveName[elem] {
 				haveName[elem] = true
 				all = append(all, dirInfo(elem))
 			}
 		}
 	}

 	if len(all) == 0 {
 		return nil, err
 	}

 	sort.Sort(byName(all))
 	return all, nil
 }

 // byName implements sort.Interface.
 type byName []os.FileInfo

 func (f byName) Len() int           { return len(f) }
 func (f byName) Less(i, j int) bool { return f[i].Name() < f[j].Name() }
 func (f byName) Swap(i, j int)      { f[i], f[j] = f[j], f[i] }

 // An httpFS implements http.FileSystem using a FileSystem.
 type httpFS struct {
 	fs FileSystem
 }

 func (h *httpFS) Open(name string) (http.File, error) {
 	fi, err := h.fs.Stat(name)
 	if err != nil {
 		return nil, err
 	}
 	if fi.IsDir() {
 		return &httpDir{h.fs, name, nil}, nil
 	}
 	f, err := h.fs.Open(name)
 	if err != nil {
 		return nil, err
 	}
 	return &httpFile{h.fs, f, name}, nil
 }

 // httpDir implements http.File for a directory in a FileSystem.
 type httpDir struct {
 	fs      FileSystem
 	name    string
 	pending []os.FileInfo
 }

 func (h *httpDir) Close() error               { return nil }
 func (h *httpDir) Stat() (os.FileInfo, error) { return h.fs.Stat(h.name) }
 func (h *httpDir) Read([]byte) (int, error) {
 	return 0, fmt.Errorf("cannot Read from directory %s", h.name)
 }

 func (h *httpDir) Seek(offset int64, whence int) (int64, error) {
 	if offset == 0 && whence == 0 {
 		h.pending = nil
 		return 0, nil
 	}
 	return 0, fmt.Errorf("unsupported Seek in directory %s", h.name)
 }

 func (h *httpDir) Readdir(count int) ([]os.FileInfo, error) {
 	if h.pending == nil {
 		d, err := h.fs.ReadDir(h.name)
 		if err != nil {
 			return nil, err
 		}
 		if d == nil {
 			d = []os.FileInfo{} // not nil
 		}
 		h.pending = d
 	}

 	if len(h.pending) == 0 && count > 0 {
 		return nil, io.EOF
 	}
 	if count <= 0 || count > len(h.pending) {
 		count = len(h.pending)
 	}
 	d := h.pending[:count]
 	h.pending = h.pending[count:]
 	return d, nil
 }

 // httpFile implements http.File for a file (not directory) in a FileSystem.
 type httpFile struct {
 	fs FileSystem
 	readSeekCloser
 	name string
 }

 func (h *httpFile) Stat() (os.FileInfo, error) { return h.fs.Stat(h.name) }
 func (h *httpFile) Readdir(int) ([]os.FileInfo, error) {
 	return nil, fmt.Errorf("cannot Readdir from file %s", h.name)
 }
	// Copyright 2011 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// This file defines types for abstract file system access and
	// provides an implementation accessing the file system of the
	// underlying OS.

	package main

	import (
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"os"
	pathpkg "path"
	"path/filepath"
	"sort"
	"strings"
	"time"
	)

	// fs is the file system that godoc reads from and serves.
	// It is a virtual file system that operates on slash-separated paths,
	// and its root corresponds to the Go distribution root: /src/pkg
	// holds the source tree, and so on. This means that the URLs served by
	// the godoc server are the same as the paths in the virtual file
	// system, which helps keep things simple.
	//
	// New file trees - implementations of FileSystem - can be added to
	// the virtual file system using nameSpace's Bind method.
	// The usual setup is to bind OS(runtime.GOROOT) to the root
	// of the name space and then bind any GOPATH/src directories
	// on top of /src/pkg, so that all sources are in /src/pkg.
	//
	// For more about name spaces, see the nameSpace type's
	// documentation below.
	//
	// The use of this virtual file system means that most code processing
	// paths can assume they are slash-separated and should be using
	// package path (often imported as pathpkg) to manipulate them,
	// even on Windows.
	//
	var fs = nameSpace{} // the underlying file system for godoc

	// Setting debugNS = true will enable debugging prints about
	// name space translations.
	const debugNS = false

	// The FileSystem interface specifies the methods godoc is using
	// to access the file system for which it serves documentation.
	type FileSystem interface {
	Open(path string) (readSeekCloser, error)
	Lstat(path string) (os.FileInfo, error)
	Stat(path string) (os.FileInfo, error)
	ReadDir(path string) ([]os.FileInfo, error)
	String() string
	}

	type readSeekCloser interface {
	io.Reader
	io.Seeker
	io.Closer
	}

	// ReadFile reads the file named by path from fs and returns the contents.
	func ReadFile(fs FileSystem, path string) ([]byte, error) {
	rc, err := fs.Open(path)
	if err != nil {
	return nil, err
	}
	defer rc.Close()
	return ioutil.ReadAll(rc)
	}

	// OS returns an implementation of FileSystem reading from the
	// tree rooted at root. Recording a root is convenient everywhere
	// but necessary on Windows, because the slash-separated path
	// passed to Open has no way to specify a drive letter. Using a root
	// lets code refer to OS(`c:\`), OS(`d:\`) and so on.
	func OS(root string) FileSystem {
	return osFS(root)
	}

	type osFS string

	func (root osFS) String() string { return "os(" + string(root) + ")" }

	func (root osFS) resolve(path string) string {
	// Clean the path so that it cannot possibly begin with ../.
	// If it did, the result of filepath.Join would be outside the
	// tree rooted at root. We probably won't ever see a path
	// with .. in it, but be safe anyway.
	path = pathpkg.Clean("/" + path)

	return filepath.Join(string(root), path)
	}

	func (root osFS) Open(path string) (readSeekCloser, error) {
	f, err := os.Open(root.resolve(path))
	if err != nil {
	return nil, err
	}
	fi, err := f.Stat()
	if err != nil {
	return nil, err
	}
	if fi.IsDir() {
	return nil, fmt.Errorf("Open: %s is a directory", path)
	}
	return f, nil
	}

	func (root osFS) Lstat(path string) (os.FileInfo, error) {
	return os.Lstat(root.resolve(path))
	}

	func (root osFS) Stat(path string) (os.FileInfo, error) {
	return os.Stat(root.resolve(path))
	}

	func (root osFS) ReadDir(path string) ([]os.FileInfo, error) {
	return ioutil.ReadDir(root.resolve(path)) // is sorted
	}

	// hasPathPrefix returns true if x == y or x == y + "/" + more
	func hasPathPrefix(x, y string) bool {
	return x == y \|\| strings.HasPrefix(x, y) && (strings.HasSuffix(y, "/") \|\| strings.HasPrefix(x[len(y):], "/"))
	}

	// A nameSpace is a file system made up of other file systems
	// mounted at specific locations in the name space.
	//
	// The representation is a map from mount point locations
	// to the list of file systems mounted at that location. A traditional
	// Unix mount table would use a single file system per mount point,
	// but we want to be able to mount multiple file systems on a single
	// mount point and have the system behave as if the union of those
	// file systems were present at the mount point.
	// For example, if the OS file system has a Go installation in
	// c:\Go and additional Go path trees in d:\Work1 and d:\Work2, then
	// this name space creates the view we want for the godoc server:
	//
	// nameSpace{
	// "/": {
	// {old: "/", fs: OS(`c:\Go`), new: "/"},
	// },
	// "/src/pkg": {
	// {old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
	// {old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
	// {old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
	// },
	// }
	//
	// This is created by executing:
	//
	// ns := nameSpace{}
	// ns.Bind("/", OS(`c:\Go`), "/", bindReplace)
	// ns.Bind("/src/pkg", OS(`d:\Work1`), "/src", bindAfter)
	// ns.Bind("/src/pkg", OS(`d:\Work2`), "/src", bindAfter)
	//
	// A particular mount point entry is a triple (old, fs, new), meaning that to
	// operate on a path beginning with old, replace that prefix (old) with new
	// and then pass that path to the FileSystem implementation fs.
	//
	// Given this name space, a ReadDir of /src/pkg/code will check each prefix
	// of the path for a mount point (first /src/pkg/code, then /src/pkg, then /src,
	// then /), stopping when it finds one. For the above example, /src/pkg/code
	// will find the mount point at /src/pkg:
	//
	// {old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
	// {old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
	// {old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
	//
	// ReadDir will when execute these three calls and merge the results:
	//
	// OS(`c:\Go`).ReadDir("/src/pkg/code")
	// OS(`d:\Work1').ReadDir("/src/code")
	// OS(`d:\Work2').ReadDir("/src/code")
	//
	// Note that the "/src/pkg" in "/src/pkg/code" has been replaced by
	// just "/src" in the final two calls.
	//
	// OS is itself an implementation of a file system: it implements
	// OS(`c:\Go`).ReadDir("/src/pkg/code") as ioutil.ReadDir(`c:\Go\src\pkg\code`).
	//
	// Because the new path is evaluated by fs (here OS(root)), another way
	// to read the mount table is to mentally combine fs+new, so that this table:
	//
	// {old: "/src/pkg", fs: OS(`c:\Go`), new: "/src/pkg"},
	// {old: "/src/pkg", fs: OS(`d:\Work1`), new: "/src"},
	// {old: "/src/pkg", fs: OS(`d:\Work2`), new: "/src"},
	//
	// reads as:
	//
	// "/src/pkg" -> c:\Go\src\pkg
	// "/src/pkg" -> d:\Work1\src
	// "/src/pkg" -> d:\Work2\src
	//
	// An invariant (a redundancy) of the name space representation is that
	// ns[mtpt][i].old is always equal to mtpt (in the example, ns["/src/pkg"]'s
	// mount table entries always have old == "/src/pkg"). The 'old' field is
	// useful to callers, because they receive just a []mountedFS and not any
	// other indication of which mount point was found.
	//
	type nameSpace map[string][]mountedFS

	// A mountedFS handles requests for path by replacing
	// a prefix 'old' with 'new' and then calling the fs methods.
	type mountedFS struct {
	old string
	fs FileSystem
	new string
	}

	// translate translates path for use in m, replacing old with new.
	//
	// mountedFS{"/src/pkg", fs, "/src"}.translate("/src/pkg/code") == "/src/code".
	func (m mountedFS) translate(path string) string {
	path = pathpkg.Clean("/" + path)
	if !hasPathPrefix(path, m.old) {
	panic("translate " + path + " but old=" + m.old)
	}
	return pathpkg.Join(m.new, path[len(m.old):])
	}

	func (nameSpace) String() string {
	return "ns"
	}

	// Fprint writes a text representation of the name space to w.
	func (ns nameSpace) Fprint(w io.Writer) {
	fmt.Fprint(w, "name space {\n")
	var all []string
	for mtpt := range ns {
	all = append(all, mtpt)
	}
	sort.Strings(all)
	for _, mtpt := range all {
	fmt.Fprintf(w, "\t%s:\n", mtpt)
	for _, m := range ns[mtpt] {
	fmt.Fprintf(w, "\t\t%s %s\n", m.fs, m.new)
	}
	}
	fmt.Fprint(w, "}\n")
	}

	// clean returns a cleaned, rooted path for evaluation.
	// It canonicalizes the path so that we can use string operations
	// to analyze it.
	func (nameSpace) clean(path string) string {
	return pathpkg.Clean("/" + path)
	}

	// Bind causes references to old to redirect to the path new in newfs.
	// If mode is bindReplace, old redirections are discarded.
	// If mode is bindBefore, this redirection takes priority over existing ones,
	// but earlier ones are still consulted for paths that do not exist in newfs.
	// If mode is bindAfter, this redirection happens only after existing ones
	// have been tried and failed.

	const (
	bindReplace = iota
	bindBefore
	bindAfter
	)

	func (ns nameSpace) Bind(old string, newfs FileSystem, new string, mode int) {
	old = ns.clean(old)
	new = ns.clean(new)
	m := mountedFS{old, newfs, new}
	var mtpt []mountedFS
	switch mode {
	case bindReplace:
	mtpt = append(mtpt, m)
	case bindAfter:
	mtpt = append(mtpt, ns.resolve(old)...)
	mtpt = append(mtpt, m)
	case bindBefore:
	mtpt = append(mtpt, m)
	mtpt = append(mtpt, ns.resolve(old)...)
	}

	// Extend m.old, m.new in inherited mount point entries.
	for i := range mtpt {
	m := &mtpt[i]
	if m.old != old {
	if !hasPathPrefix(old, m.old) {
	// This should not happen. If it does, panic so
	// that we can see the call trace that led to it.
	panic(fmt.Sprintf("invalid Bind: old=%q m={%q, %s, %q}", old, m.old, m.fs.String(), m.new))
	}
	suffix := old[len(m.old):]
	m.old = pathpkg.Join(m.old, suffix)
	m.new = pathpkg.Join(m.new, suffix)
	}
	}

	ns[old] = mtpt
	}

	// resolve resolves a path to the list of mountedFS to use for path.
	func (ns nameSpace) resolve(path string) []mountedFS {
	path = ns.clean(path)
	for {
	if m := ns[path]; m != nil {
	if debugNS {
	fmt.Printf("resolve %s: %v\n", path, m)
	}
	return m
	}
	if path == "/" {
	break
	}
	path = pathpkg.Dir(path)
	}
	return nil
	}

	// Open implements the FileSystem Open method.
	func (ns nameSpace) Open(path string) (readSeekCloser, error) {
	var err error
	for _, m := range ns.resolve(path) {
	if debugNS {
	fmt.Printf("tx %s: %v\n", path, m.translate(path))
	}
	r, err1 := m.fs.Open(m.translate(path))
	if err1 == nil {
	return r, nil
	}
	if err == nil {
	err = err1
	}
	}
	if err == nil {
	err = &os.PathError{Op: "open", Path: path, Err: os.ErrNotExist}
	}
	return nil, err
	}

	// stat implements the FileSystem Stat and Lstat methods.
	func (ns nameSpace) stat(path string, f func(FileSystem, string) (os.FileInfo, error)) (os.FileInfo, error) {
	var err error
	for _, m := range ns.resolve(path) {
	fi, err1 := f(m.fs, m.translate(path))
	if err1 == nil {
	return fi, nil
	}
	if err == nil {
	err = err1
	}
	}
	if err == nil {
	err = &os.PathError{Op: "stat", Path: path, Err: os.ErrNotExist}
	}
	return nil, err
	}

	func (ns nameSpace) Stat(path string) (os.FileInfo, error) {
	return ns.stat(path, FileSystem.Stat)
	}

	func (ns nameSpace) Lstat(path string) (os.FileInfo, error) {
	return ns.stat(path, FileSystem.Lstat)
	}

	// dirInfo is a trivial implementation of os.FileInfo for a directory.
	type dirInfo string

	func (d dirInfo) Name() string { return string(d) }
	func (d dirInfo) Size() int64 { return 0 }
	func (d dirInfo) Mode() os.FileMode { return os.ModeDir \| 0555 }
	func (d dirInfo) ModTime() time.Time { return startTime }
	func (d dirInfo) IsDir() bool { return true }
	func (d dirInfo) Sys() interface{} { return nil }

	var startTime = time.Now()

	// ReadDir implements the FileSystem ReadDir method. It's where most of the magic is.
	// (The rest is in resolve.)
	//
	// Logically, ReadDir must return the union of all the directories that are named
	// by path. In order to avoid misinterpreting Go packages, of all the directories
	// that contain Go source code, we only include the files from the first,
	// but we include subdirectories from all.
	//
	// ReadDir must also return directory entries needed to reach mount points.
	// If the name space looks like the example in the type nameSpace comment,
	// but c:\Go does not have a src/pkg subdirectory, we still want to be able
	// to find that subdirectory, because we've mounted d:\Work1 and d:\Work2
	// there. So if we don't see "src" in the directory listing for c:\Go, we add an
	// entry for it before returning.
	//
	func (ns nameSpace) ReadDir(path string) ([]os.FileInfo, error) {
	path = ns.clean(path)

	var (
	haveGo = false
	haveName = map[string]bool{}
	all []os.FileInfo
	err error
	first []os.FileInfo
	)

	for _, m := range ns.resolve(path) {
	dir, err1 := m.fs.ReadDir(m.translate(path))
	if err1 != nil {
	if err == nil {
	err = err1
	}
	continue
	}

	if dir == nil {
	dir = []os.FileInfo{}
	}

	if first == nil {
	first = dir
	}

	// If we don't yet have Go files in 'all' and this directory
	// has some, add all the files from this directory.
	// Otherwise, only add subdirectories.
	useFiles := false
	if !haveGo {
	for _, d := range dir {
	if strings.HasSuffix(d.Name(), ".go") {
	useFiles = true
	haveGo = true
	break
	}
	}
	}

	for _, d := range dir {
	name := d.Name()
	if (d.IsDir() \|\| useFiles) && !haveName[name] {
	haveName[name] = true
	all = append(all, d)
	}
	}
	}

	// We didn't find any directories containing Go files.
	// If some directory returned successfully, use that.
	if !haveGo {
	for _, d := range first {
	if !haveName[d.Name()] {
	haveName[d.Name()] = true
	all = append(all, d)
	}
	}
	}

	// Built union. Add any missing directories needed to reach mount points.
	for old := range ns {
	if hasPathPrefix(old, path) && old != path {
	// Find next element after path in old.
	elem := old[len(path):]
	if strings.HasPrefix(elem, "/") {
	elem = elem[1:]
	}
	if i := strings.Index(elem, "/"); i >= 0 {
	elem = elem[:i]
	}
	if !haveName[elem] {
	haveName[elem] = true
	all = append(all, dirInfo(elem))
	}
	}
	}

	if len(all) == 0 {
	return nil, err
	}

	sort.Sort(byName(all))
	return all, nil
	}

	// byName implements sort.Interface.
	type byName []os.FileInfo

	func (f byName) Len() int { return len(f) }
	func (f byName) Less(i, j int) bool { return f[i].Name() < f[j].Name() }
	func (f byName) Swap(i, j int) { f[i], f[j] = f[j], f[i] }

	// An httpFS implements http.FileSystem using a FileSystem.
	type httpFS struct {
	fs FileSystem
	}

	func (h *httpFS) Open(name string) (http.File, error) {
	fi, err := h.fs.Stat(name)
	if err != nil {
	return nil, err
	}
	if fi.IsDir() {
	return &httpDir{h.fs, name, nil}, nil
	}
	f, err := h.fs.Open(name)
	if err != nil {
	return nil, err
	}
	return &httpFile{h.fs, f, name}, nil
	}

	// httpDir implements http.File for a directory in a FileSystem.
	type httpDir struct {
	fs FileSystem
	name string
	pending []os.FileInfo
	}

	func (h *httpDir) Close() error { return nil }
	func (h *httpDir) Stat() (os.FileInfo, error) { return h.fs.Stat(h.name) }
	func (h *httpDir) Read([]byte) (int, error) {
	return 0, fmt.Errorf("cannot Read from directory %s", h.name)
	}

	func (h *httpDir) Seek(offset int64, whence int) (int64, error) {
	if offset == 0 && whence == 0 {
	h.pending = nil
	return 0, nil
	}
	return 0, fmt.Errorf("unsupported Seek in directory %s", h.name)
	}

	func (h *httpDir) Readdir(count int) ([]os.FileInfo, error) {
	if h.pending == nil {
	d, err := h.fs.ReadDir(h.name)
	if err != nil {
	return nil, err
	}
	if d == nil {
	d = []os.FileInfo{} // not nil
	}
	h.pending = d
	}

	if len(h.pending) == 0 && count > 0 {
	return nil, io.EOF
	}
	if count <= 0 \|\| count > len(h.pending) {
	count = len(h.pending)
	}
	d := h.pending[:count]
	h.pending = h.pending[count:]
	return d, nil
	}

	// httpFile implements http.File for a file (not directory) in a FileSystem.
	type httpFile struct {
	fs FileSystem
	readSeekCloser
	name string
	}

	func (h *httpFile) Stat() (os.FileInfo, error) { return h.fs.Stat(h.name) }
	func (h *httpFile) Readdir(int) ([]os.FileInfo, error) {
	return nil, fmt.Errorf("cannot Readdir from file %s", h.name)
	}