Source File
	lower.go

Belonging Package
	github.com/freeeve/gochickpeas/gql/internal/plan

// Core lowering primitives (port of the Rust plan/lower.rs): slot
// assignment, scan-source selection, hop building, var-length
// hop-predicate extraction, projection binding, and the shared AND-chain
// helpers. The anchor-seek recognizers live in lower_seeks.go.
package plan

import (
	"github.com/freeeve/gochickpeas/gql/internal/ast"
	"github.com/freeeve/gochickpeas/gql/internal/graph"
)

// assignSlot resolves a node pattern's slot: an existing variable keeps its
// slot (wasBound reports whether it is already bound); a new or anonymous
// node takes the next slot.
func assignSlot(node *ast.NodePat, slots map[string]int, bound map[int]bool, nextSlot *int) (slot int, wasBound bool) {
	if node.Var != "" {
		if s, ok := slots[node.Var]; ok {
			return s, bound[s]
		}
		s := *nextSlot
		*nextSlot++
		slots[node.Var] = s
		return s, false
	}
	s := *nextSlot
	*nextSlot++
	return s, false
}

// scanSource picks a fresh node's default scan source: the most selective
// indexed property seek over its inline props and WHERE equalities (via
// bestPropSeek), else a label scan, else all nodes.
func scanSource(node *ast.NodePat, where ast.Expr, g graph.Graph) ScanSource {
	if ps, ok := bestPropSeek(node, where, g); ok {
		if ps.inVals != nil {
			return ScanSource{Kind: ScanPropertyIn, Label: node.Labels[0], Key: ps.key, Values: ps.inVals}
		}
		return ScanSource{Kind: ScanProperty, Label: node.Labels[0], Key: ps.key, Value: ps.val}
	}
	if len(node.Labels) > 0 {
		return ScanSource{Kind: ScanLabel, Label: node.Labels[0]}
	}
	return ScanSource{Kind: ScanAll}
}

// buildHop lowers one relationship hop to an Expand or VarExpand op.
func buildHop(rel *ast.RelPat, from, to, relSlot int, rebind bool, node *ast.NodePat) (BindOp, error) {
	op := BindOp{
		From:    from,
		To:      to,
		Rebind:  rebind,
		Dir:     mapDir(rel.Dir),
		Types:   rel.Types,
		RelSlot: relSlot,
		Labels:  node.Labels,
		Props:   node.Props,
	}
	if rel.Length == nil {
		op.Kind = OpExpand
		return op, nil
	}
	// GQL quantifier defaulting: an absent lower bound is 0 ({,3}, *),
	// per GRAMMAR.md -- unlike Cypher's *..3, whose min defaults to 1.
	vl := rel.Length
	var minHops uint64
	if vl.Min != nil {
		minHops = *vl.Min
	}
	if vl.Max != nil && minHops > *vl.Max {
		return BindOp{}, planErrf("quantifier bound {%d,%d} is empty", minHops, *vl.Max)
	}
	// Zero-length or unbounded resolves the distinct reachable set (a
	// dedup'd BFS), which has no per-path rel list, so a named rel
	// variable is not supported there.
	reach := minHops == 0 || vl.Max == nil
	if reach && rel.Var != "" {
		return BindOp{}, planErrf("a relationship variable is not supported on a zero-length or unbounded quantified pattern -- it resolves a reachable set, not paths")
	}
	op.Kind = OpVarExpand
	op.Min = minHops
	op.Max = vl.Max
	op.RelVar = rel.Var
	return op, nil
}

// extractVarlenHopPreds lifts all(r IN rels(e) WHERE pred) conjuncts from
// a stage WHERE onto the matching var-expand as a per-hop filter; consumed
// conjuncts drop from the WHERE. (Monotonic-order conjuncts lift later, in
// the segment-wide pushMonoPreds pass.)
func extractVarlenHopPreds(where *ast.Expr, ops []BindOp) error {
	if *where == nil {
		return nil
	}
	var conjs []ast.Expr
	SplitAnd(*where, &conjs)
	var kept []ast.Expr
	for _, c := range conjs {
		pushed, err := tryPushHopPred(c, ops)
		if err != nil {
			return err
		}
		if pushed {
			continue
		}
		kept = append(kept, c)
	}
	*where = rebuildAnd(kept)
	return nil
}

// tryPushHopPred lifts a single all(r IN rels(e) WHERE pred-over-r)
// conjunct onto the var-expand binding e. Any other shape returns false
// and is handled generally (never rejected here).
func tryPushHopPred(c ast.Expr, ops []BindOp) (bool, error) {
	lp, ok := c.(*ast.ListPred)
	if !ok {
		return false, nil
	}
	e := relsArg(lp.List)
	if e == "" {
		return false, nil
	}
	var target *BindOp
	for i := range ops {
		if ops[i].Kind == OpVarExpand && ops[i].RelVar == e {
			target = &ops[i]
			break
		}
	}
	if target == nil {
		return false, nil
	}
	if lp.Quant != ast.QuantAll || predRefsOnly(lp.Pred, lp.Var) != nil {
		return false, nil
	}
	if target.RelPred != nil {
		return false, nil
	}
	target.RelPred = &RelHopPred{Var: lp.Var, Pred: lp.Pred}
	return true, nil
}

// relsArg matches rels(<var>) returning the variable name; "" otherwise.
func relsArg(e ast.Expr) string {
	f, ok := e.(*ast.Func)
	if !ok || f.Star || len(f.Args) != 1 || !eqFold(f.Name, "rels") {
		return ""
	}
	v, ok := f.Args[0].(*ast.Var)
	if !ok {
		return ""
	}
	return v.Name
}

// predRefsOnly validates that a per-hop predicate's free variables are
// only the iteration variable v (so it can be evaluated against one
// relationship).
func predRefsOnly(e ast.Expr, v string) error {
	if bad := freeVarsOutside(e, []string{v}); len(bad) > 0 {
		return planErrf("a per-hop predicate may only reference the relationship variable `%s` (found `%s`)", v, bad[0])
	}
	return nil
}

// SplitAnd walks a WHERE's top-level AND chain, appending each conjunct
// (exported: the executor's conjunct bucketing splits the same chains).
func SplitAnd(e ast.Expr, out *[]ast.Expr) {
	if b, ok := e.(*ast.Binary); ok && b.Op == ast.OpAnd {
		SplitAnd(b.LHS, out)
		SplitAnd(b.RHS, out)
		return
	}
	*out = append(*out, e)
}

// rebuildAnd re-joins conjuncts left-associatively; nil for an empty list.
func rebuildAnd(conjs []ast.Expr) ast.Expr {
	if len(conjs) == 0 {
		return nil
	}
	acc := conjs[0]
	for _, c := range conjs[1:] {
		acc = &ast.Binary{Op: ast.OpAnd, LHS: acc, RHS: c}
	}
	return acc
}

// mapDir converts pattern syntax direction to a traversal direction.
func mapDir(d ast.Dir) graph.Direction {
	switch d {
	case ast.DirOut:
		return graph.Outgoing
	case ast.DirIn:
		return graph.Incoming
	}
	return graph.Both
}

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.