<chapter id="reference">
<title
>&turtlescript; Programming Reference</title>
<para
>This is the reference for &kturtle;'s &turtlescript;. In the first section of this chapter have a look at some aspects of the <link linkend="grammar"
>grammar</link
> of &turtlescript; programs. The second section deals exclusively with <link linkend="mathematical-operators"
>mathematical operators</link
>, <link linkend="boolean-operators"
>boolean (true/false) operators</link
> and <link linkend="comparing-operators"
>comparison operators</link
>. The third section is basically a giant list of all <link linkend="commands"
>commands</link
> explaining them one-by-one. Section four explains how to <link linkend="assignment-of-variables"
>assign</link
> values to <link linkend="assignment-of-variables"
>variables</link
>. Finally we explain how to arrange the execution of commands with <link linkend="controlling-execution"
>execution controlling statements</link
> in section five and how to create you own commands with <link linkend="learn"
>learn</link
> in section six.</para>

<sect1 id="grammar">
<title
>The Grammar of &turtlescript;</title>
<para
>As in any language, &turtlescript; has different types of words and symbols. In English we distinguish verbs (like 'to walk' or 'to sing') and nouns (like 'sister' or 'house'), they are used for different purposes. &turtlescript; is a programming language, it is used to instruct &kturtle; what to do.</para>
<para
>In this section some of &turtlescript;'s different types of words and symbols are briefly explained. We explain <link linkend="comment"
>comments</link
>, <link linkend="command"
>commands</link
> and the three different kinds of literals: <link linkend="number"
>numbers</link
>, <link linkend="string"
>strings</link
> and <link linkend="boolean-value"
>boolean (true/false) values</link
>.</para>


<sect2 id="comment">
<title
>Comentarios</title>
<para
>A program consists instructions that are executed when the program is run and so called comments. Comments are not executed, &kturtle; simply ignores them when executing your program. Comment are there for other programmers to make them understand your program better. Everything that follows on a <userinput
>#</userinput
> symbol is considered a comment in &turtlescript;. For example this little program that does nothing: <screen
>
# this little program does nothing, it is only a comment!
</screen
> It is a bit useless but it explain the matter well.</para>
<para
>Comments get very useful when the program gets a little bit more complex. It can help to give some advice to other programmers. In the following program you see comments being used together with the <link linkend="print"
>print</link
> command. <screen
>
# this program has been made by Cies Breijs.
print "this text will get printed on the canvas"
# the previous line is not a comment, but the next line is:
# print "this text will not get printed!"
</screen
> The first line describes the program. The second line is executed by &kturtle; and prints <userinput
>this text will get printed on the canvas</userinput
> on the canvas. The third line is a comment. And the forth line is a comment that contains a piece of &turtlescript;, if the <userinput
>#</userinput
> symbol would be removed on the fourth line the print statement will we executed by &kturtle;. Programmers say: the print statement on the fourth line is 'commented out'.</para>
<para
>Commented lines are <glossterm
>highlighted</glossterm
> with light gray in the <link linkend="the-editor"
>code editor</link
>.</para>
</sect2>

<sect2 id="command">
<title
>Comandos</title>
<para
>Using commands you tell the turtle or &kturtle; to do something. Some commands need input, some give output. <screen
>
# forward is a command that needs input, in this case the number 100:
forward 100
</screen
> The first line is a <link linkend="comment"
>comment</link
>. The second line contains the <userinput
>forward</userinput
> command and the <link linkend="number"
>number</link
> <userinput
>100</userinput
>. The number is not part of command, it is considered 'input' for the command.</para>
<para
>For a detailed overview of all commands that &kturtle; supports go <link linkend="commands"
>here</link
>. Built-in commands are <glossterm
>highlighted</glossterm
> in dark blue</para>
</sect2>

<sect2 id="number">
<title
>Números</title>
<para
>Posibelmente xa saiba bastante acerca dos números. A maneira de utilizar os números en &kturtle; non é moi diferente da oral, nen da matemática. </para>
<para
>We have the so called natural numbers: <userinput
>0</userinput
>, <userinput
>1</userinput
>, <userinput
>2</userinput
>, <userinput
>3</userinput
>, <userinput
>4</userinput
>, <userinput
>5</userinput
>, etc. The negative numbers: <userinput
>-1</userinput
>, <userinput
>-2</userinput
>, <userinput
>-3</userinput
>, etc. And the numbers with decimals, or dot-numbers, for example: <userinput
>0.1</userinput
>, <userinput
>3.14</userinput
>, <userinput
>33.3333</userinput
>, <userinput
>-5.05</userinput
>, <userinput
>-1.0</userinput
>. </para>
<para
>Numbers can be used in <link linkend="mathematical-operators"
>mathematical operators</link
> and <link linkend="comparing-operators"
>comparison operators</link
>. They can also be stored in <link linkend="assignment-of-variables"
>variables</link
>. Numbers are <glossterm
>highlighted</glossterm
> in dark red.</para>
</sect2>

<!-- constants like pi? -->

<sect2 id="string">
<title
>Textos</title>
<para
>Primeiro un exemplo: <screen>
escrebe "Olá, son un texto."</screen>
Neste exemplo <userinput
>escrebe</userinput
> é un comando no que <userinput
>"Olá, son un texto."</userinput
> é un texto. Os textos comezan e rematan con aspas, <userinput
>"</userinput
>, mediante as cais &kturtle; sabe que é un texto.</para>
<para
>Strings can be put in <link linkend="assignment-of-variables"
>variables</link
>, just like <link linkend="number"
>numbers</link
>. Yet, unlike numbers, strings cannot be used in <link linkend="mathematical-operators"
>mathematical operators</link
> or <link linkend="comparing-operators"
>comparison operators</link
>. Strings are <glossterm
>highlighted</glossterm
> with red.</para>
</sect2>

