TeaScript

TeaScript Compatibility and Changes

Every TeaScript release package used to ship a Deprecation_and_Breaking_Changes.txt and a Known_Issues.txt. Both files only ever described the release they came with, and both were overwritten on every version bump — so the moment an issue was fixed or a deprecated API was finally removed, the record of it disappeared with the next download.

This page replaces those two files. It carries the complete history instead of a snapshot: every breaking change, every deprecation, every known issue and every experimental feature from 0.9.0 onwards.

How to use these tables

Click a column header's ▲/▼ to sort by it, and use the filter chips above each table to narrow it down. Click any row to reveal its description, workaround and migration notes, or use Expand all to open every row at once.

Some tables open pre-filtered on what is still relevant today — the open issues, the items still deprecated, the features still experimental. The selected chip is highlighted, so switch it to All (or to any other value) to see the full history. A link to a specific entry, such as DEP-15, always shows that entry even when the active filter would otherwise hide it.

About the identifiers. KI-, BC-, DEP- and EXP- numbers are stable identifiers introduced with this page. They do not match the item numbers from the old Known_Issues.txt, which were renumbered and reused inconsistently over the years; those are preserved as a Legacy # field inside each known-issue row, purely so old release notes can still be cross-referenced.

Reporting new issues. Newly discovered issues are tracked on GitHub Issues, not here. The Known Issues table below is a historical record of what was reported in the release packages, plus the handful of entries that are still open.

Known Issues

Functional issues, platform limitations and rough edges that were tracked as "known issues" across releases — as opposed to the deliberate breaking changes in the next section. Most were eventually fixed, some are still open. The table opens on the still-open ones, newest first — set Status to All for the complete history.

Status
Platform
ID Title Platforms Since Resolved Details
Legacy #
1
Description
Literals combining a decimal point and an exponent (e.g. 123.456e-10) could not be parsed. Decimal-only (123.456) or exponent-only (123456e-13) forms worked individually.
Workaround
None; avoid combining both forms.
Legacy #
2
Description
Converting a float to string (and back) lost precision beyond the 5th decimal digit, e.g. 123456e-13 displayed as 0.000000.
Workaround
Rescale before converting, to partially recover the magnitude.
Legacy #
3
Description
There was no implicit f64 ↔ i64 conversion and no cast operator.
Workaround
Use _f64toi64 / to_i64 for f64→i64, and to_f64 or +0.0 for i64→f64.
Notes
Resolved by the as cast operator. _f64toi64 itself was deprecated later — see DEP-14.
Legacy #
4
Description
(a := 4, b := 5) did not assign to a, because parentheses containing multiple expressions were reserved for future tuple construction, and tuples were not implemented yet.
Workaround
None.
Notes
Resolved when Tuples were implemented.
Legacy #
5
Description
Typing or reading Unicode input whose UTF-16 representation used a surrogate pair could echo incorrectly in the console, due to a WIN32 ReadConsoleW bug. The stored UTF-8 data itself was always correct.
Workaround
Use "Windows Terminal" together with PowerShell or Command Prompt.
Notes
The root cause turned out to be a Windows Terminal bug, fixed upstream in Windows Terminal 1.19.
Legacy #
6
Description
Parsing and evaluation errors originating inside in-string (%()) evaluation can display the wrong source snippet in the pretty-printed error output.
Workaround
Enable :debug in the interactive shell, --debug for script files, or Engine::SetDebugMode(true) in the C++ API.
Legacy #
7
Description
Comparing values where at least one operand is a non-finite float (NaN or Infinity) throws teascript::exception::runtime_error, which cannot be caught from TeaScript code.
Workaround
Use gcc ≥ 13, or clang with libc++, on Linux.
Notes
Affects gcc < 13 and clang with libstdc++. Windows (MSVC), clang with libc++ and gcc ≥ 13 perform a correct total-strong-ordering comparison instead.
Legacy #
8
Description
On Linux, clock_utc() returned UTC time without leap seconds. The underlying implementation was later found to be a misunderstanding of std::chrono::utc_clock.
Workaround
Use gcc ≥ 13 on Linux (interim workaround, pre-0.16.0).
Notes
It now returns UTC in system_clock representation on all platforms — see BC-18.
Legacy #
9
Description
The Linux implementation of line reading for the REPL lacked the history and editing niceties available on Windows.
Workaround
None.
Notes
GNU readline has been used since then.
Legacy #
10
Description
tup.0.1 parses as identifier tup, dot operator, then float literal 0.1 — so it only accesses index 0. Chained .N.M access into nested tuples needs explicit grouping: (tup.0).1.
Workaround
Use the Subscript Operator instead: tup[0].1 or tup[0][1].
Notes
Still open, but the subscript-operator workaround has been available since 0.11.0.
Legacy #
11
Description
The debug operator's output showed a dot instead of the member name for tuple elements, although the element's value printed correctly.
Workaround
None.
Legacy #
12
Description
trunc() only worked correctly within the range of i64, not across the full range of f64.
Workaround
Use _trunc from Level Util if affected (before the fix).
Legacy #
13
Description
Sending a Suspend Request from another thread to a running compiled TeaScript Binary (.tsb) in the TeaStackVM is not possible, due to the lack of the C++20 library feature std::stop_source / std::stop_token in that configuration.
Workaround
Use gcc/g++ on Linux, ideally version 13 or newer.
Legacy #
14
Description
In compiled (TeaStackVM) mode, a stop or loop statement referencing an outer loop from an inner loop is not possible when issued from inside an operand of a unary, binary or subscript operator. It evaluates fine in evaluation mode, but is discouraged there too.
Workaround
Restructure the code to avoid issuing stop or loop control from inside an operator operand.

