:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
//! Canonical Hog value formatting, matching the reference VMs' `printHogValue` /
//! `printHogStringOutput` (see `common/hogvm/typescript/src/stl/print.ts` and
//! `common/hogvm/python/stl/print.py`). This is what `print(...)` emits and is the
//! oracle the parity harness diffs against. Kept separate from `stl::to_string`
//! (which is `toString` semantics) on purpose — the two are subtly different and the
//! parity loop is what reconciles them.
use crate::values::HogMap;
use crate::{
memory::{HeapReference, VmHeap},
values::{Callable, HogLiteral, HogValue},
};
const PRINT_RECURSION_LIMIT: usize = 64;
/// Escape a string the way the reference VMs do: wrap in single quotes and escape the
/// clickhouse-style control characters plus the quote and backslash.
pub fn escape_string(value: &str) -> String {
let mut out = String::with_capacity(value.len() + 2);
out.push('\'');
for c in value.chars() {
match c {
'\u{08}' => out.push_str("\\b"),
'\u{0C}' => out.push_str("\\f"),
'\r' => out.push_str("\\r"),
'\n' => out.push_str("\\n"),
'\t' => out.push_str("\\t"),
'\0' => out.push_str("\\0"),
'\u{0B}' => out.push_str("\\v"),
'\\' => out.push_str("\\\\"),
'\'' => out.push_str("\\'"),
other => out.push(other),
}
}
out.push('\'');
out
}
/// Format a value as `print(...)` would. Top-level strings are emitted raw; everything
/// else (including strings nested inside arrays/objects) goes through [`print_hog_value`].
pub fn print_hog_string_output(heap: &VmHeap, value: &HogValue) -> Result<String, crate::VmError> {
match value.deref(heap)? {
HogLiteral::String(s) => Ok(s.to_string()),
_ => print_hog_value(heap, value, &mut Vec::new(), 0),
}
}
/// The recursive canonical printer. `marked` tracks the heap references currently being
/// printed so self-referential containers render as `null` (matching the reference VMs'
/// `marked` set), rather than recursing forever.
pub fn print_hog_value(
heap: &VmHeap,
value: &HogValue,
marked: &mut Vec<HeapReference>,
depth: usize,
) -> Result<String, crate::VmError> {
if depth > PRINT_RECURSION_LIMIT {
return Ok("null".to_string());
}
let lit = value.deref(heap)?;
let container_ptr = match value {
HogValue::Ref(ptr) if matches!(lit, HogLiteral::Array(_) | HogLiteral::Object(_)) => {
Some(*ptr)
}
_ => None,
};
if let Some(ptr) = container_ptr {
if marked.contains(&ptr) {
return Ok("null".to_string());
}
marked.push(ptr);
}
let result = format_literal(heap, lit, marked, depth);
if container_ptr.is_some() {
marked.pop();
}
result
}
fn format_literal(
heap: &VmHeap,
lit: &HogLiteral,
marked: &mut Vec<HeapReference>,
depth: usize,
) -> Result<String, crate::VmError> {
match lit {
HogLiteral::Null => Ok("null".to_string()),
HogLiteral::Boolean(b) => Ok(if *b { "true" } else { "false" }.to_string()),
HogLiteral::Number(n) => Ok(if n.is_float() {
n.to_float().to_string()
} else {
n.to_integer().to_string()
}),
HogLiteral::String(s) => Ok(escape_string(s)),
HogLiteral::Array(arr) => {
let mut parts = Vec::with_capacity(arr.len());
for elem in arr {
parts.push(print_hog_value(heap, elem, marked, depth + 1)?);
}
Ok(format!("[{}]", parts.join(", ")))
}
HogLiteral::Tuple(arr) => {
let mut parts = Vec::with_capacity(arr.len());
for elem in arr {
parts.push(print_hog_value(heap, elem, marked, depth + 1)?);
}
// The reference disambiguates 0/1-element tuples as `tuple(...)`; 2+ print as `(a, b)`.
if arr.len() < 2 {
Ok(format!("tuple({})", parts.join(", ")))
} else {
Ok(format!("({})", parts.join(", ")))
}
}
HogLiteral::Object(obj) => {
// Hog temporals are duck-typed objects; the reference prints them as DateTime(...)/Date(...).
if let Some(temporal) = format_temporal(heap, obj)? {
return Ok(temporal);
}
// Hog errors are duck-typed too; the reference prints them as `Type('message'[, payload])`.
if let Some(err) = format_error(heap, obj, marked, depth)? {
return Ok(err);
}
// HogQL AST nodes (`{__hx_ast: …}`) render back to SQL, wrapped as `sql(…)`.
if obj.contains_key("__hx_ast") {
return Ok(format!("sql({})", HogQLPrinter::new(heap).print_node(obj)?));
}
let mut parts = Vec::with_capacity(obj.len());
for (key, val) in obj.iter() {
parts.push(format!(
"{}: {}",
escape_string(key),
print_hog_value(heap, val, marked, depth + 1)?
));
}
Ok(format!("{{{}}}", parts.join(", ")))
}
// The reference VMs print both callables and closures as `fn<name(argCount)>`.
HogLiteral::Callable(callable) => Ok(print_callable(callable)),
HogLiteral::Closure(closure) => Ok(print_callable(&closure.callable)),
}
}
fn print_callable(callable: &Callable) -> String {
match callable {
Callable::Local(local) => {
format!(
"fn<{}({})>",
escape_identifier(&local.name),
local.stack_arg_count
)
}
// Native arity isn't tracked here; the reference prints maxArgs, but no corpus program
// prints a bare native-function value, so the count is a placeholder.
Callable::Stl(name) => format!("fn<{}(0)>", escape_identifier(name)),
}
}
// Render the Hog temporal duck-types: `{__hogDateTime__: true, dt, zone}` -> `DateTime(dt, 'zone')`
// and `{__hogDate__: true, year, month, day}` -> `Date(y, m, d)`. Returns None for plain objects.
fn format_temporal(heap: &VmHeap, obj: &HogMap) -> Result<Option<String>, crate::VmError> {
if marker(heap, obj.get("__hogDateTime__"))? {
let dt = number(heap, obj.get("dt"))?.unwrap_or(0.0);
let zone = string(heap, obj.get("zone"))?.unwrap_or_else(|| "UTC".to_string());
return Ok(Some(format!(
"DateTime({}, {})",
format_dt_seconds(dt),
escape_string(&zone)
)));
}
if marker(heap, obj.get("__hogDate__"))? {
let y = number(heap, obj.get("year"))?.unwrap_or(0.0) as i64;
let m = number(heap, obj.get("month"))?.unwrap_or(0.0) as i64;
let d = number(heap, obj.get("day"))?.unwrap_or(0.0) as i64;
return Ok(Some(format!("Date({y}, {m}, {d})")));
}
Ok(None)
}
// Render the Hog error duck-type `{__hogError__: true, type, message, payload?}` as
// `Type('message')` or `Type('message', payload)`. Returns None for plain objects.
fn format_error(
heap: &VmHeap,
obj: &HogMap,
marked: &mut Vec<HeapReference>,
depth: usize,
) -> Result<Option<String>, crate::VmError> {
if !marker(heap, obj.get("__hogError__"))? {
return Ok(None);
}
let type_str = string(heap, obj.get("type"))?.unwrap_or_else(|| "Error".to_string());
let message = string(heap, obj.get("message"))?.unwrap_or_default();
let payload = match obj.get("payload") {
Some(p) if !matches!(p.deref(heap)?, HogLiteral::Null) => {
format!(", {}", print_hog_value(heap, p, marked, depth + 1)?)
}
_ => String::new(),
};
Ok(Some(format!(
"{type_str}({}{payload})",
escape_string(&message)
)))
}
fn marker(heap: &VmHeap, v: Option<&HogValue>) -> Result<bool, crate::VmError> {
match v {
Some(v) => Ok(matches!(v.deref(heap)?, HogLiteral::Boolean(true))),
None => Ok(false),
}
}
fn number(heap: &VmHeap, v: Option<&HogValue>) -> Result<Option<f64>, crate::VmError> {
match v {
Some(v) => Ok(match v.deref(heap)? {
HogLiteral::Number(n) => Some(n.to_float()),
_ => None,
}),
None => Ok(None),
}
}
fn string(heap: &VmHeap, v: Option<&HogValue>) -> Result<Option<String>, crate::VmError> {
match v {
Some(v) => Ok(match v.deref(heap)? {
HogLiteral::String(s) => Some(s.to_string()),
_ => None,
}),
None => Ok(None),
}
}
// DateTime seconds print with a trailing `.0` when integral (matching Python's `float(dt)` str and
// the reference DateTime() format), e.g. 1609504496 -> "1609504496.0", 1609504496.5 unchanged.
fn format_dt_seconds(f: f64) -> String {
let s = format!("{f}");
if s.contains(['.', 'e', 'E']) || !f.is_finite() {
s
} else {
format!("{s}.0")
}
}
/// Identifiers print raw when they look like identifiers, else backtick-escaped — matching
/// the reference `escapeIdentifier`.
fn escape_identifier(identifier: &str) -> String {
let is_ident = {
let mut chars = identifier.chars();
matches!(chars.next(), Some(c) if c.is_ascii_alphabetic() || c == '_' || c == '$')
&& chars.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '$')
};
if is_ident && !identifier.is_empty() {
identifier.to_string()
} else {
let mut out = String::with_capacity(identifier.len() + 2);
out.push('`');
for c in identifier.chars() {
match c {
'\u{08}' => out.push_str("\\b"),
'\u{0C}' => out.push_str("\\f"),
'\r' => out.push_str("\\r"),
'\n' => out.push_str("\\n"),
'\t' => out.push_str("\\t"),
'\0' => out.push_str("\\0"),
'\u{0B}' => out.push_str("\\v"),
'\\' => out.push_str("\\\\"),
'`' => out.push_str("\\`"),
other => out.push(other),
}
}
out.push('`');
out
}
}
// ── HogQL AST → SQL printer ──────────────────────────────────────────────────────────────────
// Port of the reference `HogQLPrinter` (common/hogvm/typescript/src/stl/print.ts). HogQL queries
// built via `sql(...)` are duck-typed AST objects (`{__hx_ast: <type>, …}`); this renders them back
// to SQL. Only the non-pretty path is implemented (the VM never pretty-prints). The outer `sql(…)`
// wrapper is added by the caller (`format_literal`), matching `printHogValue`.
struct HogQLPrinter<'a> {
heap: &'a VmHeap,
// Mirrors the reference's `stack.length`: a query that isn't the outermost node is parenthesised.
depth: usize,
}
impl<'a> HogQLPrinter<'a> {
fn new(heap: &'a VmHeap) -> Self {
HogQLPrinter { heap, depth: 0 }
}
// Entry point: an already-dereferenced AST object.
fn print_node(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
self.depth += 1;
let result = self.dispatch(obj);
self.depth -= 1;
result
}
// Visit any child: a nested AST object dispatches; a null renders empty; anything else goes
// through the canonical value printer (the reference's `escapeValue`).
fn visit(&mut self, node: &HogValue) -> Result<String, crate::VmError> {
match node.deref(self.heap)? {
HogLiteral::Null => Ok(String::new()),
HogLiteral::Object(obj) if obj.contains_key("__hx_ast") => self.print_node(obj),
_ => print_hog_value(self.heap, node, &mut Vec::new(), 0),
}
}
fn dispatch(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let node_type = self.str_field(obj, "__hx_ast")?.ok_or_else(|| {
crate::VmError::NativeCallFailed("HogQL node missing __hx_ast".to_string())
})?;
match node_type.as_str() {
"SelectQuery" => self.select_query(obj),
"SelectSetQuery" => self.select_set_query(obj),
"JoinExpr" => self.join_expr(obj),
"JoinConstraint" => self.visit_child(obj, "expr"),
"Call" => self.call(obj),
"Constant" => self.visit_child(obj, "value"),
"Field" => self.field(obj),
"Alias" => self.alias(obj),
"And" => self.logical(obj, "and"),
"Or" => self.logical(obj, "or"),
"Not" => Ok(format!("not({})", self.visit_child(obj, "expr")?)),
"CompareOperation" => self.compare(obj),
"Tuple" => Ok(format!("tuple({})", self.exprs(obj)?.join(", "))),
"Array" => Ok(format!("[{}]", self.exprs(obj)?.join(", "))),
"ArithmeticOperation" => self.arithmetic(obj),
"OrderExpr" => Ok(format!(
"{} {}",
self.visit_child(obj, "expr")?,
self.str_field(obj, "order")?.unwrap_or_default()
)),
"Lambda" => self.lambda(obj),
"Asterisk" => Ok("*".to_string()),
other => Err(crate::VmError::NativeCallFailed(format!(
"Unknown HogQL AST node type: {other}"
))),
}
}
fn select_query(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let is_top_level = self.depth <= 1;
let distinct = if self.bool_field(obj, "distinct")? {
" DISTINCT"
} else {
""
};
let select = self.exprs_field(obj, "select")?;
let mut clauses = vec![format!("SELECT{distinct} {}", select.join(", "))];
if let Some(from) = obj.get("select_from") {
let rendered = self.visit_join_expression(from)?;
if !rendered.is_empty() {
clauses.push(format!("FROM {rendered}"));
}
}
for (key, kw) in [
("prewhere", "PREWHERE"),
("where", "WHERE"),
("having", "HAVING"),
] {
if obj.contains_key(key) {
let rendered = self.visit_child(obj, key)?;
if !rendered.is_empty() {
clauses.push(format!("{kw} {rendered}"));
}
}
}
for (key, kw) in [("group_by", "GROUP BY"), ("order_by", "ORDER BY")] {
let parts = self.exprs_field(obj, key)?;
if !parts.is_empty() {
clauses.push(format!("{kw} {}", parts.join(", ")));
}
}
if obj.contains_key("limit") {
let limit = self.visit_child(obj, "limit")?;
if !limit.is_empty() {
clauses.push(format!("LIMIT {limit}"));
if self.bool_field(obj, "limit_with_ties")? {
clauses.push("WITH TIES".to_string());
}
if obj.contains_key("offset") {
let offset = self.visit_child(obj, "offset")?;
if !offset.is_empty() {
clauses.push(format!("OFFSET {offset}"));
}
}
}
}
let response = clauses.join(" ");
Ok(if is_top_level {
response
} else {
format!("({response})")
})
}
fn select_set_query(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
// The reference decrements/increments the indent around the set query; with pretty=false that
// only affects the parenthesisation check, which we approximate via depth.
let mut result = self.visit_child(obj, "initial_select_query")?;
for entry in self.array_field(obj, "subsequent_select_queries")? {
let HogLiteral::Object(eo) = entry.deref(self.heap)? else {
continue;
};
let op = self.str_field(eo, "set_operator")?.unwrap_or_default();
let query = match eo.get("select_query") {
Some(q) => self.visit(q)?,
None => String::new(),
};
if !op.is_empty() {
result.push_str(&format!(" {op} "));
}
result.push_str(&query);
}
Ok(if self.depth > 1 {
format!("({})", result.trim())
} else {
result
})
}
fn visit_join_expression(&mut self, node: &HogValue) -> Result<String, crate::VmError> {
if let HogLiteral::Object(obj) = node.deref(self.heap)? {
if self.str_field(obj, "__hx_ast")?.as_deref() == Some("JoinExpr") {
return self.join_expr(obj);
}
}
self.visit(node)
}
fn join_expr(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let mut parts = Vec::new();
let table = self.visit_child(obj, "table")?;
match self.str_field(obj, "alias")? {
Some(alias) if alias != table => {
parts.push(format!("{table} AS {}", escape_identifier(&alias)));
}
_ => parts.push(table),
}
let mut current = obj.get("next_join").cloned();
while let Some(join) = current {
let HogLiteral::Object(jo) = join.deref(self.heap)? else {
break;
};
let jo = jo.clone();
let join_type = self
.str_field(&jo, "join_type")?
.unwrap_or_else(|| "JOIN".to_string());
let table = self.visit_child(&jo, "table")?;
let constraint = match jo.get("constraint") {
Some(c) => {
if let HogLiteral::Object(co) = c.deref(self.heap)? {
let ctype = self.str_field(co, "constraint_type")?.unwrap_or_default();
format!("{ctype} {}", self.visit(c)?)
} else {
String::new()
}
}
None => String::new(),
};
let table_with_alias = match self.str_field(&jo, "alias")? {
Some(alias) if alias != table => {
format!("{table} AS {}", escape_identifier(&alias))
}
_ => table,
};
parts.push(
format!("{join_type} {table_with_alias} {constraint}")
.trim()
.to_string(),
);
current = jo.get("next_join").cloned();
}
Ok(parts.join(" "))
}
fn call(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let name = self.str_field(obj, "name")?.unwrap_or_default();
Ok(format!(
"{name}({})",
self.exprs_field(obj, "args")?.join(", ")
))
}
fn field(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let chain = self.array_field(obj, "chain")?;
if chain.len() == 1 {
if let HogLiteral::String(s) = chain[0].deref(self.heap)? {
if s.as_str() == "*" {
return Ok("*".to_string());
}
}
}
let mut parts = Vec::with_capacity(chain.len());
for elem in &chain {
parts.push(self.escape_identifier_or_index(elem)?);
}
Ok(parts.join("."))
}
fn alias(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
if self.bool_field(obj, "hidden")? {
return self.visit_child(obj, "expr");
}
let inside = self.visit_child(obj, "expr")?;
let alias = self.str_field(obj, "alias")?.unwrap_or_default();
Ok(format!("{inside} AS {}", escape_identifier(&alias)))
}
fn logical(&mut self, obj: &HogMap, func: &str) -> Result<String, crate::VmError> {
let exprs = self.exprs_field(obj, "exprs")?;
match exprs.len() {
0 => Ok(String::new()),
1 => Ok(exprs.into_iter().next().unwrap()),
_ => Ok(format!("{func}({})", exprs.join(", "))),
}
}
fn compare(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let left = self.visit_child(obj, "left")?;
let right = self.visit_child(obj, "right")?;
let op = self.str_field(obj, "op")?.unwrap_or_default();
let func = match op.as_str() {
"==" => "equals",
"!=" => "notEquals",
"<" => "less",
">" => "greater",
"<=" => "lessOrEquals",
">=" => "greaterOrEquals",
"in" => "in",
"not in" => "notIn",
"like" => "like",
"not like" => "notLike",
"ilike" => "ilike",
"not ilike" => "notILike",
"=~" | "!~" | "=~*" | "!~*" => "match",
other => other,
};
Ok(match op.as_str() {
"!~*" => format!("not({func}({left}, concat('(?i)', {right})))"),
"=~*" => format!("{func}({left}, concat('(?i)', {right}))"),
"!~" => format!("not({func}({left}, {right}))"),
_ => format!("{func}({left}, {right})"),
})
}
fn arithmetic(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let left = self.visit_child(obj, "left")?;
let right = self.visit_child(obj, "right")?;
let func = match self.str_field(obj, "op")?.as_deref() {
Some("+") => "plus",
Some("-") => "minus",
Some("*") => "multiply",
Some("/") => "divide",
Some("%") => "modulo",
other => {
return Err(crate::VmError::NativeCallFailed(format!(
"Unknown ArithmeticOperation operator: {other:?}"
)))
}
};
Ok(format!("{func}({left}, {right})"))
}
fn lambda(&mut self, obj: &HogMap) -> Result<String, crate::VmError> {
let args = self.array_field(obj, "args")?;
let escaped: Vec<String> = args
.iter()
.filter_map(|a| match a.deref(self.heap) {
Ok(HogLiteral::String(s)) => Some(escape_identifier(s)),
_ => None,
})
.collect();
let arg_list = if escaped.len() == 1 {
escaped[0].clone()
} else {
format!("({})", escaped.join(", "))
};
Ok(format!("{arg_list} -> {}", self.visit_child(obj, "expr")?))
}
// ── helpers ──
fn exprs(&mut self, obj: &HogMap) -> Result<Vec<String>, crate::VmError> {
self.exprs_field(obj, "exprs")
}
fn exprs_field(&mut self, obj: &HogMap, key: &str) -> Result<Vec<String>, crate::VmError> {
let items = self.array_field(obj, key)?;
let mut out = Vec::with_capacity(items.len());
for item in &items {
out.push(self.visit(item)?);
}
Ok(out)
}
fn visit_child(&mut self, obj: &HogMap, key: &str) -> Result<String, crate::VmError> {
match obj.get(key) {
Some(v) => self.visit(v),
None => Ok(String::new()),
}
}
fn array_field(&self, obj: &HogMap, key: &str) -> Result<Vec<HogValue>, crate::VmError> {
match obj.get(key) {
Some(v) => Ok(match v.deref(self.heap)? {
HogLiteral::Array(a) | HogLiteral::Tuple(a) => a.clone(),
_ => Vec::new(),
}),
None => Ok(Vec::new()),
}
}
fn str_field(&self, obj: &HogMap, key: &str) -> Result<Option<String>, crate::VmError> {
string(self.heap, obj.get(key))
}
fn bool_field(&self, obj: &HogMap, key: &str) -> Result<bool, crate::VmError> {
marker(self.heap, obj.get(key))
}
// `escapeIdentifierOrIndex`: a non-negative integer stays bare; everything else is an identifier.
fn escape_identifier_or_index(&self, value: &HogValue) -> Result<String, crate::VmError> {
Ok(match value.deref(self.heap)? {
HogLiteral::Number(n) if !n.is_float() => n.to_integer().to_string(),
HogLiteral::String(s) => escape_identifier(s),
other => escape_identifier(&print_hog_value(
self.heap,
&HogLiteral::clone(other).into(),
&mut Vec::new(),
0,
)?),
})
}
}