# Claro v1.18.26 Claro logo 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 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. ## Status **Current release:** Claro v1.18.26 For the current feature map and beginner-safe limits, start with [`docs/CURRENT_STATUS.md`](docs/CURRENT_STATUS.md). The sequenced development priorities are in [`docs/ROADMAP.md`](docs/ROADMAP.md); older release-candidate notes are historical. Validated in this package: ```bash ./claro --version # Claro v1.18.26 ./claro test # PASS: 0 failure(s) ./claro validate # Validation passed. Claro v1.18.26 networking reliability is ready for use. python3 tools/validate_typecheck_diagnostics.py python3 tools/validate_ide_metadata.py python3 tools/validate_version_convention.py python3 tools/validate_package_security.py python3 tools/validate_ci_workflow.py ``` The CI workflow validator also requires its own command to remain in an executable `run` step, so the release-gate check cannot silently disappear from CI. `make` builds both `claro` and `claro.exe`, allowing the version validator to exercise the same source build on every platform. ## Beginner-first syntax Claro accepts both the sentence-like style and the shorter simple style: ```claro SET name TO "Jon" SET name "Jon" SET city to "Edmonton" ASK "What is your name?" 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. ## Simple functions ```claro TEACH greet name SAY "Hello " + name END DO greet "Jon" ``` Older function syntax still works: ```claro TEACH greet TAKES name SAY "Hello " + name LEARNED CALL greet WITH "Jon" ``` ## Objects and classes Classes can have typed fields and simple methods. ```claro CLASS Player HAS name TEXT HAS score NUMBER TEACH show SAY name SAY score END TEACH add points SET score score + points END END NEW Player player SET player.name "Jon" SET player.score 10 SET player.score player.score + 1 DO player.show DO player.add 5 SAY player.score ``` Object helper commands: ```claro 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 SET score NUMBER 10 SET name TEXT "Jon" SET ready YESNO YES TYPE OF score AS kind SAY kind CHECK TYPE score IS NUMBER ``` `CHECK TYPE` names a real Claro type. If a type name is misspelled, the checker explains the allowed beginner types instead of reporting a confusing value mismatch: ```text CHECK TYPE score IS BANANA CHECK TYPE needs a known type such as NUMBER, TEXT, YESNO, LIST, or MAP, but BANANA is not a Claro type. ``` Advanced container checks are available through `claro typecheck`: ```claro SET names AS LIST OF TEXT TO LIST ADD "Ada" TO names 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 or a missing checked argument get a friendly error: ```claro TEACH square amount CHECK TYPE amount IS NUMBER SAY amount END DO square "oops" ``` ```text Type mismatch for function square: parameter amount needs NUMBER, but this argument looks like TEXT. Function square needs argument amount as NUMBER, but this call does not provide it. Function greet needs 1 argument, but this call gives 0. Add the missing argument. Function square only accepts 1 argument, but this call gives 2. Remove the extra argument. Function squre is not known yet. Check the function name or add TEACH squre before calling it. ``` Simple functions and object methods can also declare a return type. `claro typecheck` checks each `RETURN` expression against it and reports a missing return when a declaration never returns a value: ```claro TEACH square amount RETURNS NUMBER CHECK TYPE amount IS NUMBER RETURN amount END ``` The same focused check applies to methods such as `Player.score RETURNS NUMBER`; a wrong return reports the full method name, for example: `Type mismatch for return from Player.score: expected NUMBER, but this value looks like TEXT.` The older compatibility spelling keeps the same return check for functions and methods. For example, `TEACH square TAKES amount RETURNS NUMBER` with `LEARNED` and `CALL square WITH 4` is checked before it runs, so older lessons get the same type-safety feedback. A compatibility method such as `TEACH score TAKES amount RETURNS NUMBER` inside a class is checked the same way; a correct `CALL player.score WITH 4` path is covered by release validation too. If a function or method declares `RETURNS TYPE` but uses `RETURN` without a value, the checker points out the missing expression: ```text Function square needs a NUMBER value after RETURN. Add a NUMBER expression. ``` If a function or method declares `RETURNS TYPE` but contains no `RETURN`, the checker points out the missing statement: ```text Function square declares RETURNS NUMBER but has no RETURN statement. Add RETURN with a NUMBER value. ``` Return declarations must use a known Claro type. If the type name is misspelled, the checker explains the supported beginner types: ```text Function square declares an unknown return type BANANA. Use a Claro type such as NUMBER, TEXT, YESNO, LIST, or MAP. ``` The same check applies to methods, so `Player.score RETURNS BANANA` reports `Method Player.score declares an unknown return type BANANA...` instead of allowing a misspelled type into a class definition. If a return expression cannot be understood yet, the diagnostic names the function or method and the type it needs; this is covered for both modern and older compatibility method syntax. When a NUMBER return contains a known TEXT operand in arithmetic, the checker names the operation and operand, for example: `Type mismatch for return from total: addition needs NUMBER values, but "oops" looks like TEXT.` Complete `IF`/`ELSE` return branches are also accepted inside typed functions and methods, including a nested conditional whose own branches all return; an incomplete path still gets a missing-return diagnostic. The same return diagnostic names the arithmetic operation when a NUMBER return mixes in a known TEXT operand, so the learner sees both the operation rule and the offending value instead of only a generic return mismatch. This is covered for addition, subtraction, and multiplication in functions, and for subtraction in object methods. For example, `Player.total` reports `subtraction needs NUMBER values` when its return expression mixes a checked NUMBER parameter with a TEXT value. Claro keywords are case-insensitive here, so `returns NUMBER` is accepted as the same return declaration as `RETURNS NUMBER`. The type checker keeps the return-value diagnostic when a lowercase declaration is used, which helps learners who are still learning Claro's capitalization style. The unknown-function diagnostic is validated for both modern `DO squre 4` and compatibility `CALL squre WITH 4` calls. Compatibility calls that leave `WITH` empty, such as `CALL greet WITH`, now count as zero arguments, so learners get the same missing-argument guidance as `DO greet` instead of the checker treating the blank as an argument. For functions with more than one checked parameter, Claro reports each mismatched argument with the parameter name: ```claro 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` and compatibility calls such as `CALL player.add WITH 5` are covered by validation, and wrong-type calls get a focused learner-facing error. This also works when the checked method appears after another method in the same class, so normal multi-method class examples still get the same wrong-type and extra-argument guidance: ```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" CALL player.add WITH "five" ``` ```text Type mismatch for method Player.add: parameter points needs NUMBER, but this argument looks like TEXT. Method Player.add needs argument points as NUMBER, but this call does not provide it. Method Player.rename needs 1 argument, but this call gives 0. Add the missing argument. Method Player.add only accepts 1 argument, but this call gives 2. Remove the extra argument. ``` 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. This covers both the modern `DO player.add 5` form and the older compatibility `CALL player.add WITH 5` form, including `CALL` mistakes where the method name itself is wrong: ```text Object player is not known yet. Create it with NEW ClassName player before calling player.add. Object player is not known yet. Create it with NEW ClassName player before calling player.fly. ``` 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. This is validated for both modern `DO player.fly 5` and compatibility `CALL player.fly WITH 5` calls: ```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`. This remains true if the `HAS` field appears after a simple method in the class, so learners get the field-type error instead of a misleading unknown-field hint: ```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. ``` The same field check follows a simple object alias. After `SET alias player`, assignments through `alias.score` still use the field type declared by `Player`: ```claro NEW Player player SET alias player SET alias.score "ten" ``` ```text Type mismatch for field alias.score: expected NUMBER, but this value looks like TEXT. ``` The same check follows simple arithmetic and text-concatenation expressions. For example, `SET player.score player.name + 1` now names the text operand and explains that addition into a `NUMBER` field needs numeric values, rather than silently accepting an expression whose result cannot fit the field. The checker identifies text operands in arithmetic expressions and explains the operator rule instead of treating an invalid numeric field assignment as an unknown expression: ```text Type mismatch for field player.score: subtraction needs NUMBER values, but player.name looks like TEXT. Type mismatch for field player.score: addition needs NUMBER values, but player.name looks like TEXT. Type mismatch for field player.score: multiplication needs NUMBER values, but player.name looks like TEXT. Type mismatch for field player.score: division needs NUMBER values, but player.name looks like TEXT. ``` Valid numeric subtraction is covered too: ```claro SET player.score 10 SET player.score player.score - 2 ``` The focused typecheck validation keeps this valid subtraction example beside the existing valid multiplication and division examples, so a useful expression is not confused with a nearby text-operand mistake. 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 claro new MyProject cd MyProject claro run ``` Manage packages: ```bash claro package init claro package add text claro package list claro package remove text claro package doctor claro package lock ``` Claro now creates and maintains: ```text claro.project claro.lock packages/ ``` `claro package doctor` also checks that every listed package has a manifest whose `name:` matches the package name in `claro.project`; a mismatch is reported as `BAD package manifest name` instead of being treated as a healthy package. It also compares the complete `checksum:` field, so extra or trailing checksum text, or a duplicate checksum field, is rejected as `BAD package checksum`. Package manifests must contain exactly one `version: 1` field; duplicate or prefix-matching values such as `version: 10` are rejected as `BAD package version`. The project manifest must contain exactly one `manifest-version: 1` field; duplicate or prefix-matching values such as `manifest-version: 10` are rejected as `BAD project manifest version: expected 1`. It must also contain exactly one non-empty `name:` field; otherwise doctor reports `BAD project manifest name: expected a non-empty name`. Starter projects created with `claro new MyProject` use the same `manifest-version: 1` and `lock-version: 1` headers as `claro package init`, so the first project files match the package maintenance tools. Project names and package names are checked so unsafe names such as `../bad` are rejected before Claro creates folders. Names must also be 64 characters or fewer, which keeps generated project and package paths predictable. If an unsafe package name is already present in `claro.project`, `claro package doctor`, `claro package lock`, `claro package list`, `claro package init`, `claro package add`, and lockfile refreshes during `claro package remove` flag it instead of treating it as safe lockfile data. `claro package remove` can also remove the exact unsafe entry, so a learner can repair a bad project file without Claro using that unsafe name as a folder path. `claro package doctor` also verifies listed package lockfile checksums, reports stale lock entries, and rejects lockfile package entries that are not listed in `claro.project`. ## 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 v1.18.26 adds safer beginner networking commands with offline `claro://` test URLs. ```claro HTTP CHECK "claro://hello" AS safe SAY safe HTTP GET "claro://hello" AS page STATUS status SAY page 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. ## Useful commands ```bash 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 ```bash ./claro lessons/01_hello.claro ./claro examples/quiz.claro ./claro examples/simple_functions.claro ./claro examples/objects_classes.claro ./claro examples/text_polish.claro ./claro examples/networking.claro ``` ## Documentation map If you are new to Claro, start here: 1. `docs/QUICK_START.md` 2. `docs/FIRST_HOUR.md` 3. `lessons/README.md` 4. `docs/CLI.md` 5. `docs/CURRENT_STATUS.md` Feature references by current status: - **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`). - **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`). - **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`). - **Roadmaps:** `docs/ROADMAP.md` for the current v1 direction and `docs/COMPLETE_PLATFORM_ROADMAP.md` for the larger platform goal. 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. ## Release direction 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.