Essa página é direcionada a programadores Shell que estão interessados em fazer uma função nos moldes das Funções ZZ.

Siga o roteiro aqui descrito e nos envie sua função. Ela poderá fazer parte do pacote oficial das Funções ZZ.

1. Faça um shell script normal

Esqueça Funções ZZ por enquanto. Primeiro faça o seu programa funcionar como um script Shell normal. Preocupe-se em testar situações inesperadas e tente antecipar erros do usuário para certificar-se que seu programa não contém bugs.

2. Coloque seu script numa função

Tudo funcionando? Então agora coloque todo o seu script dentro de uma função e declare todas as variáveis utilizadas como locais.

Supondo que o seu script é o "chaves.sh", com este conteúdo:

#!/bin/bash

mensagem="Foi sem querer querendo..."
repita=3

i=0
while [ $i -lt $repita ]
do
        echo "$mensagem"
        i=$((i+1))
done

Ele deve ficar assim:

#!/bin/bash

chaves ()
{ 
	local mensagem="Foi sem querer querendo..."
	local repita=3
	local i=0

	while [ $i -lt $repita ]
	do
		echo "$mensagem"
		i=$((i+1))
	done
}

chaves "$@"

Note que o comando "local" é usando antes da declaração de cada variável. NÃO use variáveis globais dentro de funções.

A função foi declarada e a última linha é a sua chamada. Então como a lógica não foi alterada, o programa continua funcionando da mesma maneira. Se não estiver, reveja os passos e o deixe funcional.

3. Transforme a função numa ZZ

#!/bin/bash

source /usr/bin/funcoeszz   # inclui o ambiente ZZ
ZZPATH=$PWD/chaves.sh       # o PATH desse script

# ----------------------------------------------------------------------------
# Repete a fala do Chaves.
# Uso: zzchaves
# Ex.: zzchaves
#
# Autor: Fulano da Silva <fulano (a) dominio com>
# Versão: 1
# Licença: GPL
# ----------------------------------------------------------------------------
zzchaves ()
{

	zzzz -h chaves $1 && return

	local mensagem="Foi sem querer querendo..."
	local repita=3
	local i=0

	while [ $i -lt $repita ]
	do
		echo $mensagem
		i=$((i+1))
	done
}

Acompanhe o que foi feito:

• As Funções ZZ originais foram incluídas no script, com o comando "source". Assim simulamos o "ambiente ZZ" em nosso script.

• Redefinimos a variável ZZPATH para o caminho completo de nosso script. Isso é necessário para o funcionamento do --help.

• O prefixo "zz" foi adicionado ao nome da função, ficando zzchaves.

• A chamada à função que existia na última linha foi retirada. Agora chamaremos a função diretamente pela linha de comando.

• Foi adicionada uma chamada à função "zzzz" na primeira linha da nossa função. Essa linha é sempre igual, mudando apenas o nome da função. Essa linha serve para que funcione o --help de sua função.

• Por falar em --help, notou que foram adicionados comentários antes da função? É desses comentários que o texto de ajuda é extraído. É um formato padrão que deve ser seguido à risca. Na dúvida copie e cole um já existente e somente altere o texto.
  Descrição do formato:
  1. Uma linha separadora com "# ----------------"
  2. A URL do site pesquisado (se aplicável)
  3. A descrição do que faz a função, em uma linha, com ponto final.
  4. Podem haver linhas extras para detalhar melhor a função
  5. A linha com a sintaxe de uso "# Uso: zz...
  6. A linha com o exemplo de uso "# Ex.: zz...
  7. A linha vazia
  8. A linha com as informações do autor (nome completo e e-mail/site/twitter)
  9. A linha com a versão da função (número inteiro e seqüencial, inicia em 1)
  10. A linha com a licença da função
  11. Uma linha separadora com "# ----------------"

4. Corra para o abraço!

$ source chaves.sh 
$ zzchaves
Foi sem querer querendo...
Foi sem querer querendo...
Foi sem querer querendo...
$ zzchaves -h

Repete a fala do Chaves
Autor: Fulano da Silva <fulano (a) dominio com>
Versão: 1
Uso: zzchaves
Ex.: zzchaves

$

:)

5. Disponibilize para a comunidade

Sua função pode ser útil para outras pessoas? Então a envie para nós!

• Mande um e-mail para o Aurelio (verde (a) aurelio net) e peça a inclusão da sua conta do Google no projeto das Funções ZZ lá no Google Code.

• Quando receber a resposta, adicione sua função nova no SVN, seguindo estas instruções.

• Pronto! Sua função já está disponível para todos a utilizarem.

Dicas

• Procure escolher um nome descritivo e curto para a função.

• Dê um nome em português para a sua função, porém não utilize acentuação, hífen, underscore, pontuação nem letras maiúsculas. Use apenas a-z e 0-9.

• Use somente letras minúsculas para as variáveis locais da função. O nome da variável pode ser em português ou inglês. Use preferencialmente o português (sem acentos!).

• Se sua função for de tradução ou pesquisa em dicionários, seu prefixo deve ser zzdic.

• Se for baixar informações da Internet, não chame o lynx diretamente, use as variáveis $ZZWWWDUMP (página formatada) e $ZZWWWHTML (fontes).

• Não faça funções interativas. Todas as Funções ZZ devem funcionar sem necessitar de intervenção do usuário.

• Se sua função precisar de opções de linha de comando, siga o formato GNU, com opções curtas (-a, -e) e/ou longas (--atualiza).

• Sua função deve ser escrita para o shell Bash. Sem exceções.

• Evite ao máximo usar comandos específicos de um sistema operacional. Lembre-se que as funções rodam em Linux, UNIX, Mac OS X e até no Windows (via Cygwin). Use os comandos padrão (sed, grep, find) que ela rodará em qualquer máquina.

• Não use código exclusivo do Bash versão 2.x. As funções ainda mantém compatibilidade com o Bash 1.x. Ou seja, não use: arrays, ==, ${!var}, ${var/isso/aquilo}, ${var:1:3}

• Ao submeter a sua função, deixe o código corretamente alinhado ("identado"). Basta olhar as funções atuais e fazer igual. Assim você facilita o entendimento do seu código para os leitores.

• Coloque comentários para esclarecer trechos difíceis do código!

• Procure limitar as linhas a 78 colunas no máximo. Quebre os comandos ou use variáveis para tornar as linhas mais curtas.

• Não esqueça de colocar as informações de autoria e versão da função.

« Anterior Próxima »