<!doctype linuxdoc system>
<article>
<title>Shellmod</title>
<subtitle>Introduo</subtitle>

<sect>O que  shellmod
<p>
	Shellmod  um mdulo do Linuxconf bem como um utilitrio para rodar em mquinas sozinhas.
	Seu objetivo  permitir a escrita simples de outros mdulos e utilitrios Linuxconf
	utilizando sh (/bin/sh, o interpretador shell).

	Os benefcios de se escrever mdulos Linuxconf (ou simplesmente
	utilitrios de administrao) desta forma so:

	<itemize>
	<item>Boa interface: Seu script funcionar tanto em modo texto como
		grfico, com uma aparncia muito melhor do que com um shell script
		comum. Quando usado como um mdulo no Linuxconf, ele tambm
		funcionar em HTML, de forma completamente transparente.
	<item>Simplicidade:  possvel escrever coisas teis em um shell script
		de 10-15 linhas.  possvel transformar um shell script no-interativo
		existente de 10-15 lines em timo script interativo de 15-20 linhas,
		sendo executado em modo texto, grfico e mesmo em HTML.
	<item>Usado como um mdulo, seu script ser capaz de se agregar a vrios
		menus do Linuxconf, fazendo-se totalmente integrado com o esquema
		de administrao.
	<item>No s o script pode aprimorar os menus do Linuxconf, como tambm
		pode participar como co-administrador em alguns dilogos. Isto significa
		que um simples script pode adicionar novos campos no dilogo de contas
		de usurio, por exemplo.
	</itemize>

	O mdulo Linuxconf C++ Normal pode, obviamente, fazer mais coisas, mas os scripts
	oferecem uma boa e eficiente soluo para instalao personalizada e suporte
	no site. Um novo mdulo Linuxconf pode ser desenvolvido com o
	usurio/amigo/cliente olhando por cima de seu ombro.

<sect>Princpios
<p>
	Nesta seo ns veremos o layout bsico de um script shellmod, como us-lo
	e como ele se comunica com o Linuxconf.

<sect1>Componentes do pacote shellmod
<p>
	O pacote shellmod fornece as seguintes partes:

	<itemize>
	<item>O utilitrio shellmod usado para executar o script shellmod sem o Linuxconf.
		Este utilitrio est localizado em /usr/bin.
	<item>O mdulo shellmod que permite ao script shellmod interagir
		com o Linuxconf. Observe que um script shellmod pode ser usado das duas
		formas, sozinho ou embutido no Linuxconf.
	<item>A biblioteca de funes shellmod-lib.sh. Ela est localizada em
		/usr/lib/linuxconf/lib. Ela contm funes de utilitrios que simplificam
		os scripts shellmod. Este arquivo deve ser originado em todos os scripts.
	<item>Um script exemplo.
	<item>Em algum momento, o pacote ir conter alguns scripts de exemplo e um
		browser ser escrito para encontrar com facilidade e testar esses scripts.
		Se voc escreveu algo genrico e til, mande para a lista de discusso do
		Linuxconf, para incluso neste pacote.
	</itemize>

<sect1>Como usar scripts shellmod
<p>
	Um script pode ser utilizado sozinho ou juntamente com o  Linuxconf. Pode ser
	utilizado de ambas as formas.

<sect2>Como um utilitrio sozinho
<p>
	Para executar um script shellmod, voc pode fazer

	<tscreen><verb>
	shellmod rota_do_script [ argumentos ]
	</verb></tscreen>

	Ou se o script iniciar com <tt>#!/usr/bin/shellmod</tt>, voc simplesmente
	o executa como qualquer utilitrio. Observe que em todos os casos, o script
	deve ser executvel (<tt>chmod +x script</tt>).

<sect2>Como um mdulo do Linuxconf
<p>
	Para ser utilizado desta forma, ele deve estar registrado no Linuxconf. Isto  feito
	interativamente ou utilizando uma linha especial de comando. O mdulo shellmod
	registra seu menu de configurao no menu <tt>Sistemas e arquivos de controle</tt>.
	Voc encontrar l um dilogo para registrar seu script. Apenas entre com a rota
	de seu script e mais nada. O script ser visvel ao Linuxconf a partir da prxima
	execuo.

	O script pode ser registrado utilizando a seguinte linha de comando. Isto  til
	especialmente se voc incluir seu script em um pacote e desejar registrar o script
	no Linuxconf como instalao de pacote.
	(Empacotadores RPM devem considerar a grande facilidade em se fazer isto).

	<tscreen><verb>
	linuxconf --modulemain shellmod --setmod rota_do_script
	</verb></tscreen>

	Observe que a construo <tt>linuxconf --modulemain</tt>  a forma normal
	de ceder o controle  linha de comando de um mdulo: o shellmod no 
	diferente.

	Voc pode remover o registro de um script do Linuxconf da seguinte forma:

	<tscreen><verb>
	linuxconf --modulemain shellmod --unsetmod rota_do_script
	</verb></tscreen>

	Observe que a sintaxe acima replica a forma normal (C++) que os mdulos Linuxconf
	podem ser registrados ou removidos do registro, usando as linhas de comando
	<tt>linuxconf --setmod</tt> e <tt>linuxconf --unsetmod</tt>.
	
