Package hff

import "github.com/ornew/hff"

Generated from this checkout's Go source. Released versions are also on pkg.go.dev.

Overview

Package hff defines the values and contracts shared by Human-Friendly Filter compilers, local evaluators, and backend translators.

Applications usually configure an engine with a schema and capabilities, compile a query into a Program, then pass that Program to a backend Build function. Compilation produces a reusable, immutable typed plan; it does not construct an evaluator or execute a database query. This separation lets a service select local matching, SQL translation, or another backend without paying for an unused execution path.

Values represent explicit HFF data. Use Int and Float to retain numeric subtypes, Null for an explicit null, and Object/List for owned collections. The zero Value is invalid. A missing object key differs from a present key containing Null; Lookup's boolean result exposes that distinction. Value accessors return an ok flag instead of coercing an incompatible type.

Types describe the input contract. The schema package provides field helpers for assembling structs, lists, maps, unions, optional fields, and nullable fields. ValidateInput creates an Input whose exact schema can be reused by multiple filters; this is separate from compiling a query against that schema.

Program and Node expose the read-only typed IR for backend authors. Programs are created by engine compilation, not by manually assembling nodes. An IR retains null tests, guards, method resolution, callback bindings, and source spans so a backend can preserve HFF semantics or reject unsupported operations.

Errors report configuration, compilation, input, and execution failures. Ordinary null results are data and do not become execution errors. Profiles describe backend support and guarantees; they do not grant capability policy or prove that a caller-owned database satisfies a declared storage contract.

Index

Constants

Source

const (
	// ConfigurationError indicates invalid host configuration or API arguments.
	ConfigurationError	= core.ConfigurationError
	// SyntaxError indicates a malformed HFF query.
	SyntaxError	= core.SyntaxError
	// TypeError indicates a query value or operation violates the schema types.
	TypeError	= core.TypeError
	// CapabilityError indicates the query requires a denied or missing permission.
	CapabilityError	= core.CapabilityError
	// BackendError indicates a backend cannot implement a valid compiled program.
	BackendError	= core.BackendError
	// InputError indicates a record is invalid or incompatible with its schema.
	InputError	= core.InputError
	// LimitError indicates a configured finite resource limit was exceeded.
	LimitError	= core.LimitError
	// CancelledError indicates a context cancellation or deadline.
	CancelledError	= core.CancelledError
)

Source

const (
	// PropagateNull skips the extension invocation when the receiver or any
	// evaluated argument is null, returning null. This is the zero/default policy.
	PropagateNull	= core.PropagateNull
	// InvokeNull permits dispatch for null receivers or arguments only when the
	// corresponding declared type admits NullType. It does not turn no-value into
	// a Value or invoke the callback for no-value.
	InvokeNull	= core.InvokeNull
)

Source

const (
	InvalidNode	= plan.InvalidNode
	MatchAllNode	= plan.MatchAllNode
	LiteralNode	= plan.LiteralNode
	VariableNode	= plan.VariableNode
	ParameterNode	= plan.ParameterNode
	FieldNode	= plan.FieldNode
	IndexNode	= plan.IndexNode
	GuardNode	= plan.GuardNode
	NullTestNode	= plan.NullTestNode
	BinaryNode	= plan.BinaryNode
	NegateNode	= plan.NegateNode
	BoolNode	= plan.BoolNode
	AndNode		= plan.AndNode
	OrNode		= plan.OrNode
	NotNode		= plan.NotNode
	ListNode	= plan.ListNode
	ObjectNode	= plan.ObjectNode
	CallNode	= plan.CallNode
	CallbackNode	= plan.CallbackNode
	TypeGuardNode	= plan.TypeGuardNode
	Equal		= plan.Equal
	NotEqual	= plan.NotEqual
	Less		= plan.Less
	LessEqual	= plan.LessEqual
	Greater		= plan.Greater
	GreaterEqual	= plan.GreaterEqual
	Match		= plan.Match
	NotMatch	= plan.NotMatch
	Add		= plan.Add
	Subtract	= plan.Subtract
	Multiply	= plan.Multiply
	Divide		= plan.Divide
	Remainder	= plan.Remainder
)

Node and operator constants are stable IR discriminants. Append new values; do not renumber or reuse existing values.

Source

const (
	// InvalidType is the zero and invalid descriptor kind.
	InvalidType	= core.InvalidType
	// NullType is the explicit null value type.
	NullType	= core.NullType
	// BoolType is the Boolean value type.
	BoolType	= core.BoolType
	// IntType is the signed int64 value type.
	IntType	= core.IntType
	// FloatType is the finite float64 value type.
	FloatType	= core.FloatType
	// StringType is the UTF-8 string value type.
	StringType	= core.StringType
	// BytesType is the byte-sequence value type.
	BytesType	= core.BytesType
	// ListType is an ordered sequence with one declared element type.
	ListType	= core.ListType
	// StructType is a fixed-key object with declared fields.
	StructType	= core.StructType
	// MapType is an object whose keys share one declared value type.
	MapType	= core.MapType
	// TimestampType is an instant with nanosecond precision.
	TimestampType	= core.TimestampType
	// DurationType is a signed duration with nanosecond precision.
	DurationType	= core.DurationType
	// AnyType accepts any valid HFF value.
	AnyType	= core.AnyType
	// NeverType has no values and is used for compiler analysis.
	NeverType	= core.NeverType
	// UnionType accepts a value belonging to any listed member type.
	UnionType	= core.UnionType
	// FunctionType describes callback functions in compiled plans.
	FunctionType	= core.FunctionType
)

Source

