twrap

package
v1.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2023 License: MIT Imports: 10 Imported by: 20

Documentation

Overview

Package twrap provides supporting functions for printing wrapped text. It allows you to print indented text that will fit within a supplied maximum line length. It is also possible to specify a minimum amount of text to print on each line in case the indent is too great.

You should first of all create a TWConf (use the NewTWConf function - it will report invalid parameters). Then you can call the various Wrap...(...) methods on it to print the text.

Index

Examples

Constants

View Source 
const (
	DfltMinCharsToPrint = 30
	DfltTargetLineLen   = 80
	DfltListPrefix      = "- "
)

Variables

This section is empty.

Functions

This section is empty.

Types

type TWConf 

type TWConf struct {
	W               io.Writer
	MinCharsToPrint int
	TargetLineLen   int
	ListPrefix      string
}

TWConf holds the configuration for a text wrapper

func NewTWConf 

func NewTWConf(opts ...TWConfOptFunc) (*TWConf, error)

NewTWConf constructs a TWConf with the default values. To override the default values pass the appropriate option functions. If any of the option funcs returns an error the error is returned and a nil value

func NewTWConfOrPanic added in v1.3.0 

func NewTWConfOrPanic(opts ...TWConfOptFunc) *TWConf

NewTWConfOrPanic constructs a TWConf using the NewTWConf func but will panic if any error is returned. This is more convenient when constructing a TWConf as it's a programming error if bad parameters have been passed and so a panic is appropriate.

func (TWConf) IdxList added in v1.4.0 

func (twc TWConf) IdxList(list []string, indent int)

IdxList will print the list of strings, one per line, with the appropriate indent and with each item prefixed with an index number

func (TWConf) IdxListItem added in v1.5.0 

func (twc TWConf) IdxListItem(indent int, list ...string)

IdxListItem calls IdxList it is simply a more convenient interface

Example

ExampleTWConf_IdxListItem provides an exaple of how the twrap.IdxListItem method might be used.

Note that there is an alternative twrap.IdxList method with the same behaviour, IdxListItem simply provides an alternative interface to the same behaviour.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.IdxListItem(4, "The quality of mercy is not strained.",
		"It droppeth as the gentle rain from heaven.",
		"Upon the place beneath.")

}

Output:

    - 1: The quality of mercy is not strained.
    - 2: It droppeth as the gentle rain from heaven.
    - 3: Upon the place beneath.
Example (ManyItems)

ExampleTWConf_IdxListItem_manyItems provides an exaple of how the twrap.IdxListItem method might be used. It highlights how the space for the digits automatically adjusts to the length of the list.

Note that there is an alternative twrap.IdxList method with the same behaviour, IdxListItem simply provides an alternative interface to the same behaviour.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.IdxListItem(4, "first item",
		"second item",
		"third item",
		"fourth",
		"and another",
		"and yet another",
		"seven",
		"eight",
		"nine",
		"ten",
		"that's sufficient")

}

Output:

    -  1: first item
    -  2: second item
    -  3: third item
    -  4: fourth
    -  5: and another
    -  6: and yet another
    -  7: seven
    -  8: eight
    -  9: nine
    - 10: ten
    - 11: that's sufficient

func (TWConf) IdxNoRptList added in v1.4.0 

func (twc TWConf) IdxNoRptList(list []string, indent int)

IdxNoRptList will print a list of strings with no wrapping. Each list item will be prefixed with an index number and will have any characters from the start of the string which are common to the preceding list item replaced with spaces

func (TWConf) IdxNoRptListItem added in v1.5.0 

func (twc TWConf) IdxNoRptListItem(indent int, list ...string)

IdxNoRptListItem calls IdxNoRptList it is simply a more convenient interface

func (TWConf) IdxNoRptPathList added in v1.4.0 

func (twc TWConf) IdxNoRptPathList(list []string, indent int)

IdxNoRptPathList will print a list of strings with no wrapping. Each list item will be prefixed with an index number. Each list item is assumed to be a pathname and will have any part of the path (except the last) which is the same as the corresponding part of the previous list item replaced with spaces. As soon as any part of the path differs, the remainder is printed as is.

func (TWConf) IdxNoRptPathListItem added in v1.5.0 

func (twc TWConf) IdxNoRptPathListItem(indent int, list ...string)

IdxNoRptPathListItem calls IdxNoRptPathList it is simply a more convenient interface

func (TWConf) List added in v1.4.0 

func (twc TWConf) List(list []string, indent int)