Breaking Changes

One-time behavioral or API changes that shipped with a specific release — as opposed to the gradual deprecate-then-remove lifecycle tracked in the next section. Not every release had breaking changes — the Version chips list only those that did. The table opens sorted by release, newest first.

Version
Category
ID Version Category Title Details
Description
Copy-assigned function parameters (without def) are const by default instead of mutable. Shared-assigned (@=) parameters are unaffected.
Migration
Use an explicit def or const. Temporary opt-outs existed via the Host option --old-mutable-parameters (removed in 0.16.0, see DEP-12), Engine::ActivateDeprecatedDefaultMutableParameters() (removed in 0.14.0, see DEP-04), Parser::OverwriteDialect() (experimental, see EXP-01), or #define TEASCRIPT_DEFAULT_CONST_PARAMETERS false.
Platforms
Any
Description
eval_file moved up to Level Core. trunc, ceil, floor, sqrt, file_copy, file_copy_newer, readtextfile, writetextfile, create_dir, path_delete, file_exists and readtomlfile moved up to Level Full.
Migration
Adjust the CoreLibrary::Bootstrap() config level if these functions are required at a lower level.
Platforms
Any
Description
When compiling in C++23 mode with <print> available (for std::vprint_unicode()) and libfmt on the include path, libfmt is now preferred, because it offers more features.
Migration
#define TEASCRIPT_DISABLE_FMTLIB 1 in Print.hpp to opt out.
Platforms
Any
Description
They return a complete UTF-8 code point (length 0–4 bytes) instead of a possibly truncated byte. If the requested position lands mid-code-point, the full enclosing glyph is returned.
Migration
No migration needed in most cases.
Platforms
Any
Description
Full UTF-8 validation of the input is performed. Invalid input no longer throws; Bool(false) is returned instead.
Migration
Check the return value.
Platforms
Any
Description
Split into Util.hpp, UtilContent.hpp and UtilInternal.hpp.
Migration
Usually only Util.hpp still needs to be included directly.
Platforms
Any
Description
The member function is const now.
Migration
Update overrides and signatures if needed.
Platforms
Any
Description
It previously threw std::out_of_range.
Migration
Catch exception::parsing_error instead.
Platforms
Any
Description
It now inherits from exception::runtime_error (which carries a SourceLocation) instead of std::bad_any_cast.
Migration
Update catch clauses that relied on std::bad_any_cast.
Platforms
Any
Description
The overload previously added an I64.
Migration
Cast explicitly if an I64 is required.
Platforms
Any
Description
It must be accounted for in any custom visitor passed to ValueObject::Visit.
Migration
Handle the Tuple alternative in visitors.
Platforms
Any
Description
_exit() accepts any type of argument as the script's result value, and a script always produces a result or NaV.
Migration
Use _exit(Any) or the new _Exit statement.
Platforms
Any
Description
Arguments are exposed as a Tuple args instead of arg1, arg2, … .
Migration
The legacy form is available via the Host option --legacy-args or TEASCRIPT_ENGINE_USE_LEGACY_ARGS=1.
Platforms
Any
Description
Required to make the library "opt-out header only".
Migration
Access the parser via mBuildTools.
Platforms
Any
Description
They must be accounted for in any custom visitor passed to ValueObject::Visit.
Migration
Handle the new alternatives in visitors.
Platforms
Any
Description
A dedicated Error type and a Zig-like catch statement for error handling were added, e.g. def n := _strtonum("abc") catch 2.
Migration
The Error type is still experimental — see EXP-04.
Platforms
Any
Description
Parameters without an assign specifier are shared-assign (@=) by default. Explicit shared parameters without const or def become implicit auto, resolved to const or mutable depending on the passed argument.
Migration
Disable via the TEASCRIPT_DEFAULT_SHARED_PARAMETERS / TEASCRIPT_DEFAULT_SHARED_AUTO_PARAMETERS defines, a custom Dialect instance, or the Host option --old-deepcopy-parameters.
Platforms
Any
Description
This removes the leap-second counting behavior on Windows and on Linux with gcc ≥ 13, eliminating an unwanted offset from system time.
Migration
No migration needed. Resolves KI-08.
Platforms
Windows, Linux (gcc ≥ 13)
Description
It was accidentally const @=; a const-correctness bug had made it appear to accept const strings. It no longer accepts a const string as input.
Migration
Pass a mutable string, or copy first.
Platforms
Any
Description
Affects _strtonum / _strtonumex, to_i64 / to_f64, _strfromascii, read[text]file, read[toml\|json]file, read[toml\|json]string, write[toml\|json]string, read/writebsonbuffer and all _buf_get_x functions.
Migration
Check for the Error type instead of, or in addition to, Bool(false).
Platforms
Any
Description
Requesting a non-const reference to a const inner value now throws exception::bad_value_cast instead of silently allowing mutation.
Migration
Use GetValue<Type const>(), or the new GetConstValue() / GetMutableValue() / GetValueCopy(). The macro TEASCRIPT_DISABLE_GETVALUE_CONSTCHECK restored the old behavior temporarily and was removed in 0.17.0 — see DEP-15.
Platforms
Any
Description
Nested const elements are skipped when the functor takes a mutable ValueObject, instead of allowing const elements to be modified through it.
Migration
Use a const-taking functor to visit const elements.
Platforms
Any
Description
The member function name was misspelled before.
Migration
Update call sites to the corrected name.
Platforms
Any

