replace

README

replace - text replacement utilities

Installation

> go get github.com/go-corelibs/replace@latest

Examples

String, StringInsensitive, StringPreserve

var contents := `First line of text says something.
Text on the second line says more.`

func main() {
    // replace "text" (case-sensitively) with "this"
    modified, count := replace.String("text", "this", contents)
    // count == 1
    // modified == "First line of this says something.\nText on the second line says more."

    // replace "text" (case-insensitively) with "this"
    modified, count := replace.StringInsensitive("text", "this", contents)
    // count == 2
    // modified == "First line of this says something.\nthis on the second line says more."

    // replace "text" (case-preserved) with "this"
    modified, count := replace.StringPreserve("text", "this", contents)
    // count == 2
    // modified == "First line of this says something.\nThis on the second line says more."
}

Vars

func main() {
    expanded := replace.Vars("hello ${name}", map[string]string{
        "name": "strange new worlds",
    })
    // expanded == "hello strange new worlds"
}

Go-CoreLibs

Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.

License

Copyright 2024 The Go-CoreLibs Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package replace provides text replacement utilities

Index

• Variables
• func FindAllIncluded(targets []string, includeHidden, noLimit, binAsText, recurse bool, ...) (found []string)
• func FindAllMatcher(targets []string, includeHidden, noLimit, binAsText, recurse bool, ...) (files, matches []string, err error)
• func FindAllMatchingRegexp(search *regexp.Regexp, targets []string, ...) (files, matches []string, err error)
• func FindAllMatchingRegexpLines(search *regexp.Regexp, targets []string, ...) (files, matches []string, err error)
• func FindAllMatchingString(search string, targets []string, ...) (files, matches []string, err error)
• func FindAllMatchingStringInsensitive(search string, targets []string, ...) (files, matches []string, err error)
• func IsIncluded(include, exclude globs.Globs, input string) (included bool)
• func MakeRegexp(search string, multiLine, dotMatchNl, ignoreCase bool) (rx *regexp.Regexp, err error)
• func ProcessFile(target string, fn func(original string) (modified string, count int)) (original, modified string, count int, delta *diff.Diff, err error)
• func Regex(search *regexp.Regexp, replace, contents string) (modified string, count int)
• func RegexFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func RegexLines(search *regexp.Regexp, replace, contents string) (modified string, count int)
• func RegexLinesFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func RegexPreserve(search *regexp.Regexp, replace, contents string) (modified string, count int)
• func RegexPreserveFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func String(search, replace, contents string) (modified string, count int)
• func StringFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func StringInsensitive(search, replace, contents string) (modified string, count int)
• func StringInsensitiveFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func StringPreserve(search, replace, contents string) (modified string, count int)
• func StringPreserveFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)
• func Vars(input string, replacements map[string]string) (expanded string)
• type FindAllMatcherFn
• type FindAllMatchingFn

Variables

var (
	ErrLargeFile    = errors.New("large file")
	ErrBinaryFile   = errors.New("binary file")
	ErrTooManyFiles = fmt.Errorf("too many files")
)

var (
	MaxFileSize  = int64(math.Round(1024.0 * 1024.0 * 5.0))
	MaxFileCount = 1000000
)

Functions

func FindAllIncluded

func FindAllIncluded(targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs) (found []string)

FindAllIncluded walks the given target paths, looking for unique IsIncluded files

func FindAllMatcher

func FindAllMatcher(targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs, fn FindAllMatchingFn, matcher FindAllMatcherFn) (files, matches []string, err error)

FindAllMatcher uses FindAllIncluded to derive a list of `files` and a list of `matches` (using the `matcher` func), returning ErrTooManyFiles if the total number of files exceeds the MaxFileCount. While performing the find process, calls the given `fn` to report progress and the state of each file processed

func FindAllMatchingRegexp

func FindAllMatchingRegexp(search *regexp.Regexp, targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs, fn FindAllMatchingFn) (files, matches []string, err error)

FindAllMatchingRegexp is a wrapper around FindAllMatcher with a custom matcher func which uses `search.Match` to filter the `matches` list

func FindAllMatchingRegexpLines

func FindAllMatchingRegexpLines(search *regexp.Regexp, targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs, fn FindAllMatchingFn) (files, matches []string, err error)

FindAllMatchingRegexpLines is a wrapper around FindAllMatcher with a custom matcher func which uses `search.Match` on each line of each file to filter the `matches` list

func FindAllMatchingString

func FindAllMatchingString(search string, targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs, fn FindAllMatchingFn) (files, matches []string, err error)

