Projeto de funções com escopo local e códigos de retorno

No Bash, as variáveis são globais por padrão. Uma variável definida dentro de uma função escapa para o escopo de quem a chamou, a menos que você a declare explicitamente como local. Essa é uma fonte comum de erros sutis em scripts do shell.

• Funções sem local podem substituir silenciosamente variáveis de quem as chamou.
• As variáveis local são destruídas quando a função retorna.
• Limites de escopo bem definidos tornam as funções reutilizáveis e testáveis de forma isolada.

Nesta lição, você aprenderá a escrever funções autocontidas: elas usam variáveis local, comunicam resultados por meio de códigos de saída e printf e nunca dependem de um estado global implícito.

Este é um exemplo concreto de vazamento de variável global. A função set_name define uma variável chamada result, sobrescrevendo silenciosamente a própria variável result do chamador.

Execute este script e observe a saída inesperada — a variável result do chamador desaparece depois da chamada da função.

O comando interno local restringe o escopo de uma variável à função envolvente e a quaisquer funções que ela chame. Fora da função, a variável fica indefinida ou mantém seu valor anterior.

• local varname — declara sem atribuir.
• local varname="value" — declara e atribui em uma única etapa.
• local -i count=0 — declara uma variável local de tipo inteiro.
• local -r PI=3.14159 — declara uma constante local somente para leitura.

Boa prática: declare como local todas as variáveis dentro de uma função, a menos que precise intencionalmente que sejam globais.

As funções do Bash não podem usar return para retornar strings — return apenas define um status de saída inteiro (0–255). Por convenção:

• return 0 — sucesso
• return 1 (ou qualquer valor diferente de zero) — falha

O chamador lê o status de saída por meio de $? imediatamente após a chamada ou usa a função diretamente em uma condição if. Os códigos de saída são a forma idiomática de sinalizar sucesso ou falha de uma função.

Quando uma função precisa retornar um resultado de string, o padrão é imprimir na saída padrão e capturar o valor com a substituição de comando $(). É preferível usar printf em vez de echo porque:

• printf não acrescenta uma nova linha final por padrão (a menos que você inclua \n).
• O comportamento de printf é consistente e definido pelo POSIX; echo varia entre os interpretadores de comandos.
• A substituição de comando remove novas linhas finais, portanto printf '%s' "$value" é preciso.

Uma função bem projetada pode tanto imprimir um resultado (em caso de sucesso) quanto sinalizar uma falha (por meio do código de saída) ao mesmo tempo. O chamador decide o que fazer com base no código de saída antes de confiar na saída.

O padrão abaixo é usado amplamente em bibliotecas Bash reais:

• Em caso de sucesso: use printf para imprimir o resultado e return 0.
• Em caso de falha: escreva um diagnóstico na saída de erro (não na saída padrão) e use return 1.
• Escrever erros na saída de erro mantém a saída padrão limpa para o encadeamento.

Recursão é uma das demonstrações mais claras de por que local é essencial. Cada chamada recursiva recebe uma cópia independente de cada variável local na pilha de chamadas. Sem local, cada chamada sobrescreveria a mesma variável global e produziria resultados incorretos.

A função fatorial abaixo é segura porque n e sub são locais a cada quadro da pilha.

A substituição de comando $() é executada em um subshell. Qualquer atribuição de variável feita dentro dele fica invisível para o interpretador de comandos pai. Quando precisar que uma função escreva em uma variável fornecida pelo chamador sem usar um subshell, use uma referência de nome (local -n), disponível no Bash 4.3+.

• local -n ref="$1" transforma ref em um alias da variável cujo nome está armazenado em $1.
• Atribuir um valor a ref dentro da função altera diretamente a variável do chamador.
• Isso evita um subshell e, ao mesmo tempo, mantém os detalhes da implementação locais.

Projetos Bash reais dividem funções reutilizáveis em arquivos de biblioteca, carregados por scripts com source (ou com o operador ponto .). Boas regras de projeto para bibliotecas:

• Toda variável dentro de uma função de biblioteca deve ser local.
• Funções de biblioteca nunca usam exit — elas usam return, para que o chamador continue em execução.
• Use um prefixo de espaço de nomes consistente (por exemplo, str_, log_) para evitar conflitos de nomes.
• Evite o carregamento duplicado usando uma variável sentinela.

Abaixo está uma biblioteca mínima de utilitários de strings que segue essas convenções.

As funções que recebem argumentos devem validá-los cedo e retornar um código de saída específico quando a entrada for inválida. Esse padrão é chamado de cláusula de guarda — falhe rapidamente e de forma clara.

• Verifique a quantidade de argumentos com $#.
• Valide os tipos ou formatos antes de realizar qualquer trabalho.
• Imprima mensagens de diagnóstico somente na saída de erro, nunca na saída padrão.
• Use códigos de retorno diferentes de zero (por exemplo, 1 = argumentos incorretos, 2 = arquivo não encontrado) para que os chamadores possam reagir de forma diferente a cada modo de falha.

Aqui está um script completo e independente que demonstra todos os conceitos desta lição funcionando em conjunto:

• Variáveis local em todas as funções.
• Códigos de saída para sinalizar sucesso ou falha.
• printf para comunicar resultados de strings.
• Erros escritos na saída de erro e resultados na saída padrão.
• Cláusulas de guarda para validação de argumentos.

Observe o fluxo: parse_version extrai os dados, version_ge faz a comparação e main usa ambos de forma organizada.

Considere a seguinte função Bash. Qual é a forma correta de capturar seu resultado de string no chamador e qual afirmação sobre a variável tmp é verdadeira?

transform() {
    local tmp="${1,,}"   # lowercase
    printf '%s' "$tmp"
    return 0
}

Nesta lição, você aprendeu a escrever funções Bash organizadas, combináveis e seguras:

• Use sempre local para as variáveis dentro das funções, a fim de evitar poluir o escopo do chamador.
• Use códigos de saída (return 0/1/N) para sinalizar sucesso ou falha — eles se integram naturalmente a if, && e ||.
• Use printf na saída padrão para comunicar resultados de strings; capture-os com $() no chamador.
• Escreva os erros na saída de erro (>&2) para manter a saída padrão limpa para o fluxo de dados e o encadeamento.
• Use local -n (referência de nome) quando precisar escrever em uma variável fornecida pelo chamador sem o custo de um subshell.
• Cláusulas de guarda (validar os argumentos cedo e retornar imediatamente quando a entrada for inválida) tornam as funções robustas e autoexplicativas.
• Arquivos de biblioteca devem ser carregados, usar prefixos de espaço de nomes, nunca chamar exit e evitar o carregamento duplicado.

Dominar esses padrões é o que diferencia scripts frágeis e feitos para uma única ocasião de bases de código Bash profissionais e fáceis de manter.