RayPals/Claro
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

refactor: keep Claro in one strict C89 source file

Browse Source
This commit is contained in:
Hermes Agent
2026-10-20 16:12:26 +00:00
parent dd7e8b8b20
commit 8ea2f772cd
59 changed files with 8353 additions and 1289 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+33 -277
View File
@@ -2,311 +2,67 @@
<img src="assets/Claro_Logo.jpg" alt="Claro logo" width="160">
**Claro** is a small, readable scripting language for beginners. It is designed to make programming approachable without requiring punctuation-heavy syntax, while still providing a path toward functions, types, objects, files, packages, and networking.
**A learning tool first. A programming language second.**
Current release: **v2026.10.20.155641**
Claro helps beginners learn programming through readable commands, simple rules,
and small programs. Accessibility for people with learning disabilities is a
core design goal; it still needs testing with learners.
## Versioning
Current release: **v2026.10.20.160950**
Development/release runs use their current UTC date and time: `vYYYY.MM.DD.HHMMSS`.
Stamp once at the beginning of each run, then build:
## Start here
```bash
python3 tools/stamp_version.py
make
```
1. [Build and run Claro](docs/QUICK_START.md).
2. [Try your first programs](docs/FIRST_HOUR.md).
3. [Follow the ten lessons](lessons/README.md), one at a time.
Ordinary rebuilds retain the run version. The stamp updates current runtime,
IDE metadata, generated project/lockfile versions, validators, and current docs;
historical release records remain unchanged. Existing lockfiles from a previous
run can be refreshed with `claro package lock`.
## Quick start
Claro's learning-first development charter and current priorities are in
[`docs/LEARNING_FIRST.md`](docs/LEARNING_FIRST.md). It supersedes older
feature-expansion priorities for current development; historical roadmaps remain
available as project history.
Build Claro with a C99 compiler and `make`:
Build with a C89 compiler and `make`, then run the first lesson:
```bash
make
```
Run a script:
```bash
./claro lessons/01_hello.claro
./claro examples/quiz.claro
```
Check a script without running it:
On Windows, see the [quick start](docs/QUICK_START.md) for build instructions.
```bash
./claro check examples/quiz.claro
```
Run the built-in test suite and validation checks:
```bash
./claro test
./claro validate
```
Useful commands:
```text
claro help
claro --version
claro doctor
claro examples
claro repl
claro new MyProject
claro run
claro fmt file.claro
claro typecheck file.claro
```
## First Claro program
## Your first program
```claro
SAY "Hello from Claro!"
SAY "Hello!"
ASK "What is your name?" name
SAY "Hello " + name
```
Claro accepts both the short beginner-friendly form and older compatibility forms. For example, these are both valid:
Start with input/output, variables, basic math, decisions, loops, lists,
simple functions, and saving text. You do not need classes, packages,
networking, or advanced types to learn with Claro.
```claro
SET name "Jon"
SET name TO "Jon"
```
## Find your way
## Core language features
- `lessons/` — small, ordered lessons.
- `examples/` — programs to try and change.
- [Documentation](docs/README.md) — learning guides and reference.
- [Current roadmap](docs/ROADMAP.md) — the small set of active priorities.
- [Learning-first rules](docs/LEARNING_FIRST.md) — how Claro is designed.
- [Contributing](CONTRIBUTING.md) — source layout, builds, and validation.
### Decisions and loops
Existing features and compatibility syntax remain supported; they are not
required for the beginner path. Experimental features are described in the
[detailed status](docs/CURRENT_STATUS.md), not promised as ready.
```claro
SET score 10
Claro scripts run with your permissions. Run only scripts you trust.
IF score >= 5
SAY "Good job!"
ELSE
SAY "Try again."
END
## Single-file C89 interpreter
DO 3 TIMES
SAY "Practice"
DONE
```
### Lists and maps
```claro
SET names AS LIST OF TEXT TO LIST
ADD "Ada" TO names
ADD "Grace" TO names
FOR EACH name IN names
SAY name
DONE
```
### Functions
```claro
TEACH greet name
SAY "Hello " + name
END
DO greet "Jon"
```
The older compatibility syntax remains supported:
```claro
TEACH greet TAKES name
RETURN "Hello " + name
LEARNED
CALL greet WITH "Jon"
SAY RESULT
```
### Objects and classes
```claro
CLASS Player
HAS name TEXT
HAS score NUMBER
TEACH add points
SET score score + points
END
END
NEW Player player
SET player.name "Jon"
SET player.score 10
DO player.add 5
SAY player.score
```
### Type checking
Type annotations are optional for beginners:
```claro
SET score NUMBER 10
SET name TEXT "Jon"
SET ready YESNO YES
CHECK TYPE score IS NUMBER
```
Run static checks with:
The complete runtime is in [`src/claro.c`](src/claro.c). Build it directly:
```bash
./claro typecheck examples/type_hardening.claro
gcc -std=c89 -pedantic-errors src/claro.c -o claro -lm
```
Claro provides learner-facing diagnostics for many incorrect variable, function, method, and object-field types. For an explicitly typed object field, the separated form needs both `AS TYPE TO value`, so `SET player.score AS NUMBER` explains how to add `TO` and a value. Type checking is still a focused foundation rather than a complete static type system.
## Files, JSON, and standard helpers
Claro includes commands and libraries for practical scripts:
```claro
WRITE FILE "note.txt" WITH "Hello from Claro"
READ FILE "note.txt" AS note
SAY note
```
Standard-library modules include path and collection helpers:
```claro
IMPORT "lib/path.claro" AS path
CALL path.join WITH "notes", "today.txt"
SAY RESULT
```
See `docs/STDLIB.md` for the current helper API.
## Projects and packages
Create a project:
```bash
claro new MyProject
cd MyProject
claro run
```
Manage local project packages:
```bash
claro package init
claro package add text
claro package list
claro package doctor
claro package lock
```
Project metadata is stored in:
```text
claro.project
claro.lock
packages/
```
The current package system is local and foundational. Remote registries, publishing, version constraints, and package signature verification are not yet stable features.
## Networking
Claro supports beginner-oriented HTTP commands and offline `claro://` test URLs:
```claro
HTTP GET "claro://hello" AS page STATUS status
SAY page
SAY status
```
Real HTTP and HTTPS requests use `curl` when available. The offline URLs make networking lessons and tests deterministic.
## Current status
### Stable foundation
- Variables, output, input, expressions, and control flow
- Loops, lists, maps, text, JSON, and file operations
- Functions and compatibility syntax
- Friendly errors and script checking
- Path and collection helpers
- Offline networking examples
### Foundation present
- Static type checking
- Objects and classes
- Local projects and packages
- Networking beyond the offline test layer
- Cooperative tasks/concurrency helpers
- IDE metadata and completion helpers
These areas work in focused scenarios but still need broader coverage and polish.
### Experimental or planned
- Real SDL graphics and game-oriented graphics support
- Web-server syntax and routes
- Remote package registry
- Full editor extension/LSP support
- A complete concurrency scheduler
Do not treat experimental graphics as a stable cross-platform game runtime yet.
## Documentation map
Recommended reading order for new learners:
1. `docs/QUICK_START.md`
2. `docs/FIRST_HOUR.md`
3. `lessons/README.md`
4. `docs/CLI.md`
5. `docs/SPEC.md`
6. `docs/CURRENT_STATUS.md`
Useful references:
- `docs/ERRORS.md` — friendly diagnostics
- `docs/SIMPLE_FUNCTIONS.md` — function syntax
- `docs/STDLIB.md` — standard helpers
- `docs/TESTING.md` — test and validation workflow
- `docs/FORMATTER.md` — formatting scripts
- `docs/IDE.md` — editor metadata and helper support
- `docs/ROADMAP.md` — current development direction
Historical release notes are kept under `docs/RC*_*.md` and older `docs/V1_*_VALIDATION.md` files. They describe project history rather than the current beginner path.
## Development
The interpreter is implemented in `src/claro.c` and currently builds as a C99 program:
```bash
make
make test
make check
```
The repository includes examples, lessons, validation tools, and a test suite. Before submitting changes, run:
```bash
./claro test
./claro validate
```
No generated source or project header is required. See [C89 build notes](docs/C89.md)
for platform dependencies, testing, and limitations.
## License
See [`LICENSE`](LICENSE) for the project license.
See [LICENSE](LICENSE).