* If a path exists according to {@link #hasPath(String)}, then * {@link #getValue(String)} will never throw an exception. However, the * typed getters, such as {@link #getInt(String)}, will still throw if the * value is not convertible to the requested type. - * + * + *
+ * Note that path expressions have a syntax and sometimes require quoting
+ * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param path
* the path expression
* @return true if a non-null value is present at the path
@@ -424,9 +428,22 @@ public interface Config extends ConfigMergeable {
* recursing {@link #root() the root object}. Note that this is very
* different from root().entrySet() which returns the set of
* immediate-child keys in the root object and includes null values.
- *
+ *
+ * Entries contain path expressions meaning there may be quoting + * and escaping involved. Parse path expressions with + * {@link ConfigUtil#splitPath}. + *
+ * Because a
+ * Note that path expressions have a syntax and sometimes require quoting
+ * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param path
* path to keep
* @return a copy of the config minus all paths except the one specified
@@ -704,18 +724,24 @@ public interface Config extends ConfigMergeable {
/**
* Clone the config with the given path removed.
- *
+ *
+ * Note that path expressions have a syntax and sometimes require quoting
+ * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param path
- * path to remove
+ * path expression to remove
* @return a copy of the config minus the specified path
*/
Config withoutPath(String path);
/**
* Places the config inside another {@code Config} at the given path.
- *
+ *
+ * Note that path expressions have a syntax and sometimes require quoting
+ * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param path
- * path to store this config at.
+ * path expression to store this config at.
* @return a {@code Config} instance containing this config at the given
* path.
*/
@@ -723,8 +749,9 @@ public interface Config extends ConfigMergeable {
/**
* Places the config inside a {@code Config} at the given key. See also
- * atPath().
- *
+ * atPath(). Note that a key is NOT a path expression (see
+ * {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param key
* key to store this config at.
* @return a {@code Config} instance containing this config at the given
@@ -737,9 +764,12 @@ public interface Config extends ConfigMergeable {
* to the given value. Does not modify this instance (since it's immutable).
* If the path already has a value, that value is replaced. To remove a
* value, use withoutPath().
- *
+ *
+ * Note that path expressions have a syntax and sometimes require quoting
+ * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
+ *
* @param path
- * path to add
+ * path expression for the value's new location
* @param value
* value at the new path
* @return the new instance with the new map entry
diff --git a/config/src/main/java/com/typesafe/config/ConfigUtil.java b/config/src/main/java/com/typesafe/config/ConfigUtil.java
index cc936923..37e394f4 100644
--- a/config/src/main/java/com/typesafe/config/ConfigUtil.java
+++ b/config/src/main/java/com/typesafe/config/ConfigUtil.java
@@ -29,7 +29,10 @@ public final class ConfigUtil {
* elements as needed and then joining them separated by a period. A path
* expression is usable with a {@link Config}, while individual path
* elements are usable with a {@link ConfigObject}.
- *
+ *
+ * See the overview documentation for {@link Config} for more detail on path
+ * expressions vs. keys.
+ *
* @param elements
* the keys in the path
* @return a path expression
@@ -45,7 +48,10 @@ public final class ConfigUtil {
* elements as needed and then joining them separated by a period. A path
* expression is usable with a {@link Config}, while individual path
* elements are usable with a {@link ConfigObject}.
- *
+ *
+ * See the overview documentation for {@link Config} for more detail on path
+ * expressions vs. keys.
+ *
* @param elements
* the keys in the path
* @return a path expression
@@ -61,7 +67,10 @@ public final class ConfigUtil {
* and unquoting the individual path elements. A path expression is usable
* with a {@link Config}, while individual path elements are usable with a
* {@link ConfigObject}.
- *
+ *
+ * See the overview documentation for {@link Config} for more detail on path
+ * expressions vs. keys.
+ *
* @param path
* a path expression
* @return the individual keys in the path
Config is conceptually a single-level map from
+ * paths to values, there will not be any {@link ConfigObject} values in the
+ * entries (that is, all entries represent leaf nodes). Use
+ * {@link ConfigObject} rather than Config if you want a tree.
+ * (OK, this is a slight lie: Config entries may contain
+ * {@link ConfigList} and the lists may contain objects. But no objects are
+ * directly included as entry values.)
+ *
* @return set of paths with non-null values, built up by recursing the
- * entire tree of {@link ConfigObject}
+ * entire tree of {@link ConfigObject} and creating an entry for
+ * each leaf value.
*/
Set