Release of TeaScript 0.15.0 ☕

TeaScript 0.15.0 was published on the 1st September in 2024 and can be downloaded for free:

New Patch Release TeaScript C++ Library 0.15.1 (03. November 2024) – This patch release fixes the header only compile mode which was broken for Engine/CoroutineScriptEngine.

All details, features and changes for this new release are following in the blog post below.

Infos and Links

The download page with more infos, links and basic instructions:
☛☛☛ Download Page. ☚☚☚

Browse the source code of the TeaScript C++ Library on Github.

Are you new to TeaScript?
Then you may read here first: Overview and Highlights of TeaScript.

Watch demos, tutorials and more on the YouTube Channel.

What was new?

The previous release blog posts are nice for a tutorial like introduction of the new features and for getting an overview. If you missed some, here is the collection.

Release of TeaScript 0.14.0 🖥– TeaStackVM, Compiler, Dis-/Assembler, Suspend+Continue, Yield, improved debugging.
Release of TeaScript 0.13.0 🗍 – Buffer, U8, U64, bit ops, UTF-8 Iterator, hex integrals, MPL-2.0.
Release of TeaScript 0.12.0 🌈 – Colored Output, Format String, Forall Loop, Sequences, interactive debugging.
Release of TeaScript 0.11.0 🎂 – TOML Support, Subscript Operator, Raw String Literals.
Release of TeaScript 0.10.0 🌞 – Tuples/Named Tuples, Passthrough Type, CoreLib config.

What is new?

The TeaScript 0.15.0 release comes with the following new main features:

• Web module as a preview for http client / server functionality with enhanced build-in JSON support.
  ☛ Watch the web feature demo on YouTube.
• Full JSON support for read and write operations (String/File ⟷ (Named) Tuple).
• Provided C++ JSON adapter for nlohmann::json, RapidJSON, Boost.Json and PicoJson.
• Added missing write support for TOML (now TOML is complete as well).
• Import/export of C++ JSON / TOML objects from/to ValueObject of TeaScript (as a Named Tuple) (TeaScript C++ Library only)

Web Client / Server Preview

The pre-compiled Windows and Linux packages of the TeaScript Host Application have this feature enabled by default (download links at the top of the page). For the TeaScript C++ Library it is an opt-in feature and must be enabled first (see below).

The web preview module adds functionality for issuing http requests (client) or receive and reply to them (server). Internally TeaScript is utilizing the power of the awesome Boost.Beast and Boost.Asio C++ libraries. (Well, for this preview maybe only 1% of the available power is used already… 😉 )

This feature comes along with automatic enhanced JSON support for payloads with Content-Type “application/json”.

You can try it easily by your self with the provided web_client.tea and web_server.tea example script files.

Here is another simple example (error handling omitted):

// issue a http GET request (here to a test page for JSON as payload)
def res := web_get( "headers.jsontest.com" )

// access http status code and its reason (may print "200: OK")
println( res.code % ": " % res.reason )

// print all header entries of the reply
tuple_print( res.header, "header", 1 )

// the above may print:
// [...]
// header.Date: "Sat, 31 Aug 2024 13:34:26 GMT"
// header.Server: "Google Frontend"
// header.Content-Length: "236"


// print the payload of the reply as String
println( res.payload ) // this will print a json formatted string


// if the payload was sent as Content-Type "application/json"
// TeaScript automatically builds a Tuple out of it.

if( is_defined res.json ) { // json Tuple is present
    // we can access all elements/objects directly.
    // In this example the server just echoed the header of
    // the request back as a json formatted string.
    
    // print the Host value
    println( res.json.Host )
    // print the User-Agent
    println( res.json["User-Agent"] )
    // dot access possible as well!
    println( res.json."User-Agent" )
}

Issuing a http POST is easy as well:

// easily create the json payload
def json_payload := json_make_object( ("name", "John"), ("age", 31) )

// issue the http POST with our json payload (plain String also works as paramter)
def reply := web_post( "postman-echo.com", json_payload, "/post" )

