<?xml version="1.0"  encoding="UTF-8" ?>

<sect1 id="specials">
<sect1info>
<title
>Especiales y variables globales internas</title>
<authorgroup>
<author
><firstname
></firstname
> <surname
></surname
> <affiliation
><address
> <email
></email>
</address
></affiliation>
</author>

<othercredit role="translator"
><firstname
>Juan Manuel</firstname
> <surname
>García Molina</surname
> <affiliation
><address
><email
>juanma@superiodico.net</email
></address
></affiliation
><contrib
>Traductor</contrib
></othercredit
> <othercredit role="translator"
><firstname
>Cristina Yenyxe</firstname
> <surname
>González García</surname
> <affiliation
><address
><email
>the.blue.valkyrie@gmail.com</email
></address
></affiliation
><contrib
>Traductor</contrib
></othercredit
> 

</authorgroup>
</sect1info>

<title
>Especiales y variables globales internas</title>

<para
>Los especiales son funciones que &kommander; procesa. Debería tener en cuenta que, hasta que &kommander; tenga un analizador completo, todos los especiales de &kommander; se ejecutarán antes que el guión. En la mayoría de casos no suele ser un problema, pero en algunos sí. </para>

<variablelist>
<varlistentry>
<term
><function
>@dcop(<parameter
>appId</parameter
>, <parameter
>objeto</parameter
>, <parameter
>función</parameter
>, <parameter
>argumentos</parameter
>)</function
></term>
<listitem>
<para
>Hace una llamada &DCOP;. @dcop(<quote
>kmail</quote
>, <quote
>KMailIface</quote
>, <quote
>checkMail()</quote
>, <quote
></quote
>) </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@dcopid</function
></term>
<listitem>
<para
>El id. &DCOP; del proceso. (kmdr-executor-@pid) </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@dialog(<parameter
>diálogo</parameter
>[,<parameter
>parámetros</parameter
>])</function
></term>
<listitem>
<para
>Lanza el cuadro de diálogo de Kommander especificado, que se obtiene del directorio de diálogos y del actual, en ese orden. Esta tarea se lleva a cabo antes de invocar al ejecutor y establece el directorio predeterminado en el que se encuentra Kommander. Los parámetros se pueden pasar al estilo de Unix o por nombre, como <quote
>variable=valor</quote
>. Luego puede buscar los parámetros globales facilitados: @global(variable) devolvería <quote
>valor</quote
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@env(<parameter
>variableDeEntorno</parameter
>)</function
></term>
<listitem>
<para
>Expande la variable de entorno especificada. @env(PWD) se expande como $PWD. Recuerde que <quote
>$</quote
> es parte de la shell y no se debe usar. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@exec(<parameter
>orden</parameter
>)</function
></term>
<listitem>
<para
>devuelve la salida de la ejecución de la orden especificada. @exec(ls -l). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@execBegin ... @execEnd</function
></term>
<listitem>
<para
>igual que <function
>@exec</function
>, pero admite shebang y guiones de varias líneas. Sirve para varios lenguajes de guiones, declarándolos o usando un shebang. </para>
<itemizedlist>
<listitem
><para
><function
>@execBegin(php)</function
></para
></listitem>
<listitem
><para
><function
>@execBegin</function
>#!/usr/bin/php</para
></listitem>
</itemizedlist>
<para
>El primero usa el nombre del ejecutable <acronym
>PHP</acronym
>. &kommander; busca <application
>php</application
> en el PATH y, si no lo encuentra, busca si está registrado con &kommander; en una ubicación externa. Si no fuera así, le diría al usuario que no se puede encontrar. El segundo ejemplo usa el clásico <quote
>shebang</quote
>, que posee algunas ventajas pero también ciertos inconvenientes. Si tiene una copia de la beta de <acronym
>PHP5</acronym
>, por ejemplo, en <filename
>/usr/local/bin</filename
>, podría no encontrarse por no estar en <filename
>/usr/bin</filename
>, y para ello el shebang sería muy útil. Sin embargo, si distribuye el cuadro de diálogo a alguien que tenga <acronym
>PHP</acronym
> en <filename
>/opt/bin</filename
>, no lo encontrará cuando use shebang. Por tanto, utilícelos con cuidado y, si va a compartir archivos, se recomienda que use el ejecutable.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@global(<parameter
>variable</parameter
>)</function
></term>
<listitem>
<para
>expande el valor de la variable global especificada. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@null</function
></term>
<listitem>
<para
>Devuelve null (nulo). Ahora que Kommander comprueba en ejecución si widgetText extá vacío, esto evitará falsos errores en caso de que haya un estado no definido en el widget.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@parentPid</function
></term>
<listitem>
<para
>El &PID; del proceso padre. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@pid</function
></term>
<listitem>
<para
>El &PID; del proceso. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@readSetting(<parameter
>clave</parameter
>, <parameter
>valorPredeterminado</parameter
>)</function
></term>
<listitem>
<para
>lee un valor de <filename
>kommanderrc</filename
> </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@selectedWidgetText</function
></term>
<listitem>
<para
>el contenido seleccionado de un widget que puede mostrar más de un valor, como una lista </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@setGlobal(<parameter
>variable</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>Establece el valor de la variable global especificada. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@widgetText</function
></term>
<listitem>
<para
>el contenido de un widget </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@writeSetting(<parameter
>clave</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>escribe un valor en <filename
>kommanderrc</filename
> </para>
</listitem>
</varlistentry>
</variablelist>

<sect2 id="arrays">
<title
>Grupo de funciones de vectores</title>

<variablelist>
<varlistentry>
<term
><function
>@Array.values(<parameter
>array</parameter
>)</function
></term>
<listitem>
<para
>Devuelve una lista de todos los valores del array, separados por EOL. Se puede usar para recorrer todos sus elementos.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.keys(<parameter
>array</parameter
>)</function
></term>
<listitem>
<para
>Devuelve una lista con todas las claves del array, separadas por EOL.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.setValue(<parameter
>array</parameter
>, <parameter
>clave</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>Define una clave y un valor para un elemento del array. Si no existe el array, se crea.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.clear(<parameter
>array</parameter
>)</function
></term>
<listitem>
<para
>Elimina todos los elementos del array.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.count(<parameter
>array</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el número de elementos del array.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.value(<parameter
>array</parameter
>,<parameter
>clave</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el valor asociado a la clave dada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.remove(<parameter
>array</parameter
>,<parameter
>clave</parameter
>)</function
></term>
<listitem>
<para
>Elimina el elemento del array que hay en la clave dada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.fromString(<parameter
>array</parameter
>,<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Añade al array todos los elementos de la cadena de caracteres, que debe tener el formato <emphasis
>clave\tvalor\n</emphasis
>."</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.toString(<parameter
>array</parameter
>,<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>"Devuelve todos los elementos del array en el formato <emphasis
>clave\tvalor\n</emphasis
>."</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="files">
<title
>Grupo de funciones de archivo</title>
<variablelist>

<varlistentry>
<term
><function
>@File.read(<parameter
>archivo</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el contendo del archivo dado.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@File.write(<parameter
>archivo</parameter
><parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Escribe la cadena de caracteres dada en el archivo.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@File.append(<parameter
>archivo</parameter
><parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Añade la cadena de caracteres dada al final del archivo.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="strings">
<title
>Grupo de funciones de cadenas de caracteres</title>
<variablelist>

<varlistentry>
<term
><function
>@String.length(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el número de caracteres de la cadena de caracteres.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.contains(<parameter
>cadena</parameter
>,<parameter
>subcadena</parameter
>)</function
></term>
<listitem>
<para
>Comprueba si la cadena de caracteres contiene la subcadena dada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.find(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Devuelve la posición de una subcadena de caracteres en la cadena, o -1 si no se encuentra.</para>
<note
><para
>Tendrá una posición de comienzo, opcional y de tipo entero, a la que se dará uso en la alfa 6.</para
></note>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.left(<parameter
>cadena</parameter
>, <parameter
>entero</parameter
>)</function
></term>
<listitem>
<para
>Devuelve los n primeros caracteres de la cadena.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.right(<parameter
>cadena</parameter
>, <parameter
>entero</parameter
>)</function
></term>
<listitem>
<para
>Devuelve los n últimos caracteres de la cadena.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.mid(<parameter
>cadena</parameter
>, <parameter
>inicio</parameter
>, <parameter
>fin</parameter
>)</function
></term>
<listitem>
<para
>Dada una cadena de caracteres, devuelve la subcadena entre las posiciones indicadas.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.remove(<parameter
>cadena</parameter
>, <parameter
>subcadena</parameter
>)</function
></term>
<listitem>
<para
>Elimina todas las ocurrencias de una subcadena de caracteres dada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.replace(<parameter
>cadena</parameter
>, <parameter
>subcadena buscada</parameter
>, <parameter
>subcadena reemplazo</parameter
>)</function
></term>
<listitem>
<para
>Reemplaza todas las ocurrencias de una subcadena de caracteres con un reemplazo dado.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.upper(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Convierte la cadena de caracteres a mayúsculas.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.lower(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Convierte la cadena de caracteres a minúsculas.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.compare(<parameter
>cadena1</parameter
>, <parameter
>cadena2</parameter
>)</function
></term>
<listitem>
<para
>Compara dos cadenas de caracteres. Devuelve 0 si son iguales. -1 si la primera es menor, 1 si la primera es mayor</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.isEmpty(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Comprueba si la cadena de caracteres está vacía.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.isNumber(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Comprueba si la cadena de caracteres es un número válido.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="builtins">
<title
>Globales incorporadas</title>
<para
>A las variables globales incorporadas se accede como a las globales habituales, con <function
>@global</function
>.</para>
<variablelist>
<varlistentry>
<term
><function
>@global(_KDDIR)</function
></term>
<listitem>
<para
>El directorio en el que está el cuadro de diálogo actual.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>@global(_NAME)</function
></term>
<listitem
><para
>El nombre del cuadro de diálogo</para
></listitem>
</varlistentry>
</variablelist>
</sect2>

</sect1>