<sect1>Estrutura de um script shellmod
<p>
	Um script shellmod sempre ter este aspecto:

	<tscreen><verb>
	#!/usr/bin/shellmod
	. /usr/lib/linuxconf/lib/shellmod-lib.sh
	register(){
		# Coloque aqui as chamadas do regmenu e comanager
	}
	# Coloque aqui as vrias funes referenciadas acima
	
	main(){
		# Ns definimos um sub-menu ou um dilogo
	}
	# O script sempre termina com a chamada da funo dispatch function call. Sempre.
	dispatch
	</verb></tscreen>

<sect2>A biblioteca de funes shellmod-lib.sh
<p>
<sect2>A funo register
<p>
	A funo register  necessria se o script for utilizado como um
	mdulo do Linuxconf. Linuxconf chamar a funo esperando que o
	script retorne a lista de menus e dilogos nos quais ele deseja
	registrar. Eis aqui um exemplo de uma funo de registro
	instalando dois sub-menus e um co-administrador (co-manager).

	<tscreen><verb>
	# Registro no menu "miscellaneous service"
	echo regmenu main MENU_MISCSERV \"menu principal do mdulo\"
	# Registro ao final do menu dnsconf
	echo regmenu function2 dnsconf \"Qualquer ttulo\"
	# Registro como co-manager no dilogo de contas de usurio
	echo comanager function-prefix user
	</verb></tscreen>

<sect2>A funo register para mdulos isolados ou sozinhos (stand-alone)
<p>
	A funo register no  necessria para mdulos isolados.  uma boa
	idia fornecer um mnimo para o caso de o usurio tentar registrar o
	mdulo no Linuxconf. As linhas seguintes tornaro claro que um
	determinado script no foi feito para ser executado desta forma:

	<tscreen><verb>
	register(){
		echo error \"Este script shellmod no pode ser usado como um mdulo\"
	}
	</verb></tscreen>

<sect2>A funo main
<p>
	Se o script  usado sozinho, ele precisa de uma funo chamada main.
	O utilitrio shellmod chamar esta funo cegamente.
	 uma boa idia sempre fornecer uma. Na funo register ns freqentemente
	registramos a funo main em um menu do Linuxconf. Desta forma, o script
	fornece uma interface consistente usada tanto sozinha como quando um mdulo
	do Linuxconf.

	A funo main geralmente define um menu ou um dilogo. Observe que a funo
	main  aquela que receber os argumentos do script.
	Os argumentos freqentemente sero usados como valores padro para os campos do dilogo.
	Observe o exemplo a seguir:

	<tscreen><verb>
	main(){
		echo DIALOG
		echo newf_str path \"Rota do Documento\" $1
		echo newf_str mail \"Enviar este documento por e-mail para\" $2
		echo newf_str fax \"Enviar este documento por fax para\" $3
		echo edit \"Gerenciador de documentos\" \"Preencha os campos para enviar o documento\"
		dispatch
		echo end
		if [ "$CODE" = "accept" ] ; then
			if [ "$mail" != "" ] ; then
				cat $path | mail $mail
			fi
			if [ "$fax" != "" ] ; then
				spoolfax $fax $path
			fi
		fi
	}
	</verb></tscreen>

<sect2>A funo dispatch
<p>
	Um mdulo sempre termina com uma chamada  funo dispatch. Um script shellmod
	pode ser visto como um conjunto de funes esperando ser chamado (uma biblioteca).
	Baseado neste contexto, o Linuxconf (ou shellmod para scripts sozinhos) chamar
	a funo apropriada.

	Observe que o script pode executar alguma inicializao antes de chamar a funo
	dispatch. Como explicado a seguir, um script pode ser visto como um pequeno
	servidor que mantm seu estado entre chamadas a suas vrias funes.

<sect1>Como funciona
<p>
	Um script shellmod interage com o shellmod ou Linuxconf ecoando comandos
	em sua sada padro. Ele recebe instues simplesmente lendo sua entrada
	padro. A funo dispatch cuida de ler e processar (dispatch) o pedido que
	ela recebe.
	Ns podemos pensar no script como sendo um sanduche entre dois
	processos shellmod, como a seguir:

	<tscreen><verb>
	shellmod | script | shellmod
	</verb></tscreen>

	Tudo que  ecoado pelo script  captado pelo shellmod e interpretado como
	comandos de protocolo.  importante redirecionar a sada do subcomando que
	voc estiver usando tanto para o canal de erros (<tt>command >&2</tt>) ou
	para /dev/null. Se isto no for feito, aparecero muitas mensagens de erro
	provenientes do shellmod.

<sect>Protocolo
<p>
	Ns agora apresentamos os vrios comandos editados pelo script. Estes
	commandos so divididos por tarefa.