const (
	// InvalidKind is the invalid zero Value representation.
	InvalidKind	= core.InvalidKind
	// NullKind is explicit HFF null.
	NullKind	= core.NullKind
	// BoolKind is a Boolean value.
	BoolKind	= core.BoolKind
	// IntKind is a signed int64 value.
	IntKind	= core.IntKind
	// FloatKind is a finite float64 value.
	FloatKind	= core.FloatKind
	// StringKind is a valid UTF-8 string value.
	StringKind	= core.StringKind
	// BytesKind is a byte sequence.
	BytesKind	= core.BytesKind
	// ListKind is an ordered list of HFF values.
	ListKind	= core.ListKind
	// ObjectKind is a string-keyed object of HFF values.
	ObjectKind	= core.ObjectKind
	// TimestampKind is a timestamp value.
	TimestampKind	= core.TimestampKind
	// DurationKind is a duration value.
	DurationKind	= core.DurationKind
)

Types

type Binding

Source

type Binding plan.Binding

Binding describes a lexically scoped callback parameter or capture. A nested callback may capture an outer binding; names can be shadowed, so use ID for identity within the Program.

func (Binding) ID

Source

func (b Binding) ID() BindingID

ID returns the binding identity, scoped to one Program. Do not persist it as a cross-program identifier; an invalid zero Binding has ID zero.

func (Binding) Name

Source

func (b Binding) Name() string

Name returns the callback parameter or capture name, or an empty string for an invalid zero Binding.

func (Binding) Type

Source

func (b Binding) Type() Type

Type returns the binding's resolved type descriptor. Invalid bindings return the invalid zero Type.

type BindingID

Source

type BindingID = plan.BindingID

BindingID identifies a callback parameter or capture within one Program. IDs are lexical plan-local handles and cannot be compared across Programs.

This alias exposes the following definition and methods.

type BindingID uint64

BindingID is unique within one Program, including nested and shadowed bindings. Zero is invalid; IDs from different programs cannot be compared meaningfully.

type CompatibilityVersion

Source

type CompatibilityVersion struct{ Component, Version string }

CompatibilityVersion names a known implementation or caller-supplied data version. A missing component is unknown; a backend must not infer a database version it cannot inspect.

type Diagnostics

Source

type Diagnostics = core.Diagnostics

Diagnostics groups independent source errors. Use errors.As for individual *Error values and Errors to obtain a defensive copy of the members.

This alias exposes the following definition and methods.

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

Diagnostics groups independent failures. Unwrap preserves errors.As for each typed Error and errors.Is for causes. It never represents a usable program.

func (*Diagnostics) Error

Source

func (d *Diagnostics) Error() string

func (*Diagnostics) Errors

Source

func (d *Diagnostics) Errors() []error

func (*Diagnostics) Unwrap

Source

func (d *Diagnostics) Unwrap() []error

type Error

Source

type Error = core.Error

Error is the typed failure returned by the API. Inspect Code rather than parsing Message text. Path identifies an input location; Span, Line, and Column identify query source when available. Span is a half-open byte range; Line and Column are one-based, with columns counted in Unicode code points. Cause supports errors.Is.

This alias exposes the following definition and methods.

type Error struct {
	Code		ErrorCode
	Path		Path
	Message		string
	Cause		error
	Span		*Span
	Line, Column	int
}

Error supports errors.As; Cause supports errors.Is for context cancellation.

func (*Error) Error

Source

func (e *Error) Error() string

func (*Error) Unwrap

Source

func (e *Error) Unwrap() error

type ErrorCode

Source

type ErrorCode = core.ErrorCode

ErrorCode classifies a configuration, syntax, type, capability, backend, input, limit, or cancellation failure. A completed false match is not an error.

This alias exposes the following definition and methods.

type ErrorCode string

ErrorCode identifies a host-level failure, never a completed false match.

type FeatureSupport

Source

type FeatureSupport struct {
	// ID is the capability or feature identifier being described.
	ID	capabilities.ID
	// Level is the support status; an omitted entry remains unknown.
	Level	SupportLevel
	// Conditions explains requirements when Level is Conditional.
	Conditions	string
}

FeatureSupport records the backend's status for one capability ID. This is not permission to compile that feature; the engine's capabilities policy is configured separately.

type Field

Source

type Field struct {
	// Name is the exact HFF object key.
	Name	string
	// Type is the required value type when the field is present.
	Type	Type
	// Optional permits the key to be absent; it does not permit explicit null.
	Optional	bool
}

Field describes one exact object key in a struct type. Optional marks the field as absence-capable without adding NullType. Add NullType to Type to permit a present null value; input validation also accepts absence for a nullable field. The flag and value type remain distinct parts of the schema.

type GuaranteeID

Source

type GuaranteeID string

GuaranteeID names one affirmative backend guarantee. Absence means only that the profile does not assert the guarantee; it does not claim the opposite.

Source

const (
	// InputValidationGuarantee means the backend validates host input records.
	InputValidationGuarantee	GuaranteeID	= "input-validation"
	// EvaluationOrderGuarantee means evaluation follows HFF's left-to-right order.
	EvaluationOrderGuarantee	GuaranteeID	= "left-to-right-evaluation"
	// CancellationGuarantee means the backend honors cancellation at documented checkpoints.
	CancellationGuarantee	GuaranteeID	= "context-cancellation"
	// StepBudgetGuarantee means the backend enforces its runtime step ceiling.
	StepBudgetGuarantee	GuaranteeID	= "step-budget"
	// GeneratedValuesGuarantee means the backend enforces its generated-value ceiling.
	GeneratedValuesGuarantee	GuaranteeID	= "generated-values-budget"
	// JSONDepthGuarantee means the backend enforces its JSON depth ceiling.
	JSONDepthGuarantee	GuaranteeID	= "json-depth-budget"
)

type Input

