mdocのCLI版コマンドをScala 3で動作させるにはcs launchを使うと便利

mdocというツールがある。

MarkdownにScalaのコードを書くと、自動的にこれをコンパイルして値が埋まった状態にしてくれるというもので、ドキュメンテーションに非常に便利だ。

例えば以下のようなコードスニペットがあるとする:

```scala mdoc
val x: Any = "hello"
x match
case s: String => "string"
case n: Int => "int"
```

これをmdocに通すといい感じにしてくれる:

```scala
val x: Any = "hello"
// x: Any = "hello"
x match
case s: String => "string"
case n: Int => "int"
// res0: String = "string"
```

mdocはCLIツールでも利用できるし、sbt上のプラグインとしても利用できるし、また単純なScalaのライブラリとしてプログラムから呼び出すこともできる。

CLI版mdoc

mdocはcs(Coursier)でインストールできる:

% cs install mdoc

あとは-inと-outを指定するだけだ:

% mdoc -in src -out out

するとsrc以下のディレクトリにある.mdファイルのうち、scala mdocというシンタックスハイライトになっている部分が自動的にコンパイルされ、評価結果がコメントとして挿入される。

Scalaのメジャーバージョンを指定する

sbtやscalaのライブラリとして使うときは利用するScalaのバージョンは自明に決まっていたので何も考えることがなかったが、CLI版ではScalaのバージョンについて考えなければならない。

そして、mdoc自体にはScalaのバージョンを指定する仕組みがない。いろいろ探してみた結果、これはmdoc自体のアーティファクトレベルで固定されているらしい。mdocがScala 2系向けにコンパイルされているなら2系でコンパイルするし、3系向けにコンパイルされているなら3系でコンパイルするということらしい。

Coursierを使っている限り、アーティファクトを切り替えるのは難しいことではない。csでインストールしたものをそのまま使う代わりに、cs launchを利用すればよい: