{"version":"https://jsonfeed.org/version/1","title":"Sufyan rambles","home_page_url":"https://dawoodjee.com/","feed_url":"https://dawoodjee.com/feed.json","description":"","items":[{"id":"https://dawoodjee.com/blog/pratt-parsing/","url":"https://dawoodjee.com/blog/pratt-parsing/","title":"Pratt Parsing","content_html":"

Hundreds of Pratt parsing posts exist. I hope this one is relatively clear,\nconcise, and comprehensive.

\n

Learn how Pratt parsers work by writing one. I assume familiarity with\ngrammars, parsers\nand TypeScript.

\n

The\ncode\nis public domain. Send feedback by email.

\n

Motivation

\n

This is an intuitive expression grammar.

\n
expr = expr ("+" | "-" | "*" | "/" | "^") expr\n     | "-" expr\n     | number\n
\n

The problem is it's ambiguous. 1 + 2 * 3 can be parsed as (1 + 2) * 3 or\n1 + (2 * 3).

\n

The textbook way to resolve ambiguity is to convolute the grammar with\nassociativity and precedence rules.

\n
expr = expr ("+" | "-") term\n     | term\n\nterm = term ("*" | "/") factor\n     | factor\n\nfactor = factor "^" number\n     | "-" factor\n     | number\n
\n

This grammar is not intuitive. It gets worse if your parser cannot handle left\nrecursion. And worse as you add more operators.

\n

The resulting syntax trees are cumbersome.

\n

Overview

\n

Pratt parsing uses grammars of this form.

\n
expr = head tail*\n\nhead = number\n     | "-" expr\n\ntail = ("+" | "-" | "*" | "/" | "^") expr\n
\n

And produces syntax trees of this form.

\n
expr = expr ("+" | "-" | "*" | "/" | "^") expr\n     | "-" expr\n     | number\n
\n

The parsing routine applies precedence and associativity rules to resolve\ngrammar ambiguity.

\n

Pratt parsers are easy to understand, implement, and integrate.

\n

We'll build a series of gradually better parsers to explain how it works.

\n

Precedence and Associativity

\n

Left-Associative Parser

\n

Start simple. Assume all operators are left-associative and without precedence.

\n

Parse 1 + 2 + 3 * 4 * 5 as ((((1 + 2) + 3) * 4) * 5).

\n

The expression grammar supports this with a repeated tail that immediately\napplies the operator to expand the left expression.

\n
expr = number (tail_op number)*\n       |    | |               |\n       └head┘ └──────tail─────┘\n
\n

The implementation reflects the grammar.

\n
function expr(ctx) {\n  let left_expr = number(next_token(ctx));\n  while (has_token(ctx)) {\n    const op = tail_op(next_token(ctx));\n    const right_expr = number(next_token(ctx));\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n
\n

Right-Associative Parser

\n

Now assume all operators are right-associative and without precedence

\n

Parse 1 + 2 + 3 * 4 * 5 as (1 + (2 + (3 * (4 * 5)))).

\n

The expression grammar supports this with a right-recursive tail that expands\nthe expression to the right before applying the operator.

\n
expr = number (tail_op expr)?\n
\n

The implementation reflects the grammar.

\n
function expr(ctx) {\n  let left_expr = number(next_token(ctx));\n  if (has_token(ctx)) {\n    const op = tail_op(next_token(ctx));\n    const right_expr = expr(ctx);\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n
\n

Mixed-Associative Grammar

\n

Sometimes the parser should apply an operator immediately as in the first\nparser. Other times it should wait until later operators are applied as in the\nsecond parser.

\n

Merge the grammars to create an ambiguous grammar that enables this choice:

\n
expr = number (tail_op number)*   // Parser 1: left-associative\nexpr = number (tail_op expr  )?   // Parser 2: right-associative\nexpr = number (tail_op expr  )*   // Merged: mixed-associative\n
\n

Take the second parser and rewrite if to while.

\n
function expr(ctx) {\n  let left_expr = number(next_token(ctx));\n  while (has_token(ctx)) {\n    const op = tail_op(next_token(ctx));\n    const right_expr = expr(ctx);\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n
\n

This parser resolves the grammar's ambiguity by always choosing to recurse,\nwhich makes it indistinguishable from the second parser.

\n

Respecting Associativity

\n

From experience we know right-associative operators should recurse.

\n

Left-associative operators should instead return the current expression to\nbecome part of the parent expression.

\n
function expr(ctx, parent_op) {\n  let left_expr = number(next_token(ctx));\n  while (has_token(ctx)) {\n    const op = tail_op(peek_token(ctx));\n    if (assoc(op) === "left") break;\n    next_token(ctx);\n    const right_expr = expr(ctx, op);\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n
\n

Now the parser respects associativity but not precedence.

\n

Respecting Precedence

\n

Pratt parsing uses nested levels of recursion to represent nested expressions of\nequal or increasing precedence.

\n

By definition, a level exits when an operator with lower precedence appears.

\n

By definition, associativity applies when operators have equal precedence.

\n

The parent operator determines a level's precedence. The root expression has no\nparent, which means minimum precedence.

\n
// Compares the precedence of two operators\nfunction cmp_precedence(op1, op2): "<" | "=" | ">";\n\nfunction expr(ctx, parent_op) {\n  let left_expr = number(next_token(ctx));\n  while (has_token(ctx)) {\n    const op = tail_op(peek_token(ctx));\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    const right_expr = expr(ctx, op);\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n\nexpr(ctx, Op.Root); // Expected syntax for parsing an expression.\n
\n

This parser respects precedence and associativity.

\n

Adding Operators

\n

Head and Tail Parsing

\n

To simplify future extensions, split the grammar into head and tail rules.

\n
expr = expr_head expr_tail*\n\nexpr_head = number\n\nexpr_tail = tail_op expr\n
\n

Refactor the parser accordingly.

\n
function expr(ctx, parent_op) {\n  const left_expr = expr_head(ctx);\n  return expr_tail(ctx, parent_op, left_expr);\n}\nfunction expr_head(ctx) {\n  return number(next_token(ctx));\n}\nfunction expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const op = tail_op(peek_token(ctx));\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    const right_expr = expr(ctx, op);\n    left_expr = infix(op, left_expr, right_expr);\n  }\n  return left_expr;\n}\n
\n

Prefix Operators

\n

Extend expr_head to support prefix operators.

\n
expr_head = number\n          | prefix_op expr\n
\n

Operators like - can have overloaded infix and prefix definitions because\nprefix_op and tail_op don't conflict in the grammar.

\n
function expr_head(ctx) {\n  const token = next_token(ctx);\n  if (is_number_token(token)) {\n    return number(token);\n  } else {\n    const op = prefix_op(token);\n    const right_expr = expr(ctx, op);\n    return prefix(op, right_expr);\n  }\n}\n
\n

Postfix Operators

\n

Update expr_tail to support postfix operators.

\n
expr_tail = postfix_op\n          | infix_op expr\n
\n

If an operator is both postfix and infix, the parser must look ahead to\ndifferentiate the two cases. Disallow this to simplify parsing.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const op = tail_op(peek_token(ctx));\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    if (is_postfix_op(op)) {\n      left_expr = postfix(op, left_expr);\n    } else {\n      const right_expr = expr(ctx, op);\n      left_expr = infix(op, left_expr, right_expr);\n    }\n  }\n  return left_expr;\n}\n
\n

Parentheses

\n

Extend expr_head to support parenthesized expressions.

\n
expr_head = "(" expr ")"\n          | number\n          | prefix_op expr\n
\n

Parentheses prevent other operators from interacting with the enclosed\nexpression, so precedence is reset.

\n
function expr_head(ctx) {\n  const token = next_token(ctx);\n  if (token === "(") {\n    const right_expr = expr(ctx, Op.Root);\n    next_token(ctx); // consume ")"\n    return right_expr;\n  } else if (is_number_token(token)) {\n    return number(token);\n  } else {\n    const op = prefix_op(token);\n    const right_expr = expr(ctx, op);\n    return prefix(op, right_expr);\n  }\n}\n
\n

) tokens appear where the parser otherwise expects tail operators. They mark\nthe end of an expression.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const token = peek_token(ctx);\n    if (token === ")") break;\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    if (is_postfix_op(op)) {\n      left_expr = postfix(op, left_expr);\n    } else {\n      const right_expr = expr(ctx, op);\n      left_expr = infix(op, left_expr, right_expr);\n    }\n  }\n  return left_expr;\n}\n
\n

Subscript Operator

\n

The (array) subscript operator [ resembles a postfix operator because there is\nno right argument.

\n

Brackets prevent other operators from interacting with the enclosed expression.

\n
expr_tail = infix_op expr\n          | postfix_op\n          | subscript_op\n\nsubscript_op = "[" expr "]"\n
\n

Like ) tokens, ] tokens mark the end of an expression.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const token = peek_token(ctx);\n    if (token === ")" || token === "]") break;\n    const op = tail_op(token);\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    if (op === Op.Subscript) {\n      const middle_expr = expr(ctx, Op.Root);\n      next_token(ctx); // consume "]"\n      left_expr = subscript(left_expr, middle_expr);\n    } else if (is_postfix_op(op)) {\n      left_expr = postfix(op, left_expr);\n    } else {\n      const right_expr = expr(ctx, op);\n      left_expr = infix(op, left_expr, right_expr);\n    }\n  }\n  return left_expr;\n}\n
\n

Ternary Operator

\n

The ternary operator left ? middle : right resembles an infix operator because\nit has an unenclosed right argument.

\n

The middle expression is enclosed so other operators cannot affect how it is\nparsed.

\n
expr_tail = infix_op expr\n          | postfix_op\n          | subscript_op\n          | ternary_op\n\nternary_op = "?" expr ":" expr\n
\n

: tokens mark the end of an expression.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const token = peek_token(ctx);\n    if (token === ")" || token === "]" || token === ":") break;\n    const op = tail_op(token);\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    next_token(ctx);\n    if (op === Op.Ternary) {\n      const middle_expr = expr(ctx, Op.Root);\n      next_token(ctx); // consume ":"\n      const right_expr = expr(ctx, op);\n      left_expr = ternary(left_expr, middle_expr, right_expr);\n    } else if (op === Op.Subscript) {\n      const middle_expr = expr(ctx, Op.Root);\n      next_token(ctx); // consume "]"\n      left_expr = subscript(left_expr, middle_expr);\n    } else if (is_postfix_op(op)) {\n      left_expr = postfix(op, left_expr);\n    } else {\n      const right_expr = expr(ctx, op);\n      left_expr = infix(op, left_expr, right_expr);\n    }\n  }\n  return left_expr;\n}\n
\n

Ternary Operator with Optional Else

\n

Modify the ternary operator so : right is optional.

\n

Pair : to the closest unpaired ? so that a ? b ? c : d parses as\na ? (b ? c : d).

\n
ternary_op = "?" expr (":" expr)?\n
\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    if (op === Op.Ternary) {\n      const middle_expr = expr(ctx, Op.Root);\n      let right_expr = null;\n      if (peek_token(ctx) === ":") {\n        next_token(ctx); // consume ":"\n        right_expr = expr(ctx, op);\n      }\n      left_expr = ternary(left_expr, middle_expr, right_expr);\n    }\n    // ...\n  }\n  return left_expr;\n}\n
\n

Non-Associative Operators and Relative Precedence

\n

Non-Associative Operators

\n

Is << left-associative or right-associative?

\n

Since it's not obvious, forgo associativity and instead require disambiguating\nparentheses.

\n

a << b passes because it has one interpretation but a << b << c fails as\nambiguous and requires parentheses to fix.

\n
function error_assoc(op) {\n  return new Error(\n    `Operator "${op}" is not associative and requires parentheses`,\n  );\n}\n\nfunction expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=") {\n      if (assoc(op) === "left") break;\n      if (assoc(op) === "none") throw error_assoc(op);\n    }\n    // ...\n  }\n  return left_expr;\n}\n
\n

Relative Precedence

\n

Is << or ** higher precedence?

\n

Since global precedence is confusing, let's instead define relative precedence\nbetween operator pairs and require parentheses for unrelated operators.

\n

For example, if Precedence(**) > Precedence(/) is the only known precedence\nrelationship, then expect the following parse results:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ExpressionParse ResultParse Trees
a << bOk(a << b)
a ** b / cOk((a ** b) / c)
a ** b << cAmbiguous(a ** (b << c)) and ((a ** b) << c)
a ** (b << c)Ok(a + (b << c))
\n

The parser's cmp_precedence() now returns "!" for unrelated operators.

\n
function error_unrelated_ops(op1, op2) {\n  return new Error(`"${op1}" is unrelated to "${op2}"`);\n}\n\nfunction expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    const order = cmp_precedence(op, parent_op);\n    if (order === "!") throw error_unrelated_ops(op, parent_op);\n    if (order === "<") break;\n    if (order === "=") {\n      if (assoc(op) === "left") break;\n      if (assoc(op) === "none") throw error_assoc(op);\n    }\n    // ...\n  }\n  return left_expr;\n}\n
\n

Precedence Groups

\n

Defining the relative precedence between every pair of operators is unscalable\nin languages with many operators.

\n

One solution is to organize operators into groups that share the same\nassociativity and relative precedence.

\n

Let's define a variety of operators, group them, and define each group's\nrelative precedence.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Precedence GroupOperatorsAssociativityGreater Precedence Than
Postfix++ -- [nonePrefix
Prefix++ -- + - !noneBitwiseShift, Exponentiation
BitwiseShift<< >>noneComparison
Exponentiation**rightMultiplication
Multiplication* / & %leftAddition
Addition+ - |leftComparison
Comparison== != < <= > >=noneConjunction
Conjunction&&leftDisjunction
Disjunction||leftTernary
Ternary?rightRoot
Rootnone
\n

Given precedence P, P(Multiplication) > P(Comparison) because precedence is\ntransitive: P(A) > P(B) and P(B) > P(C) imply P(A) > P(C).

\n

Precedence groups form a digraph. Note how BitwiseShift is unrelated to\nExponentiation, Multiplication, and Addition.

\n

Implementation

\n

Encode the precedence table in TypeScript.

\n
const enum Op {\n  PostfixPlusPlus,\n  PostfixMinusMinus,\n  Subscript,\n  // ... remaining operators\n}\nconst enum Group {\n  Postfix,\n  Prefix,\n  BitwiseShift,\n  // ... remaining groups\n}\nconst groups = [\n  {\n    id: Group.Postfix,\n    ops: [Op.PostfixPlusPlus, Op.PostfixMinusMinus /* , ... */],\n    assoc: "none",\n    gt: [Group.Prefix],\n  },\n  {\n    id: Group.Prefix,\n    ops: [Op.PrefixPlusPlus, Op.PrefixMinusMinus /* , ... */],\n    assoc: "none",\n    gt: [Group.BitwiseShift, Group.Exponentiation],\n  },\n  {\n    id: Group.BitwiseShift,\n    ops: [Op.BitwiseShiftLeft, Op.BitwiseShiftRight],\n    assoc: "none",\n    gt: [Group.Comparison],\n  },\n  // ... remaining groups\n];\n
\n

Precompute mappings from operators to groups and associativities.

\n
const map_op_to_group = new Map<Op, Group>();\nconst map_op_to_assoc = new Map<Op, "left" | "right" | "none">();\n\nfor (const group of groups) {\n  for (const op of group.ops) {\n    map_op_to_group.set(op, group.id);\n    map_op_to_assoc.set(op, group.assoc);\n  }\n}\n
\n

assoc() is a map lookup.

\n
function assoc(op) {\n  return map_op_to_assoc.get(op)!;\n}\n
\n

For each precedence group, precompute lower precedence groups using depth-first\nsearch.

\n
const precedence_gt = new Map<Group, Set<Group>>();\n\nfor (const src of groups) precedence_gt.set(src.id, new Set(src.gt));\nfor (const [_, dsts] of precedence_gt) {\n  const explore = [...dsts];\n  while (explore.length) {\n    const dst = explore.pop()!;\n    dsts.add(dst);\n    const next_dsts = precedence_gt.get(dst)!;\n    for (const new_dst of next_dsts) {\n      if (!dsts.has(new_dst)) {\n        explore.push(new_dst);\n      }\n    }\n  }\n}\n
\n

cmp_precedence() refers to the map.

\n
function cmp_precedence(op1, op2) {\n  const group1 = map_op_to_group.get(op1)!;\n  const group2 = map_op_to_group.get(op2)!;\n  if (group1 === group2) return "=";\n  if (precedence_gt.get(group1)!.has(group2)) return ">";\n  if (precedence_gt.get(group2)!.has(group1)) return "<";\n  return "!";\n}\n
\n

Wrap Up

\n

Error Handling

\n

Handle errors by checking for unexpected tokens.

\n

Start with the head parser.

\n
function error_bad_token(token) {\n  return new Error(`Bad token "${token}"`);\n}\n\nfunction expr_head(ctx) {\n  const token = next_token(ctx);\n  if (token === "(") {\n    const right_expr = expr(ctx, Op.Root);\n    const rparen = next_token(ctx);\n    if (rparen !== ")") throw error_bad_token(rparen, ")");\n    return right_expr;\n  } else if (is_number_token(token)) {\n    return number(token);\n  } else if (is_prefix_op_token(token)) {\n    const op = prefix_op(token);\n    const right_expr = expr(ctx, op);\n    return prefix(op, right_expr);\n  } else {\n    throw error_bad_token(token ?? "EOF");\n  }\n}\n
\n

And now the tail parser.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    const token = peek_token(ctx);\n    if (token === ")" || token === "]" || token === ":") break;\n    const op = tail_op(token);\n    if (op === undefined) throw error_bad_token(token);\n    const order = cmp_precedence(op, parent_op);\n    if (order === "!") throw error_unrelated_ops(op, parent_op);\n    if (order === "<") break;\n    if (order === "=") {\n      if (assoc(op) === "left") break;\n      if (assoc(op) === "none") throw error_assoc(op);\n    }\n    next_token(ctx);\n    if (op === Op.Ternary) {\n      const middle_expr = expr(ctx, Op.Root);\n      let right_expr = undefined;\n      if (peek_token(ctx) === ":") {\n        next_token(ctx);\n        right_expr = expr(ctx, op);\n      }\n      left_expr = ternary(left_expr, middle_expr, right_expr);\n    } else if (op === Op.Subscript) {\n      const middle_expr = expr(ctx, Op.Root);\n      const rbracket = next_token(ctx);\n      if (rbracket !== "]") throw error_bad_token(rbracket);\n      left_expr = subscript(left_expr, middle_expr);\n    } else if (is_postfix_op(op)) {\n      left_expr = postfix(op, left_expr);\n    } else if (is_infix_op(op)) {\n      const right_expr = expr(ctx, op);\n      left_expr = infix(op, left_expr, right_expr);\n    }\n  }\n  return left_expr;\n}\n
\n

Grammar

\n

This is the final grammar.

\n
expr = expr_head expr_tail*\n\nexpr_head = number\n          | prefix_op expr\n\nexpr_tail = infix_op expr\n          | postfix_op\n          | "[" expr "]"\n          | "?" expr (":" expr)?\n
\n

The parser produces syntax trees of this form.

\n
expr = number\n     | prefix\n     | postfix\n     | infix\n     | ternary\n     | subscript\n\nprefix = prefix_op expr\npostfix = expr postfix_op\ninfix = expr infix_op expr\nternary = expr "?" expr (":" expr)?\nsubscript = expr "[" expr "]"\n
\n

Parser

\n

Code for the final parser is\nhere\nIt includes a scanner and makes greater use of types and enums.

\n

Alternative code that uses an explicit stack (instead of the call stack) is\nhere.

\n

Run tests with deno test parser.ts.

\n

Binding Power

\n

Other posts explain Pratt parsing using "binding power."

\n

Each operator is assigned a left and right binding power based on its precedence\nand associativity:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperatorLeft Binding PowerRight Binding PowerNotes
**65Right-associative operators have higher left binding power
*34Left-associative operators have higher right binding power
+12Operators with lower precedence have lower binding powers
-12Operators with the same precedence and associativity have the same binding powers
\n

The condition for exiting a level is simplified to a binding power comparison.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    if (binding_power_right(op) < binding_power_left(parent_op)) break;\n    // ...\n  }\n  return left_expr;\n}\n
\n

I think binding power is less intuitive than the equivalent precedence and\nassociativity checks.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    const order = cmp_precedence(op, parent_op);\n    if (order === "<") break;\n    if (order === "=" && assoc(op) === "left") break;\n    // ...\n  }\n  return left_expr;\n}\n
\n

I think requiring parentheses on expressions that are ambiguous to humans is\ngood language design.

\n
function expr_tail(ctx, parent_op, left_expr) {\n  while (has_token(ctx)) {\n    // ...\n    const order = cmp_precedence(op, parent_op);\n    if (order === "!") throw error_unrelated_ops(op, parent_op);\n    if (order === "<") break;\n    if (order === "=") {\n      if (assoc(op) === "left") break;\n      if (assoc(op) === "none") throw error_assoc(op);\n    }\n    // ...\n  }\n  return left_expr;\n}\n
\n

But binding power requires operators to have global precedence and\nassociativity.

\n","date_published":"Sat, 14 Dec 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/hummus-recipe/","url":"https://dawoodjee.com/blog/hummus-recipe/","title":"Hummus Recipe","content_html":"

Ingredients

\n\n

Steps

\n
    \n
  1. Drain and rinse chickpeas
    2. \n
  2. Add tahini, olive oil, lemon juice, crushed garlic, cumin, and salt to food\nprocessor
    3. \n
  3. Blend until smooth
    4. \n
  4. Add half cup chicpeas and blend until smooth
    5. \n
  5. Add remaining chickpeas and blend until smooth
    6. \n
  6. Add ice or cold water until desired consistency
    7. \n
  7. Serve in wide container, drizzle olive oil, and sprinkle sumac
    8. \n
\n","date_published":"Sat, 19 Oct 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/postgres-timestamp-vs-timestamptz/","url":"https://dawoodjee.com/blog/postgres-timestamp-vs-timestamptz/","title":"Postgres timestamp vs timestamptz","content_html":"

Recommendations

\n\n

Definitions

\n

timestamptz represents a specific instance in universal time. It can be used\nto represent when an account is created, when a user posts a comment, or when a\nmeeting will start. timestamptz is not the combination of a timestamp and a\ntime zone. It is impossible to recover the time zone used to create a\ntimestamptz value.

\n

timestamp represents a conceptual time that might vary based on the frame of\nreference. For example, New Year's Day starts on Janaury 1 at midnight, but\nmidnight occurs at different times across planet Earth. timestamp is not a\ntimestamp relative to the UTC time zone; although the underlying storage format\nand existing misuse may imply as such.

\n

reality is chaos. If you work on a system with different interpretations of\ntimestamp and timestamptz, embracing the chaos may help preserve sanity.

\n

Literals

\n

Timestamps can be created using the ISO 8601 text format.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
typeliteral syntax
timestamptztimestamptz '2004-10-19 10:23:54-07'
timestamptimestamp '2004-10-19 10:23:54'
\n

The optional time zone suffix at the end of a literal indicates the offset\nrelative to UTC, e.g. UTC is UTC+00, PST is UTC-07, and IST is UTC+05:30

\n

If a timestamp is created from a literal with a time zone suffix, the suffix\nwill be silently ignored.

\n
select timestamp '2004-10-19 06:23:54+02';\nselect timestamp '2004-10-19 06:23:54-07';\n-- Both queries return 2004-10-19 06:23:54\n
\n

If a timestamptz is created from a literal without a time zone suffix, the\ntime zone is assumed to be the session time zone.

\n
set timezone = 'America/Los_Angeles';\nselect timestamptz '2004-10-19 06:23:54';\n-- Returns 2004-10-19 06:23:54-07\n\nset timezone = 'America/New_York';\nselect timestamptz '2004-10-19 06:23:54';\n-- Returns 2004-10-19 06:23:54-04\n
\n

Storage

\n

Both timestamp and timestamptz are stored as 64-bit integers representing the\noffset in microseconds since 2000-01-01 00:00:00 UTC.

\n
select extract(epoch from timestamp '2004-10-19 10:23:54');\nselect extract(epoch from timestamptz '2004-10-19 06:23:54-04');\nselect extract(epoch from timestamptz '2004-10-19 03:23:54-07');\n-- All queries return 1098181434\n\nselect extract(epoch from timestamp '2004-10-19 10:23:54')\n     - extract(epoch from timestamp '2000-01-01 00:00:00');\n-- Returns 151496634\n\n-- 151496634 seconds = 151496634000000 microseconds = 0x000089C90F0DE280 microseconds\n-- If you go digging, you'll find 64-bit integer 0x000089C90F0DE280 in memory.\n
\n

Even though timestamp values are stored as offsets relative to the dawn of the\nmillennium in UTC time, they should not be interpreted as timestamps in the UTC\ntime zone. Instead, refer to the prior definition of timestamp.

\n

Note that timestamptz does not store the time zone. The time zone used to\ncreate a timestamptz value cannot be recovered.

\n

Serialization

\n

timestamptz values are serialized using the session time zone.

\n
set timezone = 'America/Los_Angeles';\nselect timestamptz '2004-10-19 06:23:54-03';\n-- Returns 2004-10-19 02:23:54-07\n\nset timezone = 'America/New_York';\nselect timestamptz '2004-10-19 06:23:54-03';\n-- Returns 2004-10-19 05:23:54-04\n
\n

Serialization of timestamp values is time zone independent. The returned value\nmirrors the source literal.

\n
set timezone = 'America/Los_Angeles';\nselect timestamp '2004-10-19 06:23:54';\n-- Returns 2004-10-19 06:23:54\n\nset timezone = 'America/New_York';\nselect timestamp '2004-10-19 06:23:54';\n-- Returns 2004-10-19 06:23:54\n
\n","date_published":"Mon, 06 May 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/kumquat-marmalade-recipe/","url":"https://dawoodjee.com/blog/kumquat-marmalade-recipe/","title":"Kumquat Marmalade","content_html":"

\"Jars

\n

Ingredients

\n\n

Steps

\n
    \n
  1. Wash kumquats and remove blemishes
    2. \n
  2. Slice kumquats into ~3-5mm circular cross sections into dish
    3. \n
  3. Zest lemon into dish
    4. \n
  4. Extract lemon pulp into chunks and remove rind, then add to dish
    5. \n
  5. Weigh mixture, then add 3/4 as much sugar by weight
    6. \n
  6. Mix sugar into mixture
    7. \n
  7. Macerate mixture by letting it sit at room temperature for a couple hours or\novernight in the fridge
    8. \n
  8. Place mixture into pot
    9. \n
  9. (Optionally) grate 1 teaspoon ginger into mixture
    10. \n
  10. Boil mixture on medium heat
    11. \n
  11. Periodically mix with silicon spatula
    12. \n
  12. Take it out when it's ready (watch a video)
    13. \n
  13. Pour hot mixture into sanitized jars and seal
    14. \n
  14. Allow jars to sit until cooled to room temperature
    15. \n
  15. Refrigerate and eat
    16. \n
\n

Notes

\n\n","date_published":"Sun, 10 Mar 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/focused-search-experience/","url":"https://dawoodjee.com/blog/focused-search-experience/","title":"Focused Search Experience","content_html":"

Focus is precious. It's a necessary ingredient of usefully invested time, but\ncomes in short supply and wastes easily, which means it should be guarded and\nused strategically.

\n

Distraction is a major cause of waste. I've taken measures to fight distractions\nin my search experience because my useful work involves lots of searching.

\n

Overview

\n

This is my search experience:

\n

\n

And this is how it works:

\n\n

Google Programmable Search Engine

\n

I'm surprised Google wants anyone to user a search engine that's not google.com,\nbut Programmable Search Engine exists, somehow. It competes with the likes of\nAlgolia by offering customized website search as a service, but it also works as\na standalone search tool.

\n

This is how it compares to google.com:

\n

Pros

\n\n

Cons

\n\n

My custom search engine\nconfiguration filters out websites that make life worse for various reasons.

\n\n

This is my current blocklist:

\n
*.itnext.io/*\n*.dev.to/*\n*.tiktok.com/*\n*.quora.com/*\n*.w3schools.com/*\n*.facebook.com/*\n*.pinterest.com/*\n*.instagram.com/*\n*.medium.com/*\n*.linkedin.com/*\n*.twitter.com/*\n*.ycombinator.com/*\n*.reddit.com/*\n
\n

I also updated my custom search engine to return 20 results per page instead of\nthe default 10 to reduce the need to click the next page button.

\n

uBlock Origin

\n

The user experience of Google Programmable Search Engine is terrible because ads\nuse up the entire viewport on the results page, forcing users to scroll down to\nsee any results.

\n

\"A

\n

Examples like this show how the quest for monetization has rendered the web\nunusable. Ad blockers exist to defend ourselves from this malpractice.

\n

uBlock Origin is the content blocking web extension. It blocks ads on the\nsearch results page by default. This is the result.

\n

\"A

\n

Much better! But it can be refined further:

\n\n

This is the result:

\n

\"Search

\n

And these are the underlying uBlock Origin filters:

\n
cse.google.com##body:style(width: 580px; margin: auto)\ncse.google.com###cse-search-form:style(width: 580px !important; padding: 0 12px !important)\ncse.google.com##.gsib_b,.gsc-search-button,.gsc-above-wrapper-area\ncse.google.com##.gsc-adBlock,#cse-footer,.gcsc-find-more-on-google-branding\n
\n

Unfortunately, there's no way to get around the reCAPTCHA.

\n

\"I

\n

Firefox

\n

Almost all of my searches begin in Firefox, which I use because it best supports\nuBlock Origin\ntoday and in the\nlong term.

\n

I start by typing cmd + L to select Firefox's search bar and begin typing my\nquery. Helpful suggestions appear to save me keystrokes and send me where I want\nto go.

\n

\"Search

\n

I lied. The default suggestions UI is terrible for the usual reason,\nmonetization. I actually don't want any suggestions.

\n\n

Firefox makes it somewhat tedious, but I was able to disable all suggestions. In\nthe process, I also set the default search engine to my custom search engine and\nswitched to a light browser theme.

\n

\"Search

\n

What's next?

\n

Mission accomplished. I created a distraction-free search experience.

\n

But it's sad to think about the lost potential of people without the ability or\ndetermination to take similar measures. While a few people might come across\nthis post and learn a trick or two to better their search experience, I think it\nwould be far more valuable to the world if there were a more accessible way to\napply anti-distraction measures. I shared some thoughts on this in\nmy Web Agency post.

\n

If I could wave a magic wand to change one thing in my setup, it would be for\nSafari to support the web extension APIs needed by uBlock Origin. I like the\nminimalism of desktop Safari's controversial compact-mode UI, which embeds the\nsearch bar in the active tab widget and themes the toolbar to blend in with the\ncurrent website.

\n","date_published":"Thu, 07 Mar 2024 00:00:00 GMT","date_modified":"Sun, 10 Mar 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/web-agency/","url":"https://dawoodjee.com/blog/web-agency/","title":"Web Agency","content_html":"

Reader mode is a fantastic browser feature because it standardizes how content\nis displayed across disparate websites, removing distractions and the need to\nlearn each website's bespokoe interface. RSS readers take this concept to its\nextreme by automatically providing a standardized feed of content, removing the\nneed to navigate custom UIs to find content. Which is great when you know\nbefore-hand what content you care about, but doesn't address the need for\ncontent-on-demand. If you're listening to a song and find yourself interested in\nthe history behind it, then you'll need to search for it and navigate the web to\nfind it. It's the year 2024, and you might be able to use an LLM to find the\nanswer, skipping the whole web maze, but at least for now LLMs I use don't\nprovide the context or level of trust I want.

\n

So you go through this web maze and each page provides its own unique experience\nusually optimized for keeping you in the network or showing you ads. You've\ntrained yourself to ignore the extraneous, intrusive information and manage to\nfind the information you want. Or maybe you didn't. Perhaps you clicked on an ad\ninterleaved with the content you actually care about (e.g. on Google Search or\nReddit) or perhaps you saw a suggestion for a relation question or topic you\nmight be interested in and followed it, or perhaps a video thumbnail caught your\nattention, and before you know it, you forget the original intent of your\nsearch.

\n

Digressing from the negative effects of platform incentives, you might find\nyourself on a website that is optimized for conveying the information you want.\nBut you still have to understand its UI and the presentation might slow you\ndown; perhaps the text is too small, the font is illegible, the sidebars push\nin-network content, there's a like count at the top, there are low-value user\ncomments, there's a waste-of-(mental)-space stock image at the top... you get\nthe point. Reader mode is supposed to eliminate these details. But reader mode\ndoesn't work everywhere, it removes features that help you navigate and interact\nin useful ways, its heuristic algorithm sometimes removes content you care\nabout, and you have to manually enable (and disable) it.

\n

What we really need is a way to standardize the experience of each website to\nour preference, with ways to remove specific UI elements we don't care about,\nstandardize presentational details like fonts and page alignment, and\nconfigurable presets so we don't have to define everything ourselves. Basically,\nwe need a user-agent that gives me agency over the web in a nice usable package.\nFor example, I hate profile images because they steal focus use up valuable\nspace, so I want them all gone across all websites. I want my browser to have a\n"turn off profile images across all websites" checkbox. This functionality\ndoesn't exist because every website is different and there is no universal way\nto identify profile images. We actually need to hardcode this logic for every\nwebsite, which appears infeasible. But is it really?

\n

The 80/20 rule applies but in this case I think it's really a 99.9/0.01 rule. We\ndon't need to hardcode logic for every website on the internet, we just need\nrules for the tiny minority of websites that account for the majority of use. I\nprefer not to see profile images at all, but if they're removed from the top 100\nwebsites I visit, then I only risk seeing them rarely, which is practically\nequivalent to never. Great... so I only need to write rules for 100 websites.\nI'm lazy, so that's about 100 too many, and I'm unwilling to invest the time\nunless I'm on an OCD stint.

\n

What I really want is for something or someone else to do the work of writing\nthe rules so I can enjoy the fruits of their labor without lifting a finger\nmyself. I can think of three realistic options:

\n
    \n
  1. Outsource the work to a hard-working, altruistic benefactor who takes\nownership of the rules. This is akin to filter lists used by ad blockers.\nTens of someones do the hard, thankless work of writing and updating these\nlists to save hundreds of millions of people billions of hours annually. In\nbig-tech world where quantifying impact is supposedly important, those\nnumbers are crazy to think about. If you care about effective charity, then\nmaybe these someones deserve something.
    2. \n
  2. Crowdsource the rules so that many less hard-working people can contribute a\nlittle. Wikipedia, SponsorBlock, and crowd-sources translation platforms are\nprominent examples. The challenge here is moderation, preventing abuse, and\nfiltering low-quality contributions. SponsorBlock is interesting because\nthere is a right answer: given a video timeline, there are specific objective\ntime segments containing sponsored ads. This makes crowdsourcing a little\neasier. Wikipedia and crowd-translation platforms are a little tricker and\nrequire heavier moderation because there is no right answer. I think website\ncontent rules lean toward the objective, but there are still multiple ways to\nachieve the same result.
    3. \n
  3. Have machines devise the rules. What was unachievable just 2 years ago can\nsuddenly be done with the power of AI, particularly gen-AI. Whereas in the\npast you might attempt to create heuristic algorithms that sort of worked\nhalf the time, today you can use gen-AI, and it works great most of the time.\nYou just have to figure out how to get data into the system and pay for GPUs.
    4. \n
\n

These options are not mutually exclusive and in my opinion are all worth\nexploring. Once you have some sort of system for defining rules, the next\nquestion is how do you make them accessible to users. A web extension is the\nobvious answer, but how should it be designed so that users can easily\nunderstand and customize rules to their preference? That will have to wait for\nmy next blog post.

\n","date_published":"Fri, 23 Feb 2024 00:00:00 GMT","date_modified":"Thu, 07 Mar 2024 00:00:00 GMT"},{"id":"https://dawoodjee.com/blog/design-of-this-website/","url":"https://dawoodjee.com/blog/design-of-this-website/","title":"Design of this Website","content_html":"

For a while now, I’ve wanted to blog about topics I think are interesting or\nmight be useful to others. This post explains why I needed a website and how I\nbuilt it.

\n

Why not Social Media or Hosted CMSs

\n

Ownership is important to me because I want to control how my content is used\nand communicated. I don’t want my content presented alongside ads, cookie\nbanners, subscription dialogs, or algorithmic feeds optimized for engagement.\nI’m fortunate enough to be able to offer my content free of charge or\nencumbrances and hopefully it’s worth that price. This purism precludes using\nsocial media platforms like Medium, Substack, or Dev Community.

\n

This left me with the choice of either a hosted CMS like Wordpress or the tried,\nold method of a custom website. Unfortunately, the easy hosted option isn’t for\nme since I prefer managing content in markdown files that can be opened with a\nlocal text editor, version-controlled with Git, and understood by many useful\ntools. The hosted option would also likely involve battling an unfamiliar\nmonolith to achieve my preferred customizations. Fortunately, as a professional\nsoftware dude, I know how to build a website.

\n

The Static Website Tech Stack

\n

Maintenance is the bane of my existence, so servers that might go down and\nservices that require an up-to-date credit card are out of the question. Luckily\nGitHub Pages exists, and it offers free static website hosting. It just means my\nwebsite won’t support dynamic content, which I don’t want anyways because for\nblogs, dynamic content usually means social features like commenting, liking,\nand sharing. I think social features, which are usually designed to promote\nengagement and distribution, are almost always anti-features, since they\ndistract from the main message and consume users’ limited attention.

\n

Knowing I wanted a static website, the next step was to decide on a static\nwebsite builder. Because TypeScript is my most productive language and I hate\nwasting time on setup and tooling, I decided to use Deno, a\nbatteries-included TypeScript runtime. I Googled “deno ssg,” found\nLume, and never looked back because it just worked.

\n

Lume is just another static site generator. Raw content files go in, beautiful\n(or, if we’re being honest, usually ugly) website comes out. In my case, I\nwanted to use markdown to write blog posts and JSX to define its presentation.\nMarkdown is simple, reduces the friction of writing and editing rich(ish) text\ndocuments, and is well supported by editors and tooling. JSX is simple,\npowerful, and saves me from having to learn bespoke templating languages of\nwhich Lume has its own. Lume natively supports Markdown and setting up the\nfirst-party JSX plugin took me 5 minutes.

\n

Setting up hosting and DNS to actually get the static websites deployed at\nhttps://dawoodjee.com was straightforward. I use Namecheap for domain\nregistration since it’s done the job well for me for years, Cloudflare for easy\nDNS configuration and fast nameservers, and Lume’s stock template for deploying\nto GitHub Pages with GitHub Actions.

\n

I could have reduced complexity and save an hour by deploying to a github.io\nsubdomain, but using my own domain helps me retain control of my content. I can\nshift the underlying infrastructure, perhaps by switching from Github pages to\nGitLab Pages, without breaking the user-facing API: URLs.

\n

Designing the Website

\n

With the basic tech stack decided, the next step was to design the website. I\nfollowed this principle: less is more because extraneous content distracts\nfrom the core message. There would be no about page, no contacts page, no\nhamburgers or kabobs; just a home page with basic information and links to blog\nposts.

\n

Branding helps with recognition, so I added a simple tuxedo cat avatar to the\ntop of the page that also serves as a link to the home page. I created a footer\nwith a few useful tools: a search box (that directs queries to a site-scoped\nGoogle search), a link to the page’s underlying file in GitHub in case I want to\nmake a quick edit or someone identifies a typo, and feed links for eccentrics\nlike me.

\n

Blog posts follow this basic structure: first the title, then basic metadata,\nthen tags, and finally the content. I call it “basic metadata” because I think\nbasically everything on the internet should have it. It peeves me when an\narticle is not accompanied by its author or publish date. Why should I trust\nwhatever is written if no accountable name is attached? How do you know whether\nthe information is still relevant or hopelessly outdated? I considered adding\ntime-to-read estimates, but decided not to, since it’s unclear to me if they are\nactually useful. Email me if you know a compelling reason to include them.

\n

I have mixed feelings about tags because it’s hard to decide on and easy to miss\nappropriate tags. I chose to include them for now because they help readers\nquickly identify topics that aren’t of interest. I look forward to a future in\nwhich tags are AI-generated based on the content of blog posts. The future is\nprobably the present, but Lume doesn’t have a first-party plugin.

\n

Retrospective

\n

Well, dawoodjee.com is online and I’m on the tail end of my first blog post. Did\nI succeed? In terms of building a blog in which I retain full control, Yes. In\nterms of building a compelling blogging experience, Yes. In terms of building a\nlow maintenance website… I’m optimistic but uncertain. I’ll check back again\nlater, perhaps in a year, to see if I’m still happy. Hopefully nothing breaks\nand Dependabot security alerts skip my inbox.

\n","date_published":"Tue, 20 Feb 2024 00:00:00 GMT","date_modified":"Thu, 07 Mar 2024 00:00:00 GMT"}]}