txtar

Documentation

Overview

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.

Index

• Variables
• func FS(a *Archive) (fs.FS, error)
• func Format(a *Archive) []byte
• type Archive
  • func Parse(data []byte) *Archive
  • func ParseFile(file string) (*Archive, error)
• type File

Variables

var ErrModified error = errors.New("txtar.Archive has been modified during txtar.FS")

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.

Functions

func FS

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 Format

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.

Types

type Archive

type Archive struct {
	Comment []byte
	Files   []File
}

An Archive is a collection of files.

func Parse

func Parse(data []byte) *Archive

Parse parses the serialized form of an Archive. The returned Archive holds slices of data.

func ParseFile

func ParseFile(file string) (*Archive, error)

ParseFile parses the named file as an archive.

type File

type File struct {
	Name string // name of file ("foo/bar.txt")
	Data []byte // text content of file
}

A File is a single file in an archive.