Runtime symbols

Piko compiles template expressions to Go. In interpreted mode (dev-i), Pipit executes that code using its standard-library symbol tables and Piko runtime symbols from wdk/interp/interp_piko_symbols.

The package manifests are pipit-symbols-stdlib.yaml and piko-symbols-runtime.yaml. Local project packages can also compile from source. Registered native packages take precedence over source compilation.

Standard-library packages

The table below lists standard-library packages commonly used in templates. Pipit's standard-library manifest lists the full set. Expressions use package-qualified names such as 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 fast-path instantiations chosen at vendoring time. Calls with other element types fall back to slower reflection-based implementations where Pipit provides an implementation. Other calls need a non-generic equivalent such as sort.Slice.

slices

Element types: string, int, int8, int16, int32, int64, uint, uint8 (byte), uint16, uint32, uint64, float32, float64, bool.

FunctionElement types
slices.BinarySearchall the above except bool
slices.Compareall the above except bool
slices.IsSortedall the above except bool
slices.Maxall the above except bool
slices.Minall the above except bool
slices.Sortall the above except bool

maps

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

cmp

Element types: string, int, int8, int16, int32, int64, uint, uint8 (byte), uint16, uint32, uint64, float32, float64.

Piko runtime packages

The Piko tree vendors the following packages into wdk/interp/interp_piko_symbols.

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

(*SSRServer).WithSymbols registers native package symbols before Run. Each map entry associates an import path with its exported names and reflection values.

import (
    "reflect"

    "piko.sh/piko"
    "piko.sh/piko/wdk/interp/interp_provider_pipit"

    "myapp/util"
)

func main() {
    server := piko.New()
    server.WithInterpreterProvider(interp_provider_pipit.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. Interpreted mode requires a provider, while additional symbols are optional. Compiled dev and prod builds resolve the same identifiers at compile time.

piko extract generate produces symbol tables from piko-symbols.yaml. Its default output package, internal/piko_symbols, exports the map as piko_symbols.Symbols. See how to run interpreted mode for discovery, generation, and registration steps.

See also