Add named MAP (closed #201)

Author: python-processing-unit

docs/SPECIFICATION.html

@@ -96,7 +96,9 @@
 
 For `INT` and `FLT` types, a declaration MAY name a specific numeric base by writing `TYPE{base} name`, where `base` is an `INT` literal in the range `2` through `64`. A named-base type is a subtype of its parent numeric type: `INT{base}` values are `INT`s and `FLT{base}` values are `FLT`s, but an assignment to a named-base binding requires the value's base to match the declared base. The parent types `INT` and `FLT` (equivalent to `INT{0}` and `FLT{0}`) accept values of any valid numeric base.
 
-The first assignment to a symbol MUST use a typed form such as `TYPE name = expression` or `TYPE{base} name = expression`, with one or more spaces between the type annotation and the name and optional spaces around `=`. Subsequent assignments MAY omit the type annotation, but the symbol's type MUST remain unchanged for the lifetime of that name, including after deletion and re-assignment.
+For `MAP` types, a declaration MAY specify a template `MAP` by writing `MAP{template} name`, where `template` is any expression that evaluates to a `MAP`. A named-`MAP` type is a subtype of its parent `MAP` type: `MAP{template}` values are `MAP`s, but an assignment to a named-`MAP` binding requires the assigned value to match the template according to the default key-presence rules of the `MATCH` operator. The parent type `MAP` accepts any `MAP` value.
+
+The first assignment to a symbol MUST use a typed form such as `TYPE name = expression`, `TYPE{base} name = expression`, or `MAP{template} name = expression`, with one or more spaces between the type annotation and the name and optional spaces around `=`. Subsequent assignments MAY omit the type annotation, but the symbol's type MUST remain unchanged for the lifetime of that name, including after deletion and re-assignment.
 
 Assignments to undeclared identifiers without a type annotation MUST raise a runtime error. A binding MUST remain allocated until it is deleted with `DEL("name")`.
 
@@ -176,6 +178,8 @@
 
 `INT` and `FLT` additionally support named-base variants written `INT{base}` and `FLT{base}`, where `base` is a numeric base in the range `2` through `64` or `0` to denote the parent type. A named-base type and its parent are the same runtime type, but static type checking treats mismatched bases as incompatible. `INT` and `FLT` (base `0`) accept any valid numeric base; `INT{base}` and `FLT{base}` only accept values whose stored base equals the declared base.
 
+`MAP` additionally supports named-template variants written `MAP{template}`, where `template` is any expression that evaluates to a `MAP`. A named-template type and its parent are the same runtime type, but static type checking treats mismatched templates as incompatible. `MAP` accepts any `MAP` value; `MAP{template}` only accepts values whose entries satisfy the template under the default key-presence rules of the `MATCH` operator. Named `MAP` types with different templates are treated as distinct types.
+
 ---
 
 ### 4.0 Booleans
@@ -438,6 +442,8 @@
 
 `INT` and `FLT` type annotations MAY include a base specifier written immediately after the type name with no intervening whitespace, in the form `INT{base}` or `FLT{base}`. The `{base}` suffix is part of the type annotation and therefore MUST appear before the required space that separates the type from the declared name. For example, `INT{0d2} value` declares a binary integer, while `FLT{0x} value` declares a hexadecimal float. A base of `0` (typically written as the bare type name) denotes the parent type and accepts any valid numeric base.
 
+`MAP` type annotations MAY include a template specifier written immediately after the type name with no intervening whitespace, in the form `MAP{template}`. The `{template}` suffix is part of the type annotation and therefore MUST appear before the required space that separates the type from the declared name. For example, `MAP{<"x" = 0d1>} value` declares a map that requires an `"x"` key with integer value. The `template` MUST evaluate to a `MAP`. Signatures produced by the `SIGNATURE` built-in MUST include the template in the type annotation for named `MAP` bindings.
+
 Reading an undeclared symbol, a declared-but-never-assigned symbol, or a deleted symbol MUST raise a runtime error. Removing a binding MUST preserve its recorded static type, so any later re-assignment to the same name MUST still match the original type.
 
 Re-assignment MUST preserve the declared type for the lifetime of the symbol, including after deletion and re-creation. Symbol existence, lifetime, and mutability MAY be inspected or modified only through the language's dedicated symbol-management facilities.

src/ast.c

@@ -61,14 +61,15 @@ Expr *expr_ident(char *name, int line, int column) {
     return expr;
 }
 
-Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, int line, int column) {
+Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, Expr *template_expr, int line, int column) {
     Expr *expr = ast_alloc(sizeof(Expr));
     expr->type = EXPR_TYPED_IDENT;
     expr->line = line;
     expr->column = column;
     expr->as.typed_ident.decl_type = decl_type;
     expr->as.typed_ident.decl_base = decl_base;
     expr->as.typed_ident.name = name;
+    expr->as.typed_ident.template_expr = template_expr;
     return expr;
 }
 
@@ -146,14 +147,16 @@ Expr *expr_wildcard(int line, int column) {
     return expr;
 }
 
-Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Stmt *body, int line, int column) {
+Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr *return_template_expr, Stmt *body,
+                  int line, int column) {
     Expr *expr = ast_alloc(sizeof(Expr));
     expr->type = EXPR_LAMBDA;
     expr->line = line;
     expr->column = column;
     expr->as.lambda.params = params;
     expr->as.lambda.return_type = return_type;
     expr->as.lambda.return_base = return_base;
+    expr->as.lambda.return_template_expr = return_template_expr;
     expr->as.lambda.body = body;
     return expr;
 }
@@ -223,8 +226,8 @@ Stmt *stmt_expr(Expr *expr, int line, int column) {
     return stmt;
 }
 
-Stmt *stmt_assign(bool has_type, DeclType decl_type, int decl_base, char *name, Expr *target, Expr *value, int line,
-                  int column) {
+Stmt *stmt_assign(bool has_type, DeclType decl_type, int decl_base, char *name, Expr *target, Expr *value,
+                  Expr *template_expr, int line, int column) {
     Stmt *stmt = ast_alloc(sizeof(Stmt));
     stmt->type = STMT_ASSIGN;
     stmt->line = line;
@@ -235,17 +238,19 @@ Stmt *stmt_assign(bool has_type, DeclType decl_type, int decl_base, char *name,
     stmt->as.assign.name = name;
     stmt->as.assign.target = target;
     stmt->as.assign.value = value;
+    stmt->as.assign.template_expr = template_expr;
     return stmt;
 }
 
-Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, int line, int column) {
+Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, Expr *template_expr, int line, int column) {
     Stmt *stmt = ast_alloc(sizeof(Stmt));
     stmt->type = STMT_DECL;
     stmt->line = line;
     stmt->column = column;
     stmt->as.decl.decl_type = decl_type;
     stmt->as.decl.decl_base = decl_base;
     stmt->as.decl.name = name;
+    stmt->as.decl.template_expr = template_expr;
     return stmt;
 }
 
@@ -291,14 +296,16 @@ Stmt *stmt_parfor(char *counter, Expr *target, Stmt *body, int line, int column)
     return stmt;
 }
 