Deprecated and Removed Items

Items that went — or are going — through TeaScript's deprecate-then-remove lifecycle, on the language and Core Library level as well as the C++ API level. All of them apply to every platform. The table opens on the items that are still deprecated but not yet removed — set Status to All for the complete history.

Entries marked Source scan only carry a deprecation marker in the C++ Library source but were never announced in a released Deprecation_and_Breaking_Changes.txt. They are candidates for a future release's notes rather than confirmed deprecations. DEP-18 is a step earlier still — its replacement API already exists, but the old one is not deprecated yet.

Status
Announced
ID Item Deprecated Removed Details
Description
The old two-argument bootstrap overload.
Replacement
Use Bootstrap(Context &rContext, config::eConfig const config).
Notes
¹ The 0.11.0 release package shipped no Deprecation_and_Breaking_Changes.txt, so the exact version this was deprecated in could not be confirmed from the release notes.
Description
An ambiguous, confusingly named generic eval.
Replacement
Use _eval(code_string).
Description
Superseded by more precise parsing entry points.
Replacement
Use Integer(Content&) or Num(Content&, bool).
Description
The interim opt-out for the 0.12.0 const-parameter default change.
Replacement
Change script code to use explicit def parameters.
Notes
Introduced by BC-01.
Description
The implementation behind _f64toi64.
Replacement
Use static_cast<long long> directly in C++.
Description
Renamed for clarity.
Replacement
Use ApplyBinaryOp() / ApplyUnaryOp().
Description
Renamed for clarity.
Replacement
Use InjectVars().
Description
An obsolete constructor overload.
Replacement
Use a different constructor.
Description
A direct control-flow exception for script exit.
Replacement
Use _exit() or the _Exit statement. From C++, throw teascript::control::Exit_Script directly.
Notes
Part of the exit-code rework, see BC-12.
Description
The separate exit-code concept.
Replacement
Use _exit(Any) or the _Exit statement.
Notes
Part of the exit-code rework, see BC-12.
Description
The separate exit-code concept, on the C++ API side.
Replacement
A script always produces a result or NaV now.
Notes
Part of the exit-code rework, see BC-12.
Description
The interim opt-out for the 0.12.0 const-parameter default change.
Replacement
Change scripts to use explicit def parameters, or use a custom Dialect instance.
Notes
² Flagged as "will be deprecated" in the 0.12.0 breaking-changes notes, but never listed in a "now deprecated" section of any release until its removal was announced directly in 0.16.0. Introduced by BC-01.
Description
The fixed-arity library-function wrapper templates.
Replacement
Use the generic LibraryFunction<>, which takes any arity and an optional Context first parameter.
Notes
The generic replacement was already in use internally by the experimental WebPreview module (EXP-07) in 0.15.0 — a full release before these were formally deprecated.
Description
The Core Library function converting f64 → i64.
Replacement
Use the as cast operator (recommended), or to_i64.
Notes
Still deprecated, not yet removed as of 0.17.0. Originally the workaround for KI-03.
Description
The temporary opt-out for the 0.16.0 GetValue() const-correctness fix.
Replacement
Use GetValue<Type const>(), GetConstValue(), GetMutableValue() or GetValueCopy().
Notes
Deprecated on arrival and removed one release later. Introduced by BC-21.
Description
A legacy alias for TypeI64, predating the I64 naming.
Replacement
Use TypeI64.
Notes
Marked in a source comment only; never announced in any release notes.
Description
A legacy alias for TypeF64, predating the F64 naming.
Replacement
Use TypeF64.
Notes
Marked in a source comment only; never announced in any release notes.
Description
Marked in source as "will become deprecated" because of its complicated const usage. It is not formally deprecated yet.
Replacement
Prefer GetConstValue(), GetMutableValue() or GetValueCopy() already now.
Notes
The replacement API has been available since 0.16.0, see BC-21.

