gong

README

gong

A tiny Go library of generally useful things.

Docs: https://pkg.go.dev/github.com/mark-summerfield/gong

License

Apache-2.0

---

Documentation

Index

• Constants
• Variables
• func AbsPath(filename string) string
• func Bold(s string) string
• func Centered(s string, pad rune, width int) string
• func CheckError(message string, err error)
• func Commas(i int) string
• func ElideMiddle(s string, width int) string
• func FileExists(path string) bool
• func GetConfigFile(domain, appname, ext string) (string, bool)
• func GetIniFile(domain, appname string) (string, bool)
• func GetIniFilename(appname string) (string, bool)
• func IsRealClose(a, b float64) bool
• func IsRealZero(x float64) bool
• func IsTTY() bool
• func Italic(s string) string
• func LessFold(a, b string) bool
• func LongestCommonPath(items []string) string
• func LongestCommonPrefix(items []string) string
• func PathExists(path string) bool
• func Relativized(dir, filename string) (string, bool)
• func SortedMapKeys[K cmp.Ordered, V any](m map[K]V) []K
• func StrToInt(s string, default_ int) int
• func StringForSlice[T any](x []T) string
• func TextWrap(text string, width int) []string
• func TextWrapIndent(text string, width int, indent string) []string
• func TextWrapX(text string, width int, firstIndent, indent string) []string
• func Underline(s string) string
• func Wrapped(text string, width int) string
• func WrappedIndent(text string, width int, indent string) string
• func WrappedX(text string, width int, firstIndent, indent string) string
• type Pair
  • func NewPair[T, U any](a T, b U) Pair[T, U]
  • func (me Pair[T, U]) Both() (T, U)

Examples

• Centered
• ElideMiddle

Constants

const ModeUserRW = 0o600

Variables

var Version string // This library's version

Functions

func AbsPath

func AbsPath(filename string) string

AbsPath returns the filename with its path absolute, or cleaned on error. See also Relativized.

func Bold

func Bold(s string) string

Bold returns the given string contained within terminal escape codes to make it bold on linux and windows (providing os.Stdout is a TTY).

func Centered

func Centered(s string, pad rune, width int) string

Centered returns s centered between runs of the given pad to make it width long, or returns s as-is if it is >= width runes long.

Example

package main

import (
	"fmt"
	"github.com/mark-summerfield/gong"
)

func main() {
	s := gong.Centered("The Title", ' ', 15)
	fmt.Printf("%q\n", s)
	s = gong.Centered(" Heading ", '*', 15)
	fmt.Printf("%q\n", s)
	s = gong.Centered(" Heading ", '=', 16)
	fmt.Printf("%q\n", s)
	s = gong.Centered(" Heading ", '-', 17)
	fmt.Printf("%q\n", s)
	s = gong.Centered("Too wide to center", '#', 12)
	fmt.Printf("%q\n", s)
}

Output:

"   The Title   "
"*** Heading ***"
"=== Heading ===="
"---- Heading ----"
"Too wide to center"

func CheckError

func CheckError(message string, err error)

If err != nil calls log.Fatal with the message

func Commas

func Commas(i int) string

Commas returns a string version of the given int with commas inserted as thousands separators.

func ElideMiddle

func ElideMiddle(s string, width int) string

ElideMiddle returns s at most width runes long. If s is longer than width, splits it in the middle, inserts an ellipsis, and removes runes so that it fits width.

Example

package main

import (
	"fmt"
	"github.com/mark-summerfield/gong"
)

func main() {
	s := gong.ElideMiddle("This is short enough", 24)
	fmt.Printf("%q\n", s)
	t := "This is now far too long"
	for i := 14; i < 20; i++ {
		s = gong.ElideMiddle(t, i)
		fmt.Printf("%d: %q\n", i, s)
	}
}

Output:

"This is short enough"
14: "This is…o long"
15: "This is …o long"
16: "This is …oo long"
17: "This is n…oo long"
18: "This is n…too long"
19: "This is no…too long"

func FileExists

func FileExists(path string) bool

FileExists returns true if the filename exists and is a file. See also PathExists.

func GetConfigFile

func GetConfigFile(domain, appname, ext string) (string, bool)