FindAllMatchingString is a wrapper around FindAllMatcher with a custom matcher func which uses strings.Contains to filter the `matches` list

func FindAllMatchingStringInsensitive

func FindAllMatchingStringInsensitive(search string, targets []string, includeHidden, noLimit, binAsText, recurse bool, include, exclude globs.Globs, fn FindAllMatchingFn) (files, matches []string, err error)

FindAllMatchingStringInsensitive is a wrapper around FindAllMatcher with a custom matcher func which uses strings.Contains, in a case-insensitive way, to filter the `matches` list

func IsIncluded

func IsIncluded(include, exclude globs.Globs, input string) (included bool)

IsIncluded returns true if the given `input` string is included or is not explicitly excluded, or if `include` and `exclude` are nil or empty

func MakeRegexp

func MakeRegexp(search string, multiLine, dotMatchNl, ignoreCase bool) (rx *regexp.Regexp, err error)

MakeRegexp constructs a new *regexp.Regexp instance, prefixing the search pattern with `(?msi)` depending on the boolean arguments given

func ProcessFile

func ProcessFile(target string, fn func(original string) (modified string, count int)) (original, modified string, count int, delta *diff.Diff, err error)

ProcessFile is a convenience function which calls os.ReadFile on the target and runs the given `fn` with the string contents and creates a Diff of the changes between the original and the modified output

func Regex

func Regex(search *regexp.Regexp, replace, contents string) (modified string, count int)

Regex counts the number of matches and runs ReplaceAllString on the given contents, if there are no matches, `modified` will be the same as `contents`

func RegexFile

func RegexFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

RegexFile uses Regex to ProcessFile

func RegexLines

func RegexLines(search *regexp.Regexp, replace, contents string) (modified string, count int)

RegexLines is like Regex with the exception that the contents are split into a list of lines and `search` is applied to each line individually

func RegexLinesFile

func RegexLinesFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

RegexLinesFile uses RegexLines to ProcessFile

func RegexPreserve

func RegexPreserve(search *regexp.Regexp, replace, contents string) (modified string, count int)

RegexPreserve is similar to StringPreserve except that it works with regular expressions to perform the search and replacement process.

While StringPreserve can easily detect un-case-detectable inputs, due to the variable nature of regular expressions it is assumed that the developer using RegexPreserve is confident that the `search` and `replace` arguments result in case-detectable string replacements.

func RegexPreserveFile

func RegexPreserveFile(search *regexp.Regexp, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

RegexPreserveFile uses StringPreserve to ProcessFile

func String

func String(search, replace, contents string) (modified string, count int)

String counts the number of matches and runs strings.ReplaceAll on the given contents, if there are no matches, `modified` will be the same as `contents`

func StringFile

func StringFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

StringFile uses String to ProcessFile

func StringInsensitive

func StringInsensitive(search, replace, contents string) (modified string, count int)

StringInsensitive counts the number of case-insensitive matches and replaces each instance with the `replace` value, if there are no matches `modified` will be the same as `contents`

func StringInsensitiveFile

func StringInsensitiveFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

StringInsensitiveFile uses StringInsensitive to ProcessFile

func StringPreserve

func StringPreserve(search, replace, contents string) (modified string, count int)

StringPreserve attempts to preserve the case of per-replacement matches. Not all strings can have their cases easily detected and StringPreserve uses CanPreserve to check if the `search` and `replace` arguments are simple enough for DetectCase to discern the case patterns. If StringPreserve can't preserve, it defaults to returning the results of calling String with the same arguments given to StringPreserve.

To preserve the per-instance cases, each instance has DetectCase run and uses Case.Apply to derive the `replace` value actually used.

See the Case constants for the list of string cases supported.

func StringPreserveFile

func StringPreserveFile(search, replace, target string) (original, modified string, count int, delta *diff.Diff, err error)

StringPreserveFile uses StringPreserve to ProcessFile

func Vars

func Vars(input string, replacements map[string]string) (expanded string)

Vars searches through `input` for variables in the form of `$Name` or `${Name}` and replaces them with the corresponding `replacements` value. Missing keys are replaced with empty strings

Vars follows the POSIX 3.235 Name definition:

a word consisting solely of underscores, digits, and alphabetics from
the portable character set. The first character of a name is not a digit

Types

type FindAllMatcherFn

type FindAllMatcherFn func(data []byte) (matched bool)

FindAllMatcherFn is the function signature for custom matching of content

type FindAllMatchingFn

type FindAllMatchingFn func(file string, matched bool, err error)

FindAllMatchingFn is the function signature for custom tracking of the finding process