<sect2 id="boolean-value">
<title
>Boolean (true/false) values</title>
<para
>There are only two boolean values: <userinput
>true</userinput
> and <userinput
>false</userinput
>. Sometimes they are also called: on and off, yes and no, one and zero. But in &turtlescript; we call them, always, <userinput
>true</userinput
> and <userinput
>false</userinput
>. Have a look at this piece of &turtlescript;: <screen
>
$a = true
</screen
> If you look in the <link linkend="the-inspector"
>inspector</link
> you can see that the <link linkend="assignment-of-variables"
>variable</link
> <userinput
>$a</userinput
> is set to <userinput
>true</userinput
>, and has the boolean type.</para>
<para
>Often boolean values are the result of a <link linkend="comparing-operators"
>comparison operator</link
>, like in the following piece of &turtlescript;: <screen
>
$answer = 10 &gt; 3
</screen
> The <link linkend="assignment-of-variables"
>variable</link
> <userinput
>$answer</userinput
> is set to <userinput
>true</userinput
> because <userinput
>10</userinput
> is larger than <userinput
>3</userinput
>.</para>
<para
>Boolean values, <userinput
>true</userinput
> and <userinput
>false</userinput
>, are <glossterm
>highlighted</glossterm
> with dark red.</para>
</sect2>

</sect1>



<sect1 id="operators">
<title
>Mathematical, boolean and comparing operators</title>
<para
>The title of this section might sound very difficult, yet it is not as difficult as it sound.</para>

<sect2 id="mathematical-operators">
<title
>Mathematical operators</title>
<para
>These are the basic math symbols known as: add (<userinput
>+</userinput
>), subtract (<userinput
>-</userinput
>), multiply (<userinput
>*</userinput
>), divide (<userinput
>/</userinput
>) and power (<userinput
>^</userinput
>).</para>

<para
>Here a small example of the mathematical operators you can use in &turtlescript;: <screen
>
$add      = 1 + 1
$subtract = 20 - 5
$multiply = 15 * 2
$divide   = 30 / 30
$power    = 2 ^ 2
</screen
> The values resulting from the mathematical operations get <link linkend="assignment-of-variables"
>assigned</link
> to various <link linkend="assignment-of-variables"
>variables</link
>. Using the <link linkend="the-inspector"
>inspector</link
> you can see the values.</para>
<para
>Se só quer facer un cálculo simples pode facer algo como isto: <screen
>print 2010-12
</screen
></para>
<para
>Now an example with parentheses: <screen
>
print ( ( 20 - 5 ) * 2 / 30 ) + 1
</screen
> The expressions inside parentheses will be calculated first. In this example, 20-5 will be calculated, then multiplied by 2, divided by 30, and then 1 is added (giving 2). Parentheses can also be used in other cases.</para>
<para
>&kturtle; also has more advanced mathematical features in the form of commands. Have a look at the following commands but be aware that it concerns advanced operations: <link linkend="round"
>round</link
>, <link linkend="random"
>random</link
>, <link linkend="sqrt"
>sqrt</link
> , <link linkend="pi"
>pi</link
>, <link linkend="sin"
>sin</link
>, <link linkend="cos"
>cos</link
>, <link linkend="tan"
>tan</link
>, <link linkend="arcsin"
>arcsin</link
>, <link linkend="arccos"
>arccos</link
>, <link linkend="arctan"
>arctan</link
>.</para>
</sect2>

<sect2 id="boolean-operators">
<title
>Boolean (true/false) operators</title>
<para
>Where <link linkend="mathematical-operators"
>mathematical operators</link
> are mainly for <link linkend="number"
>numbers</link
>, boolean operators are for <link linkend="boolean-value"
>boolean values</link
> (<userinput
>true</userinput
> and <userinput
>false</userinput
>). There are only three boolean operators, namely: <userinput
>and</userinput
>, <userinput
>or</userinput
>, and <userinput
>not</userinput
>. The following piece of &turtlescript; shows how to use them: <screen
>
$and_1_1 = true and true    # -> true
$and_1_0 = true and false   # -> false
$and_0_1 = false and true   # -> false
$and_0_0 = false and false  # -> false

$or_1_1 = true or true    # -> true
$or_1_0 = true or false   # -> true
$or_0_1 = false or true   # -> true
$or_0_0 = false or false  # -> false

$not_1 = not true   # -> false
$not_0 = not false  # -> true
</screen
> Using the <link linkend="the-inspector"
>inspector</link
> you can see the values, yet we also supply these results as little comments at the end of the lines. <userinput
>and</userinput
> evaluates <userinput
>true</userinput
> only if both sides are <userinput
>true</userinput
>. <userinput
>or</userinput
> evaluates <userinput
>true</userinput
> if either side is <userinput
>true</userinput
>. And <userinput
>not</userinput
> turns a <userinput
>true</userinput
> into <userinput
>false</userinput
> and a <userinput
>false</userinput
> into <userinput
>true</userinput
>.</para>
<para
>Boolean operators are <glossterm
>highlighted</glossterm
> with pink.</para>

<sect3 id="boolean-operators-advanced-examples">
<title
>Some more advanced examples</title>
<para
>Consider the following example with <userinput
>and</userinput
>: <screen
>
$a = 1
$b = 5
if (($a &lt; 10) and ($b == 5)) and ($a &lt; $b) {
  print "hello"
}
</screen
> In this piece of &turtlescript; the result of three <link linkend="comparing-operators"
>comparing operators</link
> are merged using <userinput
>and</userinput
> operators. This means that all three have to evaluate "true" in order for the "hello" to be printed.</para>

