Générateur de diagrammes ASCII Art PlantUML

Aperçu

Créez des diagrammes ASCII art basés sur du texte en utilisant PlantUML. Parfait pour la documentation dans les environnements terminal, les fichiers README, les emails, ou tout scénario où les diagrammes graphiques ne conviennent pas.

Qu'est-ce que PlantUML ASCII Art ?

PlantUML peut générer des diagrammes en texte brut (ASCII art) au lieu d'images. C'est utile pour :

Les workflows basés sur terminal
Les commits/PR Git sans support d'images
La documentation qui doit être versionnée
Les environnements où les outils graphiques ne sont pas disponibles

Installation

# macOS
brew install plantuml

# Linux (varie selon la distribution)
sudo apt-get install plantuml  # Ubuntu/Debian
sudo yum install plantuml      # RHEL/CentOS

# Ou télécharger le JAR directement
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

Formats de sortie

Flag	Format	Description
`-txt`	ASCII	Caractères ASCII purs
`-utxt`	Unicode ASCII	Amélioré avec caractères de boîte

Workflow de base

1. Créer un fichier de diagramme PlantUML

@startuml
participant Bob
actor Alice

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

2. Générer ASCII Art

# Sortie ASCII standard
plantuml -txt diagram.puml

# Sortie améliorée en Unicode (meilleur rendu)
plantuml -utxt diagram.puml

# Utilisation du JAR directement
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml

3. Afficher la sortie

La sortie est sauvegardée en tant que diagram.atxt (ASCII) ou diagram.utxt (Unicode).

Types de diagrammes supportés

Diagramme de séquence

@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

Diagramme de classe

@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

Diagramme d'activité

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

Diagramme d'état

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

Diagramme de composant

@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

Diagramme de cas d'usage

@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

Diagramme de déploiement

@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

Options de ligne de commande

# Spécifier le répertoire de sortie
plantuml -txt -o ./output diagram.puml

# Traiter tous les fichiers du répertoire
plantuml -txt ./diagrams/

# Inclure les fichiers cachés
plantuml -txt -includeDot diagrams/

# Sortie verbose
plantuml -txt -v diagram.puml

# Spécifier le charset
plantuml -txt -charset UTF-8 diagram.puml

Intégration avec tâche Ant

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

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

Conseils pour de meilleurs diagrammes ASCII

Garder simple : Les diagrammes complexes ne s'affichent pas bien en ASCII
Étiquettes courtes : Le texte long casse l'alignement ASCII
Utiliser Unicode (-utxt) : Meilleure qualité visuelle avec caractères de boîte
Tester avant de partager : Vérifier dans le terminal avec police à largeur fixe
Considérer des alternatives : Pour les diagrammes complexes, utiliser Mermaid.js ou graphviz

Comparaison d'exemple de sortie

ASCII standard (-txt) :

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

Unicode ASCII (-utxt) :

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

Référence rapide

# Créer diagramme de séquence en ASCII
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF

plantuml -txt seq.puml
cat seq.atxt

# Créer avec Unicode
plantuml -utxt seq.puml
cat seq.utxt

Dépannage

Problème : Caractères Unicode corrompus

Solution : S'assurer que le terminal supporte UTF-8 et dispose d'une police appropriée

Problème : Diagramme mal aligné

Solution : Utiliser une police à largeur fixe (Courier, Monaco, Consolas)

Problème : Commande non trouvée

Solution : Installer PlantUML ou utiliser le JAR Java directement

Problème : Fichier de sortie non créé

Solution : Vérifier les permissions de fichier, s'assurer que PlantUML a un accès en écriture

plantuml-ascii