Runtime symbols

Piko's template expression language compiles to Go. The expressions have access to a curated subset of Go's standard library plus the piko runtime packages. This page enumerates the packages vendored into the bytecode interpreter. Source of truth: piko-symbols.yaml (stdlib) and piko-symbols-runtime.yaml (Piko packages).

Standard-library packages

The following Go standard library packages are available as-is. Call them with the usual package-qualified syntax: strings.ToUpper(state.Name).

PackageTypical uses in templates
bytesByte-slice manipulation.
contextContext values (rarely used inside templates directly).
encoding/base64Encode or decode base64.
encoding/jsonMarshal into inline JSON-LD.
errorsCheck for specific error types.
fmtSprintf and friends for formatted output.
htmlHTML escaping beyond what interpolation already provides.
ioReader/writer interfaces (rarely used).
mathArithmetic helpers (Ceil, Floor, Abs, etc.).
osEnvironment access.
pathURL and file path manipulation.
regexpRegex matching and replacement.
sortSort slices in place.
strconvString-to-number and number-to-string conversions.
stringsString manipulation (Contains, Split, ToUpper, etc.).
syncConcurrency primitives (rarely used inside templates).
timetime.Now(), duration parsing, formatting.

Generic packages

Generic packages expose a fixed set of instantiations chosen at vendoring time. Call sites that need other element types fall back to non-generic equivalents (for example sort.Slice).

slices

Element types: string, int, int64, float64, byte, bool.

FunctionElement types
slices.BinarySearchstring, int, int64, float64, byte
slices.Comparestring, int, int64, float64, byte
slices.IsSortedstring, int, int64, float64, byte
slices.Maxstring, int, int64, float64, byte
slices.Minstring, int, int64, float64, byte
slices.Sortstring, int, int64, float64, byte

maps

Key types: string, int. Value types: string, int, float64, bool, any.

cmp

Element types: string, int, int64, float64, byte.

Piko runtime packages

The Piko tree vendors the following packages.

piko.sh/piko

Top-level Piko types and helpers. Carries the build tag !js - excluded from WebAssembly targets where the server runtime is unavailable. See:

piko.sh/piko/wdk/binder

Form, JSON, and map binding into typed Go structs. Each entry point takes a context, a destination pointer, and the source payload.

SymbolSignature
binder.BindBind(ctx, dest any, src map[string][]string, opts ...Option) error - bind URL/form values.
binder.BindMapBindMap(ctx, dest any, src map[string]any, opts ...Option) error - bind a generic map.
binder.BindJSONBindJSON(ctx, dest any, src []byte, opts ...Option) error - bind a JSON payload.
binder.IgnoreUnknownKeys, binder.WithMaxSliceSize, binder.WithMaxPathDepth, binder.WithMaxPathLength, binder.WithMaxFieldCount, binder.WithMaxValueLengthPer-call Option constructors.
binder.RegisterConverter, binder.SetMaxFormFields, and related helpersProcess-wide configuration. Call once at bootstrap.

piko.sh/piko/wdk/logger

Structured logging via log/slog. The package exposes context helpers and attribute constructors. Retrieve the logger from context instead of calling logger.Info(...) directly.

SymbolPurpose
logger.From(ctx, fallback)Returns the logger stored on ctx, falling back to fallback.
logger.WithLogger(ctx, log)Stores a logger on ctx for downstream retrieval.
logger.MustFrom(ctx)Like From, but panics if no logger is present.
logger.GetLogger(name)Retrieves a named package/component logger.
logger.String, logger.Int, logger.Int64, logger.Uint64, logger.Float64, logger.Bool, logger.Time, logger.Duration, logger.Error, logger.Field, logger.StringsAttribute constructors for structured fields.
logger.LevelTrace, logger.LevelDebug, logger.LevelInfo, logger.LevelNotice, logger.LevelWarn, logger.LevelErrorLevel constants.
logger.AddPrettyOutput, logger.AddJSONOutput, logger.AddFileOutput, logger.WithLevel, logger.WithJSON, logger.WithNoColourOutput configuration.

Typical use inside a template script block:

ctx, log := logger.From(r.Context(), logger.GetLogger("page"))
log.Info("rendering", logger.String("path", r.URL.Path))

piko.sh/piko/wdk/runtime

Runtime collection, section, navigation, and search helpers. The package mirrors the top-level piko.* collection symbols for use inside generated code and interpreted scripts. See Collections API reference for the full surface.

Common entry points: GetData[T], GetSections, GetSectionsTree, GetAllCollectionItems, BuildNavigationFromMetadata, SearchCollection, QuickSearch, FetchCollection, RegisterRuntimeProvider, Filter/FilterGroup/SortOption/PaginationOptions and the FilterOp* / Sort* constants.

piko.sh/piko/wdk/safeconv

Saturating numeric conversions plus boolean and string parsers. The package exposes around 30 typed conversions (for example IntToUint8, Int64ToInt32), their Must* panicking variants, and the generic ToUint64[T integer]. See safeconv API reference for the full list.

Register custom symbols

Extend interpreted mode (dev-i) with project-specific symbols. Register them on the server before calling Run:

import (
    "reflect"

    "piko.sh/piko"
    pikointerp "piko.sh/piko/wdk/interp/interp_provider_piko"

    "myapp/util"
)

func main() {
    server := piko.New()
    server.WithInterpreterProvider(pikointerp.NewProvider())

    server.WithSymbols(map[string]map[string]reflect.Value{
        "myapp/util": {
            "FormatPrice": reflect.ValueOf(util.FormatPrice),
            "Currency":    reflect.ValueOf((*util.Currency)(nil)),
        },
    })

    // server.Run(actions, piko.RunModeDevInterpreted)
}

WithSymbols and WithInterpreterProvider are methods on *SSRServer (not options to piko.New). The dev-i interpreter consults them only. Compiled dev/prod builds resolve the same identifiers at compile time.

See also