places

README

places

fast and primitive templating for go

If you need to simply replace placeholders in a template without escaping or logic, places might be for you.

Performance

Runing benchmarks in the benchmark directory, I get the following results (go1.8, linux/amd64):

replacing 2 placeholders that occur 2500x in the template

BenchmarkNaive    1000      1263008 ns/op      4 allocs/op   4x  (strings.Replace)   
BenchmarkNaive2   2000      1042809 ns/op     13 allocs/op   3x  (strings.Replacer)  
BenchmarkReg       100     15384938 ns/op     25 allocs/op  48x  (regexp.ReplaceAllStringFunc)  
BenchmarkByte     2000      1053584 ns/op      2 allocs/op   3x  (bytes.Replace)  
BenchmarkTemplate  500      3608738 ns/op  10001 allocs/op  11x  (template.Execute)  
BenchmarkPlaces   5000       315520 ns/op      0 allocs/op   1x  (places.ReplaceString)

replacing 5000 placeholders that occur 1x in the template

BenchmarkNaiveM        1    1954624037 ns/op     10001 allocs/op  3481.58x  (strings.Replace)
BenchmarkNaive2M     500       3467816 ns/op     11007 allocs/op     6.18x  (strings.Replacer)
BenchmarkRegM        100      17515006 ns/op        26 allocs/op    31.20x  (regexp.ReplaceAllStringFunc)
BenchmarkByteM      2000        823151 ns/op         2 allocs/op     1.47x  (bytes.Replace)
BenchmarkTemplateM   500       3736012 ns/op     10001 allocs/op     6.65x  (template.Execute)
BenchmarkPlacesM    2000        561419 ns/op         0 allocs/op     1.00x  (places.ReplaceString)

replacing 2 placeholders that occur 1x in the template, parsing template each time (you should not do this until you need it)

BenchmarkOnceNaive    1000   1242754 ns/op      4 allocs/op     1.16x  (strings.Replace)  
BenchmarkOnceNaive2   2000   1069273 ns/op     13 allocs/op     1.00x  (strings.Replacer) 
BenchmarkOnceReg       100  15208299 ns/op     25 allocs/op    14.22x  (regexp.ReplaceAllStringFunc)  
BenchmarkOnceByte     1000   1208239 ns/op      4 allocs/op     1.13x  (bytes.Replace)  
BenchmarkOnceTemplate   50  31201995 ns/op  55054 allocs/op    29.18x  (template.Execute)  
BenchmarkOncePlaces   2000   1112133 ns/op     26 allocs/op     1.04x  (places.ReplaceString)  

Usage

package main

import (
    "bytes"
    "fmt"
    "net/http"
    "gitlab.com/metakeule/places"
)

// parse the template once and reuse it to speed up replacement
var cached = places.NewString("[@name@]: [@animal@]")

// you can also create the replacements ad hoc in the handler
// also map[string]string, map[string]io.ReadSeeker etc. possible
var replacements = map[string]string{
    "animal": "Duck",
    "name": "Donald",
}

func handle (wr http.ResponseWriter rq *http.Request) {
    // no error checking on write (for performance)
    // if you need error checking wrap the io.Writer
    cached.Replace(wr, places.StringMap(replacements))
}

func main() {
    http.ListenAndServe("localhost:8080", http.HandlerFunc(handle))
}

Documentation

see https://pkg.go.dev/gitlab.com/metakeule/places

Status

The package is stable and ready for consumption. API might change.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

see LICENSE file.

Documentation

Index

• Variables
• func Echo(s string) string
• func Find(template []byte, opts ...Option) (places []int)
• func FindAndReplace(template []byte, wr io.Writer, repl Replacer, opts ...Option)
• func FindAndReplaceString(template string, wr io.Writer, repl Replacer, opts ...Option)
• func Positions(template []byte, places []int) (positions []string)
• func Replace(template []byte, wr io.Writer, places []int, repl Replacer)
• func ReplaceBytes(template []byte, wr io.Writer, places []int, replacements map[string][]byte)
• type Buffer
• type BytesMap
  • func (me BytesMap) Replace(wr io.Writer, key string)
• type Cache
  • func New(t []byte, opts ...Option) *Cache
  • func NewString(t string, opts ...Option) *Cache
  • func (t *Cache) Positions() []string
  • func (t *Cache) Replace(wr io.Writer, replacer Replacer)
• type Empty
  • func (me Empty) Replace(wr io.Writer, key string)
• type Option
  • func WithDelimiter(start, end string) Option
• type ReadSeekerMap
  • func (me ReadSeekerMap) Replace(wr io.Writer, key string)
• type ReplaceFunc
  • func (me ReplaceFunc) Replace(wr io.Writer, key string)
• type ReplaceStringFunc
  • func (me ReplaceStringFunc) Replace(wr io.Writer, key string)
• type Replacer
  • func FromReadSeeker(rs io.ReadSeeker, errHandler func(error)) Replacer
  • func FromReader(rd io.Reader, errHandler func(error)) Replacer
  • func FromWriterTo(wrt io.WriterTo, errHandler func(error)) Replacer
• type ReplacerMap
  • func (me ReplacerMap) Replace(wr io.Writer, key string)
• type Self
  • func (s Self) Replace(wr io.Writer, position string)
• type String
  • func (me String) Replace(wr io.Writer, position string)
• type StringMap
  • func (me StringMap) Replace(wr io.Writer, key string)
