Skip to content

Commit 08ac315

Browse files
AndreiKingsleyAndreiKingsley
committed
utilities generation topic
1 parent 6bb729b commit 08ac315

File tree

5 files changed

+911
-0
lines changed

5 files changed

+911
-0
lines changed

‎docs/StardustDocs/d.tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,7 @@
191191
<toc-element topic="format.md"/>
192192
<toc-element topic="jupyterRendering.md"/>
193193
</toc-element>
194+
<toc-element topic="Utilities-Generation.md"/>
194195
</toc-element>
195196
<toc-element topic="gradleReference.md"/>
196197
<toc-element topic="Usage-with-Kotlin-Notebook-Plugin.md">

‎docs/StardustDocs/topics/Utilities-Generation.md

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Utilities Generation
2+
3+
<web-summary>
4+
Generate useful Kotlin definitions based on your DataFrame structure.
5+
</web-summary>
6+
7+
<card-summary>
8+
Generate useful Kotlin definitions based on your DataFrame structure.
9+
</card-summary>
10+
11+
<link-summary>
12+
Generate useful Kotlin definitions based on your DataFrame structure.
13+
</link-summary>
14+
15+
<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Generate-->
16+
17+
Special utility functions that generate code of useful Kotlin definitions (returned as a `String`)
18+
based on the current `DataFrame` schema.
19+
20+
21+
## generateInterfaces
22+
23+
Generates [`@DataSchema`](schemas.md) interfaces for this `DataFrame`
24+
(including all nested `DataFrame` columns and column groups) as Kotlin interfaces.
25+
26+
This is useful when working with the [compiler plugin](Compiler-Plugin.md)
27+
in cases where the schema cannot be inferred automatically from the source.
28+
29+
### Arguments {id="generateInterfaces-arguments"}
30+
* `markerName`: `String` – The base name to use for generated interfaces.
31+
If not specified, uses the `T` type argument of `DataFrame` simple name.
32+
33+
### Returns {id="generateInterfaces-returns"}
34+
* `CodeString` – A value class wrapper for `String`, containing
35+
the generated Kotlin code of `@DataSchema` interfaces without extension properties.
36+
37+
### Examples {id="generateInterfaces-examples"}}
38+
39+
40+
<!---FUN notebook_test_generate_docs_1-->
41+
42+
```kotlin
43+
df
44+
```
45+
46+
<!---END-->
47+
48+
<inline-frame src="./resources/notebook_test_generate_docs_1.html" width="100%" height="500px"></inline-frame>
49+
50+
<!---FUN notebook_test_generate_docs_2-->
51+
52+
```kotlin
53+
df.generateInterfaces()
54+
```
55+
56+
<!---END-->
57+
58+
Output:
59+
```kotlin
60+
@DataSchema(isOpen = false)
61+
interface _DataFrameType11 {
62+
val amount: kotlin.Double
63+
val orderId: kotlin.Int
64+
}
65+
66+
@DataSchema
67+
interface _DataFrameType1 {
68+
val orders: List<_DataFrameType11>
69+
val user: kotlin.String
70+
}
71+
```
72+
73+
By adding these interfaces to your project with the [compiler plugin](Compiler-Plugin.md) enabled,
74+
you'll gain full support for the [extension properties API](extensionPropertiesApi.md) and type-safe operations.
75+
76+
Use [`cast`](cast.md) to apply the generated schema to a `DataFrame`:
77+
78+
<!---FUN notebook_test_generate_docs_3-->
79+
80+
```kotlin
81+
df.cast<_DataFrameType1>().filter { orders.all { orderId >= 102 } }
82+
```
83+
84+
<!---END-->
85+
86+
<!--inline-frame src="./resources/notebook_test_generate_docs_3.html" width="100%" height="500px"></inline-frame>-->
87+
88+
## generateDataClasses
89+
90+
Generates Kotlin data classes corresponding to the `DataFrame` schema
91+
(including all nested `DataFrame` columns and column groups).
92+
93+
Useful when you want to:
94+
95+
- Work with the data as regular Kotlin data classes.
96+
- Work with data classes serialization.
97+
- Extract structured types for further use in your application.
98+
-
99+
### Arguments {id="generateDataClasses-arguments"}
100+
* `markerName`: `String?` — The base name to use for generated data classes.
101+
If `null`, uses the `T` type argument of `DataFrame` simple name.
102+
Default: `null`.
103+
* `extensionProperties`: `Boolean` – Whether to generate extension properties in addition to `data class` declarations.
104+
Default: `false`.
105+
* `visibility`: `MarkerVisibility` – Visibility modifier for the generated declarations.
106+
Default: `MarkerVisibility.IMPLICIT_PUBLIC`.
107+
* `useFqNames`: `Boolean` – If `true`, fully qualified type names will be used in generated code.
108+
Default: `false`.
109+
* `nameNormalizer`: `NameNormalizer` – Strategy for converting column names (with spaces, underscores, etc.) to valid Kotlin identifiers.
110+
Default: `NameNormalizer.default`.
111+
112+
### Returns {id="generateDataClasses-returns"}
113+
* `CodeString` – A value class wrapper for `String`, containing
114+
the generated Kotlin code of `data class` declarations and optionally extension properties.
115+
116+
### Examples {id="generateDataClasses-examples"}
117+
118+
<!---FUN notebook_test_generate_docs_4-->
119+
120+
```kotlin
121+
df.generateDataClasses("Customer")
122+
```
123+
124+
<!---END-->
125+
126+
Output:
127+
```kotlin
128+
@DataSchema
129+
data class Customer1(
130+
val amount: Double,
131+
val orderId: Int
132+
)
133+
134+
@DataSchema
135+
data class Customer(
136+
val orders: List<Customer1>,
137+
val user: String
138+
)
139+
```
140+
141+
AAdd these classes to your project and convert the DataFrame to a list of typed objects:
142+
143+
<!---FUN notebook_test_generate_docs_5-->
144+
145+
```kotlin
146+
val customers: List<Customer> = df.cast<Customer>().toList()
147+
```
148+
149+
<!---END-->
150+
151+
<!---FUN notebook_test_generate_docs_6-->
152+
153+
## generateCode
154+
155+
Generates a data schema interface as [`generateInterfaces()`](#generateinterfaces),
156+
along with explicit [extension properties](extensionPropertiesApi.md).
157+
Useful if you don't use the [compiler plugin](Compiler-Plugin.md).
158+
159+
### Arguments {id="generateCode-arguments"}
160+
* `markerName`: `String` – The base name to use for generated interfaces.
161+
If not specified, uses the `T` type argument of `DataFrame` simple name.
162+
* `fields`: `Boolean` – Whether to generate fields (`val ...`) inside interfaces.
163+
Default: `true`.
164+
* `extensionProperties`: `Boolean` – Whether to generate extension properties for the schema.
165+
Default: `true`.
166+
* `visibility`: `MarkerVisibility` – Visibility modifier for the generated declarations.
167+
Default: `MarkerVisibility.IMPLICIT_PUBLIC`.
168+
169+
### Returns {id="generateCode-returns"}
170+
* `CodeString` – A value class wrapper for `String`, containing
171+
the generated Kotlin code of `@DataSchema` interfaces and/or extension properties.
172+
173+
### Examples {id="generateCode-examples"}
174+
175+
```kotlin
176+
df.generateCode("Customer")
177+
```
178+
179+
<!---END-->
180+
181+
Output:
182+
```kotlin
183+
@DataSchema(isOpen = false)
184+
interface Customer1 {
185+
val amount: kotlin.Double
186+
val orderId: kotlin.Int
187+
}
188+
189+
val org.jetbrains.kotlinx.dataframe.ColumnsContainer<Customer1>.amount: org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.Double> @JvmName("Customer1_amount") get() = this["amount"] as org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.Double>
190+
val org.jetbrains.kotlinx.dataframe.DataRow<Customer1>.amount: kotlin.Double @JvmName("Customer1_amount") get() = this["amount"] as kotlin.Double
191+
val org.jetbrains.kotlinx.dataframe.ColumnsContainer<Customer1>.orderId: org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.Int> @JvmName("Customer1_orderId") get() = this["orderId"] as org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.Int>
192+
val org.jetbrains.kotlinx.dataframe.DataRow<Customer1>.orderId: kotlin.Int @JvmName("Customer1_orderId") get() = this["orderId"] as kotlin.Int
193+
194+
@DataSchema
195+
interface Customer {
196+
val orders: List<Customer1>
197+
val user: kotlin.String
198+
}
199+
200+
val org.jetbrains.kotlinx.dataframe.ColumnsContainer<Customer>.orders: org.jetbrains.kotlinx.dataframe.DataColumn<org.jetbrains.kotlinx.dataframe.DataFrame<Customer1>> @JvmName("Customer_orders") get() = this["orders"] as org.jetbrains.kotlinx.dataframe.DataColumn<org.jetbrains.kotlinx.dataframe.DataFrame<Customer1>>
201+
val org.jetbrains.kotlinx.dataframe.DataRow<Customer>.orders: org.jetbrains.kotlinx.dataframe.DataFrame<Customer1> @JvmName("Customer_orders") get() = this["orders"] as org.jetbrains.kotlinx.dataframe.DataFrame<Customer1>
202+
val org.jetbrains.kotlinx.dataframe.ColumnsContainer<Customer>.user: org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.String> @JvmName("Customer_user") get() = this["user"] as org.jetbrains.kotlinx.dataframe.DataColumn<kotlin.String>
203+
val org.jetbrains.kotlinx.dataframe.DataRow<Customer>.user: kotlin.String @JvmName("Customer_user") get() = this["user"] as kotlin.String
204+
```
205+
206+
By adding this generated code to your project, you can use the [extension properties API](extensionPropertiesApi.md)
207+
for fully type-safe column access and transformations.
208+
209+
Use [`cast`](cast.md) to apply the generated schema to a `DataFrame`:
210+
211+
<!---FUN notebook_test_generate_docs_7-->
212+
213+
```kotlin
214+
df.cast<Customer>()
215+
.add("ordersTotal") { orders.sumOf { it.amount } }
216+
.filter { user.startsWith("A") }
217+
.rename { user }.into("customer")
218+
```
219+
220+
<!---END-->
221+
222+
<!--inline-frame src="./resources/notebook_test_generate_docs_7.html" width="100%" height="500px"></inline-frame>-->
223+

0 commit comments

Comments
 (0)