runtime

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var DefaultBufferSize = 4 * 1024 // 4KB

DefaultBufferSize is the default size of buffers. It is set to 4KB by default, which is the same as the default buffer size of bufio.Writer.

View Source
var ErrInvalidStyleAttributeFunctionSignature = errors.New("invalid function signature, should be in the form func() (string, error)")
View Source
var TemplUnsupportedStyleAttributeValue = "zTemplUnsupportedStyleAttributeValue:Invalid;"

TemplUnsupportedStyleAttributeValue is the default value returned for unsupported types.

View Source
var TemplateExtensions = []string{".ghtmx", ".htmx"}

TemplateExtensions are the extensions a project may write templates with, most canonical first. It mirrors config.TemplateExtensions, which this package cannot import: NFR-012 keeps everything an application links standard-library only. TestRuntimeTemplateExtensionsMatchConfig fails if the two drift.

Functions

func AppendTrigger

func AppendTrigger(w http.ResponseWriter, name string, payload any) error

AppendTrigger merges one event into the response's HX-Trigger header, serialized for htmx 2.x: a comma-separated name list while every event is payload-less, upgraded to a JSON object ({"name": payload, ...}) as soon as any payload is involved. Multiple emissions in one response accumulate into a single header; re-emitting an event name replaces its payload in place. Event firing order in htmx follows the JSON key order, so insertion order is preserved.

Call AppendTrigger before writing the response status or body: headers set afterwards are silently discarded by net/http. It reads and rewrites the header map, so it is not safe for concurrent use on the same response. Serialized values are escaped to ASCII (\uXXXX) because HTTP header values cannot carry non-ASCII bytes reliably.

AppendTrigger is plumbing for the generated per-event emitters (FR-037): calling it directly with an ad-hoc name forfeits the declared event contract — the compiler can neither check the name nor type the payload. Do not use it in application code.

func AppendTriggerAfterSettle

func AppendTriggerAfterSettle(w http.ResponseWriter, name string, payload any) error

AppendTriggerAfterSettle merges one event into HX-Trigger-After-Settle: htmx fires it after the settle step. Same contract as AppendTrigger.

func AppendTriggerAfterSwap

func AppendTriggerAfterSwap(w http.ResponseWriter, name string, payload any) error

AppendTriggerAfterSwap merges one event into HX-Trigger-After-Swap: htmx fires it after the swap step. Same contract as AppendTrigger.

func GeneratedFragment

func GeneratedFragment(f func(GeneratedComponentInput) error) ghtmx.Fragment

GeneratedFragment creates a ghtmx.Fragment from a generated standalone fragment wrapper. Render and RenderFragment are the same function: a standalone wrapper executes only the fragment body, so there is no page output to strip (FR-031).

func GeneratedTemplate

func GeneratedTemplate(f func(GeneratedComponentInput) error) ghtmx.Component

GeneratedTemplate is used to avoid generated code needing to import the `context` and `io` packages.

func GetBuilder

func GetBuilder() (sb strings.Builder)

GetBuilder returns a strings.Builder.

func GetDevModeTextFileName

func GetDevModeTextFileName(templFileName string) string

GetDevModeTextFileName returns the sidecar path holding a template's string literals, keyed by a hash of the template's own path.

Both sides of dev-mode hot reload must agree on that path. The writer (the generator) knows the real template name; the reader is generated code that knows only its own _ghtmx.go path, so it has to recover the template name from it. Appending the canonical extension unconditionally made a .htmx project hash two different paths on the two sides, and hot reload simply stopped finding its file.

The extension is project configuration this package cannot read, so the file on disk is the signal: dev mode runs against the source tree by construction. With no template found the canonical extension still applies, which is exactly the previous behaviour.

func ReleaseAcquiredBuffer added in v0.1.16

func ReleaseAcquiredBuffer(b *Buffer, existing bool, err *error)

ReleaseAcquiredBuffer is the deferred half of a generated render function's buffer prologue, taking GetBuffer's two results and a pointer to the render's named error return:

ghtmxBuffer, ghtmxExisting := ghtmxruntime.GetBuffer(w)
defer ghtmxruntime.ReleaseAcquiredBuffer(ghtmxBuffer, ghtmxExisting, &err)

