Gerador de Diagramas em Arte ASCII com PlantUML

Visão Geral

Crie diagramas em arte ASCII baseados em texto usando o PlantUML. Perfeito para documentação em ambientes de terminal, arquivos README, e-mails ou qualquer cenário onde diagramas gráficos não sejam adequados.

O que é Arte ASCII do PlantUML?

O PlantUML pode gerar diagramas como texto puro (arte ASCII) em vez de imagens. Isso é útil para:

• Fluxos de trabalho baseados em terminal
• Commits/PRs do Git sem suporte a imagens
• Documentação que precisa ser versionada
• Ambientes onde ferramentas gráficas não estão disponíveis

Instalação

# 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

Formatos de Saída

Fluxo de Trabalho Básico

1. Crie o Arquivo de Diagrama PlantUML

@startuml
participant Bob
actor Alice

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

2. Gere a Arte 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. Visualize a Saída

A saída é salva como diagram.atxt (ASCII) ou diagram.utxt (Unicode).

Tipos de Diagrama Suportados

Diagrama de Sequência

@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

Diagrama 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

Diagrama de Atividade

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

Diagrama de Estado

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

Diagrama de Componente

@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

Diagrama de Casos de Uso

@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

Diagrama de Implantação

@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

Opções de Linha de Comando

# 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

Integração com Tarefa Ant

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

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

Dicas para Melhores Diagramas ASCII

1. Mantenha a simplicidade: Diagramas complexos não são bem renderizados em ASCII
2. Rótulos curtos: Textos longos quebram o alinhamento ASCII
3. Use Unicode (-utxt): Melhor qualidade visual com caracteres de desenho de caixa
4. Teste antes de compartilhar: Verifique no terminal com fonte monoespaçada
5. Considere alternativas: Para diagramas complexos, use Mermaid.js ou graphviz

Comparação de Saída de Exemplo

ASCII Padrão (-txt):

     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   olá        |
      |------------->|
      |              |

…