<?xml version="1.0" encoding="UTF-8" ?>
<sect1 id="specials">
<sect1info>
<title>Especiais e Variáveis Globais Embutidas</title>
<authorgroup>
<author><firstname></firstname> <surname></surname> <affiliation><address> <email></email>
</address></affiliation>
</author>
<othercredit role="translator"><firstname>Marcus</firstname><surname>Gama</surname><affiliation><address><email>marcus_gama@uol.com.br</email></address></affiliation><contrib>Tradução</contrib></othercredit>
</authorgroup>
</sect1info>
<title>Especiais e Variáveis Globais Embutidas</title>
<para>Os especiais são funções que são processadas pelo &kommander;. Você deverá saber que, até o &kommander; ter um processador completo, todos os especiais do &kommander; serão executados primeiro e só então o programa será executado. Na maioria dos casos isto não será um problema, mas em alguns deles será. </para>
<variablelist>
<varlistentry>
<term><function>@dcop(<parameter>idApl</parameter>, <parameter>objeto</parameter>, <parameter>função</parameter>, <parameter>argumentos</parameter>)</function></term>
<listitem>
<para>Faz uma chamada de &DCOP;. @dcop(<quote>kmail</quote>, <quote>KMailIface</quote>, <quote>checkMail()</quote>, <quote></quote>) </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@dcopid</function></term>
<listitem>
<para>O ID de &DCOP; do processo. (kmdr-executor-@pid) </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@dialog(<parameter>diálogo</parameter>[,<parameter>parâmetros</parameter>])</function></term>
<listitem>
<para>Lança o diálogo do Kommander indicado. O diálogo é visto na pasta do diálogo e na pasta atual - nesta ordem. Isto antecede a chamada ao executor e muda a pasta padrão para a pasta onde o arquivo do Kommander se encontra. Os parâmetros podem ser passados da forma normal do Unix ou você poderá passar parâmetros com nomes no formato <quote>variavel=valor</quote>. Você poderá então encontrar os parâmetros passados na lista de variáveis globais. O @global(variavel) iria devolver <quote>valor</quote>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@env(<parameter>variavelAmbiente</parameter>)</function></term>
<listitem>
<para>Expande-se para a variável de ambiente. O @env(PWD) expande-se para o $PWD. Lembre-se que o <quote>$</quote> faz parte da linha de comando e não deverá ser usado. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@exec(<parameter>comando</parameter>)</function></term>
<listitem>
<para>devolve o resultado da execução do comando indicado. @exec(ls -l). </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@execBegin ... @execEnd</function></term>
<listitem>
<para>o mesmo que o <function>@exec</function>, mas suporta o 'shebang' e 'scripts' de várias linhas. Isto serve para várias linguagens de programação, declarando-as ou utilizando um 'shebang'. </para>
<itemizedlist>
<listitem><para><function>@execBegin(php)</function></para></listitem>
<listitem><para><function>@execBegin</function>#!/usr/bin/php</para></listitem>
</itemizedlist>
<para>O primeiro usa o nome do executável do <acronym>PHP</acronym>. O &kommander; procura na PATH pelo <application>php</application> e, se não for encontrado, verifica se está registrado no &kommander; numa localização fora da sua PATH. Se não estiver, diz ao usuário que não pôde ser encontrado. O segundo exemplo usa o clássico <quote>shebang</quote>, que poderá ter alguns benefícios, assim como alguns problemas. Se você tiver uma versão beta do <acronym>PHP5</acronym>, por exemplo, no <filename>/usr/local/bin</filename>, ela não seria encontrada porque iria obter primeiro a versão em <filename>/usr/bin</filename>. Se, por outro lado, você distribuir o diálogo para alguém que tenha o <acronym>PHP</acronym> no <filename>/usr/local/bin</filename> apenas, ela não seria encontrada com o 'shebang' usado. Por isso, usar 'shebangs' deverá necessitar de cuidado e a utilização do executável é recomendada se estiver compartilhando arquivos.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@global(<parameter>variável</parameter>)</function></term>
<listitem>
<para>expande para o valor da variável global indicada. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@null</function></term>
<listitem>
<para>Devolve um valor nulo. Agora que o Kommander verifica pelo 'widgetText' vazio durante a execução, isto irá evitar erros no caso de um estado indefinido de um elemento.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@parentPid</function></term>
<listitem>
<para>O &PID; do processo-pai. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@pid</function></term>
<listitem>
<para>O &PID; do processo. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@readSetting(<parameter>chave</parameter>, <parameter>valorPadrão</parameter>)</function></term>
<listitem>
<para>lê um valor do <filename>kommanderrc</filename> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@selectedWidgetText</function></term>
<listitem>
<para>O conteúdo selecionado de um elemento gráfico que possa mostrar mais de um valor, como por exemplo as listas </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@setGlobal(<parameter>variável</parameter>, <parameter>valor</parameter>)</function></term>
<listitem>
<para>Configura a variável global para o valor indicado. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@widgetText</function></term>
<listitem>
<para>o conteúdo de um elemento </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@writeSetting(<parameter>chave</parameter>, <parameter>valor</parameter>)</function></term>
<listitem>
<para>grava o valor no <filename>kommanderrc</filename> </para>
</listitem>
</varlistentry>
</variablelist>
<sect2 id="arrays">
<title>Grupo de Funções de Listas</title>
<variablelist>
<varlistentry>
<term><function>@Array.values(<parameter>lista</parameter>)</function></term>
<listitem>
<para>Devolve uma lista separada por EOL's de todos os valores da lista. Pode ser usada para percorrer uma lista.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.keys(<parameter>lista</parameter>)</function></term>
<listitem>
<para>Devolve uma lista separada por EOL's de todas as chaves da lista.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.setValue(<parameter>lista</parameter>, <parameter>chave</parameter>, <parameter>valor</parameter>)</function></term>
<listitem>
<para>Define um chave e um valor para um elemento da lista. Se não existir nenhuma lista, ela é criada.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.clear(<parameter>lista</parameter>)</function></term>
<listitem>
<para>Remove todos os elementos da lista.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.count(<parameter>lista</parameter>)</function></term>
<listitem>
<para>Devolve o número de elementos na lista.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.value(<parameter>lista</parameter>,<parameter>chave</parameter>)</function></term>
<listitem>
<para>Devolve o valor associado à chave indicada.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.remove(<parameter>lista</parameter>,<parameter>chave</parameter>)</function></term>
<listitem>
<para>Remove o elemento com a chave indicada da lista.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.fromString(<parameter>lista</parameter>,<parameter>texto</parameter>)</function></term>
<listitem>
<para>Adiciona todos os elementos do texto na lista. O texto deverá ter o formato <emphasis>chave\tvalor\n</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@Array.toString(<parameter>lista</parameter>,<parameter>texto</parameter>)</function></term>
<listitem>
<para>Devolve todos os elementos na lista num formato <emphasis>chave\tvalor\n</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="files">
<title>Grupo de Funções de Arquivos</title>
<variablelist>
<varlistentry>
<term><function>@File.read(<parameter>arquivo</parameter>)</function></term>
<listitem>
<para>Devolve o conteúdo do arquivo indicado.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@File.write(<parameter>arquivo</parameter><parameter>texto</parameter>)</function></term>
<listitem>
<para>Escreve o texto indicado num arquivo.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@File.append(<parameter>arquivo</parameter><parameter>texto</parameter>)</function></term>
<listitem>
<para>Adiciona o texto indicado ao fim de um arquivo.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="strings">
<title>Grupo de Funções de Cadeias de Caracteres</title>
<variablelist>
<varlistentry>
<term><function>@String.length(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Devolve o número de caracteres no texto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.contains(<parameter>texto</parameter>,<parameter>sub-texto</parameter>)</function></term>
<listitem>
<para>Verifica se o texto contém o sub-texto indicado.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.find(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Devlve a posição de um sub-texto no texto ou -1 se não for encontrado.</para>
<note><para>Isto terá um parâmetro opcional de posição inicial para procurar as próximas instâncias na versão Alpha 6.</para></note>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.left(<parameter>texto</parameter>, <parameter>num</parameter>)</function></term>
<listitem>
<para>Devolve os primeiros 'num' caracteres do texto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.right(<parameter>texto</parameter>, <parameter>num</parameter>)</function></term>
<listitem>
<para>Devolve os últimos 'num' caracteres do texto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.mid(<parameter>texto</parameter>, <parameter>inicio</parameter>, <parameter>fim</parameter>)</function></term>
<listitem>
<para>Devolve uma sub-sequência do texto, delimitada pelas posições indicadas.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.remove(<parameter>texto</parameter>, <parameter>sub-texto</parameter>)</function></term>
<listitem>
<para>Remove todas as ocorrências de um determinado sub-texto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.replace(<parameter>texto</parameter>, <parameter>original</parameter>, <parameter>substituicao</parameter>)</function></term>
<listitem>
<para>Substitui todas as ocorrências de um determinado sub-texto por outro de substituição.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.upper(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Converte o texto para maiúsculas.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.lower(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Converte o texto para minúsculas.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.compare(<parameter>texto1</parameter>, <parameter>texto2</parameter>)</function></term>
<listitem>
<para>Compara dois textos. Devolve 0 se forem iguais, -1 se o primeiro texto for menor ou 1 se o primeiro texto for maior</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.isEmpty(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Verifica se o texto está vazio.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@String.isNumber(<parameter>texto</parameter>)</function></term>
<listitem>
<para>Verifica se o texto é um número válido.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="builtins">
<title>Globais Embutidos</title>
<para>Os globais embutidos são acessados como se fossem variáveis globais normais com o <function>@global</function>.</para>
<variablelist>
<varlistentry>
<term><function>@global(_KDDIR)</function></term>
<listitem>
<para>A pasta onde o diálogo atual se encontra.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>@global(_NAME)</function></term>
<listitem><para>O nome do diálogo</para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
