You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
improvement: Support only one type of using directives
It seems that we still support multiple ways of declaring using directives, which should be removed before 1.0.x.
It's also needed for SIP so that it's clear what can be accepted by the SIP commitee.
Copy file name to clipboardExpand all lines: website/docs/guides/using-directives.md
+15-71Lines changed: 15 additions & 71 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,33 +9,13 @@ sidebar_position: 5
9
9
10
10
The `using` directives mechanism lets you define configuration information within `.scala` source code files, eliminating the need for build tools to define a dedicated configuration syntax.
11
11
12
-
`using` directives are basically key-value pairs that let you provide multiple values to a single key. For instance, this command:
12
+
`using` directives are basically key-value pairs that let you provide multiple values to a single key. These directives need to be put in comments with a special syntax. For instance, this command:
13
13
14
14
```scala
15
-
using foo "bar", "baz"
15
+
//>usingfoo"bar", "baz"
16
16
```
17
17
18
-
will be interpreted as assigning `bar` and `baz` to the key `foo`.
19
-
20
-
As shown, `using` directives can be defined using the special keyword `using`. However, this may break existing tools outside of Scala CLI. Therefore, `using` directives can be put in comments with a special syntax:
21
-
22
-
```scala
23
-
//>usingscala"2"
24
-
25
-
/*> using options "-Xfatal-warnings" */
26
-
```
27
-
28
-
:::info
29
-
For now we recommend using the special comment (`//> using scala "3.0.2"`), and we will use that syntax in this guide.
30
-
31
-
Until `using` directives becomes a part of the Scala specification, this is the only way that guarantees that your code will work well with IDEs, code formatters, and other tools.
32
-
:::
33
-
34
-
Within one file, only one flavor of using directives can be used. The keyword-based syntax (`using scala "3"`) has precedence over special comments (`//> using scala "3"`). The deprecated, plain comments (`// using scala "3"`) have lowest priority.
35
-
36
-
For now `using` and `@using` can be mixed within a given syntax however we strongly suggest not to use deprecated `@using`.
37
-
38
-
Scala CLI reports warnings for each using directive that does not contribute to the build.
18
+
Scala CLI reports warnings for each using directive that does not contribute to the build, which includes all removed alternatives to special comment using directives.
39
19
40
20
With following snippet:
41
21
@@ -45,19 +25,20 @@ using scala "3.1"
45
25
//>usingscala"2.12.11"
46
26
```
47
27
48
-
Scala `3.1` will be used and following warnings would be reported:
28
+
Scala `2.12.11` will be used and following warnings would be reported:
49
29
50
30
```
51
-
[warn] ./.pg/a.scala:2:1: This using directive is ignored. File contains directives outside comments and those has higher precedence.
52
-
[warn] // using scala "2.13.8"
31
+
[warn] ./.pg/a.scala:1:1: This using directive is ignored. Only using directives starting with //> are supported.
32
+
[warn] using scala "3.1"
53
33
[warn] ^^^
54
-
[warn] ./.pg/a.scala:3:1: This using directive is ignored. File contains directives outside comments and those has higher precedence.
55
-
[warn] //> using scala "2.12.11"
34
+
[warn] ./.pg/a.scala:2:1: Using directive using plain comments are deprecated. Please use a special comment syntax: '//> ...'.
35
+
[warn] // using scala "2.13.8"
56
36
[warn] ^^^^
57
37
```
38
+
58
39
## Deprecated syntax
59
40
60
-
As a part of `0.0.x` series we experimented with different syntaxes for using directives. Based on feedback and discussions with the Scala compiler team, we decided to deprecate`@using` (using annotations) and `// using` (using within plain comment). Those syntaxes will keep working in the `0.1.x` series and will result in an error starting from `0.2.x`.
41
+
As a part of `0.0.x` series we experimented with different syntaxes for using directives. Based on feedback and discussions with the Scala compiler team, we decided to remove`@using` (using annotations), `// using` (using within plain comment) and `using` code directives. Those syntaxes will keep working in the `0.1.x` series and will result in an error starting from `1.0.x`.
61
42
62
43
Scala CLI produces warnings if any of the syntaxes above is used:
63
44
@@ -91,17 +72,6 @@ This means that a library or compiler option defined in one file applies to the
91
72
The only exceptions are `using target` directives, which only apply to the given file.
92
73
`using target` is a marker to assign a given file to a given target (e.g., test or main sources).
93
74
94
-
`using` directives also support indentation and braces syntax similar to the syntax of Scala:
95
-
```scala
96
-
//> using:
97
-
//> scala "2.13"
98
-
//> options "-Xasync"
99
-
//> target {
100
-
//> scope "test"
101
-
//> platform "jvm"
102
-
//> }
103
-
```
104
-
105
75
**We believe that syntax similar to `using` directives should become a part of Scala in the future.**
106
76
107
77
## `using` directives in the Scala CLI
@@ -121,24 +91,24 @@ There are several reasons that we believe `using` directives are a good solution
121
91
122
92
- One of the main Scala CLI use cases is prototyping, and the ability to ship one or more source code files with a complete configuration is a game-changer for this use case.
123
93
- Defining dependencies and other settings is common in Ammonite scripts as well.
124
-
- From a teaching perspective, the ability to provide pre-configured pieces of code that fit into one slide is also benefical.
125
-
- Having configuration close to the code is benefical, since often — especially in small programs — the given depencencies are only used within one source file.
94
+
- From a teaching perspective, the ability to provide pre-configured pieces of code that fit into one slide is also beneficial.
95
+
- Having configuration close to the code is beneficial, since often — especially in small programs — the given dependencies are only used within one source file.
126
96
127
97
We acknowledge that configuration distributed across many source files may be hard to maintain in the long term. Therefore, in the near feature we will introduce a set of lints to ensure that above a given project size or complexity, all configuration details will be centralized.
128
98
129
99
How can configuration that’s contained in source files be centralized?
130
100
`using` directives can be placed in any `.scala` file, so it’s possible to create a `.scala` file that contains only configuration information.
131
-
Therefore, when your project needs to centralize its configuration, we recommend creating a `conf.scala` file, and placing the configuration there.
101
+
Therefore, when your project needs to centralize its configuration, we recommend creating a `project.scala` file, and placing the configuration there.
132
102
We plan to add ways to Scala CLI to migrate these settings into a centralized location with one command or click.
133
103
134
104
We are aware that `using` directives may be a controversial topic, so we’ve created a [dedicated space for discussing `using` directives](https://github.com/VirtusLab/scala-cli/discussions/categories/using-directives-and-cmd-configuration-options).
135
105
136
106
137
107
## How to comment out using directives?
138
108
139
-
Using directives are part of the code so similarly, developers should be able to comment them out. Until 0.2.x when plain comment syntax will be removed commenting out using directives requires special care.
109
+
Using directives are part of the code so similarly, developers should be able to comment them out.
140
110
141
-
Paradoxically, commenting out comment-based directives does not cause any problems. Below, some examples how to do it:
111
+
Commenting out comment-based directives does not cause any problems. Below, some examples how to do it:
142
112
143
113
```scala compile
144
114
// //> using dep "no::lib:123"
@@ -148,29 +118,3 @@ Paradoxically, commenting out comment-based directives does not cause any proble
148
118
// // using dep "no::lib:123"
149
119
```
150
120
151
-
Until plain using directives in plain comments are supported, commenting keyword base syntax require some attention. Let' assume that we have a following code:
152
-
153
-
```scala fail
154
-
using scala "3.1.1"
155
-
using dep "no::lib:123"
156
-
```
157
-
158
-
and we want to comment out broken using directive: `lib "no::lib:123"` when we simply comment it out we will actually turn it into a using directive that is using a plain comment syntax!
159
-
160
-
```scala compile
161
-
using scala "3.1.1"
162
-
// using dep "no::lib:123"
163
-
```
164
-
165
-
In cases where there are other uncommented directives, scala-cli will ignore that directives, producing a warning. In cases that this is the only directive in the file, the commented directive will be still used to configure build.
166
-
167
-
In such cases we suggest to use triple `/` for single line comments, or use `//` withing multiline comments:
168
-
169
-
```scala compile
170
-
/// using dep "in::single-line-comments:123"
171
-
/*
172
-
// using dep "in::multiline-line-comments:123"
173
-
*/
174
-
```
175
-
176
-
Generally, our recommendation is to not use keyword based directives until scala-cli will stop supporting plain comments-based directives.
0 commit comments