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 byview/html.gofor 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
- Create
yourmodule.candyourmodule.hin this directory - Create
yourmodule.gowith cgo bindings (seebase64wrap.gofor a minimal example) - Add tests in
yourmodule_test.go - If your C code uses
libmor other system libraries, add#cgo LDFLAGS: -lmin the Go file
Documentation
¶
Index ¶
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.
Variables ¶
This section is empty.
Functions ¶
func ImageDimensions ¶
ImageDimensions returns the width and height of an image without fully decoding pixel data. This is faster than DecodeToPNG when you only need the dimensions (e.g. to calculate terminal row count).
func MarkdownToHTML ¶ added in v0.27.8
MarkdownToHTML converts Markdown bytes to HTML using md4c (C). This is significantly faster than goldmark for large documents.
func WrapBase64 ¶
WrapBase64 wraps base64-encoded data at 76 characters per line with \r\n separators, as required by MIME (RFC 2045).
Types ¶
type HTMLElement ¶ added in v0.27.8
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 ¶ added in v0.27.8
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 ¶
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. Uses stb_image for decoding and stb_image_write for PNG encoding in C, which is faster than Go's image stdlib for large images.
Source Files
Directories