// now we can access the result/reply message as before.

// lets print the whole json object from the reply...
tuple_print( reply.json, "json", 10 )

// may print:
// [...]
// json.args: <Tuple>
// json.data: <Tuple>
// json.data.age: 31
// json.data.name: "John"
// [...]
// json.headers.connection: "close"
// json.headers.content-length: "24"
// json.headers.content-type: "application/json"
// json.headers.host: "postman-echo.com"
// json.headers.user-agent: "TeaScript/0.15.0"
// [...]

For a web server example, please, have a look at web_server.tea.

Howto enable the web preview for the C++ Library

The web preview module is not header only and it has a dependency to Boost.Beast / Boost.Asio. Because of that, the following steps have to be done in order to use it in the TeaScript C++ Library:

• Add WebPreview.cpp from “TeaScriptRoot”/modules/source/ to your project.
• Add the include directory “TeaScriptRoot”/modules/include/ to your project.
• Add the include for the Boost Library to your project (You don’t need to compile Boost, TeaScript is using only header only libs from there)
• (optionally): If you want the default Engine of TeaScript is always loading the Web Preview module, define the preprocessor macro TEASCRIPT_ENGINE_USE_WEB_PREVIEW to 1 (or change its default value in Engine.hpp to 1). Otherwise you must manually load the web preview module into the desired Context instance.

You can also watch a short How-To on YouTube: https://youtu.be/SeRO21U1vMk

JSON Support

TeaScript now has build-in JSON support. You can convert a JSON formatted String into a Tuple object and vice versa. The Json can be written to/read from a file as well. Also, TeaScript offers a bunch of utility functions for access and manipulating JSON compatible Tuple objects.

The Json support is enabled by default and is served by the tiny PicoJson library, which is shipped with the TeaScript source.

If you use or want use the TeaScript C++ Library, it is likely that your C++ project is using a different Json library. For that case, you can change the used Json library of TeaScript. This release comes with available Json adapters for nlohmann::json, RapidJSON and Boost.Json.

While the internally used Json Adapter of TeaScript is exactly one and must be chosen at compile time, all available Json adapters can be used at runtime for manually import/export Json objects of the concrete adapter. This is for the unlucky case (but I have seen many already!) that not one Json library is in use but many.

You might have a look at the corelibrary_test05.tea code to see how the JSON support could be used (and how its functionality is tested).

Here is another simple example:

// json formatted array string to Tuple
def json := readjsonstring(  "[1, 2, 3, 4]" )

// use the utility functions for json arrays
println( json_is_array( json ) )     // true
println( json_array_empty( json ) )  // false
println( json_array_size( json ) )   // 4

// access
println( json[1] ) // 2

// manipulate
json_array_append( json, 5 ) // value 5 appended

json_array_remove( json, 1 ) // index 1 removed

// to json formatted string
def str := writejsonstring( json )

println( str )  // "[1,3,4,5]"


// use a more complex json object

const object_str := """"
{
    "name": "John",
    "age": 31,
    "additional": [1, true, "Hello"]
}
""""

def json_object := readjsonstring( object_str )

println( json_object.name ) // "John"

println( json_is_array( json_object.additional ) ) // true

println( "%(json_object.additional.2) World!" )    // "Hello World!"


// create json compatible tuples:
def new_json := json_make_object( ("foo", "bar"), ("myarray", json_make_array(1, "test" ) ) )

// build a json formatted string
def new_str := writejsonstring( new_json ) // "{"foo":"bar","myarray":[1,"test"]}"

There are convenience functions for read/write Json formatted Strings from/to files via readjsonfile() and writejsonfile() respectively.
Have a look in the Core Library Documentation for all json utility functions or use :search json from within the REPL of the TeaScript Host Application.

Technical noteworthiness

TeaScript does not have distinct arrays and dictionaries but (only) Tuples which can act as both of them and much more.

If a Tuple shall be used as a Json value and it contains key value pairs then it is considered to be a json object. But if it contains only values, then it is considered to be a json array.

