Claro/docs/ADVANCED_STATIC_TYPING.md

Advanced Static Typing

Claro v1.18.26 adds the first advanced static-typing foundation: typed containers checked by claro typecheck.

Typed lists

SET names AS LIST OF TEXT TO LIST
ADD "Ada" TO names
ADD "Grace" TO names

The type checker now rejects wrong item types:

SET names AS LIST OF TEXT TO LIST
ADD 123 TO names

Output:

Type mismatch for list names: expected TEXT item, but this value looks like NUMBER.

Typed maps

SET scores AS MAP OF NUMBER TO MAP
PUT scores KEY "math" VALUE 98

The type checker rejects wrong value types:

SET scores AS MAP OF NUMBER TO MAP
PUT scores KEY "oops" VALUE "high"

Output:

Type mismatch for map scores: expected NUMBER value, but this value looks like TEXT.

Nested container values

A typed list can contain a typed map. claro typecheck keeps the map's own type metadata while checking the outer list:

SET people AS LIST OF MAP TO LIST
SET person AS MAP OF TEXT TO MAP
PUT person KEY "name" VALUE "Ada"
ADD person TO people

This is accepted with Type check OK. More complex nested container operations and full key/value inference remain future work.

Unknown fields inside methods

When a method assigns a known value to a bare name that is not a parameter, local variable, or declared class field, claro typecheck reports the missing field instead of silently treating the typo as a new variable:

CLASS Player
    HAS score NUMBER

    TEACH train
        SET level 3
    END
END

The diagnostic is:

Object Player has no field level. Check the field name or add HAS level NUMBER to the class.

This narrow check covers direct method assignments with a known expression in both modern TEACH ... END and compatibility TEACH ... TAKES ... LEARNED methods. Broader local-variable and control-flow analysis remains future work.

Complete conditional returns

Return expressions that need more information

When a typed function or method returns a name or expression whose type the focused checker cannot infer yet, claro typecheck reports that clearly instead of silently accepting it:

TEACH square amount RETURNS NUMBER
    RETURN missing
END

Function square's return value could not be understood yet. Use a NUMBER expression after RETURN.

Use a known typed value, such as a parameter checked with CHECK TYPE, while broader expression inference remains future work.

Known NUMBER parameters can also be used in arithmetic return expressions. Numeric division is accepted when both operands are known numbers:

TEACH halve amount RETURNS NUMBER
    CHECK TYPE amount IS NUMBER
    RETURN amount / 2
END

This valid division case is included in the focused typecheck validation matrix beside the diagnostic for using a TEXT operand in division.

Subtraction follows the same rule:

TEACH difference amount RETURNS NUMBER
    CHECK TYPE amount IS NUMBER
    RETURN amount - 2
END

The focused validator checks this positive function case as well as the matching subtraction diagnostic for a TEXT operand.

The same protection applies to object methods. A checked NUMBER parameter can be divided by a number and returned as NUMBER:

CLASS Player
    TEACH total amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount / 2
    END
END

This valid method-division case is included in the focused typecheck validation matrix beside the method diagnostic for using a TEXT operand in division.

Return declarations accept the same case-insensitive keyword style as the rest of Claro. For example, returns NUMBER still enables return checking:

TEACH square amount returns NUMBER
    RETURN "oops"
END

This reports a normal return mismatch naming NUMBER and TEXT; capitalization style does not disable the safety check.

The same case-insensitive return declaration rule applies to compatibility methods. A lowercase returns still checks the method's RETURN value:

CLASS Player
    TEACH score TAKES amount returns NUMBER
        RETURN "oops"
    LEARNED
END

claro typecheck reports:

Type mismatch for return from Player.score: expected NUMBER, but this value looks like TEXT.

A correct compatibility call also remains valid when the declaration uses lowercase returns:

NEW Player player
CALL player.score WITH 4

This success path is included in the focused typecheck validation matrix.

Compatibility methods also keep arithmetic return checks when they use the older TAKES / LEARNED spelling. For example, this checked division remains a valid NUMBER return:

CLASS Player
    TEACH score TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount / 2
    LEARNED
ENDCLASS

This matching CALL player.score WITH 4 path is included in focused validation.

The same compatibility method return check explains an addition mistake instead of falling back to a generic return error:

CLASS Player
    TEACH total TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount + "oops"
    LEARNED
ENDCLASS

claro typecheck reports:

Type mismatch for return from Player.total: addition needs NUMBER values, but "oops" looks like TEXT.