Source

type Input core.Input

Input is an immutable record validated against one exact schema. Its zero value is invalid; use ValidateInput or the engine package's Validate method to construct it. Backends can reuse it with MatchInput when schemas match.

func ValidateInput

Source

func ValidateInput(ctx context.Context, schema Type, value Value, config ValidationConfig) (Input, error)

ValidateInput checks the complete value for valid HFF representations, input budgets, and compatibility with schema. It returns no partial Input on error; cancellation, limit failures, and configuration errors remain typed errors. A nil context or invalid schema is a configuration error. Zero input limits select finite defaults; set config.Unlimited to disable input depth/value ceilings explicitly. This check visits the whole record, even if a later filter reads only a few fields.

Example

{
	typ := schema.Struct(schema.Int("age"))
	record := hff.Object(map[string]hff.Value{"age": hff.Int(25)})
	input, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	if err != nil {
		panic(err)
	}
	fmt.Println("same schema:", input.Compatible(typ))
	fmt.Println("different numeric type:", input.Compatible(schema.Struct(schema.Float("age"))))

}
Complete runnable example
package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	typ := schema.Struct(schema.Int("age"))
	record := hff.Object(map[string]hff.Value{"age": hff.Int(25)})
	input, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	if err != nil {
		panic(err)
	}
	fmt.Println("same schema:", input.Compatible(typ))
	fmt.Println("different numeric type:", input.Compatible(schema.Struct(schema.Float("age"))))
}

Output:

same schema: true
different numeric type: false

func (Input) Compatible

Source

func (i Input) Compatible(t Type) bool

Compatible reports whether i is valid and was validated against a schema structurally equal to t. It does not widen unions, infer compatibility, or convert values; invalid zero inputs and schemas return false.

func (Input) Schema

Source

func (i Input) Schema() Type

Schema returns the exact schema contract used to validate this input. On an invalid zero Input it returns the invalid zero Type.

func (Input) Value

Source

func (i Input) Value() Value

Value returns the immutable value held by a validated input. On an invalid zero Input it returns the invalid zero Value.

type Kind

Source

type Kind = core.Kind

Kind identifies a value's exact representation. InvalidKind is not null: use Null to create explicit HFF null, and use input validation to reject an invalid zero Value.

This alias exposes the following definition and methods.

type Kind uint8

Kind identifies a value's exact representation. InvalidKind is not null.

func (Kind) String

Source

func (k Kind) String() string

type Limits

Source

type Limits = core.Limits

Limits contains per-stage resource ceilings; it does not itself disable limits or configure every stage at once. APIs apply only their relevant fields. Compile fields are MaxQueryBytes (source bytes), MaxSyntaxDepth, MaxCallbackDepth, and MaxCompileSteps. Input fields are MaxInputDepth and MaxInputValues. Runtime fields are MaxSteps, MaxGeneratedValues, and MaxJSONDepth. Zero fields resolve to finite values returned by DefaultLimits; negative fields are invalid. For example, ValidateInput reads MaxInputDepth and MaxInputValues, while local evaluation reads runtime fields. Use an explicit unlimited option where an API provides one; leaving fields at zero selects defaults rather than unlimited work.

func DefaultLimits

Source

func DefaultLimits() Limits

DefaultLimits returns HFF's current finite values for all limit fields. An API may use only the fields belonging to its stage; consult that API's configuration documentation before changing them.

This alias exposes the following definition and methods.

type Limits struct {
	MaxQueryBytes	int
	MaxSyntaxDepth	int
	// MaxCallbackDepth counts lexically nested callbacks, starting at one.
	MaxCallbackDepth	int
	// MaxCompileSteps bounds common compiler work, independently of evaluation.
	MaxCompileSteps	int
	MaxInputDepth	int
	MaxInputValues	int
	// MaxJSONDepth bounds local JSON parsing and serialization; the root is depth one.
	MaxJSONDepth	int
	// MaxSteps and MaxGeneratedValues are local evaluator budgets. SQL translation
	// does not promise to enforce these budgets in the database.
	MaxSteps		int
	MaxGeneratedValues	int
}

Limits are per-operation ceilings. Zero selects a finite default. Unlimited mode is an explicit engine option, not a negative or zero number.

func (Limits) Resolve

Source

func (l Limits) Resolve() (Limits, error)

type Method

Source

type Method plan.Method

Method lists the applicable signatures of a resolved method call. It is IR metadata, not a callable extension implementation.

func (Method) Name

Source

func (m Method) Name() string

Name returns the resolved method call name, or an empty string when m is an invalid zero Method.

func (Method) Signatures

Source

func (m Method) Signatures() []Signature

Signatures returns a defensive copy of the signatures that compile-time resolution found applicable to this call. The result describes dispatch choices; it does not contain backend function pointers. An invalid zero Method returns an empty slice.

type MethodConfig

Source

type MethodConfig struct {
	// ID is the stable extension identity suffix, for example "service.lookup.v1".
	// Capabilities.Method(ID) creates its permission ID; keep ID stable across
	// engine and backend configuration.
	ID	string
	// Name is the ASCII method identifier used in query calls. Receiver types may
	// distinguish overloads, but declarations must not create ambiguous overloads.
	Name	string
	// Receiver is the type accepted by the implementation. Calls with an
	// incompatible receiver fail during compilation rather than being coerced.
	Receiver	Type
	// Parameters are required positional argument types, in query argument
	// order. Values are type-checked; this declaration performs no conversion.
	Parameters	[]Type
	// Optional are trailing positional argument types; callers cannot skip them.
	Optional	[]Type
	// Variadic is the repeated trailing type, or the zero Type when absent.
	Variadic	Type
	// Result is the declared result type. An ordinary Null result
	// is also always allowed as a data failure, regardless of this type.
	Result	Type
	// NullPolicy controls invocation when receiver or arguments are null. The
	// zero value, PropagateNull, skips invocation and returns null.
	NullPolicy	NullPolicy
	// BaseCost is the positive local step charge applied before each call.
	BaseCost	int
}

