dense

Documentation

Overview

Package dense parses one line of dense chat-command text into positionals and flags, in the grammar spec 0024 fixes: positionals first, then flags that take every following word, with presence kept apart from values.

It takes a string and does not care where it came from. A slash-command String option costs no privileged intent and arrives through a platform that validated everything around it; message content under NeedMessages costs the intent the configuration reference documents. Either is the consumer's choice. Nothing here dispatches commands, generates help, or converts types: dice, numbers and durations are the consumer's, and an identifier inside dense text is text, never something the platform resolved.

The grammar, in the order the parser applies it:

• Chat clients rewrite punctuation; curly quotes become straight quotes and en or em dashes become a hyphen before anything else happens.
• A quoted word ("..." or '...', backslash escaping the next character) is a single word and is never a flag. An unterminated quote refuses the line.
• A flag is one or more dashes, a letter, then anything; trailing digits are split off as an ephemeral use count, so "-d3" is flag "d" with three uses, and a flag name therefore cannot end in a digit. "-2" is a word.
• Words before the first flag are positionals. After it, every word belongs to the most recent flag, so a line has exactly one reading: "attack goblin -adv" is a boolean adv, "attack -adv goblin" is adv=goblin, and a writer who meant otherwise moves the word.
• A flag followed by a flag, or by nothing, is present with no values. That is what boolean means; the string "true" is never invented.
• Repeats accumulate in order, and "-t a b" is the same two values as "-t a -t b". The use count belongs to the occurrence and travels with each value it collected; a count with nothing to apply it to is refused.
• With Booleans, a declared flag never takes a value, and a word after one is refused with a reason rather than bound.

Index

• Variables
• type Option
  • func Booleans(names ...string) Option
• type Parsed
  • func Parse(line string, opts ...Option) (Parsed, error)
  • func (p Parsed) Flags() []string
  • func (p Parsed) Has(name string) bool
  • func (p Parsed) Strings(name string) []string
  • func (p Parsed) Values(name string) []Value
• type Value

Variables

var (
	// ErrUnterminatedQuote is a line whose quote never closed.
	ErrUnterminatedQuote = errors.NewSentinel("comms.dense.unterminated_quote",
		"dense: unterminated quote")

	// ErrCountWithoutValue is an ephemeral count ("-d3") with no value after it.
	ErrCountWithoutValue = errors.NewSentinel("comms.dense.count_without_value",
		"dense: an ephemeral count needs a value to apply to")

	// ErrInvalidCount is an ephemeral count that is zero or has more than
	// maxCountDigits digits.
	ErrInvalidCount = errors.NewSentinel("comms.dense.invalid_count",
		"dense: an ephemeral count must be between 1 and 999999999")

	// ErrWordAfterBoolean is a word after a flag declared boolean. The line is
	// refused rather than the word bound, because the writer either meant a
	// positional (move it before the flags) or a value (quote it, and declare
	// the flag differently).
	ErrWordAfterBoolean = errors.NewSentinel("comms.dense.word_after_boolean",
		"dense: a word after a boolean flag; quote it or move it before the flags")
)

Sentinels. Providers do not wrap these; the parser is the consumer's.

Types

type Option

type Option func(*config)

Option adjusts a parse.

func Booleans

func Booleans(names ...string) Option

Booleans declares flags that never take a value. A word after one is refused with ErrWordAfterBoolean instead of being bound to it.

type Parsed

type Parsed struct {
	Positionals []string
	// contains filtered or unexported fields
}

Parsed is one line, read. Positionals is nil when there were none. Flags are reached through Has, Values and Strings; a flag present with no values is boolean, and the zero Parsed reads as empty.

func Parse

func Parse(line string, opts ...Option) (Parsed, error)

Parse reads one line.

func (Parsed) Flags

func (p Parsed) Flags() []string

Flags returns the flag names in order of first appearance.

func (Parsed) Has

func (p Parsed) Has(name string) bool

Has reports whether the flag appeared at all, with or without values.

func (Parsed) Strings

func (p Parsed) Strings(name string) []string

Strings is Values without the use counts.

func (Parsed) Values

func (p Parsed) Values(name string) []Value

Values returns the flag's values in order of appearance, nil when the flag was absent, and empty when it was present with none.

type Value

type Value struct {
	Text string
	Uses int
}

Value is one value a flag collected. Uses is the ephemeral use count of the occurrence that collected it, and zero when there was none.