tomlkt - GitLite

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #go #android #deep-learning #docker #windows #awesome #cli #vue #pytorch

tomlkt

(★ 138)

Multiplatform TOML library with builtin support for kotlinx.serialization

파일 탐색기

최종 버전 다운로드 (.zip)

- - check.yaml
  - publish.yaml
- build.gradle.kts
- build.gradle.kts
- - anchor-copy-button.svg
  - copy-icon.svg
  - copy-successful-icon.svg
  - footer-go-to-link.svg
  - go-to-top-icon.svg
  - logo-icon.svg
- - clipboard.js
  - main.js
  - navigation-loader.js
  - pages.json
  - platform-content-handler.js
  - prism.js
  - sourceset_dependencies.js
  - symbol-parameters-wrapper_deferred.js
- - font-jb-sans-auto.css
  - logo-styles.css
  - main.css
  - prism.css
  - style.css
- - package-list
- - ui-kit.min.css
  - ui-kit.min.js
- index.html
- navigation.html
- detekt.yml
- - gradle-wrapper.jar
  - gradle-wrapper.properties
- yarn.lock
.gitignore
build.gradle.kts
gradle.properties
gradlew
gradlew.bat
LICENSE
README.md
settings.gradle.kts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/eav-eav-eav/tomlkt

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd tomlkt

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Gradle (Java/Kotlin)

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
JDK (Java) Java/Kotlin 프로젝트를 빌드/실행하려면 필요합니다.
Gradle 레포에 포함된 gradlew(Gradle Wrapper)를 쓰면 Gradle을 따로 설치할 필요가 없습니다.

cd benchmark

이 프로젝트의 관련 파일이 하위 폴더 안에 있어서, 먼저 그 폴더로 이동합니다.

./gradlew build

Gradle로 빌드를 진행합니다.

✅ BUILD SUCCESSFUL 메시지가 뜨면 성공입니다. build/ 폴더에 결과물이 생성됩니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# tomlkt