MethodConfig declares one extension signature shared by engine compilation and backend registration. Parameters are required positional arguments, followed by trailing Optional arguments and then repeated Variadic arguments. Optional positions cannot be skipped to reach Variadic. A zero Variadic means no repeated argument. BaseCost must be positive and is charged for each local callback invocation; backends validate implementation registration separately.

type MethodDeclaration

Source

type MethodDeclaration core.MethodDeclaration

MethodDeclaration is the immutable, backend-independent extension signature. Its zero value is invalid. Install declarations in engine configuration to type-check calls and select their capabilities; register matching executable implementations separately with a backend Build configuration.

func NewMethodDeclaration

Source

func NewMethodDeclaration(c MethodConfig) (MethodDeclaration, error)

NewMethodDeclaration validates and copies a method signature declaration. Invalid types, IDs, names, parameter ordering, null policy, or costs return a ConfigurationError. The returned declaration does not register an implementation or grant its capability.

func (MethodDeclaration) BaseCost

Source

func (d MethodDeclaration) BaseCost() int

BaseCost returns the positive per-invocation local step charge, or zero for an invalid declaration.

func (MethodDeclaration) Equal

Source

func (d MethodDeclaration) Equal(other MethodDeclaration) bool

Equal reports whether two valid declarations have identical IDs, types, argument positions, null policy, and base cost. It is useful when Build verifies that a registered implementation still matches the engine's declaration; invalid zero declarations compare false.

func (MethodDeclaration) ID

Source

func (d MethodDeclaration) ID() string

ID returns the stable extension ID used for capability checks and dispatch, or an empty string for an invalid zero declaration.

func (MethodDeclaration) MaxArgs

Source

func (d MethodDeclaration) MaxArgs() int

MaxArgs returns the maximum positional argument count, or -1 when Variadic makes the signature unbounded. An invalid declaration returns its zero value.

func (MethodDeclaration) MinArgs

Source

func (d MethodDeclaration) MinArgs() int

MinArgs returns the minimum positional argument count, including all required parameters but not optional or variadic arguments. An invalid declaration returns zero.

func (MethodDeclaration) Name

Source

func (d MethodDeclaration) Name() string

Name returns the HFF call name, without its type-family prefix, or an empty string for an invalid zero declaration.

func (MethodDeclaration) NullPolicy

Source

func (d MethodDeclaration) NullPolicy() NullPolicy

NullPolicy returns the configured null dispatch policy. An invalid zero declaration reports PropagateNull, the zero/default policy.

func (MethodDeclaration) Optional

Source

func (d MethodDeclaration) Optional() []Type

Optional returns a defensive copy of trailing optional parameter types. These positions are positional and cannot be omitted while supplying a later variadic argument.

func (MethodDeclaration) Parameter

Source

func (d MethodDeclaration) Parameter(i int) (Type, bool)

Parameter returns the type accepted at zero-based argument position i, including optional and repeated variadic positions. The bool is false for a negative index, an out-of-range position, or an invalid declaration.

func (MethodDeclaration) Parameters

Source

func (d MethodDeclaration) Parameters() []Type

Parameters returns a defensive copy of required positional parameter types.

func (MethodDeclaration) Receiver

Source

func (d MethodDeclaration) Receiver() Type

Receiver returns the immutable receiver type descriptor by value. The zero declaration returns an invalid Type.

func (MethodDeclaration) Result

Source

func (d MethodDeclaration) Result() Type

Result returns the successful result type descriptor. Null remains an allowed callback result even when this type is non-nullable.

func (MethodDeclaration) Valid

Source

func (d MethodDeclaration) Valid() bool

Valid reports whether d is a successfully constructed declaration rather than its zero value.

func (MethodDeclaration) Variadic

Source

func (d MethodDeclaration) Variadic() Type

Variadic returns the repeated trailing parameter type, or an invalid Type.

type Node

Source

type Node plan.Node

Node is an opaque immutable semantic node. Its zero value is invalid. Children are in source evaluation order. Child and payload accessors return false for invalid indices, invalid nodes, or inapplicable payloads; returned slices are copies. Use Kind before reading kind-specific payloads.

func (Node) Binding

Source

func (n Node) Binding() (Binding, bool)

Binding returns the referenced lexical binding and true for a ParameterNode or a VariableNode that names a callback binding. Input-root paths and other node kinds return false.

func (Node) Captures

Source

func (n Node) Captures() ([]Binding, bool)

Captures returns callback captures as a defensive copy and true only for CallbackNode. Captures refer to lexical bindings outside that callback.

func (Node) Child

Source

func (n Node) Child(i int) (Node, bool)

Child returns child i and false when i is outside the child range.

func (Node) ChildCount

Source

func (n Node) ChildCount() int

ChildCount returns the number of children in source evaluation order. An invalid node has no children and returns zero.

func (Node) Constraint

Source

func (n Node) Constraint() (Type, bool)

Constraint returns the declared runtime type test and true only for TypeGuardNode. The node's resolved Type may be narrower when the input schema already provides more information.

func (Node) Field

Source

func (n Node) Field() (string, bool)

Field returns the immediate literal field name and true only when n is a FieldNode. Empty names and names containing dots are returned unchanged.

func (Node) Keys

Source

func (n Node) Keys() ([]string, bool)

Keys returns a copy of the object-entry keys aligned by index with ObjectNode children. It returns true for an object literal, including one with no entries, and false for other kinds or an invalid node.