Experimental Features and APIs

Features and API surfaces explicitly marked as experimental, either through an EXPERIMENTAL marker in the source code or as prose in the release notes and changelog. Experimental means the interface, the behavior or the existence of a feature may change or be removed without going through the normal deprecation cycle.

The Stabilized in column tracks graduation out of experimental status. Most entries are still experimental. The table opens on those — set Status to All to include the ones that have graduated.

Status
Area
ID Feature / API Area Since Stabilized in Details
Description
Overwriting the default Dialect creates an unofficial or legacy TeaScript language dialect — for example restoring the old mutable-parameter defaults at a low level. The interface "may change often or be removed entirely."
Notes
A low-level escape hatch. Prefer the standard dialect unless legacy or custom behavior is specifically needed.
Description
Engine/EngineBase::RegisterUserCallback(), CallbackFunc and UserCallbackFunc register arbitrary C++ callbacks that become callable as normal TeaScript functions. The interface, its members and the general mechanics "may change."
Notes
The longest-lived experimental feature, spanning roughly eight releases, and already widely used in the demos despite the status.
Description
A dedicated Engine variant for coroutine-style script execution with suspend and resume. The class as well as its interface and layout are "considered EXPERIMENTAL."
Description
A dedicated Error type (code plus message) with catch and try statement sugar for Zig-like error handling. "All Error related classes and functions are considered EXPERIMENTAL."
Notes
catch arrived in 0.16.0, try was added in 0.17.0. Also a breaking change, see BC-16.
Description
Parameters without an assign specifier default to shared-assign, and explicit shared parameters without const or def become implicit auto. "Experimental but activated by default."
Notes
Also a breaking change, see BC-17.
Description
Tuple ↔ BSON buffer conversion, available only when the nlohmann::json adapter and TEASCRIPT_BSONSUPPORT are enabled at build time.
Notes
Gated behind build configuration.
Description
web_get, web_post, web_server_setup, web_server_accept, web_server_reply, web_server_build_reply, web_set_payload, web_add_header and web_build_request. The first module built on the experimental IModule interface; it must be enabled manually and, once enabled, is always loaded into the Context — there is no on-demand loading from scripts yet. Versioned "Preview 0."
Description
Reflects C++ structs into TeaScript Tuples and back, built on the third-party reflectcpp library.
Notes
An optional extension, not part of the Core Library.
Description
Exposes the TeaStackVM's working-variable stack and call stack for debugging. Using them while the machine is running is a data race, and therefore undefined behavior.
Notes
Introduced together with the TeaStackVM. Debug use only, never concurrently with a running machine.
Description
Builds a string representation of a chain of nested dot operators, for introspection and debugging.
Description
Introspection helpers for partial, interactive line-by-line parsing state.
Notes
Distinct from the older Parser::Get[Final]PartialParsedASTNodes() (EXP-15), which graduated in 0.14.0.
Description
A compile-time and eval-time concept for checking the constness of a variable.
Notes
Stabilized alongside EXP-13 to EXP-15 in the same commit batch.
Description
An AST node type representing a parsed file part or fragment.
Notes
³ Best effort: located via git log -S"class ASTNode_FilePart" rather than named in changelog.txt. Introduced by the same commit that added EXP-15's original interface.
Description
A mechanism for passing arbitrary opaque C++ data through TeaScript values and calls without conversion.
Notes
Still in active use today — the WebPreview module (EXP-07) relies on it — it is simply no longer flagged experimental.
Description
The original interface for partial, line-by-line parsing introspection.
Notes
Superseded by the newer, still experimental ParsingState partial-parsing API (EXP-11).

Cross-references worth noting

Per-release detail lives in the release articles, and older packages in the Release Archive.