<para
>An example with <userinput
>or</userinput
>: <screen
>
$n = 1
if ($n &lt; 10) or ($n == 2) {
  print "hello"
}
</screen
> In this piece of &turtlescript; the left side of the <userinput
>or</userinput
> is evaluating to 'true', the right side to 'false'. Since one of the two sides of the <userinput
>or</userinput
> operator is 'true', the <userinput
>or</userinput
> operator evaluates 'true'. That means "hello" gets printed.</para>

<para
>And finally an example with <userinput
>not</userinput
> which changes 'true' into 'false' and 'false' into 'true'. Have a look: <screen
>$n = 1
if not ($n == 3) {
  print "hello"
} else {
  print "not hello ;-)"
}
</screen
></para>
</sect3>
</sect2>

<sect2 id="comparing-operators">
<title
>Comparing operators</title>
<para
>Consider this simple comparison: <screen
>
$answer = 10 &gt; 3
</screen
> Here <userinput
>10</userinput
> is compared to <userinput
>3</userinput
> with the 'greater than' operator. The result of this comparison, the <link linkend="boolean-value"
>boolean value</link
> <userinput
>true</userinput
> is stored in the <link linkend="assignment-of-variables"
>variable</link
> <userinput
>$answer</userinput
>.</para>
<para
>All <link linkend="number"
>numbers</link
> and <link linkend="assignment-of-variables"
>variables</link
> (that contain numbers) can be compared to each other with comparing operators.</para>
<para
>Here are all possible comparing operators: <table
> <title
>Types of questions</title
> <tgroup cols="3"
> <tbody
> <row
> <entry
><userinput
>$A == $B</userinput
></entry
> <entry
>equals</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> equals <userinput
>$B</userinput
></entry
> </row
> <row
> <entry
><userinput
>$A != $B</userinput
></entry
> <entry
>not-equals</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> does not equal <userinput
>$B</userinput
></entry
> </row
> <row
> <entry
><userinput
>$A &gt; $B</userinput
></entry
> <entry
>greater than</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> is greater than <userinput
>$B</userinput
></entry
> </row
> <row
> <entry
><userinput
>$A &lt; $B</userinput
></entry
> <entry
>smaller than</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> is smaller than <userinput
>$B</userinput
></entry
> </row
> <row
> <entry
><userinput
>$A &gt;= $B</userinput
></entry
> <entry
>greater than or equals</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> is greater than or equals <userinput
>$B</userinput
></entry
> </row
> <row
> <entry
><userinput
>$A &lt;= $B</userinput
></entry
> <entry
>smaller than or equals</entry
> <entry
>answer is <quote
>true</quote
> if <userinput
>$A</userinput
> is smaller than or equals <userinput
>$B</userinput
></entry
> </row
> </tbody
> </tgroup
> </table
> Please note that $A and $B have to be <link linkend="number"
>numbers</link
> or <link linkend="assignment-of-variables"
>variables</link
> that contain numbers.</para>
</sect2>


</sect1>



<sect1 id="commands">
<title
>Comandos</title>
<para
>Using commands you tell the turtle or &kturtle; to do something. Some commands need input, some give output. In this section we explain all the built-in commands of &kturtle;. Alternatively, using <link linkend="learn"
>learn</link
>, you can create your own commands. Built-in commands we discuss here are <glossterm
>highlighted</glossterm
> with dark blue.</para>

<sect2 id="moving-the-turtle">
<title
>Mover o sapoconcho</title>
<para
>Hai varios comandos que moven o sapoconcho pola pantalla.</para>

  <variablelist>
    <anchor id="forward"/>
    <varlistentry
> 
      <term
>avanza (av)<indexterm
><primary
>avanza (av)</primary
></indexterm
></term>
      <listitem
><para
><screen
>avanza X</screen>
<userinput
>avanza</userinput
> move o sapoconcho cara diante X píxeles. Cando o lápis está pousado deixará un rastro. <userinput
>avanza</userinput
> pode abreviarse como <userinput
>av</userinput
></para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="backward"/>
    <varlistentry
>  
      <term
>recua (re)<indexterm
><primary
>recua (re)</primary
></indexterm
></term>
      <listitem
><para
><screen
>recua X</screen>
<userinput
>recua</userinput
> move o sapoconcho cara atrás X píxeles. Se o lápis está pousado deixará un rastro. <userinput
>recua</userinput
> pode ser abreviado como <userinput
>re</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="turnleft"/>
    <varlistentry
> 
      <term
>xiraesquerda (xe)<indexterm
><primary
>xiraesquerda (xe)</primary
></indexterm
></term>
      <listitem
><para
><screen
>xiraesquerda X</screen>
<userinput
>xiraesquerda</userinput
> ordénalle ao sapoconcho que xire X graus á esquerda. <userinput
>xiraesquerda</userinput
> pode abreviarse como <userinput
>xe</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="turnright"/>
    <varlistentry
> 
      <term
>xiradereita (xd)<indexterm
><primary
>xiradereita (xd)</primary
></indexterm
></term>
      <listitem
><para
><screen
>xiradereita X</screen>
<userinput
>xiradereita</userinput
> ordénalle ao sapoconcho que xire X graus á dereita. <userinput
>xiradereita</userinput
> pode abreviarse como <userinput
>xd</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="direction"/>
    <varlistentry
> 
      <term
>direccion (dir)<indexterm
><primary
>direccion (dir)</primary
></indexterm
></term>
      <listitem
><para
><screen
>direccion X</screen>
<userinput
>direccion</userinput
> fai que o sapoconcho tome unha ruta a X graus do cero, polo que non é relativa á anterior ruta que seguise o sapoconcho. <userinput
>direccion</userinput
> pode abreviarse como <userinput
>dir</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="center"/>
    <varlistentry
> 
      <term
>vaiaocentro<indexterm
><primary
>vaiaocentro</primary
></indexterm
></term>
      <listitem
><para
><screen
>vaiaocentro</screen>
<userinput
>vaiaocentro</userinput
> leva o sapoconcho ao centro do lenzo.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="go"/>
    <varlistentry
> 
      <term
>vai<indexterm
><primary
>vai</primary
></indexterm
></term>
      <listitem
><para
><screen
>vai X,Y</screen>
<userinput
>go</userinput
> commands the turtle to go to a certain place on the canvas. This place is X <glossterm linkend="pixels"
>pixels</glossterm
> from the left of the canvas, and Y <glossterm linkend="pixels"
>pixels</glossterm
> form the top of the canvas. </para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="gox"/>
    <varlistentry
> 
      <term
>vaix<indexterm
><primary
>vaix</primary
></indexterm
></term>
      <listitem
><para
><screen
>vaix X</screen>
<userinput
>vaix</userinput
> fai que o sapoconcho vaia a unha posición situada a X <glossterm linkend="pixels"
>píxeles</glossterm
> do borde esquerdo do lenzo sen desprazarse en altura.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="goy"/>
    <varlistentry
> 
      <term
>vaiy<indexterm
><primary
>vaiy</primary
></indexterm
></term>
      <listitem
><para
><screen
>vaiy Y</screen>
<userinput
>gox</userinput
> using this command the turtle will move to Y <glossterm linkend="pixels"
>pixels</glossterm
> from the top of the canvas whilst staying at the same distance from the left border of the canvas.</para
></listitem>
    </varlistentry>
  </variablelist>
  <note
><para
>Cando se utilizan os comandos <userinput
>vai</userinput
>, <userinput
>vaix</userinput
>, <userinput
>vaiy</userinput
> e <userinput
>vaiaocentro</userinput
> o sapoconcho non debuxa a liña, con independencia de que o lápis estexa erguido ou pousado.</para>
  </note>
</sect2>

<sect2 id="locate-the-turtle">
<title
>Onde está o sapoconcho?</title>
<para
>Hai dous comandos que din a posición do sapoconcho na pantalla.</para>

  <variablelist>
    <anchor id="getx"/>
    <varlistentry
> 
      <term
>coordenadaX<indexterm
><primary
>coordenadaX</primary
></indexterm
></term>
      <listitem
><para
><userinput
>coordenadaX</userinput
> devolve a cantidade de píxeles que hai desde a esquerda do lenzo até a posición do sapoconcho.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="gety"/>
    <varlistentry
> 
      <term
>coordenadaY<indexterm
><primary
>coordenadaY</primary
></indexterm
></term>
      <listitem
><para
><userinput
>coordenadaY</userinput
> devolve a cantidade de píxeles que hai do cume do lenzo até a posición do sapoconcho.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="pen">
<title
>O sapoconcho ten un lápis</title>
<para
>O sapoconcho ten un lápis que debuxa unha liña á medida que se move o animal. Hai uns poucos comandos que controlan este lápis. Nesta sección explicarémolos.</para>
  <variablelist>
    <anchor id="penup"/>
    <varlistentry
> 
      <term
>subelapis (sl)<indexterm
><primary
>subelapis (sl)</primary
></indexterm
></term>
      <listitem
><para
><screen
>subelapis</screen>
<userinput
>subelapis</userinput
> separa o lápis do lenzo. Cando o lápis está <quote
>subido</quote
> non se debuxan liñas ao moverse o sapoconcho. Consulte tamén <userinput
>baixalapis</userinput
>. <userinput
>subeLapis</userinput
> pode abreviarse como <userinput
>sl</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="pendown"/>
    <varlistentry
> 
      <term
>baixalapis (bl)<indexterm
><primary
>baixalapis (bl)</primary
></indexterm
></term>
      <listitem
><para
><screen
>baixalapis</screen>
<userinput
>baixalapis</userinput
> pousa o lápis no lenzo. Cando o lápis está <quote
>baixado</quote
> debúxanse liñas cando se move o sapoconcho. Consulte tamén <userinput
>subelapis</userinput
>. <userinput
>baixalapis</userinput
> pode abreviarse como <userinput
>bl</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="setpenwidth"/>
    <varlistentry
> 
      <term
>ancholapis (al)<indexterm
><primary
>ancholapis (al)</primary
></indexterm
></term>
      <listitem
><para
><screen
>ancholapis X</screen>
<userinput
>ancholapis</userinput
> estabelece o grosor do trazo co valor de X <glossterm linkend="pixels"
>píxeles</glossterm
>. <userinput
>ancholapis</userinput
> pode abreviarse como <userinput
>al</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="setfgcolor"/>
    <varlistentry
> 
      <term
>corlapis (cl)<indexterm
><primary
>corlapis (cl)</primary
></indexterm
></term>
      <listitem
><para
><screen
>corlapis R,G,B</screen>
<userinput
>corlapis</userinput
> estabelece a cor do trazo. <userinput
>corlapis</userinput
> toma como parámetro unha <glossterm linkend="rgb"
>combinación RGB</glossterm
>. <userinput
>corlapis</userinput
> code abreviarse como <userinput
>cl</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="canvas">
<title
>Comandos para controlar o lenzo</title>
<para
>Hai varios comandos que controlan o lenzo.</para>
  <variablelist>
    <anchor id="resizecanvas"/>
    <varlistentry>
      <term
>tamañolenzo (tlz)<indexterm
><primary
>tamañolenzo (tlz)</primary
></indexterm
></term>
      <listitem
><para
><screen
>tamañolenzo X,Y</screen>
Mediante o comando <userinput
>tamañolenzo</userinput
> pode axustar o tamaño da área. Toma X e Y como entradas, onde X é o novo ancho do lenzo en <glossterm linkend="pixels"
>píxeles</glossterm
> e Y é o novo alto en <glossterm linkend="pixels"
>píxeles</glossterm
>. <userinput
>tamañolenzo</userinput
> pode abreviarse como <userinput
>tlz</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="setbgcolor"/>
    <varlistentry
> 
      <term
>corlenzo (clz)<indexterm
><primary
>corlenzo (clz)</primary
></indexterm
></term>
      <listitem
><para
><screen
>corlenzo R,G,B</screen>
<userinput
>corlenzo</userinput
> estabelece a cor do lenzo. <userinput
>corlenzo</userinput
> toma unha <glossterm linkend="rgb"
>combinación RGB</glossterm
> como entrada. <userinput
>corlenzo</userinput
> pode abreviarse como <userinput
>clz</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="clean">
<title
>Comandos para borrar</title>
<para
>Hai dous comandos para limpar o lenzo cando o emborrona.</para>
  <variablelist>
    <anchor id="clear"/>
    <varlistentry
> 
      <term
>borra (br)<indexterm
><primary
>borra (br)</primary
></indexterm
></term>
      <listitem
><para
><screen
>borra</screen>
Con <userinput
>borra</userinput
> pode borrar do lenzo todos os debuxos. As demais cousas fican: a posición e ángulo do sapoconcho, a cor do lenzo, a visibilidade do sapoconcho e o tamaño do lenzo.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="reset"/>
    <varlistentry
> 
      <term
>reinicia<indexterm
><primary
>reinicia</primary
></indexterm
></term>
      <listitem
><para
><screen
>reinicia</screen>
<userinput
>reinicia</userinput
> limpa máis a fondo do que o fai o comando <userinput
>borra</userinput
>. Despois de executar un comando <userinput
>reinicia</userinput
> todo volta a ser como cando iniciou &kturtle;. O sapoconcho estará posto no centro da pantalla, a cor do lenzo será branco, debuxarase cun trazo negro e o tamaño do lenzo será de 400 x 400 píxeles.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="sprites">
<title
>O sapoconcho é un sprite</title>
<para
>Os sprites son pequenas imaxes que se poden mover pola pantalla, como se ve nos xogos de consola. O noso animaliño tamén é un sprite. Para saber máis acerca disto, consulte a entrada <glossterm linkend="sprites"
>sprites</glossterm
> no glosario. </para>
<para
>A seguir ten un resumo completo de todos os comandos que traballan sobre sprites.</para>
<para
>[A versión actual de &kturtle; aínda non permite utilizar outros sprites que non sexan o sapoconcho. En versións futuras poderá mudar para outro deseño á súa escolla]</para>
  <variablelist>
    <anchor id="spriteshow"/>
    <varlistentry
> 
      <term
>mostrasapoconcho (msc)<indexterm
><primary
>mostrasapoconcho (msc)</primary
></indexterm
></term>
      <listitem
><para
><screen
>mostrasapoconcho</screen>
<userinput
>mostrasapoconcho</userinput
> fai de novo visíbel ao sapoconcho se antes foi agochado. <userinput
>mostrasapoconcho</userinput
> pode abreviarse como <userinput
>msc</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="spritehide"/>
    <varlistentry
> 
      <term
>agochasapoconcho (asc)<indexterm
><primary
>agochasapoconcho (asc)</primary
></indexterm
></term>
      <listitem
><para
><screen
>agochasapoconcho</screen>
<userinput
>agochasapoconcho</userinput
> fai invisíbel ao sapoconcho. Isto pode empregarse se o animal non couber no debuxo. <userinput
>agochasapoconcho</userinput
> pode abreviarse como <userinput
>asc</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="writing">
<title
>Pode escreber o sapoconcho?</title>
<para
>A resposta é: <quote
>pode</quote
>. A tartaruga pode escreber, e escreberá calquera cousa que lle mande.</para>
  <variablelist>
    <anchor id="print"/>
    <varlistentry
> 
      <term
>escrebe<indexterm
><primary
>escrebe</primary
></indexterm
></term>
      <listitem
><para
><screen
>escrebe X</screen>
O comando <userinput
>escrebe</userinput
> ordénalle ao sapoconcho que escreba algo no lenzo. <userinput
>escrebe</userinput
> pode tomar textos e números como parámetros. Pode <userinput
>escrebe</userinput
>r varios números e cadeas mediante o símbolo <quote
>+</quote
>. Aquí vai un exemplo: <screen
>$ano = 2009
$autor = "Bruno"
escrebe $autor + " debuxou unha nora en KTurtle no ano" + $ano + " e gustoulle moito!"
</screen>
      </para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="fontsize"/>
    <varlistentry
> 
      <term
>letratamaño<indexterm
><primary
>letratamaño</primary
></indexterm
></term>
      <listitem
><para
><screen
>letratamaño X</screen>
<userinput
>letratamaño</userinput
> modifica o tamaño de letra utilizado ao <userinput
>escreber</userinput
>. <userinput
>letratamaño</userinput
> toma un argumento numérico. O tamaño indícase en <glossterm linkend="pixels"
>píxeles</glossterm
>.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="math-commands">
<title
>Mathematical commands</title>
<para
>The following commands are &kturtle;'s more advanced mathematical commands.</para>
  <variablelist>
    <anchor id="round"/>
    <varlistentry>
      <term
>redondea<indexterm
><primary
>redondea</primary
></indexterm
></term>
      <listitem
><para
><screen
>redondea (x)</screen>
<userinput
>round</userinput
> the given number to the nearest integer. <screen
>
print round(10.8)
forward 20
print round(10.3)
</screen
> With this code the turtle will print the numbers 11 and 10.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="random"/>
    <varlistentry
> 
      <term
>aleatorio (alea)<indexterm
><primary
>aleatorio (alea)</primary
></indexterm
></term>
      <listitem
