cmdtypes

Package cloudeng.io/cmdutil/cmdtypes

import cloudeng.io/cmdutil/cmdtypes

Package cmdtypes provides types that are shared by the configuration and command line packages, and that can be encoded and decoded as JSON, YAML and text without those packages depending on each other.

Constants

Byte, KB, MB, GB, TB, KiB, MiB, GiB, TiB

Byte ByteSize = 1
KB ByteSize = 1_000
MB = 1_000 * KB
GB = 1_000 * MB
TB = 1_000 * GB
KiB ByteSize = 1_024
MiB = 1_024 * KiB
GiB = 1_024 * MiB
TiB = 1_024 * GiB

Variables

FlexTimeFormats

FlexTimeFormats = []string{
	time.RFC3339,
	time.DateTime,
	time.TimeOnly,
	time.DateOnly,
}

FlexTimeFormats are the layouts that a FlexTime is decoded from, tried in this order. They are time.RFC3339, time.DateTime, time.TimeOnly and time.DateOnly.

Types

Type ByteSize

type ByteSize int64

ByteSize represents a quantity of bytes. It can be parsed from and marshaled to human-readable strings using either binary (KiB, MiB, GiB, TiB) or decimal (KB, MB, GB, TB) unit suffixes. A space between the number and unit is optional; parsing is case-insensitive. Bare integers are treated as bytes. Floating-point values are accepted during parsing (e.g. "1.5GiB").

Encoding and decoding is implemented by MarshalText and UnmarshalText, which encoding/json, encoding/json/v2 and gopkg.in/yaml.v3 all use, so a single type serves all three without this package depending on any of them.

Functions

func ParseByteSize(s string) (ByteSize, error)

ParseByteSize parses s into a ByteSize. Binary (KiB, MiB, GiB, TiB) and decimal (KB, MB, GB, TB) suffixes are supported. A space between the number and unit is allowed; parsing is case-insensitive. A bare number is treated as bytes. Floating-point values are rounded to the nearest byte.

Methods

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

MarshalText implements encoding.TextMarshaler, and with it the encoding used for JSON and YAML.

func (b ByteSize) String() string

String returns a human-readable representation of b. It selects the largest decimal unit (TB, GB, MB, KB) that divides b evenly, then the largest binary unit (TiB, GiB, MiB, KiB), and falls back to "NB" when no unit divides evenly.

func (b *ByteSize) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler, and with it the decoding used for JSON and YAML.

Type FlexTime

type FlexTime time.Time

FlexTime is a time.Time that can be decoded from any of FlexTimeFormats and is always encoded as time.RFC3339.

Encoding and decoding is implemented by MarshalText and UnmarshalText, which encoding/json, encoding/json/v2 and gopkg.in/yaml.v3 all use, so a single type serves all three without this package depending on any of them.

Functions

func ParseFlexTime(s string) (FlexTime, error)

ParseFlexTime parses s as any of FlexTimeFormats.

Methods

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

MarshalText implements encoding.TextMarshaler, and with it the encoding used for JSON and YAML.

func (t FlexTime) String() string

String returns the time in time.RFC3339 format.

func (t FlexTime) Time() time.Time

Time returns the time.Time represented by t.

func (t *FlexTime) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler, and with it the decoding used for JSON and YAML.

Type Permissions

type Permissions fs.FileMode

Permissions represents file permission bits (e.g. 0700, 0755). It can be decoded from an octal number ("0700", "700", "0o700", "0x1c0"), an rwx string ("rwxr-xr-x", "-rwx------", "rwx"), or symbolic chmod notation ("u=rwx,go=", "u=rwx,go=rx"), and is always encoded as the 4 digit octal string, which every one of those formats can be read back from.

The setuid, setgid and sticky bits are represented as fs.ModeSetuid, fs.ModeSetgid and fs.ModeSticky, whichever notation they were written in, so that 4755 and rwsr-xr-x yield the same value. They are written out in the traditional UNIX form, ie. in the leading octal digit.

Encoding and decoding is implemented by MarshalText and UnmarshalText, which both encoding/json and gopkg.in/yaml.v3 use, so a single type serves both without this package depending on either. YAML additionally routes unquoted numbers such as 0700 through UnmarshalText, so they are read as octal rather than as decimal. JSON has no octal literal, so a JSON number is handled by UnmarshalJSON below, which reads it as octal for consistency.

Functions

func ParsePermissions(s string) (Permissions, error)

ParsePermissions parses a permission string in octal ("0700", "700", "0o700", "0x1c0"), rwx ("rwxr-xr-x", "-rwx------", "rwx") or symbolic chmod ("u=rwx,go=", "u=rwx,go=rx") format.

Methods

func (p Permissions) FileMode() fs.FileMode

FileMode returns the fs.FileMode represented by p.

func (p Permissions) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, and with it the encoding used for both JSON and YAML.

func (p Permissions) String() string

String returns the 4 digit octal representation of the permissions (e.g. "0700", "4755"), in the traditional UNIX form in which the leading digit carries the setuid, setgid and sticky bits.

func (p *Permissions) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. It exists only so that a JSON number is read as octal, as it is in YAML and on a command line: JSON has no octal literal, so 700 would otherwise be read as decimal and grant the wrong bits. Strings are handled by UnmarshalText.

func (p *Permissions) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler, and with it the decoding used for both JSON strings and YAML scalars.