textar

README

textar: TEXTual ARchive

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.

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

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

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.

See https://github.com/ypsu/textar/blob/main/example/seq.textar for a longer example.

Index

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

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 {
	// 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.