package semantics

Import Path
	github.com/freeeve/gochickpeas/gql/internal/semantics (on go.dev)

Dependency Relation
	imports 6 packages, and imported by 3 packages

Involved Source Files

	  d autoparam.go
		Auto-parameterization (port of autoparam.rs): lift constant inline
		node/relationship property values out of a query into numbered parameter
		slots, so two queries differing only in those constants -- {id: 669} vs
		{id: 648}, {name: 'India'} vs {name: 'China'} -- become one template
		that shares a cached plan. The lifted values are returned in slot order
		and supplied per execution through the eval context.
		
		Lifted: inline pattern property values ({id: 669}) and constant
		comparison bounds in WHERE / subquery predicates (m.day < D) -- the
		positions that vary most across parameter sets. Left baked: CASE bin
		thresholds, scalar-function arguments, projection constants, UNWIND/FOR
		lists, CALL procedure arguments, and var-length bounds -- these can
		shape the plan, so lifting them would change the plan, not just a
		looked-up value.

	  d binder.go
		Binder helpers shared by the planner: aggregate detection, column
		naming, and reference validation against a slot map (port of binder.rs).
		The per-segment compilation that uses these lives in the plan package.

	  d desugar.go
		Desugar: query normalization that runs once on the parsed AST before
		planning, shrinking the surface the planner and executor must handle
		(port of desugar.rs). Lowers non-literal inline pattern property values:
		a constant value ((t:Tag {name: 'Hot'}), {id: $p}) stays on the fast
		props seek path, but an expression value ((t:Tag {name: tagVar}),
		{since: a.created}) is rewritten to a WHERE var.key = value equality
		conjunct on the (possibly synthesized) node/relationship variable, so
		pattern matching never evaluates an expression inside a pattern.
		
		Runs at the top of planning, so every entry -- cached, prepared,
		EXPLAIN, and a recursively planned CALL { ... } body -- is normalized
		uniformly. Idempotent: a second pass finds the PropExprs already
		drained.

	  d errors.go
		Package semantics holds the passes between parsing and planning:
		desugar (AST normalization), the binder helpers (aggregate detection,
		column naming, reference validation), and auto-parameterization for
		plan-cache sharing. Ports of the Rust crate's desugar.rs / binder.rs /
		autoparam.rs.
Package-Level Type Names (total 2)

	/* sort by: alphabet | popularity */
	 type ErrKind uint8 (basic type)
		ErrKind says which pipeline sentinel the root package should wrap a
		semantic error with (package gql cannot be imported here -- cycle).

		As Types Of (total 2)
			const KindBind
			const KindPlan

	 type Error (struct)
		Error is a semantic error with the sentinel kind it maps to.

		Fields (total 2)
			Kind ErrKind
			Msg string
		Methods (only one)
			(*Error) Error() string
				Error implements the error interface.

		Implements (at least one exported)
			*Error : error


Package-Level Functions (total 10)

	 func AutoParameterize(q *ast.Query) []value.Value
		AutoParameterize lifts inline property constants in q to Literal param
		slots in a fixed left-to-right order, mutating q into the cacheable
		template and returning the lifted values in slot order. Two queries with
		identical structure lift to identical templates with values in matching
		slots.

	 func CheckRefs(e ast.Expr, scope map[string]int) error
		CheckRefs validates that every variable referenced in e is present in
		scope (the planner's name -> slot map) and every called function is
		known.

	 func CheckRefsSkippingAgg(e ast.Expr, scope map[string]int) error
		CheckRefsSkippingAgg is CheckRefs, except a top-level aggregate call's
		arguments are validated directly (an aggregate's own name needs no
		scalar-function check, and count(*) binds nothing).

	 func DerivedName(e ast.Expr) string
		DerivedName derives a column name for an unaliased projection expression
		(the standard uses the source text; this is a close-enough
		reconstruction, observable in result column names).

	 func Desugar(q *ast.Query) error
		Desugar normalizes q in place. A synthetic-variable counter threads
		through so an anonymous node/relationship carrying a non-literal inline
		property gets a stable name to compare on.

	 func ExprHasAgg(e ast.Expr) bool
		ExprHasAgg reports whether e contains an aggregate call. Deliberately
		does NOT descend into EXISTS/COUNT subqueries (their expressions are a
		different scope), mirroring the Rust binder exactly -- so the shared
		pre-order walker is not used here.

	 func IsAggName(name string) bool
		IsAggName reports whether name is an aggregate function
		(case-insensitive).

	 func IsKnownFunction(name string) bool
		IsKnownFunction reports whether name is any function the engine
		recognizes -- an aggregate or a scalar. Unknown names are rejected at
		plan time by CheckRefs; without this they would evaluate to null per
		row, silently nulling columns and filtering rows.

	 func IsKnownScalarFunc(name string) bool
		IsKnownScalarFunc reports whether name is a scalar function the engine
		can evaluate (case-insensitive).

	 func LitValue(l ast.Literal) value.Value
		LitValue converts a parsed constant to its runtime value. Param slots
		resolve at execution time, not here, and read as Null.


Package-Level Constants (total 2)

	const KindBind ErrKind = 0
		KindBind is a binding error (unknown variable/function) -> ErrBind.

	const KindPlan ErrKind = 1
		KindPlan is a planning restriction -> ErrPlan.

The pages are generated with Golds v0.8.7. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.