• type WriterToMap
  • func (me WriterToMap) Replace(wr io.Writer, key string)

Variables

var (
	// DefaultStartDel is the default start delimiter (prefix of the position)
	DefaultStartDel = []byte("[@")

	// DefaultEndDel is the default end delimiter (postfix of the position)
	DefaultEndDel = []byte("@]")
)

Functions

func Echo

func Echo(s string) string

func Find

func Find(template []byte, opts ...Option) (places []int)

Find looks for positions written in the style "[@positionname@]" inside the given template. It returns a slice containing the positions of the positions that is meant to be passed to Replace or ReplaceString.

func FindAndReplace

func FindAndReplace(template []byte, wr io.Writer, repl Replacer, opts ...Option)

FindAndReplace finds positions and replaces them in one go.

func FindAndReplaceString

func FindAndReplaceString(template string, wr io.Writer, repl Replacer, opts ...Option)

FindAndReplaceString finds positions and replaces them in one go.

func Positions

func Positions(template []byte, places []int) (positions []string)

Positions returns all the found Positions in the given template

func Replace

func Replace(template []byte, wr io.Writer, places []int, repl Replacer)

Replace replaces the positions at the given places inside the template by using the given Replacer. The given template must be the unchanged byte array that was passed to Find in order to get the places. For strings as replacements see the optimized ReplaceString function for bytes use ReplaceBytes.

func ReplaceBytes

func ReplaceBytes(template []byte, wr io.Writer, places []int, replacements map[string][]byte)

ReplaceBytes is an optimized version of Replace for a bytes map

Types

type Buffer

type Buffer interface {
	io.Writer
	WriteString(string) (int, error)
}

The Buffer interface is fullfilled by *bytes.Buffer. However since for performance reasons the errors from writing to the buffer are always ignored, you will need to write a buffer wrapper to capture them.

type BytesMap

type BytesMap map[string][]byte

BytesMap is a string map that implements Replacer

func (BytesMap) Replace

func (me BytesMap) Replace(wr io.Writer, key string)

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is caching the template and the positions of the positions

func New

func New(t []byte, opts ...Option) *Cache

New parses the given bytes and returns a Cache to remember where the positions are inside the template

func NewString

func NewString(t string, opts ...Option) *Cache

NewString parses the given string and returns a Cache to remember where the positions are inside the template

func (*Cache) Positions

func (t *Cache) Positions() []string

positions returns the positions by running through the template

func (*Cache) Replace

func (t *Cache) Replace(wr io.Writer, replacer Replacer)

Replace replaces the positions at the given places by using the given Replacer.

type Empty

type Empty struct{}

Empty is a Replacer that always returns an empty string

func (Empty) Replace

func (me Empty) Replace(wr io.Writer, key string)

type Option

type Option func(c *options)

Option is a parsing option

func WithDelimiter

func WithDelimiter(start, end string) Option

WithDelimiter sets custom delimiters of the positions The starting and delimiters must be 2 bytes long and must not be equal. We panic, if these rules are not fullfilled.

type ReadSeekerMap

type ReadSeekerMap map[string]io.ReadSeeker

ReadSeekerMap is a readseeker map that implements Replacer

func (ReadSeekerMap) Replace

func (me ReadSeekerMap) Replace(wr io.Writer, key string)

type ReplaceFunc

type ReplaceFunc func(wr io.Writer, key string)

ReplaceFunc is a func implementing Replacer

func (ReplaceFunc) Replace

func (me ReplaceFunc) Replace(wr io.Writer, key string)

type ReplaceStringFunc

type ReplaceStringFunc func(string) string

ReplaceStringFunc is a func implementing Replacer

func (ReplaceStringFunc) Replace

func (me ReplaceStringFunc) Replace(wr io.Writer, key string)

type Replacer

type Replacer interface {
	Replace(wr io.Writer, position string)
}

Replacer replaces the position with its value, by writing the value to the given io.Writer This is a core component that allows different sources for the replacement. Some implementations can be found in the replacer.go file. If you want to track errors around io then implement your own Replacer to track them.

func FromReadSeeker

func FromReadSeeker(rs io.ReadSeeker, errHandler func(error)) Replacer

FromReadSeeker returns a Replacer that is getting the data from the ReadSeeker

func FromReader

func FromReader(rd io.Reader, errHandler func(error)) Replacer

FromReader returns a Replacer that is getting the data from the Reader

func FromWriterTo

func FromWriterTo(wrt io.WriterTo, errHandler func(error)) Replacer

FromWriterTo returns a Replacer that is getting the data from the Writerto

type ReplacerMap

type ReplacerMap map[string]Replacer

ReplacerMap is a string map that implements Replacer

func (ReplacerMap) Replace

func (me ReplacerMap) Replace(wr io.Writer, key string)

type Self

type Self string

func (Self) Replace

func (s Self) Replace(wr io.Writer, position string)

Self is a Replacer that always returns the position prefixed by the value of Self

type String

type String string

String is a Relacer that always returns the string itself

func (String) Replace

func (me String) Replace(wr io.Writer, position string)

type StringMap

type StringMap map[string]string

StringMap is a string map that implements Replacer

func (StringMap) Replace

func (me StringMap) Replace(wr io.Writer, key string)

type WriterToMap

type WriterToMap map[string]io.WriterTo

WriterToMap is a writer map that implements Replacer

func (WriterToMap) Replace

func (me WriterToMap) Replace(wr io.Writer, key string)