<?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
> 

</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, todas las especiales de &kommander; se ejecutarán primero, y luego se ejecutará el guión. En la mayoría de los casos, no suele ser un problema, pero en algunos sí que lo es. </para>

<variablelist>
<varlistentry>
<term
><function
>@dcop(<parameter
>appId</parameter
>, <parameter
>objeto</parameter
>, <parameter
>funcion</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
>dialog</parameter
>[,<parameter
>parameters</parameter
>])</function
></term>
<listitem>
<para
>Lanza el cuadro de diálogo de Kommander especificado. El cuadro de diálogo se obtiene del directorio dialog y del actual, en ese orden. Esto se hace con antelación a la llamada al ejecutor y define el directorio predefinido en el que está la aplicación de Kommader. Los parámetros (parameters) se pueden pasar al estilo de Unix o por nombre, como <quote
>variable=valor</quote
>. Luego puede buscar los parámetros globales pasados.  @global(variable) devolvería <quote
>valor</quote
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@env(<parameter
>environmentVariable</parameter
>)</function
></term>
<listitem>
<para
>Expande la environmentVariable (variable de entorno) pasada. @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
>command</parameter
>)</function
></term>
<listitem>
<para
>devuelve la salida de la ejecución del command (comando) especificado. @exec(ls -l). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@execBegin ... @execEnd</function
></term>
<listitem>
<para
>igual que <function
>@exec</function
>, pero admite shebang (n.t. la marca de comienzo de un guión en Unix) y guiones de varias líneas. Sirve para varios lenguajes de guiones, así como para declararlos o usar una 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 PATH (n.t. la ruta) para <application
>php</application
> y, si no lo encontrara, buscaría si está registrado con &kommander; en una ubicación externa a su ruta. Si no fuera así, le diría al usuario que no se puede encontrar. El segundo ejemplo usa el <quote
>shebang</quote
> (n.t. la marca de comienzo de un guión en Unix) clásico, que tiene algunas ventajas y también algunos 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 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, use con cuidado las shebangs 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 si widgetText extá vacío en la ejecución, esto evitará que haya errores erróneos en el 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
>key</parameter
>, <parameter
>defaultValue</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 los widgets de lista </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@setGlobal(<parameter
>variable</parameter
>, <parameter
>value</parameter
>)</function
></term>
<listitem>
<para
>Define la variable global como el value (valor) especificado. </para>
</listitem>
</varlistentry>

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

<varlistentry>
<term
><function
>@writeSetting(<parameter
>key</parameter
>, <parameter
>value</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 la lista separada por EOL de todos los valores del array (vector). Se puede usar para pasear a través de los elementos de un vector.</para>
</listitem>
</varlistentry>

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

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

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

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

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

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

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

<varlistentry>
<term
><function
>@Array.toString(<parameter
>array</parameter
>,<parameter
>string</parameter
>)</function
></term>
<listitem>
<para
>"Devuelve todos los elementos del array (vector) 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
>file</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el contendo del file (archivo) dado.</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term
><function
>@File.append(<parameter
>file</parameter
><parameter
>string</parameter
>)</function
></term>
<listitem>
<para
>Añade la string (cadena de caracteres) dada al final del file (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
>string</parameter
>)</function
></term>
<listitem>
<para
>Devuelve el número de caracteres que hay en la cadena de caracteres (string).</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term
><function
>@String.find(<parameter
>string</parameter
>)</function
></term>
<listitem>
<para
>Devuelve la posición de una subcadena de caracteres (substring) en la cadena (string), o -1 si no se encuentra."</para>
<note
><para
>Tiene una posición opcional de comienzo, entera (integer) para encontrar los usos en alfa 6.</para
></note>
</listitem>
</varlistentry>

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

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

<varlistentry>
<term
><function
>@String.mid(<parameter
>string</parameter
>, <parameter
>int start</parameter
>, <parameter
>int end</parameter
>)</function
></term>
<listitem>
<para
>Devuelve la subcadena de caracteres (substring) de la cadena (string), comenzando en las posiciones indicadas.</para>
</listitem>
</varlistentry>

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

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

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

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

<varlistentry>
<term
><function
>@String.compare(<parameter
>string</parameter
>, <parameter
>string</parameter
>)</function
></term>
<listitem>
<para
>Compara dos cadenas de caracteres (string). 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
>string</parameter
>)</function
></term>
<listitem>
<para
>Comprueba si la cadena de caracteres (string) está vacía.</para>
</listitem>
</varlistentry>

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

</variablelist>
</sect2>

<sect2 id="builtins">
<title
>Globales internos</title>
<para
>A los globales internos se accede como a las variables 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>
