to

README

Library of Converters in Go 1.18+

• Stringer Interface
• Any->String
• String->Lines
• Func->FuncName

Documentation

Overview

Package to contains a number of converters that take any number of types and return something transformed from them. It also contains a more granular approach to fmt.Stringer.

Index

• func Dedented(in string) string
• func FuncName(i any) string
• func Human(a any) string
• func IndentWrapped(in string, indent, width int) string
• func Indentation(in string) int
• func Lines(in any) []string
• func Prefixed(in, pre string) string
• func String(in any) string
• func UsageGroup(args []string) string
• func Wrapped(buf string, width int) string
• type HumanFriend
• type Stringer

Examples

• FuncName
• Human
• IndentWrapped
• Indentation
• Lines
• Prefixed
• String
• UsageGroup
• Wrapped

Functions

func Dedented

func Dedented(in string) string

Dedented discards any initial lines with nothing but spaces in them and then detects the number of space characters at the beginning of the first line to the first non-space rune and then subsequently removes exactly that many of runes from every following line treating empty lines as if they had only n number of spaces. Note that if any line does not have n number of initial spaces it the initial runes will still be removed. It is, therefore, up to the content creator to ensure that all lines have the same space indentation.

func FuncName

func FuncName(i any) string

FuncName makes a best effort attempt to return the string name of the passed function. Anonymous functions are named "funcN" where N is the order of appearance within the current scope. Note that this function will panic if not passed a function.

Example

package main

import (
	"github.com/rwxrob/fn"
	"github.com/rwxrob/fn/each"
	"github.com/rwxrob/to"
)

func Foo() {}

func main() {

	f1 := func() {}
	f2 := func() {}

	// Foo is defined outside of the ExampleFuncName

	each.Println(fn.Map([]any{f1, f2, Foo, to.Lines}, to.FuncName))

}

Output:
func1
func2
Foo
Lines

func Human

func Human(a any) string

Human returns a human-friendly string version of the item, specifically:

• single-quoted runes
• double-quoted strings
• numbers as numbers
• function names are looked up
• slices joined with "," and wrapped in []

Anything else is rendered as its fmt.Sprintf("%v",it) form.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

type FooStruct struct{}

func (f FooStruct) String() string { return "FOO" }

type HumanFoo struct{}

func (f HumanFoo) Human() string { return "a friendly foo" }

func FooFunc(a any) {}

func main() {
	fmt.Println(to.Human('r'))                    // not number
	fmt.Println(to.Human("string💢good"))          // unescaped
	fmt.Println(to.Human(new(FooStruct)))         // has String()
	fmt.Println(to.Human(new(HumanFoo)))          // has Human()
	fmt.Println(to.Human([]rune{'r', 's', 'm'}))  // commas
	fmt.Println(to.Human([]string{"foo", "bar"})) // also commas
	fmt.Println(to.Human(func() {}))              // func1
	fmt.Println(to.Human(FooFunc))                // FooFunc
}

Output:
'r'
"string💢good"
FOO
a friendly foo
['r','s','m']
["foo","bar"]
func1
FooFunc

func IndentWrapped

func IndentWrapped(in string, indent, width int) string

IndentWrapped adds the specified number of spaces to the beginning of every line ensuring that the wrapping is preserved to the specified width. Carriage returns (if any) are dropped.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

func main() {
	fmt.Println(to.IndentWrapped("some\nthing", 5, 80))
}

Output:
     some
     thing

func Indentation

func Indentation(in string) int

Indentation returns the number of spaces (in bytes) between beginning of the passed string and the first non-space rune.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

func main() {
	fmt.Println(to.Indentation("    some"))
	fmt.Println(to.Indentation("  some"))
	fmt.Println(to.Indentation("some"))
	fmt.Println(to.Indentation(" 💚ome"))
}

Output:
4
2
0
1

func Lines

func Lines(in any) []string

Lines transforms the input into a string and then divides that string up into lines (\r?\n) suitable for functional map operations.

Example

package main

import (
	"github.com/rwxrob/fn/each"
	"github.com/rwxrob/to"
)

func main() {
	buf := `
some

thing 
here

mkay
`
	each.Print(to.Lines(buf))
}

Output:
something heremkay

func Prefixed

func Prefixed(in, pre string) string

Prefixed returns a string where every line is prefixed. Carriage returns (if any) are dropped.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

func main() {
	fmt.Println(to.Prefixed("some\nthing", "P  "))
}

Output:
P  some
P  thing

func String

func String(in any) string

String converts whatever is passed to its fmt.Sprintf("%v") string version (but avoids calling it if possible). Be sure you use things with consistent string representations.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

type stringer struct{}

func (s stringer) String() string { return "stringer" }

func main() {
	stuff := []any{
		"some", []byte{'t', 'h', 'i', 'n', 'g'},
		1, 2.234, stringer{},
	}
	for _, s := range stuff {
		fmt.Printf("%q ", to.String(s))
	}
}

Output:
"some" "thing" "1" "2.234" "stringer"

func UsageGroup

func UsageGroup(args []string) string

UsageGroup joins the slice with bars (|) and wraps with parentheses suitable for listing as a group within most command usage strings. Empty args are ignored and if no args are passed returns empty string. If only one arg, then return just that same arg. Note that no transformation is done to the string itself (such as removing white space).

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

func main() {
	fmt.Println(to.UsageGroup([]string{"", "foo", "", "bar", "with space"}))
	fmt.Printf("%q\n", to.UsageGroup([]string{"", ""}))
	fmt.Println(to.UsageGroup([]string{"one"}))
}

Output:
(foo|bar|with space)
""
one

func Wrapped

func Wrapped(buf string, width int) string

Wrapped expects a string optionally containing line returns (\n) that will be kept as hard wrap line boundaries and returns every other line exceeding the specified width as one or more wrapped lines. All spaces are crunched into a single space. If passed a negative width effectively joins all words in the buffer into a single line with no wrapping.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/to"
)

func main() {
	fmt.Printf("%q\n", to.Wrapped("some thing", 3))
	fmt.Printf("%v\n", to.Wrapped("There I was not knowing what to do about this exceedingly long line and knowing that certain people would shun me for injecting\nreturns wherever I wanted.", 40))
}

Output:
"some\nthing"
There I was not knowing what to do about
this exceedingly long line and knowing
that certain people would shun me for
injecting
returns wherever I wanted.

Types

type HumanFriend

type HumanFriend interface {
	Human() string
}

HumanFriend implementations have a human readable form that is even friendlier than fmt.Stringer.

type Stringer

type Stringer interface {
	String() string
	StringLong() string
}

Stringer interfaces fulfills fmt.Stringer with the additional promise that the output of String method will always be both consistently parsable (say as JSON) and will never span more than a single line. Stringer also requires the StringLong method promising to produce parsable strings that span multiple lines to remain easy to read.