format

Documentation

Overview

Package format holds what the commands share when rendering API results: the --format enum they render in, and the text helpers themselves — storage-XHTML to Markdown conversion, search highlight-marker stripping and indentation.

Nothing here is part of an edit round-trip. A page body that will be written back is read from and written to a file untouched, so that path stays byte-lossless; the conversions in this package produce output for reading only. ToMarkdown serves both readers of a storage body: `read --markdown`, whose output carries no sidecar and cannot be updated, and comment bodies, which arrive as storage XHTML because the comment endpoints refuse body-format=view.

Index

• func Indent(text, prefix string) string
• func StripHighlightMarkers(s string) string
• type Format
  • func (f *Format) Set(s string) error
  • func (f Format) String() string
  • func (Format) Type() string
  • func (f Format) Validate() error
• type Options
• type PageRef
• type Refs
  • func References(storage string) Refs
• type Result
  • func ToMarkdown(storage string, opts Options) Result

Functions

func Indent

func Indent(text, prefix string) string

Indent prefixes every line of text, leaving blank lines unpadded so no trailing whitespace is emitted.

func StripHighlightMarkers

func StripHighlightMarkers(s string) string

StripHighlightMarkers removes the markers Confluence search wraps around matched terms and decodes the HTML entities that come with them. A value without markers passes through unchanged, so this is safe to apply even if the server stops adding them.

Types

type Format

type Format string

Format is the output format a command renders its result in. It implements pflag.Value, so an unknown --format is rejected while cobra parses the flags: before PreRunE and RunE both, which leaves no hook a command could take over and no way to reach a command body with an unvalidated value.

const (
	Markdown Format = "md"
	JSON     Format = "json"
)

The two accepted --format values.

func (*Format) Set

func (f *Format) Set(s string) error

Set implements pflag.Value. It assigns only after validating, so a typo leaves the receiver — and with it the default the flag was registered with — untouched.

func (Format) String

func (f Format) String() string

func (Format) Type

func (Format) Type() string

Type names the value cobra prints in the --format help line. It reports "string" rather than "format" because that line is part of the agent-facing contract kept in sync with README.md and skills/cflio/SKILL.md.

func (Format) Validate

func (f Format) Validate() error

Validate rejects a Format that is not one of the accepted values. Set is not the only way to build a Format — a conversion from an arbitrary string still type-checks — so the callers that branch on one keep this guard rather than trusting the type.

type Options

type Options struct {
	// UserNames maps an Atlassian account ID to a display name.
	UserNames map[string]string
	// PageURLs maps a link target to the page's URL.
	PageURLs map[PageRef]string
}

Options carries the reference resolution ToMarkdown cannot do itself. The converter is a pure function, so looking a name or a URL up — which needs the API — happens in the command layer and arrives here as data. A zero Options is valid: every reference falls back to what the body already carries.

type PageRef

type PageRef struct {
	SpaceKey string
	Title    string
}

PageRef names a page the way storage links to one: by space key and title, with no page ID anywhere in the body.

type Refs

type Refs struct {
	// AccountIDs are the ri:user targets.
	AccountIDs []string
	// Pages are the ri:page targets. SpaceKey is empty for a link to a page
	// in the same space, which is how storage writes one — and that empty key
	// is what Options.PageURLs has to be keyed by for the lookup to hit.
	Pages []PageRef
}

Refs are the references a body makes that ToMarkdown cannot render without an Options filled in from the API. Both slices are deduplicated and sorted, so the requests a caller builds from them are deterministic.

func References

func References(storage string) Refs

References collects what a caller has to resolve for ToMarkdown to render names and URLs instead of identifiers. It walks for the same ac:link targets link renders, through the same accessor; the kinds worth resolving are listed in collectTarget, which link has to be kept in step with.

Parsing the body twice — once here, once in ToMarkdown — is the price of keeping the converter a pure function. Returning the references from the conversion instead would cost the same parse plus a discarded render, since the resolution has to be in hand before the rendering that uses it.

type Result

type Result struct {
	Markdown string
	// Unsupported names the macros and extensions that became placeholders,
	// deduplicated and sorted; UnsupportedCount counts every occurrence. A
	// reader decides from these whether the rendering can be trusted, without
	// having to read the whole file first.
	Unsupported      []string
	UnsupportedCount int
}

Result is a conversion and what it could not represent.

func ToMarkdown

func ToMarkdown(storage string, opts Options) Result

ToMarkdown converts a storage-format body to Markdown for reading. It never fails: unknown input degrades in structure, never in content, so an element this converter has never seen still yields the text inside it.