Documentation
¶
Overview ¶
Package document provides structured document I/O for YAML and JSON files. It encapsulates the read-deserialize and serialize-write patterns used throughout the codebase, with consistent error wrapping, permission modes, directory creation, and format detection.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Read ¶
Read deserializes a structured document from a reader. YAML decoding is used unconditionally since JSON is a valid subset of YAML.
Type Parameters:
- T: the target type for deserialization
Parameters:
- r: the reader to read from
Returns:
- *T: pointer to the deserialized value
- error: wraps read and parse errors
func ReadFile ¶
ReadFile deserializes a structured document from disk. Format is inferred from the file extension: .json → JSON, .yaml/.yml/anything else → YAML.
Type Parameters:
- T: the target type for deserialization
Parameters:
- path: filesystem path to the document
Returns:
- *T: pointer to the deserialized value
- error: wraps both I/O and parse errors with the file path for context
func Write ¶
Write serializes v to a stream in the given Format — the codec alone, owning no file creation.
The seam the write side was missing (#558): Read separates codec from I/O and Write now mirrors it, so creation concerns (permissions, directories) stay with whoever owns the destination. WithPerm is meaningless here and is ignored; it belongs to WriteFile.
Parameters:
- `w`: the stream to write the rendered document to.
- `format`: the Format to render; JSON or YAML.
- `v`: the value to serialize.
- `opts`: optional configuration (WithIndent, WithHeader).
Returns:
- `error`: an unknown format, a marshal error, or a stream write error.
func WriteFile ¶
WriteFile serializes v to disk as a structured document. Format is inferred from the file extension. Creates parent directories (0o750) if needed. Default file permission is 0o600; override with WithPerm.
The rename of the former path-only Write, freeing that name for the stream form — the same Read / ReadFile symmetry the read side always had (#558).
Parameters:
- `path`: filesystem path for the output document.
- `v`: the value to serialize.
- `opts`: optional configuration (WithPerm, WithIndent, WithHeader).
Returns:
- `error`: wraps marshal, directory creation, and write errors with the file path for context.
Types ¶
type Format ¶
type Format string
Format names a rendering the codec produces.
The stream form (Write) takes it explicitly — with no file name there is nothing to infer from, and the output syntax is not an option but a decision (the same rule op.SaveGraph follows: format is stated). The path form (WriteFile) infers it from the file extension as a convenience at the file boundary only.
type Option ¶
type Option func(*writeOpts)
Option configures write behavior.
func WithHeader ¶
WithHeader prepends a literal string before the serialized content. A trailing newline is appended if not present.
Parameters:
- header: text to prepend (e.g., a generated-file comment or disclaimer)
Returns:
- Option: a write option that sets the header
func WithIndent ¶
WithIndent controls JSON indentation. Ignored for YAML. Default is 2-space indent with no prefix.
Parameters:
- prefix: prefix string prepended to each line (typically empty)
- indent: indent string used for each level of nesting
Returns:
- Option: a write option that sets JSON indentation
Source Files