comment

Documentation

Overview

Package comment recognises host-language comment syntaxes (#, //, <!-- -->) so directives are found in any text file. Pure.

Index

• type Block
• type Syntax
  • func For(path string) Syntax
  • func (s Syntax) Body(line string) (string, bool)
  • func (s Syntax) Comment(indent, body string) (string, bool)
  • func (s Syntax) Render(line, body string) (string, bool)

Types

type Block

type Block struct {
	Open  string
	Close string
}

Block is a paired block-comment delimiter, e.g. {Open: "<!--", Close: "-->"}.

type Syntax

type Syntax struct {
	Line   []string
	Blocks []Block
}

Syntax is the set of comment delimiters a file format recognises. A format may expose several line markers (HCL uses both # and //) and several block pairs; Syntax.Body returns whichever comment starts earliest on the line.

func For

func For(path string) Syntax

For returns the comment syntax for the file at path, matched by base name first (dotfiles, Makefile), then a Dockerfile/Containerfile prefix, then file extension. An unrecognised file falls back to generic # and // parsing rather than being skipped, so a directive in any text file is still found.

func (Syntax) Body

func (s Syntax) Body(line string) (string, bool)

Body returns the comment text on line and whether one was found. For a line marker it is the text after the marker; for a block it is the text between the open and close delimiters, or everything after the open when the close falls on a later line. The earliest-starting delimiter wins, so `code // note` yields " note".

Matching is byte-literal: clover is line-based and does not parse the host format, so a delimiter sitting inside a string literal is not distinguished from a real comment. The distinctive clover: keyword keeps false positives rare in practice.

func (Syntax) Comment

func (s Syntax) Comment(indent, body string) (string, bool)

Comment builds a fresh comment line carrying body, prefixed by indent, for a file that does not yet have a comment on the line. It uses the syntax's first line marker, falling back to its first block pair for block-only formats (HTML, CSS). ok is false when the syntax exposes no delimiter at all. Spacing matches Syntax.Render: a single space after the opening marker (and before a block's close), so a synthesized comment is byte-identical to a rendered one.

func (Syntax) Render

func (s Syntax) Render(line, body string) (string, bool)

Render returns line with the body of its earliest comment replaced by body, preserving the text before the comment and the delimiters, and normalising spacing to a single space after the opening marker (and before a block's closing marker). ok is false when line carries no comment. It is the inverse of Syntax.Body, used by format mode to rewrite a canonicalised directive back onto its line.