Add panic BBE

examples/index.json

@@ -1376,6 +1376,13 @@
         "verifyOutput": true,
         "isLearnByExample": true
       },
+      {
+          "name": "Trap expression",
+          "url": "trap-expression",
+          "verifyBuild": true,
+          "verifyOutput": true,
+          "isLearnByExample": true
+      },
       {
         "name": "Type intersection for error types",
         "url": "error-type-intersection",

examples/trap-expression/trap_expression.bal

@@ -0,0 +1,24 @@
+import ballerina/io;
+
+function hereBeDragons() returns int {
+    // Trigger a panic deep within the call stack. 
+    alwaysPanic();
+}
+
+// Return type `never` indicate that this function will never return normally. That is it will always panic
+function alwaysPanic() returns never {
+    panic error("deep down in the code");
+}
+
+public function main() {
+    // Division by 0 trigger a panic  
+    int|error result = trap 1 / 0;
+    if result is error {
+        io:println("Error: ", result);
+    }
+    // This will tigger a panic deep within the call stack and we'll trap it here
+    int|error result2 = trap hereBeDragons();
+    if result2 is error {
+        io:println("Error: ", result2);
+    }
+}

examples/trap-expression/trap_expression.md

@@ -0,0 +1,9 @@
+# Trap expression
+
+If you have an expression such as a function call that can potentially trigger a `panic` you can use a `trap` expression to prevent further unwinding of the stack. Then if the evaluation of the expression trigger a panic you will get the `error` associated with the panic. Otherwise you will get the result of the expression.
+
+::: code trap_expression.bal :::
+
+::: out trap_expression.out :::
+
++ [Panics](https://ballerina.io/learn/by-example/panics/)

examples/trap-expression/trap_expression.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates how the trap expression is used in Ballerina to handle panics
+keywords:  ballerina, ballerina by example, bbe, error, panic, trap

examples/trap-expression/trap_expression.out

@@ -0,0 +1,4 @@
+$ bal run trap_expression.bal
+Error: error("{ballerina}DivisionByZero",message=" / by zero")
+Error: error("deep down in the code")
+