human

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2023 License: AGPL-3.0, MIT Imports: 14 Imported by: 0

Documentation

Overview

Package human provides types that support parsing and formatting human-friendly representations of values in various units.

The package only exposes type names that are not that common to find in Go programs (in our experience). For that reason, it can be interesting to import the package as '.' (dot) to inject the symbols in the namespace of the importer, especially in the common case where it's being used in the main package of a program, for example: 

import (
	. "github.com/segmentio/cli/human"
)

This can help improve code readability by importing constants in the package namespace, allowing constructs like: 

type clientConfig{
	DialTimeout Duration
	BufferSize  Bytes
	RateLimit   Rate
}
...
config := clientConfig{
	DialTimeout: 10 * Second,
	BufferSize:  64 * KiB,
	RateLimit:   20 * PerSecond,
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseBytesFloat64 

func ParseBytesFloat64(s string) (float64, error)

Types

type Boolean 

type Boolean bool

Boolean returns a boolean value.

The type supports parsing values as "true", "false", "yes", or "no", all case insensitive.

func ParseBoolean 

func ParseBoolean(s string) (Boolean, error)

func (Boolean) Format 

func (b Boolean) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbse: 

s	"yes" or "no"
t	"true" or "false"
v	same as 's'

For each of these options, these extra flags are also intepreted: 

Capitalized     +
All uppercase   #

func (Boolean) Get 

func (b Boolean) Get() any

func (Boolean) GoString 

func (b Boolean) GoString() string

GoString satisfies the fmt.GoStringer interface.

func (Boolean) MarshalJSON 

func (b Boolean) MarshalJSON() ([]byte, error)

func (Boolean) MarshalText 

func (b Boolean) MarshalText() ([]byte, error)

func (Boolean) MarshalYAML 

func (b Boolean) MarshalYAML() (any, error)

func (*Boolean) Set 

func (b *Boolean) Set(s string) error

func (Boolean) String 

func (b Boolean) String() string

String satisfies the fmt.Stringer interface, returns "yes" or "no".

func (*Boolean) UnmarshalJSON 

func (b *Boolean) UnmarshalJSON(j []byte) error

func (*Boolean) UnmarshalText 

func (b *Boolean) UnmarshalText(t []byte) error

func (*Boolean) UnmarshalYAML 

func (b *Boolean) UnmarshalYAML(y *yaml.Node) error

type Bytes 

type Bytes uint64

Bytes represents a number of bytes.

The type support parsing values in formats like: 

42 KB
8Gi
1.5KiB
...

Two models are supported, using factors of 1000 and factors of 1024 via units like KB, MB, GB for the former, or Ki, Mi, MiB for the latter.

In the current implementation, formatting is always done in factors of 1024, using units like Ki, Mi, Gi etc...

Values may be decimals when using units larger than B. Partial bytes cannot be represnted (e.g. 0.5B is not supported). 

const (
	B Bytes = 1

	KB Bytes = 1000 * B
	MB Bytes = 1000 * KB
	GB Bytes = 1000 * MB
	TB Bytes = 1000 * GB
	PB Bytes = 1000 * TB

	KiB Bytes = 1024 * B
	MiB Bytes = 1024 * KiB
	GiB Bytes = 1024 * MiB
	TiB Bytes = 1024 * GiB
	PiB Bytes = 1024 * TiB
)

func ParseBytes 

func ParseBytes(s string) (Bytes, error)

func (Bytes) Format 

func (b Bytes) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

d	base 10, unit-less
b	base 10, with unit using 1000 factors
s	base 10, with unit using 1024 factors (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

func (Bytes) Get 

func (b Bytes) Get() any

func (Bytes) GoString 

func (b Bytes) GoString() string

func (Bytes) MarshalJSON 

func (b Bytes) MarshalJSON() ([]byte, error)

func (Bytes) MarshalText 

func (b Bytes) MarshalText() ([]byte, error)

func (Bytes) MarshalYAML 

func (b Bytes) MarshalYAML() (any, error)

func (*Bytes) Set 

func (b *Bytes) Set(s string) error

func (Bytes) String 

func (b Bytes) String() string

func (*Bytes) UnmarshalJSON 

func (b *Bytes) UnmarshalJSON(j []byte) error

func (*Bytes) UnmarshalText 

func (b *Bytes) UnmarshalText(t []byte) error

func (*Bytes) UnmarshalYAML 

func (b *Bytes) UnmarshalYAML(y *yaml.Node) error

type Count 

type Count float64

Count represents a count without a unit.

The type supports parsing and formatting values like: 

1234
10 K
1.5M
...

const (
	K Count = 1000
	M Count = 1000 * K
	G Count = 1000 * M
	T Count = 1000 * G
	P Count = 1000 * T
)

func ParseCount 

func ParseCount(s string) (Count, error)

func (Count) Format 

func (c Count) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

d	base 10, unit-less, rounded to the nearest integer
e	base 10, unit-less, scientific notation
f	base 10, unit-less, decimal notation
g	base 10, unit-less, act like 'e' or 'f' depending on scale
s	base 10, with unit (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

func (Count) Get 

func (c Count) Get() any

func (Count) GoString 

func (c Count) GoString() string

func (Count) MarshalJSON 

func (c Count) MarshalJSON() ([]byte, error)

func (Count) MarshalText 

func (c Count) MarshalText() ([]byte, error)

func (Count) MarshalYAML 

func (c Count) MarshalYAML() (any, error)

func (*Count) Set 

func (c *Count) Set(s string) error

func (Count) String 

func (c Count) String() string

func (*Count) UnmarshalJSON 

func (c *Count) UnmarshalJSON(b []byte) error

func (*Count) UnmarshalText 

func (c *Count) UnmarshalText(b []byte) error

func (*Count) UnmarshalYAML 

func (c *Count) UnmarshalYAML(y *yaml.Node) error

type Duration 

type Duration time.Duration

Duration is based on time.Duration, but supports parsing and formatting more human-friendly representations.

Here are examples of supported values: 

5m30s
1d
4 weeks
1.5y
...

The current implementation does not support decimal values, however, contributions are welcome to add this feature.

Time being what it is, months and years are hard to represent because their durations vary in unpredictable ways. This is why the package only exposes constants up to a 1 week duration. For the sake of accuracy, years and months are always represented relative to a given date. Technically, leap seconds can cause any unit above the second to be variable, but in order to remain mentaly sane, we chose to ignore this detail in the implementation of this package. 

const (
	Nanosecond  Duration = 1
	Microsecond Duration = 1000 * Nanosecond
	Millisecond Duration = 1000 * Microsecond
	Second      Duration = 1000 * Millisecond
	Minute      Duration = 60 * Second
	Hour        Duration = 60 * Minute
	Day         Duration = 24 * Hour
	Week        Duration = 7 * Day
)

func ParseDuration 

func ParseDuration(s string) (Duration, error)

func ParseDurationUntil 

func ParseDurationUntil(s string, now time.Time) (Duration, error)

func (Duration) Days 

func (d Duration) Days() int

func (Duration) Format 

func (d Duration) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

s	outputs a string representation of the duration (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

The 's' and 'v' formatting verbs also interpret the options: 

'-' outputs full names of the time units instead of abbreviations
'.' followed by a digit to limit the precision of the output

func (Duration) Formatter 

func (d Duration) Formatter(now time.Time) fmt.Formatter

func (Duration) Get 

func (d Duration) Get() any

func (Duration) GoString 

func (d Duration) GoString() string

func (Duration) Hours 

func (d Duration) Hours() int

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

func (Duration) MarshalText 

func (d Duration) MarshalText() ([]byte, error)

func (Duration) MarshalYAML 

func (d Duration) MarshalYAML() (any, error)

func (Duration) Microseconds 

func (d Duration) Microseconds() int

func (Duration) Milliseconds 

func (d Duration) Milliseconds() int

func (Duration) Minutes 

func (d Duration) Minutes() int

func (Duration) Months 

func (d Duration) Months(until time.Time) int

func (Duration) Nanoseconds 

func (d Duration) Nanoseconds() int

func (Duration) Seconds 

func (d Duration) Seconds() int

func (*Duration) Set 

func (d *Duration) Set(s string) error

func (Duration) String 

func (d Duration) String() string

func (Duration) Text 

func (d Duration) Text(now time.Time) string

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(b []byte) error

func (*Duration) UnmarshalText 

func (d *Duration) UnmarshalText(b []byte) error

func (*Duration) UnmarshalYAML 

func (d *Duration) UnmarshalYAML(y *yaml.Node) error

func (Duration) Weeks 

func (d Duration) Weeks() int

func (Duration) Years 

func (d Duration) Years(until time.Time) int

type Number 

type Number float64

Number is similar to Count, but supports values with separators for readability purposes.

The type supports parsing and formatting values likes: 

123
1.5
2,000,000
...

func ParseNumber 

func ParseNumber(s string) (Number, error)

func (Number) Format 

func (n Number) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

e	base 10, separator-free, scientific notation
f	base 10, separator-free, decimal notation
g	base 10, separator-free, act like 'e' or 'f' depending on scale
s	base 10, with separators (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

func (Number) Get 

func (n Number) Get() any

func (Number) GoString 

func (n Number) GoString() string

func (Number) MarshalJSON 

func (n Number) MarshalJSON() ([]byte, error)

func (Number) MarshalText 

func (n Number) MarshalText() ([]byte, error)

func (Number) MarshalYAML 

func (n Number) MarshalYAML() (any, error)

func (*Number) Set 

func (n *Number) Set(s string) error

func (Number) String 

func (n Number) String() string

func (*Number) UnmarshalJSON 

func (n *Number) UnmarshalJSON(b []byte) error

func (*Number) UnmarshalText 

func (n *Number) UnmarshalText(b []byte) error

func (*Number) UnmarshalYAML 

func (n *Number) UnmarshalYAML(y *yaml.Node) error

type Path 

type Path string

Path represents a path on the file system.

The type interprets the special prefix "~/" as representing the home directory of the user that the program is running as.

func (Path) Get 

func (p Path) Get() any

func (Path) Resolve 

func (p Path) Resolve() (string, error)

func (*Path) Set 

func (p *Path) Set(s string) error

func (Path) String 

func (p Path) String() string

func (*Path) UnmarshalText 

func (p *Path) UnmarshalText(b []byte) error

type Rate 

type Rate float64

Rate represents a count devided by a unit of time.

The type supports parsing and formatting values like: 

200/s
1 / minute
0.5/week
...

Rate values are always stored in their per-second form in Go programs, and properly converted during parsing and formatting. 

const (
	PerNanosecond  Rate = 1 / Rate(Nanosecond)
	PerMicrosecond Rate = 1 / Rate(Microsecond)
	PerMillisecond Rate = 1 / Rate(Millisecond)
	PerSecond      Rate = 1 / Rate(Second)
	PerMinute      Rate = 1 / Rate(Minute)
	PerHour        Rate = 1 / Rate(Hour)
	PerDay         Rate = 1 / Rate(Day)
	PerWeek        Rate = 1 / Rate(Week)
)

func ParseRate 

func ParseRate(s string) (Rate, error)

func (Rate) Format 

func (r Rate) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

e	base 10, unit-less, scientific notation
f	base 10, unit-less, decimal notation
g	base 10, unit-less, act like 'e' or 'f' depending on scale
s	base 10, with units (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

func (Rate) Formatter 

func (r Rate) Formatter(d Duration) fmt.Formatter

func (Rate) Get 

func (r Rate) Get() any

func (Rate) GoString 

func (r Rate) GoString() string

func (Rate) MarshalJSON 

func (r Rate) MarshalJSON() ([]byte, error)

func (Rate) MarshalText 

func (r Rate) MarshalText() ([]byte, error)

func (Rate) MarshalYAML 

func (r Rate) MarshalYAML() (any, error)

func (*Rate) Set 

func (r *Rate) Set(s string) error

func (Rate) String 

func (r Rate) String() string

func (Rate) Text 

func (r Rate) Text(d Duration) string

func (*Rate) UnmarshalJSON 

func (r *Rate) UnmarshalJSON(b []byte) error

func (*Rate) UnmarshalText 

func (r *Rate) UnmarshalText(b []byte) error

func (*Rate) UnmarshalYAML 

func (r *Rate) UnmarshalYAML(y *yaml.Node) error

type Ratio 

type Ratio float64

Ratio represents percentage-like values.

The type supports parsing and formatting values like: 

0.1
25%
0.5 %
...

Ratio values are stored as floating pointer numbers between 0 and 1 (assuming they stay within the 0-100% bounds), and formatted as percentages.

func ParseRatio 

func ParseRatio(s string) (Ratio, error)

func (Ratio) Format 

func (r Ratio) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

e	base 10, unit-less, scientific notation
f	base 10, unit-less, decimal notation
g	base 10, unit-less, act like 'e' or 'f' depending on scale
s	base 10, with units (same as calling String)
v	same as the 's' format, unless '#' is set to print the go value

func (Ratio) Formatter 

func (r Ratio) Formatter(precision int) fmt.Formatter

func (Ratio) Get 

func (r Ratio) Get() any

func (Ratio) GoString 

func (r Ratio) GoString() string

func (Ratio) MarshalJSON 

func (r Ratio) MarshalJSON() ([]byte, error)

func (Ratio) MarshalText 

func (r Ratio) MarshalText() ([]byte, error)

func (Ratio) MarshalYAML 

func (r Ratio) MarshalYAML() (any, error)

func (*Ratio) Set 

func (r *Ratio) Set(s string) error

func (Ratio) String 

func (r Ratio) String() string

func (Ratio) Text 

func (r Ratio) Text(precision int) string

func (*Ratio) UnmarshalJSON 

func (r *Ratio) UnmarshalJSON(b []byte) error

func (*Ratio) UnmarshalText 

func (r *Ratio) UnmarshalText(b []byte) error

func (*Ratio) UnmarshalYAML 

func (r *Ratio) UnmarshalYAML(y *yaml.Node) error

type Time 

type Time time.Time

Time represents absolute point in times. The implementation is based on time.Time.

The type supports all default time formats provided by the standard time package, as well as parsing and formatting values relative to a given time point, for example: 

5 minutes ago
1h later
...

func ParseTime 

func ParseTime(s string) (Time, error)

func ParseTimeAt 

func ParseTimeAt(s string, now time.Time) (Time, error)

func (Time) Format 

func (t Time) Format(w fmt.State, v rune)

Format satisfies the fmt.Formatter interface.

The method supports the following formatting verbs: 

s	duration relative to now (same as calling String)
v	sam as the 's' format, unless '#' is set to print the go value

The 's' and 'v' formatting verbs also interpret the options: 

'-' outputs full names of the time units instead of abbreviations
'.' followed by a digit to limit the precision of the output

func (Time) Formatter 

func (t Time) Formatter(now time.Time) fmt.Formatter

func (Time) Get 

func (t Time) Get() any

func (Time) GoString 

func (t Time) GoString() string

func (Time) IsZero 

func (t Time) IsZero() bool

func (Time) MarshalJSON 

func (t Time) MarshalJSON() ([]byte, error)

func (Time) MarshalText 

func (t Time) MarshalText() ([]byte, error)

func (Time) MarshalYAML 

func (t Time) MarshalYAML() (any, error)

func (*Time) Set 

func (t *Time) Set(s string) error

func (Time) String 

func (t Time) String() string

func (Time) Text 

func (t Time) Text(now time.Time) string

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(b []byte) error

func (*Time) UnmarshalText 

func (t *Time) UnmarshalText(b []byte) error

func (*Time) UnmarshalYAML 

func (t *Time) UnmarshalYAML(y *yaml.Node) error

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.