|
| 1 | +--- |
| 2 | +title: Context Parameters |
| 3 | +type: section |
| 4 | +description: This page demonstrates how to declare context parameters, and how the compiler infers them at call-site. |
| 5 | +languages: [zh-cn] |
| 6 | +num: 60 |
| 7 | +previous-page: ca-extension-methods |
| 8 | +next-page: ca-context-bounds |
| 9 | +redirect_from: /scala3/book/ca-given-using-clauses.html |
| 10 | +--- |
| 11 | + |
| 12 | +Scala offers two important features for contextual abstraction: |
| 13 | + |
| 14 | +- **Context Parameters** allow you to specify parameters that, at the call-site, can be omitted by the programmer and should be automatically provided by the context. |
| 15 | +- **Given Instances** (in Scala 3) or **Implicit Definitions** (in Scala 2) are terms that can be used by the Scala compiler to fill in the missing arguments. |
| 16 | + |
| 17 | +## Context Parameters |
| 18 | + |
| 19 | +When designing a system, often context information like _configuration_ or settings need to be provided to the different components of your system. |
| 20 | +One common way to achieve this is by passing the configuration as additional argument to your methods. |
| 21 | + |
| 22 | +In the following example, we define a case class `Config` to model some website configuration and pass it around in the different methods. |
| 23 | + |
| 24 | +{% tabs example %} |
| 25 | +{% tab 'Scala 2 and 3' %} |
| 26 | +```scala |
| 27 | +case class Config(port: Int, baseUrl: String) |
| 28 | + |
| 29 | +def renderWebsite(path: String, config: Config): String = |
| 30 | + "<html>" + renderWidget(List("cart"), config) + "</html>" |
| 31 | + |
| 32 | +def renderWidget(items: List[String], config: Config): String = ??? |
| 33 | + |
| 34 | +val config = Config(8080, "docs.scala-lang.org") |
| 35 | +renderWebsite("/home", config) |
| 36 | +``` |
| 37 | +{% endtab %} |
| 38 | +{% endtabs %} |
| 39 | + |
| 40 | +Let us assume that the configuration does not change throughout most of our code base. |
| 41 | +Passing `config` to each and every method call (like `renderWidget`) becomes very tedious and makes our program more difficult to read, since we need to ignore the `config` argument. |
| 42 | + |
| 43 | +### Marking parameters as contextual |
| 44 | + |
| 45 | +We can mark some parameters of our methods as _contextual_. |
| 46 | + |
| 47 | +{% tabs 'contextual-parameters' class=tabs-scala-version %} |
| 48 | +{% tab 'Scala 2' %} |
| 49 | +```scala |
| 50 | +def renderWebsite(path: String)(implicit config: Config): String = |
| 51 | + "<html>" + renderWidget(List("cart")) + "</html>" |
| 52 | + // ^ |
| 53 | + // no argument config required anymore |
| 54 | + |
| 55 | +def renderWidget(items: List[String])(implicit config: Config): String = ??? |
| 56 | +``` |
| 57 | +{% endtab %} |
| 58 | +{% tab 'Scala 3' %} |
| 59 | +```scala |
| 60 | +def renderWebsite(path: String)(using config: Config): String = |
| 61 | + "<html>" + renderWidget(List("cart")) + "</html>" |
| 62 | + // ^ |
| 63 | + // no argument config required anymore |
| 64 | + |
| 65 | +def renderWidget(items: List[String])(using config: Config): String = ??? |
| 66 | +``` |
| 67 | +{% endtab %} |
| 68 | +{% endtabs %} |
| 69 | + |
| 70 | +By starting a parameter section with the keyword `using` in Scala 3 or `implicit` in Scala 2, we tell the compiler that at the call-site it should automatically find an argument with the correct type. |
| 71 | +The Scala compiler thus performs **term inference**. |
| 72 | + |
| 73 | +In our call to `renderWidget(List("cart"))` the Scala compiler will see that there is a term of type `Config` in scope (the `config`) and automatically provide it to `renderWidget`. |
| 74 | +So the program is equivalent to the one above. |
| 75 | + |
| 76 | +In fact, since we do not need to refer to `config` in our implementation of `renderWebsite` anymore, we can even omit its name in the signature in Scala 3: |
| 77 | + |
| 78 | +{% tabs 'anonymous' %} |
| 79 | +{% tab 'Scala 3 Only' %} |
| 80 | +```scala |
| 81 | +// no need to come up with a parameter name |
| 82 | +// vvvvvvvvvvvvv |
| 83 | +def renderWebsite(path: String)(using Config): String = |
| 84 | + "<html>" + renderWidget(List("cart")) + "</html>" |
| 85 | +``` |
| 86 | +{% endtab %} |
| 87 | +{% endtabs %} |
| 88 | + |
| 89 | +In Scala 2, the name of implicit parameters is still mandatory. |
| 90 | + |
| 91 | +### Explicitly providing contextual arguments |
| 92 | + |
| 93 | +We have seen how to _abstract_ over contextual parameters and that the Scala compiler can provide arguments automatically for us. |
| 94 | +But how can we specify which configuration to use for our call to `renderWebsite`? |
| 95 | + |
| 96 | +{% tabs 'explicit' class=tabs-scala-version %} |
| 97 | +{% tab 'Scala 2' %} |
| 98 | +We explicitly supply the argument value as if it was a regular argument: |
| 99 | +```scala |
| 100 | +renderWebsite("/home")(config) |
| 101 | +``` |
| 102 | +{% endtab %} |
| 103 | +{% tab 'Scala 3' %} |
| 104 | +Like we specified our parameter section with `using`, we can also explicitly provide contextual arguments with `using`: |
| 105 | +```scala |
| 106 | +renderWebsite("/home")(using config) |
| 107 | +``` |
| 108 | +{% endtab %} |
| 109 | +{% endtabs %} |
| 110 | + |
| 111 | +Explicitly providing contextual parameters can be useful if we have multiple different values in scope that would make sense, and we want to make sure that the correct one is passed to the function. |
| 112 | + |
| 113 | +For all other cases, as we will see in the next section, there is also another way to bring contextual values into scope. |
| 114 | + |
| 115 | +## Given Instances (Implicit Definitions in Scala 2) |
| 116 | + |
| 117 | +We have seen that we can explicitly pass arguments as contextual parameters. |
| 118 | +However, if there is _a single canonical value_ for a particular type, there is another preferred way to make it available to the Scala compiler: by marking it as `given` in Scala 3 or `implicit` in Scala 2. |
| 119 | + |
| 120 | +{% tabs 'instances' class=tabs-scala-version %} |
| 121 | +{% tab 'Scala 2' %} |
| 122 | +```scala |
| 123 | +implicit val config: Config = Config(8080, "docs.scala-lang.org") |
| 124 | +// ^^^^^^ |
| 125 | +// this is the value the Scala compiler will infer |
| 126 | +// as argument to contextual parameters of type Config |
| 127 | +``` |
| 128 | +{% endtab %} |
| 129 | +{% tab 'Scala 3' %} |
| 130 | +```scala |
| 131 | +val config = Config(8080, "docs.scala-lang.org") |
| 132 | +// this is the type that we want to provide the |
| 133 | +// canonical value for |
| 134 | +// vvvvvv |
| 135 | +given Config = config |
| 136 | +// ^^^^^^ |
| 137 | +// this is the value the Scala compiler will infer |
| 138 | +// as argument to contextual parameters of type Config |
| 139 | +``` |
| 140 | +{% endtab %} |
| 141 | +{% endtabs %} |
| 142 | + |
| 143 | +In the above example we specify that whenever a contextual parameter of type `Config` is omitted in the current scope, the compiler should infer `config` as an argument. |
| 144 | + |
| 145 | +Having defined a canonical value for the type `Config`, we can call `renderWebsite` as follows: |
| 146 | + |
| 147 | +```scala |
| 148 | +renderWebsite("/home") |
| 149 | +// ^ |
| 150 | +// again no argument |
| 151 | +``` |
| 152 | + |
| 153 | +[reference]: {{ site.scala3ref }}/overview.html |
| 154 | +[blog-post]: /2020/11/06/explicit-term-inference-in-scala-3.html |
0 commit comments