<sect1>Estrutura de comandos e colocao de aspas
<p>
	Todos os comandos so enviados ao shellmod atravs do comando echo. Eles
	sempre se parecem com:

	<tscreen><verb>
	echo command arg1 arg2 arg3
	</verb></tscreen>

	Os argumentos podem ser palavras simples, ou vrias palavras separadas por espaos.
	Para agrupar mltiplas palavras como um argumento simples, deve-se usar aspas.
	Apesar de isto ser uma prtica comum em linhas de commando, existe um detalhe: as aspas
	iro afetar apenas o argumento conforme visto pelo comando <tt>echo</tt>.
	Uma vez processada, a linha inteira ser recebida como um fluxo simples de palavras
	separadas por espaos e as aspas desaparecero. As aspas devem ser parte da linha
	recebida pelo shellmod. Veja um exemplo:

	<tscreen><verb>
	echo newf_str name \"Digite seu nome\" \"Tux, o pingim\"
	</verb></tscreen>

	A biblioteca shellmod-lib.sh define a funo <tt>qecho</tt> que ajudar voc
	a ter um comportamento de aspas padro. O seguinte  um exemplo reescrito
	com <tt>qecho</tt>.

	<tscreen><verb>
	qecho newf_str name "Digite seu nome" 'Tux, o pingim'
	</verb></tscreen>

	Como voc pode ver, com <tt>qecho</tt> voc pode misturar as diferentes sintaxes
	de aspas do shell. A funo <tt>qecho</tt> assegura que as aspas agregam todos
	os argumentos.
	
	
<sect1>Enviando parmetros em vrias linhas
<p>
	Scripts shell no so to bons em manipular e entregar texto em vrias linhas.
	O comando "defval" foi criado para consertar isso.
	Eis aqui uma forma tpica de utlizao:

	<tscreen><verb>
	echo var1 "Esta  a primeira linha"
	echo var1 "Esta  a segunda linha"
	echo error =var1
	</verb></tscreen>

	Isto cria uma mensagem popup de erro com duas linhas. "defval"  usado
	repetidamente para definir o texto em vrias linhas e  referenciado como um
	argumento utilizando o sinal = . O argumento no pode estar entre aspas. Deste modo,
	voc no pode utilizar a funo qecho usando um parmetro defvar parameter, porque
	qecho necessita de aspas fechando todos os parmetros.

<sect1>Construindo um dilogo.
<p>

<sect2>echo DIALOG
<p>
	Um dilogo sempre inicia com este comando. Ele no requere nenhum argumento a mais.
	Depois voc acrescenta definies de campos, adiciona botes opcionais
	e ento voc chama a funo edit. Eis aqui um exemplo:

	<tscreen><verb>
	echo DIALOG
	echo newf_str var \"ttulo do campo\" value
	edho edit \"Ttulo do dilogo\" \"Introduo do Dilogo\"
	dispatch
	echo end
	</verb></tscreen>

<sect2>echo edit \"ttulo\" \"Intruduo\" [ "boto,boto,..." ]
<p>
	Isto faz aparecer um dilogo. O controle do ttulo da janela usando o primeiro
	argumento e a maior descrio de dilogo  realizado pelo campo da
	introduo.

	O ltimo argumento  opcional e permite que voc controle os botes
	apresentados na parte inferior do dilogo. O valor "0" indica que nenhum
	boto deve ser mostrado (til para mostrar alguma sada de dados, por exemplo).

	Se o ltimo argumento for omitido, os botes Aceitar e Cancelar so
	mostrados.

<sect2>echo show \"ttulo\" \"Introduo\"
<p>
	Isto funciona do mesmo modo que o edit. Ele apresenta o dilogo com os mesmos
	argumentos, mas retorna imediatamente. Geralmente  usado com o comando
	<ref id="newf_gauge" name="newf_gauge">.
	

<sect2>dispatch
<p>
	Passa o controle para Linuxconf/shellmod e espera pelos resultados.
	As variveis de campo so atualizadas e a varivel CODE recebe o valor do
	boto selecionado pelo usurio: Pode ser tanto "accept" (aceitar) como
	"cancel" (cancelar).

<sect2>echo end
<p>
	Isto apaga o dilogo. Ele  removido da tela e esquecido.
	Ns editamos freqentemente o comando end logo aps o comando
	dispatch. Mas dilogos mais complexos podem utilizar o comando
	end aps um loop de validao.

<sect2>Um exemplo completo
<p>
	<tscreen><verb>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
main(){
	echo DIALOG
	echo newf_str name \"Nome de Usurio\"
	while true
	do
		echo edit \"Perguntas ao usurio\" \"Entre com o nome de usurio\"
		dispatch
		if [ "$CODE" = "cancel" ] ; then
			break
		elif [ "$name" = "" ] ; then
			echo error \"Por favor entre com um nome\"
		else
			echo notice \"Fazendo algo com a conta do usurio\"
			break
		fi
	done
	echo end
}
dispatch
	</verb></tscreen>			

<sect1>Construindo um menu
<p>
	Isto  manipulado pelos comandos DIALOG_MENU e new_menuitem.

<sect2>echo DIALOG_MENU
<p>
	No requere nenhum argumento.

<sect2>echo new_menuitem function prompt titulo
<p>
	Isto registra mais uma entrada no menu. Cada entrada de menu  associada
	com uma funo de script (que deve ser definida). O prompt
	geralmente  uma palavra-chave. O ttulo  o restante da entrada do menu.

<sect2>echo editmenu \"Ttulo do Menu\" \"Introduo\"
<p>
	Isto faz o menu aparecer.  seguido por uma chamada a dispatch.

<sect2>dispatch
<p>
	Aqui  onde tudo  realizado para o menu. A funo dispatch
	ser executada at que o usurio selecione o boto "quit".
	A funo correspondente  chamada sempre que uma entrada de menu
	for selecionada. Isto  manipulado transparentemente pela funo
	dispatch.

	Observe que a funo dispatch tambm termina se o usurio selecionar
	algum boto opcional (adicionados com o comando button).
	Deste modo  possvel executar o controle em um loop como o dilogo
	do exemplo acima.

