Add support for named return values. Modify AST and code generation to accommodate new return type specifications.

Author: congwang-mk

SPEC.md

@@ -2356,21 +2356,14 @@ value = (value % modulus);                  // From: value %= modulus
 
 ## 7. Functions and Control Flow
 
-### 7.1 Function Declaration
-```ebnf
-function_declaration = [ attribute_list ] [ visibility ] [ "kernel" ] "fn" identifier "(" parameter_list ")" [ "->" return_type ] "{" statement_list "}" 
+### 7.1 Function Declaration Overview
 
-attribute_list = attribute { attribute }
-attribute = "@" attribute_name [ "(" attribute_args ")" ]
-attribute_name = "xdp" | "tc" | "kprobe" | "uprobe" | "tracepoint" | 
-                 "lsm" | "cgroup_skb" | "socket_filter" | "sk_lookup" | "struct_ops" | "kfunc"
-attribute_args = string_literal | identifier
+KernelScript functions support both traditional unnamed return types and modern named return values. The complete grammar is defined in Section 15 (Complete Formal Grammar).
 
-visibility = "pub" | "priv" 
-parameter_list = [ parameter { "," parameter } ] 
-parameter = identifier ":" type_annotation 
-return_type = type_annotation 
-```
+Key function types:
+- **eBPF program functions**: Attributed with `@xdp`, `@tc`, etc. - compile to eBPF bytecode
+- **Helper functions**: Attributed with `@helper` - shared across all eBPF programs
+- **Userspace functions**: No attributes - compile to native executable
 
 ### 7.2 eBPF Program Functions
 ```kernelscript
@@ -2387,7 +2380,127 @@ fn simple_xdp(ctx: *xdp_md) -> xdp_action {
 }
 ```
 
-### 7.3 Helper Functions
+### 7.3 Named Return Values
+
+KernelScript supports both unnamed and named return values following Go's syntax pattern:
+
+- **Unnamed returns** (backward compatible): `fn name() -> type`
+- **Named returns** (new): `fn name() -> var_name: type`
+
+Named return values automatically declare a local variable with the specified name and type. This variable can be used throughout the function, and naked returns (`return` without a value) will return the current value of the named variable.
+
+#### 7.3.1 Named Return Syntax Examples
+
+```kernelscript
+// Backward compatible unnamed return (unchanged)
+fn add_numbers(a: i32, b: i32) -> i32 {
+    return a + b
+}
+
+// Named return value - 'sum' becomes a local variable
+fn add_numbers_named(a: i32, b: i32) -> sum: i32 {
+    sum = a + b    // Named variable is automatically declared
+    return         // Naked return - returns current value of 'sum'
+}
+
+// Using named return in complex logic
+fn calculate_hash(data: *u8, len: u32) -> hash_value: u64 {
+    hash_value = 0  // Named return variable is available immediately
+    
+    for (i in 0..len) {
+        hash_value = hash_value * 31 + data[i]  // Modify throughout function
+    }
+    
+    return          // Naked return with computed hash_value
+}
+
+// Mixing named variables with explicit returns
+fn validate_packet(data: *u8, len: u32) -> is_valid: bool {
+    is_valid = false  // Start with default value
+    
+    if (len == 0) {
+        return        // Early naked return with is_valid = false
+    }
+    
+    if (data == null) {
+        return false  // Explicit return still works
+    }
+    
+    is_valid = true   // Set to true if all checks pass
+    return            // Final naked return
+}
+```
+
+#### 7.3.2 Named Returns in Different Contexts
+
+Named return values work consistently across all function types:
+
+```kernelscript
+// eBPF helper functions with named returns
+@helper
+fn extract_ip_header(ctx: *xdp_md) -> ip_hdr: *iphdr {
+    var data = ctx->data
+    var data_end = ctx->data_end
+    
+    if (data + 14 + 20 > data_end) {
+        ip_hdr = null
+        return  // Naked return with null
+    }
+    
+    ip_hdr = (iphdr*)(data + 14)
+    return  // Naked return with pointer
+}
+
+// eBPF program functions with named returns
+@xdp
+fn packet_filter(ctx: *xdp_md) -> action: xdp_action {
+    action = XDP_PASS  // Default action
+    
+    var size = ctx->data_end - ctx->data
+    if (size < 64) {
+        action = XDP_DROP
+        return  // Naked return with XDP_DROP
+    }
+    
+    return  // Naked return with XDP_PASS
+}
+
+// Userspace functions with named returns
+fn lookup_counter(ip: u32) -> counter_ptr: *u64 {
+    if (counters[ip] == none) {
+        counters[ip] = 0
+    }
+    counter_ptr = &counters[ip]
+    return  // Naked return
+}
+
+// Function pointer types with named returns
+type HashFunction = fn(*u8, u32) -> hash: u64
+type PacketProcessor = fn(*xdp_md) -> result: xdp_action
+```
+
+#### 7.3.3 Code Generation
+
+Named return values compile to clean, efficient C code with zero runtime overhead:
+
+**KernelScript:**
+```kernelscript
+fn calculate_sum(a: i32, b: i32) -> result: i32 {
+    result = a + b
+    return
+}
+```
+
+**Generated C:**
+```c
+static int calculate_sum(int a, int b) {
+    int result;      // Named return variable declared
+    result = a + b;
+    return result;   // Naked return becomes explicit
+}
+```
+
+### 7.4 Helper Functions
 
 KernelScript supports two types of functions with different scoping rules:
 
