ConfigOrigin
trait ConfigOrigin
Represents the origin (such as filename and line number) of a
with
ConfigException.origin() may return null.
[[ConfigValue]]
for use in error messages. Obtain the origin of a valuewith
[[ConfigValue#origin]]
. Exceptions may have an origin, see[[ConfigException#origin]]
, but be careful becauseConfigException.origin() may return null.
It's best to use this interface only for debugging; its accuracy is
"best effort" rather than guaranteed, and a potentially-noticeable amount of
memory could probably be saved if origins were not kept around, so in the
future there might be some option to discard origins.
"best effort" rather than guaranteed, and a potentially-noticeable amount of
memory could probably be saved if origins were not kept around, so in the
future there might be some option to discard origins.
Do not implement this interface; it should only be implemented by
the config library. Arbitrary implementations will not work because the
library internals assume a specific concrete implementation. Also, this
interface is likely to grow new methods over time, so third-party
implementations will break.
the config library. Arbitrary implementations will not work because the
library internals assume a specific concrete implementation. Also, this
interface is likely to grow new methods over time, so third-party
implementations will break.
Value members
Methods
Returns a string describing the origin of a value or exception. This will
never return null.
never return null.
- Returns
-
string describing the origin
Returns a filename describing the origin. This will return null if the
origin was not a file.
origin was not a file.
- Returns
-
filename of the origin or null
Returns a URL describing the origin. This will return null if the origin
has no meaningful URL.
has no meaningful URL.
- Returns
-
url of the origin or null
Returns a classpath resource name describing the origin. This will return
null if the origin was not a classpath resource.
null if the origin was not a classpath resource.
- Returns
-
resource name of the origin or null
Returns a line number where the value or exception originated. This will
return -1 if there's no meaningful line number.
return -1 if there's no meaningful line number.
- Returns
-
line number or -1 if none is available
Returns any comments that appeared to "go with" this place in the file.
Often an empty list, but never null. The details of this are subject to
change, but at the moment comments that are immediately before an array
element or object field, with no blank line after the comment, "go with"
that element or field.
Often an empty list, but never null. The details of this are subject to
change, but at the moment comments that are immediately before an array
element or object field, with no blank line after the comment, "go with"
that element or field.
- Returns
-
any comments that seemed to "go with" this origin, empty list if
none
Returns a ConfigOrigin based on this one, but with the given
comments. Does not modify this instance or any ConfigValues with
this origin (since they are immutable). To set the returned origin to a
ConfigValue, use
comments. Does not modify this instance or any ConfigValues with
this origin (since they are immutable). To set the returned origin to a
ConfigValue, use
[[ConfigValue#withOrigin]]
.Note that when the given comments are equal to the comments on this object,
a new instance may not be created and this is returned directly.
a new instance may not be created and this is returned directly.
- Value Params
- comments
-
the comments used on the returned origin
- Returns
-
the ConfigOrigin with the given comments
- Since
-
1.3.0
Returns a ConfigOrigin based on this one, but with the given
line number. This origin must be a FILE, URL or RESOURCE. Does not modify
this instance or any ConfigValues with this origin (since they are
immutable). To set the returned origin to a ConfigValue, use
line number. This origin must be a FILE, URL or RESOURCE. Does not modify
this instance or any ConfigValues with this origin (since they are
immutable). To set the returned origin to a ConfigValue, use
[[ConfigValue#withOrigin]]
.Note that when the given lineNumber are equal to the lineNumber on this
object, a new instance may not be created and this is returned
directly.
object, a new instance may not be created and this is returned
directly.
- Value Params
- lineNumber
-
the new line number
- Returns
-
the created ConfigOrigin
- Since
-
1.3.0