<sect2>echo end
<p>
	Apaga o menu.

<sect2>Um exemplo completo
<p>
	<tscreen><verb>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
menufunc1(){
	echo notice \"menufunc1 selecionado\"
}
menufunc2(){
	echo notice \"menufunc2 selecionado\"
}
main(){
	echo DIALOG_MENU
	echo new_menuitem menufunc1 Select \"Primeira opo\"
	echo new_menuitem menufunc2 \"\" \"Segunda opo\"
	echo editmenu \"Menu principal\" \"Escolha uma opo\"
	dispatch
	echo end
}
dispatch
	</verb></tscreen>
	
<sect1>Gerenciando uma lista de registros
<p>
<sect2>echo DIALOG_LIST
<p>
	DIALOG_LIST  apenas uma variao de um menu. A principal diferena  que
	o nmero da entrada pode ser bem longo. Nesse caso, um dilogo
	de filtro ser apresentado para restringir o nmero de registros mostrados.
	Voc pode ento lidar com uma lista muito grande de itens.

	DIALOG_LIST no requer nenhum argumento.

<sect2>echo newf_head \"Ttulo da Coluna 1\" \"Ttulo da Coluna 2\" ...
<p>
	Voc pode definir o cabealho da lista. Isto  opcional, mas fica com
	um aspecto muito melhor.
	
<sect2>echo new_menuitem \"Argumentos da funo\" \"Valor da Coluna 1\" \"Valor da Coluna 2\" ...
<p>
	Funciona como DIALOG_MENU, exceto por ns normalmente fornecermos mais colunas.
	Existe uma outra variao quando a funo  definida com argumentos.
	Observe que este modo pode ser utilizado com DIALOG_MENU da mesma forma. Ns
	geralment definimos uma funo por entrada de menu e uma funo simples para
	processar cada registro da lista, usando o argumento para diferenciar o
	processamento.

	Observe tambm que voc pode usar uma soluo mista com o mesmo DIALOG_MENU
	ou DIALOG_LIST: voc pode utilizar uma funo simples para fornecer um
	processamento comum para alguns registros e uma funo diferente para
	gerenciar excees.

<sect2>echo editmenu \"Ttulo da lista\" \"Introduo\"
<p>
	Igual a DIALOG_MENU.

<sect2>dispatch
<p>
	Isto se comporta como DIALOG_MENU.

<sect2>echo end
<p>
	Isto apaga a lista.

<sect2>Um exemplo completo
<p>
	Eis aqui um exemplo real onde ns apresentamos um diretrio e
	permitimos que o usurio escolha um arquivo para fazer algo com ele.
	Ns vemos neste exemplo como  fcil analisar a sada do comando
	"<tt>ls -l</tt>" e apresentar o nome do arquivo, o tamanho e a data
	de reviso em um formato de trs colunas.
	<tscreen><verb>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
fileshow(){
	echo notice \"Processando arquivo $1\"
}
main(){
	echo DIALOG_LIST
	echo newf_head \"Nome do Arquivo\" Size \"Data de Reviso\"
	ls -l $1 | \
		(
		read total
		while read perm count user group size month day hour name
		do
			echo new_menuitem \"fileshow $name\" $name $size \"$month $day $hour\"
		done
		)
	echo editmenu \"Diretrio Atual\" \"Mostra todos os arquivos no diretrio atual\"
	dispatch
	echo end
}
dispatch
</verb></tscreen>

<sect1>Definindo campos
<p>
	Todos os comandos que definem um campo de dilogo iniciam com o prefixo <tt>newf_</tt>.
	Ns usamos a mesma ordem de nome e de parmetro (quando possvel) conforme
	a API do mdulo C++.

	O primeiro argumento  sempre o nome da varivel shell a qual receber
	o valor entrado pelo usurio. Voc utilizar freqentemente a seguinte
	construo para editar (corrigir o valor atual) de uma determinada
	varivel.

	<tscreen><verb>
	qecho newf_str var "title" "$var"
	.
	qecho edit ...
	dispatch
	if [ "$CODE" = "accept" ] ; then
		if [ "$var" = "..." ] ;then
			.
			.
		fi
	fi
	</verb></tscreen>

<sect1>Lista de comandos
<p>
	Here is the list of all field definition commands:

	<itemize>
	<item><ref id="newf_chk" name="newf_chk">
 	<item><ref id="newf_chkm" name="newf_chkm">
	<item><ref id="newf_combo" name="newf_combo">
	<item><ref id="newf_dbl" name="newf_dbl">
	<item><ref id="newf_enum" name="newf_enum">
	<item><ref id="newf_gauge" name="newf_gauge">
	<item><ref id="newf_hexnum" name="newf_hexnum">
	<item><ref id="newf_list" name="newf_list">
	<item><ref id="newf_num" name="newf_num">
	<item><ref id="newf_pass" name="newf_pass">
	<item><ref id="newf_radio" name="newf_radio">
	<item><ref id="newf_slider" name="newf_slider">
	<item><ref id="newf_str" name="newf_str">
	<item><ref id="newf_title" name="newf_title">
	</itemize>
	


<sect2>echo newf_chk var \"Ttulo do campo\" \"Valor inicial 0 ou 1\" \"Ttulo do sufixo\"
	<label id="newf_chk">