List will print the list of strings, one per line, with the appropriate indent and with each item prefixed with the list prefix

func (TWConf) ListItem added in v1.5.0 

func (twc TWConf) ListItem(indent int, list ...string)

ListItem calls List it is simply a more convenient interface

Example

ExampleTWConf_ListItem provides an exaple of how the twrap.ListItem method might be used.

Note that there is an alternative twrap.List method with the same behaviour, ListItem simply provides an alternative interface to the same behaviour.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.ListItem(4, "The quality of mercy is not strained.",
		"It droppeth as the gentle rain from heaven.",
		"Upon the place beneath.")

}

Output:

    - The quality of mercy is not strained.
    - It droppeth as the gentle rain from heaven.
    - Upon the place beneath.

func (TWConf) NoRptList added in v1.4.0 

func (twc TWConf) NoRptList(list []string, indent int)

NoRptList will print a list of strings with no wrapping. Each list item will have any characters from the start of the string which are common to the preceding list item replaced with spaces

func (TWConf) NoRptListItem added in v1.5.0 

func (twc TWConf) NoRptListItem(indent int, list ...string)

NoRptListItem calls NoRptList it is simply a more convenient interface

Example

ExampleTWConf_NoRptListItem provides an exaple of how the twrap.NoRptListItem method might be used.

Note that there is an alternative twrap.NoRptList method with the same behaviour, NoRptListItem simply provides an alternative interface to the same behaviour.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.NoRptListItem(4,
		"/abc/def/123",
		"/abc/def/124",
		"/abc/ghi/123")

}

Output:

    - /abc/def/123
    -            4
    -      ghi/123

func (TWConf) NoRptPathList added in v1.4.0 

func (twc TWConf) NoRptPathList(list []string, indent int)

NoRptPathList will print a list of strings with no wrapping. Each list item is assumed to be a pathname and will have any part of the path (except the last) which is the same as the corresponding part of the previous list item replaced with spaces. As soon as any part of the path differs, the remainder is printed as is.

func (TWConf) NoRptPathListItem added in v1.5.0 

func (twc TWConf) NoRptPathListItem(indent int, list ...string)

NoRptPathListItem calls NoRptPathList it is simply a more convenient interface

Example

ExampleTWConf_NoRptPathListItem provides an exaple of how the twrap.NoRptPathListItem method might be used.

Note that there is an alternative twrap.NoRptPathList method with the same behaviour, NoRptPathListItem simply provides an alternative interface to the same behaviour.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.NoRptPathListItem(4,
		"/abc/def/123",
		"/abc/def/124",
		"/abc/ghi/123")

}

Output:

    - /abc/def/123
    -          124
    -      ghi/123

func (TWConf) Print added in v1.2.0 

func (twc TWConf) Print(a ...any) (n int, err error)

Print calls fmt.Fprint passing the TWConf writer

func (TWConf) Printf added in v1.2.0 

func (twc TWConf) Printf(format string, a ...any) (n int, err error)

Printf calls fmt.Fprintf passing the TWConf writer

func (TWConf) Println added in v1.2.0 

func (twc TWConf) Println(a ...any) (n int, err error)

Println calls fmt.Fprintln passing the TWConf writer

func (TWConf) Wrap 

func (twc TWConf) Wrap(text string, indent int)

Wrap will print the text onto the configured writer but wraps and indents the text. It will split the text into paragraphs at any newline characters. It will always print at least MinCharsToPrint chars but will try to fit the text into TargetLineLen chars.

Example

ExampleTWConf_Wrap provides an exaple of how the twrap.Wrap method might be used.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.Wrap("\nThe quality of mercy is not strained."+
		" It droppeth as the gentle rain from heaven."+
		" Upon the place beneath.", 20)

}

Output:

                    The quality of mercy is not strained. It droppeth as the
                    gentle rain from heaven. Upon the place beneath.
Example (ShortLines)

ExampleTWConf_Wrap_shortLines provides an exaple of how the twrap.Wrap method might be used. The TWConf is created with a shorter line length.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic(twrap.SetTargetLineLen(60))

	twc.Wrap("\nThe quality of mercy is not strained."+
		" It droppeth as the gentle rain from heaven."+
		" Upon the place beneath.", 20)

}

Output:

                    The quality of mercy is not strained. It
                    droppeth as the gentle rain from heaven.
                    Upon the place beneath.

func (TWConf) Wrap2Indent 

func (twc TWConf) Wrap2Indent(
	text string,
	firstLineIndent, otherLineIndent int,
)