GetConfigFile given a domain name, say, "domain.com", and an application name, say, "myapp", and an extention, say, ".json", returns where the corresponding config file is located and true, or where the config file should be saved (i.e., if it doesn't exist) and false.

When saving (at least for the first time) you may need to create the domain folder:

dir := filepath.Dir(configFilename)
if dir != "." {
	_ = os.MkdirAll(dir, fs.ModePerm)
}
// now save to configFilename

func GetIniFile

func GetIniFile(domain, appname string) (string, bool)

GetIniFile given a domain name, say, "domain.com", and an application name, say, "myapp", returns where the corresponding .ini file is located and true, or where the .ini should be saved (i.e., if it doesn't exist) and false.

When saving (at least for the first time) you may need to create the domain folder:

dir := filepath.Dir(iniFilename)
if dir != "." {
	_ = os.MkdirAll(dir, fs.ModePerm)
}
// now save to iniFilename

func GetIniFilename

func GetIniFilename(appname string) (string, bool)

GetIniFilename

Deprecated: use GetIniFile or GetConfigFile instead.

func IsRealClose

func IsRealClose(a, b float64) bool

IsRealClose returns true if a and b are very close to each other. Should be adequate for test comparisons. See also IsRealZero.

func IsRealZero

func IsRealZero(x float64) bool

IsRealZero returns true if x is close to 0. Should be adequate for test comparisons. See also IsRealClose.

func IsTTY

func IsTTY() bool

IsTTY returns true if stdout is a tty; otherwise false.

func Italic

func Italic(s string) string

Italic returns the given string contained within terminal escape codes to make it italic on linux (and in theory on windows, but I've never seen it work on windows), (providing os.Stdout is a TTY).

func LessFold

func LessFold(a, b string) bool

LessFold returns true if string a is case-insensitively less than string b; otherwise returns false. This function can also be used to sort a slice of strings, e.g., `slices.SortFunc(mystrings, gong.LessFold)`.

func LongestCommonPath

func LongestCommonPath(items []string) string

LongestCommonPath returns the longest common path, i.e., component, /-separated (which could be "" if there isn't one).

func LongestCommonPrefix

func LongestCommonPrefix(items []string) string

LongestCommonPrefix returns the longest common prefix (which could be "" if there isn't one).

func PathExists

func PathExists(path string) bool

PathExists returns true if the path/filename exists. See also FileExists.

func Relativized

func Relativized(dir, filename string) (string, bool)

Relativized returns filename with a path relative to dir, (i.e., as if dir were root but without the leading /) and true; or filename with an absolute path and false if filename isn't in the same path tree as dir. See also AbsPath.

func SortedMapKeys

func SortedMapKeys[K cmp.Ordered, V any](m map[K]V) []K

SortedMapKeys returns a sorted list of the given map's keys.

func StrToInt

func StrToInt(s string, default_ int) int

StrToInt returns s converted to an int, or if s isn't a valid int returns default_

func StringForSlice

func StringForSlice[T any](x []T) string

StringForSlice returns a string of space-separated items. Mostly useful for tests.

func TextWrap

func TextWrap(text string, width int) []string

TextWrap splits the given text into \n\n-separated paras (or treats it as one para) and returns a slices of strings each one at most width runes long (unless any word is greater than width). See also TextWrapIndent and TextWrapX.

func TextWrapIndent

func TextWrapIndent(text string, width int, indent string) []string

TextWrapIndent splits the given text into \n\n-separated paras (or treats it as one para) and returns a slices of strings each one at most width runes long (unless any word is greater than width). For each para, every returned string is preceded by the indent (which may be empty). See also TextWrap and TextWrapX.

func TextWrapX

func TextWrapX(text string, width int, firstIndent,
	indent string) []string

TextWrapX splits the given text into slices of strings each one at most width runes long (unless any word is greater than width). For each para, the first returned string is preceded by the firstIndent (which may be empty), and all subsequent lines in the para are preceded by inded (which may be empty). In the given text, \n\n is output as \n (line-break), and \n is treated as whitespace. See also TextWrap and TextWrapIndent.

func Underline

func Underline(s string) string

Underline returns the given string contained within terminal escape codes to make it underlined on linux and windows (providing os.Stdout is a TTY).

func Wrapped

func Wrapped(text string, width int) string

Wrapped returns the given text as a single string of \n-separated paras with each para at most width characters wide.

This is a convenience wrapper for TextWrap. See also WrappedX and WrappedIndent.

func WrappedIndent

func WrappedIndent(text string, width int, indent string) string

WrappedIndent returns the given text as a single string of \n-separated paras with each para indented with the given indent and at most width characters wide.

This is a convenience wrapper for TextWrapIndent. See also WrappedX and Wrapped.

func WrappedX

func WrappedX(text string, width int, firstIndent,
	indent string) string

WrappedX returns the given text as a single string of \n-separated paras with each para's first line indented with the firstIndent and the remaining lines indented with the given indent and at most width characters wide.

This is a convenience wrapper for TextWrapX. See also WrappedIndent and Wrapped.

Types

type Pair

type Pair[T, U any] struct {
	First  T
	Second U
}

A pair of any two values.

func NewPair

func NewPair[T, U any](a T, b U) Pair[T, U]

NewPair usually supports p := NewPair(x, y) rather than having to specify types with p := Pair[T, U]{x, y}.

func (Pair[T, U]) Both

func (me Pair[T, U]) Both() (T, U)

Both returns both of the pair's values.