This negative compatibility fixture is part of focused release validation.

Compatibility methods support numeric subtraction in the same focused way:

CLASS Player
    TEACH score TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount - 2
    LEARNED
ENDCLASS

The matching CALL player.score WITH 4 success path is included in focused validation alongside the modern method subtraction case.

Compatibility methods also keep numeric multiplication return checks. This older TAKES / LEARNED spelling accepts a checked NUMBER parameter multiplied by a number and returned as NUMBER:

CLASS Player
    TEACH score TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount * 2
    LEARNED
ENDCLASS

The matching CALL player.score WITH 4 success path is included in focused validation.

Compatibility method division mistakes receive the same operation-specific guidance:

CLASS Player
    TEACH total TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount / "oops"
    LEARNED
ENDCLASS

claro typecheck reports:

Type mismatch for return from Player.total: division needs NUMBER values, but "oops" looks like TEXT.

This negative compatibility fixture is part of focused release validation.

When a function declares a return type, claro typecheck accepts nested conditionals when every branch returns a value of that type:

TEACH choose flag RETURNS NUMBER
    IF flag
        IF flag
            RETURN 1
        ELSE
            RETURN 2
        END
    ELSE
        RETURN 3
    END
END

An incomplete branch still produces a missing-return diagnostic. Deeper control-flow analysis through loops and more complex conditions remains planned.

Object aliases and field checks

When a simple object is assigned to another variable, claro typecheck preserves its class for direct field assignments:

NEW Player player
SET alias player
SET alias.score 10

If the value has the wrong type, the diagnostic names the alias and the expected class field type:

Type mismatch for field alias.score: expected NUMBER, but this value looks like TEXT.

This is intentionally limited to simple aliases. Broader object-flow analysis through branches, loops, and complex expressions remains planned.

The same field-assignment check follows a second simple alias. This lets a learner use a more descriptive name without losing the class field type:

SET backup alias
SET backup.score "ten"

Output:

Type mismatch for field backup.score: expected NUMBER, but this value looks like TEXT.

This remains limited to direct assignments through simple alias chains; control-flow and complex object-flow analysis are still planned.

Text operands are also identified when they appear in arithmetic expressions assigned to NUMBER fields. The diagnostic names the operator and the text operand, which catches a common beginner mistake such as adding a text field to a number field:

SET player.score player.name + 1

Type mismatch for field player.score: addition needs NUMBER values, but player.name looks like TEXT.

Subtraction, multiplication, and division use the same beginner-facing guidance:

SET player.score player.score - player.name

Type mismatch for field player.score: subtraction needs NUMBER values, but player.name looks like TEXT.

The same learner-facing result is preserved for multiplication, so the checker does not lose the useful TEXT type when the invalid expression uses *:

SET player.score player.score * player.name

Type mismatch for field player.score: multiplication needs NUMBER values, but player.name looks like TEXT.

Division is covered in the same way:

SET player.score player.score / player.name

Type mismatch for field player.score: division needs NUMBER values, but player.name looks like TEXT.

Numeric division remains accepted in a NUMBER field, so the type checker protects both sides of this operator without rejecting a valid beginner expression:

SET player.score 10
SET player.score player.score / 2

This example is included in the focused typecheck validation matrix.

Numeric multiplication is accepted in a NUMBER field as well:

SET player.score player.score * 2

The focused validation matrix keeps this valid arithmetic case beside the multiplication text-operand diagnostic, so a useful expression is not confused with the nearby beginner mistake.

The expression checker now gives operator-specific guidance for known TEXT operands in subtraction, multiplication, and division, including typed method return expressions. Broader expression inference remains future work.

Compatibility methods use the same arithmetic return checks as modern methods. This older spelling is accepted when a checked NUMBER parameter is used in a numeric addition:

CLASS Player
    TEACH score TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount + 2
    LEARNED
ENDCLASS

NEW Player player
CALL player.score WITH 4

The focused validation matrix covers this positive compatibility example alongside subtraction, multiplication, and division.

The same operator-specific diagnostic is covered for older compatibility methods:

CLASS Player
    TEACH total TAKES amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN amount - "oops"
    LEARNED
ENDCLASS

Claro reports:

Type mismatch for return from Player.total: subtraction needs NUMBER values, but "oops" looks like TEXT.

This keeps TAKES / LEARNED lessons aligned with the modern method syntax.