[![Maven Central](https://img.shields.io/maven-central/v/dev.eav.tomlkt/tomlkt)](https://search.maven.org/artifact/dev.eav.tomlkt/tomlkt)
[![License](https://img.shields.io/github/license/eav-eav-eav/tomlkt)](http://www.apache.org/licenses/LICENSE-2.0)

Powerful and easy to use [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) plugin for [TOML 1.0.0 compliance](https://toml.io/en/v1.0.0)
encoding and decoding.

*If you find any problem along usage, please raise an [issue](https://github.com/eav-eav-eav/tomlkt/issues).* :wink:

## Setup

<details open>
<summary>Gradle Kotlin (build.gradle.kts)</summary>

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    implementation("dev.eav.tomlkt:tomlkt:0.6.1")
}
```
</details>

<details>
<summary>Gradle Groovy (build.gradle)</summary>

```groovy
repositories {
    mavenCentral()
}

dependencies {
    implementation "dev.eav.tomlkt:tomlkt:0.6.1"
}
```
</details>

<details>
<summary>Maven (.pom)</summary>

```xml
<dependency>
  <groupId>dev.eav.tomlkt</groupId>
  <artifactId>tomlkt-jvm</artifactId>
  <version>0.6.1</version>
</dependency>
```
</details>

*Note: If your project is Kotlin Multiplatform, you can simply add this into commonMain
dependencies.*

## Quick Start

Write some config:

```toml
name = "Eav"

[account]
username = "Eav"
password = "123456"
```

Write some code:

```kotlin
@Serializable
data class User(
    val name: String,
    val account: Account?
)

@Serializable
data class Account(
    val username: String,
    val password: String
)

fun main() {
    // Here we use JVM.
    val tomlString = Paths.get("...").readText()
    // Either is OK, but to explicitly pass a serializer is faster.
    val user = Toml.decodeFromString(User.serializer(), tomlString)
    val user = Toml.decodeFromString<User>(tomlString)
    // That's it!

// By the way if you need some configuration.
    val toml = Toml {
        ignoreUnknownKeys = true
    }
    // Use toml to apply the change.

// Encoding.
    val anotherUser = User("Anonymous", null)
    // Again, better to explicitly pass a serializer.
    val config = Toml.encodeToString(User.serializer(), anotherUser)
    Paths.get("...").writeText(config)
    // Done.
}
```

## Supported TOML Features

| TOML Data Type          | Encoding           | Decoding           |
|-------------------------|--------------------|--------------------|
| [Comment](#Comment)     | :heavy_check_mark: | :heavy_check_mark: |
| Key                     | :heavy_check_mark: | :heavy_check_mark: |
| [String](#String)       | :heavy_check_mark: | :heavy_check_mark: |
| Integer                 | :heavy_check_mark: | :heavy_check_mark: |
| Float                   | :heavy_check_mark: | :heavy_check_mark: |
| Boolean                 | :heavy_check_mark: | :heavy_check_mark: |
| [Date Time](#Date-Time) | :heavy_check_mark: | :heavy_check_mark: |
| Array                   | :heavy_check_mark: | :heavy_check_mark: |
| Table                   | :heavy_check_mark: | :heavy_check_mark: |
| Inline Table            | :heavy_check_mark: | :heavy_check_mark: |
| Array of Tables         | :heavy_check_mark: | :heavy_check_mark: |

### Comment

Implemented as an annotation `@TomlComment` on **properties**:

```kotlin
class IntData(
    @TomlComment("""
        An integer,
        but is decoded into Long originally.
    """)
    val int: Int
)
IntData(10086)
```

The code above will be encoded into:

```toml
# An integer,
# but is decoded into Long originally.
int = 10086
```

### String

Basic strings are encoded as `"<content>"`. For multilines and literals, put an annotation as
below:

```kotlin
class MultilineStringData(
    @TomlMultilineString
    val multilineString: String
)
MultilineStringData("""
    Do, a deer, a female deer.
    Re, a drop of golden sun.
""".trimIndent())

class LiteralStringData(
    @TomlLiteralString
    val literalString: String
)
LiteralStringData("C:\\Users\\<User>\\.m2\\repositories")
```

The code above will be encoded into:

```toml
multilineString = """
Do, a deer, a female deer.
Re, a drop of golden sun."""

literalString = 'C:\Users\<User>\.m2\repositories'
```

You can use both annotations to get multiline literal string.

### Date Time

TOML supports several date time formats, so does tomlkt. tomlkt declares `TomlLocalDateTime`,
`TomlOffsetDateTime`, `TomlLocalDate`, `TomlLocalTime` as expect types with builtin support for
serialization (`@Serializable`).

The mapping of these expect types are as follows:

| tomlkt             | java.time      | kotlinx.datetime |
|--------------------|----------------|------------------|
| TomlLocalDateTime  | LocalDateTime  | LocalDateTime    |
| TomlOffsetDateTime | OffsetDateTime | Instant          |
| TomlLocalDate      | LocalDate      | LocalDate        |
| TomlLocalTime      | LocalTime      | LocalTime        |

[TomlLiteral](https://github.com/eav-eav-eav/tomlkt/tree/master/core/src/commonMain/kotlin/dev/eav/tomlkt/TomlElement.kt) is the default intermediate representation of a date time. For conversion,
simply use `TomlLiteral(TomlLocalDateTime)` to create a `TomlLiteral` from a `TomlLocalDateTime`
(true for other types), and `TomlLiteral.toLocalDateTime()` for the other way.

If you would like to provide a custom serializer, use `NativeLocalDateTime` and the like as raw
types.

### TomlElement

The working process of tomlkt:

* Encoding: Model → (TomlElementEncoder) → TomlElement → (TomlElementEmitter) → File.
* Decoding: File → (TomlElementParser) → TomlElement → (TomlElementDecoder) → Model.

As shown, if you already have a TOML file, you can have no model class, but still gain access
to every entry with the help of [TomlElement](https://github.com/eav-eav-eav/tomlkt/tree/master/core/src/commonMain/kotlin/dev/eav/tomlkt/TomlElement.kt). Simply parse the file with
`Toml.parseToTomlTable`, then access entries via various `TomlTable` extensions. Also, if you
are a framework author, you would also need the power of dynamic construction. For example, you
can construct a `TomlTable` like this:

```kotlin
val table = buildTomlTable {
    literal("title", "TOML Example")

table("database") {
        literal("enabled", true)
        array("ports", TomlInline.Instance) {
            literal(8000)
        }
        
        table("temperature") {
            val commentForCpu = """
                The max temperature for the core.
                DO NOT SET OVER 100.0!
            """.trimIndent()

literal("cpu", 79.5, TomlComment(commentForCpu))
        }
    }

array("servers", TomlComment("Available servers.")) {
        table {
            literal("ip", "10.0.0.1")
            literal("role", "main")
        }
        table {
            literal("ip", "10.0.0.2")
        }
    }
}
```

The code above will be encoded into:

```toml
title = "TOML Example"

[database]
enabled = true
ports = [ 8000 ]

[database.temperature]
# The max temperature for the core.
# DO NOT SET OVER 100.0!
cpu = 79.5

# Available servers.

[[servers]]
ip = "10.0.0.1"
role = "main"

[[servers]]
ip = "10.0.0.2"
```

*Note: All the metadata coming from [annotations](https://github.com/eav-eav-eav/tomlkt/tree/master/core/src/commonMain/kotlin/dev/eav/tomlkt/Annotations.kt) is ignored in the parser, meaning that
despite you could parse a file into an element, you cannot emit it back to file fully as is.*

### Others

For other information, view [API docs](https://eav-eav-eav.github.io/tomlkt/).