<chapter>
  <title>Labels and aliases</title>
  <para>
    Labels are an important part of your code.  However, since each
    label must normally be unique, this can lead to <quote>namespace
    pollution,</quote> and you'll find yourself going through ever
    more contorted constructions to generate unique label names.
    Ophis offers two solutions to this: <emphasis>anonymous
    labels</emphasis> and <emphasis>temporary labels</emphasis>.  This
    tutorial will cover both of these facilities, and also introduce
    the aliasing mechanism.
  </para>

  <section>
    <title>Temporary labels</title>

    <para>
      Temporary labels are the easiest to use.  If a label begins with
      an underscore, it will only be reachable from inside the
      innermost enclosing scope.  Scopes begin when
      a <literal>.scope</literal> statement is encountered.  This
      produces a new, inner scope if there is another scope in use.
      The <literal>.scend</literal> command ends the innermost
      currently active scope.
    </para>

    <para>
      We can thus rewrite our header data using temporary labels, thus
      allowing the main program to have a label
      named <literal>next</literal> if it wants.
    </para>

<programlisting>
.word $0801
.org  $0801

.scope
        .word _next, 10      ; Next line and current line number
        .byte $9e," 2064",0  ; SYS 2064
_next:  .word 0              ; End of program
.scend

.advance 2064
</programlisting>

    <para>
      It's possible to have multiple temporary labels with the same
      name in different parts of the code. If you create a label map
      in those cases, you will have to look at the sourcefile location
      to distinguish them.
    </para>

  </section>
  <section>
    <title>Anonymous labels</title>
      <para>
        Anonymous labels are a way to handle short-ranged branches
        without having to come up with names for the then and else
        branches, for brief loops, and other such purposes.  To define
        an anonymous label, use an asterisk.  To refer to an anonymous
        label, use a series of <literal>+</literal>
        or <literal>-</literal> signs.  <literal>+</literal> refers to
        the next anonymous label, <literal>++</literal> the label
        after that, etc.  Likewise, <literal>-</literal> is the most
        recently defined label, <literal>--</literal> the one before
        that, and so on.  The main body of the Hello World program
        with anonymous labels would be:
      </para>

<programlisting>
        ldx #0
*       lda hello, x
        beq +
        jsr $ffd2
        inx
        bne -
*       rts
</programlisting>

    <para>
      It is worth noting that anonymous labels are globally available.
      They are not temporary labels, and they ignore scoping
      restrictions.
    </para>
  </section>
  <section>
    <title>Aliasing</title>

      <para>
        Rather the reverse of anonymous labels, aliases are names
        given to specific memory locations.  These make it easier to
        keep track of important constants or locations.  The KERNAL
        routines are a good example of constants that deserve names.
        To assign the traditional name <literal>chrout</literal> to
        the routine at $FFD2, simply give the directive:
      </para>

<programlisting>
.alias chrout $ffd2
</programlisting>

      <para>And change the <userinput>jsr</userinput> command
      to:</para>

<programlisting>
        jsr chrout
</programlisting>

    <para>
      The final version of the code is in <xref linkend="tutor2-src" endterm="tutor2-fname">.  It should
      assemble to exactly the same program as <xref linkend="tutor1-src" endterm="tutor1-fname">.
    </para>
  </section>
</chapter>
