Skip to content
3 changes: 3 additions & 0 deletions glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,3 +165,6 @@
| ユーザー定義エフェクト | User-defined effect |
| 解釈不能エフェクト | Uninterpretable effect |
| 多相エフェクト | Polymorphic effect |
| 注釈 | Annotation |
| エフェクトのロック | Effect locking |
| ロックファイル | Lock file |
3 changes: 2 additions & 1 deletion src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@
- [末尾再帰](./tail-recursion.md)
- [匿名ホールと名前付きホール](./holes.md)
- [型注釈](./type-ascriptions.md)
- [注釈](./annotations.md)
- [冗長性](./redundancy.md)
- [デバッグ](./debugging.md)
- [ツール](./tools.md)
Expand All @@ -91,14 +92,14 @@
- [依存関係の使用](./using-dependencies.md)
- [バージョンとアップグレード](./versions-and-upgrades.md)
- [依存関係の信頼](./trusting-dependencies.md)
- [エフェクトのロック](./locking-effects.md)
- [パッケージの公開](./publishing-a-package.md)
---

- [高度な機能](./advanced-features.md)
- [検査付きキャスト](./checked-casts.md)
- [未検査キャスト](./unchecked-casts.md)
- [バグと到達不能コード](./bug-and-unreachable.md)
- [遅延評価](./laziness.md)
- [純粋性リフレクション](./purity-reflection.md)
- [型レベルプログラミング](./type-level-programming.md)
- [停止性検査](./termination-checking.md)
Expand Down
98 changes: 98 additions & 0 deletions src/annotations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# 注釈

