docfmt

Documentation

Overview

Package docfmt implements formatting and checking of user format strings.

Strings are checked at runtime for proper formatting, or by a (simple) static analyzer. Checking is disabled by default, but can be enabled by building with the "doccheck" tag. See Check.

Index

• Constants
• func AssertValid(message string)
• func AssertValidArgs(args ...any)
• func Capitalize(word string) (result string, ok bool)
• func Format(message string) string
• func SplitParts(message string) (parts []string)
• func SplitWords(part string) (words []string, sep string)
• type ValidationError
  • func (ve ValidationError) Error() string
• type ValidationKind
• type ValidationResult
  • func Validate(message string, exceptions ...string) (errors []ValidationResult)
  • func (v ValidationResult) Error() string

Constants

const Enabled = false

Enabled indicates if runtime checking is enabled

Functions

func AssertValid

func AssertValid(message string)

AssertValid asserts that message is properly formatted and calling Validate on it returns no results.

When checking is disabled, no runtime checking is performed. When checking is enabled and a message fails to pass validation, calls panic()

func AssertValidArgs

func AssertValidArgs(args ...any)

AssertValidArgs checks that args does not contain exactly one argument of type error.

When checking is disabled, no runtime checking is performed. When checking is enabled and the check is failed, calls panic()

func Capitalize

func Capitalize(word string) (result string, ok bool)

Capitalize capitalizes word that passes validation of individual words. A word is capitalized by upper-casing the first non-whitespace rune in the word.

Returns the capitalized word, and a boolean true if capitalization was performed, or the unchanged word and false if the word contained only whitespace.

func Format

func Format(message string) string

Format formats message before presenting it to a user. It passes the message to AssertValid, which may cause a panic if checking is enabled and the word does not pass the checks.

A message is formatted by splitting a message into parts and words. It then capitalizes the first non-whitespace word of each part.

See also SplitParts, SplitWords, Check, Capitalize.

func SplitParts

func SplitParts(message string) (parts []string)

SplitParts splits a message into parts for validation.

Message parts are delimited by either ':' or '.'. Each part may contain quoted strings, as in go syntax. Quoted strings are always considered part of the same part.

Separators are considered part of the preceding part. Every part, with the exception of the last part, will have a string separator. The empty message consists of a single empty part.

Any message fulfills the invariant:

message == strings.Join(SplitParts(message), "")

func SplitWords

func SplitWords(part string) (words []string, sep string)

SplitWords splits a single part into different words and a possibly trailing separator.

Words are delimited by space characters. Each part may contain quoted strings, as in go syntax. Quoted strings are always considered part of the same word.

Separators are considered part of the preceding word. Every word, with the exception of the last word, will end in a non-empty sequence of whitespace characters The empty part consists of a single empty word.

Any part fulfills the invariant:

words, sep := SplitWords(part)
part == strings.Join(SplitParts(words), "") + sep

Types

type ValidationError

type ValidationError struct {
	Results []ValidationResult

	// message is the message being checked
	Message string
}

ValidationError is returned when a message fails validation. It implements the built-in error interface.

func (ValidationError) Error

func (ve ValidationError) Error() string

type ValidationKind

type ValidationKind string

ValidationKind represents different types of validation errors

const (
	ValidationOK           ValidationKind = ""
	PartIsEmpty            ValidationKind = "part is empty"
	WordIsEmpty            ValidationKind = "word is empty"
	WordIncorrectQuote     ValidationKind = "word not quoted correctly"
	WordNoOutsideDashes    ValidationKind = "word has leading or trailing dashes"
	WordNoSequentialDashes ValidationKind = "word contains sequential dashes"
	WordForbiddenRune      ValidationKind = "word may only contain lower case letters and dashes"
	WordInvalidEnd         ValidationKind = "word must end with a single ' ' or '\n'"
)

type ValidationResult

type ValidationResult struct {
	PartIndex, WordIndex int
	Part, Word           string
	Kind                 ValidationKind
}

func Validate

func Validate(message string, exceptions ...string) (errors []ValidationResult)

Validate validates message and returns all validation errors.

Each message is first split into parts, see SplitParts. Then each part is validated as follows:

• a part (with the exception of the last part) may not be empty (PartIsEmpty)

Furthermore each part is split into words, see SplitWords. Then each word is validated as follows:

• no word may be empty (WordIsEmpty)
• a word may only contain lower case letter (ForbiddenCharacter)
• a word starting with ` and ending with ' is always valid, because it is a quoted word
• a word starting with ` and not ending with ' must be a word quoted in go syntax, and may not have any extra content (WordIncorrectQuote)
• a word may have a leading '(' or a trailing ')', assuming other rules apply accordingly
• a word may contain a trailing comma
• a word may only contain capital letters when all runes in it are capital letters, or if the last letter is an s and the rest are capital.
• a word may consist of only digits when all runes in it are digits
• a word may contain '-'s, but only non-sequential occurrences (WordNoSequentialDashes) that are not the first or last letter (WordNoOutsideDashes)
• a word that starts with '%' is always valid, because it might be a format string
• each word (except for the last word) must end with a space character, that is either " " or "\n" (InvalidEndSpace)

Furthermore, words inside of exceptions are always permitted.

func (ValidationResult) Error

func (v ValidationResult) Error() string