twist

README

🌀 twist

A reversible template package for Go — render structured text and parse it back into data.

Overview

Twist is a Go library for creating reversible string templates. It allows you to both generate strings from templates and parse strings back into structured data.

Features

• Simple template syntax using {{field}} delimiters (with configuration options for custom delimeters)
• Generate strings from templates using struct or map data
• Parse strings back into struct or map data
• Handle ambiguous matches by returning all possible interpretations
• Type-safe parsing into Go structs

Installation

Examples

Documentation

Index

• Variables
• func MustNew(s string, opts ...twistOption) twist
• func New(s string, opts ...twistOption) (twist, error)
• func WithDelimiters(delimiters [2]string) twistOption
• func WithUnique() executeOption
• type StrPart
  • func MustNewStrPart(s string, start, end int) StrPart
  • func NewStrPart(s string, start, end int) (StrPart, error)
  • func (p StrPart) Matches(other StrPart) bool
  • func (p StrPart) String() string
  • func (p StrPart) TrimSpace() StrPart

Variables

var (
	// ErrTwist is the base error for all twist errors.
	ErrTwist = errors.New("twist error")

	// ErrInvalidConfig is returned when the TwistConfig is invalid.
	ErrInvalidConfig = fmt.Errorf("%w: invalid config", ErrTwist)

	// ErrInvalidTemplate is returned when creating a new twist with an invalid template.
	ErrInvalidTemplate = fmt.Errorf("%w: invalid template", ErrTwist)

	// ErrInvalidData is returned when attemping to execute or parse a template with invalid data.
	ErrInvalidData = fmt.Errorf("%w: invalid data", ErrTwist)

	// ErrTemplateMismatch is returned when parsing a string which does not match the original template.
	ErrTemplateMismatch = fmt.Errorf("%w: template mismatch", ErrTwist)

	// ErrAmbiguousTemplate is returned when attempting to get a unique data set from a template
	// which has multiple possible data sets.
	ErrAmbiguousTemplate = fmt.Errorf("%w: template is ambiguous", ErrTwist)
)

var (
	ErrInvalidStrPart = errors.New("Invalid StrPart")
)

Functions

func MustNew

func MustNew(s string, opts ...twistOption) twist

MustNew is a convenience function that wraps `New` and panics if the template is invalid.

func New

func New(s string, opts ...twistOption) (twist, error)

New creates a 'twist' and errors if the template is invald.

Twists are reversible templates that can be used to create basic string template using {{ and }} as delimeters by default.

func WithDelimiters

func WithDelimiters(delimiters [2]string) twistOption

When creating a 'twist' with `New` this function creates a twist with a custom set of delimeters, by default '{{' and '}}' are used as delimeters.

func WithUnique

func WithUnique() executeOption

When `Executing` a template this option causes an error to be returned if the resulting string cannot be used to recreate the original data passed into the template.

Types

type StrPart

type StrPart struct {
	Start int
	End   int
	// contains filtered or unexported fields
}

A reference to a subset of a string

func MustNewStrPart

func MustNewStrPart(s string, start, end int) StrPart

Construct a new StrPart. Panics if arguments are invalid.

func NewStrPart

func NewStrPart(s string, start, end int) (StrPart, error)

Construct a new StrPart

func (StrPart) Matches

func (p StrPart) Matches(other StrPart) bool

Compare two StrParts to see if their strings are equal

func (StrPart) String

func (p StrPart) String() string

Return the substring that StrPart refers to

func (StrPart) TrimSpace

func (p StrPart) TrimSpace() StrPart

Construct a new StrPart that has it's whitespace trimmed