existing reports that the writer was already a buffer, which means it belongs to an outer component: this call then does nothing, and that component releases it. Otherwise the buffer is drained and returned to the pool, and a flush failure becomes the render's error — but only when the render itself succeeded, so a render error is never overwritten.

It is a plain function rather than a closure returned alongside the buffer so the generated defer keeps a statically-known callee: the compiler open-codes it onto the stack, where a deferred func value would cost an allocation on every component render (NFR-002 holds allocation counts exactly).

func ReleaseBuffer

func ReleaseBuffer(w io.Writer) (err error)

ReleaseBuffer drains the buffer into its underlying writer and returns it to the pool. It deliberately does not invoke the underlying http.Flusher: an implicit end-of-render flush would commit the response headers and force chunked transfer encoding — header effects the handler never requested (FR-034, FR-090). Streaming flushes stay explicit via the ghtmx.Flush() component.

func SanitizeStyleAttributeValues

func SanitizeStyleAttributeValues(values ...any) (string, error)

SanitizeStyleAttributeValues renders a style attribute value. The supported types are: - string - ghtmx.SafeCSS - map[string]string - map[string]ghtmx.SafeCSSProperty - ghtmx.KeyValue[string, string] - A map of key/values where the key is the CSS property name and the value is the CSS property value. - ghtmx.KeyValue[string, ghtmx.SafeCSSProperty] - A map of key/values where the key is the CSS property name and the value is the CSS property value. - ghtmx.KeyValue[string, bool] - The bool determines whether the value should be included. - ghtmx.KeyValue[ghtmx.SafeCSS, bool] - The bool determines whether the value should be included. - func() (anyOfTheAboveTypes) - func() (anyOfTheAboveTypes, error) - []anyOfTheAboveTypes

In the above, ghtmx.SafeCSS and ghtmx.SafeCSSProperty are types that are used to indicate that the value is safe to render as CSS without sanitization. All other types are sanitized before rendering.

If an error is returned by any function, or a non-nil error is included in the input, the error is returned.

func ScriptContentInsideStringLiteral

func ScriptContentInsideStringLiteral[T any](v T, errs ...error) (string, error)

func ScriptContentOutsideStringLiteral

func ScriptContentOutsideStringLiteral[T any](v T, errs ...error) (string, error)

func WriteString

func WriteString(w io.Writer, index int, s string) (err error)

WriteString writes the string to the writer. If development mode is enabled s is replaced with the string at the index in the _ghtmx.txt file.

Types

type Buffer

type Buffer struct {
	Underlying io.Writer
	// contains filtered or unexported fields
}

Buffer is a wrapper around bufio.Writer that enables flushing and closing of the underlying writer.

func GetBuffer

func GetBuffer(w io.Writer) (b *Buffer, existing bool)

GetBuffer creates and returns a new buffer if the writer is not already a buffer, or returns the existing buffer if it is.

func (*Buffer) Close

func (b *Buffer) Close() error

Close closes the buffer and the underlying io.Writer if it implements io.Closer.

func (*Buffer) Flush

func (b *Buffer) Flush() error

Flush writes any buffered data to the underlying io.Writer and calls the Flush method of the underlying http.Flusher if it implements it, committing the HTTP response. Only the explicit ghtmx.Flush() streaming component reaches this; end-of-render release uses ReleaseBuffer, which drains without the http.Flusher cascade.

func (*Buffer) Reset

func (b *Buffer) Reset(w io.Writer)

Reset sets the underlying io.Writer to w and resets the buffer.

func (*Buffer) Size

func (b *Buffer) Size() int

Size returns the size of the underlying buffer in bytes.

func (*Buffer) Write

func (b *Buffer) Write(p []byte) (n int, err error)

Write the contents of p into the buffer.

func (*Buffer) WriteString

func (b *Buffer) WriteString(s string) (n int, err error)

WriteString writes the contents of s into the buffer.

type GeneratedComponentInput

type GeneratedComponentInput struct {
	Context context.Context
	Writer  io.Writer
}

GeneratedComponentInput is used to avoid generated code needing to import the `context` and `io` packages.

type StringLoader

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

func NewStringLoader

func NewStringLoader(devModeWatchRootPath string) (sl *StringLoader)

func (*StringLoader) GetWatchedString

func (sl *StringLoader) GetWatchedString(templFilePath string, index int, defaultValue string) (string, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL