Add \F escape code (closes #235)

Author: python-processing-unit

docs/SPECIFICATION.html

@@ -248,6 +248,8 @@
 
 - `\R` = raw mode toggle. In raw mode, all escape sequences (with the exception of `\R`) are treated as plain text until the next `\R` or the end of the string literal.
 
+- `\F` = formatted mode toggle. When formatted mode is on, `{` and `}` delimit embedded expressions within the string literal. The embedded expression is parsed, evaluated, coerced to `STR`, and concatenated into the resulting string. Braces inside the embedded expression are matched by depth: the first `}` that closes the outer `{` terminates the interpolation. Nested braces inside the expression (e.g., block bodies, map literals) are consumed as part of the expression. Raw mode supersedes formatted mode: when raw mode is active, `{` and `}` are treated as literal characters even if formatted mode is also active.
+
 If an invalid escape sequence (or a non-Hexadecimal value when one is expected by the escape sequence) is encountered in a `STR` literal, an error MUST be raised.
 
 ---

src/ast.c

@@ -147,6 +147,15 @@ Expr *expr_wildcard(int line, int column) {
     return expr;
 }
 
+Expr *expr_fmt_str(ExprList parts, int line, int column) {
+    Expr *expr = ast_alloc(sizeof(Expr));
+    expr->type = EXPR_FMT_STR;
+    expr->line = line;
+    expr->column = column;
+    expr->as.fmt_str.parts = parts;
+    return expr;
+}
+
 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));
@@ -469,6 +478,9 @@ void free_expr(Expr *expr) {
         free_expr(expr->as.lambda.return_template_expr);
         free_stmt(expr->as.lambda.body);
         break;
+    case EXPR_FMT_STR:
+        free_expr_list(&expr->as.fmt_str.parts);
+        break;
     case EXPR_IDENT:
         free(expr->as.ident);
         break;

src/ast.h

@@ -48,7 +48,8 @@ typedef enum {
     EXPR_INDEX,
     EXPR_RANGE,
     EXPR_WILDCARD,
-    EXPR_LAMBDA
+    EXPR_LAMBDA,
+    EXPR_FMT_STR
 } ExprType;
 
 typedef struct {
@@ -91,6 +92,9 @@ struct Expr {
         struct {
             Stmt *block;
         } async;
+        struct {
+            ExprList parts; // alternating STR parts and embedded expressions
+        } fmt_str;
         struct {
             ParamList params;
             DeclType return_type;
@@ -244,6 +248,7 @@ 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,
                   int line, int column);
+Expr *expr_fmt_str(ExprList parts, int line, int column);
 void expr_list_add(ExprList *list, Expr *expr);
 
 Stmt *stmt_block(int line, int column);

src/builtins.c

@@ -6448,6 +6448,12 @@ static Value builtin_str(Interpreter *interp, Value *args, int argc, Expr **arg_
     RUNTIME_ERROR(interp, "STR expects BOOL, STR, INT, or FLT", line, col);
 }
 
+Value builtin_str_value(Interpreter *interp, Value v, int line, int col) {
+    Value args[1];
+    args[0] = v;
+    return builtin_str(interp, args, 1, NULL, NULL, line, col);
+}
+
 // BYTES(INT: n, endian = "big"):TNS
 static Value builtin_bytes(Interpreter *interp, Value *args, int argc, Expr **arg_nodes, Env *env, int line, int col) {
     (void)arg_nodes;

src/builtins.h

@@ -41,4 +41,7 @@ void builtins_reset_dynamic(void);
 
 const char *decl_type_name(DeclType dt);
 
+// Convert any value to STR (BOOL, INT, FLT, STR). Returns a newly allocated STR value.
+Value builtin_str_value(Interpreter *interp, Value v, int line, int col);
+
 #endif // BUILTINS_H

src/interpreter.c

@@ -1246,6 +1246,64 @@ Value eval_expr(Interpreter *interp, Expr *expr, Env *env) {
     case EXPR_STR:
         return value_str(expr->as.str_value);
 
+    case EXPR_FMT_STR: {
+        size_t total_len = 0;
+        size_t part_count = expr->as.fmt_str.parts.count;
+        Value *temp_vals = safe_malloc(sizeof(Value) * part_count);
+        for (size_t i = 0; i < part_count; i++) {
+            Expr *part = expr->as.fmt_str.parts.items[i];
+            if (part->type == EXPR_STR) {
+                total_len += strlen(part->as.str_value ? part->as.str_value : "");
+            } else {
+                Value v = eval_expr(interp, part, env);
+                if (interp->error) {
+                    for (size_t j = 0; j < i; j++) {
+                        if (expr->as.fmt_str.parts.items[j]->type != EXPR_STR) {
+                            value_free(temp_vals[j]);
+                        }
+                    }
+                    free(temp_vals);
+                    return value_null();
+                }
+                temp_vals[i] = builtin_str_value(interp, v, expr->line, expr->column);
+                if (interp->error) {
+                    for (size_t j = 0; j < i; j++) {
+                        if (expr->as.fmt_str.parts.items[j]->type != EXPR_STR) {
+                            value_free(temp_vals[j]);
+                        }
+                    }
+                    free(temp_vals);
+                    return value_null();
+                }
+                total_len += strlen(temp_vals[i].as.s ? temp_vals[i].as.s : "");
+            }
+        }
+
+        char *result = safe_malloc(total_len + 1);
+        result[0] = '\0';
+        size_t pos = 0;
+        for (size_t i = 0; i < part_count; i++) {
+            Expr *part = expr->as.fmt_str.parts.items[i];
+            if (part->type == EXPR_STR) {
+                const char *s = part->as.str_value ? part->as.str_value : "";
+                size_t len = strlen(s);
+                memcpy(result + pos, s, len);
+                pos += len;
+            } else {
+                const char *s = temp_vals[i].as.s;
+                size_t len = strlen(s ? s : "");
+                memcpy(result + pos, s, len);
+                pos += len;
+                value_free(temp_vals[i]);
+            }
+        }
+        result[pos] = '\0';
+        free(temp_vals);
+        Value ret = value_str(result);
+        free(result);
+        return ret;
+    }
+
     case EXPR_IDENT: {
         Value v;
         DeclType dtype;