Wrap2Indent will print the text as with Wrap. The first line printed of each paragraph will be indented by the first supplied indent and the other lines will be indented by the second indent value.

Example

ExampleTWConf_Wrap2Indent provides an exaple of how the twrap.Wrap2Indent method might be used.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.Wrap2Indent("list item: A description of the item such as"+
		" might appear in a menu.\n"+
		"item2: A description of the second item in the menu. Note the"+
		" indentation of the start of the line and the following text.",
		20, 24)

}

Output:

                    list item: A description of the item such as might appear in
                        a menu.
                    item2: A description of the second item in the menu. Note
                        the indentation of the start of the line and the
                        following text.

func (TWConf) Wrap3Indent added in v1.1.0 

func (twc TWConf) Wrap3Indent(
	text string,
	line1Indent, paraLine1Indent, line2Indent int,
)

Wrap3Indent will print the text as with Wrap. The first line printed will be indented by the first supplied indent, thereafter the first line of each paragraph will be indented by the second supplied indent and any other lines will be indented by the third indent value.

func (TWConf) WrapPrefixed added in v1.1.0 

func (twc TWConf) WrapPrefixed(prefix, text string, indent int)

WrapPrefixed will print the text as with Wrap. The first line will start with the prefix and the indent of the subsequent lines will be adjusted to include the length of the prefix.

Example

ExampleTWConf_WrapPrefixed provides an exaple of how the twrap.WrapPrefixed method might be used.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.WrapPrefixed("Portia: ", "The quality of mercy is not strained."+
		" It droppeth as the gentle rain from heaven."+
		" Upon the place beneath.", 20)

}

Output:

                    Portia: The quality of mercy is not strained. It droppeth as
                            the gentle rain from heaven. Upon the place beneath.
Example (MultiPara)

ExampleTWConf_WrapPrefixed_multiPara provides an exaple of how the twrap.WrapPrefixed method might be used.

Note that it uses the NewTWConfOrPanic func. This will panic if there are any problems with the optional parameters passed to it. If you want to handle any errors yourself then use the NewTWConf func instead. This will return a non-nil error if there are any problems with the parameters and the returned TWConf value shoud not be used. 

package main

import (
	"github.com/nickwells/twrap.mod/twrap"
)

func main() {
	twc := twrap.NewTWConfOrPanic()

	twc.WrapPrefixed("See also: ",
		"The github.com/nickwells/param.mod/param/phelp package makes"+
			" extensive use of the twrap package"+
			"\n\n"+
			"As do several of the utilities in .../utilities",
		10)

}

Output:

          See also: The github.com/nickwells/param.mod/param/phelp package makes
                    extensive use of the twrap package

                    As do several of the utilities in .../utilities

type TWConfOptFunc 

type TWConfOptFunc func(*TWConf) error

TWConfOptFunc is the signature of the function that is passed to the NewTWConf function to override the default values

func SetListPrefix added in v1.4.0 

func SetListPrefix(pfx string) TWConfOptFunc

SetListPrefix returns a TWConfOptFunc suitable for passing to NewTWConf which will set the ListPrefix

func SetMinChars added in v1.1.0 

func SetMinChars(n int) TWConfOptFunc

SetMinChars returns a TWConfOptFunc suitable for passing to NewTWConf which will set the MinCharsToPrint. The value must be greater or equal to zero.

func SetTargetLineLen added in v1.1.0 

func SetTargetLineLen(n int) TWConfOptFunc

SetTargetLineLen returns a TWConfOptFunc suitable for passing to NewTWConf which will set the TargetLineLen. The new target line length must be greater than zero.

func SetWriter added in v1.1.0 

func SetWriter(w io.Writer) TWConfOptFunc

SetWriter returns a TWConfOptFunc suitable for passing to NewTWConf which will set the Writer from the default value of os.Stdout. The writer must not be nil.

func TWConfOptSetMinChars deprecated 

func TWConfOptSetMinChars(n int) TWConfOptFunc

TWConfOptSetMinChars

Deprecated: use SetMinChars instead

func TWConfOptSetTargetLineLen deprecated 

func TWConfOptSetTargetLineLen(n int) TWConfOptFunc

TWConfOptSetTargetLineLen

Deprecated: use SetTargetLineLen instead

func TWConfOptSetWriter deprecated 

func TWConfOptSetWriter(w io.Writer) TWConfOptFunc

TWConfOptSetWriter

Deprecated: use SetWriter instead

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.