func (Node) Kind

Source

func (n Node) Kind() NodeKind

Kind returns the semantic operation represented by n, or InvalidNode for an invalid zero Node.

func (Node) Literal

Source

func (n Node) Literal() (Value, bool)

Literal returns an explicit literal payload, including an explicit Null, and true only for LiteralNode. It returns an invalid zero Value and false for other node kinds or an invalid node.

func (Node) MayNoValue

Source

func (n Node) MayNoValue() bool

MayNoValue reports whether n can produce the internal no-value state, such as when a postfix guard finds a missing or mismatched path. No-value is not an HFF Value and propagates through evaluation. An invalid Node reports false.

func (Node) Method

Source

func (n Node) Method() (Method, bool)

Method returns the resolved method payload and true only for CallNode.

func (Node) Operator

Source

func (n Node) Operator() (Operator, bool)

Operator returns the operation payload for binary and null-test nodes. The bool is false for other node kinds or an invalid node.

func (Node) Parameters

Source

func (n Node) Parameters() ([]Binding, bool)

Parameters returns callback parameters as a defensive copy and true only for CallbackNode. The bool distinguishes an empty parameter list from an inapplicable accessor.

func (Node) Path

Source

func (n Node) Path() ([]string, bool)

Path returns a copy of the static path from the Program's input root when n is a variable or field chain rooted there. Callback-local variables, dynamic indexing, and other node kinds have no such path and return false. Empty literal path components are preserved. A path with no components is not returned as a payload.

func (Node) Span

Source

func (n Node) Span() Span

Span returns n's half-open UTF-8 byte range in Program.Source. An invalid Node returns the zero Span.

func (Node) Type

Source

func (n Node) Type() Type

Type returns the statically resolved result type of n. A runtime type guard can narrow it relative to the original schema; an invalid Node returns the invalid zero Type.

func (Node) Valid

Source

func (n Node) Valid() bool

Valid reports whether n is a compiler-created node rather than its zero value.

type NodeKind

Source

type NodeKind = plan.NodeKind

NodeKind identifies a semantic operation in the typed IR, independent from parser productions. Use it to select the applicable Node payload accessor.

This alias exposes the following definition and methods.

type NodeKind uint8

func (NodeKind) String

Source

func (k NodeKind) String() string

type NullPolicy

Source

type NullPolicy = core.NullPolicy

NullPolicy controls whether an extension callback runs when its receiver or an argument evaluates to explicit null. No-value always propagates without invoking an extension.

This alias exposes the following definition and methods.

type NullPolicy uint8

NullPolicy controls whether a declared method observes ordinary null.

type Operator

Source

type Operator = plan.Operator

Operator identifies arithmetic, comparison, and explicit null-test operations. It is meaningful only for node kinds that carry an operator.

This alias exposes the following definition and methods.

type Operator string

type Path

Source

type Path = core.Path

Path is a sequence of literal field or index labels. Components are not split on dots; for example, []string{"service.name"} is one field.

This alias exposes the following definition and methods.

type Path []string

Path is a sequence of literal names, not a dot-separated identifier.

type Profile

Source

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

Profile is an immutable snapshot of known backend facts and effective configuration. Inspect it for compatibility reporting; Build remains authoritative for a specific program, mapping, and configuration. A zero Profile is invalid.

func NewProfile

Source

func NewProfile(config ProfileConfig) (Profile, error)

NewProfile validates and snapshots a profile. It rejects an empty backend name, invalid or duplicate entries, invalid declarations, and negative limits with a ConfigurationError. Slice and limit-pointer changes made by the caller after construction do not affect the Profile. For example, omit a feature to leave it unknown rather than claiming support: 

profile, err := hff.NewProfile(hff.ProfileConfig{
    Backend: "local",
    Features: []hff.FeatureSupport{{ID: capabilities.Access, Level: hff.Supported}},
})
if err != nil { return err }
if access, ok := profile.Feature(capabilities.Access); ok { _ = access.Level }

func (Profile) Backend

Source

func (p Profile) Backend() string

Backend returns the declared backend name, or an empty string for an invalid zero Profile.

func (Profile) Capabilities

Source

func (p Profile) Capabilities() capabilities.Set

Capabilities returns the declared service policy. Its zero value is unspecified and does not mean all capabilities are allowed; use capabilities.Set.Specified to distinguish it from an explicit empty policy.

func (Profile) CompileLimits

Source

func (p Profile) CompileLimits() (Limits, bool)

CompileLimits reports query-byte, syntax-depth, callback-depth, and compilation-work ceilings. The bool is false when no stage limits were declared; a true result with zero applicable fields means explicitly unbounded. Other stage fields are not applicable.

func (Profile) Details

Source

func (p Profile) Details() []ProfileDetail

Details returns a defensive copy of backend-specific descriptive values. Details have no built-in interpretation and grant no capability.

func (Profile) Feature

Source

func (p Profile) Feature(id capabilities.ID) (FeatureSupport, bool)

Feature looks up a declared feature. The bool is false when the ID has no entry, which means support is unknown. When true, inspect Level and, for Conditional, Conditions; the result does not replace Build validation.

func (Profile) Features

Source

func (p Profile) Features() []FeatureSupport

Features returns a defensive copy of declared feature statuses. Omitted feature IDs remain unknown; changing the returned slice cannot change p.

func (Profile) Guarantees

Source

func (p Profile) Guarantees() []GuaranteeID

Guarantees returns a defensive copy of affirmative guarantees. An absent ID is not an assertion that the backend violates it.

func (Profile) HasGuarantee

Source

func (p Profile) HasGuarantee(id GuaranteeID) bool

