Compare commits

...
5 Commits
35 changed files with 4355 additions and 123 deletions

No files matched your search

+1
View File
@@ -13,6 +13,7 @@
- Prefer defining Lyng entities (enums/classes/type shapes) in `.lyng` files; only define them in Kotlin when there is Kotlin/platform-specific implementation detail that cannot be expressed in Lyng.
- Avoid hardcoding Lyng API documentation in Kotlin registrars when it can be declared in `.lyng`; Kotlin-side docs should be fallback/bridge only.
- For mixed pluggable modules (Lyng + Kotlin), embed module `.lyng` sources as generated Kotlin string literals, evaluate them into module scope during registration, then attach Kotlin implementations/bindings.
- When a change adds or changes Lyng-visible runtime/module behavior, update the corresponding `.lyng` declaration in the same change, including declaration-level docs/comments for new API surface.
## Kotlin/Wasm generation guardrails
- Avoid creating suspend lambdas for compiler runtime statements. Prefer explicit `object : Statement()` with `override suspend fun execute(...)`.
+167 -23
View File
@@ -1,9 +1,32 @@
# Json support
Since 1.0.5 we start adding JSON support. Versions 1,0,6* support serialization of the basic types, including lists and
maps, and simple classes. Multiple inheritance may produce incorrect results, it is work in progress.
Lyng now has two distinct JSON-facing layers:
## Serialization in Lyng
- plain JSON projection:
- `Obj.toJson()`
- `Obj.toJsonString()`
- canonical JSON round-trip format:
- `Json.encode(value)`
- `Json.decode(text)`
- typed canonical JSON round-trip format:
- `Json.encodeAs(Type, value)`
- `Json.decodeAs(Type, text)`
Use the first when you need ordinary JSON for interop.
Use the second when you need Lyng value round-trip semantics through JSON text with no schema.
Use the third when both sides already know the Lyng type and you want the same round-trip semantics with fewer type
tags in the JSON.
This distinction is intentional:
- plain JSON projection is optimized for compatibility with ordinary JSON tooling
- canonical `Json.encode()` is optimized for semantic fidelity to Lyng and Lynon and stays self-describing
- typed canonical `Json.encodeAs()` is optimized for the same fidelity when the schema is provided externally
- these goals conflict for values such as sets, exceptions, singleton objects, buffers, and maps with non-string keys
## Plain JSON projection in Lyng
// in lyng
assertEquals("{\"a\":1}", {a: 1}.toJsonString())
@@ -20,7 +43,8 @@ Simple classes serialization is supported:
assertEquals( "{\"foo\":1,\"bar\":2}", Point(1,2).toJsonString() )
>>> void
Note that mutable members are serialized by default. You can exclude any member (including constructor parameters) from JSON serialization using the `@Transient` attribute:
Note that mutable members are serialized by default. You can exclude any member (including constructor parameters) from
JSON serialization using the `@Transient` attribute:
import lyng.serialization
@@ -31,7 +55,7 @@ Note that mutable members are serialized by default. You can exclude any member
assertEquals( "{\"bar\":2,\"visible\":100}", Point2(1,2).toJsonString() )
>>> void
Note that if you override json serialization:
Note that if you override plain JSON serialization:
import lyng.serialization
@@ -46,8 +70,8 @@ Note that if you override json serialization:
assertEquals( "{\"custom\":true}", Point2(1,2).toJsonString() )
>>> void
Custom serialization of user classes is possible by overriding `toJsonObject` method. It must return an object which is
serializable to Json. Most often it is a map, but any object is accepted, that makes it very flexible:
Custom serialization of user classes is possible by overriding `toJsonObject`. It must return an object which is
serializable to JSON. Most often it is a map, but any object is accepted:
import lyng.serialization
@@ -70,12 +94,87 @@ serializable to Json. Most often it is a map, but any object is accepted, that m
Please note that `toJsonString` should be used to get serialized string representation of the object. Don't call
`toJsonObject` directly, it is not intended to be used outside the serialization library.
## Canonical Json round-trip format
`Json.encode()` and `Json.decode()` are now the JSON equivalents of `Lynon.encode()` and `Lynon.decode()`.
They still use JSON text, but they add Lyng-specific type tags where plain JSON would otherwise lose information.
When a map already fits ordinary JSON object rules, canonical JSON keeps that traditional object shape. In particular,
maps with string keys are still serialized as JSON objects, not as tagged entry lists.
Example:
```lyng
import lyng.serialization
import lyng.time
enum Color { Red, Green }
class Point(x,y) { var z = 42 }
val p = Point(1,2)
p.z = 99
val value = List(
p,
Map([1, "one"], ["two", 2]),
Set(1,2,3),
"hello".encodeUtf8(),
Date(2026,4,15),
Color.Green
)
assertEquals(value, Json.decode(Json.encode(value)))
```
The canonical `Json` format is intended for Lyng-to-Lyng transfer through JSON text.
The plain `toJson()` projection is intended for ordinary JSON interop.
Canonical `Json.encode()` should be read as the JSON analogue of `Lynon.encode()`: when Lynon already preserves a
Lyng distinction, canonical JSON tries to preserve it too, using tags only where ordinary JSON is insufficient.
## Typed canonical Json round-trip format
`Json.encodeAs(Type, value)` and `Json.decodeAs(Type, text)` use the same canonical rules, but with a declared target
type available during the whole traversal.
This changes one thing only: type tags may be omitted when the declared type is already exact enough to restore the
value unambiguously.
The same map rule still applies here: `Map<String, T>` stays a normal JSON object, while non-string-key maps fall back
to canonical entry encoding.
Example:
```lyng
import lyng.serialization
closed class Point(x: Int, y: Int)
closed class Segment(a: Point, b: Point)
val value = Segment(Point(0, 1), Point(2, 3))
val encoded = Json.encodeAs(Segment, value)
assertEquals("{\"a\":{\"x\":0,\"y\":1},\"b\":{\"x\":2,\"y\":3}}", encoded)
assertEquals(value, Json.decodeAs(Segment, encoded))
```
Subtype information is still preserved when the declared type is wider than the runtime one. For example, if a field is
declared as `Base` but contains `Derived`, canonical subtype tags remain in that field.
This is why the APIs are split:
- `toJson()` stays plain and interop-friendly
- `Json.encode()` stays fully self-describing and safe to decode without a schema
- `Json.encodeAs()` uses the supplied schema to reduce noise, but only where that schema is sufficient
## Kotlin side interfaces
The "Batteries included" principle is also applied to serialization.
- `Obj.toJson()` provides Kotlin `JsonElement`
- `Obj.toJsonString()` provides Json string representation
- `Obj.toJson()` provides Kotlin `JsonElement` for the plain JSON projection
- `Obj.toJsonString()` provides plain JSON string representation
- `Obj.decodeSerializableWith()` and `Obj.decodeSerializable()` allows to decode Lyng classes as Kotlin objects using
`kotlinx.serialization`:
@@ -104,10 +203,9 @@ suspend inline fun <reified T> Obj.decodeSerializable(scope: Scope = Scope()) =
decodeSerializableWith<T>(serializer<T>(), scope)
```
Note that lyng-2-kotlin deserialization with `kotlinx.serialization` uses JsonElement as information carrier without
formatting and parsing actual Json strings. This is why we use `Json.decodeFromJsonElement` instead of
`Json.decodeFromString`. Such an approach gives satisfactory performance without writing and supporting custom
`kotlinx.serialization` codecs.
Note that Lyng-to-Kotlin deserialization with `kotlinx.serialization` is based on the plain JSON projection,
not the canonical `Json.encode()` format. It uses `JsonElement` as the information carrier without formatting and
parsing actual JSON strings. This is why we use `Json.decodeFromJsonElement` instead of `Json.decodeFromString`.
### Pitfall: JSON objects and Map<String, Any?>
@@ -134,7 +232,8 @@ fun deserializeMapWithJsonTest() = runTest {
But what if your map has objects of different types? The approach of using polymorphism is partially applicable, but what to do with `{ one: 1, two: "two" }`?
The answer is pretty simple: use `JsonObject` in your deserializable object. This class is capable of holding any JSON types and structures and is sort of a silver bullet for such cases:
The answer is simple: use `JsonObject` in your deserializable object. This class is capable of holding any JSON types
and structures:
~~~kotlin
@Serializable
@@ -154,26 +253,71 @@ fun deserializeAnyMapWithJsonTest() = runTest {
~~~
# List of supported types
## Supported shapes
### Plain JSON projection
| Lyng type | JSON type | notes |
|-----------|-----------|-------------|
| `Int` | number | |
| `Real` | number | |
| `Real` | number | finite values only as plain numbers |
| `String` | string | |
| `Bool` | boolean | |
| `null` | null | |
| `Instant` | string | ISO8601 (1) |
| `List` | array | (2) |
| `Map` | object | (2) |
| `Map` | object | string keys only |
| simple class instance | object | constructor fields + mutable vars |
| enum | string | entry name |
### Canonical `Json.encode`
This format can also round-trip:
- maps with non-string keys
- sets
- immutable collections
- buffers and bit buffers
- class instances
- singleton objects
- enums
- exceptions
- `Date`, `Instant`, `DateTime`
- non-finite reals
- `void`
### Typed canonical `Json.encodeAs`
This format round-trips the same value space as canonical `Json.encode`, but it can emit simpler JSON for:
- closed classes and other exactly-known class fields
- enums when the enum type is known
- typed collections whose element types are known
- nested object graphs where declared field types are precise
It still falls back to canonical tagged encoding when exact runtime type information would otherwise be lost.
It does so by adding Lyng-specific type tags only when necessary.
## Kotlin-side extension point for more formats
Additional formats can be exported from Kotlin modules by subclassing `ObjSerializationFormatClass` and registering the
format in module scope with `bindSerializationFormat(...)`.
```kotlin
module.bindSerializationFormat(
object : ObjSerializationFormatClass("MyFormat") {
override suspend fun encodeValue(scope: Scope, value: Obj): Obj = ...
override suspend fun decodeValue(scope: Scope, encoded: Obj): Obj = ...
}
)
```
This makes `MyFormat.encode(...)` and `MyFormat.decode(...)` available from Lyng after importing the module.
(1)
: ISO8601 flavor 1970-05-06T06:00:00.000Z in used; number of fractional digits depends on the truncation
on [Instant](time.md), see `Instant.truncateTo...` functions.
: ISO8601 flavor `1970-05-06T06:00:00.000Z` is used; number of fractional digits depends on truncation on
`Instant`, see `Instant.truncateTo...` functions.
(2)
: List may contain any objects serializable to Json.
(3)
: Map keys must be strings, map values may be any objects serializable to Json.
: Lists may contain any values serializable by the selected JSON layer.
+178 -14
View File
@@ -1,4 +1,4 @@
### lyng.io.db — SQL database access for Lyng scripts
# lyng.io.db — SQL database access for Lyng scripts
This module provides the portable SQL database contract for Lyng. The current shipped providers are SQLite via `lyng.io.db.sqlite` and a JVM-only JDBC bridge via `lyng.io.db.jdbc`.
@@ -6,7 +6,7 @@ This module provides the portable SQL database contract for Lyng. The current sh
---
#### Install the module into a Lyng session
## Install the module into a Lyng session
For SQLite-backed database access, install both the generic DB module and the SQLite provider:
@@ -54,7 +54,7 @@ suspend fun bootstrapJdbc() {
---
#### Using from Lyng scripts
## Using from Lyng scripts
Typed SQLite open helper:
@@ -188,34 +188,98 @@ assertThrows(RollbackException) {
---
#### Portable API
## Runnable serialization sample
##### `Database`
A complete runnable example is in [examples/sqlite_serialization.lyng](/home/sergeych/dev/lyng/examples/sqlite_serialization.lyng).
It uses:
- `@DbJson`
- `@DbLynon`
- `@DbExcept`
- `@cols(...)`, `@vals(...)`, `@set(...)`
- `decodeAs<T>()`
The current direct read form that works under `jlyng` is:
```lyng
tx.select("select * from item where id = ?", 1).decodeAs<Item>().first
```
If we want a shorter form such as:
```lyng
tx.selectAllAs<Item>("item where id = ?", 1).first
```
it should be added as a built-in `SqlTransaction` API. A pure Lyng generic wrapper around `decodeAs<T>()` does not currently preserve `T` reliably enough under `jlyng`.
---
## Portable API
### `Database`
- `transaction(block)` — opens a transaction, commits on normal exit, rolls back on uncaught failure.
##### `SqlTransaction`
### `SqlTransaction`
- `select(clause, params...)` — execute a statement whose primary result is a row set.
- `execute(clause, params...)` — execute a side-effect statement and return `ExecutionResult`.
- `transaction(block)` — nested transaction with real savepoint semantics.
##### `ResultSet`
`select(...)` and `execute(...)` also support SQL object-expansion macros for declaration-driven writes:
- `@cols(?1)` — expand object argument `?1` to a comma-separated column list
- `@vals(?1)` — expand object argument `?1` to matching placeholders and bind values
- `@set(?1)` — expand object argument `?1` to `column = ?` pairs and bind values
Each macro also supports an optional clause-local exclusion list:
```lyng
tx.execute("update item set @set(?1 except: \"id\", \"createdAt\") where id = ?2", item, item.id)
```
Example:
```lyng
tx.execute("insert into item(@cols(?1)) values(@vals(?1))", item)
tx.execute("update item set @set(?1) where id = ?2", item, item.id)
```
When a clause uses any of these macros, non-expanded scalar parameters in the same SQL string must use explicit indexed placeholders such as `?2`, `?3`, and so on.
### `ResultSet`
- `columns` — positional `SqlColumn` metadata, available before iteration.
- `size()` — result row count.
- `isEmpty()` — fast emptiness check where possible.
- `iterator()` — normal row iteration while the transaction is active.
- `toList()` — materialize detached `SqlRow` snapshots that may be used after the transaction ends.
- `decodeAs<T>()` — transaction-scoped iterable view that decodes each row into `T`.
##### `SqlRow`
### `SqlRow`
- `row[index]` — zero-based positional access.
- `row["columnName"]` — case-insensitive lookup by output column label.
- `row.decodeAs<T>()` — decode one row into a typed Lyng value.
Name-based access fails with `SqlUsageException` if the name is missing or ambiguous.
##### `ExecutionResult`
### `DbFieldAdapter`
Custom DB field projection hook used by `@DbDecodeWith(...)` and `@DbSerializeWith(...)`.
- `decode(rawValue, column, row, targetType)` — adapt one raw DB field value to a Lyng value for the requested target type.
- `encode(value, targetType)` — adapt one Lyng value to a direct DB-bindable value for SQL object expansion.
Use `@DbDecodeWith(adapter)` on class constructor parameters and class-body fields/properties that participate in `decodeAs<T>()`.
Use `@DbSerializeWith(adapter)` on constructor parameters and class-body fields/properties that participate in `@cols(...)`, `@vals(...)`, and `@set(...)` object expansion.
Annotation arguments are evaluated once when the declaration is created, and the resulting adapter instance is retained in declaration metadata.
### `ExecutionResult`
- `affectedRowsCount`
- `getGeneratedKeys()`
@@ -224,7 +288,7 @@ Statements that return rows directly, such as `... returning ...`, should use `s
---
#### Value mapping
## Value mapping
Portable bind values:
@@ -237,6 +301,88 @@ Portable bind values:
Unsupported parameter values fail with `SqlUsageException`.
SQL object-expansion write rules:
- constructor parameters participate in projection by declaration order
- matching serializable class-body fields/properties also participate
- `@Transient` fields are excluded automatically
- `@DbExcept` fields are excluded automatically
- `except:` excludes additional fields for one specific macro use
- direct DB-bindable values are written as-is
- `@DbJson` fields are encoded as canonical JSON text
- `@DbLynon` fields are encoded as Lynon binary
- `@DbSerializeWith(adapter)` fields are encoded through the adapter
- unannotated non-bindable object fields fail with `SqlUsageException`
Write-side encoding is intentionally explicit. The runtime does not try to infer target DB column types from SQL text or backend metadata during statement preparation.
Example:
```lyng
import lyng.io.db
import lyng.io.db.sqlite
class Payload(name: String, count: Int)
object TrimAdapter: DbFieldAdapter {
override fun encode(value, targetType) =
when(value) {
null -> null
else -> value.toString().trim()
}
}
class Item(
id: Int,
@DbSerializeWith(TrimAdapter) title: String,
@DbJson meta: Payload,
@DbLynon state: Payload
) {
var note: String = ""
@DbExcept var cache: String = ""
}
val db = openSqlite(":memory:")
val restored = db.transaction { tx ->
tx.execute(
"create table item(id integer not null, title text not null, meta text not null, state blob not null, note text not null)"
)
val item = Item(1, " first ", Payload("json", 10), Payload("bin", 20))
item.note = "created"
item.cache = "not stored"
tx.execute("insert into item(@cols(?1)) values(@vals(?1))", item)
item.title = " second "
item.meta = Payload("json2", 11)
item.state = Payload("bin2", 21)
item.note = "updated"
tx.execute(
"update item set @set(?1 except: \"id\") where id = ?2",
item,
item.id
)
tx.select("select id, title, meta, state, note from item").decodeAs<Item>().first
}
assertEquals("second", restored.title)
assertEquals("json2", restored.meta.name)
assertEquals(21, restored.state.count)
assertEquals("updated", restored.note)
```
This example shows:
- `@DbSerializeWith(...)` trimming a string before write
- `@DbJson` storing structured data in a text column
- `@DbLynon` storing structured data in a binary column
- `@DbExcept` excluding a field from automatic projection
- `@set(... except: "id")` skipping one field for an update clause
- `decodeAs<Item>()` reconstructing the object on read
Portable result metadata categories:
- `Binary`
@@ -249,11 +395,27 @@ Portable result metadata categories:
- `DateTime`
- `Instant`
Typed row decode rules:
- object/class targets map constructor parameters by column label, case-insensitively
- remaining matching serializable mutable fields are assigned after constructor call
- `@DbDecodeWith(adapter)` on a constructor parameter or class-body field/property takes precedence over built-in JSON/Lynon decoding
- `@DbDecodeWith(adapter)` must receive exactly one adapter instance implementing `DbFieldAdapter`
- adapter output must match the target member type or decoding fails with `SqlUsageException`
- missing required non-null constructor fields fail
- defaulted or nullable constructor fields may be omitted from the result
- extra result columns currently fail in strict mode
- if a row has exactly one column, that value may be decoded directly as the requested target type
- JSON-like native column types (`json`, `jsonb`) are decoded through typed canonical `Json` when the target type is not `String`
- binary columns are decoded through `Lynon` when the target type is not `Buffer`
- `Buffer` targets keep the raw binary payload without Lynon decoding
- plain text columns are not implicitly treated as JSON
For temporal types, see [time functions](time.md).
---
#### SQLite provider
## SQLite provider
`lyng.io.db.sqlite` currently provides the first concrete backend.
@@ -297,7 +459,7 @@ Open-time validation failures:
- malformed URL or bad option shape -> `IllegalArgumentException`
- runtime open failure -> `DatabaseException`
#### JDBC provider
## JDBC provider
`lyng.io.db.jdbc` is currently implemented on the JVM target only. The `lyngio-jvm` artifact bundles and explicitly loads these JDBC drivers:
@@ -369,7 +531,7 @@ PostgreSQL-specific notes:
---
#### Lifetime rules
## Lifetime rules
`ResultSet` is valid only while its owning transaction is active.
@@ -387,12 +549,14 @@ This means:
- do not keep `ResultSet` objects after the transaction block returns
- materialize rows with `toList()` inside the transaction when they must outlive it
- the iterable returned by `decodeAs<T>()` is also transaction-scoped
- decoded objects produced while iterating `decodeAs<T>()` are detached ordinary Lyng values
The same rule applies to generated keys from `ExecutionResult.getGeneratedKeys()`: the `ResultSet` is transaction-scoped, but rows returned by `toList()` are detached.
---
#### Platform support
## Platform support
- `lyng.io.db` — generic contract, available when host code installs it
- `lyng.io.db.sqlite` — implemented on JVM and Linux Native in the current release tree
+162 -6
View File
@@ -1,6 +1,40 @@
# Lyng serialization
Lyng has builting binary bit-effective serialization format, called Lynon for LYng Object Notation. It is typed, binary, implements caching, automatic compression, variable-length ints, one-bit Booleans an many nice features.
Lyng has a built-in serialization module, `lyng.serialization`.
There are now two built-in formats with different goals:
- `Lynon`: the canonical binary format for Lyng values.
- `Json`: the canonical JSON-based round-trip format for Lyng values.
In addition, `Obj.toJson()` / `toJsonString()` remain available as a plain JSON projection for interoperability with
regular JSON tools and Kotlin `kotlinx.serialization`.
## Canonical formats
`Lynon` and `Json` are both exposed as format objects with the same surface:
- `Format.encode(value)`
- `Format.decode(encodedValue)`
For the built-in formats:
- `Lynon.encode(x)` returns `BitBuffer`
- `Lynon.decode(bitBuffer)` returns the original Lyng value
- `Json.encode(x)` returns `String`
- `Json.decode(jsonString)` returns the original Lyng value
`Json` also provides a typed canonical mode:
- `Json.encodeAs(Type, value)` returns `String`
- `Json.decodeAs(Type, jsonString)` returns the original Lyng value of the specified type
This is still canonical JSON, but it is schema-driven instead of fully self-describing.
## Lynon
Lynon is LYng Object Notation. It is typed, binary, bit-effective, implements caching, automatic compression,
variable-length integers, one-bit booleans, and preserves Lyng runtime structure well.
It is as simple as:
@@ -20,7 +54,8 @@ It is as simple as:
assert( text.length > (encodedBits.toBuffer() as Buffer).size )
>>> void
Any class you create is serializable by default; lynon serializes first constructor fields, then any `var` member fields.
Any class you create is serializable by default; Lynon serializes first constructor fields, then any `var` member
fields.
## Transient Fields
@@ -40,7 +75,7 @@ class MyData(@Transient val tempSecret, val publicData) {
Transient fields:
- Are **omitted** from Lynon binary streams.
- Are **omitted** from JSON output (via `toJson`).
- Are **omitted** from JSON output (`toJson`) and canonical `Json.encode(...)`.
- Are **ignored** during structural equality checks (`==`).
- If a transient constructor parameter has a **default value**, it will be restored to that default value during deserialization. Otherwise, it will be `null`.
- Class body fields marked as `@Transient` will keep their initial values (or values assigned in `init`) after deserialization.
@@ -49,8 +84,131 @@ Transient fields:
- **Singleton Objects**: `object` declarations are serializable by name. Their state (mutable fields) is also serialized and restored, respecting `@Transient`.
- **Classes**: Class objects themselves can be serialized. They are serialized by their full qualified name. When converted to JSON, a class object includes its public static fields (excluding those marked `@Transient`).
- **Exceptions**: canonical formats preserve exception class, message, extra data, and captured stack trace.
## Custom Serialization
## Plain JSON projection vs canonical Json format
There are two JSON-related APIs and they serve different purposes:
- `Obj.toJson()` / `toJsonString()`
- produce ordinary JSON values
- best for interop with external JSON systems
- best for `Obj.decodeSerializable()` / `decodeSerializableWith()`
- may be lossy for Lyng-specific structures
- `Json.encode()` / `Json.decode()`
- produce JSON text too
- use Lyng-specific type tags so the payload is self-describing
- intended for round-tripping Lyng values
- intended to match Lynon semantics where JSON can carry them
- still keep ordinary string-key maps in traditional JSON object form
- can preserve values that plain JSON cannot represent directly, such as:
- maps with non-string keys
- sets
- buffers and bit buffers
- class instances
- singleton objects
- enums
- exceptions
- date/time objects
- non-finite reals
- `void`
- `Json.encodeAs(Type, value)` / `Json.decodeAs(Type, text)`
- also round-trip Lyng values through JSON text
- use the declared or requested type as decoding schema
- recursively omit type tags when the declared type is already exact enough
- keep canonical tags when the runtime value is more specific than the declared type
- produce less noisy JSON for closed and otherwise precisely-typed object graphs
- still keep ordinary `Map<String, ...>` values in traditional JSON object form
Why this split exists:
- plain `toJson()` must remain ordinary JSON so it stays convenient for external JSON systems and Kotlin
`kotlinx.serialization`
- canonical `Json.encode()` is for Lyng-to-Lyng transport through JSON text without any external schema, so it must
remain self-describing and preserve Lyng runtime
distinctions whenever possible
- `Json.encodeAs()` exists for the cases where a schema is known on both sides and we want canonical round-trip
behavior with fewer tags
- one API cannot optimize for both goals at once: either you get too many Lyng tags for ordinary JSON interop, or you
get lossy round-trips
Example:
import lyng.serialization
import lyng.time
enum Color { Red, Green }
class Point(x,y) { var z = 42 }
val p = Point(1,2)
p.z = 99
val x = List(
p,
Map([1, "one"], ["two", 2]),
Set(1,2,3),
"hello".encodeUtf8(),
Date(2026,4,15),
Color.Green
)
assertEquals(x, Json.decode(Json.encode(x)))
>>> void
Typed canonical example:
import lyng.serialization
closed class Point(x: Int, y: Int)
closed class Segment(a: Point, b: Point)
val value = Segment(Point(0,1), Point(2,3))
val json = Json.encodeAs(Segment, value)
assertEquals("{\"a\":{\"x\":0,\"y\":1},\"b\":{\"x\":2,\"y\":3}}", json)
assertEquals(value, Json.decodeAs(Segment, json))
>>> void
## Adding more formats from Kotlin modules
External modules can add new formats on the Kotlin side.
The common base class is:
```kotlin
abstract class ObjSerializationFormatClass(className: String) : ObjClass(className) {
abstract suspend fun encodeValue(scope: Scope, value: Obj): Obj
abstract suspend fun decodeValue(scope: Scope, encoded: Obj): Obj
}
```
To export a new format from a module:
```kotlin
im.addPackage("test.formats") { module ->
module.bindSerializationFormat(
object : ObjSerializationFormatClass("Reverse") {
override suspend fun encodeValue(scope: Scope, value: Obj): Obj =
ObjString(value.toString(scope).value.reversed())
override suspend fun decodeValue(scope: Scope, encoded: Obj): Obj =
ObjString((encoded as ObjString).value.reversed())
}
)
}
```
Then from Lyng, after importing the Kotlin module above, usage looks like:
```lyng
import test.formats
assertEquals("cba", Reverse.encode("abc"))
assertEquals("abc", Reverse.decode("cba"))
```
## Notes
Important is to understand that normally `Lynon.decode` wants [BitBuffer], as `Lynon.encode` produces. If you have the regular [Buffer], be sure to convert it:
@@ -59,5 +217,3 @@ Important is to understand that normally `Lynon.decode` wants [BitBuffer], as `L
this possibly creates extra zero bits at the end, as bit content could be shorter than byte-grained but for the Lynon format it does not make sense. Note that when you serialize [BitBuffer], exact number of bits is written. To convert bit buffer to bytes:
Lynon.encode("hello").toBuffer()
(topic is incomplete and under construction)
+1 -1
View File
@@ -327,7 +327,7 @@ Singleton objects are declared using the `object` keyword. They provide a conven
```lyng
object Config {
val version = "1.5.5"
val version = "1.5.6-SNAPSHOT"
fun show() = println("Config version: " + version)
}
+56
View File
@@ -0,0 +1,56 @@
import lyng.io.db.sqlite
println("SQLite serialization demo: write-side projection and decodeAs<T>()")
class Payload(name: String, count: Int)
class Item(
id: Int,
title: String,
@DbJson meta: Payload,
@DbLynon state: Payload
) {
var note: String = ""
@DbExcept var cache: String = ""
}
val restored = openSqlite(":memory:").transaction { tx ->
tx.execute(
"create table item(id integer not null, title text not null, meta text not null, state blob not null, note text not null)"
)
val item = Item(1, "first", Payload("json", 10), Payload("bin", 20))
item.note = "created"
item.cache = "not stored"
tx.execute("insert into item(@cols(?1)) values(@vals(?1))", item)
item.title = "second"
item.meta = Payload("json2", 11)
item.state = Payload("bin2", 21)
item.note = "updated"
tx.execute(
"update item set @set(?1 except: \"id\") where id = ?2",
item,
item.id
)
val restored = tx.select("select * from item where id = ?", 1).decodeAs<Item>().first
assertEquals("second", restored.title)
assertEquals("json2", restored.meta.name)
assertEquals(11, restored.meta.count)
assertEquals("bin2", restored.state.name)
assertEquals(21, restored.state.count)
assertEquals("updated", restored.note)
restored
} as Item
println("Restored item:")
println(" id=" + restored.id)
println(" title=" + restored.title)
println(" meta=" + restored.meta.name + "/" + restored.meta.count)
println(" state=" + restored.state.name + "/" + restored.state.count)
println(" note=" + restored.note)
println("OK")
File diff suppressed because it is too large. Load diff
@@ -137,6 +137,392 @@ class LyngSqliteModuleTest {
assertEquals(2L, result.value)
}
@Test
fun testDecodeAsProjectsJsonColumnIntoObjectField() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
class Row(id: Int, payload: Point)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(id integer not null, payload json not null)")
tx.execute("insert into data(id, payload) values(?, ?)", 7, "{\"x\":4,\"y\":5}")
val row = tx.select("select id, payload from data").decodeAs<Row>().first
assertEquals(7, row.id)
assertEquals(4, row.payload.x)
assertEquals(5, row.payload.y)
row.payload.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-decode-json-field>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testDecodeAsSupportsSingleJsonColumnProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload json not null)")
tx.execute("insert into data(payload) values(?)", "{\"x\":9,\"y\":11}")
val point = tx.select("select payload from data").decodeAs<Point>().first
assertEquals(9, point.x)
assertEquals(11, point.y)
point.x + point.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-decode-json-single>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(20L, result.value)
}
@Test
fun testDecodeAsDoesNotAutoDecodePlainTextAsJson() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload text not null)")
tx.execute("insert into data(payload) values(?)", "{\"x\":1,\"y\":2}")
tx.select("select payload from data").decodeAs<Point>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-decode-json-text-guard>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testDecodeAsSupportsSingleLynonBinaryProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.serialization
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
tx.execute("insert into data(payload) values(?)", Lynon.encode(Point(6, 8)).toBuffer())
val point = tx.select("select payload from data").decodeAs<Point>().first
assertEquals(6, point.x)
assertEquals(8, point.y)
point.x + point.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-decode-lynon-single>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(14L, result.value)
}
@Test
fun testDecodeAsSupportsDbDecodeWithOnConstructorParamsAndFields() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object TrimmedStringAdapter: DbFieldAdapter {
override fun decode(rawValue, column, row, targetType) =
when(rawValue) {
null -> null
else -> rawValue.toString().trim()
}
}
class User(
id: Int,
@DbDecodeWith(TrimmedStringAdapter) name: String
) {
@DbDecodeWith(TrimmedStringAdapter)
var note: String = ""
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(id integer not null, name text not null, note text not null)")
tx.execute("insert into data(id, name, note) values(?, ?, ?)", 10, " Alice ", " hello ")
val user = tx.select("select id, name, note from data").decodeAs<User>().first
assertEquals(10, user.id)
assertEquals("Alice", user.name)
assertEquals("hello", user.note)
user.note.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-decode-dbdecodewith>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testDecodeAsFailsWhenDbDecodeWithReturnsWrongType() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object BadAdapter: DbFieldAdapter {
override fun decode(rawValue, column, row, targetType) = 42
}
class User(@DbDecodeWith(BadAdapter) name: String)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(name text not null)")
tx.execute("insert into data(name) values(?)", "Alice")
tx.select("select name from data").decodeAs<User>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-decode-dbdecodewith-bad-type>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testDecodeAsKeepsRawBufferForBufferTarget() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.buffer
import lyng.serialization
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
val encoded = Lynon.encode(Point(1, 2)).toBuffer()
tx.execute("insert into data(payload) values(?)", encoded)
val payload = tx.select("select payload from data").decodeAs<Buffer>().first
assertEquals(encoded.size, payload.size)
payload.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-decode-buffer-raw>", code), scope.importManager).execute(scope) as ObjInt
assertTrue(result.value > 0)
}
@Test
fun testDecodeAsFailsForNonLynonBinaryTypedProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.buffer
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
tx.execute("insert into data(payload) values(?)", "hello".encodeUtf8())
tx.select("select payload from data").decodeAs<Point>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-decode-lynon-binary-guard>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testSqlObjectExpansionInsertAndUpdateUseDbAnnotations() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Payload(name: String, count: Int)
class Item(
id: Int,
title: String,
@DbJson meta: Payload,
@DbLynon state: Payload
) {
var note: String = ""
@DbExcept var cache: String = "skip"
@Transient var transientNote: String = "temp"
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table item(id integer not null, title text not null, meta text not null, state blob not null, note text not null)")
val item = Item(1, "first", Payload("json", 10), Payload("bin", 20))
item.note = "created"
tx.execute("insert into item(@cols(?1)) values(@vals(?1))", item)
item.title = "second"
item.meta = Payload("json2", 11)
item.state = Payload("bin2", 21)
item.note = "updated"
item.cache = "must-not-be-written"
item.transientNote = "must-not-be-written"
tx.execute("update item set @set(?1) where id = ?2", item, 1)
val restored = tx.select("select id, title, meta, state, note from item").decodeAs<Item>().first
assertEquals(1, restored.id)
assertEquals("second", restored.title)
assertEquals("json2", restored.meta.name)
assertEquals(11, restored.meta.count)
assertEquals("bin2", restored.state.name)
assertEquals(21, restored.state.count)
assertEquals("updated", restored.note)
restored.state.count
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-object-expansion>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(21L, result.value)
}
@Test
fun testSqlObjectExpansionSupportsDbSerializeWithAdapter() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object TrimAdapter: DbFieldAdapter {
override fun encode(value, targetType) =
when(value) {
null -> null
else -> value.toString().trim()
}
}
class User(
id: Int,
@DbSerializeWith(TrimAdapter) name: String
)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table user(id integer not null, name text not null)")
tx.execute("insert into user(@cols(?1)) values(@vals(?1))", User(7, " Alice "))
val row = tx.select("select id, name from user").first
val storedName: String = row["name"] as String
assertEquals(7, row["id"])
assertEquals("Alice", storedName)
storedName.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-object-expansion-adapter>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testSqlObjectExpansionSupportsClauseLevelExceptFilter() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Item(id: Int, title: String, note: String) {
var stamp: String = ""
@DbExcept var cache: String = "skip"
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table item(id integer not null, title text not null, note text not null, stamp text not null default '')")
val item = Item(1, "first", "keep")
item.stamp = "created"
tx.execute(
"insert into item(@cols(?1 except: \"stamp\")) values(@vals(?1 except: \"stamp\"))",
item
)
item.title = "second"
item.note = "changed-but-excluded"
item.stamp = "updated"
item.cache = "still-skip"
tx.execute(
"update item set @set(?1 except: \"id\", \"note\") where id = ?2",
item,
1
)
val restored = tx.select("select id, title, note, stamp from item").decodeAs<Item>().first
assertEquals(1, restored.id)
assertEquals("second", restored.title)
assertEquals("keep", restored.note)
assertEquals("updated", restored.stamp)
restored.stamp.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-object-expansion-except>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(7L, result.value)
}
@Test
fun testSqlObjectExpansionRejectsUnannotatedComplexFields() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Payload(name: String)
class BadRecord(id: Int, payload: Payload)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table bad_record(id integer not null, payload text not null)")
tx.execute("insert into bad_record(@cols(?1)) values(@vals(?1))", BadRecord(1, Payload("x")))
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-object-expansion-bad-field>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testNestedTransactionRollbackUsesSavepoint() = runTest {
val scope = Script.newScope()
@@ -19,11 +19,13 @@ package net.sergeych.lyng.io.db.sqlite
import kotlinx.coroutines.test.runTest
import kotlinx.datetime.TimeZone
import net.sergeych.lyng.Compiler
import net.sergeych.lyng.ExecutionError
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.Script
import net.sergeych.lyng.Source
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBool
import net.sergeych.lyng.obj.ObjBuffer
@@ -231,6 +233,392 @@ class LyngSqliteModuleNativeTest {
assertEquals("beta", stringValue(scope, rows.getAt(scope, ObjInt.of(1)).getAt(scope, ObjString("name"))))
}
@Test
fun testDecodeAsProjectsJsonColumnIntoObjectField() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
class Row(id: Int, payload: Point)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(id integer not null, payload json not null)")
tx.execute("insert into data(id, payload) values(?, ?)", 7, "{\"x\":4,\"y\":5}")
val row = tx.select("select id, payload from data").decodeAs<Row>().first
assertEquals(7, row.id)
assertEquals(4, row.payload.x)
assertEquals(5, row.payload.y)
row.payload.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-decode-json-field>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testDecodeAsSupportsSingleJsonColumnProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload json not null)")
tx.execute("insert into data(payload) values(?)", "{\"x\":9,\"y\":11}")
val point = tx.select("select payload from data").decodeAs<Point>().first
assertEquals(9, point.x)
assertEquals(11, point.y)
point.x + point.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-decode-json-single>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(20L, result.value)
}
@Test
fun testDecodeAsDoesNotAutoDecodePlainTextAsJson() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload text not null)")
tx.execute("insert into data(payload) values(?)", "{\"x\":1,\"y\":2}")
tx.select("select payload from data").decodeAs<Point>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-native-decode-json-text-guard>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testDecodeAsSupportsSingleLynonBinaryProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.serialization
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
tx.execute("insert into data(payload) values(?)", Lynon.encode(Point(6, 8)).toBuffer())
val point = tx.select("select payload from data").decodeAs<Point>().first
assertEquals(6, point.x)
assertEquals(8, point.y)
point.x + point.y
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-decode-lynon-single>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(14L, result.value)
}
@Test
fun testDecodeAsSupportsDbDecodeWithOnConstructorParamsAndFields() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object TrimmedStringAdapter: DbFieldAdapter {
override fun decode(rawValue, column, row, targetType) =
when(rawValue) {
null -> null
else -> rawValue.toString().trim()
}
}
class User(
id: Int,
@DbDecodeWith(TrimmedStringAdapter) name: String
) {
@DbDecodeWith(TrimmedStringAdapter)
var note: String = ""
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(id integer not null, name text not null, note text not null)")
tx.execute("insert into data(id, name, note) values(?, ?, ?)", 10, " Alice ", " hello ")
val user = tx.select("select id, name, note from data").decodeAs<User>().first
assertEquals(10, user.id)
assertEquals("Alice", user.name)
assertEquals("hello", user.note)
user.note.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-decode-dbdecodewith>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testDecodeAsFailsWhenDbDecodeWithReturnsWrongType() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object BadAdapter: DbFieldAdapter {
override fun decode(rawValue, column, row, targetType) = 42
}
class User(@DbDecodeWith(BadAdapter) name: String)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(name text not null)")
tx.execute("insert into data(name) values(?)", "Alice")
tx.select("select name from data").decodeAs<User>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-native-decode-dbdecodewith-bad-type>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testDecodeAsKeepsRawBufferForBufferTarget() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.buffer
import lyng.serialization
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
val encoded = Lynon.encode(Point(1, 2)).toBuffer()
tx.execute("insert into data(payload) values(?)", encoded)
val payload = tx.select("select payload from data").decodeAs<Buffer>().first
assertEquals(encoded.size, payload.size)
payload.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-decode-buffer-raw>", code), scope.importManager).execute(scope) as ObjInt
assertTrue(result.value > 0)
}
@Test
fun testDecodeAsFailsForNonLynonBinaryTypedProjection() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
import lyng.buffer
class Point(x: Int, y: Int)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table data(payload blob not null)")
tx.execute("insert into data(payload) values(?)", "hello".encodeUtf8())
tx.select("select payload from data").decodeAs<Point>().first
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-native-decode-lynon-binary-guard>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testSqlObjectExpansionInsertAndUpdateUseDbAnnotations() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Payload(name: String, count: Int)
class Item(
id: Int,
title: String,
@DbJson meta: Payload,
@DbLynon state: Payload
) {
var note: String = ""
@DbExcept var cache: String = "skip"
@Transient var transientNote: String = "temp"
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table item(id integer not null, title text not null, meta text not null, state blob not null, note text not null)")
val item = Item(1, "first", Payload("json", 10), Payload("bin", 20))
item.note = "created"
tx.execute("insert into item(@cols(?1)) values(@vals(?1))", item)
item.title = "second"
item.meta = Payload("json2", 11)
item.state = Payload("bin2", 21)
item.note = "updated"
item.cache = "must-not-be-written"
item.transientNote = "must-not-be-written"
tx.execute("update item set @set(?1) where id = ?2", item, 1)
val restored = tx.select("select id, title, meta, state, note from item").decodeAs<Item>().first
assertEquals(1, restored.id)
assertEquals("second", restored.title)
assertEquals("json2", restored.meta.name)
assertEquals(11, restored.meta.count)
assertEquals("bin2", restored.state.name)
assertEquals(21, restored.state.count)
assertEquals("updated", restored.note)
restored.state.count
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-object-expansion>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(21L, result.value)
}
@Test
fun testSqlObjectExpansionSupportsDbSerializeWithAdapter() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db
import lyng.io.db.sqlite
object TrimAdapter: DbFieldAdapter {
override fun encode(value, targetType) =
when(value) {
null -> null
else -> value.toString().trim()
}
}
class User(
id: Int,
@DbSerializeWith(TrimAdapter) name: String
)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table user(id integer not null, name text not null)")
tx.execute("insert into user(@cols(?1)) values(@vals(?1))", User(7, " Alice "))
val row = tx.select("select id, name from user").first
val storedName: String = row["name"] as String
assertEquals(7, row["id"])
assertEquals("Alice", storedName)
storedName.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-object-expansion-adapter>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(5L, result.value)
}
@Test
fun testSqlObjectExpansionSupportsClauseLevelExceptFilter() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Item(id: Int, title: String, note: String) {
var stamp: String = ""
@DbExcept var cache: String = "skip"
}
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table item(id integer not null, title text not null, note text not null, stamp text not null default '')")
val item = Item(1, "first", "keep")
item.stamp = "created"
tx.execute(
"insert into item(@cols(?1 except: \"stamp\")) values(@vals(?1 except: \"stamp\"))",
item
)
item.title = "second"
item.note = "changed-but-excluded"
item.stamp = "updated"
item.cache = "still-skip"
tx.execute(
"update item set @set(?1 except: \"id\", \"note\") where id = ?2",
item,
1
)
val restored = tx.select("select id, title, note, stamp from item").decodeAs<Item>().first
assertEquals(1, restored.id)
assertEquals("second", restored.title)
assertEquals("keep", restored.note)
assertEquals("updated", restored.stamp)
restored.stamp.size
}
""".trimIndent()
val result = Compiler.compile(Source("<sqlite-native-object-expansion-except>", code), scope.importManager).execute(scope) as ObjInt
assertEquals(7L, result.value)
}
@Test
fun testSqlObjectExpansionRejectsUnannotatedComplexFields() = runTest {
val scope = Script.newScope()
createSqliteModule(scope.importManager)
val code = """
import lyng.io.db.sqlite
class Payload(name: String)
class BadRecord(id: Int, payload: Payload)
val db = openSqlite(":memory:")
db.transaction { tx ->
tx.execute("create table bad_record(id integer not null, payload text not null)")
tx.execute("insert into bad_record(@cols(?1)) values(@vals(?1))", BadRecord(1, Payload("x")))
}
""".trimIndent()
val error = assertFailsWith<ExecutionError> {
Compiler.compile(Source("<sqlite-native-object-expansion-bad-field>", code), scope.importManager).execute(scope)
}
assertEquals("SqlUsageException", error.errorObject.objClass.className)
}
@Test
fun testExecuteRejectsReturningButSelectSupportsIt() = runTest {
val scope = Script.newScope()
+81
View File
@@ -20,6 +20,38 @@ extern class SqlColumn {
val nativeType: String
}
/*
Adapter interface for custom DB field projection.
Use it with `@DbDecodeWith(adapter)` on class constructor parameters or
class-body fields/properties participating in `decodeAs<T>()` projection,
and with `@DbSerializeWith(adapter)` on fields participating in SQL object
expansion macros such as `@vals(?1)` and `@set(?1)`.
`targetType` is the requested Lyng target type represented as a runtime
type object, such as a class or a type expression.
Default methods throw `NotImplementedException`.
*/
interface DbFieldAdapter {
/*
Decode one raw database field value into a Lyng value suitable for the
requested target type.
*/
fun decode(rawValue: Object?, column: SqlColumn, row: SqlRow, targetType: Object): Object? =
throw NotImplementedException("DB field adapter decode is not implemented")
/*
Encode one Lyng value into a database field representation.
The result must be a direct DB-bindable value:
null, Bool, Int, Double/Real, Decimal, String, Buffer, Date, DateTime,
or Instant.
*/
fun encode(value: Object?, targetType: Object): Object? =
throw NotImplementedException("DB field adapter encode is not implemented")
}
extern class SqlRow {
/* Number of columns in the row */
val size: Int
@@ -34,6 +66,22 @@ extern class SqlRow {
names and invalid indexes should also fail.
*/
override fun getAt(indexOrName: String | Int): Object?
/*
Decode this row into a typed Lyng value.
For object/class targets, constructor parameters are matched by column
label first and then remaining matching serializable mutable fields are
assigned.
If a constructor parameter or class-body field/property has
`@DbDecodeWith(adapter)`, the adapter is applied first and its result
must match the target member type.
For single-column rows, the column value may also be decoded directly to
the requested target type.
*/
fun decodeAs<T>(): T
}
/*
@@ -69,6 +117,16 @@ extern class ResultSet : Iterable<SqlRow> {
internally, but this must not change visible later iteration behavior.
*/
override fun isEmpty(): Bool
/*
Return a transaction-scoped iterable view that decodes each row with
`SqlRow.decodeAs<T>()`.
The returned iterable itself must not be used after the owning
transaction ends. Materialized decoded objects may outlive the
transaction.
*/
fun decodeAs<T>(): Iterable<T>
}
extern class ExecutionResult {
@@ -133,6 +191,29 @@ extern class SqlTransaction {
- Date, DateTime, Instant
Unsupported parameter values should fail with `SqlUsageException`.
SQL object expansion macros are also supported:
- `@cols(?1)` expands one object argument to a comma-separated column list
- `@vals(?1)` expands the same object to matching `?` placeholders and
generated bind values
- `@set(?1)` expands to `col = ?` pairs and generated bind values
- each macro also accepts an optional `except:` filter, for example
`@set(?1 except: "id", "updatedAt")`
When a clause uses `@cols`, `@vals`, or `@set`, any non-expanded scalar
parameters in the same clause must use explicit indexed placeholders such
as `?2`, `?3`, and so on.
Projection is declaration-driven:
- `@Transient` fields are excluded
- `@DbExcept` fields are excluded
- `except:` excludes additional fields for that specific macro use
- `@DbJson` fields are encoded as JSON text
- `@DbLynon` fields are encoded as Lynon binary
- `@DbSerializeWith(adapter)` fields are encoded through the adapter
- unannotated non-primitive fields fail with `SqlUsageException`
*/
fun select(clause: String, params...): ResultSet
+1 -1
View File
@@ -21,7 +21,7 @@ import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
group = "net.sergeych"
version = "1.5.5"
version = "1.5.6-SNAPSHOT"
// Removed legacy buildscript classpath declarations; plugins are applied via the plugins DSL below
@@ -88,7 +88,8 @@ data class ArgsDeclaration(val params: List<Item>, val endTokenType: Token.Type)
a.visibility ?: defaultVisibility,
recordType = recordType,
declaringClass = declaringClass,
isTransient = a.isTransient
isTransient = a.isTransient,
annotations = a.annotations
)
}
return
@@ -108,7 +109,8 @@ data class ArgsDeclaration(val params: List<Item>, val endTokenType: Token.Type)
a.visibility ?: defaultVisibility,
recordType = recordType,
declaringClass = declaringClass,
isTransient = a.isTransient
isTransient = a.isTransient,
annotations = a.annotations
)
}
@@ -505,5 +507,7 @@ data class ArgsDeclaration(val params: List<Item>, val endTokenType: Token.Type)
val accessType: AccessType? = null,
val visibility: Visibility? = null,
val isTransient: Boolean = false,
val annotationSpecs: List<ParsedDeclAnnotation> = emptyList(),
val annotations: List<DeclAnnotation> = emptyList(),
)
}
@@ -41,6 +41,17 @@ data class ClassDeclSpec(
val initScope: List<Statement>,
)
private suspend fun evaluateConstructorAnnotations(scope: Scope, args: ArgsDeclaration?): ArgsDeclaration? {
if (args == null) return null
if (args.params.none { it.annotationSpecs.isNotEmpty() }) return args
return args.copy(
params = args.params.map { item ->
if (item.annotationSpecs.isEmpty()) item
else item.copy(annotations = item.annotationSpecs.evaluateDeclAnnotations(scope))
}
)
}
internal suspend fun executeClassDecl(
scope: Scope,
spec: ClassDeclSpec,
@@ -60,7 +71,8 @@ internal suspend fun executeClassDecl(
val newClass = ObjInstanceClass(spec.className, *parentClasses.toTypedArray())
newClass.isAnonymous = spec.isAnonymous
newClass.constructorMeta = ArgsDeclaration(emptyList(), Token.Type.RPAREN)
newClass.isSingletonObject = true
newClass.constructorMeta = evaluateConstructorAnnotations(scope, ArgsDeclaration(emptyList(), Token.Type.RPAREN))
for (i in parentClasses.indices) {
val argsList = spec.baseSpecs[i].args
if (argsList != null) newClass.directParentArgs[parentClasses[i]] = argsList
@@ -85,6 +97,7 @@ internal suspend fun executeClassDecl(
}
if (spec.isExtern) {
val evaluatedConstructorArgs = evaluateConstructorAnnotations(scope, spec.constructorArgs)
val parentClasses = spec.baseSpecs.mapNotNull { baseSpec ->
val rec = scope[baseSpec.name]
val cls = rec?.value as? ObjClass
@@ -105,8 +118,8 @@ internal suspend fun executeClassDecl(
}
val stub = resolved ?: ObjInstanceClass(spec.className, *parentClasses.toTypedArray()).apply {
this.isAbstract = true
constructorMeta = spec.constructorArgs
spec.constructorArgs?.params?.forEach { p ->
constructorMeta = evaluatedConstructorArgs
evaluatedConstructorArgs?.params?.forEach { p ->
if (p.accessType != null) {
createField(
p.name,
@@ -117,6 +130,7 @@ internal suspend fun executeClassDecl(
pos = Pos.builtIn,
isTransient = p.isTransient,
type = ObjRecord.Type.ConstructorField,
annotations = p.annotations,
fieldId = spec.constructorFieldIds?.get(p.name)
)
}
@@ -160,16 +174,17 @@ internal suspend fun executeClassDecl(
}
}
val evaluatedConstructorArgs = evaluateConstructorAnnotations(scope, spec.constructorArgs)
val newClass = ObjInstanceClass(spec.className, *parentClasses.toTypedArray()).also {
it.isAbstract = spec.isAbstract
it.isClosed = spec.isClosed
it.instanceConstructor = constructorCode
it.constructorMeta = spec.constructorArgs
it.constructorMeta = evaluatedConstructorArgs
for (i in parentClasses.indices) {
val argsList = spec.baseSpecs[i].args
if (argsList != null) it.directParentArgs[parentClasses[i]] = argsList
}
spec.constructorArgs?.params?.forEach { p ->
evaluatedConstructorArgs?.params?.forEach { p ->
if (p.accessType != null) {
it.createField(
p.name,
@@ -180,6 +195,7 @@ internal suspend fun executeClassDecl(
pos = Pos.builtIn,
isTransient = p.isTransient,
type = ObjRecord.Type.ConstructorField,
annotations = p.annotations,
fieldId = spec.constructorFieldIds?.get(p.name)
)
}
@@ -38,6 +38,7 @@ class ClassInstanceFieldDeclStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation> = emptyList(),
val fieldId: Int?,
val initStatement: Statement?,
override val pos: Pos,
@@ -56,6 +57,7 @@ class ClassInstancePropertyDeclStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation> = emptyList(),
val prop: ObjProperty,
val methodId: Int?,
val initStatement: Statement?,
@@ -75,6 +77,7 @@ class ClassInstanceDelegatedDeclStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation> = emptyList(),
val methodId: Int?,
val initStatement: Statement?,
override val pos: Pos,
@@ -32,6 +32,7 @@ class ClassStaticFieldInitStatement(
val initializer: Statement?,
val isDelegated: Boolean,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation> = emptyList(),
private val startPos: Pos,
) : Statement() {
override val pos: Pos = startPos
@@ -39,6 +40,7 @@ class ClassStaticFieldInitStatement(
override suspend fun execute(scope: Scope): Obj {
val initValue = initializer?.let { execBytecodeOnly(scope, it, "class static field init") }?.byValueCopy()
?: ObjNull
val annotations = annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("static field init requires class scope")
return if (isDelegated) {
@@ -61,7 +63,8 @@ class ClassStaticFieldInitStatement(
writeVisibility,
startPos,
isTransient = isTransient,
type = ObjRecord.Type.Delegated
type = ObjRecord.Type.Delegated,
annotations = annotations
).apply {
delegate = finalDelegate
}
@@ -72,7 +75,8 @@ class ClassStaticFieldInitStatement(
visibility,
writeVisibility,
recordType = ObjRecord.Type.Delegated,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
).apply {
delegate = finalDelegate
}
@@ -85,7 +89,8 @@ class ClassStaticFieldInitStatement(
visibility,
writeVisibility,
startPos,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
)
scope.addItem(
name,
@@ -94,7 +99,8 @@ class ClassStaticFieldInitStatement(
visibility,
writeVisibility,
recordType = ObjRecord.Type.Field,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
)
initValue
}
@@ -2014,6 +2014,7 @@ class Compiler(
private var lastAnnotation: (suspend (Scope, ObjString, Statement) -> Statement)? = null
private var isTransientFlag: Boolean = false
private val pendingDeclAnnotations: MutableList<ParsedDeclAnnotation> = mutableListOf()
private var lastLabel: String? = null
private val strictSlotRefs: Boolean = settings.strictSlotRefs
private val allowUnresolvedRefs: Boolean = settings.allowUnresolvedRefs
@@ -2689,6 +2690,7 @@ class Compiler(
lastAnnotation = null
lastLabel = null
isTransientFlag = false
pendingDeclAnnotations.clear()
while (true) {
val t = cc.next()
return when (t.type) {
@@ -2706,15 +2708,17 @@ class Compiler(
}
Token.Type.ATLABEL -> {
val label = t.value
if (label == "Transient") {
val parsedAnnotation = parseDeclAnnotation(t)
if (parsedAnnotation.name == "Transient") {
isTransientFlag = true
continue
}
if (cc.peekNextNonWhitespace().type == Token.Type.LBRACE) {
lastLabel = label
lastLabel = parsedAnnotation.name
}
pendingDeclAnnotations += parsedAnnotation
if (parsedAnnotation.name != "Transient") {
lastAnnotation = parsedAnnotation.toStatementAnnotation()
}
lastAnnotation = parseAnnotation(t)
continue
}
@@ -4033,11 +4037,17 @@ class Compiler(
Token.Type.ID, Token.Type.ATLABEL -> {
var isTransient = false
if (t.type == Token.Type.ATLABEL) {
if (t.value == "Transient") {
val annotationSpecs = mutableListOf<ParsedDeclAnnotation>()
while (t.type == Token.Type.ATLABEL) {
val spec = parseDeclAnnotation(t)
annotationSpecs += spec
if (spec.name == "Transient") {
isTransient = true
t = cc.next()
} else throw ScriptError(t.pos, "Unexpected label in argument list")
}
t = cc.next()
}
if (annotationSpecs.isNotEmpty() && !isClassDeclaration) {
throw ScriptError(t.pos, "parameter annotations are currently supported only on class constructor parameters")
}
// visibility
@@ -4114,7 +4124,8 @@ class Compiler(
defaultValue,
effectiveAccess,
visibility,
isTransient
isTransient,
annotationSpecs = annotationSpecs
)
// important: valid argument list continues with ',' and ends with '->' or ')'
@@ -7120,19 +7131,25 @@ class Compiler(
return parseNumberOrNull(isPlus) ?: throw ScriptError(cc.currentPos(), "Expecting number")
}
suspend fun parseAnnotation(t: Token): (suspend (Scope, ObjString, Statement) -> Statement) {
private suspend fun parseDeclAnnotation(t: Token): ParsedDeclAnnotation {
val extraArgs = parseArgsOrNull()
resolutionSink?.reference(t.value, t.pos)
// println("annotation ${t.value}: args: $extraArgs")
return { scope, name, body ->
val extras = extraArgs?.first?.toArguments(scope, extraArgs.second)?.list
val required = listOf(name, body)
val args = extras?.let { required + it } ?: required
val fn = scope.get(t.value)?.value ?: scope.raiseSymbolNotFound("annotation not found: ${t.value}")
if (fn !is Statement) scope.raiseIllegalArgument("annotation must be callable, got ${fn.objClass}")
(fn.execute(scope.createChildScope(Arguments(args))) as? Statement)
?: scope.raiseClassCastError("function annotation must return callable")
}
val compiledArgs = extraArgs?.first?.map { arg ->
val value = arg.value
arg.copy(
value = if (value is Statement) wrapBytecode(value) else value
)
} ?: emptyList()
return ParsedDeclAnnotation(
name = t.value,
args = compiledArgs,
tailBlockMode = extraArgs?.second ?: false,
pos = t.pos
)
}
suspend fun parseAnnotation(t: Token): (suspend (Scope, ObjString, Statement) -> Statement) {
return parseDeclAnnotation(t).toStatementAnnotation()
}
suspend fun parseArgsOrNull(): Pair<List<ParsedArgument>, Boolean>? =
@@ -9232,6 +9249,8 @@ class Compiler(
isTransient: Boolean = isTransientFlag
): Statement {
isTransientFlag = false
val declarationAnnotationSpecs = pendingDeclAnnotations.toList()
pendingDeclAnnotations.clear()
val actualExtern = isExtern || (codeContexts.lastOrNull() as? CodeContext.ClassBody)?.isExtern == true
var start = cc.currentPos()
var extTypeName: String? = null
@@ -9700,6 +9719,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotations = emptyList(),
accessTypeLabel = "Callable",
initializer = initExpr,
pos = start
@@ -10251,6 +10271,8 @@ class Compiler(
isTransient: Boolean = isTransientFlag
): Statement {
isTransientFlag = false
val declarationAnnotationSpecs = pendingDeclAnnotations.toList()
pendingDeclAnnotations.clear()
val actualExtern = isExtern || (codeContexts.lastOrNull() as? CodeContext.ClassBody)?.isExtern == true
val markStart = cc.savePos()
val nextToken = cc.next()
@@ -10643,6 +10665,9 @@ class Compiler(
!isStatic &&
!isProperty
) {
if (declarationAnnotationSpecs.isNotEmpty()) {
throw ScriptError(start, "declaration annotations are currently supported only on class members")
}
if (isDelegate) {
val initExpr = initialExpression ?: throw ScriptError(start, "Delegate must be initialized")
val slotPlan = slotPlanStack.lastOrNull()
@@ -10663,6 +10688,9 @@ class Compiler(
}
if (isStatic) {
if (extTypeName != null && declarationAnnotationSpecs.isNotEmpty()) {
throw ScriptError(start, "declaration annotations are not supported on extension properties")
}
if (declaringClassNameCaptured != null) {
val directRef = unwrapDirectRef(initialExpression)
val declClass = resolveTypeDeclObjClass(varTypeDecl)
@@ -10685,6 +10713,7 @@ class Compiler(
initializer = initialExpression,
isDelegated = isDelegate,
isTransient = isTransient,
annotationSpecs = declarationAnnotationSpecs,
startPos = start
)
return NopStatement
@@ -10847,6 +10876,9 @@ class Compiler(
}
if (extTypeName != null) {
if (declarationAnnotationSpecs.isNotEmpty()) {
throw ScriptError(start, "declaration annotations are not supported on extension properties")
}
declareLocalName(extensionPropertyGetterName(extTypeName, name), isMutable = false)
if (setter != null) {
declareLocalName(extensionPropertySetterName(extTypeName, name), isMutable = false)
@@ -10883,6 +10915,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotations = emptyList(),
accessTypeLabel = accessType,
initializer = initExpr,
pos = start
@@ -10898,6 +10931,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotationSpecs = declarationAnnotationSpecs,
methodId = memberMethodId,
initStatement = initStmt,
pos = start
@@ -10919,6 +10953,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotations = emptyList(),
prop = prop,
pos = start
)
@@ -10933,6 +10968,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotationSpecs = declarationAnnotationSpecs,
prop = prop,
methodId = memberMethodId,
initStatement = initStmt,
@@ -10950,6 +10986,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotations = emptyList(),
isLateInitVal = isLateInitVal,
initializer = initialExpression,
pos = start
@@ -10966,6 +11003,7 @@ class Compiler(
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient,
annotationSpecs = declarationAnnotationSpecs,
fieldId = memberFieldId,
initStatement = initStmt,
pos = start
@@ -0,0 +1,129 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng
import net.sergeych.lyng.bytecode.BytecodeStatement
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjIterable
import net.sergeych.lyng.obj.ObjList
import net.sergeych.lyng.obj.ObjMap
import net.sergeych.lyng.obj.ObjString
/**
* Preserved declaration annotation evaluated at declaration-creation time.
*/
data class DeclAnnotation(
val name: String,
val positional: List<Obj> = emptyList(),
val named: Map<String, Obj> = emptyMap(),
)
/**
* Parsed declaration annotation awaiting declaration-time evaluation.
*/
data class ParsedDeclAnnotation(
val name: String,
val args: List<ParsedArgument> = emptyList(),
val tailBlockMode: Boolean = false,
val pos: Pos = Pos.builtIn,
) {
suspend fun evaluate(scope: Scope): DeclAnnotation {
val resolved = evaluateDeclAnnotationArguments(scope, args, tailBlockMode)
return DeclAnnotation(name, resolved.list, resolved.named)
}
fun toStatementAnnotation(): suspend (Scope, ObjString, Statement) -> Statement = { scope, declName, body ->
val extras = args.toArguments(scope, tailBlockMode).list
val required = listOf(declName, body)
val callArgs = if (extras.isEmpty()) required else required + extras
val fn = scope.get(name)?.value ?: scope.raiseSymbolNotFound("annotation not found: $name")
if (fn !is Statement) scope.raiseIllegalArgument("annotation must be callable, got ${fn.objClass}")
(fn.execute(scope.createChildScope(Arguments(callArgs))) as? Statement)
?: scope.raiseClassCastError("function annotation must return callable")
}
}
suspend fun Iterable<ParsedDeclAnnotation>.evaluateDeclAnnotations(scope: Scope): List<DeclAnnotation> {
val result = mutableListOf<DeclAnnotation>()
for (spec in this) {
result += spec.evaluate(scope)
}
return result
}
private suspend fun evaluateDeclAnnotationArguments(
scope: Scope,
args: List<ParsedArgument>,
tailBlockMode: Boolean,
): Arguments {
suspend fun eval(value: Obj): Obj = when (value) {
is BytecodeBodyProvider -> (value.bytecodeBody() ?: scope.raiseIllegalState("annotation argument requires bytecode body")).execute(scope)
is Statement -> BytecodeStatement.wrap(value, "@annotation", allowLocalSlots = true).execute(scope)
else -> value.callOn(scope)
}
val resolved = ArrayList<ParsedArgument>(args.size)
for (arg in args) {
resolved += arg.copy(value = eval(arg.value))
}
val positional: MutableList<Obj> = mutableListOf()
var named: MutableMap<String, Obj>? = null
var namedSeen = false
for ((idx, x) in resolved.withIndex()) {
if (x.name != null) {
if (named == null) named = linkedMapOf()
if (named.containsKey(x.name)) scope.raiseIllegalArgument("argument '${x.name}' is already set")
named[x.name] = x.value
namedSeen = true
continue
}
val value = x.value
if (x.isSplat) {
when {
value is ObjMap -> {
if (named == null) named = linkedMapOf()
for ((k, v) in value.map) {
if (k !is ObjString) scope.raiseIllegalArgument("named splat expects a Map with string keys")
val key = k.value
if (named.containsKey(key)) scope.raiseIllegalArgument("argument '$key' is already set")
named[key] = v
}
namedSeen = true
}
value is ObjList -> {
if (namedSeen) scope.raiseIllegalArgument("positional splat cannot follow named arguments")
positional.addAll(value.list)
}
value.isInstanceOf(ObjIterable) -> {
if (namedSeen) scope.raiseIllegalArgument("positional splat cannot follow named arguments")
val iterable = value.invokeInstanceMethod(scope, "toList") as ObjList
positional.addAll(iterable.list)
}
else -> scope.raiseClassCastError("expected list of objects for splat argument")
}
} else {
val isLast = idx == resolved.size - 1
if (namedSeen && !(isLast && tailBlockMode)) {
scope.raiseIllegalArgument("positional argument cannot follow named arguments")
}
positional.add(value)
}
}
return Arguments(positional, tailBlockMode, named ?: emptyMap())
}
@@ -33,6 +33,7 @@ class InstanceFieldInitStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotations: List<DeclAnnotation> = emptyList(),
val isLateInitVal: Boolean,
val initializer: Statement?,
override val pos: Pos,
@@ -50,7 +51,8 @@ class InstanceFieldInitStatement(
isAbstract = isAbstract,
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
)
return ObjVoid
}
@@ -74,6 +76,7 @@ class InstancePropertyInitStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotations: List<DeclAnnotation> = emptyList(),
val prop: ObjProperty,
override val pos: Pos,
) : Statement() {
@@ -88,7 +91,8 @@ class InstancePropertyInitStatement(
isAbstract = isAbstract,
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
)
return ObjVoid
}
@@ -104,6 +108,7 @@ class InstanceDelegatedInitStatement(
val isClosed: Boolean,
val isOverride: Boolean,
val isTransient: Boolean,
val annotations: List<DeclAnnotation> = emptyList(),
val accessTypeLabel: String,
val initializer: Statement,
override val pos: Pos,
@@ -130,7 +135,8 @@ class InstanceDelegatedInitStatement(
isAbstract = isAbstract,
isClosed = isClosed,
isOverride = isOverride,
isTransient = isTransient
isTransient = isTransient,
annotations = annotations
).apply {
delegate = finalDelegate
}
@@ -718,6 +718,7 @@ open class Scope(
isTransient: Boolean = false,
callSignature: CallSignature? = null,
typeDecl: TypeDecl? = null,
annotations: List<DeclAnnotation> = emptyList(),
fieldId: Int? = null,
methodId: Int? = null
): ObjRecord {
@@ -731,6 +732,7 @@ open class Scope(
isTransient = isTransient,
callSignature = callSignature,
typeDecl = typeDecl,
annotations = annotations,
memberName = name,
fieldId = fieldId,
methodId = methodId
@@ -27,6 +27,8 @@ import net.sergeych.lyng.bytecode.CmdVm
import net.sergeych.lyng.bytecode.BytecodeLambdaCallable
import net.sergeych.lyng.miniast.*
import net.sergeych.lyng.obj.*
import net.sergeych.lyng.serialization.ObjJsonClass
import net.sergeych.lyng.serialization.bindSerializationFormat
import net.sergeych.lyng.pacman.ImportManager
import net.sergeych.lyng.stdlib_included.complexLyng
import net.sergeych.lyng.stdlib_included.decimalLyng
@@ -949,11 +951,13 @@ class Script(
)
}
addPackage("lyng.serialization") {
it.addConstDoc(
name = "Lynon",
value = ObjLynonClass,
doc = "Lynon serialization utilities: encode/decode data structures to a portable binary/text form.",
type = type("lyng.Class")
it.bindSerializationFormat(
ObjLynonClass,
doc = "Lynon serialization utilities: encode/decode data structures to a portable binary format."
)
it.bindSerializationFormat(
ObjJsonClass,
doc = "Universal JSON serialization utilities with bidirectional Lyng object support."
)
}
addPackage("lyng.time") {
@@ -6360,7 +6360,8 @@ class BytecodeCompiler(
isMutable = stmt.isMutable,
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient
isTransient = stmt.isTransient,
annotationSpecs = stmt.annotationSpecs
)
)
} else {
@@ -6370,7 +6371,8 @@ class BytecodeCompiler(
isMutable = stmt.isMutable,
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient
isTransient = stmt.isTransient,
annotationSpecs = stmt.annotationSpecs
)
)
}
@@ -6397,6 +6399,7 @@ class BytecodeCompiler(
writeVisibility = stmt.writeVisibility,
typeDecl = stmt.typeDecl,
isTransient = stmt.isTransient,
annotationSpecs = stmt.annotationSpecs,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride,
@@ -6419,6 +6422,7 @@ class BytecodeCompiler(
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient,
annotationSpecs = stmt.annotationSpecs,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride,
@@ -6442,6 +6446,7 @@ class BytecodeCompiler(
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient,
annotationSpecs = stmt.annotationSpecs,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride,
@@ -6475,6 +6480,7 @@ class BytecodeCompiler(
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient,
annotations = stmt.annotations,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride
@@ -6497,6 +6503,7 @@ class BytecodeCompiler(
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient,
annotations = stmt.annotations,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride
@@ -6517,6 +6524,7 @@ class BytecodeCompiler(
visibility = stmt.visibility,
writeVisibility = stmt.writeVisibility,
isTransient = stmt.isTransient,
annotations = stmt.annotations,
isAbstract = stmt.isAbstract,
isClosed = stmt.isClosed,
isOverride = stmt.isOverride,
@@ -18,6 +18,7 @@
package net.sergeych.lyng.bytecode
import net.sergeych.lyng.ArgsDeclaration
import net.sergeych.lyng.ParsedDeclAnnotation
import net.sergeych.lyng.Pos
import net.sergeych.lyng.TypeDecl
import net.sergeych.lyng.Visibility
@@ -85,6 +86,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation>,
) : BytecodeConst()
data class ClassDelegatedDecl(
val name: String,
@@ -92,6 +94,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation>,
) : BytecodeConst()
data class ClassInstanceInitDecl(
val initStatement: Obj,
@@ -103,6 +106,7 @@ sealed class BytecodeConst {
val writeVisibility: Visibility?,
val typeDecl: TypeDecl?,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -116,6 +120,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -130,6 +135,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotationSpecs: List<ParsedDeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -143,6 +149,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotations: List<net.sergeych.lyng.DeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -153,6 +160,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotations: List<net.sergeych.lyng.DeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -164,6 +172,7 @@ sealed class BytecodeConst {
val visibility: Visibility,
val writeVisibility: Visibility?,
val isTransient: Boolean,
val annotations: List<net.sergeych.lyng.DeclAnnotation>,
val isAbstract: Boolean,
val isClosed: Boolean,
val isOverride: Boolean,
@@ -365,6 +365,7 @@ class BytecodeStatement private constructor(
stmt.initializer?.let { unwrapDeep(it) },
stmt.isDelegated,
stmt.isTransient,
stmt.annotationSpecs,
stmt.pos
)
}
@@ -385,6 +386,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotationSpecs,
stmt.fieldId,
stmt.initStatement?.let { unwrapDeep(it) },
stmt.pos
@@ -400,6 +402,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotationSpecs,
stmt.prop,
stmt.methodId,
stmt.initStatement?.let { unwrapDeep(it) },
@@ -416,6 +419,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotationSpecs,
stmt.methodId,
stmt.initStatement?.let { unwrapDeep(it) },
stmt.pos
@@ -431,6 +435,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotations,
stmt.isLateInitVal,
stmt.initializer?.let { unwrapDeep(it) },
stmt.pos
@@ -446,6 +451,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotations,
stmt.prop,
stmt.pos
)
@@ -461,6 +467,7 @@ class BytecodeStatement private constructor(
stmt.isClosed,
stmt.isOverride,
stmt.isTransient,
stmt.annotations,
stmt.accessTypeLabel,
unwrapDeep(stmt.initializer),
stmt.pos
@@ -2805,6 +2805,7 @@ class CmdDeclClassField(internal val constId: Int, internal val slot: Int) : Cmd
val decl = frame.fn.constants[constId] as? BytecodeConst.ClassFieldDecl
?: error("DECL_CLASS_FIELD expects ClassFieldDecl at $constId")
val scope = frame.ensureScope()
val annotations = decl.annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("class field init requires class scope")
val value = frame.slotToObj(slot).byValueCopy()
@@ -2815,7 +2816,8 @@ class CmdDeclClassField(internal val constId: Int, internal val slot: Int) : Cmd
decl.visibility,
decl.writeVisibility,
Pos.builtIn,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = annotations
)
scope.addItem(
decl.name,
@@ -2824,7 +2826,8 @@ class CmdDeclClassField(internal val constId: Int, internal val slot: Int) : Cmd
decl.visibility,
decl.writeVisibility,
recordType = ObjRecord.Type.Field,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = annotations
)
return
}
@@ -2835,6 +2838,7 @@ class CmdDeclClassDelegated(internal val constId: Int, internal val slot: Int) :
val decl = frame.fn.constants[constId] as? BytecodeConst.ClassDelegatedDecl
?: error("DECL_CLASS_DELEGATED expects ClassDelegatedDecl at $constId")
val scope = frame.ensureScope()
val annotations = decl.annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("class delegated init requires class scope")
val initValue = frame.slotToObj(slot)
@@ -2857,7 +2861,8 @@ class CmdDeclClassDelegated(internal val constId: Int, internal val slot: Int) :
decl.writeVisibility,
Pos.builtIn,
isTransient = decl.isTransient,
type = ObjRecord.Type.Delegated
type = ObjRecord.Type.Delegated,
annotations = annotations
).apply {
delegate = finalDelegate
}
@@ -2868,7 +2873,8 @@ class CmdDeclClassDelegated(internal val constId: Int, internal val slot: Int) :
decl.visibility,
decl.writeVisibility,
recordType = ObjRecord.Type.Delegated,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = annotations
).apply {
delegate = finalDelegate
}
@@ -2895,6 +2901,7 @@ class CmdDeclClassInstanceField(internal val constId: Int, internal val slot: In
val decl = frame.fn.constants[constId] as? BytecodeConst.ClassInstanceFieldDecl
?: error("DECL_CLASS_INSTANCE_FIELD expects ClassInstanceFieldDecl at $constId")
val scope = frame.ensureScope()
val annotations = decl.annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("class instance field requires class scope")
cls.createField(
@@ -2911,7 +2918,8 @@ class CmdDeclClassInstanceField(internal val constId: Int, internal val slot: In
isTransient = decl.isTransient,
typeDecl = decl.typeDecl,
type = ObjRecord.Type.Field,
fieldId = decl.fieldId
fieldId = decl.fieldId,
annotations = annotations
)
if (!decl.isAbstract) {
decl.initStatement?.let { cls.instanceInitializers += it }
@@ -2926,6 +2934,7 @@ class CmdDeclClassInstanceProperty(internal val constId: Int, internal val slot:
val decl = frame.fn.constants[constId] as? BytecodeConst.ClassInstancePropertyDecl
?: error("DECL_CLASS_INSTANCE_PROPERTY expects ClassInstancePropertyDecl at $constId")
val scope = frame.ensureScope()
val annotations = decl.annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("class instance property requires class scope")
cls.addProperty(
@@ -2938,7 +2947,8 @@ class CmdDeclClassInstanceProperty(internal val constId: Int, internal val slot:
isOverride = decl.isOverride,
pos = decl.pos,
prop = decl.prop,
methodId = decl.methodId
methodId = decl.methodId,
annotations = annotations
)
if (!decl.isAbstract) {
decl.initStatement?.let { cls.instanceInitializers += it }
@@ -2953,6 +2963,7 @@ class CmdDeclClassInstanceDelegated(internal val constId: Int, internal val slot
val decl = frame.fn.constants[constId] as? BytecodeConst.ClassInstanceDelegatedDecl
?: error("DECL_CLASS_INSTANCE_DELEGATED expects ClassInstanceDelegatedDecl at $constId")
val scope = frame.ensureScope()
val annotations = decl.annotationSpecs.evaluateDeclAnnotations(scope)
val cls = scope.thisObj as? ObjClass
?: scope.raiseIllegalState("class instance delegated requires class scope")
cls.createField(
@@ -2968,7 +2979,8 @@ class CmdDeclClassInstanceDelegated(internal val constId: Int, internal val slot
isOverride = decl.isOverride,
isTransient = decl.isTransient,
type = ObjRecord.Type.Delegated,
methodId = decl.methodId
methodId = decl.methodId,
annotations = annotations
)
if (!decl.isAbstract) {
decl.initStatement?.let { cls.instanceInitializers += it }
@@ -2994,7 +3006,8 @@ class CmdDeclInstanceField(internal val constId: Int, internal val slot: Int) :
isAbstract = decl.isAbstract,
isClosed = decl.isClosed,
isOverride = decl.isOverride,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = decl.annotations
)
if (slot >= frame.fn.scopeSlotCount) {
val localIndex = slot - frame.fn.scopeSlotCount
@@ -3023,7 +3036,8 @@ class CmdDeclInstanceProperty(internal val constId: Int, internal val slot: Int)
isAbstract = decl.isAbstract,
isClosed = decl.isClosed,
isOverride = decl.isOverride,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = decl.annotations
)
if (slot >= frame.fn.scopeSlotCount) {
val localIndex = slot - frame.fn.scopeSlotCount
@@ -3076,7 +3090,8 @@ class CmdDeclInstanceDelegated(internal val constId: Int, internal val slot: Int
isAbstract = decl.isAbstract,
isClosed = decl.isClosed,
isOverride = decl.isOverride,
isTransient = decl.isTransient
isTransient = decl.isTransient,
annotations = decl.annotations
).apply {
delegate = finalDelegate
}
@@ -3705,9 +3720,26 @@ class CmdGetClassScope(
decl = declared
break
}
val resolved = rec ?: scope.raiseSymbolNotFound(name)
val declClass = decl ?: cls
val resolvedRec = cls.resolveRecord(scope, resolved, name, declClass)
val resolvedRec = if (rec != null) {
val declClass = decl ?: cls
cls.resolveRecord(scope, rec, name, declClass)
} else {
val metaRec = cls.objClass.getInstanceMemberOrNull(name)
if (metaRec == null || metaRec.isAbstract) {
scope.raiseSymbolNotFound(name)
}
val declClass = metaRec.declaringClass ?: cls.objClass
val resolved = cls.resolveRecord(scope, metaRec, name, declClass)
if (resolved.type == ObjRecord.Type.Fun) {
resolved.copy(
value = ObjExternCallable.fromBridge {
resolved.value.invoke(scope, cls, args, declClass)
}
)
} else {
resolved
}
}
val value = resolvedRec.value
frame.storeObjResult(dst, value)
return
@@ -24,6 +24,9 @@ import net.sergeych.lyng.parseLyng
/** Extension that converts a [Pos] (line/column) into absolute character offset in the [Source] text. */
fun Source.offsetOf(pos: Pos): Int {
if (lines.isEmpty()) return 0
if (pos.line < 0) return 0
if (pos.line >= lines.size) return text.length
var off = 0
// Sum full preceding lines + one '\n' per line (lines[] were created by String.lines())
var i = 0
@@ -31,8 +34,8 @@ fun Source.offsetOf(pos: Pos): Int {
off += lines[i].length + 1 // assume \n as separator
i++
}
off += pos.column
return off
off += pos.column.coerceIn(0, lines[pos.line].length)
return off.coerceAtMost(text.length)
}
private val reservedIdKeywords = setOf("constructor", "property")
@@ -28,6 +28,23 @@ import net.sergeych.lynon.LynonType
// Simple id generator for class identities (not thread-safe; fine for scripts)
private object ClassIdGen { var c: Long = 1L; fun nextId(): Long = c++ }
private fun DeclAnnotation.toObj(): Obj {
val namedArgs = linkedMapOf<Obj, Obj>()
for ((k, v) in named) {
namedArgs[ObjString(k)] = v
}
return ObjMap(
linkedMapOf(
ObjString("name") to ObjString(name),
ObjString("positional") to ObjImmutableList(positional),
ObjString("named") to ObjMap(namedArgs)
)
)
}
private fun annotationListObj(annotations: List<DeclAnnotation>): Obj =
ObjImmutableList(annotations.map { it.toObj() })
val ObjClassType by lazy {
object : ObjClass("Class") {
override suspend fun deserialize(scope: Scope, decoder: LynonDecoder, lynonType: LynonType?): Obj {
@@ -98,6 +115,30 @@ val ObjClassType by lazy {
val rec = cls.getInstanceMemberOrNull(name)
rec?.value ?: ObjNull
}
addFnDoc(
name = "getConstructorAnnotations",
doc = "Return preserved annotations for a constructor parameter by name as descriptor maps with fields `name`, `positional`, and `named`.",
params = listOf(ParamDoc("name", type("lyng.String"))),
returns = TypeGenericDoc(type("lyng.List"), listOf(type("lyng.Map"))),
moduleName = "lyng.stdlib"
) {
val cls = thisAs<ObjClass>()
val name = requiredArg<ObjString>(0).value
val param = cls.constructorMeta?.params?.firstOrNull { it.name == name }
annotationListObj(param?.annotations ?: emptyList())
}
addFnDoc(
name = "getMemberAnnotations",
doc = "Return preserved annotations for a member by name as descriptor maps with fields `name`, `positional`, and `named`.",
params = listOf(ParamDoc("name", type("lyng.String"))),
returns = TypeGenericDoc(type("lyng.List"), listOf(type("lyng.Map"))),
moduleName = "lyng.stdlib"
) {
val cls = thisAs<ObjClass>()
val name = requiredArg<ObjString>(0).value
val rec = cls.getInstanceMemberOrNull(name) ?: cls.classScope?.objects?.get(name)
annotationListObj(rec?.annotations ?: emptyList())
}
}
}
@@ -119,6 +160,7 @@ open class ObjClass(
var isAbstract: Boolean = false
var isClosed: Boolean = false
var isSingletonObject: Boolean = false
var logicalPackageNameOverride: String? = null
// Stable identity and simple structural version for PICs
@@ -850,6 +892,7 @@ open class ObjClass(
methodId: Int? = null,
typeDecl: net.sergeych.lyng.TypeDecl? = null,
callSignature: net.sergeych.lyng.CallSignature? = null,
annotations: List<DeclAnnotation> = emptyList(),
): ObjRecord {
// Validation of override rules: only for non-system declarations
var existing: ObjRecord? = null
@@ -952,6 +995,7 @@ open class ObjClass(
type = type,
callSignature = callSignature,
typeDecl = typeDecl,
annotations = annotations,
memberName = name,
fieldId = effectiveFieldId,
methodId = effectiveMethodId
@@ -978,7 +1022,8 @@ open class ObjClass(
type: ObjRecord.Type = ObjRecord.Type.Field,
fieldId: Int? = null,
methodId: Int? = null,
callSignature: net.sergeych.lyng.CallSignature? = null
callSignature: net.sergeych.lyng.CallSignature? = null,
annotations: List<DeclAnnotation> = emptyList()
): ObjRecord {
initClassScope()
val existing = classScope!!.objects[name]
@@ -1020,6 +1065,7 @@ open class ObjClass(
recordType = type,
isTransient = isTransient,
callSignature = callSignature,
annotations = annotations,
fieldId = effectiveFieldId,
methodId = effectiveMethodId
)
@@ -1066,7 +1112,8 @@ open class ObjClass(
isOverride: Boolean = false,
pos: Pos = Pos.builtIn,
prop: ObjProperty? = null,
methodId: Int? = null
methodId: Int? = null,
annotations: List<DeclAnnotation> = emptyList()
) {
val g = getter?.let { ObjExternCallable.fromBridge { it() } }
val s = setter?.let { ObjExternCallable.fromBridge { it(requiredArg(0)); ObjVoid } }
@@ -1075,7 +1122,8 @@ open class ObjClass(
name, finalProp, false, visibility, writeVisibility, pos, declaringClass,
isAbstract = isAbstract, isClosed = isClosed, isOverride = isOverride,
type = ObjRecord.Type.Property,
methodId = methodId
methodId = methodId,
annotations = annotations
)
}
@@ -16,6 +16,7 @@
*/
package net.sergeych.lyng.obj
import net.sergeych.lyng.DeclAnnotation
import net.sergeych.lyng.Scope
import net.sergeych.lyng.Visibility
@@ -40,6 +41,7 @@ data class ObjRecord(
var receiver: Obj? = null,
val callSignature: net.sergeych.lyng.CallSignature? = null,
val typeDecl: net.sergeych.lyng.TypeDecl? = null,
val annotations: List<DeclAnnotation> = emptyList(),
val memberName: String? = null,
val fieldId: Int? = null,
val methodId: Int? = null,
@@ -0,0 +1,742 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.serialization
import kotlinx.datetime.LocalDate
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonNull
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.booleanOrNull
import kotlinx.serialization.json.doubleOrNull
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.longOrNull
import net.sergeych.lyng.Arguments
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Pos
import net.sergeych.lyng.Scope
import net.sergeych.lyng.TypeDecl
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjBitBuffer
import net.sergeych.lyng.obj.ObjBool
import net.sergeych.lyng.obj.ObjBuffer
import net.sergeych.lyng.obj.ObjClass
import net.sergeych.lyng.obj.ObjDate
import net.sergeych.lyng.obj.ObjDateTime
import net.sergeych.lyng.obj.ObjEnumClass
import net.sergeych.lyng.obj.ObjEnumEntry
import net.sergeych.lyng.obj.ObjException
import net.sergeych.lyng.obj.ObjImmutableList
import net.sergeych.lyng.obj.ObjImmutableMap
import net.sergeych.lyng.obj.ObjImmutableSet
import net.sergeych.lyng.obj.ObjInstance
import net.sergeych.lyng.obj.ObjInt
import net.sergeych.lyng.obj.ObjInstant
import net.sergeych.lyng.obj.ObjList
import net.sergeych.lyng.obj.ObjMap
import net.sergeych.lyng.obj.ObjNull
import net.sergeych.lyng.obj.ObjReal
import net.sergeych.lyng.obj.ObjRecord
import net.sergeych.lyng.obj.ObjSet
import net.sergeych.lyng.obj.ObjString
import net.sergeych.lyng.obj.ObjTypeExpr
import net.sergeych.lyng.obj.ObjVoid
import net.sergeych.lyng.obj.matchesTypeDecl
import net.sergeych.lyng.requireExactCount
import net.sergeych.lyng.requireScope
import net.sergeych.lynon.BitArray
import net.sergeych.mp_tools.decodeBase64Url
import net.sergeych.mp_tools.encodeToBase64Url
import kotlin.time.Instant
private const val TYPE_KEY = "@lyng"
private const val VALUE_KEY = "value"
private const val ITEMS_KEY = "items"
private const val ENTRIES_KEY = "entries"
private const val CLASS_KEY = "class"
private const val NAME_KEY = "name"
private const val ARGS_KEY = "args"
private const val VARS_KEY = "vars"
private const val BASE64_KEY = "base64"
private const val LAST_BYTE_BITS_KEY = "lastByteBits"
private const val MESSAGE_KEY = "message"
private const val EXTRA_DATA_KEY = "extraData"
private const val STACK_TRACE_KEY = "stackTrace"
object ObjJsonClass : ObjSerializationFormatClass("Json") {
init {
addClassFn("encodeAs") {
requireExactCount(2)
val targetType = typeDeclFromJsonTarget(requireScope(), args[0])
ObjString(encodeToJsonElement(requireScope(), args[1], targetType).toString())
}
addClassFn("decodeAs") {
requireExactCount(2)
val scope = requireScope()
val targetType = typeDeclFromJsonTarget(scope, args[0])
val text = when (val encoded = args[1]) {
is ObjString -> encoded.value
else -> encoded.toString(scope).value
}
decodeFromJsonElement(scope, Json.parseToJsonElement(text), targetType)
}
}
override suspend fun encodeValue(scope: Scope, value: Obj): Obj =
ObjString(encodeToJsonElement(scope, value).toString())
override suspend fun decodeValue(scope: Scope, encoded: Obj): Obj {
val text = when (encoded) {
is ObjString -> encoded.value
else -> encoded.toString(scope).value
}
return decodeFromJsonElement(scope, Json.parseToJsonElement(text))
}
suspend fun encodeToJsonElement(scope: Scope, value: Obj, expectedType: TypeDecl? = null): JsonElement =
UniversalJsonCodec.encode(scope, value, expectedType)
suspend fun decodeFromJsonElement(scope: Scope, element: JsonElement, expectedType: TypeDecl? = null): Obj =
UniversalJsonCodec.decode(scope, element, expectedType)
}
suspend fun Obj.toUniversalJsonElement(scope: Scope = Scope()): JsonElement =
ObjJsonClass.encodeToJsonElement(scope, this)
suspend fun decodeUniversalJsonElement(element: JsonElement, scope: Scope = Scope()): Obj =
ObjJsonClass.decodeFromJsonElement(scope, element)
private fun typeDeclFromJsonTarget(scope: Scope, target: Obj): TypeDecl = when (target) {
is ObjTypeExpr -> target.typeDecl
is ObjClass -> TypeDecl.Simple(target.className, false)
is ObjInstance -> TypeDecl.Simple(target.objClass.className, false)
is ObjString -> TypeDecl.Simple(target.value, false)
else -> scope.raiseClassCastError("Json.encodeAs/decodeAs expects a class or type expression")
}
private object UniversalJsonCodec {
suspend fun encode(scope: Scope, value: Obj, expectedType: TypeDecl? = null): JsonElement {
if (expectedType != null) {
encodeWithExpectedType(scope, value, expectedType)?.let { return it }
}
return encodeCanonical(scope, value)
}
suspend fun decode(scope: Scope, element: JsonElement, expectedType: TypeDecl? = null): Obj {
if (expectedType != null) {
if (element is JsonObject && TYPE_KEY in element) {
return ensureMatchesExpectedType(scope, decodeCanonical(scope, element), expectedType)
}
decodeWithExpectedType(scope, element, expectedType)?.let {
return ensureMatchesExpectedType(scope, it, expectedType)
}
}
return decodeCanonical(scope, element)
}
private suspend fun encodeCanonical(scope: Scope, value: Obj): JsonElement = when (value) {
ObjVoid -> tagged("void")
ObjNull -> JsonNull
is ObjBool -> JsonPrimitive(value.value)
is ObjInt -> JsonPrimitive(value.value)
is ObjReal -> if (value.value.isFinite()) {
JsonPrimitive(value.value)
} else {
tagged("real", VALUE_KEY to JsonPrimitive(value.value.toString()))
}
is ObjString -> JsonPrimitive(value.value)
is ObjDate -> tagged("date", VALUE_KEY to JsonPrimitive(value.date.toString()))
is ObjInstant -> tagged("instant", VALUE_KEY to JsonPrimitive(value.instant.toString()))
is ObjDateTime -> tagged("dateTime", VALUE_KEY to JsonPrimitive(value.toRFC3339()))
is ObjBuffer -> tagged("buffer", BASE64_KEY to JsonPrimitive(value.base64))
is ObjBitBuffer -> tagged(
"bitBuffer",
BASE64_KEY to JsonPrimitive(value.bitArray.asUByteArray().asByteArray().encodeToBase64Url()),
LAST_BYTE_BITS_KEY to JsonPrimitive(value.bitArray.lastByteBits)
)
is ObjImmutableList -> tagged("immutableList", ITEMS_KEY to JsonArray(value.toMutableList().map { encodeCanonical(scope, it) }))
is ObjList -> JsonArray(value.list.map { encodeCanonical(scope, it) })
is ObjImmutableSet -> tagged("immutableSet", ITEMS_KEY to JsonArray(value.toMutableSet().map { encodeCanonical(scope, it) }))
is ObjSet -> tagged("set", ITEMS_KEY to JsonArray(value.set.map { encodeCanonical(scope, it) }))
is ObjImmutableMap -> tagged("immutableMap", ENTRIES_KEY to encodeEntries(scope, value.map.entries.map { it.toPair() }))
is ObjMap -> encodeCanonicalMap(scope, value)
is ObjEnumEntry -> tagged(
"enum",
CLASS_KEY to JsonPrimitive(value.objClass.className),
NAME_KEY to JsonPrimitive(value.name.value)
)
is ObjException -> tagged(
"exception",
CLASS_KEY to JsonPrimitive(value.exceptionClass.className),
MESSAGE_KEY to encodeCanonical(scope, value.message),
EXTRA_DATA_KEY to encodeCanonical(scope, value.extraData),
STACK_TRACE_KEY to encodeCanonical(scope, value.getStackTrace())
)
is ObjClass -> tagged("class", NAME_KEY to JsonPrimitive(value.className))
is ObjInstance -> if (value.objClass.isSingletonObject) {
encodeCanonicalSingletonObject(scope, value)
} else {
encodeCanonicalInstance(scope, value)
}
else -> scope.raiseNotImplemented("Json.encode can't serialize ${value.objClass.className}")
}
private suspend fun decodeCanonical(scope: Scope, element: JsonElement): Obj = when (element) {
JsonNull -> ObjNull
is JsonPrimitive -> decodePrimitive(element)
is JsonArray -> ObjList(element.map { decodeCanonical(scope, it) }.toMutableList())
is JsonObject -> decodeCanonicalObject(scope, element)
}
private suspend fun encodeWithExpectedType(scope: Scope, value: Obj, expectedType: TypeDecl): JsonElement? {
if (value === ObjNull) return JsonNull
when (value) {
is ObjBool -> return JsonPrimitive(value.value)
is ObjInt -> return JsonPrimitive(value.value)
is ObjReal -> if (value.value.isFinite()) return JsonPrimitive(value.value)
is ObjString -> return JsonPrimitive(value.value)
is ObjDate -> if (isExpectedExactClass(scope, expectedType, value.objClass)) return JsonPrimitive(value.date.toString())
is ObjInstant -> if (isExpectedExactClass(scope, expectedType, value.objClass)) return JsonPrimitive(value.instant.toString())
is ObjDateTime -> if (isExpectedExactClass(scope, expectedType, value.objClass)) return JsonPrimitive(value.toRFC3339())
is ObjBuffer -> if (isExpectedExactClass(scope, expectedType, value.objClass)) return JsonPrimitive(value.base64)
is ObjBitBuffer -> if (isExpectedExactClass(scope, expectedType, value.objClass)) {
return JsonObject(
linkedMapOf(
BASE64_KEY to JsonPrimitive(value.bitArray.asUByteArray().asByteArray().encodeToBase64Url()),
LAST_BYTE_BITS_KEY to JsonPrimitive(value.bitArray.lastByteBits)
)
)
}
is ObjEnumEntry -> if (isExpectedExactClass(scope, expectedType, value.objClass)) {
return JsonPrimitive(value.name.value)
}
is ObjList -> if (expectedBaseName(expectedType) == "List") {
return JsonArray(value.list.map { encode(scope, it, expectedElementType(expectedType)) })
}
is ObjImmutableList -> if (expectedBaseName(expectedType) == "ImmutableList") {
return JsonArray(value.toMutableList().map { encode(scope, it, expectedElementType(expectedType)) })
}
is ObjSet -> if (expectedBaseName(expectedType) == "Set") {
return JsonArray(value.set.map { encode(scope, it, expectedElementType(expectedType)) })
}
is ObjImmutableSet -> if (expectedBaseName(expectedType) == "ImmutableSet") {
return JsonArray(value.toMutableSet().map { encode(scope, it, expectedElementType(expectedType)) })
}
is ObjMap -> if (expectedBaseName(expectedType) == "Map") {
return encodeTypedMap(scope, value.map, expectedKeyType(expectedType), expectedValueType(expectedType))
}
is ObjImmutableMap -> if (expectedBaseName(expectedType) == "ImmutableMap") {
return encodeTypedMap(scope, value.map, expectedKeyType(expectedType), expectedValueType(expectedType))
}
is ObjInstance -> if (isExpectedExactClass(scope, expectedType, value.objClass)) {
return if (value.objClass.isSingletonObject) encodeTypedSingletonObject(scope, value) else encodeTypedInstance(scope, value)
}
else -> Unit
}
return null
}
private suspend fun decodeWithExpectedType(scope: Scope, element: JsonElement, expectedType: TypeDecl): Obj? = when (element) {
JsonNull -> ObjNull
is JsonPrimitive -> decodePrimitiveWithExpectedType(scope, element, expectedType)
is JsonArray -> decodeArrayWithExpectedType(scope, element, expectedType)
is JsonObject -> decodeObjectWithExpectedType(scope, element, expectedType)
}
private suspend fun encodeCanonicalMap(scope: Scope, value: ObjMap): JsonElement {
if (value.map.keys.all { it is ObjString } && TYPE_KEY !in value.map.keys.map { (it as ObjString).value }) {
return JsonObject(
value.map.entries.associate { (k, v) ->
(k as ObjString).value to encodeCanonical(scope, v)
}
)
}
return tagged("map", ENTRIES_KEY to encodeEntries(scope, value.map.entries.map { it.toPair() }))
}
private suspend fun encodeTypedMap(
scope: Scope,
map: Map<Obj, Obj>,
keyType: TypeDecl?,
valueType: TypeDecl?
): JsonElement {
val stringKeys = keyType != null && expectedBaseName(keyType) == "String"
if (stringKeys && map.keys.all { it is ObjString } && TYPE_KEY !in map.keys.map { (it as ObjString).value }) {
return JsonObject(
map.entries.associate { (k, v) ->
(k as ObjString).value to encode(scope, v, valueType)
}
)
}
return JsonArray(
map.entries.map { (k, v) ->
JsonArray(listOf(encode(scope, k, keyType), encode(scope, v, valueType)))
}
)
}
private suspend fun encodeEntries(scope: Scope, entries: List<Pair<Obj, Obj>>): JsonArray =
JsonArray(entries.map { (k, v) -> JsonArray(listOf(encodeCanonical(scope, k), encodeCanonical(scope, v))) })
private suspend fun encodeCanonicalInstance(scope: Scope, value: ObjInstance): JsonElement {
val meta = value.objClass.constructorMeta
?: scope.raiseError("can't serialize non-serializable object (no constructor meta)")
val args = linkedMapOf<String, JsonElement>()
for (param in meta.params) {
if (!param.isTransient) {
args[param.name] = encodeCanonical(scope, value.readField(scope, param.name).value)
}
}
val vars = linkedMapOf<String, JsonElement>()
for ((key, record) in value.serializingVars) {
vars[key.substringAfterLast("::")] = encodeCanonical(scope, record.value)
}
return tagged(
"instance",
CLASS_KEY to JsonPrimitive(value.objClass.className),
ARGS_KEY to JsonObject(args),
VARS_KEY to JsonObject(vars)
)
}
private suspend fun encodeTypedInstance(scope: Scope, value: ObjInstance): JsonObject {
val meta = value.objClass.constructorMeta
?: scope.raiseError("can't serialize non-serializable object (no constructor meta)")
val fields = linkedMapOf<String, JsonElement>()
for (param in meta.params) {
if (!param.isTransient) {
fields[param.name] = encode(scope, value.readField(scope, param.name).value, param.type)
}
}
for ((key, record) in value.serializingVars) {
fields[key.substringAfterLast("::")] = encode(scope, record.value, record.typeDecl)
}
return JsonObject(fields)
}
private suspend fun encodeCanonicalSingletonObject(scope: Scope, value: ObjInstance): JsonElement {
val vars = linkedMapOf<String, JsonElement>()
for ((key, record) in value.serializingVars) {
vars[key.substringAfterLast("::")] = encodeCanonical(scope, record.value)
}
return tagged(
"object",
NAME_KEY to JsonPrimitive(value.objClass.className),
VARS_KEY to JsonObject(vars)
)
}
private suspend fun encodeTypedSingletonObject(scope: Scope, value: ObjInstance): JsonObject {
val vars = linkedMapOf<String, JsonElement>()
for ((key, record) in value.serializingVars) {
vars[key.substringAfterLast("::")] = encode(scope, record.value, record.typeDecl)
}
return JsonObject(vars)
}
private suspend fun decodeCanonicalObject(scope: Scope, element: JsonObject): Obj {
val tag = element[TYPE_KEY]?.jsonPrimitive?.content
if (tag == null) {
val map = linkedMapOf<Obj, Obj>()
for ((k, v) in element) {
map[ObjString(k)] = decodeCanonical(scope, v)
}
return ObjMap(map.toMutableMap())
}
return when (tag) {
"void" -> ObjVoid
"real" -> decodeTaggedReal(element)
"date" -> ObjDate(LocalDate.parse(requiredString(element, VALUE_KEY)))
"instant" -> ObjInstant(Instant.parse(requiredString(element, VALUE_KEY)))
"dateTime" -> ObjDateTime.type.invokeInstanceMethod(scope, "parseRFC3339", ObjString(requiredString(element, VALUE_KEY)))
"buffer" -> ObjBuffer(requiredString(element, BASE64_KEY).decodeBase64Url().asUByteArray())
"bitBuffer" -> ObjBitBuffer(
BitArray(
requiredString(element, BASE64_KEY).decodeBase64Url().asUByteArray(),
requiredInt(element, LAST_BYTE_BITS_KEY)
)
)
"immutableList" -> ObjImmutableList(requiredArray(element, ITEMS_KEY).map { decodeCanonical(scope, it) })
"set" -> ObjSet(requiredArray(element, ITEMS_KEY).map { decodeCanonical(scope, it) }.toMutableSet())
"immutableSet" -> ObjImmutableSet(requiredArray(element, ITEMS_KEY).map { decodeCanonical(scope, it) })
"map" -> decodeCanonicalMap(scope, requiredArray(element, ENTRIES_KEY), mutable = true)
"immutableMap" -> decodeCanonicalMap(scope, requiredArray(element, ENTRIES_KEY), mutable = false)
"class" -> resolveClass(scope, requiredString(element, NAME_KEY))
"enum" -> decodeCanonicalEnum(scope, element)
"instance" -> decodeCanonicalInstance(scope, element)
"object" -> decodeCanonicalSingletonObject(scope, element)
"exception" -> decodeCanonicalException(scope, element)
else -> scope.raiseIllegalArgument("unknown Json type tag '$tag'")
}
}
private fun decodePrimitive(element: JsonPrimitive): Obj {
element.booleanOrNull?.let { return ObjBool(it) }
if (element.isString) return ObjString(element.content)
val raw = element.content
return if (!raw.contains('.') && !raw.contains('e', ignoreCase = true)) {
element.longOrNull?.let { ObjInt.of(it) } ?: ObjReal(raw.toDouble())
} else {
ObjReal(element.doubleOrNull ?: raw.toDouble())
}
}
private suspend fun decodePrimitiveWithExpectedType(scope: Scope, element: JsonPrimitive, expectedType: TypeDecl): Obj? {
val expectedClass = expectedExactClass(scope, expectedType)
val baseName = expectedBaseName(expectedType)
return when {
expectedClass is ObjEnumClass && element.isString ->
expectedClass.invokeInstanceMethod(scope, "valueOf", ObjString(element.content))
baseName == "Bool" -> element.booleanOrNull?.let { ObjBool(it) }
baseName == "Int" -> if (!element.isString) element.longOrNull?.let { ObjInt.of(it) } else null
baseName == "Real" -> decodeExpectedReal(element)
baseName == "String" -> if (element.isString) ObjString(element.content) else null
baseName == "Date" && element.isString -> ObjDate(LocalDate.parse(element.content))
baseName == "Instant" && element.isString -> ObjInstant(Instant.parse(element.content))
baseName == "DateTime" && element.isString ->
ObjDateTime.type.invokeInstanceMethod(scope, "parseRFC3339", ObjString(element.content))
baseName == "Buffer" && element.isString -> ObjBuffer(element.content.decodeBase64Url().asUByteArray())
else -> decodePrimitive(element)
}
}
private fun decodeExpectedReal(element: JsonPrimitive): ObjReal? {
if (element.isString) {
return when (element.content) {
"NaN" -> ObjReal(Double.NaN)
"Infinity" -> ObjReal(Double.POSITIVE_INFINITY)
"-Infinity" -> ObjReal(Double.NEGATIVE_INFINITY)
else -> null
}
}
val raw = element.content
return ObjReal((element.doubleOrNull ?: raw.toDouble()))
}
private fun decodeTaggedReal(element: JsonObject): ObjReal {
val raw = requiredString(element, VALUE_KEY)
val value = when (raw) {
"NaN" -> Double.NaN
"Infinity" -> Double.POSITIVE_INFINITY
"-Infinity" -> Double.NEGATIVE_INFINITY
else -> raw.toDouble()
}
return ObjReal(value)
}
private suspend fun decodeArrayWithExpectedType(scope: Scope, element: JsonArray, expectedType: TypeDecl): Obj? {
val itemType = expectedElementType(expectedType)
return when (expectedBaseName(expectedType)) {
"List" -> ObjList(element.map { decode(scope, it, itemType) }.toMutableList())
"ImmutableList" -> ObjImmutableList(element.map { decode(scope, it, itemType) })
"Set" -> ObjSet(element.map { decode(scope, it, itemType) }.toMutableSet())
"ImmutableSet" -> ObjImmutableSet(element.map { decode(scope, it, itemType) })
"Map" -> decodeTypedMap(scope, element, mutable = true, keyType = expectedKeyType(expectedType), valueType = expectedValueType(expectedType))
"ImmutableMap" -> decodeTypedMap(scope, element, mutable = false, keyType = expectedKeyType(expectedType), valueType = expectedValueType(expectedType))
else -> null
}
}
private suspend fun decodeObjectWithExpectedType(scope: Scope, element: JsonObject, expectedType: TypeDecl): Obj? {
return when (expectedBaseName(expectedType)) {
"Map" -> decodeTypedMapObject(scope, element, mutable = true, valueType = expectedValueType(expectedType))
"ImmutableMap" -> decodeTypedMapObject(scope, element, mutable = false, valueType = expectedValueType(expectedType))
"BitBuffer" -> {
val base64 = element[BASE64_KEY]?.jsonPrimitive?.content ?: return null
val bits = element[LAST_BYTE_BITS_KEY]?.jsonPrimitive?.content?.toInt() ?: return null
ObjBitBuffer(BitArray(base64.decodeBase64Url().asUByteArray(), bits))
}
else -> {
val klass = expectedExactClass(scope, expectedType) ?: return null
when {
klass.isSingletonObject -> decodeTypedSingletonObject(scope, klass, element)
klass is ObjEnumClass -> null
else -> decodeTypedInstance(scope, klass, element)
}
}
}
}
private suspend fun decodeCanonicalMap(scope: Scope, entries: JsonArray, mutable: Boolean): Obj {
val pairs = entries.map { item ->
val pair = item as? JsonArray ?: scope.raiseIllegalArgument("map entry must be a JSON array")
if (pair.size != 2) scope.raiseIllegalArgument("map entry must contain exactly 2 items")
decodeCanonical(scope, pair[0]) to decodeCanonical(scope, pair[1])
}
return if (mutable) ObjMap(pairs.toMap().toMutableMap()) else ObjImmutableMap(pairs.toMap())
}
private suspend fun decodeTypedMap(
scope: Scope,
entries: JsonArray,
mutable: Boolean,
keyType: TypeDecl?,
valueType: TypeDecl?
): Obj {
val pairs = entries.map { item ->
val pair = item as? JsonArray ?: scope.raiseIllegalArgument("map entry must be a JSON array")
if (pair.size != 2) scope.raiseIllegalArgument("map entry must contain exactly 2 items")
decode(scope, pair[0], keyType) to decode(scope, pair[1], valueType)
}
return if (mutable) ObjMap(pairs.toMap().toMutableMap()) else ObjImmutableMap(pairs.toMap())
}
private suspend fun decodeTypedMapObject(
scope: Scope,
element: JsonObject,
mutable: Boolean,
valueType: TypeDecl?
): Obj {
val map = linkedMapOf<Obj, Obj>()
for ((k, v) in element) {
map[ObjString(k)] = decode(scope, v, valueType)
}
return if (mutable) ObjMap(map.toMutableMap()) else ObjImmutableMap(map)
}
private suspend fun decodeCanonicalEnum(scope: Scope, element: JsonObject): Obj {
val klass = resolveClass(scope, requiredString(element, CLASS_KEY))
if (klass !is ObjEnumClass) scope.raiseClassCastError("${klass.className} is not an enum")
return klass.invokeInstanceMethod(scope, "valueOf", ObjString(requiredString(element, NAME_KEY)))
}
private suspend fun decodeCanonicalInstance(scope: Scope, element: JsonObject): Obj {
val klass = resolveClass(scope, requiredString(element, CLASS_KEY))
return decodeCanonicalInstanceWithClass(scope, klass, requiredObject(element, ARGS_KEY), requiredObject(element, VARS_KEY))
}
private suspend fun decodeTypedInstance(scope: Scope, klass: ObjClass, element: JsonObject): Obj {
val meta = klass.constructorMeta
?: scope.raiseError("can't deserialize ${klass.className} from Json: no constructor meta")
val namedArgs = linkedMapOf<String, Obj>()
for (param in meta.params) {
if (param.isTransient) continue
val encoded = element[param.name]
if (encoded == null) {
if (param.defaultValue == null && !param.type.isNullable) {
scope.raiseIllegalArgument("missing constructor field '${param.name}' for ${klass.className}")
}
} else {
namedArgs[param.name] = decode(scope, encoded, param.type)
}
}
val callScope = scope.createChildScope(args = Arguments(list = emptyList(), named = namedArgs))
val instance = klass.callOn(callScope)
if (instance is ObjInstance) {
val ctorNames = meta.params.map { it.name }.toSet()
for ((name, encoded) in element) {
if (name in ctorNames) continue
val target = resolveSerializableVar(instance, name)
?: scope.raiseIllegalArgument("unknown serializable field '${klass.className}.$name'")
target.value = decode(scope, encoded, target.typeDecl)
}
}
return instance
}
private suspend fun decodeCanonicalInstanceWithClass(
scope: Scope,
klass: ObjClass,
argsObject: JsonObject,
varsObject: JsonObject
): Obj {
val meta = klass.constructorMeta
?: scope.raiseError("can't deserialize ${klass.className} from Json: no constructor meta")
val namedArgs = linkedMapOf<String, Obj>()
for (param in meta.params) {
if (param.isTransient) continue
val encoded = argsObject[param.name]
if (encoded == null) {
if (param.defaultValue == null && !param.type.isNullable) {
scope.raiseIllegalArgument("missing constructor field '${param.name}' for ${klass.className}")
}
} else {
namedArgs[param.name] = decodeCanonical(scope, encoded)
}
}
val callScope = scope.createChildScope(args = Arguments(list = emptyList(), named = namedArgs))
val instance = klass.callOn(callScope)
if (instance is ObjInstance) {
for ((name, encoded) in varsObject) {
val target = resolveSerializableVar(instance, name)
?: scope.raiseIllegalArgument("unknown serializable field '${klass.className}.$name'")
target.value = decodeCanonical(scope, encoded)
}
}
return instance
}
private suspend fun decodeCanonicalSingletonObject(scope: Scope, element: JsonObject): Obj {
val instance = resolveObject(scope, requiredString(element, NAME_KEY))
val varsObject = requiredObject(element, VARS_KEY)
for ((name, encoded) in varsObject) {
val target = resolveSerializableVar(instance, name)
?: scope.raiseIllegalArgument("unknown serializable field '${instance.objClass.className}.$name'")
target.value = decodeCanonical(scope, encoded)
}
return instance
}
private suspend fun decodeTypedSingletonObject(scope: Scope, klass: ObjClass, element: JsonObject): Obj {
val instance = resolveObject(scope, klass.className)
for ((name, encoded) in element) {
val target = resolveSerializableVar(instance, name)
?: scope.raiseIllegalArgument("unknown serializable field '${instance.objClass.className}.$name'")
target.value = decode(scope, encoded, target.typeDecl)
}
return instance
}
private suspend fun decodeCanonicalException(scope: Scope, element: JsonObject): Obj {
val klass = resolveClass(scope, requiredString(element, CLASS_KEY))
if (klass !is ObjException.Companion.ExceptionClass) {
scope.raiseClassCastError("${klass.className} is not an exception class")
}
val message = decodeCanonical(scope, requireElement(element, MESSAGE_KEY)) as? ObjString
?: scope.raiseClassCastError("exception message must be a string")
val extraData = decodeCanonical(scope, requireElement(element, EXTRA_DATA_KEY))
val stackTrace = decodeCanonical(scope, requireElement(element, STACK_TRACE_KEY)) as? ObjList
?: scope.raiseClassCastError("exception stackTrace must be a list")
return ObjException(klass, scope, message, extraData, stackTrace)
}
private suspend fun ensureMatchesExpectedType(scope: Scope, value: Obj, expectedType: TypeDecl): Obj {
if (!matchesTypeDecl(scope, value, expectedType)) {
scope.raiseClassCastError("decoded Json value of type ${value.objClass.className} does not match expected type ${typeName(expectedType)}")
}
return value
}
private fun resolveSerializableVar(instance: ObjInstance, name: String): ObjRecord? =
instance.serializingVars[name]
?: instance.serializingVars.entries.singleOrNull { it.key.substringAfterLast("::") == name }?.value
private suspend fun resolveClass(scope: Scope, className: String): ObjClass {
scope.get(className)?.value?.let {
if (it is ObjClass) return it
if (it is ObjInstance && it.objClass.className == className) return it.objClass
scope.raiseClassCastError("Expected class $className, got ${it.objClass.className}")
}
val resolved = scope.resolveQualifiedIdentifier(className)
if (resolved is ObjClass) return resolved
if (resolved is ObjInstance && resolved.objClass.className == className) return resolved.objClass
scope.raiseClassCastError("Expected class $className, got ${resolved.objClass.className}")
return resolved as ObjClass
}
private suspend fun resolveObject(scope: Scope, objectName: String): ObjInstance {
scope.get(objectName)?.value?.let {
if (it is ObjInstance) return it
scope.raiseClassCastError("Expected object $objectName, got ${it.objClass.className}")
}
if (objectName.contains('.')) {
val resolved = scope.resolveQualifiedIdentifier(objectName)
val inst = resolved as? ObjInstance
if (inst != null) return inst
scope.raiseClassCastError("Expected object $objectName, got ${resolved.objClass.className}")
}
scope.raiseSymbolNotFound(objectName)
}
private suspend fun expectedExactClass(scope: Scope, expectedType: TypeDecl): ObjClass? {
val nonNullable = nonNullableType(expectedType)
val className = when (nonNullable) {
is TypeDecl.Simple -> nonNullable.name
is TypeDecl.Generic -> nonNullable.name
else -> return null
}
return resolveClass(scope, className)
}
private suspend fun isExpectedExactClass(scope: Scope, expectedType: TypeDecl, actualClass: ObjClass): Boolean =
expectedExactClass(scope, expectedType) == actualClass
private fun expectedBaseName(expectedType: TypeDecl?): String? {
val nonNullable = expectedType?.let { nonNullableType(it) } ?: return null
return when (nonNullable) {
is TypeDecl.Simple -> nonNullable.name.substringAfterLast('.')
is TypeDecl.Generic -> nonNullable.name.substringAfterLast('.')
else -> null
}
}
private fun expectedTypeArgs(expectedType: TypeDecl?): List<TypeDecl> = when (val nonNullable = expectedType?.let { nonNullableType(it) }) {
is TypeDecl.Generic -> nonNullable.args
else -> emptyList()
}
private fun expectedElementType(expectedType: TypeDecl?): TypeDecl? = expectedTypeArgs(expectedType).getOrNull(0)
private fun expectedKeyType(expectedType: TypeDecl?): TypeDecl? = expectedTypeArgs(expectedType).getOrNull(0)
private fun expectedValueType(expectedType: TypeDecl?): TypeDecl? = expectedTypeArgs(expectedType).getOrNull(1)
private fun nonNullableType(type: TypeDecl): TypeDecl = when (type) {
is TypeDecl.Function -> type.copy(nullable = false)
is TypeDecl.Ellipsis -> type.copy(nullable = false)
is TypeDecl.TypeVar -> type.copy(nullable = false)
is TypeDecl.Union -> type.copy(nullable = false)
is TypeDecl.Intersection -> type.copy(nullable = false)
is TypeDecl.Simple -> TypeDecl.Simple(type.name, false)
is TypeDecl.Generic -> TypeDecl.Generic(type.name, type.args, false)
else -> type
}
private fun typeName(type: TypeDecl): String = when (type) {
TypeDecl.TypeAny -> "Any"
TypeDecl.TypeNullableAny -> "Any?"
is TypeDecl.Simple -> type.name + if (type.isNullable) "?" else ""
is TypeDecl.Generic -> buildString {
append(type.name)
append('<')
append(type.args.joinToString(",") { typeName(it) })
append('>')
if (type.isNullable) append('?')
}
is TypeDecl.Function -> "Callable"
is TypeDecl.Ellipsis -> typeName(type.elementType) + "..."
is TypeDecl.TypeVar -> type.name + if (type.isNullable) "?" else ""
is TypeDecl.Union -> type.options.joinToString(" | ") { typeName(it) }
is TypeDecl.Intersection -> type.options.joinToString(" & ") { typeName(it) }
}
private fun tagged(type: String, vararg fields: Pair<String, JsonElement>): JsonObject =
JsonObject(linkedMapOf(TYPE_KEY to JsonPrimitive(type), *fields))
private fun requiredString(element: JsonObject, key: String): String =
requireElement(element, key).jsonPrimitive.content
private fun requiredInt(element: JsonObject, key: String): Int =
requireElement(element, key).jsonPrimitive.content.toInt()
private fun requiredArray(element: JsonObject, key: String): JsonArray =
requireElement(element, key) as? JsonArray
?: throw IllegalArgumentException("field '$key' must be a JSON array")
private fun requiredObject(element: JsonObject, key: String): JsonObject =
requireElement(element, key) as? JsonObject
?: throw IllegalArgumentException("field '$key' must be a JSON object")
private fun requireElement(element: JsonObject, key: String): JsonElement =
element[key] ?: throw IllegalArgumentException("missing field '$key'")
}
@@ -0,0 +1,59 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng.serialization
import net.sergeych.lyng.ModuleScope
import net.sergeych.lyng.Scope
import net.sergeych.lyng.miniast.addConstDoc
import net.sergeych.lyng.miniast.type
import net.sergeych.lyng.obj.Obj
import net.sergeych.lyng.obj.ObjClass
import net.sergeych.lyng.requireOnlyArg
import net.sergeych.lyng.requireScope
abstract class ObjSerializationFormatClass(
className: String
) : ObjClass(className) {
abstract suspend fun encodeValue(scope: Scope, value: Obj): Obj
abstract suspend fun decodeValue(scope: Scope, encoded: Obj): Obj
init {
addClassFn("encode") {
encodeValue(requireScope(), requireOnlyArg())
}
addClassFn("decode") {
decodeValue(requireScope(), requireOnlyArg())
}
}
}
suspend fun ModuleScope.bindSerializationFormat(
format: ObjSerializationFormatClass,
exportName: String = format.className,
doc: String = "${format.className} serialization format."
): ObjSerializationFormatClass {
addConstDoc(
name = exportName,
value = format,
doc = doc,
type = type("lyng.Class")
)
return format
}
@@ -18,14 +18,13 @@
package net.sergeych.lynon
import net.sergeych.lyng.Scope
import net.sergeych.lyng.requireOnlyArg
import net.sergeych.lyng.requireScope
import net.sergeych.lyng.serialization.ObjSerializationFormatClass
import net.sergeych.lyng.obj.*
// Most often used types:
object ObjLynonClass : ObjClass("Lynon") {
object ObjLynonClass : ObjSerializationFormatClass("Lynon") {
suspend fun encodeAny(scope: Scope, obj: Obj): ObjBitBuffer {
val bout = MemoryBitOutput()
@@ -41,15 +40,9 @@ object ObjLynonClass : ObjClass("Lynon") {
return deserializer.decodeAny(scope)
}
init {
addClassConst("test", ObjString("test_const"))
addClassFn("encode") {
encodeAny(requireScope(), requireOnlyArg<Obj>())
}
addClassFn("decode") {
decodeAny(requireScope(), requireOnlyArg<Obj>())
}
}
override suspend fun encodeValue(scope: Scope, value: Obj): Obj = encodeAny(scope, value)
override suspend fun decodeValue(scope: Scope, encoded: Obj): Obj = decodeAny(scope, encoded)
}
/**
+267
View File
@@ -32,6 +32,8 @@ import kotlinx.serialization.json.encodeToJsonElement
import net.sergeych.lyng.*
import net.sergeych.lyng.obj.*
import net.sergeych.lyng.pacman.InlineSourcesImportProvider
import net.sergeych.lyng.serialization.ObjSerializationFormatClass
import net.sergeych.lyng.serialization.bindSerializationFormat
import net.sergeych.lyng.thisAs
import net.sergeych.mp_tools.globalDefer
import net.sergeych.tools.bm
@@ -4663,6 +4665,243 @@ class ScriptTest {
)
}
@Test
fun testUniversalJsonRoundTrip() = runTest {
eval(
"""
import lyng.serialization
import lyng.time
enum Color { Red, Green }
class Point(foo,bar) {
var z = 42
}
val point = Point(1,2)
val color = Color.Green
point.z = 99
val value = List(
point,
Map([1, "one"], ["two", 2]),
Set(1,2,3),
"hello".encodeUtf8(),
Date(2026,4,15),
color
)
val restored = Json.decode(Json.encode(value))
assertEquals(value, restored)
assertEquals(99, restored[0].z)
assertEquals("one", restored[1][1])
assertEquals(true, restored[2].contains(3))
assertEquals("hello", restored[3].decodeUtf8())
assertEquals("2026-04-15", restored[4].toString())
assertEquals(Color.Green, restored[5])
""".trimIndent()
)
}
@Test
fun testJsonDecodePlainJsonString() = runTest {
val decoded = eval(
"""
import lyng.serialization
Json.decode("{\"foo\":[1,true,\"bar\"]}")
""".trimIndent()
)
assertEquals("""{"foo":[1,true,"bar"]}""", decoded.toJson().toString())
}
@Test
fun testUniversalJsonExceptionRoundTrip() = runTest {
eval(
"""
import lyng.serialization
class MyException : Exception("boom")
val ex = MyException()
val restored = Json.decode(Json.encode(ex))
assert(restored is MyException)
assert(restored is Exception)
assertEquals(ex.message, restored.message)
assert(restored.stackTrace.size > 0)
""".trimIndent()
)
}
@Test
fun testUniversalJsonSingletonObjectRoundTrip() = runTest {
eval(
"""
import lyng.serialization
object Counter {
var value = 1
}
Counter.value = 77
val restored = Json.decode(Json.encode(Counter))
assertEquals(Counter, restored)
assertEquals(77, Counter.value)
assertEquals(77, restored.value)
""".trimIndent()
)
}
@Test
fun testCanonicalJsonUsesTraditionalObjectsForStringKeyMaps() = runTest {
eval(
"""
import lyng.serialization
val value = Map(["foo", 1], ["bar", 2])
val encoded = Json.encode(value)
assertEquals("{\"foo\":1,\"bar\":2}", encoded)
val restored = Json.decode(encoded)
assertEquals(value, restored)
assertEquals(1, restored["foo"])
""".trimIndent()
)
}
@Test
fun testTypedJsonRoundTripOmitsExactTypeInformation() = runTest {
eval(
"""
import lyng.serialization
closed class Point(x: Int, y: Int)
val point = Point(0, 1)
val encoded = Json.encodeAs(Point, point)
assertEquals("{\"x\":0,\"y\":1}", encoded)
val restored = Json.decodeAs(Point, encoded)
assertEquals(point, restored)
""".trimIndent()
)
}
@Test
fun testTypedJsonUsesTraditionalObjectsForStringKeyMaps() = runTest {
eval(
"""
import lyng.serialization
closed class Payload(values: Map<String, Int>)
val value = Payload(Map(["foo", 1], ["bar", 2]))
val encoded = Json.encodeAs(Payload, value)
assertEquals("{\"values\":{\"foo\":1,\"bar\":2}}", encoded)
val restored = Json.decodeAs(Payload, encoded)
assertEquals(value, restored)
assertEquals(2, restored.values["bar"])
""".trimIndent()
)
}
@Test
fun testTypedJsonRecursesUsingDeclaredFieldTypes() = runTest {
eval(
"""
import lyng.serialization
closed class Point(x: Int, y: Int)
closed class Segment(a: Point, b: Point)
val value = Segment(Point(0, 1), Point(2, 3))
val encoded = Json.encodeAs(Segment, value)
assertEquals("{\"a\":{\"x\":0,\"y\":1},\"b\":{\"x\":2,\"y\":3}}", encoded)
val restored = Json.decodeAs(Segment, encoded)
assertEquals(value, restored)
""".trimIndent()
)
}
@Test
fun testTypedJsonHandlesNullableFields() = runTest {
eval(
"""
import lyng.serialization
closed class Point(x: Int, y: Int)
closed class MaybePoint(point: Point?, label: String?)
val value = MaybePoint(null, "origin")
val encoded = Json.encodeAs(MaybePoint, value)
assertEquals("{\"point\":null,\"label\":\"origin\"}", encoded)
assertEquals(value, Json.decodeAs(MaybePoint, encoded))
val value2 = MaybePoint(Point(3, 4), null)
val encoded2 = Json.encodeAs(MaybePoint, value2)
assertEquals("{\"point\":{\"x\":3,\"y\":4},\"label\":null}", encoded2)
assertEquals(value2, Json.decodeAs(MaybePoint, encoded2))
""".trimIndent()
)
}
@Test
fun testTypedJsonKeepsSubtypeTagsWhenDeclaredTypeIsWider() = runTest {
eval(
"""
import lyng.serialization
class Base(baseX: Int)
class Derived(derivedX: Int, z: Int): Base(derivedX)
closed class Holder(item: Base)
val value = Holder(Derived(1, 2))
val encoded = Json.encodeAs(Holder, value)
val restored = Json.decodeAs(Holder, encoded)
assert(restored.item is Derived)
assertEquals(2, restored.item.z)
""".trimIndent()
)
}
@Test
fun testTypedJsonUsesEntriesForNonStringKeyMaps() = runTest {
eval(
"""
import lyng.serialization
closed class Numbered(values: Map<Int, String>)
val value = Numbered(Map([1, "one"], [2, "two"]))
val encoded = Json.encodeAs(Numbered, value)
assertEquals("{\"values\":[[1,\"one\"],[2,\"two\"]]}", encoded)
val restored = Json.decodeAs(Numbered, encoded)
assertEquals(value, restored)
assertEquals("one", restored.values[1])
""".trimIndent()
)
}
@Test
fun testTypedJsonOmitsEnumTagsWhenEnumTypeIsKnown() = runTest {
eval(
"""
import lyng.serialization
enum Color { Red, Green }
closed class Paint(color: Color)
val value = Paint(Color.Green)
val encoded = Json.encodeAs(Paint, value)
assertEquals("{\"color\":\"Green\"}", encoded)
val restored = Json.decodeAs(Paint, encoded)
assertEquals(value, restored)
assertEquals(Color.Green, restored.color)
""".trimIndent()
)
}
@Serializable
data class TestJson2(
val value: Int,
@@ -4722,6 +4961,34 @@ class ScriptTest {
assertEquals(TestJson4(TestEnum.One), x)
}
@Test
fun testExternalSerializationFormatRegistration() = runTest {
val im = Script.defaultImportManager.copy()
im.addPackage("test.formats") { module ->
module.bindSerializationFormat(
object : ObjSerializationFormatClass("Reverse") {
override suspend fun encodeValue(scope: Scope, value: Obj): Obj =
ObjString(value.toString(scope).value.reversed())
override suspend fun decodeValue(scope: Scope, encoded: Obj): Obj {
val text = (encoded as? ObjString)?.value
?: scope.raiseClassCastError("Reverse.decode expects String")
return ObjString(text.reversed())
}
},
doc = "Simple test format that reverses strings."
)
}
val scope = im.newStdScope()
scope.eval(
"""
import test.formats
assertEquals("cba", Reverse.encode("abc"))
assertEquals("abc", Reverse.decode("cba"))
""".trimIndent()
)
}
@Test
fun testStringLast() = runTest {
eval(
@@ -0,0 +1,68 @@
/*
* Copyright 2026 Sergey S. Chernov real.sergeych@gmail.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package net.sergeych.lyng
import kotlinx.coroutines.test.runTest
import net.sergeych.lyng.obj.ObjInt
import kotlin.test.Test
import kotlin.test.assertEquals
class DeclAnnotationIntrospectionTest {
@Test
fun classAnnotationQueriesExposeConstructorAndMemberAnnotations() = runTest {
val scope = Scope()
val result = scope.eval(
"""
val suffix = "!"
object Marker
class Sample(
@Transient @Tag(1, label: "ctor", extra: suffix) val x: Int
) {
@Transient @DbDecodeWith(Marker)
var y: Int = 10
}
val ctorAnnotations: ImmutableList<Map<String, Object>> = Sample.getConstructorAnnotations("x")
val ctorTag: Map<String, Object> = ctorAnnotations[1]
val ctorPositional: ImmutableList<Object> = ctorTag["positional"] as ImmutableList<Object>
val ctorNamed: Map<String, Object> = ctorTag["named"] as Map<String, Object>
assertEquals(2, ctorAnnotations.size)
assertEquals("Transient", ctorAnnotations[0]["name"])
assertEquals("Tag", ctorTag["name"])
assertEquals(1, ctorPositional[0])
assertEquals("ctor", ctorNamed["label"])
assertEquals("!", ctorNamed["extra"])
val memberAnnotations: ImmutableList<Map<String, Object>> = Sample.getMemberAnnotations("y")
val memberDecodeWith: Map<String, Object> = memberAnnotations[1]
val memberPositional: ImmutableList<Object> = memberDecodeWith["positional"] as ImmutableList<Object>
assertEquals(2, memberAnnotations.size)
assertEquals("Transient", memberAnnotations[0]["name"])
assertEquals("DbDecodeWith", memberDecodeWith["name"])
assertEquals(Marker, memberPositional[0])
memberAnnotations.size + ctorAnnotations.size
""".trimIndent()
) as ObjInt
assertEquals(4L, result.value)
}
}
+19 -1
View File
@@ -14,6 +14,24 @@ extern class NotImplementedException
/* Raised when an awaited asynchronous task was cancelled before producing a value. */
extern class CancellationException : Exception
/* Runtime metaobject describing a class. */
extern class Class {
/* Full name of this class including package if available. */
val className: String
/* Simple name of this class (without package). */
val name: String
/* Declared instance fields of this class and its ancestors (C3 order), without duplicates. */
val fields: List<String>
/* Declared instance methods of this class and its ancestors (C3 order), without duplicates. */
val methods: List<String>
/* Lookup a member by name in this class (including ancestors) and return it, or null if absent. */
fun get(name: String): Object?
/* Preserved annotations for a constructor parameter as descriptor maps with keys `name`, `positional`, and `named`. */
fun getConstructorAnnotations(name: String): ImmutableList<Map<String, Object>>
/* Preserved annotations for a member as descriptor maps with keys `name`, `positional`, and `named`. */
fun getMemberAnnotations(name: String): ImmutableList<Map<String, Object>>
}
/* A handle to a running asynchronous task. */
extern class Deferred {
/* Cancel the task if it is still active. Safe to call multiple times. */
@@ -648,4 +666,4 @@ class LaunchPool(maxWorkers, maxQueueSize = Channel.UNLIMITED) {
w.await()
}
}
}
}
+351
View File
@@ -0,0 +1,351 @@
# ResultSet typed decode API
Status: draft design note
## Goal
Extend `lyng.io.db` with row deserialization into ordinary Lyng objects using the new typed serialization-style API naming.
Primary use case:
```lyng
class Point(x: Real, y: Real)
val point = db.transaction { tx ->
tx.select(
"select row as x, col as y from data where not is_deleted"
).decodeAs<Point>().first
}
```
## Agreed API
Use `decodeAs<T>()` as the only public API form in v1.
Rationale:
- matches the new typed serialization naming (`Json.decodeAs(...)`)
- communicates decoding/materialization, not casting
- keeps the common case strongly typed and chain-friendly
- avoids adding a second runtime-type overload before it is needed
Planned Lyng-facing declarations:
```lyng
extern class SqlRow {
fun decodeAs<T>(): T
}
extern class ResultSet : Iterable<SqlRow> {
fun decodeAs<T>(): Iterable<T>
}
```
## Lifetime semantics
`ResultSet.decodeAs<T>()` returns a transaction-scoped iterable view over the underlying result set.
Rules:
- the returned iterable must not be used after the owning transaction ends
- decoded objects created during iteration are detached ordinary Lyng objects
- to keep decoded values after the transaction, materialize them inside the transaction
- normal materialization forms are `toList()`, `first`, `findFirst`, or manual iteration
Valid:
```lyng
val points = db.transaction { tx ->
tx.select("select x, y from point")
.decodeAs<Point>()
.toList()
}
```
Invalid:
```lyng
val decoded = db.transaction { tx ->
tx.select("select x, y from point").decodeAs<Point>()
}
decoded.first
```
## ResultSet shape
`ResultSet.decodeAs<T>()` should preserve the current `ResultSet` paradigm:
- `ResultSet` stays the row-producing source
- `decodeAs<T>()` is a projection from `Iterable<SqlRow>` to `Iterable<T>`
- no new DB-specific collection type is introduced in v1
Implementation-wise, `ResultSet.decodeAs<T>()` can be defined as a lazy iterable that decodes each row via `SqlRow.decodeAs<T>()`.
## Mapping discussion to finalize
The following mapping behavior still needs explicit design decisions:
- how constructor parameters are matched from columns
- whether matching is case-insensitive
- whether mutable serializable fields are populated after constructor call
- treatment of default constructor values
- treatment of nullable vs non-nullable targets
- behavior for missing columns
- behavior for extra columns
- behavior for duplicate/ambiguous column labels
- whether `onDeserialized()` is called after row decode
- whether v1 supports only flat object decode or also nested shapes
## Current direction for mapping
Current likely direction, not finalized yet:
- constructor parameters map by column label
- matching is case-insensitive, consistent with `SqlRow["name"]`
- after constructor call, remaining matching serializable mutable fields may be assigned
- missing required non-null constructor values fail
- missing nullable constructor parameters become `null`
- defaulted constructor parameters use their defaults when the column is absent
- ambiguous duplicate column labels fail
- extra columns likely fail in strict mode for v1
- `onDeserialized()` likely should run after the object is fully populated
- v1 should likely stay flat and avoid nested/prefix-based mapping
## Projection/conversion rules
### General principle
Row decoding should be strict and predictable.
It should not globally treat every SQL string column as serialized JSON or every binary column as Lynon.
That would be too implicit:
- ordinary text columns are common and must stay ordinary text by default
- ordinary binary/blob columns are common and must stay raw binary by default
- automatic format decoding should happen only when there is a clear signal
### Proposed conversion precedence
For each constructor parameter or serializable mutable field:
1. resolve the source column by name
2. if the source value already matches the target type, use it directly
3. if an explicit DB decoding attribute is present on the target member, apply that decoding rule
4. otherwise, if the column metadata clearly indicates a special encoded DB type and the target is not the raw DB carrier type, apply the built-in format rule
5. otherwise fail with a decode/type mismatch error
### Direct match
Direct match means the row value is already assignable to the target type after the normal SQL backend conversion.
Examples:
- SQL numeric column already surfaced as `Int`/`Real`/`Decimal`
- SQL bool column surfaced as `Bool`
- SQL date/time column surfaced as `Date`, `DateTime`, `Instant`
- SQL text column surfaced as `String`
- SQL binary column surfaced as `Buffer`
These should not trigger any extra JSON/Lynon decoding.
### Built-in encoded-column rules
Current likely direction:
- JSON/JSONB-like columns should decode through typed canonical `Json` when the target is not `String`
- binary columns should decode through `Lynon` when the target is not `Buffer`
This implies the current default:
- string -> non-string is eligible for automatic typed `Json` decode only when the column metadata says the DB column is JSON-like
- binary -> non-binary is decoded through `Lynon`
- binary -> `Buffer` stays raw `Buffer`
Examples:
- PostgreSQL `json` / `jsonb` column into `Point` -> use typed `Json` decode
- PostgreSQL `jsonb` column into `Map<String, Object?>` -> use typed `Json` decode
- plain `text` / `varchar` column into `Point` -> fail unless explicitly annotated
- `bytea` / `blob` column into `Buffer` -> direct match, no Lynon decode
- `bytea` / `blob` column into `Point` -> decode with `Lynon`
### Attribute-based explicit decoding
Common explicit attributes look useful:
- `@DbJson`
- `@DbLynon`
Applied to constructor parameters and serializable mutable fields.
Meaning:
- `@DbJson` means decode the column value as typed canonical JSON into the target member type
- `@DbLynon` means decode the column value as Lynon into the target member type
Example:
```lyng
class Record(
id: Int,
@DbJson payload: Payload,
@DbLynon cachedState: CacheEntry
)
```
This keeps the common DB formats easy to use without making plain `String` or `Buffer` columns magical.
Implementation note:
- declaration metadata now preserves evaluated constructor-parameter and class-member annotation arguments
- annotation arguments are evaluated once at declaration creation time and retained for the lifetime of the declaration
- `@DbDecodeWith(...)` now uses that preserved metadata path
### Generic custom decoder hook
A generic hook is useful too, but it should be adapter-based, not lambda-based.
Planned shape:
- `@DbDecodeWith(adapter)`
- `adapter` should be an instance of a dedicated interface such as `DbFieldAdapter`
Reason:
- a named adapter interface is easier to document and evolve than arbitrary callables
- it gives us room for richer decoding context without baking ad-hoc callable signatures into annotations
- it keeps the DB mapping API explicit and self-describing
Current design direction:
```lyng
interface DbFieldAdapter {
fun decode(rawValue: Object?, column: SqlColumn, row: SqlRow, targetType: Object): Object? =
throw NotImplementedException("DB field adapter decode is not implemented")
fun encode(value: Object?, targetType: Object): Object? =
throw NotImplementedException("DB field adapter encode is not implemented")
}
```
Decided:
- `decode(...)` should receive the target type
- adapters may be any ordinary instance, not only singleton objects
- the same abstraction should later support symmetric `encode(...)`
- adapter result must be checked against the target member type after decoding
Still open before full implementation:
- exact annotation shape for `@DbDecodeWith(...)`
- whether target member name should also be passed
- whether `targetType` should later get a more specific declaration type than plain `Object`
Implemented in the current design:
- `@DbDecodeWith(adapter)` on constructor parameters
- `@DbDecodeWith(adapter)` on class-body fields/properties participating in `decodeAs<T>()`
Future improvement:
- compiler warning when preserved annotation metadata captures runtime state/closures
- extend preserved annotation metadata beyond constructor parameters and class members to functions and top-level declarations
### Arrays and maps
Arrays and maps should not get DB-specific bespoke mapping in v1 unless they are coming through a recognized encoded format.
Reason:
- portable SQL array/map support is backend-specific and inconsistent
- JSON columns already give us a portable representation for `List` and `Map`
- adding DB-native array semantics now would complicate the contract too early
So in v1:
- if the backend already surfaces a value that directly matches the target type, use it
- otherwise `List` / `Map` reconstruction should happen via `@DbJson` or recognized JSON-like column metadata
### Recommended v1 policy
Current recommended projection policy:
- direct type match first
- then explicit member attribute (`@DbJson`, `@DbLynon`)
- then metadata-driven JSON decode for recognized JSON-like DB columns
- then Lynon decode for binary columns when the target is not `Buffer`
- no implicit JSON decode for arbitrary text columns
- fail on anything else
## Write-side SQL object expansion
The symmetric write-side convenience should be explicit and declaration-driven, but it should not attempt semantic SQL analysis.
Agreed v1 surface:
- `@cols(?1)` expands one object argument to projected column names
- `@vals(?1)` expands the same object argument to matching placeholders and encoded bind values
- `@set(?1)` expands the same object argument to `column = ?` pairs and encoded bind values
- each macro accepts an optional `except:` filter, for example `@set(?1 except: "id", "updatedAt")`
Examples:
```lyng
tx.execute(
"insert into item(@cols(?1)) values(@vals(?1))",
item
)
tx.execute(
"update item set @set(?1) where id = ?2",
item,
item.id
)
```
Rules:
- once a clause uses `@cols`, `@vals`, or `@set`, plain sequential `?` placeholders are not allowed in the same clause
- non-expanded parameters in macro clauses must use explicit indexed placeholders such as `?2`
- the same object argument may be referenced multiple times
- object expansion is based on declaration metadata, not SQL metadata
- v1 excludes `@Transient` and `@DbExcept` fields automatically
- `except:` excludes additional fields for one specific macro use
### Write-side field encoding policy
Write-side encoding cannot rely on DB column type inference, so non-trivial field serialization must be explicit.
For each projected field:
1. if the value is already directly DB-bindable, bind it as-is
2. else if `@DbJson` is present, encode to canonical JSON text
3. else if `@DbLynon` is present, encode to Lynon binary
4. else if `@DbSerializeWith(adapter)` is present, call `adapter.encode(value, targetType)`
5. else fail with `SqlUsageException`
Direct DB-bindable values in v1:
- `null`
- `Bool`
- `Int`, `Real`, `Decimal`
- `String`
- `Buffer`
- `Date`, `DateTime`, `Instant`
This is intentionally stricter than decode-side behavior. On writes, there is no portable, reliable way to infer the intended target DB representation from SQL text alone.
### Adapter role
`DbFieldAdapter` is now symmetric by design:
- `decode(rawValue, column, row, targetType)` is used by `decodeAs<T>()`
- `encode(value, targetType)` is used by SQL object expansion
The adapter instance is captured in preserved declaration annotation metadata, not passed ad hoc at the call site.
Future task:
- consider warnings or lints for risky annotation captures such as stateful adapters or closure-capturing instances
@@ -0,0 +1,25 @@
# Serialization Format Registry
Current status:
- no global serialization-format registry
- formats are exported explicitly from modules and used explicitly, e.g. `Lynon.encode(...)`, `Json.decode(...)`, or `MyFormat.encode(...)`
Why no registry now:
- explicit module exports already solve the current use case
- a registry adds global mutable state and naming semantics we do not currently need
- there is no current runtime feature that needs format discovery by string name
When a registry may become worth adding:
- config-driven format selection, e.g. `"format": "json"`
- host-side introspection such as "list installed serialization formats"
- collision detection across independently loaded modules
- admin or tooling APIs that need to resolve a format without importing its module explicitly
If added later, the registry should be:
- optional, not required for normal explicit usage
- based on stable fully qualified ids, not just short export names
- designed as a host/tooling facility first, not as part of ordinary script-level serialization