> 💡 **お知らせ**: このドキュメントはAIによって翻訳されています。表現に違和感がある場合は、[原文(英語)](https://doc.flix.dev/annotations.html)を参照するか、[翻訳にご協力](https://github.com/flix-jp/book/edit/master/src/annotations.md)ください。

Flix は、限られた組み込みの注釈(Annotation)の集合をサポートしています。

例えば、`@Test` 注釈は関数をテストとしてマークします。テストフレームワークはそのような関数をすべて実行し、合格したかどうかを報告します:

```flix
@Test
def testSum01(): Unit \ Assert =
Assert.assertEq(expected = 6, sum(1 :: 2 :: 3 :: Nil, 0))
```

もう一つの例として、`@Tailrec` 注釈は、関数内のすべての再帰呼び出しが末尾呼び出しであることをコンパイラに検証させます。下記の `sum` 関数は、再帰呼び出しが関数の最後に行われる処理であるため、このチェックに合格します:

```flix
@Tailrec
def sum(l: List[Int32], acc: Int32): Int32 = match l {
case Nil => acc
case x :: xs => sum(xs, acc + x)
}
```

Flix には、次の組み込み注釈があります:

| 注釈 | 意味 |
|---------------------|-------------------------------------------------------------------------------------------------------------|
| `@Test` | 関数をテストとして実行します。[テストフレームワーク](./test-framework.md)を参照してください。 |
| `@Skip` | `@Test` 関数をスキップします。テストは実行されず、スキップとして報告されます。 |
| `@DefaultHandler` | エフェクトのデフォルトハンドラであることを示します。[デフォルトハンドラ](./default-handlers.md)を参照してください。 |
| `@Tailrec` | 自己再帰呼び出しがすべて末尾呼び出しであることを検証します。[末尾再帰](./tail-recursion.md)を参照してください。 |
| `@Terminates` | 関数が構造的再帰であることを検証します。[停止性検査](./termination-checking.md)を参照してください。 |
| `@Inline` | コンパイラに関数を常にインライン化させます。 |
| `@DontInline` | コンパイラに関数を決してインライン化させません。 |
| `@Deprecated` | その宣言が非推奨であることを文書化します。 |
| `@Experimental` | その宣言が予告なく変更または削除される可能性があることを文書化します。 |
| `@Lazy` | その関数が遅延評価を使用することを文書化します。 |
| `@LazyWhenPure` | 純粋な関数が与えられた場合に遅延評価を使用することを文書化します。[純粋性リフレクション](./purity-reflection.md)を参照してください。 |
| `@Parallel` | その関数が並列評価を使用することを文書化します。 |
| `@ParallelWhenPure` | 純粋な関数が与えられた場合に並列評価を使用することを文書化します。[純粋性リフレクション](./purity-reflection.md)を参照してください。 |

最後の6つの注釈はドキュメント用です。これらは API ドキュメントやエディタ上のヒントとして表示されますが、コンパイラが関数をどのように変換するかには影響しません。

> **注意:** Flix には `@Override` 注釈はありません。トレイトのデフォルト実装を上書きするインスタンスは、代わりに `redef` キーワードで関数をマークします。

<!--
# Annotations

Flix supports a limited set of built-in annotations.

For example, the `@Test` annotation marks a function as a test. The test
framework runs every such function and reports whether it passed:

```flix
@Test
def testSum01(): Unit \ Assert =
Assert.assertEq(expected = 6, sum(1 :: 2 :: 3 :: Nil, 0))
```

As another example, the `@Tailrec` annotation asks the compiler to verify that
every recursive call in a function is a tail call. The `sum` function below
passes the check, because the recursive call is the last thing it does:

```flix
@Tailrec
def sum(l: List[Int32], acc: Int32): Int32 = match l {
case Nil => acc
case x :: xs => sum(xs, acc + x)
}
```

Flix has the following built-in annotations:

| Annotation | Meaning |
|---------------------|------------------------------------------------------------------------------------------------------------------------|
| `@Test` | Runs the function as a test. See [Test Framework](./test-framework.md). |
| `@Skip` | Skips a `@Test` function. The test is reported as skipped, not run. |
| `@DefaultHandler` | Marks the default handler of an effect. See [Default Handlers](./default-handlers.md). |
| `@Tailrec` | Verifies that every self-recursive call is a tail call. See [Tail Recursion](./tail-recursion.md). |
| `@Terminates` | Verifies that the function is structurally recursive. See [Termination Checking](./termination-checking.md). |
| `@Inline` | Makes the compiler always inline the function. |
| `@DontInline` | Makes the compiler never inline the function. |
| `@Deprecated` | Documents that the declaration is deprecated. |
| `@Experimental` | Documents that the declaration may change or be removed without warning. |
| `@Lazy` | Documents that the function uses lazy evaluation. |
| `@LazyWhenPure` | Documents that the function uses lazy evaluation when given a pure function. See [Purity Reflection](./purity-reflection.md). |
| `@Parallel` | Documents that the function uses parallel evaluation. |
| `@ParallelWhenPure` | Documents that the function uses parallel evaluation when given a pure function. See [Purity Reflection](./purity-reflection.md). |

The last six annotations are documentation. They are shown in the API docs and
as hints in the editor, but they do not change how the compiler translates the
function.

> **Note:** Flix has no `@Override` annotation. An instance that overrides a
> default implementation from its trait marks the function with the `redef`
> keyword instead.
-->
2 changes: 2 additions & 0 deletions src/build-and-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Flix プロジェクトは、`flix.toml` マニフェスト、`src` 内の Flix
| `run` | プロジェクトの `main` を実行します。 |
| `test` | プロジェクトのすべてのテストを実行します。 |
| `doc` | プロジェクトの API ドキュメントを生成します。 |
| `format` | プロジェクトのソースコードを整形します。 |
| `stat` | プロジェクトに関する統計情報を表示します。 |
| `build` | プロジェクト全体をコンパイルします。 |
| `build-classes` | プロジェクトを Java クラスファイルにコンパイルします。 |
Expand Down Expand Up @@ -74,6 +75,7 @@ every test.
| `run` | runs `main` in the project. |
| `test` | runs all tests in the project. |
| `doc` | generates API documentation for the project. |
| `format` | formats the source code of the project. |
| `stat` | prints statistics about the project. |
| `build` | compiles the entire project. |
| `build-classes` | compiles the project to Java class files. |
Expand Down
46 changes: 46 additions & 0 deletions src/checking-running-and-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,28 @@ build

このドキュメントは、`build/doc/index.html` をブラウザで開くことで読めます。

## ソースコードの整形

`format` コマンドを使うと、プロジェクトのソースコードを整形できます。このコマンドは、`src` と `test` 内のすべてのファイルをその場で書き換えます。`src/Main.flix` が次のような内容であるとき:

```flix
def main( ) : Unit \ IO =
println( "Hello World!" )

def add(x:Int32,y:Int32):Int32=x+y
```

`format` を実行した後は次のようになります:

```flix
def main(): Unit \ IO =
println("Hello World!")

def add(x: Int32, y: Int32): Int32 = x + y
```

プロジェクトがコンパイルできない場合、`format` はエラーを報告し、ファイルには手を加えません。

## 統計情報の表示

`stat` コマンドを使うと、プロジェクトに関する統計情報を表示できます:
Expand Down Expand Up @@ -185,6 +207,30 @@ build

We read it by opening `build/doc/index.html` in a browser.

## Formatting the Source Code

We can format the source code of the project with the `format` command. The
command rewrites every file in `src` and `test` in place. If `src/Main.flix` reads:

```flix
def main( ) : Unit \ IO =
println( "Hello World!" )

def add(x:Int32,y:Int32):Int32=x+y
```

then after `format` it reads:

```flix
def main(): Unit \ IO =
println("Hello World!")

def add(x: Int32, y: Int32): Int32 = x + y
```

If the project does not compile, `format` reports the errors and leaves the
files untouched.

## Printing Statistics

We can print statistics about the project with the `stat` command:
Expand Down
12 changes: 6 additions & 6 deletions src/common-problems.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ eff Emit[t] {
def emit(x: t): Unit
}

def f(): Unit \ Emit[Int32] + Emit[String] =
def f(): Unit \ { Emit[Int32], Emit[String] } =
Emit.emit(42);
Emit.emit("Hello")
```
Expand All @@ -132,7 +132,7 @@ Flix コンパイラは次のように報告します:

>> Mismatched type arguments for effect 'Emit': 'Int32' and 'String'.

5 | def f(): Unit \ Emit[Int32] + Emit[String] =
5 | def f(): Unit \ { Emit[Int32], Emit[String] } =
^^^^^^^^^^^^
mismatched effect type argument.

Expand Down Expand Up @@ -273,7 +273,7 @@ eff Emit[t] {
def emit(x: t): Unit
}

def f(): Unit \ Emit[Int32] + Emit[String] =
def f(): Unit \ { Emit[Int32], Emit[String] } =
Emit.emit(42);
Emit.emit("Hello")
```
Expand All @@ -285,9 +285,9 @@ The Flix compiler reports:

>> Mismatched type arguments for effect 'Emit': 'Int32' and 'String'.

5 | def f(): Unit \ Emit[Int32] + Emit[String] =
^^^^^^^^^^^^
mismatched effect type argument.
5 | def f(): Unit \ { Emit[Int32], Emit[String] } =
^^^^^^^^^^^^
mismatched effect type argument.

The effect 'Emit' is used with different types for its 1st type parameter 't'.

Expand Down
20 changes: 10 additions & 10 deletions src/concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ def main(): Unit \ IO =
チャネルを介してメッセージを送受信する例を示します:

```flix
def main(): Int32 \ {Chan, NonDet, IO} = region rc {
def main(): Int32 \ { Chan, NonDet, IO } = region rc {
let (tx, rx) = Channel.unbuffered();
spawn Channel.send(42, tx) @ rc;
Channel.recv(rx)
Expand All @@ -66,7 +66,7 @@ def meow(tx: Sender[String]): Unit \ Chan =
def woof(tx: Sender[String]): Unit \ Chan =
Channel.send("Woof!", tx)

def main(): Unit \ {Chan, NonDet, IO} = region rc {
def main(): Unit \ { Chan, NonDet, IO } = region rc {
let (tx1, rx1) = Channel.buffered(1);
let (tx2, rx2) = Channel.buffered(1);
spawn meow(tx1) @ rc;
Expand All @@ -85,7 +85,7 @@ def main(): Unit \ {Chan, NonDet, IO} = region rc {
場合によっては、メッセージが届くまでブロックして、永遠に待ち続けるかもしれない状況を避けたいことがあります。そのような場合は、メッセージがすぐに利用できないときに代わりのアクションを取りたくなります。これは、以下に示すように*デフォルトケース(Default case)*で実現できます:

```flix
def main(): String \ {Chan, NonDet} = region rc {
def main(): String \ { Chan, NonDet } = region rc {
let (_, rx1) = Channel.buffered(1);
let (_, rx2) = Channel.buffered(1);
select {
Expand All @@ -105,12 +105,12 @@ def main(): String \ {Chan, NonDet} = region rc {
例えば、次のプログラムには、チャネルにメッセージを送るまでに1分かかる遅い関数がありますが、`select` 式は `Channel.timeout` を利用して、`5` 秒だけ待って諦めるようになっています:

```flix
def slow(tx: Sender[String]): Unit \ {Chan, NonDet, IO} =
def slow(tx: Sender[String]): Unit \ { Chan, NonDet, IO } =
let delay = Channel.timeout(60, Time.TimeUnit.Seconds);
Channel.recv(delay);
Channel.send("I am very slow", tx)

def main(): Unit \ {Chan, NonDet, IO} = region rc {
def main(): Unit \ { Chan, NonDet, IO } = region rc {
let (tx, rx) = Channel.buffered(1);
spawn slow(tx) @ rc;
let timeout = Channel.timeout(5, Time.TimeUnit.Seconds);
Expand Down Expand Up @@ -193,7 +193,7 @@ Here is an example of sending and receiving a message
over a channel:

```flix
def main(): Int32 \ {Chan, NonDet, IO} = region rc {
def main(): Int32 \ { Chan, NonDet, IO } = region rc {
let (tx, rx) = Channel.unbuffered();
spawn Channel.send(42, tx) @ rc;
Channel.recv(rx)
Expand Down Expand Up @@ -223,7 +223,7 @@ def meow(tx: Sender[String]): Unit \ Chan =
def woof(tx: Sender[String]): Unit \ Chan =
Channel.send("Woof!", tx)

def main(): Unit \ {Chan, NonDet, IO} = region rc {
def main(): Unit \ { Chan, NonDet, IO } = region rc {
let (tx1, rx1) = Channel.buffered(1);
let (tx2, rx2) = Channel.buffered(1);
spawn meow(tx1) @ rc;
Expand All @@ -249,7 +249,7 @@ We can achieve this with a _default case_ as shown
below:

```flix
def main(): String \ {Chan, NonDet} = region rc {
def main(): String \ { Chan, NonDet } = region rc {
let (_, rx1) = Channel.buffered(1);
let (_, rx2) = Channel.buffered(1);
select {
Expand Down Expand Up @@ -280,12 +280,12 @@ a channel, but the `select` expression relies on
giving up:

```flix
def slow(tx: Sender[String]): Unit \ {Chan, NonDet, IO} =
def slow(tx: Sender[String]): Unit \ { Chan, NonDet, IO } =
let delay = Channel.timeout(60, Time.TimeUnit.Seconds);
Channel.recv(delay);
Channel.send("I am very slow", tx)

def main(): Unit \ {Chan, NonDet, IO} = region rc {
def main(): Unit \ { Chan, NonDet, IO } = region rc {
let (tx, rx) = Channel.buffered(1);
spawn slow(tx) @ rc;
let timeout = Channel.timeout(5, Time.TimeUnit.Seconds);
Expand Down
Loading
Loading