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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL