mdpatch

Documentation

Overview

Package mdpatch replaces HTML-comment marker blocks in Markdown files and normalizes line endings for documentation snapshot workflows.

Index

• Variables
• func NormalizeEOL(data []byte, mode EOLMode) []byte
• func PatchBytes(original, replacement []byte, marker string, opts PatchOptions) ([]byte, error)
• func PatchMarkdownFile(path string, out []byte, marker string, opts PatchOptions) error
• func ValidateMarker(marker string) error
• type EOLMode
  • func ParseEOLMode(s string) (EOLMode, error)
• type Fence
  • func ParseFence(s string) (Fence, error)
• type PatchOptions

Examples

• NormalizeEOL
• PatchBytes
• PatchMarkdownFile

Variables

var (
	// ErrMarkerNotFound indicates that a complete marker block was not found.
	ErrMarkerNotFound = errors.New("marker block not found")
	// ErrDuplicateMarker indicates that a marker line occurs more than once.
	ErrDuplicateMarker = errors.New("duplicate marker")
	// ErrInvalidMarker indicates that a marker name cannot be represented safely.
	ErrInvalidMarker = errors.New("invalid marker")
	// ErrInvalidFence indicates that a fence language tag is invalid.
	ErrInvalidFence = errors.New("invalid fence")
)

Functions

func NormalizeEOL

func NormalizeEOL(data []byte, mode EOLMode) []byte

NormalizeEOL applies the given line-ending normalization to data. EOLNone returns data unchanged.

Example

package main

import (
	"fmt"

	"github.com/apstndb/ptyhelp/mdpatch"
)

func main() {
	fmt.Printf("%q\n", mdpatch.NormalizeEOL([]byte("one\r\ntwo\n"), mdpatch.EOLCRLF))
}

Output:
"one\r\ntwo\r\n"

func PatchBytes

func PatchBytes(original, replacement []byte, marker string, opts PatchOptions) ([]byte, error)

PatchBytes returns original after replacing the marker block with replacement, without performing file I/O.

Example

package main

import (
	"fmt"

	"github.com/apstndb/ptyhelp/mdpatch"
)

func main() {
	original := []byte("<!-- help begin -->\nold\n<!-- help end -->\n")
	patched, err := mdpatch.PatchBytes(original, []byte("new\n"), "help", mdpatch.PatchOptions{
		Fence: mdpatch.FenceNone,
	})
	if err != nil {
		panic(err)
	}
	fmt.Print(string(patched))
}

Output:
<!-- help begin -->
new
<!-- help end -->

func PatchMarkdownFile

func PatchMarkdownFile(path string, out []byte, marker string, opts PatchOptions) error

PatchMarkdownFile replaces the lines strictly between <!-- marker begin --> and <!-- marker end --> with fenced or raw content per opts.Fence.

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/apstndb/ptyhelp/mdpatch"
)

func main() {
	dir, err := os.MkdirTemp("", "mdpatch-example-")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(dir)

	path := filepath.Join(dir, "README.md")
	if err := os.WriteFile(path, []byte("<!-- help begin -->\nold\n<!-- help end -->\n"), 0o644); err != nil {
		panic(err)
	}
	if err := mdpatch.PatchMarkdownFile(path, []byte("usage\n"), "help", mdpatch.PatchOptions{}); err != nil {
		panic(err)
	}
	patched, err := os.ReadFile(path)
	if err != nil {
		panic(err)
	}
	fmt.Print(string(patched))
}

Output:
<!-- help begin -->
```text
usage
```
<!-- help end -->

func ValidateMarker

func ValidateMarker(marker string) error

ValidateMarker checks that marker is safe to embed in HTML comment markers.

Types

type EOLMode

type EOLMode int

EOLMode represents a line-ending normalization mode.

const (
	// EOLNone leaves line endings unchanged except where patch logic applies its own rules.
	EOLNone EOLMode = iota
	// EOLLF normalizes all line endings to LF.
	EOLLF
	// EOLCRLF normalizes all line endings to CRLF.
	EOLCRLF
)

func ParseEOLMode

func ParseEOLMode(s string) (EOLMode, error)

ParseEOLMode parses a string into an EOLMode. Valid values are "none", "lf", and "crlf" (case-sensitive).

type Fence

type Fence string

Fence controls fenced-code wrapping. Its zero value is FenceText.

const (
	// FenceText emits a fenced code block tagged as text.
	FenceText Fence = "text"
	// FenceNone emits replacement content without a fenced code block.
	FenceNone Fence = "none"
)

func ParseFence

func ParseFence(s string) (Fence, error)

ParseFence parses -fence values: text, none, or a language tag.

type PatchOptions

type PatchOptions struct {
	EOL   EOLMode
	Fence Fence
}

PatchOptions configures marker-block replacement.