><para
><screen
>aleatorio X,Y</screen>
<userinput
>aleatorio</userinput
> é un comando que toma unha entrada e saca un resultado. Como entrada precisa de dous números, o primeiro (X) é o resultado mínimo, o segundo (Y) o máximo. A saída é un número escollido ao chou que é como mínimo o menor e como máximo o maior. Aquí vai un exemplo:<screen>
repite 500 {
  $x = aleatorio 1,20
  avanza $x
  xiraesquerda 10 - $x
}
</screen
> Mediante o comando <userinput
>aleatorio</userinput
> pode introducir algo de caos no programa.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="sqrt"/>
    <varlistentry
> 
      <term
>sqrt<indexterm
><primary
>sqrt</primary
></indexterm
></term>
      <listitem
><para
><screen
>sqrt X</screen>
The <userinput
>sqrt</userinput
> command is sued to find the square root of a number, X.</para
></listitem>
    </varlistentry>
  </variablelist>
<!--
  <variablelist>
    <anchor id="exp"/>
    <varlistentry
> 
      <term
>exp<indexterm
><primary
>exp</primary
></indexterm
></term>
      <listitem
><para
><screen
>sqrt X</screen>
      </para
></listitem>
    </varlistentry>
  </variablelist>
-->
  <variablelist>
    <anchor id="pi"/>
    <varlistentry
> 
      <term
>pi<indexterm
><primary
>pi</primary
></indexterm
></term>
      <listitem
><para
><screen
>pi</screen>
This command returns the constant Pi, <userinput
>3.14159</userinput
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="sin"/>
    <anchor id="cos"/>
    <anchor id="tan"/>
    <varlistentry>
      <term
>sin<indexterm
><primary
>sin</primary
></indexterm
>, cos<indexterm
><primary
>cos</primary
></indexterm
>, tan<indexterm
><primary
>tan</primary
></indexterm
></term>
      <listitem
><para>
<screen
>sin X
cos X
tan X
</screen>
These three commands represent the world famous trigoniometrical functions <userinput
>sin</userinput
>, <userinput
>cos</userinput
> and <userinput
>tan</userinput
>. The input argument of these commands, X, is a <link linkend="number"
>number</link
>.</para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="arcsin"/>
    <anchor id="arccos"/>
    <anchor id="arctan"/>
    <varlistentry>
      <term
>arcsin<indexterm
><primary
>arcsin</primary
></indexterm
>, arccos<indexterm
><primary
>arccos</primary
></indexterm
>, arctan<indexterm
><primary
>arctan</primary
></indexterm
></term>
      <listitem
><para>
<screen
>arcsin X
arccos X
arctan X
</screen>
These commands are the inverse functions of <link linkend="sin"
>sin</link
>, <link linkend="cos"
>cos</link
> and <link linkend="tan"
>tan</link
>. The input argument of these commands, X, is a <link linkend="number"
>number</link
>.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="dialogs">
<title
>Introdución de datos e obtención de resultados mediante diálogos</title>
<para
>Un diálogo é unha pequena fiestra emerxente que lle dá algo de información ou que lle pide algún dato. &kturtle; ten dous comandos para diálogos, que son: <userinput
>mostra</userinput
> e <userinput
>pergunta</userinput
></para>
  <variablelist>
    <anchor id="message"/>
    <varlistentry
> 
      <term
>mostra<indexterm
><primary
>mostra</primary
></indexterm
></term>
      <listitem
><para
><screen
>mostra X</screen>
O comando <userinput
>mostra</userinput
> toma un <link linkend="string"
>texto</link
> como entrada, e mostra un diálogo que contén o <link linkend="string"
>texto</link
>. <screen
>message "Cies started KTurtle in 2003 and still enjoys working on it!"
</screen>
      </para
></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="ask"/>
    <varlistentry
> 
      <term
>pergunta<indexterm
><primary
>pergunta</primary
></indexterm
></term>
      <listitem
><para
><screen
>pergunta X</screen>
<userinput
>ask</userinput
> takes a <link linkend="string"
>string</link
> as input. It shows this string in a pop-up dialog (similar to <link linkend="message"
>message</link
>), along with an input field. After the user has entered a <link linkend="number"
>number</link
> or a <link linkend="string"
>string</link
> into this, the result can be stored in a <link linkend="assignment-of-variables"
>variable</link
> or passed as an argument to a <link linkend="commands"
>command</link
>. For example: <screen
>
$in = ask "What is your year of birth?"
$out = 2003 - $in
print "In 2003 you were " + $out + " years old at some point."
</screen
> If the user cancels the input dialog, or does not enter anything at all, the <link linkend="assignment-of-variables"
>variable</link
> is empty.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

</sect1>



<sect1 id="assignment-of-variables">
<title
>Assignment of variables</title>
<para
>First we have a look at variables, then we look at assigning values to those variables. </para>

<para
>Variables are words that start with a <quote
>$</quote
>, in the <link linkend="the-editor"
>editor</link
> they are <glossterm
>highlighted</glossterm
> with purple.</para>

<para
>Variables can contain any <link linkend="number"
>number</link
>, <link linkend="string"
>string</link
> or <link linkend="boolean-value"
>boolean (true/false) value</link
>. Using the assignment, <userinput
>=</userinput
>, a variable is given its content. It will keep that content until the program finishes executing or until the variable is reassigned to something else.</para>

<para
>You can use variables, once assigned, just as if they are their content. For instance in the following piece of &turtlescript;: <screen
>
$x = 10
$x = $x / 3
print $x
</screen
> First the variable <userinput
>$x</userinput
> is assigned to <userinput
>10</userinput
>. Then <userinput
>$x</userinput
> is reassigned to itself divided by <userinput
>3</userinput
> &mdash; this effectively means <userinput
>$x</userinput
> is reassigned to product of <userinput
>10 / 3</userinput
>. Finally <userinput
>$x</userinput
> is printed. In line two and three you see that <userinput
>$x</userinput
> is used as if it is its contents.</para>

<para
>Variables have to be assigned in order to be used. For example: <screen
>
print $n
</screen
> Will result in an error message.</para>

<para
>Please consider the following piece of &turtlescript;: <screen
>
$a = 2004
$b = 25

# the next command prints "2029"
print $a + $b
backward 30
# the next command prints "2004 plus 25 equals 2029"
print $a + " plus " + $b + " equals " + ($a + $b)
</screen
> In the first two lines the variables <userinput
>$a</userinput
> and <userinput
>$b</userinput
> are set to 2004 and 25. Then in two <userinput
>print</userinput
> commands with a <userinput
>backward 30</userinput
> in between are executed. The comments before the <userinput
>print</userinput
> commands explain what they are doing. The command <userinput
>backward 30</userinput
> is there to make sure every output is on a new line. As you see variables can be used just as if their where what they contain, you can use them with any kind of <link linkend="operators"
>operators</link
> or give them as input when invoking <link linkend="commands"
>commands</link
>.</para>

<para
>One more example: <screen
>
$name = ask "What is your name?"
print "Hi " + $name + "! Good luck while learning the art of programming..."
</screen
> Pretty straight forward. Again you can see that the variable <userinput
>$name</userinput
>, treated just like a string.</para>

<para
>When using variables the <link linkend="the-inspector"
>inspector</link
> is very helpful. It shows you the contents of all variables that are currently in use.</para>
</sect1>



<sect1 id="controlling-execution">
<title
>Control da execución</title>
<para
>Os controladores da execución permítenlle, como indica o nome, controlar o fluxo de execución.</para>
<para
>Execution controlling commands are <glossterm
>highlighted</glossterm
> with dark green in a bold font type. The brackets are mostly used together with execution controllers and they are <glossterm
>highlighted</glossterm
> with black.</para>

<sect2 id="wait">
<title
>Facer que o sapoconcho agarde</title>
<para
>Se programou algo en &kturtle; xa se terá decatado de que o sapoconcho pode ser moi moi moi rápido cando debuxa. Este comando fai que agarde durante un tempo.</para>
  <variablelist>
    <varlistentry>
      <term
>agarda<indexterm
><primary
>agarda</primary
></indexterm
></term>
      <listitem
><para
><screen
>agarda X</screen>
<userinput
>agarda</userinput
> fai que o sapoconcho estexa quedo durante X segundos. <screen>
repite 36 {
  avanza 5
  xiradereita 10
  agarda 0.5
}
</screen
> Este código debuxa un círculo, pero o animal agardará medio segundo tras cada paso. Isto dá a impresión dun sapoconcho lento.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="if">
<title
>Executar "se"</title>
  <variablelist>
    <varlistentry>
      <term
>se<indexterm
><primary
>se</primary
></indexterm
></term>
      <listitem
><para
><screen
>if <link linkend="boolean-value">boolean</link> { ... }</screen>
The code that is placed between the brackets will only be executed <userinput
>if</userinput
> the <link linkend="boolean-value"
>boolean value</link
> evaluates <quote
>true</quote
>. <screen
>
$x = 6
if $x &gt; 5 {
  print "$x is greater than five!"
}
</screen
> On the first line <userinput
>$x</userinput
> is set to 6. On the second line a <link linkend="comparing-operators"
>comparing operator</link
> is used to evaluate <userinput
>$x &gt; 5</userinput
>. Since this evaluates <quote
>true</quote
>, 6 is larger than 5, the execution controller <userinput
>if</userinput
> will allow the code between the brackets to be executed.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="else">
<title
>Se non, o caso contrario: "noutrocaso"</title>
  <variablelist>
    <varlistentry>
      <term
>noutrocaso<indexterm
><primary
>noutrocaso</primary
></indexterm
></term>
      <listitem
><para
><screen
>if <link linkend="boolean-value">boolean</link> { ... } else { ... }</screen>
<userinput
>else</userinput
> can be used in addition to the execution controller <link linkend="if"
><userinput
>if</userinput
></link
>. The code between the brackets after <userinput
>else</userinput
> is only executed if the <link linkend="boolean-value"
>boolean</link
> evaluates <quote
>false</quote
>. <screen
>
reset
$x = 4
if $x &gt; 5 {
  print "$x is greater than five!"
} else {
  print "$x is smaller than six!"
}
</screen
> The <link linkend="comparing-operators"
>comparing operator</link
> evaluates the expression <userinput
>$x &gt; 5</userinput
>. Since 4 is not greater than 5 the expression evaluates <quote
>false</quote
>. This means the code between the brackets after <userinput
>else</userinput
> gets executed.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="while">
<title
>O ciclo "mentres"</title>
  <variablelist>
    <varlistentry>
      <term
>mentres<indexterm
><primary
>mentres</primary
></indexterm
></term>
      <listitem
><para
><screen
>while <link linkend="boolean-value">boolean</link> { ... }</screen>
The execution controller <userinput
>while</userinput
> is a lot like <link linkend="if"
><userinput
>if</userinput
></link
>. The difference is that <userinput
>while</userinput
> keeps repeating (looping) the code between the brackets until the <link linkend="boolean-value"
>boolean</link
> evaluates <quote
>false</quote
>. <screen
>
$x = 1
while $x &lt; 5 {
  forward 10
  wait 1
  $x = $x + 1
}
</screen
> On the first line <userinput
>$x</userinput
> is set to 1. On the second line <userinput
>$x &lt; 5</userinput
> is evaluated. Since the answer to this question is <quote
>true</quote
> the execution controller <userinput
>while</userinput
> starts executing the code between the brackets until the <userinput
>$x &lt; 5</userinput
> evaluates <quote
>false</quote
>. In this case the code between the brackets will be executed 4 times, because every time the fifth line is executed <userinput
>$x</userinput
> increases by 1.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="repeat">
<title
>O ciclo "repite"</title>
  <variablelist>
    <varlistentry>
      <term
