diff --git a/docs/Advanced-Concepts/CDEs.rst b/docs/Advanced-Concepts/CDEs.rst index a4a19966..a609a8c5 100644 --- a/docs/Advanced-Concepts/CDEs.rst +++ b/docs/Advanced-Concepts/CDEs.rst @@ -21,24 +21,37 @@ Consider the following example using CDEs. class WithX(b: Boolean) extends Config((site, here, up) => { case SomeKeyX => b - } + }) class WithY(b: Boolean) extends Config((site, here, up) => { case SomeKeyY => b - } + }) When forming a query based on a ``Parameters`` object, like ``p(SomeKeyX)``, the configuration system traverses the "chain" of config fragments until it finds a partial function which is defined at the key, and then returns that value. .. code:: scala - val params = Config(new WithX(true) ++ new WithY(true)) // "chain" together config fragments + val params = new Config(new WithX(true) ++ new WithY(true)) // "chain" together config fragments params(SomeKeyX) // evaluates to true params(SomeKeyY) // evaluates to true params(SomeKeyZ) // evaluates to false In this example, the evaluation of ``params(SomeKeyX)`` will terminate in the partial function defined in ``WithX(true)``, while the evaluation of ``params(SomeKeyY)`` will terminate in the partial function defined in ``WithY(true)``. Note that when no partial functions match, the evaluation will return the default value for that parameter. +Config fragments take precedence from left to right, meaning that a fragment at the start of the chain can override the value of a fragment to the right. It helps to read the fragment chain from right to left. + +.. code:: scala + + case object SomeKeyX extends Field[Int](0) + + class WithX(n: Int) extends Config((site, here, up) => { + case SomeKeyX => n + }) + + val params = new Config(new WithX(10) ++ new WithX(5)) + println(params(SomeKeyX)) // evaluates to 10 + The real power of CDEs arises from the ``(site, here, up)`` parameters to the partial functions, which provide useful "views" into the global parameterization that the partial functions may access to determine a parameterization. .. note:: @@ -54,10 +67,10 @@ Site class WithXEqualsYSite extends Config((site, here, up) => { case SomeKeyX => site(SomeKeyY) // expands to site(SomeKeyY, site) - } + }) - val params_1 = Config(new WithXEqualsYSite ++ new WithY(true)) - val params_2 = Config(new WithY(true) ++ new WithXEqualsYSite) + val params_1 = new Config(new WithXEqualsYSite ++ new WithY(true)) + val params_2 = new Config(new WithY(true) ++ new WithXEqualsYSite) params_1(SomeKeyX) // evaluates to true params_2(SomeKeyX) // evaluates to true @@ -75,10 +88,10 @@ Here class WithXEqualsYHere extends Config((site, here, up) => { case SomeKeyY => false case SomeKeyX => here(SomeKeyY, site) - } + }) - val params_1 = Config(new WithXEqualsYHere ++ new WithY(true)) - val params_2 = Config(new WithY(true) ++ new WithXEqualsYHere) + val params_1 = new Config(new WithXEqualsYHere ++ new WithY(true)) + val params_2 = new Config(new WithY(true) ++ new WithXEqualsYHere) params_1(SomeKeyX) // evaluates to false params_2(SomeKeyX) // evaluates to false @@ -95,10 +108,10 @@ Up class WithXEqualsYUp extends Config((site, here, up) => { case SomeKeyX => up(SomeKeyY, site) - } + }) - val params_1 = Config(new WithXEqualsYUp ++ new WithY(true)) - val params_2 = Config(new WithY(true) ++ new WithXEqualsYUp) + val params_1 = new Config(new WithXEqualsYUp ++ new WithY(true)) + val params_2 = new Config(new WithY(true) ++ new WithXEqualsYUp) params_1(SomeKeyX) // evaluates to true params_2(SomeKeyX) // evaluates to false