v1.12.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Dec 13, 2023 License: BSD-3-Clause Imports: 9 Imported by: 5



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.



This section is empty.


This section is empty.


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.

func NeedsQuote added in v1.3.0

func NeedsQuote(data []byte) bool

NeedsQuote reports whether the given data needs to be quoted before it's included as a txtar file.

func Quote added in v1.3.0

func Quote(data []byte) ([]byte, error)

Quote quotes the data so that it can be safely stored in a txtar file. This copes with files that contain lines that look like txtar separators.

The original data can be recovered with Unquote. It returns an error if the data cannot be quoted (for example because it has no final newline or it holds unprintable characters)

func Unquote added in v1.3.0

func Unquote(data []byte) ([]byte, error)

Unquote unquotes data as quoted by Quote.

func Write

func Write(a *Archive, dir string) error

Write writes each File in an Archive to the given directory, returning any errors encountered. An error is also returned in the event a file would be written outside of dir.


type Archive

type Archive = txtar.Archive

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.

TODO use golang.org/x/tools/txtar.Parse when https://github.com/golang/go/issues/59264 is fixed.

func ParseFile

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

ParseFile parses the named file as an archive.

type File

type File = txtar.File

A File is a single file in an archive.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL