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

<sect1 id="specials">
<sect1info>
<title
>Especials i variables globals encastades</title>
<authorgroup>
<author
><firstname
></firstname
> <surname
></surname
> <affiliation
><address
> <email
></email>
</address
></affiliation>
</author>

&traductor.Antoni.Bella; 

</authorgroup>
</sect1info>

<title
>Especials i variables globals encastades</title>

<para
>Les especials són funcions que processades per &kommander;. Heu de tenir en compte que fins que &kommander; disposi d'un analitzador complet, totes les especials de &kommander; s'executaran abans que l'script. En la majoria dels casos això no és un problema, però en alguns sí. </para>

<variablelist>
<varlistentry>
<term
><function
>@dcop(<parameter
>appId</parameter
>, <parameter
>objecte</parameter
>, <parameter
>funció</parameter
>, <parameter
>arguments</parameter
>)</function
></term>
<listitem>
<para
>Realitza una crida &DCOP;. @dcop(<quote
>kmail</quote
>, <quote
>KMailIface</quote
>, <quote
>checkMail()</quote
>, <quote
></quote
>) </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@dcopid</function
></term>
<listitem>
<para
>L'identificador &DCOP; del procés. (kmdr-executor-@pid). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@dialog(<parameter
>diàleg</parameter
>[,<parameter
>paràmetres</parameter
>])</function
></term>
<listitem>
<para
>Llança el diàleg de &kommander; especificat. El diàleg que se cerca en el directori de diàlegs i en el directori actual -en aquest ordre-. Aquesta tasca es du a terme abans de cridar a l'executor i establir el directori per omissió en el qual es troba l'aplicació &kommander;. Els paràmetres es poden passar a la forma usual de Unix o per nom com <quote
>variable=valor</quote
>. A continuació, pot trobar els paràmetres passats a la piscina global. @global(variable) retornaria <quote
>valor</quote
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@env(<parameter
>variableEntorn</parameter
>)</function
></term>
<listitem>
<para
>S'expandeix a la variable d'entorn especificada. @env(PWD) s'expandeix a $PWD. Recordeu que <quote
>$</quote
> forma part de la l'intèrpret d'ordres i no s'ha d'utilitzar. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@exec(<parameter
>ordre</parameter
>)</function
></term>
<listitem>
<para
>Retorna el resultat d'executar l'ordre especificada. @exec(ls -l). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@execBegin «...» @execEnd</function
></term>
<listitem>
<para
>El mateix que <function
>@exec</function
>, però admet scripts shebang i multi-línia. Això serveix per a diversos llenguatges d'script, ja sigui per declarar o per utilitzar 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 primer utilitza el nom de l'executable de <acronym
>PHP</acronym
>. &kommander; cerca a la PATH per a <application
>php</application
> i si no el troba mira per veure si s'ha registrat amb &kommander; a un lloc fora del seu camí. Si no s'indica l'usuari no el podrà trobar. Els segon exemple utilitza el clàssic <quote
>shebang</quote
>, el qual posseeix alguns avantatges i també certs inconvenients. Si teniu una còpia beta de <acronym
>PHP5</acronym
>, per exemple, en <filename
>/usr/local/bin</filename
> que no es trobi per no estar a <filename
>/usr/bin</filename
> això seria útil. No obstant, si distribuïu el diàleg amb algú que només tingui <acronym
>PHP</acronym
> a <filename
>/usr/local/bin</filename
> no el trobarà quan s'utilitzi shebang. Pel que utilitzeu els shebangs amb compte, i es recomana utilitzar l'executable si aneu a compartir fitxers.</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term
><function
>@null</function
></term>
<listitem>
<para
>Retorna null. Ara que &kommander; comprova en execució si widgetText és buit, això evitarà previndrà errors en el cas que hi hagi un estat sense definir en un estri.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@parentPid</function
></term>
<listitem>
<para
>El &PID; del procés pare. </para>
</listitem>
</varlistentry>

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

<varlistentry>
<term
><function
>@readSetting(<parameter
>clau</parameter
>, <parameter
>valorOmissió</parameter
>)</function
></term>
<listitem>
<para
>Llegeix un valor des de <filename
>kommanderrc</filename
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@selectedWidgetText</function
></term>
<listitem>
<para
>El contingut seleccionat en un estri que pot mostrar més d'un valor, com els estris de llista. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@setGlobal(<parameter
>variable</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>Estableix la variable global al valor especificat. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@widgetText</function
></term>
<listitem>
<para
>El contingut d'un estri. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@writeSetting(<parameter
>clau</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>Escriu un valor a <filename
>kommanderrc</filename
>. </para>
</listitem>
</varlistentry>
</variablelist>

<sect2 id="arrays">
<title
>Grup de funcions de matriu</title>

<variablelist>
<varlistentry>
<term
><function
>@Array.values(<parameter
>matriu</parameter
>)</function
></term>
<listitem>
<para
>Retorna una llista separada per final de línia de tots els valors en la matriu. Es pot utilitzar per a recórrer una matriu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.keys(<parameter
>matriu</parameter
>)</function
></term>
<listitem>
<para
>Retorna una llista separada per final de línia de totes les claus en la matriu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.setValue(<parameter
>matriu</parameter
>, <parameter
>clau</parameter
>, <parameter
>valor</parameter
>)</function
></term>
<listitem>
<para
>Estableix una clau i un valor per a un element d'una matriu. Si no hi ha cap matriu, es crearà.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.clear(<parameter
>matriu</parameter
>)</function
></term>
<listitem>
<para
>Elimina tots els elements de la matriu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.count(<parameter
>matriu</parameter
>)</function
></term>
<listitem>
<para
>Retorna el nombre d'elements en la matriu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.value(<parameter
>matriu</parameter
>,<parameter
>clau</parameter
>)</function
></term>
<listitem>
<para
>Retorna el valor associat a la clau donada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.remove(<parameter
>matriu</parameter
>,<parameter
>clau</parameter
>)</function
></term>
<listitem>
<para
>Elimina l'element amb la clau donada de la matriu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.fromString(<parameter
>matriu</parameter
>,<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>«Afegeix tots els elements en la cadena a la matriu. La cadena haurà de tenir el format <emphasis
>clau \tvalor\n</emphasis
>».</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@Array.toString(<parameter
>matriu</parameter
>,<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>«Retorna tots els elements a la matriu en el format <emphasis
>clau\tvalor\n</emphasis
>».</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="files">
<title
>Grup de funcions de fitxer</title>
<variablelist>

<varlistentry>
<term
><function
>@File.read(<parameter
>fitxer</parameter
>)</function
></term>
<listitem>
<para
>Retorna el contingut del fitxer donat.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@File.write(<parameter
>fitxer</parameter
><parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Escriu la cadena donada a un fitxer.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@File.append(<parameter
>fitxer</parameter
><parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Afegeix la cadena donada al final d'un fitxer.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="strings">
<title
>Grup de funcions de cadena</title>
<variablelist>

<varlistentry>
<term
><function
>@String.length(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Retorna el nombre de caràcters en la cadena.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.contains(<parameter
>cadena</parameter
>,<parameter
>subcadena</parameter
>)</function
></term>
<listitem>
<para
>Comprova si la cadena conté la subcadena donada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.find(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Retorna la posició d'una subcadena en la cadena, o -1 si no es troba.</para>
<note
><para
>Això tindrà una posició de començament opcional de tipus sencer per trobar propers usos en l'alfa 6.</para
></note>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.left(<parameter
>cadena</parameter
>, <parameter
>sencer</parameter
>)</function
></term>
<listitem>
<para
>Retorna els primers «núm.» caràcters de la cadena.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.right(<parameter
>cadena</parameter
>, <parameter
>sencer</parameter
>)</function
></term>
<listitem>
<para
>Retorna els últims «núm.» caràcters de la cadena.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.mid(<parameter
>cadena</parameter
>, <parameter
>sencer inici</parameter
>, <parameter
>sencer final</parameter
>)</function
></term>
<listitem>
<para
>Retorna una subcadena de la cadena, començant des de la posició donada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.remove(<parameter
>cadena</parameter
>, <parameter
>subcadena</parameter
>)</function
></term>
<listitem>
<para
>Elimina totes les ocurrències d'una subcadena donada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.replace(<parameter
>cadena</parameter
>, <parameter
>subcadena de cerca</parameter
>, <parameter
>subcadena de substitució</parameter
>)</function
></term>
<listitem>
<para
>Substitueix totes les ocurrències d'una subcadena donada amb una de substitució donada.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.upper(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Converteix la cadena a majúscules.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.lower(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Converteix la cadena a minúscules.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.compare(<parameter
>cadena</parameter
>, <parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Compara dues cadenes. Retorna 0 si són iguals, -1 si la primera és menor, 1 si la primera és major.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.isEmpty(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Comprova si la cadena és buida.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>@String.isNumber(<parameter
>cadena</parameter
>)</function
></term>
<listitem>
<para
>Comprova si la cadena és un nombre vàlid.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="builtins">
<title
>Globals encastades</title>
<para
>A les globals encastades s'accedeix com a les variables globals comunes amb <function
>@global</function
>.</para>
<variablelist>
<varlistentry>
<term
><function
>@global(_KDDIR)</function
></term>
<listitem>
<para
>El directori en el que es troba del diàleg actual.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>@global(_NAME)</function
></term>
<listitem
><para
>El nom del diàleg.</para
></listitem>
</varlistentry>
</variablelist>
</sect2>

</sect1>
