collate

Documentation

Overview

Package collate is a provider-only collation engine: it compares strings using glibc's locale-aware strcoll_l, reached over dlopen/dlsym rather than cgo. It exists to give agent tooling a faithful, deterministic ISO-8859-1 collation order without linking libc and without shelling out.

Scope, on purpose

This package is a LIBRARY. It wires to no applet, registers no verb, and is deliberately narrow: it accepts ONLY the two explicit ISO-8859-1 locale aliases (see Open). Everything else — the "C" locale, a bare "de_DE" with no codeset, "de_DE.UTF-8", ISO-8859-15/"Latin-9", and arbitrary names — is rejected up front, before any libc is loaded, with ErrUnsupportedLocale. The narrow surface is the safety story: the only code path that ever reaches glibc has already been proven to name a single-byte Latin-1 locale.

The real provider is built only on linux/amd64 and linux/arm64 (collate_glibc.go). Every other platform gets a stub (collate_stub.go) whose Open returns ErrUnsupportedPlatform after the same locale validation, so callers get one consistent, honest contract everywhere.

Third-party provenance

The dlopen/dlsym FFI is provided by github.com/ebitengine/purego (v0.10.0), upstream https://github.com/ebitengine/purego, Apache-2.0 licensed. purego is used directly — no cgo — via purego.Dlopen/Dlsym/RegisterFunc. See THIRD_PARTY_LICENSES.md.

Index

• Variables
• type Provider
  • func Open(name string) (*Provider, error)
  • func (p *Provider) Close() error
  • func (p *Provider) Compare(a, b string) (int, error)

Variables

var (
	// ErrUnsupportedPlatform is returned by Open on any platform other than
	// linux/amd64 and linux/arm64, where no glibc provider is built.
	ErrUnsupportedPlatform = errors.New("collate: glibc collation provider is only built for linux/amd64 and linux/arm64")

	// ErrUnsupportedLocale is returned when the requested locale name is not one
	// of the two accepted ISO-8859-1 aliases. Reported BEFORE any libc is loaded.
	ErrUnsupportedLocale = errors.New("collate: unsupported locale; only the ISO-8859-1 aliases \"de_DE.ISO-8859-1\" and \"de_DE.iso88591\" are accepted")

	// ErrGlibcUnavailable is returned when libc.so.6 cannot be loaded, or the
	// loaded C library is not glibc (honest detection via gnu_get_libc_version),
	// or a required symbol is missing.
	ErrGlibcUnavailable = errors.New("collate: glibc runtime not detected")

	// ErrMissingLocale is returned when glibc is present but the requested locale
	// data is not installed (newlocale failed).
	ErrMissingLocale = errors.New("collate: locale data is not installed")

	// ErrInitFailure is returned when glibc newlocale fails due to ENOMEM or other initialization failure.
	ErrInitFailure = errors.New("collate: initialization failure")

	// ErrCodeset is returned when the opened locale's CODESET is not ISO-8859-1,
	// which would mean the byte-oriented Compare contract does not hold.
	ErrCodeset = errors.New("collate: locale codeset is not ISO-8859-1")

	// ErrNulInput is returned by Compare when either operand contains a NUL byte,
	// which a C string cannot represent unambiguously.
	ErrNulInput = errors.New("collate: input contains a NUL byte")

	// ErrClosed is returned by Compare after the provider has been closed.
	ErrClosed = errors.New("collate: provider is closed")
)

Sentinel errors. These are platform-independent so callers can switch on them identically on Linux and on the stub platforms.

Types

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider compares strings in a glibc ISO-8859-1 locale via strcoll_l.

It holds two independent locale_t handles — one carrying LC_COLLATE (used by strcoll_l) and one carrying LC_CTYPE (used to read and verify CODESET). A RWMutex fences concurrent Compare calls against Close; Close is idempotent.

func Open

func Open(name string) (*Provider, error)

Open returns a Provider for one of the accepted ISO-8859-1 locale aliases.

The locale name is validated before any libc is touched; an unaccepted name returns ErrUnsupportedLocale. It then requires glibc (ErrGlibcUnavailable if absent), the locale data to be installed (ErrMissingLocale), and the locale's CODESET to be exactly ISO-8859-1 (ErrCodeset). The caller owns the returned Provider and must Close it.

func (*Provider) Close

func (p *Provider) Close() error

Close frees the provider's locale_t handles. It is safe to call more than once and safe against concurrent Compare calls: the write lock waits for in-flight comparisons to finish, and the closed flag stops later ones deterministically.

func (*Provider) Compare

func (p *Provider) Compare(a, b string) (int, error)

Compare returns -1, 0, or +1 as a sorts before, equal to, or after b under the provider's LC_COLLATE order. The operands must be ISO-8859-1 (single-byte) encoded, matching the locale's codeset. A NUL byte in either operand returns ErrNulInput; a closed provider returns ErrClosed.