https://github.com/mattt/swift-configuration-toml
A TOML provider for the Swift Configuration framework.
https://github.com/mattt/swift-configuration-toml
swift-configuration
Last synced: 4 months ago
JSON representation
A TOML provider for the Swift Configuration framework.
- Host: GitHub
- URL: https://github.com/mattt/swift-configuration-toml
- Owner: mattt
- License: mit
- Created: 2025-12-17T23:59:10.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T12:56:59.000Z (6 months ago)
- Last Synced: 2025-12-23T03:55:29.455Z (6 months ago)
- Topics: swift-configuration
- Language: Swift
- Homepage:
- Size: 36.1 KB
- Stars: 18
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Swift Configuration TOML
A [TOML](https://toml.io) provider for the [Swift Configuration](https://github.com/apple/swift-configuration) framework,
built on [swift-toml](https://github.com/mattt/swift-toml) for spec-compliant parsing
## Requirements
- Swift 6.2+ / Xcode 26+
- macOS 15.0+ / iOS 18.0+ / watchOS 11.0+ / tvOS 18.0+ / visionOS 2.0+
## Installation
### Swift Package Manager
Add the following to your `Package.swift` file:
```swift
dependencies: [
.package(url: "https://github.com/apple/swift-configuration.git", from: "1.0.0"),
.package(url: "https://github.com/mattt/swift-configuration-toml.git", from: "1.0.0")
]
```
Then add the dependency to your target:
```swift
.target(
name: "YourTarget",
dependencies: [
.product(name: "Configuration", package: "swift-configuration"),
.product(name: "ConfigurationTOML", package: "swift-configuration-toml")
],
swiftSettings: [
.interoperabilityMode(.Cxx)
]
)
```
## Usage
### Basic Usage
```swift
import Configuration
import ConfigurationTOML
// Create a provider from a TOML file
let provider = try await TOMLProvider(filePath: "/path/to/config.toml")
let config = ConfigReader(provider: provider)
// Read configuration values
let title = config.string(forKey: "title")
let port = config.int(forKey: "port", default: 8080)
let debug = config.bool(forKey: "debug", default: false)
```
### Nested Tables
```swift
// config.toml:
// [server]
// host = "localhost"
// port = 8080
//
// [database]
// url = "postgres://localhost/mydb"
// maxConnections = 10
let provider = try await TOMLProvider(filePath: "config.toml")
let config = ConfigReader(provider: provider)
let host = config.string(forKey: "server.host")
let port = config.int(forKey: "server.port")
let dbUrl = config.string(forKey: "database.url")
let maxConn = config.int(forKey: "database.maxConnections")
```
### Arrays
```swift
// config.toml:
// ports = [8001, 8002, 8003]
// names = ["alpha", "beta", "gamma"]
let provider = try await TOMLProvider(filePath: "config.toml")
let config = ConfigReader(provider: provider)
let ports = config.intArray(forKey: "ports")
let names = config.stringArray(forKey: "names")
```
### Parsing Options (bytes + secrets)
```swift
import Configuration
import ConfigurationTOML
let options = TOMLSnapshot.ParsingOptions(
bytesDecoder: .hex,
secretsSpecifier: .dynamic { key, _ in
key.lowercased().contains("password") || key.lowercased().contains("token")
}
)
let provider = try await TOMLProvider(filePath: "config.toml", parsingOptions: options)
let config = ConfigReader(provider: provider)
let apiKeyBytes = config.bytes(forKey: "api.key")
```
### Using `FileProvider`
`TOMLSnapshot` conforms to `FileConfigSnapshot`, so it can be used with Swift Configuration’s file providers:
```swift
import Configuration
import ConfigurationTOML
let provider = try await FileProvider(
filePath: "config.toml",
parsingOptions: .default
)
let config = ConfigReader(provider: provider)
```
### Reloading providers
`ConfigurationTOML` includes a `Reloading` trait (disabled by default).
Enable it to use `ReloadingTOMLProvider`.
When enabled, this package also forwards the `Reloading` trait to its `swift-configuration`
dependency automatically.
```diff
dependencies: [
.package(
url: "https://github.com/mattt/swift-configuration-toml.git",
from: "1.0.0",
+ traits: [.defaults, .trait(name: "Reloading")]
)
]
```
When the `Reloading` trait is enabled, you can use `ReloadingTOMLProvider` inside a `ServiceGroup`
to enable automatic reloading of your configuration file.
```swift
import Configuration
import ConfigurationTOML
let provider = try await ReloadingTOMLProvider(filePath: "config.toml")
let config = ConfigReader(provider: provider)
let logger = Logger(label: "config")
let serviceGroup = ServiceGroup(services: [provider], logger: logger)
try await serviceGroup.run()
```
### Complex Configuration
```swift
// config.toml:
// [server]
// host = "localhost"
// port = 8080
//
// [server.ssl]
// enabled = true
// certificate = "/path/to/cert.pem"
let provider = try await TOMLProvider(filePath: "config.toml")
let config = ConfigReader(provider: provider)
let host = config.string(forKey: "server.host")
let port = config.int(forKey: "server.port")
let sslEnabled = config.bool(forKey: "server.ssl.enabled")
let cert = config.string(forKey: "server.ssl.certificate")
```
## License
This project is available under the MIT license.
See the LICENSE file for more info.