secreplace

README

secreplace

secreplace is a library which aids in the string replacement of "sections". A section is defined as text enclosed by open and close terminators.

For example, take the following string:

Hi, my name is (_NAME_)!

(_ and _) are the open and close terminators, respectively. We'd like to replace (_NAME_) with something else. Let's pick a function and run ReplaceOne:

replacer := func(s string) (string, error) {
    return "COOL-"+s, nil
}

out, changed, err := ReplaceOne("Hi, my name is (_NAME_)!", "(_", "_)", replacer)
// out     == "Hi, my name is COOL-NAME!"
// changed == true
// err     == nil

The ReplaceAll function will repeatedly call ReplaceOne until no more replacements can occur. This allows for nesting, for example:

replacer := func(s string) (string, error) {
    return "COOL"+s, nil
}

out, changed, err := ReplaceAll("Hi, my name is (_(_A_)-(_B_)_)!", "(_", "_)", replacer)
// out     == "Hi, my name is COOL-COOL-A-COOL-B!"
// changed == true
// err     == nil

Any errors returned by the replacement function will be returned by ReplaceOne and ReplaceAll. Any unmatched terminators will be caught and also cause errors to be returned.

Documentation

Overview

Package secreplace aids in replacing sections of text which are surrounded by known beginning and end terminators. Sections can be nested, and secreplace can replace all until no changes can be made.

Index

• Variables
• func Find(s string, open, close string) (start, end int, ok bool, err error)
• func ReplaceAll(s string, open, close string, f func(string) (string, error)) (out string, changed bool, err error)
• func ReplaceOne(s string, open, close string, f func(string) (string, error)) (out string, changed bool, err error)

Examples

• ReplaceAll
• ReplaceOne

Variables

var (
	// ErrNoMatchingOpen is returned when there is no matching open for a close.
	ErrNoMatchingOpen = errors.New("secreplace: no matching open")

	// ErrNoMatchingClose is returned when there is no matching close for an open.
	ErrNoMatchingClose = errors.New("secreplace: no matching close")

	// ErrEmptyOpen is returned when the open terminator is empty.
	ErrEmptyOpen = errors.New("secreplace: empty open")

	// ErrEmptyClose is returned when the close terminator is empty.
	ErrEmptyClose = errors.New("secreplace: empty close")

	// ErrNilFunc is returned when the given replacer function is nil.
	ErrNilFunc = errors.New("secreplace: nil func")
)

Functions

func Find

func Find(s string, open, close string) (start, end int, ok bool, err error)

Find searches for the first, most interior section of input text surrounded by open and close. It returns the range of text containing the section in the form [start, end) including the open/close strings, a boolean that is true when a match is found, and an error.

func ReplaceAll

func ReplaceAll(s string, open, close string, f func(string) (string, error)) (out string, changed bool, err error)

ReplaceAll calls ReplaceOne repeatedly until no more replacements can be made, or an error occurs. On an error, ReplaceAll will return the partially replaced string and properly set changed to be true or false.

Example

package main

import (
	"fmt"

	"github.com/jakebailey/secreplace"
)

func main() {
	const (
		open  = "(_"
		close = "_)"
	)

	replacer := func(s string) (string, error) {
		return s, nil
	}

	out, changed, err := secreplace.ReplaceAll("(_foo (_bar_) (_baz (_qux_)_)_)", open, close, replacer)
	fmt.Println(out)
	fmt.Println(changed)
	fmt.Println(err)
}

Output:

foo bar baz qux
true
<nil>

func ReplaceOne

func ReplaceOne(s string, open, close string, f func(string) (string, error)) (out string, changed bool, err error)

ReplaceOne replaces a single match found by Find. It calls f on the text between the open and close strings, and returns a new string with the whole section replaced. Errors produced by Find and f are propogated. On an error, ReplaceOne will return the original string.

Example

package main

import (
	"fmt"

	"github.com/jakebailey/secreplace"
)

func main() {
	const (
		open  = "(_"
		close = "_)"
	)

	replacer := func(s string) (string, error) {
		return s, nil
	}

	out, changed, err := secreplace.ReplaceOne("Hello, (_NAME_)!", open, close, replacer)
	fmt.Println(out)
	fmt.Println(changed)
	fmt.Println(err)
}

Output:

Hello, NAME!
true
<nil>