Implement Falcon Runtime

README.md

@@ -1,13 +1,13 @@
 ![image|690x338](https://community.appinventor.mit.edu/uploads/default/original/3X/e/d/ed3b9d22ddaefffb4fd5ab71964b8816c56c63a1.png)
 
-Falcon is a language designed for App Inventor to enable syntax-based programming and for incorporating agenting coding abilities.
+Falcon is a language designed for App Inventor to enable syntax-based programming and for incorporating agentic coding abilities.
 
 ## Quirks
 1. Falcon follows 1-based indexing.
 2. Falcon variables are dynamically typed. Do not declare variables.
 3. Lists and dictionaries are passed as references.
 4. Falcon follows Kotlin's style of functional expressions.
-5. Falcon does not have a return statement; the last expression in a body is returned.
+5. Falcon does not have a traditional return statement. In result functions, the last expression is returned. Use `yield` inside a result function for an early return.
 6. Falcon does NOT have a try-catch or a throw statement.
 7. Only single-line comments using double slash `//` are supported.
 8. Do not use `_` in place of unused variables
@@ -179,15 +179,44 @@ func double(n) = { n * 2 }
 Or multiple expressions:
 
 ```
-func FibSum(n) = {
+func Fib(n) = {
   if (n < 2) {
     n  
   } else {
-    FibSum(n - 1) + FibSum(n - 2)
+    Fib(n - 1) + Fib(n - 2)
   }
 }
 ```
-Note that there is no `return` statement in Falcon. The last statement in a body is taken as the output of an expression.
+Note that there is no `return` statement in Falcon. The last expression in a body is taken as the output of an expression.
+
+### yield
+
+`yield <expr>` exits a result function early and returns the given value to the caller. It only works inside result functions (`= { ... }`). If no `yield` is reached, the last expression in the body is returned as usual.
+
+```
+func first_divisible(n, list) = {
+  for (i: 1..list.listLen()) {
+    if (list[i] % n == 0) {
+      yield list[i]
+    }
+  }
+  -1
+}
+
+println(first_divisible(7, [3, 10, 21, 44]))  // Output: 21
+println(first_divisible(7, [1, 2, 3]))         // Output: -1
+```
+
+A common pattern is using `yield` as a guard clause:
+
+```
+func safe_div(a, b) = {
+  if (b == 0) {
+    yield 0
+  }
+  a / b
+}
+```
 
 ## Functions
 
@@ -298,7 +327,7 @@ e.g. `"Hello  ".trim()`
 ### Dictionary
 
 - `dictLen()`
-- `get(key)`
+- `get(key, notFound)`
 - `set(key, value)`
 - `delete(key)`
 - `getAtPath(path_list, notfound)`
@@ -376,7 +405,7 @@ Usage `.min { m, n -> bool_m_preceeds_n }` and `.max { m, n -> bool_m_preceeds_n
 local names = ["Bob", "Alice", "John"]
 // Find the longest name
 local longestName = names
-  .max { m, n -> n.textLen() > m.textLen() }  // use min { } for the shortest name
+  .max { m, n -> m.textLen() < n.textLen() }  // use min { } for the shortest name
 println(longestName)
 ```
 

lang/code/ast/blockly.go

@@ -173,9 +173,8 @@ func ensureStatement(expr Expr) Block {
 	// First evaluate Blockly(). True indicates we expect a statement.
 	// This gives time for if expressions to mutate to if statement.
 	aBlock := expr.Blockly(true)
-	if expr.Consumable(true) {
-		// It's still consumable, wrap around evaluate but ignore result
-		return Block{Type: "controls_eval_but_ignore", Values: []Value{{Block: aBlock}}}
+	if expr.Consumable() {
+		panic("result of `" + expr.String() + "` is never used")
 	}
 	return aBlock
 }

lang/code/ast/common/binary.go

@@ -15,16 +15,28 @@ type BinaryExpr struct {
 
 func (b *BinaryExpr) String() string {
 	myPrecedence := lex.PrecedenceOf(b.Where.Flags[0])
+	// For non-left-associative operators, right operands at the same precedence need parens
+	// to avoid changing semantics: e.g. 10-(3-2) must not become 10-3-2.
+	rightNeedsParensAtSamePrec := b.Operator == lex.Dash || b.Operator == lex.Slash || b.Operator == lex.Power
 	stringified := make([]string, len(b.Operands))
 	for i, operand := range b.Operands {
 		operandStr := operand.String()
+		needsParens := false
 		// If operand is a BinaryExpr with lower precedence, wrap it
 		if binExpr, ok := operand.(*BinaryExpr); ok {
-			if lex.PrecedenceOf(binExpr.Where.Flags[0]) < myPrecedence {
-				operandStr = "(" + operandStr + ")"
+			opPrec := lex.PrecedenceOf(binExpr.Where.Flags[0])
+			if opPrec < myPrecedence {
+				needsParens = true
+			} else if i > 0 && rightNeedsParensAtSamePrec && opPrec == myPrecedence {
+				needsParens = true
 			}
+		} else if !operand.Continuous() {
+			// Non-continuous expressions (e.g. if-else) need parens as binary operands
+			needsParens = true
+		}
+		if needsParens {
+			operandStr = "(" + operandStr + ")"
 		}
-
 		stringified[i] = operandStr
 	}
 	return strings.Join(stringified, " "+*b.Where.Content+" ")
@@ -39,7 +51,10 @@ func (b *BinaryExpr) CanRepeat(testOperator lex.Type) bool {
 		return false
 	}
 	switch b.Operator {
-	case lex.Power, lex.Dash, lex.Slash:
+	case lex.Power, lex.Dash, lex.Slash,
+		lex.Equals, lex.NotEquals, lex.TextEquals, lex.TextNotEquals,
+		lex.LessThan, lex.LessThanEqual, lex.GreatThan, lex.GreaterThanEqual,
+		lex.TextLessThan, lex.TextGreaterThan:
 		return false
 	default:
 		return true
@@ -75,11 +90,23 @@ func (b *BinaryExpr) Continuous() bool {
 	return false
 }
 
-func (b *BinaryExpr) Consumable(flags ...bool) bool {
+func (b *BinaryExpr) Consumable() bool {
 	return true
 }
 
 func (b *BinaryExpr) Signature() []ast.Signature {
+	switch b.Operator {
+	case lex.Plus, lex.Times, lex.Dash, lex.Slash, lex.Power, lex.Remainder, lex.BitwiseAnd, lex.BitwiseOr, lex.BitwiseXor:
+		b.ensureSignature(ast.SignNumb, ast.SignText)
+	case lex.LogicAnd, lex.LogicOr:
+		b.ensureSignature(ast.SignBool, ast.SignText)
+	case lex.Underscore:
+		// _ auto-converts any operand type to text at runtime; no type enforcement here.
+	case lex.TextEquals, lex.TextNotEquals, lex.TextLessThan, lex.TextGreaterThan:
+		b.ensureSignature(ast.SignText, ast.SignNumb)
+	case lex.LessThan, lex.LessThanEqual, lex.GreatThan, lex.GreaterThanEqual:
+		b.ensureSignature(ast.SignNumb, ast.SignText)
+	}
 	switch b.Operator {
 	case lex.BitwiseAnd, lex.BitwiseOr, lex.BitwiseXor:
 		return []ast.Signature{ast.SignNumb}
@@ -95,6 +122,8 @@ func (b *BinaryExpr) Signature() []ast.Signature {
 		return []ast.Signature{ast.SignText}
 	case lex.LessThan, lex.LessThanEqual, lex.GreatThan, lex.GreaterThanEqual:
 		return []ast.Signature{ast.SignBool}
+	case lex.Remainder:
+		return []ast.Signature{ast.SignNumb}
 	case lex.TextEquals, lex.TextNotEquals, lex.TextLessThan, lex.TextGreaterThan:
 		return []ast.Signature{ast.SignBool}
 	default:
@@ -103,6 +132,21 @@ func (b *BinaryExpr) Signature() []ast.Signature {
 	}
 }
 
+func (b *BinaryExpr) ensureSignature(acceptableSignature ...ast.Signature) {
+	if len(b.Operands) == 0 {
+		panic("BinaryExpr.ensureSignature: empty operands")
+	}
+	for _, op := range b.Operands {
+		opSigs := op.Signature()
+		for _, signature := range acceptableSignature {
+			if ast.HasSignature(opSigs, signature) {
+				return
+			}
+		}
+	}
+	b.Where.TypeError("Operator '%' requires % operand types", *b.Where.Content, ast.FormatSignatures(acceptableSignature))
+}
+
 func (b *BinaryExpr) textCompare() ast.Block {
 	var fieldOp string
 	switch b.Operator {
@@ -128,7 +172,7 @@ func (b *BinaryExpr) relationalExpr() ast.Block {
 	case lex.LessThan:
 		fieldOp = "LT"
 	case lex.LessThanEqual:
-		fieldOp = "LT"
+		fieldOp = "LTE"
 	case lex.GreatThan:
 		fieldOp = "GT"
 	case lex.GreaterThanEqual:

lang/code/ast/common/drop.go

@@ -0,0 +1,43 @@
+package common
+
+import "strings"
+
+// dropTypeWords lists the type-name suffixes (and direct function names) that
+// constitute a no-op type-conversion in Falcon's dynamic type system.
+// ".toString()", ".toStr()", ".toInt()", ".toNumber()" etc. are all identity
+// operations that should be silently dropped from the AST.
+var dropTypeWords = map[string]bool{
+	"string": true, "str": true, "text": true,
+	"int": true, "integer": true,
+	"num": true, "number": true, "float": true, "double": true,
+	"bool": true, "boolean": true,
+	"list": true, "array": true, "arr": true,
+	"dict": true, "map": true, "object": true, "obj": true,
+}
+
+// IsDropMethod reports whether a 0-arg method call named name is a no-op
+// type conversion that should be silently dropped.
+// Matches the "to<Type>" camelCase prefix pattern (e.g. toString, toStr,
+// toInt, toNumber, toList, toDict, toBoolean, …).
+func IsDropMethod(name string) bool {
+	lower := strings.ToLower(name)
+	if !strings.HasPrefix(lower, "to") || len(lower) <= 2 {
+		return false
+	}
+	return dropTypeWords[lower[2:]]
+}
+
+// IsDropFunction reports whether a 1-arg function call named name is a no-op
+// type-cast wrapper that should be dropped, keeping only its argument.
+// Matches both bare type names (string, int, number, …) and the "to<Type>"
+// prefix form (toString, toInt, …).
+func IsDropFunction(name string) bool {
+	lower := strings.ToLower(name)
+	if dropTypeWords[lower] {
+		return true
+	}
+	if strings.HasPrefix(lower, "to") && len(lower) > 2 {
+		return dropTypeWords[lower[2:]]
+	}
+	return false
+}

lang/code/ast/common/empty_socket.go

@@ -21,10 +21,10 @@ func (e *EmptySocket) Continuous() bool {
 	return true
 }
 
-func (e *EmptySocket) Consumable(flags ...bool) bool {
+func (e *EmptySocket) Consumable() bool {
 	return false
 }
 
 func (e *EmptySocket) Signature() []ast.Signature {
-	return []ast.Signature{ast.SignText}
+	return []ast.Signature{ast.SignNumb}
 }