transform

Documentation

Overview

Package transform defines some useful transformations on TOML documents.

Index

• func FindTable(doc *tomledit.Document, name ...string) *tomledit.Entry
• func InsertMapping(tab *tomledit.Section, kv *parser.KeyValue, replace bool) bool
• func SortKeyValuesByName(items []parser.Item)
• func SortSectionsByName(ss []*tomledit.Section)
• func WithLogWriter(ctx context.Context, w io.Writer) context.Context
• type Applier
• type Func
  • func EnsureKey(table parser.Key, kv *parser.KeyValue) Func
  • func MoveKey(oldKey, rootKey, newKey parser.Key) Func
  • func Remove(key parser.Key, more ...parser.Key) Func
  • func Rename(oldKey, newKey parser.Key) Func
  • func SnakeToKebab() Func
  • func (f Func) Apply(ctx context.Context, doc *tomledit.Document) error
• type Plan
  • func (p Plan) Apply(ctx context.Context, doc *tomledit.Document) error
• type Step
  • func (s Step) Apply(ctx context.Context, doc *tomledit.Document) error

Functions

func FindTable

func FindTable(doc *tomledit.Document, name ...string) *tomledit.Entry

FindTable returns the entry the first table with the given name in doc, or nil if no such table exists. An empty name denotes the global table.

func InsertMapping

func InsertMapping(tab *tomledit.Section, kv *parser.KeyValue, replace bool) bool

InsertMapping inserts the specified key-value mapping into the given table. If replace is true, the new value replaces an existing one with that name, otherwise the original value is retained. The function reports true if kv was inserted or replaced an existing value, otherwise false.

func SortKeyValuesByName

func SortKeyValuesByName(items []parser.Item)

SortKeyValuesByName performs a stable in-place sort of items, so that any key-value entries are ordered by their names, but other items such as comments are left in their original positions.

func SortSectionsByName

func SortSectionsByName(ss []*tomledit.Section)

SortSectionsByName performs a stable in-place sort of the given slice of sections by their name.

func WithLogWriter

func WithLogWriter(ctx context.Context, w io.Writer) context.Context

WithLogWriter attaches w to ctx as a logging target.

Types

type Applier

type Applier interface {
	Apply(context.Context, *tomledit.Document) error
}

An Applier applies one or more transformations to a document. The Func, Step, and Plan types implement this interface.

type Func

type Func func(context.Context, *tomledit.Document) error

A Func implements the applier interface with a function.

func EnsureKey

func EnsureKey(table parser.Key, kv *parser.KeyValue) Func

EnsureKey ensures the given table contains a mapping for the given key, adding kv if it it is not already present. It reports an error if the table does not exist.

func MoveKey

func MoveKey(oldKey, rootKey, newKey parser.Key) Func

MoveKey moves the mapping at oldKey from its current location to be a child of rootKey with the new name newKey. It reports whether the key was moved.

func Remove

func Remove(key parser.Key, more ...parser.Key) Func

Remove removes the section or mapping at the given keys, and reports whether the removals were successful. All the removals are attempted before returning.

func Rename

func Rename(oldKey, newKey parser.Key) Func

Rename renames the section or mapping at oldKey to newKey, and reports whether the rename was successful. The mapping is not moved within the document, only its label is changed.

func SnakeToKebab

func SnakeToKebab() Func

SnakeToKebab transforms all the key names in doc from snake_case to kebab-case. This transformation cannot fail.

func (Func) Apply

func (f Func) Apply(ctx context.Context, doc *tomledit.Document) error

Apply applies f to doc, satisfying the Applier interface.

type Plan

type Plan []Step

A Plan is a sequence of transformations to be applied in order.

func (Plan) Apply

func (p Plan) Apply(ctx context.Context, doc *tomledit.Document) error

Apply applies each step of p to the document in order, and reports the error from the first step that fails, or nil. An empty Plan always succeeds.

type Step

type Step struct {
	Desc    string  // human-readable description (for logging)
	T       Applier // the transformation itself
	ErrorOK bool    // if true, ignore errors from evaluating T
}

A Step is a single transformation in a plan.

func (Step) Apply

func (s Step) Apply(ctx context.Context, doc *tomledit.Document) error

Apply applies the transformation step and reports its error. If ErrorOK is true, a non-nil error from the transformation is ignored.