encoding.txtar #

Description

The purpose of the encoding.txtar module, is best described in the original Go source:

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 spec

See the spec in the txtar Go package source code, linked above:

• 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.

Example

import os
import encoding.txtar

a := txtar.parse('comment
line1
line2
-- file.txt --
some content that will go into file.txt
some more content
-- a/b/c/file.v --
import os
dump(os.args)
-- bcd/def/another.v --
dump(2+2)
')
assert a.files.len == 2
assert a.files[0].path == 'file.txt'
assert a.files[2].path == 'bcd/def/another.v'

tfolder := os.join_path(os.temp_dir(), 'xyz')
txtar.unpack(a, tfolder)!
assert os.exists(os.join_path(tfolder, 'bcd/def/another.v'))
b := txtar.pack(tfolder, '')!
assert b.files.len == a.files.len
os.rmdir_all(tfolder)!

fn pack(path string, comment string) !Archive

pack will create a txtar archive, given a path. When the path is a folder, it will walk over all files in that base folder, read their contents and create a File entry for each. When the path is a file, it will create an Archive, that contains just a single File entry, for that single file.

fn parse(content string) Archive

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

fn parse_file(file_path string) !Archive

parse_file parses the given file_path as an archive. It will return an error, only if the file_path is not readable. See the README.md, or the test txtar_test.v, for a description of the format.

fn unpack(a &Archive, path string) !

unpack will extract all files in the archive a, into the base folder path. Note that all file paths will be appended to the base folder path, i.e. if you have a File with path field == 'abc/def/x.v', and base folder path == '/tmp', then the final path for that File, will be '/tmp/abc/def/x.v' Note that unpack will try to create any of the intermediate folders like /tmp, /tmp/abc, /tmp/abc/def, if they do not already exist.

struct Archive {
pub mut:
	comment string // the start of the archive; contains potentially multiple lines, before the files
	files   []File // a series of files
}

Archive is a collection of files

fn (a &Archive) str() string

str returns a string representation of the a Archive. It is suitable for storing in a text file. It is also in the same format, that txtar.parse/1 expects.

fn (a &Archive) unpack_to(path string) !

unpack_to extracts the content of the archive a, into the folder path.

struct File {
pub mut:
	path    string // 'abc/def.v' from the `-- abc/def.v --` header
	content string // everything after that, till the next `-- name --` line.
}

File is a single file in an Archive. Each starting with a -- FILENAME -- line.