O que é um heredograma na prática
Heredygrama é o nome que alguns desenvolvedores dão ao heredoc, aquele recurso do shell que permite escrever strings multiline dentro de scripts. A sintaxe original vem do ksh e foi adotada por bash, zsh e dash. A forma mais simples é começar com um delimitador, escrever o conteúdo e fechar com o mesmo delimitador na linha seguinte. A gente costuma chamar de heredoc em inglês, mas em português técnico já vi heredograma, heredocumento e até "aqui-doc". O importante é que isso resolve um problema real: injetar blocos de texto em comandos sem depender de echo encadeado ou arquivos temporários.
como usar um heredograma passo a passo
O comando começa com o operador menos conhecido do dia a dia: o símbolo de menção e citação. Vou explicar a estrutura básica e depois um exemplo que realmente usei no campo. No bash, a sintaxe padrão é esta aqui:
comando << DELIMITADOR O conteúdo segue na linha de baixo até que você repita o mesmo DELIMITADOR colado na coluna 1. Sem espaços antes. Isso é importante porque se colocar tabulação ou espaço antes do fechamento, o shell não reconhece e o comando trava.
Vamos a um exemplo concreto. Imagine que você precisa gerar um arquivo JSON para configurar um serviço e não quer depender de ferramentas externas. O heredograma resolve isso em uma linha: cat << EOF > /tmp/config.json
{ "servidor": "db.internal",
"porta": 5432, "timeout": 30
} EOF
Isso cria o arquivo instantaneamente. O cat recebe a entrada padrão do heredoc e redireciona para o arquivo. Sem variáveis, sem subshell, sem dependência.
variantes que quase ninguém explica
Tem dois comportamentos que fazem diferença prática e que raramente aparecem em tutoriais básicos. O primeiro é o hífen antes do delimitador: <<-. Quando você coloca o hífen, o shell remove tabs de indentação do conteúdo. Isso é útil quando o heredoc está dentro de uma função com recuo. O segundo é a aspa no delimitador. Se você escrever <<"EOF" com aspas, o shell não expande variáveis nem comandos substitutos no conteúdo. Sem aspas, a expansão acontece normalmente. Isso é um detalhe que já me custou duas horas de debugging numa vez que um script estava substituindo variáveis que eu não queria que fossem substituídas.
Na prática, eu uso a versão com aspas quando preciso gerar configs sensíveis onde variáveis do sistema não podem ser interpoladas. E uso a versão sem hífen quando o heredoc está no nível raiz do script.
problemas comuns e como contornar
O erro mais frequente é o delimitador de fechamento não estar colado na coluna 1. Se você colocar qualquer espaço antes, o shell continua esperando e o script fica pendurado. Outra armadilha é usar caracteres especiais no delimitador. Delimitadores como $EOF ou EOF! podem causar comportamento inesperado dependendo da versão do shell. O delimitador ideal é uma palavra simples, sem caracteres especiais, maiúsculas. Eu uso geralmente "HERE" ou "END" em scripts de produção. Evite "EOF" se o conteúdo do script puder conter a string EOF como dado legítimo. Nesse caso, um delimitador mais único como "CFG_END" evita colisões.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Outro problema prático é o heredoc dentro de loops. A cada iteração, o shell reabre a entrada e isso pode adicionar sobrecarga em loops grandes. Se você estiver processando milhares de linhas, considere usar here-string (<<<) ou redirectionamento de arquivo em vez de heredoc dentro do loop.
quando não usar heredograma
O heredoc não é bala de prata. Para strings pequenas de uma linha, use aspas simples ou duplas normalmente. O overhead de parsing do heredoc é insignificante em scripts pequenos, mas em scripts que rodam a cada segundo em loops apertados, a leitura do conteúdo com heredoc pode adicionar latência mensurável. Também evite heredoc em scripts que precisam ser compatíveis com sh primitivo em sistemas embarcados. O sh padrão do Alpine Linux e de algumas imagens Docker não suporta <<- com hífen. Se o script precisa rodar em ambientes restritos, use a sintaxe básica sem hífen e sem expansão de variáveis.
Para geração de arquivos grandes, considere usar ferramentas como python ou jq em vez de heredoc. O heredoc é limitado a strings literais e não oferece formatação estruturada. Se o conteúdo precisa ser válido JSON ou XML com validação, uma ferramenta dedicada corta o tempo de processamento de 2 horas para cerca de 15 minutos, dependendo do seu setup.
exemplo avançado com heredygrama
Vou mostrar um caso real que encontrei recentemente. Precisei gerar um certificado TLS autoassinado em um script de deploy que rodava em containers efêmeros. O heredoc resolvia a geração do CSR, mas o problema era que o delimitador estava dentro de uma função com indentação de 4 tabs. A solução foi usar <<- CERT_END com o hífen para remover a indentação automaticamente. Sem o hífen, o certificado ficava com espaços no início e o openssl rejeitava. Foi um detalhe que me levou 40 minutos para identificar porque o erro não era óbvio no log.
O código final ficou assim: generate_csr() {
openssl req <<- CERT_END -new -newkey rsa:2048 -nodes
-keyout /tmp/key.pem -out /tmp/csr.pem -subj "/CN=${1}"
CERT_END }
O hífen antes do delimitador removeu as 4 tabs de indentação e o openssl processou o CSR sem reclamar. Sem o hífen, o subj ficava com espaços no início e o comando travava.
alternativas ao heredoc
Se o heredoc não se encaixa no seu caso, existem alternativas. O Python com strings triplas permite múltiplas linhas sem depender do shell. O jq é ideal para geração de JSON estruturado. O printf com formato permite controle granular sobre quebras de linha e escape de caracteres. Em scripts de produção, eu geralmente prefiro usar Python para geração de configs complexas. O heredoc é útil para situações simples onde o conteúdo é estático e não precisa de validação. Para conteúdo dinâmico com interpolação de variáveis, o printf ou a expansão direta do shell são mais controláveis.
O heredograma, ou heredoc, é um recurso prático do shell que resolve um problema específico: injetar strings multiline sem arquivos temporários. Conhecer as variantess, os problemas comuns e as limitações permite usar o recurso de forma eficiente. O delimitador correto, a indentação e a versão do shell são fatores que determinam se o heredoc vai funcionar ou vai gerar dor de cabeça.