HasGuarantee reports whether this profile explicitly declares the affirmative guarantee. False means no guarantee is asserted, not necessarily that the backend lacks the behavior.

func (Profile) InputLimits

Source

func (p Profile) InputLimits() (Limits, bool)

InputLimits reports input depth and value-count ceilings. The bool is false when no limits were declared; a true result with zero applicable fields means explicitly unbounded.

func (Profile) Methods

Source

func (p Profile) Methods() []MethodDeclaration

Methods returns a defensive copy of configured immutable extension declarations. Their presence does not enable those methods in the service's capability set or prove that a particular Build registered an implementation.

func (Profile) RuntimeLimits

Source

func (p Profile) RuntimeLimits() (Limits, bool)

RuntimeLimits reports evaluation-step, generated-value, and JSON-depth ceilings. The bool is false when no limits were declared; a true result with zero applicable fields means explicitly unbounded.

func (Profile) Valid

Source

func (p Profile) Valid() bool

Valid reports whether p contains a profile created successfully by NewProfile; the zero Profile is invalid.

func (Profile) Version

Source

func (p Profile) Version(component string) (string, bool)

Version returns a known component version and true when component was declared. A false result means unknown; versions are not guessed from a backend or database connection.

func (Profile) Versions

Source

func (p Profile) Versions() []CompatibilityVersion

Versions returns a defensive copy of known version components. Missing components remain unknown; values are never inferred from a backend.

type ProfileConfig

Source

type ProfileConfig struct {
	// Backend is a stable backend name, such as "local" or "postgresql".
	Backend	string
	// Features lists known feature statuses; omitted IDs remain unknown.
	Features	[]FeatureSupport
	// Versions lists only known implementation or explicitly supplied data versions.
	Versions	[]CompatibilityVersion
	// Guarantees lists affirmative guarantees, not missing behavior.
	Guarantees	[]GuaranteeID
	// Details contains backend-specific descriptive values.
	Details	[]ProfileDetail
	// Methods contains extension declarations; it does not enable permissions.
	Methods	[]MethodDeclaration
	// Capabilities is the effective service policy; its zero value is unknown.
	Capabilities	capabilities.Set
	// Nil limits mean unknown or outside this backend's responsibility. Non-nil
	// limits describe resolved ceilings; zero applicable fields mean explicitly
	// unbounded. Fields belonging to a different stage are not applicable.
	CompileLimits	*Limits
	InputLimits	*Limits
	RuntimeLimits	*Limits
}

ProfileConfig declares backend facts known to the caller or implementation. NewProfile validates and snapshots slices and limit pointers. Nil stage-limit pointers mean unknown or outside the backend's responsibility; non-nil zero fields mean explicitly unbounded for that stage. Capabilities is a separate explicit service policy, not a backend support report.

type ProfileDetail

Source

type ProfileDetail struct{ Name, Value string }

ProfileDetail holds backend-specific descriptive information. It grants no capabilities and is not a configuration option or execution guarantee.

type Program

Source

type Program plan.Program

Program holds the immutable typed plan and the schema, capability policy, method declarations, and resolved limits used to compile it. Compilation creates Programs; backends consume them without mutation. Its zero value is invalid.

func (Program) Capabilities

Source

func (p Program) Capabilities() capabilities.Set

Capabilities returns the explicit capability policy used to compile p. This is the compile-time permission set, not a backend support profile. An invalid zero Program returns the unspecified zero Set.

func (Program) Limits

Source

func (p Program) Limits() Limits

Limits returns the resolved limit values used to compile p. Inspect the compile-stage fields rather than interpreting zero as unlimited; zero fields were resolved from defaults unless UnlimitedLimits reports true. The zero Program returns the zero Limits value.

func (Program) Root

Source

func (p Program) Root() Node

Root returns the root of the typed plan, or an invalid Node for an invalid zero Program.

func (Program) Schema

Source

func (p Program) Schema() Type

Schema returns the exact immutable input schema used at compilation. The zero Program returns an invalid Type.

func (Program) Source

Source

func (p Program) Source() string

Source returns the original query text used to compile p, preserving source spelling for diagnostics and inspection. The zero Program returns an empty string.

func (Program) UnlimitedLimits

Source

func (p Program) UnlimitedLimits() bool

UnlimitedLimits reports whether compilation was explicitly configured without finite limits. It concerns compilation only, not input validation or backend runtime limits.

func (Program) Valid

Source

func (p Program) Valid() bool

Valid reports whether p is a compiler-created typed program rather than the invalid zero Program.

type Signature

Source

type Signature plan.Signature

Signature is one resolved method declaration applicable at a call site. A call may contain several non-ambiguous signatures for overload resolution.

func (Signature) Declaration

Source

func (s Signature) Declaration() (MethodDeclaration, bool)

Declaration returns the immutable extension declaration for an extension signature. The bool is false for built-in signatures or an invalid signature; a false result does not indicate a missing backend implementation.

func (Signature) ID

Source

func (s Signature) ID() string

ID returns the stable method signature identity, or an empty string for an invalid signature.

func (Signature) Parameters

Source

func (s Signature) Parameters() []Type

Parameters returns a defensive copy of the ordered declared parameter types: required parameters, optional parameters, then the repeated type if variadic. Optional positions are positional, and the final parameter is repeated only when Variadic reports true. An invalid signature returns nil.

func (Signature) Receiver

Source

func (s Signature) Receiver() Type

Receiver returns the signature's receiver type descriptor, or an invalid zero Type for an invalid signature.

func (Signature) Result

Source

func (s Signature) Result() Type

Result returns the signature's declared result type. Extension callbacks may also return ordinary null as a data failure. An invalid signature returns the invalid zero Type.

func (Signature) Variadic