@@ -2463,7 +2576,7 @@ fn main() -> i32 {
 }
 ```
 
-### 7.4 eBPF Tail Calls
+### 7.5 eBPF Tail Calls
 
 KernelScript provides transparent eBPF tail call support that automatically converts function calls to tail calls when appropriate. Tail calls enable efficient program chaining without stack overhead and are especially useful for packet processing pipelines.
 
@@ -4149,11 +4262,15 @@ type_alias = type_annotation
 
 (* Function declarations *)
 function_declaration = [ attribute_list ] [ visibility ] [ "kernel" ] "fn" identifier "(" parameter_list ")" 
-                       [ "->" type_annotation ] "{" statement_list "}"
+                       [ return_type_spec ] "{" statement_list "}"
+
+(* Return type specification - supports both unnamed and named return values *)
+return_type_spec = "->" type_annotation                        (* Unnamed: fn() -> u64 *)
+                 | "->" identifier ":" type_annotation          (* Named: fn() -> result: u64 *)
 
 impl_declaration = [ attribute_list ] "impl" identifier "{" impl_body "}"
 impl_body = { impl_function }
-impl_function = "fn" identifier "(" parameter_list ")" [ "->" type_annotation ] "{" statement_list "}" 
+impl_function = "fn" identifier "(" parameter_list ")" [ return_type_spec ] "{" statement_list "}" 
 
 visibility = "pub" | "priv" 
 parameter_list = [ parameter { "," parameter } ] 
@@ -4252,7 +4369,7 @@ string_type = "str" "(" integer_literal ")"
 
 array_type = "[" type_annotation "" integer_literal "]" 
 pointer_type = "*" type_annotation 
-function_type = "fn" "(" [ type_annotation { "," type_annotation } ] ")" [ "->" type_annotation ] 
+function_type = "fn" "(" [ type_annotation { "," type_annotation } ] ")" [ return_type_spec ] 
 
 (* Literals *)
 literal = integer_literal | string_literal | char_literal | boolean_literal | 

examples/named_return.ks

@@ -0,0 +1,188 @@
+// XDP context struct (from BTF)
+struct xdp_md {
+  data: u64,
+  data_end: u64,
+  data_meta: u64,
+  ingress_ifindex: u32,
+  rx_queue_index: u32,
+  egress_ifindex: u32,
+}
+
+// XDP action enum (from BTF)
+enum xdp_action {
+  XDP_ABORTED = 0,
+  XDP_DROP = 1,
+  XDP_PASS = 2,
+  XDP_REDIRECT = 3,
+  XDP_TX = 4,
+}
+
+// Basic named return value - Go-style syntax
+fn add_with_named_return(a: i32, b: i32) -> sum: i32 {
+  sum = a + b      // 'sum' is automatically declared as a local variable
+  return           // Naked return - returns current value of 'sum'
+}
+
+// Named return with complex logic
+fn calculate_hash(value: u32, multiplier: u32) -> hash_value: u64 {
+  hash_value = 0   // Named return variable is available immediately
+  
+  for (i in 0..multiplier) {
+    hash_value = hash_value * 31 + value  // Modify throughout function
+  }
+  
+  return           // Naked return with computed hash_value
+}
+
+// Mixing named variables with explicit returns
+fn validate_length(len: u32, min_len: u32) -> is_valid: bool {
+  is_valid = false  // Start with default value
+  
+  if (len == 0) {
+    return        // Early naked return with is_valid = false
+  }
+  
+  if (len < min_len) {
+    return false  // Explicit return still works
+  }
+  
+  is_valid = true   // Set to true if all checks pass
+  return            // Final naked return
+}
+
+// eBPF helper functions with named returns
+@helper
+fn calculate_packet_size(ctx: *xdp_md) -> packet_size: u32 {
+  var data = ctx->data
+  var data_end = ctx->data_end
+  
+  if (data_end <= data) {
+    packet_size = 0
+    return  // Naked return with 0
+  }
+  
+  packet_size = data_end - data  // Calculate size
+  return                        // Naked return with size
+}
+
+// eBPF program functions with named returns
+@xdp
+fn advanced_packet_filter(ctx: *xdp_md) -> action: xdp_action {
+  action = XDP_PASS  // Default action
+  
+  var size = ctx->data_end - ctx->data
+  if (size < 64) {
+    action = XDP_DROP
+    return  // Naked return with XDP_DROP
+  }
+  
+  var packet_size = calculate_packet_size(ctx)
+  if (packet_size == 0) {
+    action = XDP_ABORTED
+    return  // Naked return with XDP_ABORTED
+  }
+  
+  return  // Naked return with XDP_PASS
+}
+
+// Userspace functions with named returns
+fn lookup_counter(ip: u32) -> counter_value: u64 {
+  // This would normally access a map, simplified for example
+  counter_value = ip * 1000  // Compute some value
+  
+  if (counter_value > 1000000) {
+    counter_value = 0  // Reset if too high
+  }
+  
+  return  // Naked return
+}
+
+type HashFunction = fn(*u8, u32) -> u64
+type PacketProcessor = fn(*xdp_md) -> xdp_action
+
+// Example with recursive named returns
+fn fibonacci(n: u32) -> result: u64 {
+  if (n <= 1) {
+    result = n
+    return
+  }
+  
+  var a = fibonacci(n - 1)
+  var b = fibonacci(n - 2)
+  result = a + b
+  return
+}
+
+// Named return with error handling
+fn safe_divide(numerator: i32, denominator: i32) -> quotient: i32 {
+  if (denominator == 0) {
+    quotient = 0  // Safe default
+    return
+  }
+  
+  quotient = numerator / denominator
+  return
+}
+
+// Complex example combining multiple features
+fn process_data_with_validation(value: u32, len: u32) -> status: i32 {
+  status = -1  // Error by default
+  
+  // Validate input
+  if (value == 0 || len == 0) {
+    return  // Early return with error status
+  }
+  
+  // Calculate hash for validation
+  var hash = calculate_hash(value, len)
+  if (hash == 0) {
+    status = -2  // Invalid hash
+    return
+  }
+  
+  // Process successful
+  status = 0
+  return
+}
+
+fn main() -> exit_code: i32 {
+  print("=== Named Return Values Demo ===")
+  
+  // Demonstrate basic named return
+  var sum = add_with_named_return(10, 20)
+  print("Sum with named return: %d", sum)
+  
+  // Test validation function
+  var validation_result = validate_length(25, 10)
+  if (validation_result) {
+    print("Validation result: valid")
+  } else {
+    print("Validation result: invalid")
+  }
+  
+  // Test hash calculation
+  var hash = calculate_hash(42, 5)
+  print("Hash value: %llu", hash)
+  
+  // Test counter lookup
+  var counter = lookup_counter(0x08080808)  // Google DNS
+  print("Counter for 8.8.8.8: %llu", counter)
+  
+  // Test fibonacci
+  var fib_result = fibonacci(10)
+  print("Fibonacci(10) = %llu", fib_result)
+  
+  // Test safe division
+  var quotient1 = safe_divide(10, 2)
+  var quotient2 = safe_divide(10, 0)  // Safe division by zero
+  print("10 / 2 = %d, 10 / 0 = %d", quotient1, quotient2)
+  
+  // Test complex processing
+  var status = process_data_with_validation(123, 10)
+  print("Processing status: %d", status)
+  
+  print("=== Demo Complete ===")
+  
+  exit_code = 0  // Set named return variable
+  return         // Naked return with exit_code = 0
+}