package txtar

Import Path
	golang.org/x/tools/txtar (on go.dev)

Dependency Relation
	imports 10 packages, and imported by 0 packages

Involved Source Files

	  d archive.go
		Package txtar implements a trivial text-based file archive format.
		
		The goals for the format are:
		
		  - be trivial enough to create and edit by hand.
		  - be able to store trees of text files describing go command test cases.
		  - diff nicely in git history and code reviews.
		
		Non-goals include being a completely general archive format,
		storing binary data, storing file modes, storing special files like
		symbolic links, and so on.
		
		# Txtar format
		
		A txtar archive is zero or more comment lines and then a sequence of file entries.
		Each file entry begins with a file marker line of the form "-- FILENAME --"
		and is followed by zero or more file content lines making up the file data.
		The comment or file content ends at the next file marker line.
		The file marker line must begin with the three-byte sequence "-- "
		and end with the three-byte sequence " --", but the enclosed
		file name can be surrounding by additional white space,
		all of which is stripped.
		
		If the txtar file is missing a trailing newline on the final line,
		parsers should consider a final newline to be present anyway.
		
		There are no possible syntax errors in a txtar archive.

	    fs.go
Package-Level Type Names (total 7, in which 2 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Archive (struct)
		An Archive is a collection of files.

		Fields (total 2, both are exported)
			Comment []byte
			Files []File
		As Outputs Of (at least 2, both are exported)
			func Parse(data []byte) *Archive
			func ParseFile(file string) (*Archive, error)
		As Inputs Of (at least 2, both are exported)
			func Format(a *Archive) []byte
			func FS(a *Archive) (fs.FS, error)

	 type File (struct)
		A File is a single file in an archive.

		Fields (total 2, both are exported)
			Data []byte
				// text content of file

			Name string
				// name of file ("foo/bar.txt")


	/* 5 unexporteds ... *//* 5 unexporteds: */
	 type fileinfo (struct)
		A fileinfo implements fs.FileInfo and fs.DirEntry for a given archive file.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			mode fs.FileMode
			path string
				// unique path to the file or directory within a filesystem

			size int
		Methods (total 8, all are exported)
			(*fileinfo) Info() (fs.FileInfo, error)
			(*fileinfo) IsDir() bool
			(*fileinfo) ModTime() time.Time
			(*fileinfo) Mode() fs.FileMode
			(*fileinfo) Name() string
			(*fileinfo) Size() int64
			(*fileinfo) Sys() any
			(*fileinfo) Type() fs.FileMode
		Implements (at least 2, both are exported)
			*fileinfo : io/fs.DirEntry
			*fileinfo : io/fs.FileInfo

	 type filesystem (struct)
		A filesystem is a simple in-memory file system for txtar archives,
		represented as a map from valid path names to information about the
		files or directories they represent.
		
		File system operations are read only. Modifications to the underlying
		*Archive may race. To help prevent this, the filesystem tries
		to detect modification during Open and return ErrModified if it
		is able to detect a modification.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			ar *Archive
			nodes map[string]*node
		Methods (total 2, both are exported)
			(*filesystem) Open(name string) (fs.File, error)
			(*filesystem) ReadFile(name string) ([]byte, error)
		Implements (at least 2, both are exported)
			*filesystem : io/fs.FS
			*filesystem : io/fs.ReadFileFS
		As Inputs Of (at least 4, none are exported)
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func dataOf(fsys *filesystem, n *node) ([]byte, error)
			func directory(fsys *filesystem, dir string) (*node, error)
			func initFiles(fsys *filesystem) error
			func insert(fsys *filesystem, n *node) error

	 type node (struct)
		node is a file or directory in the tree of a filesystem.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			entries []fs.DirEntry
				// subdirectories and files (for directories)

			fileinfo fileinfo
				// fs.FileInfo and fs.DirEntry implementation

			fileinfo.mode fs.FileMode
			fileinfo.path string
				// unique path to the file or directory within a filesystem

			fileinfo.size int
			idx int
				// index into ar.Files (for files)

		Methods (total 8, all are exported)
			(*node) Info() (fs.FileInfo, error)
			(*node) IsDir() bool
			(*node) ModTime() time.Time
			(*node) Mode() fs.FileMode
			(*node) Name() string
			(*node) Size() int64
			(*node) Sys() any
			(*node) Type() fs.FileMode
		Implements (at least 2, both are exported)
			*node : io/fs.DirEntry
			*node : io/fs.FileInfo
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func directory(fsys *filesystem, dir string) (*node, error)
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func dataOf(fsys *filesystem, n *node) ([]byte, error)
			func insert(fsys *filesystem, n *node) error

	 type openDir (struct)
		A openDir is a directory fs.File (so also an fs.ReadDirFile) open for reading.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			entries []fs.DirEntry
			fileinfo fileinfo
			fileinfo.mode fs.FileMode
			fileinfo.path string
				// unique path to the file or directory within a filesystem

			fileinfo.size int
			offset int
		Methods (total 12, all are exported)
			(*openDir) Close() error
			(*openDir) Info() (fs.FileInfo, error)
			(*openDir) IsDir() bool
			(*openDir) ModTime() time.Time
			(*openDir) Mode() fs.FileMode
			(*openDir) Name() string
			(*openDir) Read(b []byte) (int, error)
			(*openDir) ReadDir(count int) ([]fs.DirEntry, error)
			(*openDir) Size() int64
			(*openDir) Stat() (fs.FileInfo, error)
			(*openDir) Sys() any
			(*openDir) Type() fs.FileMode
		Implements (at least 7, all are exported)
			*openDir : io.Closer
			*openDir : io.ReadCloser
			*openDir : io.Reader
			*openDir : io/fs.DirEntry
			*openDir : io/fs.File
			*openDir : io/fs.FileInfo
			*openDir : io/fs.ReadDirFile

	 type openFile (struct)
		An openFile is a regular (non-directory) fs.File open for reading.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			data []byte
			fileinfo fileinfo
			fileinfo.mode fs.FileMode
			fileinfo.path string
				// unique path to the file or directory within a filesystem

			fileinfo.size int
			offset int64
		Methods (total 13, all are exported)
			(*openFile) Close() error
			(*openFile) Info() (fs.FileInfo, error)
			(*openFile) IsDir() bool
			(*openFile) ModTime() time.Time
			(*openFile) Mode() fs.FileMode
			(*openFile) Name() string
			(*openFile) Read(b []byte) (int, error)
			(*openFile) ReadAt(b []byte, offset int64) (int, error)
			(*openFile) Seek(offset int64, whence int) (int64, error)
			(*openFile) Size() int64
			(*openFile) Stat() (fs.FileInfo, error)
			(*openFile) Sys() any
			(*openFile) Type() fs.FileMode
		Implements (at least 11, all are exported)
			*openFile : io.Closer
			*openFile : io.ReadCloser
			*openFile : io.Reader
			*openFile : io.ReaderAt
			*openFile : io.ReadSeekCloser
			*openFile : io.ReadSeeker
			*openFile : io.Seeker
			*openFile : io/fs.DirEntry
			*openFile : io/fs.File
			*openFile : io/fs.FileInfo
			*openFile : mime/multipart.File


Package-Level Functions (total 11, in which 4 are exported)

	 func Format(a *Archive) []byte
		Format returns the serialized form of an Archive.
		It is assumed that the Archive data structure is well-formed:
		a.Comment and all a.File[i].Data contain no file marker lines,
		and all a.File[i].Name is non-empty.

	 func FS(a *Archive) (fs.FS, error)
		FS returns the file system form of an Archive.
		It returns an error if any of the file names in the archive
		are not valid file system names.
		The archive must not be modified while the FS is in use.
		
		If the file system detects that it has been modified, calls to the
		file system return an ErrModified error.

	 func Parse(data []byte) *Archive
		Parse parses the serialized form of an Archive.
		The returned Archive holds slices of data.

	 func ParseFile(file string) (*Archive, error)
		ParseFile parses the named file as an archive.

	/* 7 unexporteds ... *//* 7 unexporteds: */
	 func dataOf(fsys *filesystem, n *node) ([]byte, error)
		dataOf returns the data associated with the file t.
		May return ErrModified if fsys.ar has been modified.

	 func directory(fsys *filesystem, dir string) (*node, error)
		directory returns the directory node with the path dir and lazily-creates it
		if it does not exist.

	 func findFileMarker(data []byte) (before []byte, name string, after []byte)
		findFileMarker finds the next file marker in data,
		extracts the file name, and returns the data before the marker,
		the file name, and the data after the marker.
		If there is no next marker, findFileMarker returns before = fixNL(data), name = "", after = nil.

	 func fixNL(data []byte) []byte
		If data is empty or ends in \n, fixNL returns data.
		Otherwise fixNL returns a new slice consisting of data with a final \n added.

	 func initFiles(fsys *filesystem) error
		initFiles initializes fsys from fsys.ar.Files. Returns an error if there are any
		invalid file names or collisions between file or directories.

	 func insert(fsys *filesystem, n *node) error
		insert adds node n as an entry to its parent directory within the filesystem.

	 func isMarker(data []byte) (name string, after []byte)
		isMarker checks whether data begins with a file marker line.
		If so, it returns the name from the line and the data after the line.
		Otherwise it returns name == "" with an unspecified after.


Package-Level Variables (total 4, in which 1 is exported)

	  var ErrModified error
		ErrModified indicates that file system returned by FS
		noticed that the underlying archive has been modified
		since the call to FS. Detection of modification is best effort,
		to help diagnose misuse of the API, and is not guaranteed.

	/* 3 unexporteds ... *//* 3 unexporteds: */
	  var marker []byte
	  var markerEnd []byte
	  var newlineMarker []byte
Package-Level Constants (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	const readOnly fs.FileMode = 292 // read only mode
	const readOnlyDir fs.FileMode = 2147483940

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)