Metadata-Version: 2.4
Name: dsg-parse
Version: 0.1.0
Summary: Cソースコード解析およびPlantUMLシーケンス図生成ツール
Author-email: dsgp <design.parser@gmail.com>
License: MIT License
        
        Copyright (c) 2026 dsg-p
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/dsg-p/dsgp
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# CtoPlantUML

C言語のソースコードを静的解析し、関数呼び出しの流れをPlantUMLのシーケンス図として自動生成するツールです。

## できること・特徴

- 複数ファイル・複数ディレクトリ構成のCプロジェクトに対応
- if / else if / else の分岐を PlantUML の `alt` / `else` へ変換
- for / while のループを PlantUML の `loop` へ変換
- 関数間の呼び出し・復帰をシーケンス図の活性化（`activate` / `deactivate`）として表現
- ファイルパスごとに `box` で色分け表示
- 同名関数の重複定義を検知し、ログファイルへ記録した上で図中にも `(※ 重複)` として明示
- Cソース中のコメント（`//` および `/* */`）を、シーケンス図のメッセージラベルへ日本語概要として引き継ぐ
- プロジェクト内に定義が見つからない関数呼び出し（外部関数・ライブラリ関数等）は、一律「外部」参加者への往復呼び出しとして表現

## 動作環境

- Python 3系（標準ライブラリのみで動作し、追加のpipパッケージは不要です）
  - 動作確認バージョン: `Python 3.10.6`
- PlantUMLのプレビュー環境（VSCode拡張機能や公式サーバー等、お好みのものをご用意ください）
  - PlantUMLの画像生成にはGraphviz（`dot`コマンド）とJavaランタイムが必要な場合があります
  - 動作確認バージョン:
    - `dot --version` → `graphviz version 15.1.0 (20260618.0150)`
    - `java --version` → `openjdk 21.0.11 2026-04-21 LTS`


## クイックスタート

本ライブラリは、コマンドラインツール（CLI） または Pythonスクリプトからの呼び出し の両方で利用可能です。

以下のようなシンプルなCソース（`test.c`）を例に、動作方法をご紹介します。

```c
#include <stdio.h>

void helper(int value) {
    // 値を2倍にする
    printf("value = %d\n", value * 2);
}

int main(void) {
    int number = 5;
    helper(number);
    return 0;
}
```

---

### 実行方法

用途に合わせて以下のいずれかの方法で実行できます。

#### パターン1: コマンドライン実行（CLI）
インストール後に提供される `c2pu` コマンドを使用します。

```bash
c2pu -d ./prj_test -o output.pu -l duplicate_functions.log -e main
```

#### パターン2: モジュールとしてCLI実行（python -m）
環境に応じてモジュール形式で直接指定して実行します。

```bash
python -m dsgp.c2pu -d ./prj_test -o output.pu -l duplicate_functions.log -e main
```

##### 【CLIで指定可能なオプション】

| オプション | 意味 | デフォルト値 |
|---|---|---|
| `-d`, `--dir` | 解析対象のC言語ソースディレクトリ | `../prj_test` |
| `-o`, `--output` | 出力するPlantUMLファイルのパス | `output.pu` |
| `-l`, `--log` | 重複関数検知ログの出力パス | `duplicate_functions.log` |
| `-e`, `--entry` | シーケンスの起点とする関数名 | `main` |


#### パターン3: Pythonスクリプトから呼び出す
Pythonコード内から `dsgp` モジュールをインポートし、`c2pu()` 関数を実行します。

```python
import dsgp

# 全ての引数を指定して実行する場合
dsgp.c2pu(
    target_directory="./cdir",
    output_file_path="output.pu",
    duplicate_log_file="duplicate_functions.log",
    entry_func_name="main"
)

# デフォルト値を利用してシンプルに実行することも可能です
# dsgp.c2pu(target_directory="./cdir")
```


### 生成例

上記の `test.c` を解析すると、以下のようなPlantUMLシーケンス図が生成されます。

```plantuml
@startuml
actor "Host OS" as host
box "test.c" #FFE4E1
participant "main" as main
participant "helper" as helper
end box
participant "外部" as 外部
host -> main : main()
activate main
main -> helper : helper(number);
activate helper
helper -> 外部 : // 値を2倍にする \n printf("value = %d \n", value * 2);
activate 外部
外部 -> helper : return
deactivate 外部
helper -> main : return;
deactivate helper
main -> host : return 0;
deactivate main
@enduml
```

`printf` は `helper` 関数内で定義されている関数ではないため「外部」参加者への呼び出しとして表現され、Cソース中のコメント `// 値を2倍にする` が、呼び出し行のメッセージラベルの1行目として引き継がれています。


## 処理パイプラインの全体像

`main.py`が以下6段階の処理を順に呼び出す、直列パイプライン構成になっています。

1. **ファイル探索**（`get_all_c_path.py`）：対象ディレクトリ配下の`.c`ファイルを再帰的に収集
2. **構文解析**（`research_func_in_file.py`）：コメント抽出、関数定義の切り出し、ステートメント単位への分解、制御構文のネスト解体
3. **抽象化**（`abstract_ir_generator.py`）：C言語固有の表記を、`ConditionNode` / `LoopNode` / `ActionNode`という言語非依存の中間表現（IR）へ変換
4. **リンク付け**（`abstract_ir_linkers.py`）：関数呼び出しノードに、呼び出し先関数への参照ポインタを付与
5. **スケジューリング**（`abstract_ir_scheduler.py`）：エントリポイント関数を起点に、関数呼び出しを再帰展開し、時系列に平坦化された実行順序を構築
6. **PlantUML出力**（`output_plant_uml.py`）：平坦化された実行順序から`.pu`ファイルを機械的に生成

## 細かな特徴、既知の制約

現時点のコードを確認した限りで判明している細かな特徴、制約です。  
また、ここに記載のないケースで想定外の構文に対しては正しく解析できない可能性があります。

- `switch`文は検知されますが、`case`ごとの個別分岐としては表現されず、`switch(条件式)`という単一のブロックとして図に出力されます
- 関数ポインタ経由の呼び出しや、マクロ経由で間接的に呼ばれる関数呼び出しは追跡できません（呼び出し先の関数名を、呼び出し文字列からの直接的な正規表現マッチングでのみ特定しているため）
- 同一プロジェクト内で同名の関数が複数定義されている場合、最初に見つかった定義のみが採用され、以降の定義は重複としてログに記録されるのみで、呼び出し先としては使用されません
- 再帰呼び出し（自分自身、または循環する呼び出し関係）を検知した場合、図の生成を継続せずエラー終了します
- 関数呼び出しの引数として渡されている式（計算式や別の関数呼び出しの戻り値等）は、シーケンス図上のメッセージラベルとしてそのまま文字列表示されるのみで、評価や意味解釈はされません
