Explicit handling of paths in using directives

[prolativ]

Is your feature request related to a problem? Please describe.

Some using directives take paths as arguments. These might be some directives specific to scala-cli itself or something that is passed further to some other tool (e.g. options passed to the compiler or a compiler plugin). When relative paths are used it might be unclear if the programmer's intent was to:

1. pass the relative path unmodified to the underlying tool
   2a) treat the path as relative to the file in which the directive is located
   2b) treat the path as relative to the root of the build (e.g. foo/bar for scala-cli run foo/bar)
   2c) treat the path as relative to the current working directory (where scala-cli is run from)

Describe the solution you'd like
To avoid the confusion, file paths in using directives could be represented with some special syntax distinct from bare string literals. This would make it clear whether a user meant 1 or 2. Potentially a distinction between the subcases of 2 could be made if we find it useful to support all of them, although IMO it would be enough for most use cases to support only 2a.

Taking #1072 as an example, the problematic directive

//> using options  "-Ycheck:instrumentCoverage", "-coverage-out:.", "-sourceroot:."

could be replaced with something like

//> using options  "-Ycheck:instrumentCoverage", "-coverage-out:"${.}, "-sourceroot:"${.}

although I'm not insisting on ${...} as the proper syntax - this is just to show the concept.
Then ${.} would get substituted by scala-cli with the absolute path of the directory containing the file with the using directive (assuming we're considering 2a) and the option containing the absolute path would get passed to the compiler. Paths defined as quoted strings wouldn't be modified in any way.
The example also shows that we would need some way to concatenate the resolved paths with some string literals to form proper options for the compiler or some other tool.

[lwronski]

@prolativ Thanks for reporting,
your proposed syntax makes sense, but I would slightly modify it.

"-coverage-out:"${.}

will be replaced to

"-coverage-out:${.}"

and if you want to skip a special character, users should add and additional dollar $:

"-coverage-out:$${.}"

scala-cli convert it options to "-coverage-out:${.}"

[prolativ]

I wouldn't like to go too far but we should probably keep in mind that using this exact syntax could cause some complications if we wanted to have some kind of more general variable substitution in strings. E.g. we could support something like

//> using value "fooVersion" "1.2.3"
//> using lib "org.foo::foo-a:${fooVersion}"
//> using lib "org.foo::foo-b:${fooVersion}"

[prolativ]

Also if we finally decide to use internal string interpolation we should make sure that it's well supported by IDEs so that it's properly highlighted and people don't get interpolation by accident when a bare string literal was expected.

[prolativ]

One thing to consider (although making things more complicated): should we allow some kind of (predefined and OS agnostic?) path variables, e.g. HOME or TMP?

[lwronski]

I wouldn't like to go too far but we should probably keep in mind that using this exact syntax could cause some complications if we wanted to have some kind of more general variable substitution in strings. E.g. we could support something like

//> using value "fooVersion" "1.2.3"
//> using lib "org.foo::foo-a:${fooVersion}"
//> using lib "org.foo::foo-b:${fooVersion}"

Hi @prolativ, starting from the next version of scala-cli, you will be able to use the syntax "${.}" for explicit path handling in using directives.

After internal discussion, we have decided to implement only the "${.}" syntax and not include variables in using directives. For now, variables are out of scope for using directives