All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.ekrich.config.ConfigValue.scala Maven / Gradle / Ivy

Go to download

Configuration library for Scala using HOCON files

The newest version!
/**
 *   Copyright (C) 2011-2012 Typesafe Inc. 
 */
package org.ekrich.config

/**
 * An immutable value, following the JSON type
 * schema.
 *
 * 

 * Because this object is immutable, it is safe to use from multiple threads and
 * there's no need for "defensive copies."
 *
 * 

 * Do not implement interface {@code ConfigValue}; 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.
 */
trait ConfigValue extends ConfigMergeable {

  /**
   * The origin of the value (file, line number, etc.), for debugging and
   * error messages.
   *
   * @return where the value came from
   */
  def origin: ConfigOrigin

  /**
   * The {@link ConfigValueType} of the value; matches the JSON type schema.
   *
   * @return value's type
   */
  def valueType: ConfigValueType

  /**
   * Returns the value as a plain Java boxed value, that is, a {@code String},
   * {@code Number}, {@code Boolean}, {@code Map},
   * {@code List}, or {@code null}, matching the {@link #valueType}
   * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
   * {@link ConfigList}, it is recursively unwrapped.
   *
   * @return a plain Java value corresponding to this ConfigValue
   */
  def unwrapped: AnyRef

  /**
   * Renders the config value as a HOCON string. This method is primarily
   * intended for debugging, so it tries to add helpful comments and
   * whitespace.
   *
   * 

   * If the config value has not been resolved
   * (see [[Config!.resolve()* Config.resolve()]]),
   * it's possible that it can't be rendered as valid HOCON. In that case the
   * rendering should still be useful for debugging but you might not be able
   * to parse it. If the value has been resolved, it will always be parseable.
   *
   * 

   * This method is equivalent to
   * {@code render(ConfigRenderOptions.defaults())}.
   *
   * @return the rendered value
   */
  def render: String

  /**
   * Renders the config value to a string, using the provided options.
   *
   * 

   * If the config value has not been resolved
   * (see [[[Config!.resolve()* Config.resolve()]]),
   * it's possible that it can't be rendered as valid HOCON. In that case the
   * rendering should still be useful for debugging but you might not be able
   * to parse it. If the value has been resolved, it will always be parseable.
   *
   * 

   * If the config value has been resolved and the options disable all
   * HOCON-specific features (such as comments), the rendering will be valid
   * JSON. If you enable HOCON-only features such as comments, the rendering
   * will not be valid JSON.
   *
   * @param options
   *            the rendering options
   * @return the rendered value
   */
  def render(options: ConfigRenderOptions): String

  override def withFallback(other: ConfigMergeable): ConfigValue

  /**
   * Places the value inside a {@link Config} at the given path. See also
   * {@link ConfigValue#atKey}.
   *
   * @param path
   *            path to store this value at.
   * @return a {@code Config} instance containing this value at the given
   *         path.
   */
  def atPath(path: String): Config

  /**
   * Places the value inside a {@link Config} at the given key. See also
   * {@link ConfigValue#atPath}.
   *
   * @param key
   *            key to store this value at.
   * @return a {@code Config} instance containing this value at the given key.
   */
  def atKey(key: String): Config

  /**
   * Returns a {@code ConfigValue} based on this one, but with the given
   * origin. This is useful when you are parsing a new format of file or setting
   * comments for a single ConfigValue.
   *
   * @since 1.3.0
   * @param origin the origin set on the returned value
   * @return the new ConfigValue with the given origin
   */
  def withOrigin(origin: ConfigOrigin): ConfigValue
}
 















© 2015 - 2024 Weber Informatics LLC | Privacy Policy