Skip to content
ekrichPublic

About

Scala configuration library supporting HOCON for Scala, Java, Scala.js, and Scala Native

Topics

Resources

Contributing

Stars

136 stars

Watchers

3 watching

Forks

Repository files navigation

sconfig

CI Scala.js Scala Native Scala Steward badge

Configuration library written in Scala which is a direct translation of the original widely used Java library.

Care has been taken to keep the API the same, but some changes were needed to follow Scala conventions. For example, the empty parentheses were dropped from non-side-effecting methods, so config.root() is now config.root. The scalafix rule handles these changes for you. Using the library from Java is still possible, as the working Java examples show.

Scala JVM, Scala Native, and Scala.js are supported. Scala JVM is fully supported whereas the other platforms support a subset of the full API.

For motivation and background about this project see the PR to the original project. The TLDR is the library was ported to Scala to support Scala Native so scalafmt which uses HOCON configuration could be compiled into a native application.

For the original Java library, see lightbend/config.

Getting Started

Sonatype Central

To use in sbt 2, add the following, replacing x.y.z with the version from the Maven Central badge above. All available versions can be seen at the Maven Repository.

libraryDependencies += "org.ekrich" %% "sconfig" % "x.y.z"

Note: For Scala.js and Scala Native with sbt 1, use %%%.

Please refer to the Usage and Help section below for critical Scala Native and Scala.js usage information. The TLDR is that you must add a java.time library dependency to your project. Refer to the sjavatime home page for the current version or alternative java.time libraries.

If migrating from the original config library, see the migrating section below.

Contributing

See Contributing for helpful hints for those wishing to contribute to this repository.

Cross Build Versions

Scala.js Scala Native

Scala Version JVM Scala.js (1.x) Native (0.5.x)
2.13.x ✅ ✅ ✅
3.x.x ✅ ✅ ✅
  • Scala Native 0.5.x support from 0.7.0.
  • Scala 3 support on Scala Native 0.4.3-RC2 or greater.
  • Scala 2.11 support through version 1.4.9.
  • Scala 3.8+ and Scala.js 1.21+ usage requires Java 17 as of v2.0.0+ of sconfig.
  • Scala 3.9.0 or greater required as of v2.1.0.
  • Scala 2.12 dropped in version 2.2.0.

Usage and Help

scaladoc Discord

The intent is to keep this library in sync with the original, but each PR needs to be ported to maintain feature parity. Because of this, the Core Reference documentation below could contain features that are not yet implemented. Also, we added some New Features that diverge from the original codebase.

Core Reference: Please refer to the original library documentation in the README.

New Features: Refer to the New Features document for changes that are specific to this library.

Platform Support: Use this link for a guide to using Scala Native and Scala.js.

For specific changes, refer to the Releases below.

Migrating from lightbend/config to sconfig

sconfig Scala version support Latest scalafix version

This project publishes a scalafix rule to migrate existing Scala 2 source code that uses com.typesafe.config.Config to this implementation. Scalafix rules modify in place existing valid Scala code. Think of it as a fancy find-and-replace tool that is aware of the Scala type system and can therefore narrowly tailor the changes being made. (Since scalafix changes the source code on your file system, it's best to commit any changes prior to running the rule, in case something weird happens.)

The rule will replace com.typesafe.config package references with org.ekrich.config, and remove trailing parens on some methods (where the API changed from the Java implementation).

Complete setup documentation and the current scalafix version can be found in the scalafix user guide. At a high level, the process is as follows:

  1. Add scalafix to the project's project/plugins.sbt file using the version found above:

    addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "a.b.c")
  2. Add this project to the project's libraryDependencies, but don't remove the old one yet!

    (The old dependency needs to stay on the classpath until after the rule runs, because the code must compile before it will run.)

  3. Run the scalafix sbt command shown below to apply the rule using the version of sconfig selected. Replace the x.y.z below with the version (must be greater than version 1.4.5 when scalafix was added):

    scalafixEnable; scalafixAll dependency:ReplaceTypesafeConfig@org.ekrich:sconfig-scalafix:x.y.z
    
  4. Remove the old config dependency from the project's libraryDependencies

  5. Commit the changes

If you'd rather not use scalafix, especially if you don't use config much, change the dependency, then update the imports and remove the trailing parentheses on non-side-effecting methods. The compiler will point out what's left.

Releases

Latest Release: Sonatype Central

See RELEASES for details or older releases.

About

Scala configuration library supporting HOCON for Scala, Java, Scala.js, and Scala Native

Topics

Resources

Contributing

Stars

136 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages