Skip to content

docs: rename LogoScript -> iklo in refs/ucblogo (project's current name) #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
owkwo-bot wants to merge 1 commit into
base: main
from
+9 −9
Open

docs: rename LogoScript -> iklo in refs/ucblogo (project's current name) #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions refs/ucblogo/summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
---
**Document:** Berkeley Logo (UCBLogo) Reference
**Purpose:** Authoritative documentation of UCBLogo semantics — the stable foundation that LogoScript builds on and extends. Not a LogoScript spec; read this to understand the baseline, then see AGENTS.md for deviations.
**Purpose:** Authoritative documentation of UCBLogo semantics — the stable foundation that iklo builds on and extends (iklo is the second iteration of this project; the first was named LogoScript). Not an iklo spec; read this to understand the baseline, then see AGENTS.md for deviations.
**Audience:** Language semanticists, logo interpreters, AI agents reasoning about Logo behavior.
**Last Updated:** 2026-07-01 (stable)
**Sources:**
- Brian Harvey, "Computer Science Logo Style", 2nd ed., Vols. 1–3, MIT Press, 1997.
- Berkeley Logo Reference Manual (appendix to Vol. 2, pp. 267–309).
- Berkeley Logo source: https://people.eecs.berkeley.edu/~bh/logo.html
**Cross-refs:**
- [AGENTS.md](../../AGENTS.md) — LogoScript deviations and extensions
- [spec/backlog.md](../../spec/backlog.md) — implementation status of LogoScript features (and the per-epic specs under [spec/](../../spec/))
**Important:** Examples here use UCBLogo syntax. LogoScript syntax differs significantly: see AGENTS.md introduction for key differences.
- [AGENTS.md](../../AGENTS.md) — iklo deviations and extensions, and what's actually implemented today
- [specs/](../../specs/) — per-epic feature specs (Spec Kit layout); implementation status lives in each epic's own `tasks.md` and in [specs/execution-queue.md](../../specs/execution-queue.md)
**Important:** Examples here use UCBLogo syntax. iklo syntax differs significantly: see AGENTS.md introduction for key differences.
---

# Berkeley Logo (UCBLogo) Reference

This file is the **stable reference for UCBLogo semantics**. It is *not* a LogoScript spec, and LogoScript does **not** inherit from it: UCBLogo is a **comparison baseline and a source of inspiration**, not a compatibility target ([ADR-0008](../../design/decisions/ADR-0008-ucblogo-is-inspiration-not-a-compatibility-target.md)). Read it to understand what UCBLogo does; consult `AGENTS.md` for what LogoScript does.
This file is the **stable reference for UCBLogo semantics**. It is *not* an iklo spec, and iklo does **not** inherit from it: UCBLogo is a **comparison baseline and a source of inspiration**, not a compatibility target (`LANGUAGE.md`'s own introduction: "It is *intentionally* similar to 80's Logo, taking inspiration particularly from UCBLogo"). Read it to understand what UCBLogo does; consult `AGENTS.md` for what iklo does.

> **Note on code examples**: All examples here use **UCBLogo syntax**. LogoScript deviates in several places — most notably: procedure bodies use `is ... end` instead of just `end`; conditionals use `if <cond> then ... else ... end` instead of `if <cond> [...]`; word literals use `'word` (single quote) instead of `"word`; comments use `#` (`;` is deprecated; `//` and `/* */` were removed by Grammar 2.0 §13b); scope is lexical by default; and there is no `catch`/`throw` — errors are values ([ADR-0009](../../design/decisions/ADR-0009-errors-are-values-no-exceptions.md)). Read the examples for their semantic content; do not copy UCBLogo syntax directly into LogoScript.

ghost Sep 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: The syntax note says Iklo word/string literals use "word, but Iklo's current reference distinguishes token literals such as 'foo from string literals such as "hello". Readers following this note treat a string as a token/word and write the wrong syntax or semantics.

Suggested fix: Describe the two forms separately, e.g. token literals use bare tokens or 'foo where quoting is required, while strings use "hello".

ghost Sep 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: The note presents cond and do ... end as current Iklo deviations, but AGENTS.md says anything not listed as implemented is aspirational, and the execution queue still lists cond as work to be implemented. A reader copying the supposedly current syntax receives syntax that the current implementation does not support.

Triggers: When a reader uses this actively referenced document to write code against the current implementation.

Suggested fix: Mark these constructs as aspirational/planned, or describe only the syntax currently implemented and link to the relevant spec for future syntax.

> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.

ghost Sep 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Do not present cond and do ... end as implemented syntax unless the current implementation supports them. Mark planned forms as aspirational or document only supported syntax, otherwise readers will copy unsupported code from this reference.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At refs/ucblogo/summary.md, line 20:

<comment>Do not present `cond` and `do ... end` as implemented syntax unless the current implementation supports them. Mark planned forms as aspirational or document only supported syntax, otherwise readers will copy unsupported code from this reference.</comment>

<file context>
@@ -1,23 +1,23 @@
+This file is the **stable reference for UCBLogo semantics**. It is *not* an iklo spec, and iklo does **not** inherit from it: UCBLogo is a **comparison baseline and a source of inspiration**, not a compatibility target (`LANGUAGE.md`'s own introduction: "It is *intentionally* similar to 80's Logo, taking inspiration particularly from UCBLogo"). Read it to understand what UCBLogo does; consult `AGENTS.md` for what iklo does.
 
-> **Note on code examples**: All examples here use **UCBLogo syntax**. LogoScript deviates in several places — most notably: procedure bodies use `is ... end` instead of just `end`; conditionals use `if <cond> then ... else ... end` instead of `if <cond> [...]`; word literals use `'word` (single quote) instead of `"word`; comments use `#` (`;` is deprecated; `//` and `/* */` were removed by Grammar 2.0 §13b); scope is lexical by default; and there is no `catch`/`throw` — errors are values ([ADR-0009](../../design/decisions/ADR-0009-errors-are-values-no-exceptions.md)). Read the examples for their semantic content; do not copy UCBLogo syntax directly into LogoScript.
+> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
 
 *Sources:*
</file context>
Suggested change
> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
+> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use planned `cond` forms instead of `if <cond> [...]`; token literals use bare tokens or `'foo` where quoting is required, while strings use `"hello"`; comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.

ghost Sep 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Listing "word (double quote) as a deviation is contradictory: that is the same leading sigil UCBLogo uses for word literals, so it doesn't illustrate a difference, and iklo's actual string literal is "..." (opening and closing quotes, per LANGUAGE.md). This is the foot-gun the PR was fixing — one stale claim traded for a muddy one.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At refs/ucblogo/summary.md, line 20:

<comment>Listing `"word` (double quote) as a deviation is contradictory: that is the same leading sigil UCBLogo uses for word literals, so it doesn't illustrate a difference, and iklo's actual string literal is `"..."` (opening and closing quotes, per LANGUAGE.md). This is the foot-gun the PR was fixing — one stale claim traded for a muddy one.</comment>

<file context>
@@ -1,23 +1,23 @@
+This file is the **stable reference for UCBLogo semantics**. It is *not* an iklo spec, and iklo does **not** inherit from it: UCBLogo is a **comparison baseline and a source of inspiration**, not a compatibility target (`LANGUAGE.md`'s own introduction: "It is *intentionally* similar to 80's Logo, taking inspiration particularly from UCBLogo"). Read it to understand what UCBLogo does; consult `AGENTS.md` for what iklo does.
 
-> **Note on code examples**: All examples here use **UCBLogo syntax**. LogoScript deviates in several places — most notably: procedure bodies use `is ... end` instead of just `end`; conditionals use `if <cond> then ... else ... end` instead of `if <cond> [...]`; word literals use `'word` (single quote) instead of `"word`; comments use `#` (`;` is deprecated; `//` and `/* */` were removed by Grammar 2.0 §13b); scope is lexical by default; and there is no `catch`/`throw` — errors are values ([ADR-0009](../../design/decisions/ADR-0009-errors-are-values-no-exceptions.md)). Read the examples for their semantic content; do not copy UCBLogo syntax directly into LogoScript.
+> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
 
 *Sources:*
</file context>
Suggested change
> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
word/string literals use double-quoted `"..."` strings (open and close);

ghost Sep 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The deviation note says only "comments use #", silently dropping that ; is iklo's hard terminator — yet this whole doc's examples use UCBLogo ;-comments, so a reader copying them into iklo would hit parse errors. The PR description says this correction ("; as terminator") was intended, but it isn't in the committed text. Add ; as a hard terminator to the note.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At refs/ucblogo/summary.md, line 20:

<comment>The deviation note says only "comments use `#`", silently dropping that `;` is iklo's hard terminator — yet this whole doc's examples use UCBLogo `;`-comments, so a reader copying them into iklo would hit parse errors. The PR description says this correction ("`;` as terminator") was intended, but it isn't in the committed text. Add `;` as a hard terminator to the note.</comment>

<file context>
@@ -1,23 +1,23 @@
+This file is the **stable reference for UCBLogo semantics**. It is *not* an iklo spec, and iklo does **not** inherit from it: UCBLogo is a **comparison baseline and a source of inspiration**, not a compatibility target (`LANGUAGE.md`'s own introduction: "It is *intentionally* similar to 80's Logo, taking inspiration particularly from UCBLogo"). Read it to understand what UCBLogo does; consult `AGENTS.md` for what iklo does.
 
-> **Note on code examples**: All examples here use **UCBLogo syntax**. LogoScript deviates in several places — most notably: procedure bodies use `is ... end` instead of just `end`; conditionals use `if <cond> then ... else ... end` instead of `if <cond> [...]`; word literals use `'word` (single quote) instead of `"word`; comments use `#` (`;` is deprecated; `//` and `/* */` were removed by Grammar 2.0 §13b); scope is lexical by default; and there is no `catch`/`throw` — errors are values ([ADR-0009](../../design/decisions/ADR-0009-errors-are-values-no-exceptions.md)). Read the examples for their semantic content; do not copy UCBLogo syntax directly into LogoScript.
+> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
 
 *Sources:*
</file context>
Suggested change
> **Note on code examples**: All examples here use **UCBLogo syntax**. iklo deviates in several places — most notably: procedure bodies use `do ... end` instead of just `end`; conditionals use `cond` forms instead of `if <cond> [...]`; word/string literals use `"word` (double quote); comments use `#`; scope is lexical by default; and there is no `catch`/`throw` — errors are values, not exceptions (`LANGUAGE.md`: "should *not* be implemented like standard OOP-like exceptions, but use a simpler mechanism based on returning sum types"). Read the examples for their semantic content; do not copy UCBLogo syntax directly into iklo.
comments use `#` (and `;` is a hard terminator, not a comment);


*Sources:*
- *Brian Harvey, "Computer Science Logo Style", 2nd ed., Vols. 1–3, MIT Press, 1997.*
Expand Down Expand Up @@ -175,7 +175,7 @@ end

- **Global variables**: created by `make` at top level, or `make` inside a procedure if not locally declared
- **Local variables**: procedure inputs (`:name`) + explicitly declared with `local "name`
- **Dynamic scope** *(UCBLogo)*: subprocedures can read/write variables of their calling procedures — this is intentional in Berkeley Logo. **LogoScript uses lexical scope by default**, so this pattern does not apply unless dynamic scope is explicitly opted into.
- **Dynamic scope** *(UCBLogo)*: subprocedures can read/write variables of their calling procedures — this is intentional in Berkeley Logo. **iklo uses lexical scope by default**, so this pattern does not apply unless dynamic scope is explicitly opted into.
- `:name` is syntactic sugar for `thing "name` — the colon is an abbreviation for `thing`, not for the combination of colon+name
- `local [var1 var2]` declares multiple locals at once
- `localmake "var value` = `local "var` + `make "var value` (library procedure)
Expand All @@ -184,7 +184,7 @@ end
### Dynamic Scope Example

```logo
; UCBLogo dynamic scope — works in UCBLogo, NOT by default in LogoScript
; UCBLogo dynamic scope — works in UCBLogo, NOT by default in iklo
to water :pitcher
output item :pitcher :state ; accesses :state from calling procedure
end
Expand Down
2 changes: 1 addition & 1 deletion refs/ucblogo/understanding-ucblogo-evaluator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Understanding the UCBLogo evaluator

> **Provenance.** Attributed to **Brian Harvey** (University of California, Berkeley),
> from the UCBLogo distribution. Reproduced here as a design reference for LogoScript.
> from the UCBLogo distribution. Reproduced here as a design reference for iklo.
> The exact upstream source URL was not recorded when this file was added — **TODO**.
> See [`../README.md`](../README.md) for licensing of the material under `refs/`.
>
Expand Down