But if a Tuple object is empty, it is not possible to distinguish between an empty json array and an empty json object. For this case TeaScript inserts a marker inside a Tuple which comes from a json import or should be used for a json export and was considered to be an json array.

Because of that it is really important to use the provided utility functions for json arrays. They will take care of the specialties under the hood.

Howto change the Json Adapter

The Json adapters are not header only and have dependencies to other Json C++ libraries. Because of that, the following steps have to be done:

• Add the include directory for the desired Json library to your project, e.g., /nlohmann_3.11.3/single_include/
• Add the include directory for TeaScript extensions to your project: “TeaScriptRoot”/extensions/include/
• Add the corresponding adapter to your project, e.g., “TeaScriptRoot”/extensions/source/JsonAdapterNlohmann.cpp
• Define the preprocessor macro TEASCRIPT_JSON_FLAVOR to TEASCRIPT_JSON_NLOHMANN. Either via project settings or inside JsonSupport.hpp.

Thats it. After this changes, TeaScript will use nlohmann::json for the Json support.

Complete TOML support

Before, TeaScript was able to read TOML files/strings already. Now it can also write them with writetomlstring() and writetomlfile().

The TOML feature is optional. In order to activate it, you must download the tomlplusplus library and add the include directory to your project. Thats all, TeaScript will automatically detect it.

The same kind of utility functions were added to the TOML support as it was for JSON. Have a look in the Core Library Documentation for all toml utility functions or use :search toml from within the REPL of the TeaScript Host Application.

Please note, the same noteworthiness as for json applies to toml. So, in order to support possibly empty arrays, you must use the corresponding utility functions, like toml_is_array, toml_array_empty, toml_array_size, toml_array_append, toml_array_remove and so on.

Import/Export of C++ Json objects

Within C++ you can import and export C++ Json objects of all available adapters/json libraries.

For the time being you need a valid instance of the corresponding TeaScript Context. If you use the Engine class, the easiest way is to derive from it and use the Context member from there.

The demo app uses this feature in the web preview code. You can view the source of the function here: teascript_demo.cpp webpreview_code().

Here is some little example code using nlohmann::json:

// somewhere in the code where a TeaScript context is available...

// just make some json object
nlohmann::json  value;
value["name"] = "John";
value["myarray"] = { 4, 5, 6 };

// import it
ValueObject  val = teascript::JsonAdapterNlohmann::ToValueObject( context, value );

// add it as variable 'json'. ('context' and the context of the engine should be the same.)
engine.AddSharedValueObject( "json", val );


// export is even more simple

// assuming there is a 'json2' variable which is a json compatible Tuple...
auto const valobj = engine.GetVar( "json2" );

// and export it to nlohmann::json.
nlohmann::json  value2;
teascript::JsonAdapterNlohmann::FromValueObject( valobj, value2 );

Shortcut for creating dictionaries

Tuples with named elements are used as the map/dictionary container in TeaScript. Before you had to use the Uniform Definition Syntax for create them or use the _tuple_named_append/insert functions.

Now, a third way is available, which enables creating dictionaries easily with one call: _tuple_named_create()

This functions excepts an arbitrary amount of parameters. Each parameter must be a tuple with 2 elements. The first element must be always of type String. This will be the key of the entry. The second element can be of any type and will be the value of the entry.

Here is some example code showing the 3 available possibilities:

// old way, use _tuple_named_append
def dic1 := _tuple_create()              // empty tuple to start with.
_tuple_named_append( dic1, "elem1", 1 )  // added "elem1" with value 1
_tuple_named_append( dic1, "elem2", "foo" )  // added "elem2" with value "foo"


// old way (but still great!), the Uniform Definition Syntax.
def dic1.elem3 := true      // added "elem3" with value true
def dic1.baz   := _buf(10)  // added "baz" with Buffer of size 10


// Now we do the same with the new _tuple_named_create()

def dic2 := _tuple_named_create( ("elem1", 1), ("elem2", "foo"), ("elem3", true), ("baz", _buf(10) ) )


println( dic1 == dic2 )   // prints: true