plantuml-ascii

PlantUML ASCII アート図生成ツール

概要

PlantUML を使用して、テキストベースの ASCII アート図を作成します。ターミナル環境でのドキュメント、README ファイル、メールなど、グラフィカルな図が適さないあらゆるシナリオに最適です。

PlantUML ASCII アートとは？

PlantUML は、画像の代わりにプレーンテキスト（ASCII アート）として図を生成できます。これは以下のような場合に便利です：

• ターミナルベースのワークフロー
• 画像をサポートしない Git コミット/PR
• バージョン管理が必要なドキュメント
• グラフィカルツールが利用できない環境

インストール

# macOS
brew install plantuml

# Linux (varies by distro)
sudo apt-get install plantuml  # Ubuntu/Debian
sudo yum install plantuml      # RHEL/CentOS

# Or download JAR directly
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

出力形式

フラグ	形式	説明
-txt	ASCII	純粋な ASCII 文字
-utxt	Unicode ASCII	罫線文字で強化

基本的なワークフロー

1. PlantUML 図ファイルを作成

@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. ASCII アートを生成

# Standard ASCII output
plantuml -txt diagram.puml

# Unicode-enhanced output (better looking)
plantuml -utxt diagram.puml

# Using JAR directly
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml

3. 出力を表示

出力は diagram.atxt（ASCII）または diagram.utxt（Unicode）として保存されます。

サポートされている図の種類

シーケンス図

@startuml
actor User
participant "Web App" as App
database "Database" as DB

User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml

クラス図

@startuml
class User {
  +id: int
  +name: string
  +email: string
  +login(): bool
}

class Order {
  +id: int
  +total: float
  +items: List
  +calculateTotal(): float
}

User "1" -- "*" Order : places
@enduml

アクティビティ図

@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml

ステート図

@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml

コンポーネント図

@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db

client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml

ユースケース図

@startuml
actor "User" as user
actor "Admin" as admin

rectangle "System" {
  user -- (Login)
  user -- (View Profile)
  user -- (Update Settings)
  admin -- (Manage Users)
  admin -- (Configure System)
}
@enduml

配置図

@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2

user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml

コマンドラインオプション

# Specify output directory
plantuml -txt -o ./output diagram.puml

# Process all files in directory
plantuml -txt ./diagrams/

# Include dot files (hidden files)
plantuml -txt -includeDot diagrams/

# Verbose output
plantuml -txt -v diagram.puml

# Specify charset
plantuml -txt -charset UTF-8 diagram.puml

Ant タスクとの統合

<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>

より良い ASCII 図を作成するためのヒント

1. シンプルに保つ：複雑な図は ASCII でうまくレンダリングされません
2. 短いラベル：長いテキストは ASCII の整列を崩します
3. Unicode を使用する（-utxt）：罫線文字でより良い視覚品質が得られます
4. 共有する前にテストする：等幅フォントでターミナルで確認してください
5. 代替案を検討する：複雑な図には Mermaid.js や graphviz を使用してください

出力例の比較

標準 ASCII（-txt）：

     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |

Unicode ASCII（-utxt）：

┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │

クイックリファレンス

# Create sequence diagram in ASCII
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF

plantuml -txt seq.puml
cat seq.atxt

# Create with Unicode
plantuml -utxt seq.puml
cat seq.utxt

トラブルシューティング

問題：Unicode 文字が文字化けする

• 解決策：ターミナルが UTF-8 をサポートし、適切なフォントがあることを確認してください

問題：図がずれて見える

• 解決策：等幅フォント（Courier、Monaco、Consolas）を使用してください

問題：コマンドが見つからない

• 解決策：PlantUML をインストールするか、Java JAR を直接使用してください

問題：出力ファイルが作成されない

• 解決策：ファイルの権限を確認し、PlantUML に書き込みアクセス権があることを確認してください