Docs: document operator support (full prefix + infix; postfix unsupported by design) #31

New issue

Closed

opened 2026-06-02 20:09:28 +00:00 by navicore · 1 comment

navicore commented

2026-06-02 20:09:28 +00:00

Owner

Summary

Document the operator model explicitly: prlg supports prefix and
infix operators, and postfix is not supported — by design. Users coming
from teaching texts (e.g. Clause and Effect) reasonably assume all three
fixities plus op/3; the docs should set the boundary clearly.

What to document

Operator table. The supported prefix and infix operators with their
precedence and type (xfx/xfy/yfx, fy/fx), so users know exactly what parses.
Canonical form is always available. Every operator term is sugar for a
compound: 2 + 3 ≡ +(2, 3), - a ≡ -(a). Anything writable with an
operator is writable in functor notation.
Postfix is unsupported, intentionally. State plainly that there are no
postfix operators and none are planned. Rationale worth including:
- Postfix is pure syntactic sugar — zero expressive power. X yf is just the
  compound yf(X); the term, and therefore everything unification/resolution
  sees, is identical.
- ISO/standard Prolog ships no built-in postfix operators either; the
  standard only defines the postfix types so a program could declare one
  via op/3.
- op/3 (user-defined operators of any fixity) is also not supported, so
  there is no path to a postfix operator at all.
Known quirks to call out: -3 folds to a negative number, not the
compound -(3) (use - a / - X for prefix-as-term examples).

Prerequisite

The "full prefix + infix" claim is only accurate once the operator table is
complete — currently blocked by:

#28 — missing prefix operators (+, \)
#29 — missing infix operators (** ^ >> << xor div /\ \/ :)

Write the documentation to match the table after those land (or document the
current subset honestly in the meantime).

Context

Drives the loglings operator chapter, where we teach prefix + infix as
runnable lessons and present postfix as "the language has it; this engine is a
deliberate subset" — so accurate engine docs let the curriculum cite them.

Reported against prlg 0.4.1.

## Summary Document the operator model explicitly: `prlg` supports **prefix** and **infix** operators, and **postfix is not supported — by design**. Users coming from teaching texts (e.g. *Clause and Effect*) reasonably assume all three fixities plus `op/3`; the docs should set the boundary clearly. ## What to document 1. **Operator table.** The supported prefix and infix operators with their precedence and type (xfx/xfy/yfx, fy/fx), so users know exactly what parses. 2. **Canonical form is always available.** Every operator term is sugar for a compound: `2 + 3` ≡ `+(2, 3)`, `- a` ≡ `-(a)`. Anything writable with an operator is writable in functor notation. 3. **Postfix is unsupported, intentionally.** State plainly that there are no postfix operators and none are planned. Rationale worth including: - Postfix is pure syntactic sugar — zero expressive power. `X yf` is just the compound `yf(X)`; the term, and therefore everything unification/resolution sees, is identical. - ISO/standard Prolog ships **no** built-in postfix operators either; the standard only defines the postfix *types* so a program could declare one via `op/3`. - `op/3` (user-defined operators of any fixity) is also not supported, so there is no path to a postfix operator at all. 4. **Known quirks** to call out: `-3` folds to a negative *number*, not the compound `-(3)` (use `- a` / `- X` for prefix-as-term examples). ## Prerequisite The "full prefix + infix" claim is only accurate once the operator table is complete — currently blocked by: - #28 — missing prefix operators (`+`, `\`) - #29 — missing infix operators (`** ^ >> << xor div /\ \/ :`) Write the documentation to match the table *after* those land (or document the current subset honestly in the meantime). ## Context Drives the `loglings` operator chapter, where we teach prefix + infix as runnable lessons and present postfix as "the language has it; this engine is a deliberate subset" — so accurate engine docs let the curriculum cite them. --- Reported against `prlg` 0.4.1.

navicore referenced this issue

2026-06-02 23:11:23 +00:00

doc sync #35

navicore commented

2026-06-02 23:11:48 +00:00

Author

Owner

#35

https://git.navicore.tech/navicore/patch-prolog/pulls/35

navicore closed this issue

2026-06-02 23:11:48 +00:00