Rename MATCH to VALIDATE (closes #243)

Author: python-processing-unit

docs/specification/3-statements.html

@@ -35,7 +35,7 @@
 
 For `int` and `float` 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 `float{base}` values are `float`s, but an assignment to a named-base binding requires the value's base to match the declared base. The parent types `int` and `float` (equivalent to `int{0}` and `float{0}`) accept values of any valid numeric base.
 
-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.
+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 `VALIDATE` 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{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.
 

docs/specification/4-types.html

@@ -21,7 +21,7 @@
 
 `int` and `float` additionally support named-base variants written `int{base}` and `float{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 `float` (base `0`) accept any valid numeric base; `int{base}` and `float{base}` only accept values whose stored base equals the declared base.
 
-`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.
+`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 `VALIDATE` operator. Named `map` types with different schemas are treated as distinct types.
 
 ---
 

docs/specification/9-built-ins.html

@@ -167,7 +167,7 @@
 
 - `bool KEYIN(int|float|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 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.
+- `bool VALIDATE(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 `"validate"` 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 `"validate"` entry, unknown metadata subkey name, or metadata subkey value that is not `int` MUST cause `VALIDATE` to return `false` rather than raising an error. A non-`map` `"validate"` 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`, `float`, or `str`), and duplicate values MUST raise a runtime error.
 

src/builtins.c

@@ -9509,22 +9509,22 @@ static Value builtin_valuein(Interpreter *interp, Value *args, int argc, Expr **
     return value_bool(false);
 }
 
-static int match_read_metadata(Map *tpl, int *typing, int *recurse, int *shape, int explicit_typing,
+static int validate_read_metadata(Map *tpl, int *typing, int *recurse, int *shape, int explicit_typing,
                                int explicit_recurse, int explicit_shape);
 
-// Helper: recursive match implementation
-static int match_map_internal(Map *m, Map *tpl, int typing, int recurse, int shape, int explicit_typing,
+// Helper: recursive validate implementation
+static int validate_map_internal(Map *m, Map *tpl, int typing, int recurse, int shape, int explicit_typing,
                               int explicit_recurse, int explicit_shape) {
     if (!tpl) {
         return 1;
     }
-    if (!match_read_metadata(tpl, &typing, &recurse, &shape, explicit_typing, explicit_recurse, explicit_shape)) {
+    if (!validate_read_metadata(tpl, &typing, &recurse, &shape, explicit_typing, explicit_recurse, explicit_shape)) {
         return 0;
     }
     for (size_t i = 0; i < tpl->count; i++) {
         Value tkey = tpl->items[i].key;
         Value tval = tpl->items[i].value;
-        if (tkey.type == VAL_STR && tkey.as.s && strcmp(tkey.as.s, "match") == 0) {
+        if (tkey.type == VAL_STR && tkey.as.s && strcmp(tkey.as.s, "validate") == 0) {
             if (tval.type == VAL_MAP && tval.as.map) {
                 continue;
             }
@@ -9571,7 +9571,7 @@ static int match_map_internal(Map *m, Map *tpl, int typing, int recurse, int sha
             Map *mm = mval.as.map;
             Map *tt = tval.as.map;
             int ok =
-                match_map_internal(mm, tt, typing, recurse, shape, explicit_typing, explicit_recurse, explicit_shape);
+                validate_map_internal(mm, tt, typing, recurse, shape, explicit_typing, explicit_recurse, explicit_shape);
             value_free(mval);
             if (!ok) {
                 return 0;
@@ -9583,25 +9583,25 @@ static int match_map_internal(Map *m, Map *tpl, int typing, int recurse, int sha
     return 1;
 }
 
-static int match_read_metadata(Map *tpl, int *typing, int *recurse, int *shape, int explicit_typing,
+static int validate_read_metadata(Map *tpl, int *typing, int *recurse, int *shape, int explicit_typing,
                                int explicit_recurse, int explicit_shape) {
-    Value match_key = value_str("match");
+    Value validate_key = value_str("validate");
     int found = 0;
-    Value match_value = value_map_get((Value){.type = VAL_MAP, .as.map = tpl}, match_key, &found);
-    value_free(match_key);
+    Value validate_value = value_map_get((Value){.type = VAL_MAP, .as.map = tpl}, validate_key, &found);
+    value_free(validate_key);
     if (!found) {
         return 1;
     }
-    if (match_value.type != VAL_MAP) {
-        value_free(match_value);
+    if (validate_value.type != VAL_MAP) {
+        value_free(validate_value);
         return 1;
     }
-    if (!match_value.as.map) {
-        value_free(match_value);
+    if (!validate_value.as.map) {
+        value_free(validate_value);
         return 0;
     }
 
-    Map *metadata = match_value.as.map;
+    Map *metadata = validate_value.as.map;
     for (size_t i = 0; i < metadata->count; i++) {
         Value subkey = metadata->items[i].key;
         Value subval = metadata->items[i].value;
@@ -9617,28 +9617,28 @@ static int match_read_metadata(Map *tpl, int *typing, int *recurse, int *shape,
             target = shape;
             explicit = explicit_shape;
         } else {
-            value_free(match_value);
+            value_free(validate_value);
             return 0;
         }
         if (subval.type != VAL_INT) {
-            value_free(match_value);
+            value_free(validate_value);
             return 0;
         }
         if (!explicit) {
             *target = subval.as.i ? 1 : 0;
         }
     }
-    value_free(match_value);
+    value_free(validate_value);
     return 1;
 }
 
-// MATCH(map, schema, typing=0, recurse=0, shape=0):int
-static Value builtin_match(Interpreter *interp, Value *args, int argc, Expr **arg_nodes, Env *env, int line, int col) {
+// VALIDATE(map, schema, typing=0, recurse=0, shape=0):int
+static Value builtin_validate(Interpreter *interp, Value *args, int argc, Expr **arg_nodes, Env *env, int line, int col) {
     (void)arg_nodes;
     (void)env;
     (void)argc;
     if (args[0].type != VAL_MAP || args[1].type != VAL_MAP) {
-        RUNTIME_ERROR(interp, "MATCH expects two map arguments", line, col);
+        RUNTIME_ERROR(interp, "VALIDATE expects two map arguments", line, col);
     }
     int typing = 0;
     int recurse = 0;
@@ -9647,23 +9647,23 @@ static Value builtin_match(Interpreter *interp, Value *args, int argc, Expr **ar
     int explicit_recurse = 0;
     int explicit_shape = 0;
     if (argc >= 3 && args[2].type != VAL_NULL) {
-        EXPECT_INT(args[2], "MATCH", interp, line, col);
+        EXPECT_INT(args[2], "VALIDATE", interp, line, col);
         typing = args[2].as.i ? 1 : 0;
         explicit_typing = 1;
     }
     if (argc >= 4 && args[3].type != VAL_NULL) {
-        EXPECT_INT(args[3], "MATCH", interp, line, col);
+        EXPECT_INT(args[3], "VALIDATE", interp, line, col);
         recurse = args[3].as.i ? 1 : 0;
         explicit_recurse = 1;
     }
     if (argc >= 5 && args[4].type != VAL_NULL) {
-        EXPECT_INT(args[4], "MATCH", interp, line, col);
+        EXPECT_INT(args[4], "VALIDATE", interp, line, col);
         shape = args[4].as.i ? 1 : 0;
         explicit_shape = 1;
     }
     Map *m = args[0].as.map;
     Map *tpl = args[1].as.map;
-    int ok = match_map_internal(m, tpl, typing, recurse, shape, explicit_typing, explicit_recurse, explicit_shape);
+    int ok = validate_map_internal(m, tpl, typing, recurse, shape, explicit_typing, explicit_recurse, explicit_shape);
     return value_bool(ok != 0);
 }
 
@@ -11693,7 +11693,7 @@ static Value builtin_parallel(Interpreter *interp, Value *args, int argc, Expr *
 static const char *builtin_params_round[] = {"x", "ndigits", "mode"};
 static const char *builtin_params_bytes[] = {"x", "endian"};
 static const char *builtin_params_split[] = {"s", "delimiter"};
-static const char *builtin_params_match[] = {"value", "schema", "typing", "recurse", "shape"};
+static const char *builtin_params_validate[] = {"value", "schema", "typing", "recurse", "shape"};
 static const char *builtin_params_readfile[] = {"path", "coding"};
 static const char *builtin_params_writefile[] = {"data", "path", "coding"};
 static const char *builtin_params_pause[] = {"thr", "seconds"};
@@ -11815,7 +11815,7 @@ static BuiltinFunction builtins_table[] = {
     {"VALUES", 1, 1, builtin_values},
     {"KEYIN", 2, 2, builtin_keyin},
     {"VALUEIN", 2, 2, builtin_valuein},
-    {"MATCH", 2, 5, builtin_match, builtin_params_match, 5},
+    {"VALIDATE", 2, 5, builtin_validate, builtin_params_validate, 5},
     {"ILEN", 1, 1, builtin_ilen},
     {"LEN", 0, -1, builtin_len},
 

src/value.c

@@ -1089,8 +1089,8 @@ static Value value_map_get_locked(Value mapval, Value key, int *found) {
     return value_copy(m->items[idx].value);
 }
 
-// Minimal match implementation for env-check path (defaults: typing=0, recurse=0, shape=0).
-// Supports "match" metadata override from the schema.
+// Minimal validate implementation for env-check path (defaults: typing=0, recurse=0, shape=0).
+// Supports "validate" metadata override from the schema.
 // Thread-safe: acquires locks on both maps during comparison.
 bool value_map_matches(Value map, Value templ) {
     if (map.type != VAL_MAP || templ.type != VAL_MAP) {
@@ -1113,7 +1113,7 @@ bool value_map_matches(Value map, Value templ) {
         Value tkey = t->items[i].key;
         Value tval = t->items[i].value;
         if (tkey.type == VAL_STR && tkey.as.s && tval.type == VAL_MAP && tval.as.map &&
-            strcmp(tkey.as.s, "match") == 0) {
+            strcmp(tkey.as.s, "validate") == 0) {
             continue;
         }
         int found = 0;

src/value.h

@@ -134,9 +134,9 @@ bool decl_type_accepts_value(DeclType expected, int expected_base, Value value);
 // Format a type name including base for int/float. Returns buf.
 const char *decl_type_name_base(DeclType type, int base, char *buf, size_t buf_size);
 
-// Match a map value against a map schema (same semantics as MATCH with defaults).
-// Returns true if all keys in `templ` exist in `map` and satisfy the match (typing=0, recurse=0, shape=0).
-// Supports "match" metadata override in the schema.
+// Validate a map value against a map schema (same semantics as VALIDATE with defaults).
+// Returns true if all keys in `templ` exist in `map` and satisfy the validate (typing=0, recurse=0, shape=0).
+// Supports "validate" metadata override in the schema.
 bool value_map_matches(Value map, Value templ);
 
 #endif // VALUE_H