barcodecty

barcode-cty-func

A Go module providing barcode image generation as a go-cty / HCL2 function. Supports 11 barcode formats and returns PNG images as bytes objects.

Backed by github.com/boombuler/barcode.

Installation

go get github.com/tsarna/barcode-cty-func

Usage

import (
    barcodecty "github.com/tsarna/barcode-cty-func"
    "github.com/zclconf/go-cty/cty/function"
)

// Register all functions in an HCL eval context
funcs := barcodecty.GetBarcodeFunctions()
// funcs is map[string]function.Function — merge into your eval context

Functions

barcode(type, data[, options])

Generates a barcode image and returns it as a bytes object with content_type = "image/png".

img = barcode("qr", "https://example.com")
# img.content_type == "image/png"

Barcode Types

Options

The optional third argument is an object. All fields are optional. scale and width are mutually exclusive (both control horizontal sizing). height can be used alone or combined with either scale or width.

Sizing behaviour:

• scale: multiplies the barcode's natural width by the given integer. For 2D codes, height is scaled equally. For 1D codes, height is set to a sensible default (see below). Every module/bar maps to exactly scale pixels wide with no interpolation artefacts.
• height: sets an explicit pixel height. Can be combined with scale (which controls width) or used alone (with default scale = 4 for width).
• width / height: both dimensions set explicitly. Useful when the image must fit a specific pixel budget.
• Neither specified: defaults to scale = 4.

Default 1D barcode height:

1D barcodes have a natural height of only 1 pixel, so the function applies a default height when none is specified:

• Code 128: 20% of the scaled width, producing a proportional barcode regardless of data length.
• All other 1D types: scale * 24 (96px at the default scale of 4).

These defaults can always be overridden with an explicit height option.

Signature declarations

The tables above are what barcode really accepts. Its cty metadata cannot say so: the options object is optional, and the only way cty offers to make an argument optional is to make it variadic — which claims it may be repeated, when it may not — and cty has no way to describe the object's shape, so it is dynamic. Reflected from cty alone the function reads as barcode(type, data, ...options), with all four options invisible.

So externs.cty declares the real signature, as a functy //functy:extern declaration, with the options object spelled out attribute by attribute. The file is never compiled and declares nothing callable; it exists so that help(), generated documentation, and editor tooling can show what the cty metadata cannot.

Externs() returns it as opaque bytes — this package does not import functy and does not parse them:

parser.RegisterExterns(barcodecty.Externs(), barcodecty.ExternsFilename)

A host that is not a functy host can ignore it entirely; the cty Description on the function and every parameter (including the full option list) is still populated.

Examples

QR code with defaults

img = barcode("qr", "https://example.com")

QR code with high error correction and explicit scale

img = barcode("qr", "https://example.com/p?id=${ctx.payload.id}", {
    scale            = 8,
    error_correction = "H",
})

QR code at a fixed pixel size

img = barcode("qr", "https://example.com", {
    width  = 400,
    height = 400,
})

Code 128 label

label = barcode("code128", ctx.payload.tracking_number, {
    scale = 3,
})

1D barcode with explicit height

label = barcode("code39", "ITEM-42", {
    height = 80,
})

EAN-13 for retail product

# data must be exactly 12 digits; check digit is computed and appended
ean = barcode("ean13", ctx.payload.gtin12)

License

BSD 2-Clause