<p>
	Define um campo de caixa de verificao (lig/des ou sim/no). A varivel var
	ser definida como 0 ou 1. Este campo tem dois ttulos. Um na esquerda da
	caixa de verificao e um na direita. No Linuxconf, isto  freqentemente
	usado da seguinte maneira:

	<tscreen><verb>
	A seguinte caracterstica [ ] est selecionada
	</verb></tscreen>

<sect2>Variaes da sintaxe de newf_chk
<p>
	Quando voc usar newf_chk, voc deve passar valores 0 ou 1. A varivel edit
	receber esse valor como 0 ou 1. Isto no  muito til, j que, com freqncia,
	scripts shell lidam com diferentes tipos de valores booleanos. Por exemplo,
	um script tratando com um servidor SQL pode se deparar com valores como Y e N.
	Para evitar a traduo de um sistema para o outro, a sintaxe do valor inicial
	foi expandida.

	<itemize>
	<item>Para facilitar as coisas, o shellmod aceita como valor selecionado
		qualquer coisa entre 1, Y e Yes (mausculas ou minsculas). A menos
		que o contrrio seja explicitado, estes valores sero traduzidos para 1.
		Todo o restante ser traduzido para 0.
	<item>Utilizando um formato especial de trs campos, pode-se especificar o valor
		real e o dicionrio utilizado para interpret-lo. O valor deve ser
		especificado da seguinte maneira:

		<tscreen><verb>
		valor:valor_lig:valor_des
		</verb></tscreen>

		Deste modo, se a sua aplicao est lidando com valores ON/OFF, voc pode
		especificar o valor inicial desta forma:

		<tscreen><verb>
		$var:ON:OFF
		</verb></tscreen>

		No s os valores ON e OFF sero aceitos pelo interpretador, como
		tambm o resultado final ser enviado ao script usando uma daquelas
		palavras.
	</itemize>
		
<sect2>echo newf_chkm var \"ttulo do campo\" \"valor numrico inicial\" \"valor1\" \"valor2\" ...
	<label id="newf_chkm">
<p>
	Configurao de campos de seleo mltipla utilizando caixas de verificao.
	As caixas so apresentadas horizontalmente. Eis um exemplo seguido do campo
	produzido em modo texto:

	<tscreen><verb>
	echo newf_chkm sel \"Qual posio\" 1 esquerda centro direita
	</verb></tscreen>

	This produces:

	<tscreen><verb>
	Qual posio    ( ) esquerda  (o) centro ( ) direita
	</verb></tscreen>

	A varivel var conter o ndice numrico do item selecionado,
	iniciando em 0.

<sect2>echo newf_combo var \"ttulo do campo\" \"Valor inicial\"
	<label id="newf_combo">
<p>
	Configura uma linha simples + campo seletor. O usurio ser capaz de selecionar um valor
	dentre uma lista de valores ou entrar com um outro manualmente. A varivel var ir
	conter o valor textual seja ele digitado ou selecionado.

	newf_combo  usado com o comando comboitem. Voc configura antes o campo
	combo e ento voc passa um por um os valores possveis utilizando
	comboitem. Observe que os valores so seguidos por um texto descritivo
	(opcional). Segue abaixo um cdigo exemplo:

	<tscreen><verb>
	echo newf_combo port \"Qual porta\" ttyS1
	echo comboitem ttyS0 \"COM1 no DOS\"
	echo comboitem ttyS1 \"COM2 no DOS\"
	echo comboitem ttyS2 \"COM3 no DOS\"
	</verb></tscreen>

	A varivel $port conter o valor ttyS0, ttyS1, ttyS2 ou qualquer coisa
	que o usurio digite. Veja <ref id="newf_enum" name="newf_enum">
	e <ref id="newf_list" name="newf_list"> para variaes deste campo
	de entrada.

<sect2>echo newf_dbl var \"ttulo do campo\" \"valor numrico inicial\" numero-de-casas
	<label id="newf_dbl">
<p>
	Configura um campo de entrada numrico com notao decimal. Funciona
	como <tt><ref id="newf_num" name="newf_num"></tt>
	exceto por permitir um ponto decimal. O parmetro nmero-de-casas
	controla o nmero de dgitos permitidos aps o ponto decimal bem como a
	formatao do campo.

<sect2>echo newf_enum var \"ttulo do campo\" \"Valor numrico inicial\"
	<label id="newf_enum">
<p>
	Configura um campo seletor. O usurio ser capaz de selecionar um valor
	dentre uma lista de seleo. A varivel var conter o ndice dos itens
	selecionados. O usurio  limitado a escolher um nico item da lista.

	newf_enum  usado com o comando enumitem. Voc configura primeiro o
	campo enum e ento passa um por um os valores possveis utilizando
	enumitem. Segue abaixo um cdigo exemplo:

	<tscreen><verb>
	echo newf_enum no \"Qual porta\" 1
	echo enumitem ttyS0 \"COM1 no DOS\"
	echo enumitem ttyS1 \"COM2 no DOS\"
	echo enumitem ttyS2 \"COM3 no DOS\"
	</verb></tscreen>

	A varivel $no conter o valor 0, 1 ou 2. Veja
	<ref id="newf_combo" name="newf_combo"> e
	<ref id="newf_list" name="newf_list">
	para variaes deste campo de entrada.

