docs

📚 Comparator Documentation

Welcome to the full documentation for the comparator package — a dependency-free Go library for deep comparison and rich diffing of arbitrary Go values.

Everything here is built on the Go standard library only. If you are just getting started, read the guides in order; otherwise jump straight to the topic you need.

🗂️ Table of Contents

Guide	What it covers
Getting Started	Installation, your first comparison, and the core types.
Configuration & Options	Every functional option, its default, and when to use it.
Diffing	DiffResult, Difference, diff modes, and how to read a diff.
Output Formats	Text (with color), JSON, Markdown, HTML, unified diff, and visual tree.
JSON Patch	Generating and applying RFC 6902 patch documents.
Custom Comparators	Custom equality, plus the Equatable/Comparable interfaces.
Extensibility	Generics, streaming reporters, context, and pluggable formatters.
Testing	AssertEqual and friends for use in test suites.
Performance	Benchmarks, cost model, and tuning tips.
FAQ	Common questions, gotchas, and thread-safety.

⚡ Quick Links

• Package reference: pkg.go.dev/github.com/slashdevops/comparator
• Runnable examples: comparator_examples_test.go, comparator_api_examples_test.go, and comparator_options_examples_test.go
• Source: comparator.go

🧭 Mental Model

The package exposes two layers:

1. Equality — the Comparator interface answers a single question: are these two values equal under this configuration?
2. Diffing — the DiffComparer interface answers a richer question: how exactly do these two values differ, and how do I present that?

Both are configured with the same set of functional options, so you learn the options once and reuse them everywhere.