Source

func (s Signature) Variadic() bool

Variadic reports whether the signature repeats its final parameter type. An invalid signature reports false.

type Span

Source

type Span = core.Span

Span is a half-open range [Start, End) of UTF-8 byte offsets in the original query, not rune indexes. Source diagnostics report one-based lines and columns counted in Unicode code points. A zero Span is an empty range at byte offset zero; use the containing query to interpret it.

This alias exposes the following definition and methods.

type Span struct{ Start, End int }

Span is a half-open range of UTF-8 byte offsets in the original query.

type SupportLevel

Source

type SupportLevel uint8

SupportLevel describes backend support separately from service permission. An absent feature entry is unknown, not unsupported or supported. Even a Supported entry is descriptive; Build remains authoritative for a concrete program and configuration.

Source

const (
	// UnknownSupport means the profile makes no claim about the feature. Profiles
	// express this by omitting the feature entry; NewProfile rejects an explicit
	// UnknownSupport entry.
	UnknownSupport	SupportLevel	= iota
	// Supported means the backend declares support, subject to Build validation.
	Supported
	// Conditional means support requires a non-empty Conditions explanation.
	Conditional
	// Unsupported means this backend profile declares the feature unavailable.
	Unsupported
)

type Type

Source

type Type core.Type

Type is an immutable description of values accepted by a schema or produced by a compiled expression. Its zero value is invalid; construct descriptors with PrimitiveType or the composite constructors, then call Check before using one as a host input schema. Function types are compiler metadata and are rejected by Check.

func NewListType

Source

func NewListType(element Type) Type

NewListType constructs an ordered list type whose elements must match element. Check the resulting descriptor before using it as an input schema.

func NewMapType

Source

func NewMapType(element Type) Type

NewMapType constructs an object type whose values must all match element. Map keys are strings. Check the resulting descriptor before using it as an input schema.

func NewStructType

Source

func NewStructType(fields ...Field) Type

NewStructType constructs a fixed-key object type from fields. Field order is canonicalized, but names and descriptors are not repaired: Check reports invalid UTF-8 or duplicate names, invalid types, and unsupported function types. Empty field names are allowed. Optional records key-absence permission independently of the value type. A nullable field can use Type: NewUnionType(PrimitiveType(StringType), PrimitiveType(NullType)); input validation accepts its absence as a normal null-safe case even when Optional is false. Optional still does not add NullType to Type.

func NewUnionType

Source

func NewUnionType(members ...Type) Type

NewUnionType constructs a normalized union from member descriptors. Nested unions are flattened, duplicate members are removed, and members are sorted canonically. No members produces NeverType; one member returns that member directly. Include NullType to allow explicit null; this does not make a struct field optional.

func PrimitiveType

Source

func PrimitiveType(k TypeKind) Type

PrimitiveType constructs a primitive descriptor, including AnyType, NullType, and NeverType. Invalid or composite kinds produce the invalid zero Type. AnyType accepts any valid HFF value; NeverType accepts no values and is mainly useful in compiler analysis. Use the composite constructors for list, map, struct, and union descriptors.

func (Type) Check

Source

func (t Type) Check() error

Check recursively validates a host-schema descriptor. It rejects invalid and function types, duplicate struct keys, and nesting beyond the supported schema depth. Engine input schemas additionally require a struct or map root.

func (Type) Element

Source

func (t Type) Element() Type

Element returns the declared element type for a list or map. It returns an invalid zero Type for other kinds or an invalid receiver.

func (Type) Equal

Source

func (t Type) Equal(other Type) bool

Equal reports structural equality, including field names, optionality, and nested member types. It does not infer compatibility or perform coercion.

func (Type) Fields

Source

func (t Type) Fields() []Field

Fields returns a defensive copy of a struct's fields. It returns nil for non-struct or invalid types; changing the returned slice does not change t.

func (Type) Key

Source

func (t Type) Key() string

Key returns the stable canonical structural key for descriptor comparison and caches. It is not a display format or serialization contract.

func (Type) Kind

Source

func (t Type) Kind() TypeKind

Kind returns the descriptor kind; an invalid zero Type reports InvalidType.

func (Type) Members

Source

func (t Type) Members() []Type

Members returns a defensive copy of union members, or nil when t is not a union. A normalized union has at least two members; singleton unions have already collapsed to their member type.

func (Type) Parameters

Source

func (t Type) Parameters() []Type

Parameters returns a defensive copy of function parameter types, or nil for a non-function type. Function types are compiler metadata, not host schema types accepted by Check.

func (Type) Result

Source

func (t Type) Result() Type

Result returns a function's result type, or an invalid zero Type for other kinds or an invalid receiver.

type TypeKind

Source

type TypeKind = core.TypeKind

TypeKind identifies a schema or compiler type category. FunctionType and NeverType are primarily used in compiled plans, not host input schemas.

This alias exposes the following definition and methods.

type TypeKind uint8

TypeKind includes compiler types that are not host values.

type ValidationConfig

Source

type ValidationConfig = core.ValidationConfig

ValidationConfig selects host-input depth and value-count limits. Zero fields use finite defaults; Unlimited explicitly removes those two ceilings. Compile and runtime fields in Limits do not affect ValidateInput.

This alias exposes the following definition and methods.

type ValidationConfig struct {
	Limits		Limits
	Unlimited	bool
}

ValidationConfig makes disabling limits an explicit host choice.

type Value

Source

type Value core.Value

Value owns immutable data. Its zero value is invalid; it is neither missing nor null. Use Null for explicit null, and use Object lookup to distinguish a missing key from a key holding Null.

func Bool

Source

func Bool(v bool) Value