<sect2>echo newf_gauge ID \"ttulo do campo\" \"Valor decimal inicial\" \"Valor mximo\"
	<label id="newf_gauge">
<p>
	Configura um indicador visual de medida, geralmente usada para mostrar o progresso
	de execuo de um processo (carregamento, instalao). O estado do indicador
	 alterado  cada chamada a este comando. A primeira chamada define o campo,
	as prximas atualizam o indicador. Este widget  geralmente utilizado com o comando
	"show" de forma que o script nunca pra no estado "edit".
	Eis aqui um pequeno exemplo:

	<tscreen><verb>
	echo DIALOG
	qecho newf_gauge ID "Status" 0 10
	qecho show "Status" ""
	i=0
	while [ "$i" != "10" ] ; do
	    i=`expr $i + 1`
	    sleep 1
	    qecho newf_gauge ID "Status" $i 10
	    qecho show "Status" ""
	done
	</verb></tscreen>

<sect2>echo newf_hexnum var \"ttulo do campo\" \"Valor hexadecimal inicial\"
	<label id="newf_hexnum">
<p>
	Configura um campo de entrada numrico (inteiro). Funciona como
	<tt><ref id="newf_num" name="newf_num"></tt>
	mas aceita dgitos numricos e hexadecimais.

<sect2>echo newf_list var \"ttulo do campo\" \"Valor inicial\"
	<label id="newf_list">
<p>
	Configura um campo seletor. O usurio poder selecionar um valor
	dentre uma lista. A varivel var ir conter o valor textual
	selecionado.

	newf_list  utilizado com o comando listitem. Voc primeiro configura
	o campo de lista e ento voc passa um por um todos os valores
	possveis usando listitem. Observe que os valores so seguidos por um
	texto descritivo (opcional).
	Segue um cdigo exemplo:

	<tscreen><verb>
	echo newf_list port \"Qual porta\" ttyS1
	echo listitem ttyS0 \"COM1 no DOS\"
	echo listitem ttyS1 \"COM2 no DOS\"
	echo listitem ttyS2 \"COM3 no DOS\"
	</verb></tscreen>

	A varivel $port conter o valor ttyS0, ttyS1 ou ttyS2.
	Veja <ref id="newf_enum" name="newf_enum">
	e <ref id="newf_combo" name="newf_combo">
	para variaes neste campo de entrada.

<sect2>echo newf_num var \"ttulo do campo\" \"Valor numrico inicial\"
	<label id="newf_num">
<p>
	Configura um campo de entrada numrico (inteiro). Funciona como <tt>newf_str</tt>
	mas aceita apenas um dgito.

<sect2>echo newf_pass var \"ttulo do campo\" \"Valor inicial\"
	<label id="newf_pass">
<p>
	Configura um campo de senha. Funciona como o campo <tt>newf_str</tt> exceto
	pela entrada no ser ecoada (digitao invisvel).

<sect2>echo newf_radio var \"ttulo do campo\" valor-numrico valor-da-instncia \"ttulo do sufixo\"
	<label id="newf_radio">
<p>
	Configura um campo de boto de rdio. Vrios campos de boto de rdio devem
	ser definidos para cada seleo possvel. Todos os botes de rdio que compartilham
	a mesma varivel de entrada (var, acima) operam juntos: ligar um desliga o outro
	e vice-versa. A varivel var conter o valor numrico do campo de boto de rdio
	selecionado.

	Botes de rdio selecionados podem ser colocados em qualquer lugar em um dilogo.
	Eles no precisam estar em seqncia nem mesmo na mesma pgina do dilogo.

<sect2>echo newf_slider var \"ttulo do campo\" \"Valor decimal inicial\" \"Valor mnimo\" \"Valor mximo\"
	<label id="newf_slider">
<p>
	Isto funciona como newf_num, para editar um valor decimal. Mas 
	mostrado como um boto deslizante. Os valores mnimo e mximo representam as
	margens esquerda e direita do boto deslizante.

	<tscreen><verb>
	qecho newf_slider var "Hora de Reunio" 15 9 16
	</verb></tscreen>

<sect2>echo newf_str var \"ttulo do campo\" \"Valor inicial\"
	<label id="newf_str">
<p>
	Configura uma entrada de texto de uma linha.

<sect2>echo newf_title "Ttulo da Pgina" level "Ttulo Esquerdo" "Ttulo em modo texto"
	<label id="newf_title">
<p>
	Isto no  um campo de entrada, mas  uma forma de organizar um grande dilogo
	em uma seo. O resultado final  bem diferente em modo grfico do que em em
	texto ou HTML. Em modo grfico, isto criar um dilogo em um bloco de notas
	e cada newf_title define uma pgina do bloco de notas.

	O primeiro argumento, o ttulo da pgina,  usado apenas em modo grfico.

	O segundo argumento  um nmero e representa o nvel do bloco de notas. Isto
	permite dilogos muito complexos com blocos de notas dentro de blocos de notas.
	Em modos texto e HTML mode, este argumento no tem efeito.

	<itemize>
	<item>Um valor de 0 adiciona uma diviso horizontal entre dois campos.
		o "Ttulo em modo texto"  centrado nesta diviso.
	<item>Um valor de 1 cria o primeiro nvel do bloco de notas. Um valor de 2
		cria um sub-bloco de notas com o atual.
	</itemize>

	O terceiro argumento, ttulo esquerdo,  utilizado apenas em modo texto e HTML.
	Ele coloca um pequeno ttulo  esquerda dos campos de entrada.

	O ltimo argumento, Ttulo em modo texto, aparece centrado entre dois campos
	de entrada.

