From acca3b5c6d1ee3cdc1ebf63daaf7433bc1253c32 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Thu, 9 Apr 2015 12:33:01 -0400 Subject: [PATCH] README: Discuss FAQ on how reference.conf gets resolved Closes #306, relates to #167 --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index b5a9325f..747a4747 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ to merge it in. - [Immutability](#immutability) - [Schemas and Validation](#schemas-and-validation) - [Standard behavior](#standard-behavior) + - [Note about resolving substitutions in `reference.conf` and `application.conf`](#note-about-resolving-substitutions-in-referenceconf-and-applicationconf) - [Merging config trees](#merging-config-trees) - [How to handle defaults](#how-to-handle-defaults) - [Understanding `Config` and `ConfigObject`](#understanding-config-and-configobject) @@ -70,12 +71,14 @@ to merge it in. - [Inheritance](#inheritance) - [Optional system or env variable overrides](#optional-system-or-env-variable-overrides) - [Concatenation](#concatenation) + - [`reference.conf` can't refer to `application.conf`](#referenceconf-cant-refer-to-applicationconf) - [Miscellaneous Notes](#miscellaneous-notes) - [Debugging Your Configuration](#debugging-your-configuration) - [Supports Java 8 and Later](#supports-java-8-and-later) - [Rationale for Supported File Formats](#rationale-for-supported-file-formats) - [Other APIs (Wrappers and Ports)](#other-apis-wrappers-and-ports) - [Scala wrappers for the Java library](#scala-wrappers-for-the-java-library) + - [Clojure wrappers for the Java library](#clojure-wrappers-for-the-java-library) - [Ruby port](#ruby-port) - [Python port](#python-port) @@ -254,6 +257,29 @@ configuration. In the replacement config file, you can use file; after the include statement you could go on to override certain settings. +#### Note about resolving substitutions in `reference.conf` and `application.conf` + +The substitution syntax `${foo.bar}` will be resolved +twice. First, all the `reference.conf` files are merged and then +the result gets resolved. Second, all the `application.conf` are +layered over the `reference.conf` and the result of that gets +resolved again. + +The implication of this is that the `reference.conf` stack has to +be self-contained; you can't leave an undefined value `${foo.bar}` +to be provided by `application.conf`, or refer to `${foo.bar}` in +a way that you want to allow `application.conf` to +override. However, `application.conf` can refer to a `${foo.bar}` +in `reference.conf`. + +This can be frustrating at times, but possible workarounds +include: + + * putting an `application.conf` in a library jar, alongside the +`reference.conf`, with values intended for later resolution. + * putting some logic in code instead of building up values in the + config itself. + ### Merging config trees Any two Config objects can be merged with an associative operation @@ -696,6 +722,14 @@ concatenation, but not object/array concatenation. `+=` does not work in Play/Akka 2.0 either. Post-2.0 versions support these features. +### `reference.conf` can't refer to `application.conf` + +Please see this +earlier section; all `reference.conf` have substitutions +resolved first, without `application.conf` in the stack, so the +reference stack has to be self-contained. + ## Miscellaneous Notes ### Debugging Your Configuration