Update terminology: template -> schema (closes #234)

Author: python-processing-unit

docs/SPECIFICATION.html

@@ -96,9 +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.
 
-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.
+For `MAP` types, a declaration MAY specify a schema `MAP` by writing `MAP{schema} name`, where `schema` is any expression that evaluates to a `MAP`. A named-`MAP` type is a subtype of its parent `MAP` type: `MAP{schema}` values are `MAP`s, but an assignment to a named-`MAP` binding requires the assigned value to match the schema 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.
+The first assignment to a symbol MUST use a typed form such as `TYPE name = expression`, `TYPE{base} name = expression`, or `MAP{schema} 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")`.
 
@@ -178,7 +178,7 @@
 
 `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.
+`MAP` additionally supports named-schema variants written `MAP{schema}`, where `schema` is any expression that evaluates to a `MAP`. A named-schema type and its parent are the same runtime type, but static type checking treats mismatched schemas as incompatible. `MAP` accepts any `MAP` value; `MAP{schema}` only accepts values whose entries satisfy the schema under the default key-presence rules of the `MATCH` operator. Named `MAP` types with different schemas are treated as distinct types.
 
 ---
 
@@ -444,7 +444,7 @@
 
 `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.
+`MAP` type annotations MAY include a schema specifier written immediately after the type name with no intervening whitespace, in the form `MAP{schema}`. The `{schema}` 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 `schema` MUST evaluate to a `MAP`. Signatures produced by the `SIGNATURE` built-in MUST include the schema 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.
 
@@ -841,7 +841,7 @@
 
 - `BOOL KEYIN(INT|FLT|STR key, MAP map)` and `BOOL VALUEIN(ANY value, MAP map)` = MUST return `TRUE` when the given key or value occurs in `map` and `FALSE` otherwise.
 
-- `BOOL MATCH(MAP map, MAP template, INT typing = 0, INT recurse = 0, INT shape = 0)` = MUST return `TRUE` if every key in `template` is present in `map` and, when `typing`, `shape`, or `recurse` is nonzero, the corresponding matched values also satisfy type, shape, and recursive nesting constraints. If `template` contains a key `"match"` whose value is a `MAP`, that entry is metadata and is not itself required in `map`: the effective value of each parameter is the explicit keyword argument if supplied, otherwise the metadata subkey if present and valid, otherwise the implicit default `0`. Each metadata key MUST be an `INT`, and an invalid `"match"` entry, unknown metadata subkey name, or metadata subkey value that is not `INT` MUST cause `MATCH` to return `FALSE` rather than raising an error. A non-`MAP` `"match"` value is matched as an ordinary key.
+- `BOOL MATCH(MAP map, MAP schema, INT typing = 0, INT recurse = 0, INT shape = 0)` = MUST return `TRUE` if every key in `schema` is present in `map` and, when `typing`, `shape`, or `recurse` is nonzero, the corresponding matched values also satisfy type, shape, and recursive nesting constraints. If `schema` contains a key `"match"` whose value is a `MAP`, that entry is metadata and is not itself required in `map`: the effective value of each parameter is the explicit keyword argument if supplied, otherwise the metadata subkey if present and valid, otherwise the implicit default `0`. Each metadata key MUST be an `INT`, and an invalid `"match"` entry, unknown metadata subkey name, or metadata subkey value that is not `INT` MUST cause `MATCH` to return `FALSE` rather than raising an error. A non-`MAP` `"match"` value is matched as an ordinary key.
 
 - `MAP INV(MAP map)` = MUST return a new map whose keys and values are reversed. Every value in `map` MUST be a scalar key type (`INT`, `FLT`, or `STR`), and duplicate values MUST raise a runtime error.
 

src/ast.c

@@ -61,15 +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, Expr *template_expr, int line, int column) {
+Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, Expr *schema_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;
+    expr->as.typed_ident.schema_expr = schema_expr;
     return expr;
 }
 
@@ -156,7 +156,7 @@ Expr *expr_fmt_str(ExprList parts, int line, int column) {
     return expr;
 }
 
-Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr *return_template_expr, Stmt *body,
+Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr *return_schema_expr, Stmt *body,
                   int line, int column) {
     Expr *expr = ast_alloc(sizeof(Expr));
     expr->type = EXPR_LAMBDA;
@@ -165,7 +165,7 @@ Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr
     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.return_schema_expr = return_schema_expr;
     expr->as.lambda.body = body;
     return expr;
 }
@@ -236,7 +236,7 @@ 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,
-                  Expr *template_expr, int line, int column) {
+                  Expr *schema_expr, int line, int column) {
     Stmt *stmt = ast_alloc(sizeof(Stmt));
     stmt->type = STMT_ASSIGN;
     stmt->line = line;
@@ -247,19 +247,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;
+    stmt->as.assign.schema_expr = schema_expr;
     return stmt;
 }
 
-Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, Expr *template_expr, int line, int column) {
+Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, Expr *schema_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;
+    stmt->as.decl.schema_expr = schema_expr;
     return stmt;
 }
 
@@ -305,16 +305,15 @@ 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, Expr *return_template_expr, Stmt *body, int line,
-                int column) {
+Stmt *stmt_func(char *name, DeclType ret, int return_base, Expr *return_schema_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.return_schema_expr = return_schema_expr;
     stmt->as.func_stmt.body = body;
     return stmt;
 }
@@ -448,7 +447,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);
+        free_expr(expr->as.typed_ident.schema_expr);
         break;
     case EXPR_PTR:
         free(expr->as.ptr_name);
@@ -472,10 +471,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(expr->as.lambda.params.items[i].schema_expr);
         }
         free(expr->as.lambda.params.items);
-        free_expr(expr->as.lambda.return_template_expr);
+        free_expr(expr->as.lambda.return_schema_expr);
         free_stmt(expr->as.lambda.body);
         break;
     case EXPR_FMT_STR:
@@ -523,11 +522,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);
+        free_expr(stmt->as.assign.schema_expr);
         break;
     case STMT_DECL:
         free(stmt->as.decl.name);
-        free_expr(stmt->as.decl.template_expr);
+        free_expr(stmt->as.decl.schema_expr);
         break;
     case STMT_IF:
         free_expr(stmt->as.if_stmt.condition);
@@ -555,10 +554,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_expr(stmt->as.func_stmt.params.items[i].schema_expr);
         }
         free(stmt->as.func_stmt.params.items);
-        free_expr(stmt->as.func_stmt.return_template_expr);
+        free_expr(stmt->as.func_stmt.return_schema_expr);
         free_stmt(stmt->as.func_stmt.body);
         break;
     case STMT_RETURN:

src/ast.h

@@ -24,7 +24,7 @@ typedef struct Param {
     char *name;
     bool coerced;
     Expr *default_value; // optional
-    Expr *template_expr; // NEW: MAP template expression, NULL if none
+    Expr *schema_expr;   // NEW: MAP schema expression, NULL if none
 } Param;
 
 typedef struct ParamList {
@@ -79,7 +79,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
+            Expr *schema_expr; // NEW: MAP schema expression, NULL if none
         } typed_ident;
         struct {
             Expr *callee;
@@ -98,8 +98,8 @@ struct Expr {
         struct {
             ParamList params;
             DeclType return_type;
-            int return_base;            // 0 = parent INT/FLT, 2..64 = named base
-            Expr *return_template_expr; // NEW: MAP return template, NULL if none
+            int return_base;          // 0 = parent INT/FLT, 2..64 = named base
+            Expr *return_schema_expr; // NEW: MAP return schema, NULL if none
             Stmt *body;
         } lambda;
         ExprList tns_items;
@@ -164,13 +164,13 @@ struct Stmt {
             char *name;
             Expr *target;
             Expr *value;
-            Expr *template_expr; // NEW: MAP template expression, NULL if none
+            Expr *schema_expr; // NEW: MAP schema 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
+            Expr *schema_expr; // NEW: MAP schema expression, NULL if none
         } decl;
         struct {
             Expr *condition;
@@ -197,8 +197,8 @@ struct Stmt {
             char *name;
             ParamList params;
             DeclType return_type;
-            int return_base;            // 0 = parent INT/FLT, 2..64 = named base
-            Expr *return_template_expr; // NEW: MAP return template, NULL if none
+            int return_base;          // 0 = parent INT/FLT, 2..64 = named base
+            Expr *return_schema_expr; // NEW: MAP return schema, NULL if none
             Stmt *body;
         } func_stmt;
         struct {
@@ -237,7 +237,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, Expr *template_expr, int line, int column);
+Expr *expr_typed_ident(DeclType decl_type, int decl_base, char *name, Expr *schema_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);
@@ -246,7 +246,7 @@ 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, Expr *return_template_expr, Stmt *body,
+Expr *expr_lambda(ParamList params, DeclType return_type, int return_base, Expr *return_schema_expr, Stmt *body,
                   int line, int column);
 Expr *expr_fmt_str(ExprList parts, int line, int column);
 void expr_list_add(ExprList *list, Expr *expr);
@@ -255,14 +255,13 @@ 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,
-                  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);
+                  Expr *schema_expr, int line, int column);
+Stmt *stmt_decl(DeclType decl_type, int decl_base, char *name, Expr *schema_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, Expr *return_template_expr, Stmt *body, int line,
-                int column);
+Stmt *stmt_func(char *name, DeclType ret, int return_base, Expr *return_schema_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);