<sect1>Adicionando botes
<p>
	Voc pode adicionar botes opcionais usando simplesmente o comando button.
	Ele requer dois argumentos. O primeiro  a ID (identificao) do boto que ser
	passada ao script utilizando a varivel CODE. O segundo  o rtulo (ttulo)
	do boto. Segue abaixo um exemplo:

	<tscreen><verb>
	echo DIALOG
	echo newf_str name \"Nome de usurioe\" $name
	echo button Add \"Adicionar novo usurio\"
	echo edit "title" \"Gerenciamento de usurios\"
	dispatch
	echo end
	if [ "$CODE" = "Add" ] ; then
		# Adicionando um novo usurio
	elif [ "$CODE" = "accept" ] ; then
		# Inspecionando um registro de usurio
	fi
	</verb></tscreen>

<sect1>Configura o campo atual de entrada
<p>
	O cdigo de operao "setcurfield" coloca o foco do teclado em um campo especfico.
	Voc deve passar a ID (identificao) do campo como um argumento simples. Eis um exemplo:

	<tscreen><verb>
	qecho DIALOG
	qecho newf_str uid "ID de Usurio" 
	qecho newf_str name "Nome" 
	qecho newf_str phone "Nome"
	qecho setcurfield name
	qecho edit "exemplo" "O foco agora est no nome"
	dispatch
	echo end 
	</verb></tscreen>

<sect>Construindo co-gerenciadores
<p>
	Co-gerenciadores so timos. Eles permitem que funcionalidades sejam adicionadas ao
	Linuxconf no exato lugar a que elas pertencem, ao invs de se adicionar novos
	sub-menus.

<sect1>Princpios
<p>
	Um co-gerenciador  um componente que participa de um dilogo. Ele pode
	adicionar campos e validao. O caso mais comum  o dilogo de conta de
	usurio, onde vrios co-gerenciadores participam. O mais visvel deles  o
	mdulo mailconf, que insere uma seo completa para manipular aliases de
	email. Um outro  o mdulo pppdialin, o qual adiciona uma seo para lidar
	com parmetros PPP.

	Um co-gerenciador deve fornecer 4 funes:

	<itemize>
	<item>Adicionar campos ao dilogo. Aqui o co-gerenciador ir provavelmente
		adicionar uma nova seo e alguns campos. Ele no  forado a
		adicionar nada.
	<item>Adicionar validao. O co-gerenciador pode fazer qualquer tipo de
		validao, no apenas em seus prprios campos. Ao administrador no
		 permitido efetuar qualquer mudana  conta do usurio at que
		todos os co-gerenciadores concordem.
	<item>Salvar as entradas. O co-gerenciador deve salvar o valor dos campos
		que ele gerencia. Co-gerenciadores de contas de usurio devem
		preservar informaes indexadas por usurio.
	<item>Apagar informaes associadas  conta do usurio/registro de informaes
		quando for apagado.
	</itemize>

	Observe que os co-gerenciadores foram criados com contas de usurio em
	mente, mas o conceito  mais geral que isso. Troque "conta de usurio"
	acima por "registro" e voc ter um retrato mais geral.

<sect1>Registrando o co-gerenciador
<p>
	Linuxconf deve ser notificado que um co-gerenciador existe paa um determinado dilogo.
	Dilogos so identificados por uma pequena chave. Por exemplo, a chave para a
	conta do usurio  "user".

	Um co-gerenciador shellmod deve fornecer quatro funes, utilizando o mesmo prefixo.
	Quando voc registra o co-gerenciador, voc deve fornecer o prefixo da funo e
	a chave de dilogo. Isto  feito com a funo register.
	Segue abaixo um exemplo:

	<tscreen><verb>
	# Registra como um co-gerenciador no dilogo de conta de usurio
	echo comanager ufct user
	</verb></tscreen>

	O prefixo da funo  ufct. Deve-se criar quatro funes
	de acordo com este prefixo:

	<itemize>
	<item>ufct-setupdia
	<item>ufct-validate
	<item>ufct-save
	<item>ufct-deluser
	</itemize>


<sect1>As vrias funes
<p>
<sect2>setupdia
<p>
	Esta funo  chamada durante a construo do dilogo. Voc pode usar qualquer
	cdigo de operao normalmente para definir um dilogo. Voc no precisa
	definir o dilogo por voc prprio (echo DIALOG) j que ele est definido
	implicitamente.

	Enquanto voc pode simplesmente adicionar campos no dilogo, algum geralmente
	definir uma nova seo do dilogo. A menos que voc faa isso, seu novo campo
	ser anexado  seo atual, a qual pode ser qualquer seo.

	Voc define uma seo com o cdigo de operao newf_title.

	<tscreen><verb>
	qecho newf_title "Listas de postagem" 1 - "Listas de postagem"
	</verb></tscreen>