Bool constructs a Boolean HFF value. The payload is stored exactly; HFF truthiness is defined by evaluation, not by this constructor.

func Bytes

Source

func Bytes(v []byte) Value

Bytes copies v into an immutable byte value. Later changes to v do not change the Value; AsBytes returns another copy.

func Duration

Source

func Duration(v time.Duration) Value

Duration constructs a nanosecond-precision duration value.

func Float

Source

func Float(v float64) Value

Float constructs a float64 HFF value. Non-finite values are rejected by input validation rather than converted to null.

func Int

Source

func Int(v int64) Value

Int constructs an int64 HFF value without conversion to or from float64.

func List

Source

func List(values ...Value) Value

List copies values into an immutable ordered list. The empty call creates an empty list, not null. Backends such as local Match validate it against the Program schema; ValidateInput can create a reusable checked input explicitly.

func Null

Source

func Null() Value

Null constructs the explicit HFF null value.

func Object

Source

func Object(values map[string]Value) Value

Object copies values into an immutable object. A nil or empty map creates an empty object, not null. A missing key differs from a key explicitly mapped to Null(); use Lookup's bool result to tell them apart.

func String

Source

func String(v string) Value

String constructs an HFF string without normalization or numeric parsing. Input validation rejects strings that are not valid UTF-8.

func Timestamp

Source

func Timestamp(v time.Time) Value

Timestamp constructs a timestamp normalized to UTC. It represents an instant; the input time's location and monotonic clock reading are not part of the HFF value.

func (Value) AsBool

Source

func (v Value) AsBool() (bool, bool)

AsBool returns the Boolean payload and true only for BoolKind. The bool in the second result reports the kind match, not the payload's truth value.

func (Value) AsBytes

Source

func (v Value) AsBytes() ([]byte, bool)

AsBytes returns a defensive copy and true only for BytesKind. Mutating the returned bytes cannot change v.

func (Value) AsDuration

Source

func (v Value) AsDuration() (time.Duration, bool)

AsDuration returns the nanosecond-precision duration and true only for DurationKind.

func (Value) AsFloat

Source

func (v Value) AsFloat() (float64, bool)

AsFloat returns the float64 payload and true only for FloatKind. Input validation rejects NaN and infinities; this accessor does not coerce IntKind.

func (Value) AsInt

Source

func (v Value) AsInt() (int64, bool)

AsInt returns the int64 payload and true only for IntKind. It does not convert FloatKind values.

func (Value) AsList

Source

func (v Value) AsList() ([]Value, bool)

AsList returns a defensive copy of the ordered elements and true only for ListKind. A valid empty list returns a non-nil empty slice and true; false means the receiver is not a list, not that the list is empty.

Example

{
	list := hff.List(hff.String("admin"), hff.String("viewer"))
	items, ok := list.AsList()
	if !ok {
		panic("expected a list")
	}

	items[0] = hff.String("changed")
	original, _ := list.AsList()
	first, _ := original[0].AsString()
	fmt.Println(first)

}
Complete runnable example
package main

import (
	"fmt"

	"github.com/ornew/hff"
)

func main() {
	list := hff.List(hff.String("admin"), hff.String("viewer"))
	items, ok := list.AsList()
	if !ok {
		panic("expected a list")
	}
	// The returned slice is a copy; changing it does not mutate the HFF list.
	items[0] = hff.String("changed")
	original, _ := list.AsList()
	first, _ := original[0].AsString()
	fmt.Println(first)
}

Output:

admin

func (Value) AsObject

Source

func (v Value) AsObject() (map[string]Value, bool)

AsObject returns a defensive copy of the entries and true only for ObjectKind. A valid empty object returns a non-nil empty map and true; false means the receiver is not an object.

func (Value) AsString

Source

func (v Value) AsString() (string, bool)

AsString returns the string payload and true only for StringKind. The bool reports the kind match; it is not a success flag for string contents.

func (Value) AsTimestamp

Source

func (v Value) AsTimestamp() (time.Time, bool)

AsTimestamp returns the UTC-normalized instant and true only for TimestampKind.

func (Value) Kind

Source

func (v Value) Kind() Kind

Kind returns the exact representation kind. The zero Value reports InvalidKind; explicit null reports NullKind.

func (Value) Lookup

Source

func (v Value) Lookup(key string) (Value, bool)

Lookup returns an object field and whether the key exists. A present Null() value returns (Null(), true); a missing key or non-object receiver returns (zero Value, false). The zero Value in the latter case is invalid, not null.

Example

{
	record := hff.Object(map[string]hff.Value{"nickname": hff.Null(), "active": hff.Bool(false)})
	_, missing := record.Lookup("missing")
	nickname, present := record.Lookup("nickname")
	active, _ := record.Lookup("active")
	flag, typed := active.AsBool()
	fmt.Println("missing key exists:", missing)
	fmt.Println("nickname exists and is null:", present && nickname.Kind() == hff.NullKind)
	fmt.Println("active Boolean:", flag, typed)

}
Complete runnable example
package main

import (
	"fmt"

	"github.com/ornew/hff"
)

func main() {
	record := hff.Object(map[string]hff.Value{"nickname": hff.Null(), "active": hff.Bool(false)})
	_, missing := record.Lookup("missing")
	nickname, present := record.Lookup("nickname")
	active, _ := record.Lookup("active")
	flag, typed := active.AsBool()
	fmt.Println("missing key exists:", missing)
	fmt.Println("nickname exists and is null:", present && nickname.Kind() == hff.NullKind)
	fmt.Println("active Boolean:", flag, typed)
}

Output:

missing key exists: false
nickname exists and is null: true
active Boolean: false true
Explore HFF
Search documentation

Search the language specification and guides.

↑ ↓ to move · Enter to openEsc to close