clib

README

clib

C implementations of performance-critical operations, integrated via cgo.

Why C?

Some operations in Matcha benefit from dropping into C for speed and lower memory usage. The biggest wins are in image dimension queries (30,000x faster than Go's stdlib) and base64 wrapping for large attachments (3-4x faster).

Components

base64wrap

MIME-compliant base64 line-wrapping (RFC 2045). Wraps base64-encoded strings at 76 characters with \r\n separators. Used by sender/ for every attachment, inline image, and S/MIME signature.

Files: base64wrap.c, base64wrap.h, base64wrap.go

imgconv

Image decoding and PNG re-encoding using stb_image (vendored single-header C libraries). No external system dependencies required.

• DecodeToPNG() — decodes any image format (JPEG, PNG, BMP, GIF) and re-encodes to PNG. Used by view/html.go for inline email images.
• ImageDimensions() — reads image width and height from the header only, without decoding pixel data. Used to calculate terminal row spacing for inline images.

Files: imgconv.c, imgconv.h, imgconv.go, stb_image.h, stb_image_write.h

htmlconv

Single-pass HTML-to-structured-elements parser. Takes raw HTML and returns a slice of HTMLElement values representing headings, links, images, blockquotes, tables, and text. Used by the email view to render HTML emails in the terminal without a full DOM.

• HTMLToElements() — parses HTML into structured elements with type, text, and up to two attributes (e.g., href/src, alt/cite).

Files: htmlconv.c, htmlconv.h, htmlconv.go

markdown

Markdown-to-HTML conversion using md4c (vendored). Supports GitHub-flavored features: tables, strikethrough, task lists, and permissive autolinks.

• MarkdownToHTML() — converts Markdown bytes to HTML bytes.

Files: md4c.c, md4c.h, md4c-html.c, md4c-html.h, markdown.go

Pure Go fallbacks

Every function has a _nocgo.go counterpart (build tag !cgo) that provides the same API using pure Go libraries:

C implementation	Go fallback
base64wrap.go	Manual string builder
imgconv.go (stb_image)	image/png, image/jpeg, image/gif
htmlconv.go	goquery DOM parsing
markdown.go (md4c)	goldmark

Adding new C code

1. Create yourmodule.c and yourmodule.h in this directory
2. Create yourmodule.go with cgo bindings (see base64wrap.go for a minimal example)
3. Add tests in yourmodule_test.go
4. If your C code uses libm or other system libraries, add #cgo LDFLAGS: -lm in the Go file

Documentation

Index

• Constants
• func ImageDimensions(data []byte) (width, height int, ok bool)
• func MarkdownToHTML(md []byte) []byte
• func WrapBase64(data string) string
• type HTMLElement
  • func HTMLToElements(html string) ([]HTMLElement, bool)
• type ImageConvertResult
  • func DecodeToPNG(data []byte) (ImageConvertResult, bool)

Constants

const (
	HElemText       = 0
	HElemH1         = 1
	HElemH2         = 2
	HElemLink       = 3
	HElemImage      = 4
	HElemBlockquote = 5
	HElemTable      = 6
)

HTMLElementType constants mirror the C enum values in htmlconv.h.

Functions

func ImageDimensions

func ImageDimensions(data []byte) (width, height int, ok bool)

ImageDimensions returns the width and height of an image without fully decoding pixel data. This is the pure Go fallback — it must fully decode the image since Go's stdlib does not support header-only reads.

func MarkdownToHTML

func MarkdownToHTML(md []byte) []byte

MarkdownToHTML converts Markdown bytes to HTML using md4c (C). This is significantly faster than goldmark for large documents.

func WrapBase64

func WrapBase64(data string) string

WrapBase64 wraps base64-encoded data at 76 characters per line with \r\n separators, as required by MIME (RFC 2045).

Types

type HTMLElement

type HTMLElement struct {
	Type  int
	Text  string // Text content
	Attr1 string // href (link), src (image), cite (blockquote)
	Attr2 string // alt (image), prev_text (blockquote)
}

HTMLElement represents a parsed element from an HTML document.

func HTMLToElements

func HTMLToElements(html string) ([]HTMLElement, bool)

HTMLToElements parses HTML and returns structured elements. This is a single-pass C parser that replaces goquery-based DOM parsing.

type ImageConvertResult

type ImageConvertResult struct {
	PNGData []byte
	Width   int
	Height  int
}

ImageConvertResult holds the output of DecodeToPNG.

func DecodeToPNG

func DecodeToPNG(data []byte) (ImageConvertResult, bool)

DecodeToPNG takes raw image bytes (JPEG, PNG, BMP, GIF, etc.) and returns PNG-encoded bytes along with image dimensions. This is the pure Go fallback used when cgo is not available.