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

docs: clean up Claro README

Browse Source
This commit is contained in:
RayPals
2026-09-19 18:34:59 +00:00
parent 5d53b16a77
commit ba50b3c789
1 changed files with 169 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+169 -253
View File
@@ -1,48 +1,100 @@
# Claro v1.18.26 # Claro
<img src="assets/Claro_Logo.jpg" alt="Claro logo" width="160"> <img src="assets/Claro_Logo.jpg" alt="Claro logo" width="160">
Claro is a small, readable scripting language designed to help beginners — especially learners with learning disabilities — learn programming without being overwhelmed by punctuation-heavy syntax. **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.
Claro stays plain-text first: simple enough to start with `SET name "Jon"`, but able to grow into stronger typed scripts, objects, packages, networking, and tooling over the v1 line. Graphics/SDL work is experimental and not enabled in the stable executable. Current release: **v1.18.26**
## Status ## Quick start
**Current release:** Claro v1.18.26 Build Claro with a C99 compiler and `make`:
Validated in this package:
```bash ```bash
./claro --version make
# Claro v1.18.26
./claro test
# PASS: 0 failure(s)
./claro validate
# Validation passed. Claro v1.18.26 networking reliability is ready for use.
``` ```
## Beginner-first syntax Run a script:
Claro accepts both the sentence-like style and the shorter simple style: ```bash
./claro lessons/01_hello.claro
./claro examples/quiz.claro
```
Check a script without running it:
```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
```claro ```claro
SET name TO "Jon" SAY "Hello from Claro!"
SET name "Jon"
SET city to "Edmonton"
ASK "What is your name?" name ASK "What is your name?" name
SAY "Hello " + name SAY "Hello " + name
IF name = "Jon"
SAY "Nice name!"
END
``` ```
Older forms such as `ASK "Name?" AS name`, `ENDIF`, `DONE`, and `LEARNED` still work so older Claro examples do not break. Claro accepts both the short beginner-friendly form and older compatibility forms. For example, these are both valid:
## Simple functions ```claro
SET name "Jon"
SET name TO "Jon"
```
## Core language features
### Decisions and loops
```claro
SET score 10
IF score >= 5
SAY "Good job!"
ELSE
SAY "Try again."
END
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 ```claro
TEACH greet name TEACH greet name
@@ -52,30 +104,24 @@ END
DO greet "Jon" DO greet "Jon"
``` ```
Older function syntax still works: The older compatibility syntax remains supported:
```claro ```claro
TEACH greet TAKES name TEACH greet TAKES name
SAY "Hello " + name RETURN "Hello " + name
LEARNED LEARNED
CALL greet WITH "Jon" CALL greet WITH "Jon"
SAY RESULT
``` ```
## Objects and classes ### Objects and classes
Classes can have typed fields and simple methods.
```claro ```claro
CLASS Player CLASS Player
HAS name TEXT HAS name TEXT
HAS score NUMBER HAS score NUMBER
TEACH show
SAY name
SAY score
END
TEACH add points TEACH add points
SET score score + points SET score score + points
END END
@@ -84,174 +130,52 @@ END
NEW Player player NEW Player player
SET player.name "Jon" SET player.name "Jon"
SET player.score 10 SET player.score 10
DO player.show
DO player.add 5 DO player.add 5
SAY player.score SAY player.score
``` ```
Object helper commands: ### Type checking
```claro Type annotations are optional for beginners:
OBJECT CLASS player AS kind
OBJECT FIELDS player AS fields
```
## Static type safety
Beginners can still write the simplest form:
```claro
SET name "Jon"
```
When learners are ready, Claro can protect variables with plain-text types:
```claro ```claro
SET score NUMBER 10 SET score NUMBER 10
SET name TEXT "Jon" SET name TEXT "Jon"
SET ready YESNO YES SET ready YESNO YES
TYPE OF score AS kind
SAY kind
CHECK TYPE score IS NUMBER CHECK TYPE score IS NUMBER
``` ```
Advanced container checks are available through `claro typecheck`: Run static checks with:
```bash
./claro typecheck examples/type_hardening.claro
```
Claro provides learner-facing diagnostics for many incorrect variable, function, method, and object-field types. 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 ```claro
SET names AS LIST OF TEXT TO LIST WRITE FILE "note.txt" WITH "Hello from Claro"
ADD "Ada" TO names READ FILE "note.txt" AS note
SAY note
SET scores AS MAP OF NUMBER TO MAP
PUT scores KEY "math" VALUE 98
``` ```
`claro typecheck` also has an early function-argument diagnostic foundation. A function can state a parameter expectation with `CHECK TYPE`, and calls with the wrong value type get a friendly error: Standard-library modules include path and collection helpers:
```claro ```claro
TEACH square amount IMPORT "lib/path.claro" AS path
CHECK TYPE amount IS NUMBER CALL path.join WITH "notes", "today.txt"
SAY amount SAY RESULT
END
DO square "oops"
``` ```
```text See `docs/STDLIB.md` for the current helper API.
Type mismatch for function square: parameter amount needs NUMBER, but this argument looks like TEXT.
```
For functions with more than one checked parameter, Claro reports each mismatched argument with the parameter name: ## Projects and packages
```claro Create a project:
TEACH label TAKES name, age
CHECK TYPE name IS TEXT
CHECK TYPE age IS NUMBER
END
CALL label WITH 7, "old"
```
The same narrow diagnostic foundation now covers simple object method calls when the object was created with `NEW` and the method body uses `CHECK TYPE` for a parameter. Correct calls such as `DO player.add 5` are covered by validation, and wrong-type calls get a focused learner-facing error:
```claro
CLASS Player
HAS score NUMBER
TEACH add points
CHECK TYPE points IS NUMBER
SET score score + points
END
END
NEW Player player
DO player.add "five"
```
```text
Type mismatch for method Player.add: parameter points needs NUMBER, but this argument looks like TEXT.
```
If a learner calls a simple object method before creating the object with `NEW`, `claro typecheck` now points to the missing setup instead of letting the dotted call look like an ordinary unknown function:
```text
Object player is not known yet. Create it with NEW ClassName player before calling player.add.
```
If the object exists but the class does not declare that method, Claro now names the class and suggests where to add the missing `TEACH` block:
```text
Object Player has no method fly. Check the method name or add TEACH fly inside CLASS Player.
```
For simple object fields created with `NEW Class name`, `claro typecheck` also catches direct wrong-type field assignments such as `SET player.score "ten"` when the class says `HAS score NUMBER`:
```text
Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.
```
It also catches direct assignments to undeclared fields and suggests the matching `HAS` line:
```text
Object Player has no field level. Check the field name or add HAS level NUMBER to the class.
```
TEXT-valued and YESNO-valued field-name mistakes are validated too:
```text
Object Player has no field nickname. Check the field name or add HAS nickname TEXT to the class.
Object Player has no field ready. Check the field name or add HAS ready YESNO to the class.
```
If Claro cannot infer the value type for an undeclared field yet, it avoids exposing the internal `ANY` placeholder and keeps the hint beginner-facing:
```text
Object Player has no field level. Check the field name or add the field to the class with the right type.
```
Direct object-field `CHECK TYPE` metadata mismatches are validated for NUMBER, TEXT, and YESNO fields too. For example, after `HAS ready YESNO` and `SET player.ready YES`, `CHECK TYPE player.ready IS TEXT` reports:
```text
Type check failed: expected TEXT, but player.ready looks like YESNO.
```
If `CHECK TYPE` names an undeclared field, Claro now gives the same class-and-field hint as direct field assignment. For example, `CHECK TYPE player.level IS NUMBER` after `NEW Player player` reports:
```text
Object Player has no field level. Check the field name or add HAS level NUMBER to the class.
```
TEXT expectations are validated with the same pattern, for example `CHECK TYPE player.nickname IS TEXT` reports:
```text
Object Player has no field nickname. Check the field name or add HAS nickname TEXT to the class.
```
YESNO expectations are validated too; `CHECK TYPE player.enabled IS YESNO` reports:
```text
Object Player has no field enabled. Check the field name or add HAS enabled YESNO to the class.
```
If a learner checks a field before creating the object with `NEW`, `claro typecheck` points to the missing object setup:
```text
Object player is not known yet. Create it with NEW ClassName player before checking player.score.
```
The same missing-object guidance is now validated for direct field assignment before `NEW`:
```text
Object player is not known yet. Create it with NEW ClassName player before setting player.score.
```
## Project and package workflow
v1.18.26 hardens Claro's project/package workflow.
Create a starter project:
```bash ```bash
claro new MyProject claro new MyProject
@@ -259,18 +183,17 @@ cd MyProject
claro run claro run
``` ```
Manage packages: Manage local project packages:
```bash ```bash
claro package init claro package init
claro package add text claro package add text
claro package list claro package list
claro package remove text
claro package doctor claro package doctor
claro package lock claro package lock
``` ```
Claro now creates and maintains: Project metadata is stored in:
```text ```text
claro.project claro.project
@@ -278,99 +201,92 @@ claro.lock
packages/ packages/
``` ```
Package names are checked so unsafe names such as `../bad` are rejected. The current package system is local and foundational. Remote registries, publishing, version constraints, and package signature verification are not yet stable features.
## Standard-library path and collection helpers
Claro includes tested, namespaced helpers for everyday programs:
```claro
IMPORT "lib/path.claro" AS path
IMPORT "lib/collections.claro" AS collections
CALL path.join WITH "notes", "today.txt"
SAY RESULT
SET names AS LIST OF TEXT TO LIST
ADD "Ada" TO names
ADD "Grace" TO names
CALL collections.join WITH names, " and "
SAY RESULT
```
The `path` module includes `join`, `basename`, `dirname`, `ext`, `stem`, and `absolute`. The `collections` module includes list length/search/join/reverse helpers and map key/value/default-access helpers. See `docs/STDLIB.md` for the complete, current API.
## Networking ## Networking
v1.18.26 adds safer beginner networking commands with offline `claro://` test URLs. Claro supports beginner-oriented HTTP commands and offline `claro://` test URLs:
```claro ```claro
HTTP CHECK "claro://hello" AS safe
SAY safe
HTTP GET "claro://hello" AS page STATUS status HTTP GET "claro://hello" AS page STATUS status
SAY page SAY page
SAY status SAY status
HTTP SAVE "claro://json" TO "network_demo.json" AS saveStatus
SAY saveStatus
``` ```
The latest HTTP status is also stored in `LASTHTTP`. Real `http://` and `https://` requests use `curl` when available, while `claro://` works offline for lessons and tests. Real HTTP and HTTPS requests use `curl` when available. The offline URLs make networking lessons and tests deterministic.
## Useful commands ## Current status
```bash ### Stable foundation
claro help
claro --version
claro test
claro validate
claro doctor
claro examples
claro check examples/quiz.claro
claro typecheck examples/type_hardening.claro
claro fmt examples/quiz.claro
claro repl
claro new MyProject
claro run
claro package init
claro package add text
claro package list
claro package doctor
claro ide
```
## Good first scripts - 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
```bash ### Foundation present
./claro lessons/01_hello.claro
./claro examples/quiz.claro - Static type checking
./claro examples/simple_functions.claro - Objects and classes
./claro examples/objects_classes.claro - Local projects and packages
./claro examples/text_polish.claro - Networking beyond the offline test layer
./claro examples/networking.claro - 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 ## Documentation map
If you are new to Claro, start here: Recommended reading order for new learners:
1. `docs/QUICK_START.md` 1. `docs/QUICK_START.md`
2. `docs/FIRST_HOUR.md` 2. `docs/FIRST_HOUR.md`
3. `lessons/README.md` 3. `lessons/README.md`
4. `docs/CLI.md` 4. `docs/CLI.md`
5. `docs/CURRENT_STATUS.md` 5. `docs/SPEC.md`
6. `docs/CURRENT_STATUS.md`
Feature references by current status: Useful references:
- **Ready for beginner lessons:** language reference (`docs/SPEC.md`), friendly errors/checking (`docs/ERRORS.md`, `docs/LINTER.md`, `docs/TESTING.md`), formatter (`docs/FORMATTER.md`), and simple functions (`docs/SIMPLE_FUNCTIONS.md`). - `docs/ERRORS.md` — friendly diagnostics
- **Foundation present, still being polished:** static typing (`docs/ADVANCED_STATIC_TYPING.md`), objects/classes (`docs/V1_15_OBJECTS_CLASSES.md`), local projects/packages (`docs/V1_16_PACKAGES_PROJECTS.md`), HTTP client networking (`docs/V1_17_NETWORKING.md`), cooperative tasks (`docs/CONCURRENCY.md`), and IDE metadata/helper support (`docs/IDE.md`). - `docs/SIMPLE_FUNCTIONS.md` — function syntax
- **Planned or experimental, not stable beginner features yet:** remote package registry (`docs/PACKAGE_REGISTRY.md`), web server API (`docs/WEB_SERVER_PLAN.md`), full editor extension/LSP (`docs/EDITOR_EXTENSION_PLAN.md`), and real SDL graphics (`docs/GRAPHICS.md`, `docs/SDL12.md`). - `docs/STDLIB.md` — standard helpers
- **Roadmaps:** `docs/ROADMAP.md` for the current v1 direction and `docs/COMPLETE_PLATFORM_ROADMAP.md` for the larger platform goal. - `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 and validation logs are kept in files such as `docs/RC*_NOTES.md`, `docs/RC*_VALIDATION.md`, and older `docs/V1_*_VALIDATION.md`. They are useful for project history, but they are not the beginner starting path. 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.
## Release direction ## Development
Claro should remain in the `v1.xx.yy` line for normal development. A future Claro v2 should mean a full rewrite years later, not an ordinary feature update. 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
```
## License
See [`LICENSE`](LICENSE) for the project license.