From 1e6285814e2775340fb8e377ffeda4a88f2a5c21 Mon Sep 17 00:00:00 2001
From: Heshan Padmasiri <heshanp@wso2.com>
Date: Mon, 21 Oct 2024 16:14:05 +0530
Subject: [PATCH] Add a better example

---
 examples/raw-templates/raw_templates.bal | 21 +++++++++++++++++----
 examples/raw-templates/raw_templates.md  |  5 ++++-
 examples/raw-templates/raw_templates.out |  6 ++++--
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/examples/raw-templates/raw_templates.bal b/examples/raw-templates/raw_templates.bal
index 4dd68d49a6..3a18087003 100644
--- a/examples/raw-templates/raw_templates.bal
+++ b/examples/raw-templates/raw_templates.bal
@@ -1,13 +1,26 @@
 import ballerina/io;
 
-function foo() returns boolean {
+function col3() returns boolean {
     return false;
 }
 
+type MyCSVRawTemplate object {
+    *object:RawTemplate;
+    public (string[] & readonly) strings;
+    public [int, int, boolean] insertions;
+};
+
 public function main() {
-    int x = 5;
-    error y = error("foo");
-    object:RawTemplate rawTemplate = `x is ${x}. y is ${y}. The result of calling foo is ${foo()}`;
+    int col1 = 5;
+    int col2 = 10;
+
+    // No static type validation for interpolation
+    object:RawTemplate rawTemplate = `${col1}, ${col2}, ${col3()}`;
     io:println(rawTemplate.strings);
     io:println(rawTemplate.insertions);
+
+    // validate interpolations at compile time
+    MyCSVRawTemplate myCSVRawTemplate = `${col1}, ${col2}, ${col3()}`;
+    io:println(myCSVRawTemplate.strings);
+    io:println(myCSVRawTemplate.insertions);
 }
diff --git a/examples/raw-templates/raw_templates.md b/examples/raw-templates/raw_templates.md
index 5f03d84e04..34d7ee5a49 100644
--- a/examples/raw-templates/raw_templates.md
+++ b/examples/raw-templates/raw_templates.md
@@ -1,6 +1,8 @@
 # Raw templates
 
-Raw template expressions are backtick templates without a tag (such as `string` or `xml`). This is a sequence of characters interleaved with interpolations within a pair of backticks (in the form`${expression}`). The result of evaluating such a raw template is a `RawTemplate` object that has two fields `(readonly & string[]) strings` and `(any|error)[] insertions`.  The `strings` array will have string literals in the backtick string broken at interpolations and the `insertions` array will have the resultant values of evaluating each interpolation.
+Raw template expressions are backtick templates without a tag (such as `string` or `xml`). This is a sequence of characters interleaved with interpolations within a pair of backticks (in the form`${expression}`). The result of evaluating such a raw template is a `RawTemplate` object that has two fields `(readonly & string[]) strings` and `(any|error)[] insertions`. The `strings` array will have string literals in the backtick string broken at interpolations and the `insertions` array will have the resultant values of evaluating each interpolation.
+
+If you want to control the type of values used for interpolation more precisely, you can define an object type that includes the `RawTemplate` type and give a narrower type for the `insertions` fields. Then, the compiler will statically verify that the corresponding values used for interpolation belong to the desired type.
 
 ::: code raw_templates.bal :::
 
@@ -8,3 +10,4 @@ Raw template expressions are backtick templates without a tag (such as `string`
 
 ## Related links
 - [Backtick templates](https://ballerina.io/learn/by-example/backtick-templates/)
+- [Object type inclusion](https://ballerina.io/learn/by-example/object-type-inclusion/)
diff --git a/examples/raw-templates/raw_templates.out b/examples/raw-templates/raw_templates.out
index 9b3a7f3230..e9475adff1 100644
--- a/examples/raw-templates/raw_templates.out
+++ b/examples/raw-templates/raw_templates.out
@@ -1,3 +1,5 @@
 $ bal run
-["x is ",". y is ",". result of calling foo is ",""]
-[5,error("foo"),false]
+["",", ",", ",""]
+[5,10,false]
+["",", ",", ",""]
+[5,10,false]