>repite<indexterm
><primary
>repite</primary
></indexterm
></term>
      <listitem
><para
><screen
>repeat <link linkend="number">number</link> { ... }</screen>
The execution controller <userinput
>repeat</userinput
> is a lot like <link linkend="while"
><userinput
>while</userinput
></link
>. The difference is that <userinput
>repeat</userinput
> keeps repeating (looping) the code between the brackets for as many times as the given number.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="for">
<title
>O ciclo "desde", un ciclo cun contador</title>
  <variablelist>
    <varlistentry>
      <term
>desde<indexterm
><primary
>desde</primary
></indexterm
><indexterm
><primary
>pasando</primary
></indexterm
></term>
      <listitem
><para
><screen
>for <link linkend="assignment-of-variables">variable</link> = <link linkend="number">number</link> to <link linkend="number">number</link> { ... }</screen>
The <userinput
>for</userinput
> loop is a <quote
>counting loop</quote
>, &ie; it keeps count for you. The first number sets the variable to the value in the first loop. Every loop the number is increased until the second number is reached. <screen
>
for $x = 1 to 10 {
  print $x * 7
  forward 15
}
</screen
> Every time the code between the brackets is executed the <userinput
>$x</userinput
> is increased by 1, until <userinput
>$x</userinput
> reaches the value of 10. The code between the brackets prints the <userinput
>$x</userinput
> multiplied by 7. After this program finishes its execution you will see the times table of 7 on the canvas. </para>
     <para
>O paso por omisión no bucle é 1, pero pode utilizar outro valor mediante <screen
>for <link linkend="assignment-of-variables">variable</link> = <link linkend="number">number</link> to <link linkend="number">number</link> step <link linkend="number">number</link> { ... }</screen
></para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="break">
<title
>Sair dun bucle</title>
  <variablelist>
    <varlistentry>
      <term
>sair<indexterm
><primary
>sair</primary
></indexterm
></term>
      <listitem
><para
><screen
>sair</screen>
Terminates the current loop immediately and transfers control to the statement immediately following that loop.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="exit">
<title
>Stop executing your program</title>
  <variablelist>
    <varlistentry>
      <term
>fin<indexterm
><primary
>fin</primary
></indexterm
></term>
      <listitem
><para
><screen
>fin</screen>
Finishes the execution of your program.</para
></listitem>
    </varlistentry>
  </variablelist>
</sect2>
</sect1>


<sect1 id="learn">


<!--<sect2 id="name">
<title
>Names</title>
<para
>When using the &turtlescript; programming language you create new things. If you write a program you will often need <link linkend="containers"
>containers</link
> and in some cases you need <link linkend="learn"
>learn</link
> to create new commands. When making a new command with <link linkend="learn"
>learn</link
> you will have to specify a name.</para>
<para
>You can choose any name, as long as it does not already have a meaning. For instance you cannot name a function <link linkend="forward"
>forward</link
>, since that name is already used for an internal command.
<screen
>
# here forward is used as a new command, 
# but it already has a meaning so 
# this will produce an error:
learn forward {
  print "this is invalid"
}

# this works:
learn myforward {
  print "this is ok"
}
</screen>
Names can contain only letters, numbers and underscores (_). Yet they have to start with a letter. Container names have to start with the container prefix ($).
<screen
>
# here forward is used as a container, 
# starting with the $ prefix, so it does
# not conflict with the forward command
$forward = 20
print $forward
</screen>
</para>
<para
>Containers are <glossterm
>highlighted</glossterm
> with bolded purple in the <link linkend="the-editor"
>code editor</link
>.</para>
<para>
Please read the documentation on <link linkend="containers"
>containers</link
> and the <link linkend="learn"
>learn</link
> command for a better explanation and more examples.
</para>
</sect2
>-->





<title
>Cree os seus proprios comandos con <quote
>define</quote
></title>
<para
><userinput
>learn</userinput
> is special as it is used to create your own commands. The commands you create can take <glossterm linkend="input-output"
>input</glossterm
> and return <glossterm linkend="input-output"
>output</glossterm
>. Let us take a look at how a new command is created: <screen
>
learn circle $x {
  repeat 36 {
    forward $x
    turnleft 10
  }
}
</screen
> The new command is called <userinput
>circle</userinput
>. <userinput
>circle</userinput
> takes one <glossterm linkend="input-output"
>input</glossterm
> argument, to set the size of the circle. <userinput
>circle</userinput
> returns no <glossterm linkend="input-output"
>output</glossterm
>. The <userinput
>circle</userinput
> command can now be used like a normal command in the rest of the code. See this example: <screen
>define faiCirculo $X {
  repite 36 {
    avanza $X
    xiraesquerda 10
  }
}
vai 200,200
faiCirculo 20

vai 300,300
faiCirculo 40  
</screen>
</para>
<para
>In the next example, a command with a return value is created. <screen
>
learn faculty $x {
  $r = 1
  for $i = 1 to $x {
    $r = $r * $i
  }
  return $r
}

print faculty 5
</screen
> In this example a new command called <userinput
>faculty</userinput
> is created. If the input of this command is <userinput
>5</userinput
> then the output is <userinput
>5*4*3*2*1</userinput
>. By using <userinput
>return</userinput
> the <glossterm linkend="input-output"
>output</glossterm
> value is specified and the execution is returned.</para>
<para
>Commands can have more than one <glossterm linkend="input-output"
>input</glossterm
>. In the next example, a command that draws a rectangle is created: <screen
>
learn box $x, $y {
  forward $y
  turnright 90
  forward $x
  turnright 90
  forward $y
  turnright 90
  forward $x
  turnright 90
}
</screen
> Now you can run <userinput
>box 50, 100</userinput
> and the turtle will draw a rectangle on the canvas. </para>
  
</sect1>

</chapter>
