Merge pull request #5749 from heshanpadmasiri/feat/raw-template

Update raw-template BBE to remove external dependency

examples/raw-templates/raw_templates.bal

@@ -1,31 +1,28 @@
 import ballerina/io;
-import ballerinax/java.jdbc;
-import ballerina/sql;
 
-jdbc:Client dbClient = check new (url = "jdbc:h2:file:./master/orderdb",
-                           user = "test", password = "test");
+function col3() returns boolean {
+    return false;
+}
 
-public function main() returns error? {
-    // Uses a raw template to create the `Orders` table.
-    _ = check dbClient->execute(`CREATE TABLE IF NOT EXISTS Orders
-                                (orderId INTEGER NOT NULL, customerId INTEGER, noOfItems INTEGER,
-                                PRIMARY KEY (orderId))`);
-    // Uses a raw template to insert values to the `Orders` table.
-    _ = check dbClient->execute(`INSERT INTO Orders (orderId, customerId, noOfItems)
-                                 VALUES (1, 1, 20)`);
-    _ = check dbClient->execute(`INSERT INTO Orders (orderId, customerId, noOfItems)
-                                 VALUES (2, 1, 15)`);
+type MyCSVRawTemplate object {
+    *object:RawTemplate;
+    public (string[] & readonly) strings;
+    public [int, int, boolean] insertions;
+};
 
-    stream<record {| anydata...; |}, sql:Error?> strm = getOrders(1);
-    record {|record {} value;|}|sql:Error? v = strm.next();
-    while (v is record {|record {} value;|}) {
-        record {} value = v.value;
-        io:println(value);
-        v = strm.next();
-    }
-}
+public function main() {
+    int col1 = 5;
+    int col2 = 10;
+
+    // Any value is allowed as an interpolation when defining a value of the `object:RawTemplate` type 
+    // since it has `(any|error)[]` as the `insertions` type.
+    object:RawTemplate rawTemplate = `${col1}, fixed_string1,  ${col2}, ${col3()}, fixed_string3`;
+    io:println(rawTemplate.strings);
+    io:println(rawTemplate.insertions);
 
-function getOrders(int customerId) returns stream<record {| anydata...; |}, sql:Error?> {
-    // In this raw template, the `customerId` variable is interpolated in the literal.
-    return dbClient->query(`SELECT * FROM orders WHERE customerId = ${customerId}`);
+    // With the custom `MyCSVRawTemplate ` raw template type, the compiler 
+    // expects two integers followed by a boolean value as interpolations.
+    MyCSVRawTemplate myCSVRawTemplate = `fixed_string4, ${col1}, ${col2}, fixed_string_5, ${col3()}`;
+    io:println(myCSVRawTemplate.strings);
+    io:println(myCSVRawTemplate.insertions);
 }

examples/raw-templates/raw_templates.md

@@ -1,22 +1,16 @@
 # Raw templates
 
-A raw template is a backtick template without a tag. Exposes result of phase 1 without further processing. Raw template is evaluated by evaluating each expression and creating an object containing.
+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 an `object: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.
 
-- an `array` of the `strings` separated by insertions
-- an `array` of the results of expression evaluation and an `array` of `strings` separating
+If you want to control the type of the strings or the interpolations more precisely, you can define an object type that includes the `object:RawTemplate` type and override the relevant field(s) with narrower types. Then, the compiler will statically validate the values against the expected type(s).
 
->**Important use case:** SQL parameters.
-
->**Note:** The relevant database driver JAR should be defined in the `Ballerina.toml` file as a dependency. This sample is based on an H2 database and the H2 database driver JAR need to be added to `Ballerina.toml` file. This sample is written using H2 2.1.210 and it is recommended to use H2 JAR with versions higher than 2.1.210.
-
-For a sample configuration and more information on the underlying module, see the [`jdbc` module](https://lib.ballerina.io/ballerinax/java.jdbc/latest/).
+An important use case of custom raw templates is SQL parameterized queries.
 
 ::: code raw_templates.bal :::
 
-Add the relevant database driver JAR details to the `Ballerina.toml` file.
-
-::: code Ballerina.toml :::
-
-Build and run the project using the `bal run` command.
+::: out raw_templates.out :::
 
-::: out raw_templates.out :::
+## Related links
+- [Backtick templates](https://ballerina.io/learn/by-example/backtick-templates/)
+- [Object type inclusion](https://ballerina.io/learn/by-example/object-type-inclusion/)
+- [Database Access - Simple query](https://ballerina.io/learn/by-example/mysql-query-operation/)

examples/raw-templates/raw_templates.out

@@ -1,3 +1,5 @@
 $ bal run
-{"ORDERID":1,"CUSTOMERID":1,"NOOFITEMS":20}
-{"ORDERID":2,"CUSTOMERID":1,"NOOFITEMS":15}
+["",", fixed_string1,  ",", ",", fixed_string3"]
+[5,10,false]
+["fixed_string4, ",", ",", fixed_string_5, ",""]
+[5,10,false]