<sect2>validate
<p>
	Esta funo recebe todo o valor do campo (digitado pelo usurio). Cada
	campo corresponde a uma varivel shell, de forma que voc pode testar
	diretamente os valores delas. Voc deve utilizar o cdigo  "retcode" para
	verificar se a validao foi bem-sucedida. Veja o exemplo a seguir:

	<tscreen><verb>
	echo retcode 0
	</verb></tscreen>

	Qualquer valor diferente de 0  tomado como uma falha na validao. Qualquer erro
	deve ser reportado com o cdigo de operao "error". Voc tambm pode usar
	"setcurfield" para saltar a um campo especfico.

	<tscreen><verb>
	if [ "$a1" = "vlida" ] ; then
		echo retcode 0
	else
		echo setcurfield a1
		echo retcode -1
		echo error \"sample.sh: Valor invlido, entre com a palavra vlida\"
	fi
	</verb></tscreen>


<sect2>save
<p>
	Todos os valores dos campos so retornados ao seu script como variveis shell.
	A funo save deve fazer vrias coisas com as informaes. Ela pode tanto salvar
	em um arquivo, ou executar algumas aes (enviar um mail a um administrador
	sobre as mudanas necessrias, por exemplo).

	Outras variveis shell tambm contm informaes relacionadas a este dilogo
	(veja abaixo o contexto do dilogo).

<sect2>deluser
<p>
	O nome desta funo  um tanto ambgo. Significa que o registro deve ser
	apagado (em geral, uma conta de usurio). Voc deve usar a informao a partir
	do contexto do dilogo (veja abaixo) para executar o apagamento desejado.

<sect1>Contexto do Dilogo
<p>
	Um co-gerenciador manipula uma parte de um grande dilogo. Para gerenciar propriamente
	sua parte, o co-gerenciador deve conhecer outras informaes sobre o dilogo atual.
	Por exemplo, para aprimorar o dilogo de conta de usurio, deve-se conhecer a
	conta do usurio (identificao do usurio) sendo editada bem como o domnio
	( uma conta de usurio de domnio virtual de mail?).

	Esta informao extra  passada como variveis shell, prontamente utilizveis.
	A informao disponvel  dependente de dilogos. Para co-gerenciadores de
	contas de usurios, as seguintes variveis so fornecidas:

	<descrip>
	<tag>domain</tag>
		 passado o domnio de mail virtual. Para o domnio principal, esta
		varivel  configurada para /.
	<tag>is_new</tag>
		Isto  um flag que mostra a voc se esta  uma nova conta (o nome est
		vazio) ou no.
	<tag>name</tag>
		Esta  a identificao de usurio.
	</descrip>

	Uma forma de aprender as informaes disponveis para seu script  execut-lo
	em modo de depurao sob o Linuxconf. Voc pode ativar este modo a partir da
	interface de usurio do Linuxconf, no controle de sistema e arquivos/gerenciamento
	de mdulos shell/configurao do shellmod.

<sect>Vida do processo do script
<p>
	Shellmod e Linuxconf executaro o script sempre que necessrio. Usado como um
	mdulo do Linuxconf, o script no  executado durante a inicializao do Linuxconf,
	mas apenas quando  selecionada uma entrada de um de seus menus ou co-gerenciadores.

	O script  iniciado e procede  sua funo dispatch, onde ele espera
	por um pedido. Alguns pedidos engatilham a execuo de uma das funes
	do script. Quando a funo termina, a funo dispatch original recomea
	e continua a aguardar. Observe que dispatch pode ser utilizado
	recursivamente.

	Uma vez iniciado, o script permanece l esperando por um pedido at que o Linuxconf
	termine. Desta forma, isto pode ser visto como um pequeno servidor compartilhando
	informaes coletadas enquanto executa vrios pedidos.

	Quando utilizado como um utilitrio sozinho, o script terminar assim que terminar
	a funo principal.

<sect>Construtor de mdulos
<p>
	Um construtor de mdulos shell est disponvel para voc fazer as coisas mais rpido.
	Voc consegue acessar este construtor atravs do menu principal do shellmod ou com o
	utilitrio shellmod:

	<tscreen><verb>
	shellmod --build
	</verb></tscreen>

	Aparece um dilogo simples. Voc o preenche e  criada uma base para um novo
	mdulo shell. Seguem abaixo os vrios campos:

<sect1>Rota do mdulo
<p>
	Simplesmente entre com a rota completa ou relativa do novo script shell
	que voc deseja criar. O construtor no  capaz de editar um mdulo
	existente.

<sect1>Inserir no menu
<p>
	Voc deve fornecer a ID (identificao) do menu no qual voc deseja inserir
	o mdulo (no Linuxconf). Um mdulo pode ser inserido em vrios menus do
	Linuxconf, mas o construtor apenas suporta um. A modificao posterior do
	cdigo  fcil.

	Este campo tem uma lista para ajudar na seleo da ID correta.

<sect1>Ttulo do Menu
<p>
	Entre com o texto da entrada de menu.

<sect1>Isto  um co-gerenciador de contas de usurio
<p>
	Selecionando esta caixa de verificao, voc instrui o construtor a gerar
	os modelos de funo adequados para o co-gerenciador (setupdia, save, deluser, validate).

	Observe que um mdulo pode ser um co-gerenciador e efetuar inseres em menus da mesma maneira.

<sect1>Entradas do menu principal.
<p>
	Simplesmente digite as vrias entradas de menu. Para cada uma, o construtor
	ir gerar um modelo de funo shell menufunc1, menufunc2. Ele tambm ir
	gerar o cdigo do menu na funo principal. Voc ter que fornecer o cdigo
	para as diversas funes menufunc.

</article>