From 4f3a91fd8602f3ee8cea48e3e5beefaadff69990 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Mon, 28 Nov 2011 15:11:26 -0500 Subject: [PATCH] document why substitutions special-case system props currently needed for files that are included in other files. not really happy with how this works now, but documenting it as a starting point. maybe to force a substitution to resolve from the root we could start it with a period? ${.this.is.a.root.prop} ? --- HOCON.md | 17 ++++++++++++----- README.md | 19 ++++++++++++++++++- 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/HOCON.md b/HOCON.md index 7c74ca5e..ed8beee6 100644 --- a/HOCON.md +++ b/HOCON.md @@ -14,7 +14,7 @@ The following features are desirable, to support human usage: - ability to refer to another part of the configuration (set a value to another value) - import/include another configuration file into the current file - - a mapping to a flat properties list such as Java's System properties + - a mapping to a flat properties list such as Java's system properties - ability to get values from environment variables - ability to write comments @@ -948,7 +948,7 @@ its substitutions. ### Conventional override by system properties -For an application's config, Java System properties _override_ +For an application's config, Java system properties _override_ settings found in the configuration file. This supports specifying config options on the command line. @@ -961,9 +961,16 @@ properties. If you merge system properties in to an application's configuration as overrides, then falling back to them for -substitutions won't add anything - they would already be found in -the configuration. But if you don't merge them in as overrides -then you could fall back to them. +substitutions isn't important when parsing a toplevel config file +- they would already be found in the configuration. + +However, there are some cases when system properties fallbacks are +used. For example, when a config file is parsed as an include, its +substitutions are relative to the key the file is included +underneath. In that case, `${user.home}` might become +`${something.user.home}` and would not match a system property +override applied to the root of the config tree. However, +`${user.home}` always falls back to the system property. ### Substitution fallback to environment variables diff --git a/README.md b/README.md index 0fea41c6..d18df257 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,24 @@ Here are some features that might be nice to add. - substitutions with fallbacks; this could be something like `${foo.bar,baz,null}` where it would look up `foo.bar`, then `baz`, then finally fall back to null. One question is whether - entire nested objects would be allowed as fallbacks. + entire nested objects would be allowed as fallbacks. This + feature may not really be needed because you can just list the + key multiple times instead: `a=null,a=${?baz},a=${?foo.bar}` + - improve handling of substitutions in includes. Right now if you + have a parent file `a : { include "child.conf" }` and + `child.conf` contains a substitution written `${b}`, then + `${b}` ends up referring to `${a.b}` (that is, its parent key + is prepended to it). The downside of this is that there's no + way to refer to toplevel settings from inside `child.conf`, and + system properties must be special-case fallbacks for + substitutions to allow them to be used from `child.conf`. If + `${b}` in an include always referred to the root `${b}` then + substitutions would not need any special system property + awareness, but there would be no way to write a file to be + included in another file without knowing the parent key the + file would be included into. The solution probably involves + special syntax for one of "root-relative" or "file-relative", + with the regular syntax meaning one or the other. ## Rationale