Repository files navigation

A Swift library for reading configuration in applications and libraries.

• 📚Documentation is available on theSwift Package Index.
• 💻Examples are availablejust below, in theExamples directory, and on theExample use cases page.
• 🚀Contributions are welcome, please seeCONTRIBUTING.md.
• 🪪License is Apache 2.0, repeated inLICENSE.
• 🔒Security issues should be reported via the process inSECURITY.md.

Swift Configuration defines an abstraction layer between configurationreaders andproviders.

Applications and librariesread configuration through a consistent API, while the actualprovider is set up once at the application's entry point.

Swift Configuration allows you to combine multiple providers in a hierarchy, where values from higher-priority sources override those from lower-priority ones.

For example, if you have a default configuration in JSON:

{"http": {"timeout":30  }}

And want to be able to provide an override for that using an environment variable:

# Environment variables:HTTP_TIMEOUT=15

The example code below creates the two relevant providers, and resolves them in the order you list:

letconfig=ConfigReader(providers:[EnvironmentVariablesProvider(),tryawaitFileProvider<JSONSnapshot>(filePath:"/etc/config.json")])lethttpTimeout= config.int(forKey:"http.timeout", default:60)print(httpTimeout) // prints 15

The resolved configuration value is15 from the environment variable. Without the environment variable, it would use30 from the JSON file.If both sources are unavailable, the fallback default of60 is returned.

Tip: More example use cases are described inexample use cases, and complete working examples are available in theExamples directory.

Add the dependency to yourPackage.swift:

.package(url:"https://github.com/apple/swift-configuration", exact:"1.0.0-alpha.1")

Add the library dependency to your target:

.product(name:"Configuration",package:"swift-configuration")

Import and use in your code:

import Configurationletconfig=ConfigReader(provider:EnvironmentVariablesProvider())lethttpTimeout= config.int(forKey:"http.timeout", default:60)print("The HTTP timeout is:\(httpTimeout)")

• Configuring applications
• Configuring libraries

For more, check out the fulldocumentation.

This package offers additional integrations you can enable usingpackage traits.To enable an additional trait on the package, update the package dependency:

.package(    url: "https://github.com/apple/swift-configuration",    exact: "1.0.0-alpha.1",+   traits: [.defaults, "OtherFeatureSupport"])

Available traits:

• JSONSupport (default): Adds support forFileProvider<JSONSnapshot>, aConfigProvider for reading JSON files.
• LoggingSupport (opt-in): Adds support forAccessLogger, a way to emit access events into aSwiftLog.Logger.
• ReloadingSupport (opt-in): Adds support for auto-reloading variants of file providers, such asReloadingFileProvider<JSONSnapshot> (whenJSONSupport is enabled) andReloadingFileProvider<YAMLSnapshot> (whenYAMLSupport is enabled).
• CommandLineArgumentsSupport (opt-in): Adds support forCommandLineArgumentsProvider for parsing command line arguments.
• YAMLSupport (opt-in): Adds support forFileProvider<YAMLSnapshot>, aConfigProvider for reading YAML files.

The library is supported on macOS, Linux, and Windows.

The library includes comprehensive built-in provider support:

• Environment variables:EnvironmentVariablesProvider
• Command-line arguments:CommandLineArgumentsProvider
• JSON file:FileProvider<JSONSnapshot> andReloadingFileProvider<JSONSnapshot>
• YAML file:FileProvider<YAMLSnapshot> andReloadingFileProvider<YAMLSnapshot>
• Directory of files:DirectoryFilesProvider
• In-memory:InMemoryProvider andMutableInMemoryProvider
• Key transforming:KeyMappingProvider

You can also implement a customConfigProvider for specialized configuration formats and sources.

• 3 access patterns: synchronous, asynchronous, and watching
• Provider hierarchy
• Hot reloading/watching value updates
• Namespacing and scoped readers
• Debugging and troubleshooting
• Redaction of secrets
• Consistent snapshots
• Custom key syntax

Comprehensive documentation is hosted on theSwift Package Index.