# 通知設計書 3-funs() 非推奨

## 概要

本ドキュメントは、dplyrパッケージにおける`funs()`関数の非推奨警告通知について、その設計仕様を定義するものである。

### 本通知の処理概要

`funs()`関数はdplyr 0.8.0で非推奨となり、`list()`またはラムダ式への移行が推奨されている。この通知は、ユーザーが`funs()`を呼び出した際に、lifecycleパッケージの`deprecate_warn()`関数を通じて詳細な警告メッセージを表示する。

**業務上の目的・背景**：`funs()`関数は、`summarise_at()`、`mutate_at()`などのscoped verbs（範囲指定関数）で使用する関数リストを作成するためのものであった。しかし、この関数は独自の無名関数指定方法を提供しており、purrrや他のtidyverseパッケージで採用されている規約と一貫性がなかった。このため、標準的な`list()`関数やラムダ記法（`~`）への移行が推奨された。

**通知の送信タイミング**：ユーザーがRコード内で`funs()`関数を呼び出した瞬間に、この警告が発生する。`always = TRUE`が設定されているため、毎回警告が表示される（セッション内での抑制なし）。

**通知の受信者**：Rコンソールまたはスクリプトを実行している開発者・データアナリスト。警告メッセージはRの標準警告システムを通じてコンソールに表示される。

**通知内容の概要**：関数が非推奨である旨、代替として`list()`やラムダ式を使用すべき旨、および具体的な移行例が詳細なメッセージとして表示される。

**期待されるアクション**：ユーザーは`funs()`の呼び出しを以下のいずれかに置き換えることが期待される：(1) 単純な名前付きリスト `list(mean = mean, median = median)`、(2) tibble::lst()による自動命名 `tibble::lst(mean, median)`、(3) ラムダ式 `list(~ mean(., trim = .2), ~ median(., na.rm = TRUE))`

## 通知種別

コンソール警告（lifecycle deprecation warning）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数呼び出し時即座に表示） |
| 優先度 | 中（警告レベル） |
| リトライ | 無し（`always = TRUE`のため毎回表示） |

### 送信先決定ロジック

警告メッセージはRの標準出力（stderr）に送信される。受信者の決定は不要であり、関数を呼び出したセッションに対して直接表示される。

## 通知テンプレート

### コンソール警告の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | lifecycle パッケージ |
| 形式 | テキスト（複数行） |

### 本文テンプレート

```
`funs()` was deprecated in dplyr 0.8.0.
i Please use a list of either functions or lambdas:

  # Simple named list:
  list(mean = mean, median = median)

  # Auto named with `tibble::lst()`:
  tibble::lst(mean, median)

  # Using lambdas
  list(~ mean(., trim = .2), ~ median(., na.rm = TRUE))
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | コンソール警告のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード "0.8.0" | Yes |
| what | 非推奨となった関数名 | ハードコード "funs()" | Yes |
| always | 毎回警告を表示するか | ハードコード TRUE | Yes |
| details | 詳細な移行ガイド | ハードコード（複数行） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `funs()`の実行 | 常に | ユーザーがコード内で`funs()`を呼び出すたびに警告表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | `always = TRUE`のため、毎回警告が表示される |
| lifecycle verbosityの設定 | `options(lifecycle_verbosity = "quiet")` で警告を完全に抑制可能 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[funs関数呼び出し] --> B[lifecycle::deprecate_warn実行]
    B --> C[詳細メッセージ生成]
    C --> D[コンソールに警告表示]
    D --> E[引数のquosure化]
    E --> F[as_fun変換ループ]
    F --> G[new_funs作成]
    G --> H[fun_listオブジェクト返却]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースアクセスは発生しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベース更新は発生しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 無効な関数指定 | as_funで変換できない引数が渡された場合 | エラーメッセージを表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 該当なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（ユーザーの関数呼び出しに応じて即座に表示）

## セキュリティ考慮事項

- 個人情報の取り扱い：なし
- 警告メッセージには機密情報は含まれない
- 外部通信は発生しない

## 備考

- `funs()`は`fun_list`クラスのオブジェクトを返す
- 関数は名前、関数オブジェクト、または`.`をダミー引数とした呼び出しとして指定できる
- 無名関数（`function(x) ...`）やpurrr記法（`~ ...`）は`funs()`内では直接サポートされていなかった
- この関数は`@keywords internal`としてマークされており、内部使用を想定
- `always = TRUE`が設定されているため、この警告は非常に強い非推奨を示している

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

`fun_list`クラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | deprec-funs.R | `R/deprec-funs.R` | `fun_list`クラスの定義（66-76行目） |

**読解のコツ**: `fun_list`は`have_name`属性を持つリストであり、各要素はquosure（遅延評価式）として保持される。

#### Step 2: エントリーポイントを理解する

`funs()`関数のエントリーポイントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | deprec-funs.R | `R/deprec-funs.R` | `funs()`関数の定義（38-65行目） |

**主要処理フロー**:
1. **39-55行目**: `lifecycle::deprecate_warn()`の呼び出しと詳細メッセージ
2. **57-58行目**: 引数のquosure化と環境取得
3. **61-63行目**: 各引数を関数に変換するループ
4. **64行目**: `new_funs()`で`fun_list`オブジェクト作成

#### Step 3: 詳細メッセージの構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | deprec-funs.R | `R/deprec-funs.R` | `paste_line()`による複数行メッセージ構築（43-54行目） |

**メッセージ構成**:
- 単純な名前付きリストの例
- `tibble::lst()`を使用した自動命名の例
- ラムダ式を使用した例

#### Step 4: 関数変換ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | deprec-funs.R | `R/deprec-funs.R` | `as_fun()`関数（外部定義） |
| 4-2 | deprec-funs.R | `R/deprec-funs.R` | `new_funs()`関数（66-76行目） |

### プログラム呼び出し階層図

```
funs(...)
    │
    ├─ lifecycle::deprecate_warn()
    │      ├─ paste_line() [詳細メッセージ生成]
    │      └─ 警告表示
    │
    ├─ enquos(...)
    │      └─ 引数をquosureに変換
    │
    ├─ caller_env()
    │      └─ デフォルト環境取得
    │
    ├─ map(dots, as_fun)
    │      └─ 各引数を関数に変換
    │
    └─ new_funs(funs)
           ├─ attr設定 (have_name)
           ├─ exprs_auto_name() [名前の自動生成]
           └─ class設定 ("fun_list")
```

### データフロー図

```
[入力]               [処理]                    [出力]

関数指定 ───────▶ funs()呼び出し ──────────▶ 警告メッセージ（stderr）
(名前/関数/式)           │
                        ▼
               enquos() & map(as_fun) ─────▶ fun_list オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| deprec-funs.R | `R/deprec-funs.R` | ソース | `funs()`と`new_funs()`の定義 |
| colwise-mutate.R | `R/colwise-mutate.R` | ソース | `funs()`の主な使用箇所（scoped verbs） |
| colwise.R | `R/colwise.R` | ソース | colwise関数群の共通処理 |
| NAMESPACE | `NAMESPACE` | 設定 | エクスポート定義 |