-Stmt *stmt_func(char *name, DeclType ret, int return_base, Stmt *body, int line, int column) {
+Stmt *stmt_func(char *name, DeclType ret, int return_base, Expr *return_template_expr, Stmt *body, int line,
+                int column) {
     Stmt *stmt = ast_alloc(sizeof(Stmt));
     stmt->type = STMT_FUNC;
     stmt->line = line;
     stmt->column = column;
     stmt->as.func_stmt.name = name;
     stmt->as.func_stmt.return_type = ret;
     stmt->as.func_stmt.return_base = return_base;
+    stmt->as.func_stmt.return_template_expr = return_template_expr;
     stmt->as.func_stmt.body = body;
     return stmt;
 }
@@ -432,6 +439,7 @@ void free_expr(Expr *expr) {
         break;
     case EXPR_TYPED_IDENT:
         free(expr->as.typed_ident.name);
+        free_expr(expr->as.typed_ident.template_expr);
         break;
     case EXPR_PTR:
         free(expr->as.ptr_name);
@@ -455,8 +463,10 @@ void free_expr(Expr *expr) {
         for (size_t i = 0; i < expr->as.lambda.params.count; i++) {
             free(expr->as.lambda.params.items[i].name);
             free_expr(expr->as.lambda.params.items[i].default_value);
+            free_expr(expr->as.lambda.params.items[i].template_expr);
         }
         free(expr->as.lambda.params.items);
+        free_expr(expr->as.lambda.return_template_expr);
         free_stmt(expr->as.lambda.body);
         break;
     case EXPR_IDENT:
@@ -501,9 +511,11 @@ void free_stmt(Stmt *stmt) {
             free_expr(stmt->as.assign.target);
         }
         free_expr(stmt->as.assign.value);
+        free_expr(stmt->as.assign.template_expr);
         break;
     case STMT_DECL:
         free(stmt->as.decl.name);
+        free_expr(stmt->as.decl.template_expr);
         break;
     case STMT_IF:
         free_expr(stmt->as.if_stmt.condition);
@@ -531,8 +543,10 @@ void free_stmt(Stmt *stmt) {
         for (size_t i = 0; i < stmt->as.func_stmt.params.count; i++) {
             free(stmt->as.func_stmt.params.items[i].name);
             free_expr(stmt->as.func_stmt.params.items[i].default_value);
+            free_expr(stmt->as.func_stmt.params.items[i].template_expr);
         }
         free(stmt->as.func_stmt.params.items);
+        free_expr(stmt->as.func_stmt.return_template_expr);
         free_stmt(stmt->as.func_stmt.body);
         break;
     case STMT_RETURN:

src/ast.h

@@ -24,6 +24,7 @@ typedef struct Param {
     char *name;
     bool coerced;
     Expr *default_value; // optional
+    Expr *template_expr; // NEW: MAP template expression, NULL if none
 } Param;
 
 typedef struct ParamList {
@@ -77,6 +78,7 @@ struct Expr {
             DeclType decl_type;
             int decl_base; // 0 = parent INT/FLT, 2..64 = named base
             char *name;
+            Expr *template_expr; // NEW: MAP template expression, NULL if none
         } typed_ident;
         struct {
             Expr *callee;
@@ -92,7 +94,8 @@ struct Expr {
         struct {
             ParamList params;
             DeclType return_type;
-            int return_base; // 0 = parent INT/FLT, 2..64 = named base
+            int return_base;            // 0 = parent INT/FLT, 2..64 = named base
+            Expr *return_template_expr; // NEW: MAP return template, NULL if none
             Stmt *body;
         } lambda;
         ExprList tns_items;
@@ -157,11 +160,13 @@ struct Stmt {
             char *name;
             Expr *target;
             Expr *value;
+            Expr *template_expr; // NEW: MAP template expression, NULL if none
         } assign;
         struct {
             DeclType decl_type;
             int decl_base; // 0 = parent INT/FLT, 2..64 = named base
             char *name;
+            Expr *template_expr; // NEW: MAP template expression, NULL if none
         } decl;
         struct {
             Expr *condition;
@@ -188,7 +193,8 @@ struct Stmt {
             char *name;
             ParamList params;
             DeclType return_type;
-            int return_base; // 0 = parent INT/FLT, 2..64 = named base
+            int return_base;            // 0 = parent INT/FLT, 2..64 = named base
+            Expr *return_template_expr; // NEW: MAP return template, NULL if none
             Stmt *body;
         } func_stmt;
         struct {
@@ -227,7 +233,7 @@ Expr *expr_flt(double value, int base, int base_is_nan, int line, int column);
 Expr *expr_str(char *value, int line, int column);
 Expr *expr_ptr(char *name, int line, int column);
 Expr *expr_ident(char *name, int line, int column);
-Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, int line, int column);
+Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, Expr *template_expr, int line, int column);
 Expr *expr_call(Expr *callee, int line, int column);
 void call_kw_add(Expr *call, char *name, Expr *value);
 Expr *expr_tns(int line, int column);
@@ -236,20 +242,22 @@ Expr *expr_map(int line, int column);
 Expr *expr_index(Expr *target, int line, int column, bool is_map);
 Expr *expr_range(Expr *start, Expr *end, int line, int column);
 Expr *expr_wildcard(int line, int column);
-Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Stmt *body, int line, int column);
+Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr *return_template_expr, Stmt *body,
+                  int line, int column);
 void expr_list_add(ExprList *list, Expr *expr);
 
 Stmt *stmt_block(int line, int column);
 Stmt *stmt_async(Stmt *body, int line, int column);
 Stmt *stmt_expr(Expr *expr, int line, int column);
-Stmt *stmt_assign(bool has_type, DeclType decl_type, int decl_base, char *name, Expr *target, Expr *value, int line,
-                  int column);
-Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, int line, int column);
+Stmt *stmt_assign(bool has_type, DeclType decl_type, int decl_base, char *name, Expr *target, Expr *value,
+                  Expr *template_expr, int line, int column);
+Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, Expr *template_expr, int line, int column);
 Stmt *stmt_if(Expr *cond, Stmt *then_branch, int line, int column);
 Stmt *stmt_while(Expr *cond, Stmt *body, int line, int column);
 Stmt *stmt_for(char *counter, Expr *target, Stmt *body, int line, int column);
 Stmt *stmt_parfor(char *counter, Expr *target, Stmt *body, int line, int column);
-Stmt *stmt_func(char *name, DeclType ret, int return_base, Stmt *body, int line, int column);
+Stmt *stmt_func(char *name, DeclType ret, int return_base, Expr *return_template_expr, Stmt *body, int line,
+                int column);
 Stmt *stmt_return(Expr *value, int line, int column);
 Stmt *stmt_pop(Expr *expr, int line, int column);
 Stmt *stmt_break(Expr *value, int line, int column);