Text concatenation is also accepted when the result is assigned to a TEXT field. This keeps a common beginner pattern type-safe without treating every + expression as numeric:

SET player.name player.name + " Lovelace"

The focused typecheck validation matrix covers this positive case beside the existing numeric-expression and text-operand checks.

The same rule works when the literal comes first:

SET player.name "Ada " + player.name

This reverse-order concatenation is also covered by focused validation, so learners can build text from either side without losing the declared TEXT field type.

Two TEXT fields can be combined as well:

SET player.name player.name + player.nickname

The focused validation matrix covers this field-to-field form so a learner can build text from named object fields without losing the declared TEXT type.

CHECK TYPE also preserves TEXT field metadata through the same chained aliases:

CLASS Player
    HAS name TEXT
END

NEW Player player
SET alias player
SET backup alias
SET player.name "Ada"
CHECK TYPE backup.name IS TEXT

This confirms the declared field type without requiring the learner to repeat the original object variable name. The broader limits are unchanged: aliases created through branches, loops, or complex expressions are still planned.

CHECK TYPE also follows simple aliases for direct field metadata checks. This includes a second alias, so learners can give an object a more descriptive local name without losing the class field information:

NEW Player player
SET alias player
SET alias.score 10
CHECK TYPE alias.score IS NUMBER

SET backup alias
CHECK TYPE backup.score IS NUMBER

If the requested type is wrong, the diagnostic names the alias and the declared field type:

Type check failed: expected TEXT, but alias.score looks like NUMBER.

The same diagnostic remains specific after the second alias:

SET backup alias
CHECK TYPE backup.score IS TEXT

Type check failed: expected TEXT, but backup.score looks like NUMBER.

Function parameter checks

Claro now has a small static-checking foundation for function arguments. Keep the beginner-friendly function syntax, then put the expected type inside the function with CHECK TYPE:

TEACH square amount
    CHECK TYPE amount IS NUMBER
    SAY amount
END

DO square 4

If a learner calls the function with the wrong kind of value, claro typecheck explains which parameter needs which type:

TEACH square amount
    CHECK TYPE amount IS NUMBER
    SAY amount
END

DO square "oops"

Output:

Type mismatch for function square: parameter amount needs NUMBER, but this argument looks like TEXT.

If the learner forgets a checked argument, claro typecheck now names the missing parameter and expected type:

TEACH square amount
    CHECK TYPE amount IS NUMBER
    SAY amount
END

DO square

Output:

Function square needs argument amount as NUMBER, but this call does not provide it.

Multiple checked parameters are reported separately, so a learner can fix each argument one at a time:

TEACH label TAKES name, age
    CHECK TYPE name IS TEXT
    CHECK TYPE age IS NUMBER
    SAY name
    SAY age
END

CALL label WITH 7, "old"

Output:

Type mismatch for function label: parameter name needs TEXT, but this argument looks like NUMBER.
Type mismatch for function label: parameter age needs NUMBER, but this argument looks like TEXT.

If a learner mistypes a function name, claro typecheck now names the unknown function and suggests either checking the spelling or adding a matching TEACH block. This is covered for both modern DO and older compatibility CALL ... WITH calls:

TEACH square amount
    CHECK TYPE amount IS NUMBER
    SAY amount
END

DO squre 4
CALL squre WITH 4

Each form reports the same beginner-facing fix:

Function squre is not known yet. Check the function name or add TEACH squre before calling it.

Function and method return checks

Simple functions and object methods can declare a return type with RETURNS TYPE. claro typecheck checks each simple RETURN expression before the program runs:

CLASS Player
    TEACH score amount RETURNS NUMBER
        RETURN amount
    END
END

NEW Player player
DO player.score 4

Returning text from this method produces a learner-facing diagnostic that names the class and method:

Type mismatch for return from Player.score: expected NUMBER, but this value looks like TEXT.

If a method's return expression is not understood yet, the diagnostic names the method and gives the promised type so the learner knows what to replace:

CLASS Player
    TEACH square amount RETURNS NUMBER
        CHECK TYPE amount IS NUMBER
        RETURN missing
    END
END

Method Player.square's return value could not be understood yet. Use a NUMBER expression after RETURN.

Methods can also return a typed field declared by their class. A field is available by its simple name inside the method, so RETURN score is checked against HAS score NUMBER instead of being treated as an unknown expression. Returning that field from a method declared RETURNS TEXT reports the same expected-versus-found diagnostic.

This is a focused check for simple return expressions. When a parameter has a CHECK TYPE declaration, that known type also informs arithmetic return expressions in functions and methods, so RETURN amount + 1 is checked against the declared return type. The RETURNS keyword is case-insensitive in both modern and compatibility function forms, so returns NUMBER keeps working while learners are still getting used to Claro's capitalization. A declared return with no RETURN, or with a RETURN only inside an IF, gets a beginner-facing message explaining that the function may finish without returning the promised type:

Function choose declares RETURNS NUMBER but does not return a NUMBER value on every path. Add RETURN to each branch or after the conditional.

The focused validation matrix covers modern and compatibility syntax, including a compatibility method that returns a class-declared field, method success and mismatch fixtures, unknown method return expressions, typed field returns, missing returns, and conditional-only returns. It also includes a positive nested IF/ELSE return example inside a method, so a complete nested method path is protected from regression. Full path-sensitive analysis proving that every IF/ELSE branch returns remains planned.

Object method parameter checks

Claro also checks simple object method arguments when the method body names a parameter with CHECK TYPE. This keeps the method syntax beginner-readable while giving a clearer error before the program runs:

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 5

If the learner passes text where the method expects a number:

DO player.add "five"

Output:

Type mismatch for method Player.add: parameter points needs NUMBER, but this argument looks like TEXT.

If the learner forgets a checked method argument, claro typecheck also names the missing method parameter and expected type:

DO player.add

Output:

Method Player.add needs argument points as NUMBER, but this call does not provide it.

If the learner gives too many arguments to a simple checked method, claro typecheck now points to the extra argument instead of silently accepting it:

DO player.add 5, 6

Output:

Method Player.add only accepts 1 argument, but this call gives 2. Remove the extra argument.

Both sides of this narrow method foundation are covered by validation: tests/typecheck_method_good.claro checks that DO player.add 5 is accepted, tests/typecheck_method_bad.claro checks the friendly wrong-type diagnostic, tests/typecheck_method_missing_arg_bad.claro checks the missing checked-argument diagnostic, and tests/typecheck_method_extra_arg_bad.claro checks the extra-argument diagnostic. Multi-method class examples are covered too, including the extra-argument case where the checked method appears after another method in the same class. A compatibility CALL second.add WITH 5, 6 through a two-step alias is also covered by tests/typecheck_object_alias_method_call_extra_arg_bad.claro, preserving the same actionable extra-argument message for older lessons.

If the method call comes before the object is created, the type checker now gives the learner the missing setup step. The modern DO form and the older compatibility CALL ... WITH form both get this guidance, even when the method name is also a typo:

CLASS Player
    HAS score NUMBER

    TEACH add points
        CHECK TYPE points IS NUMBER
        SET score score + points
    END
END

DO player.add 5
CALL player.add WITH 5
CALL player.fly WITH 5

Output:

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 the method, Claro now names the class and suggests where to add the missing TEACH block. This is validated for the modern DO player.fly 5 form and the older compatibility CALL player.fly WITH 5 form:

DO player.fly 5
CALL player.fly WITH 5

Output:

Object Player has no method fly. Check the method name or add TEACH fly inside CLASS Player.

Object field assignment checks

Claro also has a narrow static diagnostic for direct object-field assignments. If a class declares a typed field and a script creates a simple object with NEW Class name, claro typecheck remembers the field type:

CLASS Player
    HAS score NUMBER
END

NEW Player player
SET player.score 10

If a learner assigns the wrong value type directly to that known field:

SET player.score "ten"

Output:

Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.

Simple expressions are checked too. Text joined with a number has a TEXT result, so this mistake is caught before running the program:

SET player.name "Ada"
SET player.score player.name + 1

Type mismatch for field player.score: expected NUMBER, but this value looks like TEXT.

The reverse mismatch is checked as well. A numeric expression cannot be stored in a TEXT field:

SET player.score 10
SET player.name player.score + 1

Type mismatch for field player.name: expected TEXT, but this value looks like NUMBER.

If a learner assigns to a field the class did not declare, claro typecheck now names the object class and suggests the matching HAS line:

CLASS Player
    HAS score NUMBER
END

NEW Player player
SET player.level 3

Output:

Object Player has no field level. Check the field name or add HAS level NUMBER to the class.

The unknown-field hint uses the value type it can see. Text-valued and YESNO-valued typos such as SET player.nickname "Ace" and SET player.ready YES are covered separately:

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.

