unhtml

README

unhtml

Note: this project was largely built through AI-assisted ("vibe coding") sessions. Every change was reviewed, tested, and understood by a human maintainer before being merged — nothing here is unattended AI output. Test coverage stands at 81.2% of statements as of the latest review.

Reflection-based HTML unmarshalling for Go, built on goquery. Declare a struct with html/attr/conv/opt tags and extract it from a *goquery.Selection the same way encoding/json extracts a struct from JSON.

Install

go get github.com/Ovila98/unhtml

Quick example

package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/PuerkitoBio/goquery"
	"github.com/Ovila98/unhtml"
)

const source = `
<div class="lot">
	<span id="batch-id">B-2024-001</span>
	<h3 class="product">Golden Delicious Apples</h3>
	<a class="details" href="/lots/1001">details</a>
	<span class="owner">Verger de la Colline</span>
</div>
`

type Lot struct {
	ID      string `html:"#batch-id" opt:"required"`
	Product string `html:".product"`
	Link    string `html:"a.details" attr:"href"`
	Owner   string `html:".owner" opt:"default=unknown"`
}

func main() {
	doc, err := goquery.NewDocumentFromReader(strings.NewReader(source))
	if err != nil {
		log.Fatal(err)
	}

	var lot Lot
	if err := unhtml.Unmarshal(doc.Find(".lot"), &lot); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", lot)
}

unhtml handles navigation, selection, extraction, conversion, defaults, and recursion — the consumer only declares what it wants. Scalars, pointers, nested structs, and slices of any of those are all supported; see SPEC.md for the complete tag reference.

Documentation

SPEC.md is the full reference: every html/attr/conv tag, every opt directive (required, default=, empty=, ignore, raw, last, eq=), supported destination types and their conversion priority, structural resolution rules, and error format.

License

Apache License 2.0 — see LICENSE.

Documentation

Overview

Package unhtml provides reflection-based HTML unmarshalling on top of goquery, aiming for an experience similar to json.Unmarshal / xml.Unmarshal but for HTML DOM trees.

A destination struct describes what it wants via struct tags:

type Lot struct {
    ID      string `html:".batch-id" opt:"required"`
    Product string `html:".product"`
}

var lot Lot
err := unhtml.Unmarshal(row, &lot)

Index

• func Unmarshal(sel *goquery.Selection, dest any) error
• type HTMLUnmarshaler

Functions

func Unmarshal

func Unmarshal(sel *goquery.Selection, dest any) error

Unmarshal extracts data from sel into dest according to the struct tags (html, attr, conv, opt) declared on dest's type.

• If dest is a pointer to a struct, sel is treated as the single node to unmarshal fields from.
• If dest is a pointer to a slice (of structs or of struct pointers), one element is produced per node contained in sel.

Types

type HTMLUnmarshaler

type HTMLUnmarshaler interface {
	UnmarshalHTML(raw string) error
}

HTMLUnmarshaler is implemented by types that know how to parse their own extracted text/attribute value. It takes priority over every other conversion, including encoding.TextUnmarshaler.