Documentation
¶
Overview ¶
Package encoder turns a data string into a Matrix of modules.
Encoders are registered by name in an init function and looked up through the registry, never through a switch statement in a caller. Adding a symbology is therefore one new file plus one Register call.
Every encoder also publishes Capabilities, which is what /v1/symbologies serves. Capabilities are honest about a given build: a symbology that needs the optional zint linkage registers itself as unavailable with a reason rather than disappearing from the list.
Index ¶
Constants ¶
const ( // EAN13 is the registry name of the EAN-13 encoder. EAN13 = "ean13" // EAN8 is the registry name of the EAN-8 encoder. EAN8 = "ean8" // UPCA is the registry name of the UPC-A encoder. UPCA = "upca" // UPCE is the registry name of the UPC-E encoder. UPCE = "upce" )
Registry names of the EAN/UPC retail symbologies.
const ( // ITF is the registry name of Interleaved 2 of 5. ITF = "itf" // ITF14 is the registry name of the fixed-length GS1 shipping variant. ITF14 = "itf14" // TwoOfFive is the registry name of Standard (non-interleaved) 2 of 5. TwoOfFive = "2of5" )
Registry names of the two-of-five family.
const Aztec = "aztec"
Aztec is the registry name of the Aztec Code encoder.
const Codabar = "codabar"
Codabar is the registry name of the Codabar encoder.
const Code128 = "code128"
Code128 is the registry name of the Code 128 encoder.
const Code39 = "code39"
Code39 is the registry name of the Code 39 encoder.
const Code93 = "code93"
Code93 is the registry name of the Code 93 encoder.
const DataMatrix = "datamatrix"
DataMatrix is the registry name of the Data Matrix encoder.
const PDF417 = "pdf417"
PDF417 is the registry name of the PDF417 encoder.
const QR = "qr"
QR is the registry name of the QR Code encoder.
Variables ¶
var ( // ErrUnknownSymbology means no encoder is registered under that name. ErrUnknownSymbology = errors.New("unknown symbology") // build. Capabilities.Reason explains what is missing. ErrUnavailable = errors.New("symbology unavailable in this build") // ErrDataTooLong means the payload exceeds what the symbology can carry. ErrDataTooLong = errors.New("data too long for this symbology") // ErrInvalidData means the payload violates the symbology's alphabet, // length, or check-digit rules. ErrInvalidData = errors.New("data invalid for this symbology") // ErrUnsupportedOption means the option is meaningful in general but not // honoured by this encoder. ErrUnsupportedOption = errors.New("option not supported by this symbology") )
Sentinel errors. The HTTP layer maps these onto stable error codes, so a caller can switch on the code rather than on message text.
Functions ¶
func Names ¶
func Names() []string
Names lists every registered symbology, available or not, sorted.
func Register ¶
func Register(e Encoder)
Register adds an encoder under its own name. It panics on a duplicate, because two encoders claiming one symbology is a programming error that must surface at startup rather than resolve arbitrarily.
Register is intended for init functions.
func RegisterUnavailable ¶
func RegisterUnavailable(caps Capabilities)
RegisterUnavailable records a symbology that this build cannot encode, so that /v1/symbologies lists it with an explanation instead of omitting it. The optional zint-backed symbologies register through here in the default build.
Types ¶
type Capabilities ¶
type Capabilities struct {
// Name is the registry key, e.g. "qr".
Name string `json:"name"`
// Title is the human-readable name, e.g. "QR Code".
Title string `json:"title"`
// Kind is 1d or 2d.
Kind Kind `json:"kind"`
// Available reports whether this build can actually encode it.
Available bool `json:"available"`
// Reason explains an Available:false, e.g. "requires full build".
Reason string `json:"reason,omitempty"`
// ECCLevels lists accepted error-correction levels, strongest last.
ECCLevels []string `json:"ecc_levels,omitempty"`
// Charset describes the accepted alphabet in prose.
Charset string `json:"charset"`
// MaxLength is the largest payload in characters, 0 when unbounded in
// practice or when the limit depends on the character mix.
MaxLength int `json:"max_length,omitempty"`
// FixedLengths lists the exact input lengths accepted, if the symbology
// requires one. Empty means variable length.
FixedLengths []int `json:"fixed_lengths,omitempty"`
// QuietZone is the margin the specification requires, in modules.
QuietZone int `json:"quiet_zone"`
// HRI reports whether human-readable text is normally printed with the
// code.
HRI bool `json:"hri"`
// Notes records build-specific limitations, e.g. an option this encoder
// accepts only in its automatic form.
Notes string `json:"notes,omitempty"`
}
Capabilities describes what a symbology accepts, for /v1/symbologies and for pre-flight validation.
func All ¶
func All() []Capabilities
All returns the capabilities of every registered symbology, sorted by name. It backs GET /v1/symbologies, which must be honest about what this particular build can do.
type EncodeOpts ¶
type EncodeOpts struct {
// ECC is the error-correction level. Empty means the symbology default.
ECC string
// Version pins the symbology version or size. Zero means automatic.
Version int
// Mask pins the data-mask pattern. Negative means automatic; the zero
// value is normalised to automatic by Normalise.
Mask int
// QuietZone overrides the specified margin, in modules. Negative means
// use the symbology default.
QuietZone int
}
EncodeOpts are the symbology-level options for a single encode.
The zero value asks for every automatic default, which is what a caller who supplies no encode options gets.
func AutoEncodeOpts ¶
func AutoEncodeOpts() EncodeOpts
AutoEncodeOpts returns EncodeOpts with every field set to its automatic value. Callers building options from a request should start here so that "unset" is distinguishable from "explicitly zero".
type Encoder ¶
type Encoder interface {
// Name is the registry key.
Name() string
// Caps describes what this encoder accepts.
Caps() Capabilities
// Encode produces the module grid, without a quiet zone. The quiet zone
// is applied by the renderer so that style can widen it.
Encode(data string, o EncodeOpts) (Matrix, error)
}
Encoder converts a data string into a module Matrix.
Implementations must be safe for concurrent use: they are shared across all requests and must hold no per-encode state.
type Kind ¶
type Kind string
Kind distinguishes linear symbologies from two-dimensional ones. It drives rendering: a 1D matrix is one module tall and is extruded to a bar height, and may carry human-readable interpretation text beneath the bars.
type Matrix ¶
type Matrix struct {
// Cols and Rows are the grid dimensions in modules.
Cols, Rows int
// Symbology is the encoder that produced this grid.
Symbology string
// Kind distinguishes 1D from 2D, which changes how it is rendered.
Kind Kind
// QuietZone is the margin this symbology specifies, in modules.
QuietZone int
// HRI is the human-readable interpretation text printed beneath a linear
// code. Empty for 2D symbologies and when the caller suppressed it.
HRI string
// contains filtered or unexported fields
}
Matrix is the module grid produced by an Encoder.
A module is the smallest unit of a code: one square for a 2D symbology, one bar-width column for a linear one. The grid excludes the quiet zone, which the renderer applies, and carries no pixel dimensions — sizing is a render and output concern.
For a linear symbology Rows is 1: the single row of bars is extruded to the requested bar height at render time.
func (Matrix) At ¶
At reports whether the module at (x, y) is dark. Coordinates outside the grid read as light, which lets renderers walk a padded area without bounds-checking every access.
func (Matrix) Dark ¶
Dark counts the dark modules. It backs the scannability heuristics, which care about the light-to-dark balance of a rendered code.
func (Matrix) Modules ¶
Modules returns the grid in row-major order. The slice aliases the matrix; callers must not modify it.
Source Files