When the value is an expression whose type is not known yet, Claro now avoids the internal ANY placeholder and gives a plain next step instead:

Object Player has no field level. Check the field name or add the field to the class with the right type.

Direct CHECK TYPE on an undeclared field uses the expected type from the check in its suggestion:

CHECK TYPE player.level IS NUMBER

Output:

Object Player has no field level. Check the field name or add HAS level NUMBER to the class.

TEXT expectations use the same learner-facing pattern:

CHECK TYPE player.nickname IS TEXT

Output:

Object Player has no field nickname. Check the field name or add HAS nickname TEXT to the class.

YESNO expectations are covered too:

CHECK TYPE player.enabled IS YESNO

Output:

Object Player has no field enabled. Check the field name or add HAS enabled YESNO to the class.

If the object itself has not been created yet, the diagnostic points to the missing NEW step:

CHECK TYPE player.score IS NUMBER

Output:

Object player is not known yet. Create it with NEW ClassName player before checking player.score.

Direct field assignment before NEW is checked with the same beginner-first guidance:

SET player.score 10

Output:

Object player is not known yet. Create it with NEW ClassName player before setting player.score.

Both sides of this narrow field foundation are covered by validation: tests/typecheck_object_field_good.claro checks that SET player.score 10 is accepted for a HAS score NUMBER field, tests/typecheck_object_field_text_good.claro checks that SET player.name "Ada" is accepted for a HAS name TEXT field, tests/typecheck_object_field_yesno_good.claro checks that SET player.ready YES is accepted for a HAS ready YESNO field, tests/typecheck_object_field_unknown_object_bad.claro checks that SET player.score 10 before NEW Player player reports the missing-object assignment diagnostic, tests/typecheck_object_field_check_type_unknown_object_bad.claro checks the matching missing-object CHECK TYPE diagnostic, and the remaining object-field fixtures cover known-field mismatches, unknown NUMBER/TEXT/YESNO fields, and unknown-field assignments whose value type is not inferable yet.

This slice is intentionally small: it covers direct NEW Class object plus SET object.field value cases in one file. Field declarations are collected even when a learner writes a simple method before a later HAS field, so the type checker can still report the field's declared type. Broader object flows, aliases, method return checks, and richer object signatures remain future work.

Simple functions also get an arity check before running. If a learner defines TEACH greet name and then writes DO greet without the name argument, claro typecheck reports:

Function greet needs 1 argument, but this call gives 0. Add the missing argument.

The older compatibility spelling gets the same beginner-facing result when WITH is left empty:

CALL greet WITH

Output:

Function greet needs 1 argument, but this call gives 0. Add the missing argument.

The same method-aware diagnostic is used when a method directly assigns the wrong value to a class field. For example, SET name 123 inside Player.rename reports Type mismatch for field name in Player.rename: expected TEXT, but this value looks like NUMBER. The operator-specific form also remains available: SET score score + name inside Player.add RETURNS NUMBER reports Type mismatch for field score in Player.add: addition needs NUMBER values, but name looks like TEXT. YESNO fields use the same clear method context: assigning text to HAS ready YESNO inside Player.toggle reports Type mismatch for field ready in Player.toggle: expected YESNO, but this value looks like TEXT. Both modern DO and compatibility CALL ... WITH method forms are covered by the focused validation matrix. These focused checks cover typed method bodies; broader control-flow and object-flow analysis remains planned.

Status

This is currently a static checker feature. It improves claro typecheck and validation confidence for DO and compatibility CALL ... WITH function calls, simple DO object.method ... calls where the object was created with NEW Class name, and direct assignments to known object fields. Runtime enforcement for every container mutation and richer function/object signatures can be added later after the syntax is classroom-tested.

Method-body field assignments are covered in both modern and compatibility syntax, including a valid YESNO assignment through TEACH toggle TAKES value and CALL player.toggle WITH YES. Method-body CHECK TYPE metadata has the same balanced coverage: a modern DO player.toggle YES example and the compatibility CALL example both verify a declared YESNO field. The focused release validator keeps these positive examples beside the wrong-type diagnostics.

A bare field typo inside a method's CHECK TYPE is also checked now. For example, CHECK TYPE level IS NUMBER in Player.train reports Object Player has no field level. Check the field name or add HAS level NUMBER to the class. The older TAKES / LEARNED method spelling receives the same diagnostic. This keeps method metadata checks consistent with direct method-field assignments and uses the expected type to make the repair actionable.