textar

README

textar: TEXTual ARchive

Package textar encodes a file list (key-value slice) into a human editable text file and vice versa. See https://pkg.go.dev/github.com/ypsu/textar for the documentation.

Note: this project uses https://ypsu.github.io/featver as its versioning scheme. The project will enter the more stable v1 version only when it has users already.

Comes with a command line tool as well, check out https://pkg.go.dev/github.com/ypsu/textar/bin/textar.

Documentation

Overview

Package textar encodes a file list (key-value slice) into a human editable text file and vice versa. This is inspired by https://pkg.go.dev/golang.org/x/tools/txtar but this format can encode any content without issues. Each file in a textar is encoded via "[SEP] [NAME]\n[CONTENT]\n". The first SEP in the file determines the SEP for the whole file. SEP cannot contain space or newline. Example:

== file1
file1 content
== file2
file2 content
== # some comment
some comment body.
== file3
file3 content.

The separator here is == because that's how the archive starts. The Format function automatically picks a separator that is unique and won't conflict with existing file values. Use Parse to parse it back into a slice of File entries.

By default textar skips parsing entries starting with #. They can be used as comments. This behavior can be altered with ParseOptions.

See https://github.com/ypsu/textar/blob/main/example/seq.textar for a longer example. See the testdata directory of https://github.com/ypsu/pkgtrim for a more realistic example.

Index

• func FS(archive []File) fstest.MapFS
• func Format(archive []File) []byte
• func Indent(data []byte, indent string) []byte
• func Unindent(data []byte, indent string) []byte
• type File
  • func Parse(data []byte) []File
• type FormatOptions
  • func (fo FormatOptions) Format(archive []File) []byte
• type ParseOptions
  • func (po ParseOptions) Parse(data []byte) []File

Functions

func FS

func FS(archive []File) fstest.MapFS

FS returns an object implementing io/fs.FS built from the contents of an archive. This is a helper function for tests.

func Format

func Format(archive []File) []byte

Format an archive into a byte stream with the default settings.

func Indent

func Indent(data []byte, indent string) []byte

Indent is a convenience function to indent data. Note that textar doesn't need this but indenting makes a textar easier to read if it contains embedded textars.

func Unindent

func Unindent(data []byte, indent string) []byte

Unindent is a convenience function to undo Indent.

Types

type File

type File struct {
	Name string
	Data []byte
}

File represents a single entry in the text archive.

func Parse

func Parse(data []byte) []File

Parse data with the default settings. Note by default textar skips entries that start with the # comment marker. Use ParseOptions to alter this.

type FormatOptions

type FormatOptions struct {
	// The byte which gets repeated and then used to separate the Files.
	// Defaults to '=' if unspecified or set to an invalid value.
	Separator byte

	// Format appends the resulting data to this buffer.
	// Use this to reduce memory allocations.
	// Don't use it for concatenating textars, it won't work.
	Buffer []byte
}

FormatOptions allows customizing the formatting.

func (FormatOptions) Format

func (fo FormatOptions) Format(archive []File) []byte

Format an archive into a byte stream with custom settings.

type ParseOptions

type ParseOptions struct {
	// If true, textar won't skip entries that have a name starting with # or have an empty name.
	ParseComments bool
	// Parse appends the resulting Files to this buffer.
	Buffer []File
}

ParseOptions allows customizing the parsing.

func (ParseOptions) Parse

func (po ParseOptions) Parse(data []byte) []File

Parse data with custom settings.