Documentation
¶
Overview ¶
Package formatter defines the interface for config file formatters.
A Formatter transforms source bytes into a canonically formatted version. Each formatter implementation lives in its own sub-package (e.g., formatter/json, formatter/yaml) and is registered on the filetype.FileType it handles.
Design constraints:
- Stateless: Format may be called concurrently on different files.
- Idempotent: Format(Format(x, opts), opts) == Format(x, opts).
- Comment-preserving: output must contain every comment from the input.
- Consistent output: all formatters report issues using the same message shape so cfv's output looks like one tool, not a patchwork.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsFormatted ¶
IsFormatted reports whether src is already in canonical form. This is a convenience function: it runs Format and compares the result byte-for-byte with the input.
func NormalizeLineEndings ¶
func NormalizeLineEndings(data []byte, ending LineEnding) []byte
NormalizeLineEndings converts line endings in data to the requested style.
LineEndingDefault and LineEndingLF are both treated as LF (no-ops if the input already uses LF). LineEndingCRLF replaces bare \n with \r\n, leaving existing \r\n sequences untouched.
Types ¶
type ErrSkipped ¶
type ErrSkipped struct {
Reason string
}
ErrSkipped indicates the formatter cannot process this file but it is not a syntax error. The file should be reported to the user with the reason but not counted as a failure or formatted.
func (*ErrSkipped) Error ¶
func (e *ErrSkipped) Error() string
Error implements the error interface.
type Formatter ¶
type Formatter interface {
// Format returns the canonically formatted version of src.
// If src is already canonical, Format returns src unchanged (byte-equal).
// Returns an error if src cannot be parsed (unparseable input is not
// a formatting issue — it's a syntax error handled by the validator).
Format(src []byte, opts Options) ([]byte, error)
}
Formatter transforms source bytes into canonically formatted output.
Implementations must be stateless and safe for concurrent use. Implementations must preserve all comments present in the source.
type IndentStyle ¶
type IndentStyle int
IndentStyle selects between spaces and tabs.
const ( // IndentDefault means the formatter uses its own convention. IndentDefault IndentStyle = iota // IndentSpaces uses spaces for indentation. IndentSpaces // IndentTabs uses tabs for indentation. IndentTabs )
type LineEnding ¶
type LineEnding int
LineEnding selects the line terminator.
const ( // LineEndingDefault uses the formatter's convention (typically LF). LineEndingDefault LineEnding = iota // LineEndingLF uses \n. LineEndingLF // LineEndingCRLF uses \r\n. LineEndingCRLF )
type Options ¶
type Options struct {
// IndentStyle selects spaces or tabs. Zero value = format default.
IndentStyle IndentStyle
// IndentWidth is spaces per indent level. Ignored when IndentStyle is Tabs.
// Zero value = format default.
IndentWidth int
// FinalNewline ensures the file ends with exactly one newline.
FinalNewline bool
// LineEnding selects the line terminator for output.
LineEnding LineEnding
// SortKeys sorts object/map keys alphabetically when true.
SortKeys bool
// MaxLineWidth is the target maximum line width. 0 = no limit.
// Formatters use this as a hint, not a hard constraint.
MaxLineWidth int
// QuoteStyle controls quoting of string scalars.
// Only applies to formats with multiple quoting conventions (YAML).
// JSON always uses double quotes per spec; this field is ignored for JSON.
QuoteStyle QuoteStyle
// XMLWhitespaceSensitivity controls XML whitespace handling.
// Ignore: reformat all indentation (default for config files).
// Preserve: only modify existing indentation, never insert newlines.
XMLWhitespaceSensitivity XMLWhitespace
// XMLSelfClosingSpace adds a space before /> in self-closing tags.
// true: <br /> ; false: <br/>
XMLSelfClosingSpace bool
}
Options controls formatting behavior. Each formatter uses the fields that apply to its format and ignores the rest. Zero values mean "use the format-specific default."
Options are resolved by the CLI before being passed to a formatter:
CLI flags > .cfv.toml [format.<type>] > .cfv.toml [format] > .editorconfig > hardcoded defaults
func DefaultFormatOptions ¶
func DefaultFormatOptions() Options
DefaultFormatOptions returns the global default formatting options. These are overridden by .cfv.toml [format] settings and per-format overrides in .cfv.toml [format.<type>].
Zero values mean "use the format-specific default," so this only sets options that have a universal reasonable default.
func LoadFixtureOptions ¶
LoadFixtureOptions reads a JSON sidecar file to override formatting options. The file maps Options field names to values. Zero-value fields in the JSON are left at their default from baseOpts.
Example opts.json:
{"IndentStyle": 2, "IndentWidth": 4}
IndentStyle values: 0=IndentDefault, 1=IndentSpaces, 2=IndentTabs LineEnding values: 0=LineEndingDefault, 1=LineEndingLF, 2=LineEndingCRLF
If the file does not exist, baseOpts is returned unchanged.
type QuoteStyle ¶
type QuoteStyle int
QuoteStyle controls string scalar quoting.
const ( // QuotePreserve keeps the original quoting style from the source. QuotePreserve QuoteStyle = iota // QuoteDouble forces double-quoted strings. QuoteDouble // QuoteSingle forces single-quoted strings. QuoteSingle )
type XMLWhitespace ¶
type XMLWhitespace int
XMLWhitespace controls XML whitespace sensitivity.
const ( // XMLWhitespaceIgnore treats all whitespace as insignificant. // The formatter inserts newlines and indentation freely. // Default for config files (POM, .csproj, plist). XMLWhitespaceIgnore XMLWhitespace = iota // XMLWhitespacePreserve only modifies existing indentation. // Never inserts or removes newlines. Safe for XHTML/SVG. XMLWhitespacePreserve )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package envfmt provides a Formatter for .env files.
|
Package envfmt provides a Formatter for .env files. |
|
Package hclfmt provides a Formatter for HCL (HashiCorp Configuration Language) files.
|
Package hclfmt provides a Formatter for HCL (HashiCorp Configuration Language) files. |
|
Package inifmt provides a Formatter for INI files.
|
Package inifmt provides a Formatter for INI files. |
|
Package jsoncfmt provides a Formatter for JSONC (JSON with Comments) files.
|
Package jsoncfmt provides a Formatter for JSONC (JSON with Comments) files. |
|
Package jsonfmt provides a Formatter for JSON files.
|
Package jsonfmt provides a Formatter for JSON files. |
|
Package propfmt provides a Formatter for Java .properties files.
|
Package propfmt provides a Formatter for Java .properties files. |
|
Package tomlfmt provides a Formatter for TOML files.
|
Package tomlfmt provides a Formatter for TOML files. |
|
Package xmlfmt provides a Formatter for XML files.
|
Package xmlfmt provides a Formatter for XML files. |
|
Package yamlfmt provides a Formatter for YAML files.
|
Package yamlfmt provides a Formatter for YAML files. |