Ophis/doc/tutor2.sgm
2014-05-24 05:48:26 -07:00

115 lines
3.7 KiB
Plaintext

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