File: README.html

package info (click to toggle)
64tass 1.60.3243-1
links: PTS
area: main
in suites: forky, sid
size: 3,432 kB
sloc: ansic: 48,995; xml: 647; asm: 333; makefile: 250
file content (6923 lines) | stat: -rw-r--r-- 323,748 bytes
<!DOCTYPE HTML>
<html lang="en">
<!-- $Id: README.html 3243 2025-05-10 05:17:11Z soci $ -->
<head>
<title>64tass v1.60 r3243 reference manual</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Description" content="64tass, an advanced multi pass macro assembler for the 65xx family of microprocessors">
<meta name="Keywords" content="6502 assembler, 65816, 6510, 65C02, dtv, c64 cross assembler">
<meta name="Author" content="Kajtar Zsolt">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
dt {margin-top:0.5em}
dt + dt {margin-top:0em}
body {font-family:serif;}
p, dd, h1, h2, h3, h4, li, caption {hyphens:auto;-moz-hyphens:auto;-webkit-hyphens:auto;-ms-hyphens:auto;}
code {hyphens:manual;-moz-hyphens:manual;-webkit-hyphens:manual;-ms-hyphens:manual;}
h1, h2, h3, h4 {text-align:left;font-family:sans-serif}
hr {display:none}
pre {border:1px dotted #eee;background-color:#ffe;padding:2px; border-radius: 4px;}
pre.make b {color:inherit;}
pre.make span {color:navy;}
pre.make span.cmd {color:green;}
pre.diag span.error {color:red;}
pre.diag span.note {color:darkcyan;}
pre.diag span.caret {color:green;}
pre b, code b {color:navy;}
pre b.d, code b.d {color:#e60;}
pre b.k, pre span.k, code b.k, code span.k {color:#00d;}
pre span, code span {color:#d00;}
pre span.s, code span.s {color:#e60;}
pre i {color:brown;}
pre u, code u {text-decoration:none;color:green;}
p, dd {text-align:justify;}
p + p {text-indent:3ex;margin-top:-0.5em}
table {border-bottom:2px solid black;border-top:2px solid black;border-collapse:collapse;width:100%;margin-top:0.5em;margin-bottom:0.5em; border-spacing: 0px;}
td, th {padding: 0px 1ex 0px 1ex;border-left:1px solid silver;border-top:1px solid silver}
tr:nth-child(odd) {background: #fafaff;}
td:first-child, th:first-child {border-left: 0px;}
caption {caption-side:bottom;}
table.opcodes th, table.opcodes td {text-align:left;table-layout:fixed;}
table.trans td:nth-child(1), table.trans td:nth-child(4) {text-align:center;}
dl.errorlist > dt, dl.dir > dt, table.trans td, table.esc td, table.opcodes th, table.opcodes td, code, pre, table.trans2 td {font-family:monospace,monospace;}
dl.errorlist > dt {font-weight:bold;}

thead th {background-color:#eee;border-bottom:1px solid black;}
a[href], a:visited { text-decoration: none; color: blue; }
a[href]:hover { text-decoration: underline; }

@media screen {
   html {background-color: gray;}
   body > div {max-width:50em;margin-left:auto; margin-right:auto; overflow: hidden;}
   body {font-size:12pt;max-width:60em; background-color:white; margin-left:auto; margin-right:auto; border:1px solid black; box-shadow: black 2px 2px; padding: 5em 0.5em;}
   pre, div {overflow:auto;}
}
.links {line-height: 2em; word-spacing: 1ex; text-align: justify;}

@media print {
   h1, h2, h3, h4 {page-break-after:avoid;}
   a[href], a:visited {text-decoration:none;color:inherit;}
   body {font-size:10pt;}
   pre {overflow:hidden;}
}

#toc li { list-style: none; }
#toc ul { counter-reset: section; }
#toc li > a:before { content: counters(section, ".") " "; counter-increment: section; color:black; }
#toc ul { margin: 0px; font-weight: normal;}
#toc > ul > li { margin-top: 0.5em; font-weight: bold; }

body { counter-reset: countcaption;}
h1 { counter-reset: counth2; font-size: 2em; margin: 0 0 0.67em 0; }

h2:before { content: counter(counth2) " "; counter-increment: counth2; min-width: 40pt;display:inline-block;margin-right:5pt;}
h2 { counter-reset: counth3; }
h3:before { content: counter(counth2) "." counter(counth3) " "; counter-increment: counth3; min-width: 40pt;display:inline-block;margin-right:5pt;}
h3 { counter-reset: counth4; }
h4:before { content: counter(counth2) "." counter(counth3) "." counter(counth4) " "; counter-increment: counth4; min-width: 40pt;display:inline-block;margin-right:5pt;}
caption:before { content: "Table " counter(countcaption) ": "; counter-increment: countcaption; font-weight:bold;}
h2 a:after, h3 a:after, h4 a:after, dt a[name][href]:after {content: "¶"}
h2 a, h3 a, h4 a, dt a[name][href] {color:blue;visibility:hidden;text-decoration:none;}
h2:hover a, h3:hover a, h4:hover a, dt:hover a[name][href] {visibility:visible;}

q { quotes: "\201C" "\201D" "\2018" "\2019"; }
</style>
</head>
<body>
<div>
<h1>64tass v1.60 r3243 reference manual</h1>

<p>This is the manual for 64tass, the multi pass optimizing macro assembler for
the 65xx series of processors. Key features:

<ul>
<li>Open source portable C with minimal dependencies</li>
<li>Familiar syntax to Omicron TASS and TASM</li>
<li>Supports 6502, 65C02, R65C02, W65C02, 65CE02, 65816, DTV, 65EL02, 4510, 45GS02</li>
<li>Arbitrary-precision integers and bit strings, double precision floating point numbers</li>
<li>Character and byte strings, array arithmetic</li>
<li>Handles UTF-8, UTF-16 and 8&nbsp;bit RAW encoded source files, Unicode character strings</li>
<li>Supports Unicode identifiers with compatibility normalization and optional case insensitivity</li>
<li>Built-in <q>linker</q> with section support</li>
<li>Various memory models, binary targets and text output formats (also Hex/S-record)</li>
<li>Assembly and label listings available for debugging or exporting</li>
<li>Conditional compilation, macros, structures, unions, scopes</li>
</ul>

<p>Contrary how the length of this document suggests 64tass can be used with
just basic 6502 assembly knowledge in simple ways like any other assembler. If
some advanced functionality is needed then this document can serve as a
reference.

<p><b>This is a development version. Features or syntax may change as a result
of corrections in non-backwards compatible ways in some rare cases. It's
difficult to get everything <q>right</q> first time.</b>

<p>Project page: <a href="https://sourceforge.net/projects/tass64/">https://sourceforge.net/projects/tass64/</a>

<p>The page hosts the latest and older versions with sources and a bug and a feature request tracker.</p>

<hr>
<nav id="toc">
<h2>Table of Contents<a name="contents" href="#contents"></a></h2>

<ul>
 <li><a href="#contents">Table of Contents</a></li>
 <li><a href="#usage-tips">Usage tips</a></li>
 <li><a href="#expressions-datatypes">Expressions and data types</a>
 <ul>
  <li><a href="#integers">Integer constants</a></li>
  <li><a href="#bit-string">Bit string constants</a></li>
  <li><a href="#floating-point">Floating point constants</a></li>
  <li><a href="#character-string">Character string constants</a></li>
  <li><a href="#byte-string">Byte string constants</a></li>
  <li><a href="#list-tuples">Lists and tuples</a></li>
  <li><a href="#dictionaries">Dictionaries</a></li>
  <li><a href="#code">Code</a></li>
  <li><a href="#addressing">Addressing modes</a></li>
  <li><a href="#uninitialized">Uninitialized memory</a></li>
  <li><a href="#booleans">Booleans</a></li>
  <li><a href="#type">Types</a></li>
  <li><a href="#symbols">Symbols</a>
  <ul>
   <li><a href="#symbols-regular">Regular symbols</a></li>
   <li><a href="#symbols-local">Local symbols</a></li>
   <li><a href="#symbols-anonymous">Anonymous symbols</a></li>
   <li><a href="#symbols-constant">Constant and re-definable symbols</a></li>
   <li><a href="#star">The star label</a></li>
  </ul></li>
  <li><a href="#builtin-functions">Built-in functions</a>
  <ul>
   <li><a href="#math-functions">Mathematical functions</a></li>
   <li><a href="#byte-functions">Byte string functions</a></li>
   <li><a href="#other-functions">Other functions</a></li>
  </ul></li>
  <li><a href="#expressions">Expressions</a>
  <ul>
   <li><a href="#operators">Operators</a></li>
   <li><a href="#comparison">Comparison operators</a></li>
   <li><a href="#bitstringextractor">Bit string extraction operators</a></li>
   <li><a href="#conditionals">Conditional operators</a></li>
   <li><a href="#addresslength">Address length forcing</a></li>
   <li><a href="#compound">Compound assignment</a></li>
   <li><a href="#slicing_indexing">Slicing and indexing</a></li>
  </ul></li>
 </ul></li>
 <li><a href="#compiler-directives">Compiler directives</a>
 <ul>
  <li><a href="#program-counter">Controlling the compile offset and program counter</a></li>
  <li><a href="#alignment">Aligning data or code</a></li>
  <li><a href="#data-dumping">Dumping data</a>
  <ul>
   <li><a href="#data-numeric">Storing numeric values</a></li>
   <li><a href="#data-text">Storing string values</a></li>
  </ul></li>
  <li><a href="#text-encoding">Text encoding</a></li>
  <li><a href="#structures">Structured data</a>
  <ul>
   <li><a href="#structure">Structure</a></li>
   <li><a href="#union">Union</a></li>
   <li><a href="#struct-and-union">Combined use of structures and unions</a></li>
  </ul></li>
  <li><a href="#macros">Macros</a>
  <ul>
   <li><a href="#macro-parameters">Parameter references</a></li>
   <li><a href="#macro-textreference">Text references</a></li>
  </ul></li>
  <li><a href="#user-functions">Custom functions</a></li>
  <li><a href="#conditional-assembly">Conditional assembly</a>
  <ul>
   <li><a href="#conditional-if">If, else if, else</a></li>
   <li><a href="#conditional-switch">Switch, case, default</a></li>
   <li><a href="#conditional-comment">Comment</a></li>
  </ul></li>
  <li><a href="#repetitions">Repetitions</a></li>
  <li><a href="#including">Including files</a></li>
  <li><a href="#scopes">Scopes</a></li>
  <li><a href="#sections">Sections</a></li>
  <li><a href="#w65816">65816 related</a></li>
  <li><a href="#compiletime-checks">Controlling errors</a></li>
  <li><a href="#target-cpu">Target</a></li>
  <li><a href="#misc">Misc</a></li>
  <li><a href="#listing-control">Printer control</a></li>
 </ul></li>
 <li><a href="#pseudo-instructions">Pseudo instructions</a>
 <ul>
  <li><a href="#aliases">Aliases</a></li>
  <li><a href="#generic-instructions">Generic instructions</a></li>
  <li><a href="#branch-always">Always taken branches</a></li>
  <li><a href="#branch-long">Long branches</a></li>
 </ul></li>
 <li><a href="#tasm-compatibility">Original turbo assembler compatibility</a>
 <ul>
  <li><a href="#tasm-convert">How to convert source code for use with 64tass</a></li>
  <li><a href="#tasm-diff">Differences to the original turbo ass macro on the C64</a></li>
  <li><a href="#tasm-labels">Labels</a></li>
  <li><a href="#tasm-expression">Expression evaluation</a></li>
  <li><a href="#tasm-macros">Macros</a></li>
  <li><a href="#tasm-bugs">Bugs</a></li>
 </ul></li>
 <li><a href="#commandline-options">Command line options</a>
 <ul>
  <li><a href="#commandline-output">Output options</a></li>
  <li><a href="#commandline-operation">Operation options</a></li>
  <li><a href="#commandline-diagnostic">Diagnostic options</a></li>
  <li><a href="#commandline-target">Target selection on command line</a></li>
  <li><a href="#commandline-symbol">Symbol listing</a></li>
  <li><a href="#commandline-assembly">Assembly listing</a></li>
  <li><a href="#commandline-other">Other options</a></li>
  <li><a href="#commandline-file">Command line from file</a></li>
 </ul></li>
 <li><a href="#messages">Messages</a>
 <ul>
  <li><a href="#messages-warnings">Warnings</a></li>
  <li><a href="#messages-errors">Errors</a></li>
  <li><a href="#messages-fatal">Fatal errors</a></li>
 </ul></li>
 <li><a href="#credits">Credits</a></li>
 <li><a href="#builtin-translations-escapes">Default translation and escape sequences</a>
 <ul>
  <li><a href="#translate-raw8">Raw 8-bit source</a>
  <ul>
   <li><a href="#translate-raw8-none">The none encoding for raw 8-bit</a></li>
   <li><a href="#translate-raw8-screen">The screen encoding for raw 8-bit</a></li>
  </ul></li>
  <li><a href="#translate-unicode">Unicode and ASCII source</a>
  <ul>
   <li><a href="#translate-unicode-none">The none encoding for Unicode</a></li>
   <li><a href="#translate-unicode-screen">The screen encoding for Unicode</a></li>
  </ul></li>
 </ul></li>
 <li><a href="#opcodes">Opcodes</a>
 <ul>
  <li><a href="#opcodes-6502">Standard 6502 opcodes</a></li>
  <li><a href="#opcodes-6502i">6502 illegal opcodes</a></li>
  <li><a href="#opcodes-65dtv02">65DTV02 opcodes</a></li>
  <li><a href="#opcodes-65c02">Standard 65C02 opcodes</a></li>
  <li><a href="#opcodes-r65c02">R65C02 opcodes</a></li>
  <li><a href="#opcodes-w65c02">W65C02 opcodes</a></li>
  <li><a href="#opcodes-w65816">W65816 opcodes</a></li>
  <li><a href="#opcodes-65el02">65EL02 opcodes</a></li>
  <li><a href="#opcodes-65ce02">65CE02 opcodes</a></li>
  <li><a href="#opcodes-4510">CSG 4510 opcodes</a></li>
  <li><a href="#opcodes-45gs02">45GS02 opcodes</a></li>
 </ul></li>
 <li><a href="#appendix">Appendix</a>
 <ul>
  <li><a href="#directives">Assembler directives</a></li>
  <li><a href="#functions">Built-in functions</a></li>
  <li><a href="#types">Built-in types</a></li>
 </ul></li>
</ul>
</nav>

<hr>
<h2>Usage tips<a name="usage-tips" href="#usage-tips"></a></h2>
<p>64tass is a command line assembler, the source can be written in any text
editor. As a minimum the source filename must be given on the command line. The
<q><a href="#o_ascii"><code>-a</code></a></q> command line option is highly recommended if the source is Unicode or
ASCII.

<pre>
64tass -a src.asm
</pre>

<p>There are also some useful parameters which are described later.

<p>For comfortable compiling I use such <q>Makefile</q>s (for <a href="https://en.wikipedia.org/wiki/Make_%28software%29">make</a>):

<pre class="make">
<span>demo.prg:</span> source.asm macros.asm pic.drp music.bin
        <span class="cmd">64tass -C -a -B -i source.asm -o demo.tmp</span>
        <span class="cmd">pucrunch -ffast -x 2048 demo.tmp &gt;demo.prg</span>
</pre>

<p>This way <q>demo.prg</q> is recreated by compiling <q>source.asm</q>
whenever <q>source.asm</q>, <q>macros.asm</q>, <q>pic.drp</q> or <q>music.bin</q> had changed.

<p>Of course it's not much harder to create something similar for win32 (make.bat),
however this will always compile and compress:

<pre>
64tass.exe -C -a -B -i source.asm -o demo.tmp
pucrunch.exe -ffast -x 2048 demo.tmp &gt;demo.prg
</pre>

<p>Here's a slightly more advanced Makefile example with default action as
testing in VICE, clean target for removal of temporary files and compressing
using an intermediate temporary file:

<pre class="make">
<span>all:</span> demo.prg
        <span class="cmd">x64 -autostartprgmode 1 -autostart-warp +truedrive +cart</span> $&lt;

<span>demo.prg:</span> demo.tmp
        <span class="cmd">pucrunch -ffast -x 2048</span> $&lt; &gt;$@

<span>demo.tmp:</span> source.asm macros.asm pic.drp music.bin
        <span class="cmd">64tass -C -a -B -i</span> $&lt; <span class="cmd">-o</span> $@

<b>.INTERMEDIATE:</b> demo.tmp
<b>.PHONY:</b> all clean
<span>clean:</span>
        $(RM) <span class="cmd">demo.prg demo.tmp</span>
</pre>

<p>It's useful to add a basic header to your source files like the one below,
so that the resulting file is directly runnable without additional
compression:

<pre>
*       <b>=</b> <span>$0801</span>
        <b class="d">.word</b> (<u>+</u>), <span>2005</span>  <i>;pointer, line number</i>
        <b class="d">.null</b> <span>$9e</span>, <span class="k">format</span>(<span class="s">"%4d"</span>, <u>start</u>)<i>;will be sys 4096</i>
+       <b class="d">.word</b> <span>0</span>          <i>;basic line end</i>

*       <b>=</b> <span>$1000</span>

start   <b>rts</b>
</pre>

<p>A frequently coming up question is, how to automatically allocate
memory, without hacks like <code>*=*+1</code>? Sure
there's <a href="#d_byte"><code>.byte</code></a> and friends for variables with initial values
but what about zero page, or RAM outside of program area? The solution
is to not use an initial value by using <q><a href="#uninitialized"><code>?</code></a></q> or not
giving a fill byte value to <a href="#d_fill"><code>.fill</code></a>.

<pre>
*       <b>=</b> <span>$02</span>
p1      <b class="d">.addr</b> <span>?</span>         <i>;a zero page pointer</i>
temp    <b class="d">.fill</b> <span>10</span>        <i>;a 10 byte temporary area</i>
</pre>

<p>Space allocated this way
is not saved in the output as there's no data to save at those
addresses.

<p>What about some code running on zero page for speed? It needs to be
relocated, and the length must be known to copy it there. Here's
an example:

<pre>
        <b>ldx</b> #<span class="k">size</span>(<u>zpcode</u>)-<span>1</span><i>;calculate length</i>
-       <b>lda</b> <u>zpcode</u>,x
        <b>sta</b> <u>wrbyte</u>,x
        <b>dex</b>             <i>;install to zero page</i>
        <b>bpl</b> <u>-</u>
        <b>jsr</b> <u>wrbyte</u>
        <b>rts</b>
<i>;code continues here but is compiled to run from $02</i>
zpcode  <b class="k">.logical</b> <span>$02</span>
wrbyte  <b>sta</b> <span>$ffff</span>       <i>;quick byte writer at $02</i>
        <b>inc</b> <u>wrbyte</u>+<span>1</span>
        <b>bne</b> <u>+</u>
        <b>inc</b> <u>wrbyte</u>+<span>2</span>
+       <b>rts</b>
        <b class="k">.endlogical</b>
</pre>

<p>The assembler supports lists and tuples, which does not seems interesting at
first as it sound like something which is only useful when heavy scripting is
involved. But as normal arithmetic operations also apply on all their elements at
once, this could spare quite some typing and repetition.

<p>Let's take a simple example of a low/high byte jump table of return
addresses, this usually involves some unnecessary copy/pasting to create a pair
of tables with constructs like <code>&gt;(label-1)</code>.

<pre>
jumpcmd <b>lda</b> <u>hibytes</u>,x   <i>; selected routine in X register</i>
        <b>pha</b>
        <b>lda</b> <u>lobytes</u>,x   <i>; push address to stack</i>
        <b>pha</b>
        <b>rts</b>             <i>; jump, rts will increase pc by one!</i>
<i>; Build a list of jump addresses minus 1</i>
_       <b>:=</b> (<u>cmd_p</u>, <u>cmd_c</u>, <u>cmd_m</u>, <u>cmd_s</u>, <u>cmd_r</u>, <u>cmd_l</u>, <u>cmd_e</u>)-<span>1</span>
lobytes <b class="d">.byte</b> &lt;<u>_</u>        <i>; low bytes of jump addresses</i>
hibytes <b class="d">.byte</b> &gt;<u>_</u>        <i>; high bytes</i>
</pre>

<p>There are some other tips below in the descriptions.</p>

<hr>
<h2>Expressions and data types<a name="expressions-datatypes" href="#expressions-datatypes"></a></h2>

<h3>Integer constants<a name="integers" href="#integers"></a></h3>

<p>Integer constants can be entered as decimal digits of arbitrary
length. An underscore can be used between digits as a separator for
better readability of long numbers. The following operations are
accepted:

<div><table border="0">
<caption>Integer operators and functions</caption>
<tr><td width="60"><code><u>x</u> + <u>y</u></code><td>add <code><u>x</u></code> to <code><u>y</u></code><td><code><span>2</span> + <span>2</span></code> is <code><span>4</span></code>
<tr><td><code><u>x</u> - <u>y</u></code><td>subtract <code><u>y</u></code> from <code><u>x</u></code><td><code><span>4</span> - <span>1</span></code> is <code><span>3</span></code>
<tr><td><code><u>x</u> * <u>y</u></code><td>multiply <code><u>x</u></code> with <code><u>y</u></code><td><code><span>2</span> * <span>3</span></code> is <code><span>6</span></code>
<tr><td><code><u>x</u> / <u>y</u></code><td>integer divide <code><u>x</u></code> by <code><u>y</u></code><td><code><span>7</span> / <span>2</span></code> is <code><span>3</span></code>
<tr><td><code><u>x</u> % <u>y</u></code><td>integer modulo of <code><u>x</u></code> divided by <code><u>y</u></code><td><code><span>5</span> % <span>2</span></code> is <code><span>1</span></code>
<tr><td><code><u>x</u> ** <u>y</u></code><td><code><u>x</u></code> raised to power of <code><u>y</u></code><td><code><span>2</span> ** <span>4</span></code> is <code><span>16</span></code>
<tr><td><code>-<u>x</u></code><td>negated value<td><code>-<span>2</span></code> is <code><span>-2</span></code>
<tr><td><code>+<u>x</u></code><td>unchanged<td><code>+<span>2</span></code> is <code><span>2</span></code>
<tr><td><code>~<u>x</u></code><td><code>-<u>x</u> - <span>1</span></code><td><code>~<span>3</span></code> is <code><span>-4</span></code>
<tr><td><code><u>x</u> | <u>y</u></code><td>bitwise or<td><code><span>2</span> | <span>6</span></code> is <code><span>6</span></code>
<tr><td><code><u>x</u> ^ <u>y</u></code><td>bitwise xor<td><code><span>2</span> ^ <span>6</span></code> is <code><span>4</span></code>
<tr><td><code><u>x</u> &amp; <u>y</u></code><td>bitwise and<td><code><span>2</span> &amp; <span>6</span></code> is <code><span>2</span></code>
<tr><td><code><u>x</u> &lt;&lt; <u>y</u></code><td>logical shift left<td><code><span>1</span> &lt;&lt; <span>3</span></code> is <code><span>8</span></code>
<tr><td><code><u>x</u> &gt;&gt; <u>y</u></code><td>arithmetic shift right<td><code><span>-8</span> &gt;&gt; <span>3</span></code> is <code><span>-1</span></code>
</table></div>

<p>Integers are automatically promoted to floats as necessary in expressions.
Other types can be converted to integer using the integer type
<code>int</code>.

<p>Integer division is a floor division (rounding down) so <code>7 / 4</code>
is <code>1</code> and not <code>1.75</code>. If ceiling division is required (rounding up) that
can be done by negating both the divident and the result. Typically it's done like <code>0 - -5 / 4</code> which results in <code>2</code>.

<pre>
        <b class="d">.byte</b> <span>23</span>        <i>; as unsigned</i>
        <b class="d">.char</b> <span>-23</span>       <i>; as signed</i>

<i>; using negative integers as immediate values</i>
        <b>ldx</b> #-<span>3</span>         <i>; works as '#-' is signed immediate</i>
num     <b>=</b> <span>-3</span>
        <b>ldx</b> #+<u>num</u>       <i>; needs explicit '#+' for signed 8 bits</i>

        <b>lda</b> #((<u>bitmap</u> &gt;&gt; <span>10</span>) &amp; <span>$0f</span>) | ((<u>screen</u> &gt;&gt; <span>6</span>) &amp; <span>$f0</span>)
        <b>sta</b> <span>$d018</span>
</pre>

<h3>Bit string constants<a name="bit-string" href="#bit-string"></a></h3>

<p>Bit string constants can be entered in hexadecimal form with a leading
dollar sign or in binary with a leading percent sign. An underscore can
be used between digits as a separator for better readability of long
numbers. The following operations are accepted:

<div><table border="0">
<caption>Bit string operators and functions</caption>
<tr><td><code>~<u>x</u></code><td>invert bits<td><code>~<span>%101</span></code> is <code><span>~%101</span></code>
<tr><td><code><u>y</u> .. <u>x</u></code><td>concatenate bits<td><code><span>$a</span> .. <span>$b</span></code> is <code><span>$ab</span></code>
<tr><td><code><u>y</u> <span class="k">x</span> <u>n</u></code><td>repeat<td><code><span>%101</span> <span class="k">x</span> <span>3</span></code> is <code><span>%101101101</span></code>
<tr><td><code><u>x</u>[<u>n</u>]</code><td>extract bit(s)<td><code><span>$a</span>[<span>1</span>]</code> is <code><span>%1</span></code>
<tr><td><code><u>x</u>[<u>s</u>]</code><td>slice bits<td><code><span>$1234</span>[<span>4</span>:<span>8</span>]</code> is <code><span>$3</span></code>
<tr><td><code><u>x</u> | <u>y</u></code><td>bitwise or<td><code><span>~$2</span> | <span>$6</span></code> is <code><span>~$0</span></code>
<tr><td><code><u>x</u> ^ <u>y</u></code><td>bitwise xor<td><code><span>~$2</span> ^ <span>$6</span></code> is <code><span>~$4</span></code>
<tr><td><code><u>x</u> &amp; <u>y</u></code><td>bitwise and<td><code><span>~$2</span> &amp; <span>$6</span></code> is <code><span>$4</span></code>
<tr><td><code><u>x</u> &lt;&lt; <u>y</u></code><td>bitwise shift left<td><code><span>$0f</span> &lt;&lt; <span>4</span></code> is <code><span>$0f0</span></code>
<tr><td><code><u>x</u> &gt;&gt; <u>y</u></code><td>bitwise shift right<td><code><span>~$f4</span> &gt;&gt; <span>4</span></code> is <code><span>~$f</span></code>
</table></div>

<p>Length of bit string constants are defined in bits and is calculated from
the number of bit digits used including leading zeros.

<p>Bit strings are automatically promoted to integer or floating point as necessary in
expressions. The higher bits are extended with zeros or ones as needed.

<p>Bit strings support indexing and slicing. This is explained in detail
in section <q><a href="#slicing_indexing">Slicing and indexing</a></q>.

<p>Other types can be converted to bit string using the bit string type <code>bits</code>.

<pre>
        <b class="d">.byte</b> <span>$33</span>       <i>; 8 bits in hexadecimal</i>
        <b class="d">.byte</b> <span>%00011111</span> <i>; 8 bits in binary</i>
        <b class="d">.text</b> <span>$1234</span>     <i>; $34, $12 (little endian)</i>

        <b>lda</b> <span>$01</span>
        <b>and</b> #~<span>$07</span>       <i>; 8 bits even after inversion</i>
        <b>ora</b> #<span>$05</span>
        <b>sta</b> <span>$01</span>

        <b>lda</b> <span>$d015</span>
        <b>and</b> #~<span>%00100000</span> <i>;clear a bit</i>
        <b>sta</b> <span>$d015</span>
</pre>

<h3>Floating point constants<a name="floating-point" href="#floating-point"></a></h3>

<p>Floating point constants have a radix point in them and optionally an
exponent. A decimal exponent is <q><code>e</code></q> while a binary one is <q><code>p</code></q>.
An underscore can be used between digits as a separator for better
readability. The following operations can be used:

<div><table border="0">
<caption>Floating point operators and functions</caption>
<tr><td width="80"><code><u>x</u> + <u>y</u></code><td>add <code><u>x</u></code> to <code><u>y</u></code><td><code><span>2.2</span> + <span>2.2</span></code> is <code><span>4.4</span></code>
<tr><td><code><u>x</u> - <u>y</u></code><td>subtract <code><u>y</u></code> from <code><u>x</u></code><td><code><span>4.1</span> - <span>1.1</span></code> is <code><span>3.0</span></code>
<tr><td><code><u>x</u> * <u>y</u></code><td>multiply <code><u>x</u></code> with <code><u>y</u></code><td><code><span>1.5</span> * <span>3</span></code> is <code><span>4.5</span></code>
<tr><td><code><u>x</u> / <u>y</u></code><td>integer divide <code><u>x</u></code> by <code><u>y</u></code><td><code><span>7.0</span> / <span>2.0</span></code> is <code><span>3.5</span></code>
<tr><td><code><u>x</u> % <u>y</u></code><td>integer modulo of <code><u>x</u></code> divided by <code><u>y</u></code><td><code><span>5.0</span> % <span>2.0</span></code> is <code><span>1.0</span></code>
<tr><td><code><u>x</u> ** <u>y</u></code><td><code><u>x</u></code> raised to power of <code><u>y</u></code><td><code><span>2.0</span> ** <span>-1</span></code> is <code><span>0.5</span></code>
<tr><td><code>-<u>x</u></code><td>negated value<td><code>-<span>2.0</span></code> is <code><span>-2.0</span></code>
<tr><td><code>+<u>x</u></code><td>unchanged<td><code>+<span>2.0</span></code> is <code><span>2.0</span></code>
<tr><td><code>~<u>x</u></code><td>almost <code>-<u>x</u></code><td><code>~<span>2.1</span></code> is almost <code><span>-2.1</span></code>
<tr><td><code><u>x</u> | <u>y</u></code><td>bitwise or<td><code><span>2.5</span> | <span>6.5</span></code> is <code><span>6.5</span></code>
<tr><td><code><u>x</u> ^ <u>y</u></code><td>bitwise xor<td><code><span>2.5</span> ^ <span>6.5</span></code> is <code><span>4.0</span></code>
<tr><td><code><u>x</u> &amp; <u>y</u></code><td>bitwise and<td><code><span>2.5</span> &amp; <span>6.5</span></code> is <code><span>2.5</span></code>
<tr><td><code><u>x</u> &lt;&lt; <u>y</u></code><td>logical shift left<td><code><span>1.0</span> &lt;&lt; <span>3.0</span></code> is <code><span>8.0</span></code>
<tr><td><code><u>x</u> &gt;&gt; <u>y</u></code><td>arithmetic shift right<td><code><span>-8.0</span> &gt;&gt; <span>4</span></code> is <code><span>-0.5</span></code>
</table></div>

<p>As usual comparing floating point numbers for (non) equality is a bad idea due to rounding errors.

<p>The only predefined constant is <code>pi</code>.

<p>Floating point numbers are automatically truncated to integer as necessary.
Other types can be converted to floating point by using the type <code>float</code>.

<p>Fixed point conversion can be done by using the shift operators. For example
an 8.16 fixed point number can be calculated as <code>(3.14 &lt;&lt; 16) &amp; $ffffff</code>.
The binary operators operate like if the floating point number would be a fixed
point one. This is the reason for the strange definition of inversion.

<pre>
        <b class="d">.byte</b> <span>3.66e1</span>       <i>; 36.6, truncated to 36</i>
        <b class="d">.byte</b> <span>$1.8p4</span>       <i>; 4:4 fixed point number (1.5)</i>
        <b class="d">.sint</b> <span>12.2p8</span>       <i>; 8:8 fixed point number (12.2)</i>
</pre>

<h3>Character string constants<a name="character-string" href="#character-string"></a></h3>

<p>Character strings are enclosed in single or double quotes and can hold any Unicode
character.

<p>Operations like indexing or slicing are always done on the original
representation. The current encoding is only applied when it's used in
expressions as numeric constants or in context of text data directives.

<p>Doubling the quotes inside string literals escapes them and results in a single quote.

<div><table border="0">
<caption>Character string operators and functions</caption>
<tr><td><code><u>y</u> .. <u>x</u></code><td>concatenate strings<td><code><span class="s">"a"</span> .. <span class="s">"b"</span></code> is <code><span class="s">"ab"</span></code>
<tr><td><code><u>y</u> <span class="k">in</span> <u>x</u></code><td>is substring of<td><code><span class="s">"b"</span> <span class="k">in</span> <span class="s">"abc"</span></code> is <code><span>true</span></code>
<tr><td><code><u>a</u> <span class="k">x</span> <u>n</u></code><td>repeat<td><code><span class="s">"ab"</span> <span class="k">x</span> <span>3</span></code> is <code><span class="s">"ababab"</span></code>
<tr><td><code><u>a</u>[<u>i</u>]</code><td>character from start<td><code><span class="s">"abc"</span>[<span>1</span>]</code> is <code><span class="s">"b"</span></code>
<tr><td><code><u>a</u>[-<u>i</u>]</code><td>character from end<td><code><span class="s">"abc"</span>[<span>-1</span>]</code> is <code><span class="s">"c"</span></code>
<tr><td><code><u>a</u>[:]</code><td>no change<td><code><span class="s">"abc"</span>[:]</code> is <code><span class="s">"abc"</span></code>
<tr><td><code><u>a</u>[<u>s</u>:]</code><td>cut off start<td><code><span class="s">"abc"</span>[<span>1</span>:]</code> is <code><span class="s">"bc"</span></code>
<tr><td><code><u>a</u>[:-<u>s</u>]</code><td>cut off end<td><code><span class="s">"abc"</span>[:<span>-1</span>]</code> is <code><span class="s">"ab"</span></code>
<tr><td><code><u>a</u>[<u>s</u>]</code><td>reverse<td><code><span class="s">"abc"</span>[::<span>-1</span>]</code> is <code><span class="s">"cba"</span></code>
</table></div>

<p>Character strings are converted to integers, byte and bit strings as necessary using the current
encoding and escape rules. For example when using a sane encoding <code>"z"-"a"</code> is
<code>25</code>.

<p>Other types can be converted to character strings by using the type
<code>str</code> or by using the <code>repr</code> and <code>format</code>
functions.

<p>Character strings support indexing and slicing. This is explained in detail
in section <q><a href="#slicing_indexing">Slicing and indexing</a></q>.

<pre>
mystr   <b>=</b> <span class="s">"oeU"</span>         <i>; character string constant</i>
        <b class="d">.text</b> <span class="s">'it''s'</span>   <i>; it's</i>
        <b class="d">.word</b> <span class="s">"ab"</span>+<span>1</span>    <i>; conversion result is "bb" usually</i>

        <b class="d">.text</b> <span class="s">"text"</span>[:<span>2</span>]     <i>; "te"</i>
        <b class="d">.text</b> <span class="s">"text"</span>[<span>2</span>:]     <i>; "xt"</i>
        <b class="d">.text</b> <span class="s">"text"</span>[:<span>-1</span>]    <i>; "tex"</i>
        <b class="d">.text</b> <span class="s">"reverse"</span>[::<span>-1</span>]<i>; "esrever"</i>
</pre>

<h3>Byte string constants<a name="byte-string" href="#byte-string"></a></h3>

<p>Byte strings are like character strings, but hold bytes instead of characters.

<p>Quoted character strings prefixing by <q><code>b</code></q>, <q><code>l</code></q>, <q><code>n</code></q>, <q><code>p</code></q>, <q><code>s</code></q>, <q><code>x</code></q>
or <q>z</q> characters can be used to create byte strings. The resulting byte
string contains what <a href="#d_text"><code>.text</code></a>, <a href="#d_shiftl"><code>.shiftl</code></a>,
<a href="#d_null"><code>.null</code></a>, <a href="#d_ptext"><code>.ptext</code></a> and <a href="#d_shift"><code>.shift</code></a> would
create. Direct hexadecimal entry can be done using the <q><code>x</code></q> prefix and
<q><code>z</code></q> denotes a z85 encoded byte string. Spaces can be used between pairs of
hexadecimal digits as a separator for better readability.

<div><table border="0">
<caption>Byte string operators and functions</caption>
<tr><td><code><u>y</u> .. <u>x</u></code><td>concatenate strings<td><code><span class="s">x"12"</span> .. <span class="s">x"34"</span></code> is <code><span class="s">x"1234"</span></code>
<tr><td><code><u>y</u> <span class="k">in</span> <u>x</u></code><td>is substring of<td><code><span class="s">x"34"</span> <span class="k">in</span> <span class="s">x"1234"</span></code> is <code><span>true</span></code>
<tr><td><code><u>a</u> <span class="k">x</span> <u>n</u></code><td>repeat<td><code><span class="s">x"ab"</span> <span class="k">x</span> <span>3</span></code> is <code><span class="s">x"ababab"</span></code>
<tr><td><code><u>a</u>[<u>i</u>]</code><td>byte from start<td><code><span class="s">x"abcd12"</span>[<span>1</span>]</code> is <code><span class="s">x"cd"</span></code>
<tr><td><code><u>a</u>[-<u>i</u>]</code><td>byte from end<td><code><span class="s">x"abcd"</span>[<span>-1</span>]</code> is <code><span class="s">x"cd"</span></code>
<tr><td><code><u>a</u>[:]</code><td>no change<td><code><span class="s">x"abcd"</span>[:]</code> is <code><span class="s">x"abcd"</span></code>
<tr><td><code><u>a</u>[<u>s</u>:]</code><td>cut off start<td><code><span class="s">x"abcdef"</span>[<span>1</span>:]</code> is <code><span class="s">x"cdef"</span></code>
<tr><td><code><u>a</u>[:-<u>s</u>]</code><td>cut off end<td><code><span class="s">x"abcdef"</span>[:<span>-1</span>]</code> is <code><span class="s">x"abcd"</span></code>
<tr><td><code><u>a</u>[<u>s</u>]</code><td>reverse<td><code><span class="s">x"abcdef"</span>[::<span>-1</span>]</code> is <code><span class="s">x"efcdab"</span></code>
</table></div>

<p>Byte strings support indexing and slicing. This is explained in detail
in section <q><a href="#slicing_indexing">Slicing and indexing</a></q>.

<p>Other types can be converted to byte strings by using the type <code>bytes</code>.

<pre>
        <b class="k">.enc</b> <span class="s">"screen"</span>   <i>;use screen encoding</i>
mystr   <b>=</b> <span class="s">b"oeU"</span>        <i>;convert text to bytes, like <a href="#d_text">.text</a></i>
        <b class="k">.enc</b> <span class="s">"none"</span>     <i>;normal encoding</i>

        <b class="d">.text</b> <u>mystr</u>     <i>;text as originally encoded</i>
        <b class="d">.text</b> <span class="s">s"p1"</span>     <i>;convert to bytes like <a href="#d_shift">.shift</a></i>
        <b class="d">.text</b> <span class="s">l"p2"</span>     <i>;convert to bytes like <a href="#d_shiftl">.shiftl</a></i>
        <b class="d">.text</b> <span class="s">n"p3"</span>     <i>;convert to bytes like <a href="#d_null">.null</a></i>
        <b class="d">.text</b> <span class="s">p"p4"</span>     <i>;convert to bytes like <a href="#d_ptext">.ptext</a></i>
</pre>

<p>Binary data may be embedded in source code by using hexadecimal byte
strings. This is more compact than using <code>.byte</code> followed by a lot
of numbers. As expected 1 byte becomes 2 characters.

<pre>
        <b class="d">.text</b> <span class="s">x"fce2"</span>   <i>;2 bytes: $fc and $e2 (big endian)</i>
</pre>

<p>If readability is not a concern then the more compact z85 encoding may be used
which encodes 4 bytes into 5 characters. Data lengths not a multiple of 4 are
handled by omitting leading zeros in the last group.

<pre>
        <b class="d">.text</b> <span class="s">z"FiUj*2M$hf"</span><i>;8 bytes: 80 40 20 10 08 04 02 01</i>
</pre>

<p>For data lengths of multiple of 4 bytes any z85 encoder will do. Otherwise the
simplest way to encode a binary file into a z85 string is to create a source file
which reads it using the line <q><code>label = binary('filename')</code></q>. Now if the labels
are listed to a file then there will be a z85 encoded definition for this
label.

<h3>Lists and tuples<a name="list-tuples" href="#list-tuples"></a></h3>

<p>Lists and tuples can hold a collection of values. Lists are defined from
values separated by comma between square brackets <code>[1, 2, 3]</code>, an
empty list is <code>[]</code>. Tuples are similar but are enclosed in
parentheses instead. An empty tuple is <code>()</code>, a single element tuple
is <code>(4,)</code> to differentiate from normal numeric expression
parentheses. When nested they function similar to an array. Both
types are immutable.

<div><table border="0">
<caption>List and tuple operators and functions</caption>
<tr><td><code><u>y</u> .. <u>x</u></code><td>concatenate lists<td><code>[<span>1</span>] .. [<span>2</span>]</code> is <code>[<span>1</span>, <span>2</span>]</code>
<tr><td><code><u>y</u> <span class="k">in</span> <u>x</u></code><td>is member of list<td><code><span>2</span> <span class="k">in</span> [<span>1</span>, <span>2</span>, <span>3</span>]</code> is <code><span>true</span></code>
<tr><td><code><u>a</u> <span class="k">x</span> <u>n</u></code><td>repeat<td><code>[<span>1</span>, <span>2</span>] <span class="k">x</span> <span>2</span></code> is <code>[<span>1</span>, <span>2</span>, <span>1</span>, <span>2</span>]</code>
<tr><td><code><u>a</u>[<u>i</u>]</code><td>element from start<td><code>(<span class="s">"1"</span>, <span>2</span>)[<span>1</span>]</code> is <code><span>2</span></code>
<tr><td><code><u>a</u>[-<u>i</u>]</code><td>element from end<td><code>(<span class="s">"1"</span>, <span>2</span>, <span>3</span>)[<span>-1</span>]</code> is <code><span>3</span></code>
<tr><td><code><u>a</u>[:]</code><td>no change<td><code>(<span>1</span>, <span>2</span>, <span>3</span>)[:]</code> is <code>(<span>1</span>, <span>2</span>, <span>3</span>)</code>
<tr><td><code><u>a</u>[<u>s</u>:]</code><td>cut off start<td><code>(<span>1</span>, <span>2</span>, <span>3</span>)[<span>1</span>:]</code> is <code>(<span>2</span>, <span>3</span>)</code>
<tr><td><code><u>a</u>[:-<u>s</u>]</code><td>cut off end<td><code>(<span>1</span>, <span>2.0</span>, <span>3</span>)[:<span>-1</span>]</code> is <code>(<span>1</span>, <span>2.0</span>)</code>
<tr><td><code><u>a</u>[<u>s</u>]</code><td>reverse<td><code>(<span>1</span>, <span>2</span>, <span>3</span>)[::<span>-1</span>]</code> is <code>(<span>3</span>, <span>2</span>, <span>1</span>)</code>
<tr><td><code>*<u>a</u></code><td>convert to arguments<td><code><span class="k">format</span>(<span class="s">"%d: %s"</span>, *<u>mylist</u>)</code>
<tr><td><code>... op <u>a</u></code><td>left fold<td><code>... + (<span>1</span>, <span>2</span>, <span>3</span>)</code> is <code>((<span>1</span>+<span>2</span>)+<span>3</span>)</code>
<tr><td><code><u>a</u> op ...</code><td>right fold<td><code>(<span>1</span>, <span>2</span>, <span>3</span>) - ...</code> is <code>(<span>1</span>-(<span>2</span>-<span>3</span>))</code>
</table></div>

<p>Arithmetic operations are applied on the all elements recursively,
therefore <code>[1, 2] + 1</code> is <code>[2, 3]</code>, and <code>abs([1,
-1])</code> is <code>[1, 1]</code>.

<p>Arithmetic operations between lists are applied one by one on their
elements, so <code>[1, 2] + [3, 4]</code> is <code>[4, 6]</code>.

<p>When lists form an array and columns/rows are missing the smaller array is
stretched to fill in the gaps if possible, so <code>[[1], [2]] * [3, 4]</code>
is <code>[[3, 4], [6, 8]]</code>.

<p>Lists and tuples support indexing and slicing. This is explained in detail
in section <q><a href="#slicing_indexing">Slicing and indexing</a></q>.

<pre>
mylist  <b>=</b> [<span>1</span>, <span>2</span>, <span class="s">"whatever"</span>]
mytuple <b>=</b> (<u>cmd_e</u>, <u>cmd_g</u>)

mylist  <b>=</b> (<span class="s">"e"</span>, <u>cmd_e</u>, <span class="s">"g"</span>, <u>cmd_g</u>, <span class="s">"i"</span>, <u>cmd_i</u>)
keys    <b class="d">.text</b> <u>mylist</u>[::<span>2</span>]    <i>; keys ("e", "g", "i")</i>
call_l  <b class="d">.byte</b> &lt;<u>mylist</u>[<span>1</span>::<span>2</span>]-<span>1</span><i>; routines (&lt;cmd_e-1, &lt;cmd_g-1, &lt;cmd_i-1)</i>
call_h  <b class="d">.byte</b> &gt;<u>mylist</u>[<span>1</span>::<span>2</span>]-<span>1</span><i>; routines (&gt;cmd_e-1, &gt;cmd_g-1, &gt;cmd_i-1)</i>
</pre>

<p>Although lists elements of variables can't be changed using indexing (at the
moment) the same effect can be achieved by combining slicing and
concatenation:

<pre>
lst     := <u>lst</u>[:<span>2</span>] .. [<span>4</span>] .. <u>lst</u>[<span>3</span>:]<i>; same as lst[2] := 4 would be</i>
</pre>

<p>Folding is done on pair of elements either forward (left) or reverse
(right). The list must contain at least one element. Here are some folding examples:

<pre>
minimum <b>=</b> <span class="k">size</span>([<u>part1</u>, <u>part2</u>, <u>part3</u>]) &lt;? ...
maximum <b>=</b> <span class="k">size</span>([<u>part1</u>, <u>part2</u>, <u>part3</u>]) &gt;? ...
sum     <b>=</b> <span class="k">size</span>([<u>part1</u>, <u>part2</u>, <u>part3</u>]) + ...
xorall  <b>=</b> <u>list_of_numbers</u> ^ ...
join    <b>=</b> <u>list_of_strings</u> .. ...
allbits <b>=</b> <u>sprites</u>.(<u>left</u>, <u>middle</u>, <u>right</u>).<u>bits</u> | ...
all     <b>=</b> [<span>true</span>, <span>true</span>, <span>true</span>, <span>true</span>] &amp;&amp; ...
any     <b>=</b> [<span>false</span>, <span>false</span>, <span>false</span>, <span>true</span>] || ...
</pre>

<p>The <code>range(start, end, step)</code> built-in function can be used to
create lists of integers in a range with a given step value. At least the end
must be given, the start defaults to 0 and the step to 1. Sounds not very
useful, so here are a few examples:

<pre>
<i>;Bitmask table, 8 bits from left to right</i>
        <b class="d">.byte</b> <span>%10000000</span> &gt;&gt; <span class="k">range</span>(<span>8</span>)
<i>;Classic 256 byte single period sinus table with values of 0&ndash;255.</i>
        <b class="d">.byte</b> <span>128</span> + <span>127.5</span> * <span class="k">sin</span>(<span class="k">range</span>(<span>256</span>) * <u>pi</u> / <span>128</span>)
<i>;Screen row address tables</i>
_       <b>:=</b> <span>$400</span> + <span class="k">range</span>(<span>0</span>, <span>1000</span>, <span>40</span>)
scrlo   <b class="d">.byte</b> &lt;<u>_</u>
scrhi   <b class="d">.byte</b> &gt;<u>_</u>
</pre>

<h3>Dictionaries<a name="dictionaries" href="#dictionaries"></a></h3>

<p>Dictionaries hold key and value pairs normally but can be used as sets too
if simple values are used. In the latter case the values are the keys for
themselves.

<p>A dictionary is defined with coma separated values between curly brackets. An
empty one is <code>{}</code>. Key and value pairs are separated with colon,
like <code>{ &lt;key&gt;:&lt;value&gt; }</code>. A default value for missing
items is can be defined by leaving out the key before the colon, like <code>{
:&lt;default&gt; }</code>. Simple value don't use a colon <code>{
&lt;value&gt; }</code>.

<p>Looking up a non-existing key is an error unless a default value is
given. Dictionaries are immutable. There are limitations what may be used as a
key but the value can be anything. As the keys are used for lookups these must
be unique.

<div><table border="0">
<caption>Dictionary operators and functions</caption>
<tr><td><code><u>y</u> .. <u>x</u></code><td>combine dictionaries<td><code>{<span>1</span>:<span>2</span>, <span>3</span>:<span>4</span>} .. {<span>2</span>:<span>3</span>, <span>3</span>:<span>1</span>}</code> is <code>{<span>1</span>:<span>2</span>, <span>2</span>:<span>3</span>, <span>3</span>:<span>1</span>}</code>
<tr><td><code><u>x</u>[<u>i</u>]</code><td>value lookup<td><code>{<span class="s">"1"</span>:<span>2</span>}[<span class="s">"1"</span>]</code> is <code><span>2</span></code>
<tr><td><code><u>x</u>.<u>i</u></code><td>symbol lookup<td><code>{.<u>ONE</u>:<span>1</span>, .<u>TWO</u>:<span>2</span>}.<u>ONE</u></code> is <code><span>1</span></code>
<tr><td><code><u>y</u> <span class="k">in</span> <u>x</u></code><td>is a key<td><code><span>1</span> <span class="k">in</span> {<span>1</span>:<span>2</span>}</code> is <code><span>true</span></code>
</table></div>

<pre>
<i>; Simple lookup</i>
        <b class="d">.text</b> {<span>1</span>:<span class="s">"one"</span>, <span>2</span>:<span class="s">"two"</span>}[<span>2</span>]<i>; "two"</i>
<i>; 16 element "fader" table 1-&gt;15-&gt;12-&gt;11-&gt;0</i>
        <b class="d">.byte</b> {<span>1</span>:<span>15</span>, <span>15</span>:<span>12</span>, <span>12</span>:<span>11</span>, :<span>0</span>}[<span class="k">range</span>(<span>16</span>)]
<i>; Variables can be used to build dictionaries incrementally.</i>
md      <b>:=</b> {<span>1</span>:<span>2</span>}
md      <b>..=</b> {<span>3</span>:<span>4</span>}
</pre>

<p>The keys can be symbols as well, this allows simple definition of data
structures or enumerations.</p>

<pre>
<i>; Symbol accessible values. May be useful as a function return value too.</i>
coords  <b>=</b> {.<u>x</u>: <span>24</span>, .<u>y</u>: <span>50</span>}
        <b>ldx</b> #<u>coords</u>.<u>x</u>
        <b>ldy</b> #<u>coords</u>.<u>y</u>
<i>; Simple enumeration where red = 0, green = 1, blue = 2</i>
colors  <b>=</b> <span class="k">dict</span>(.(<u>red</u>, <u>green</u>, <u>blue</u>), <span class="k">range</span>(<span>3</span>))
        <b>lda</b> #<u>color</u>.<u>green</u>
<i>; Enumerate register bits as %1, %10, %100, ...</i>
irqbits <b>=</b> <span class="k">dict</span>(.(<u>ta</u>, <u>tb</u>, <u>tod</u>, <u>serial</u>, <u>flag</u>), <span>%1</span> &lt;&lt; <span class="k">range</span>(<span>5</span>))
        <b>and</b> #<u>irqbits</u>.<u>flag</u>
</pre>

<h3>Code<a name="code" href="#code"></a></h3>
<p>Code holds the result of compilation in binary and other enclosed objects.
In an arithmetic operation it's used as the numeric address of the memory where
it starts. The compiled content remains static even if later parts of the
source overwrite the same memory area.

<p><b>Indexing and slicing of code to access the compiled content might be
implemented differently in future releases. Use this feature at your own
risk for now, you might need to update your code later.</b>

<div><table border="0">
<caption>Label operators and functions</caption>
<tr><td><code><u>a</u>.<u>b</u></code><td>b member of a<td><code><u>label</u>.<u>locallabel</u></code>
<tr><td><code>.<u>b</u> <span class="k">in</span> <u>a</u></code><td>if a has symbol b<td><code>.<u>locallabel</u> <span class="k">in</span> <u>label</u></code>
<tr><td><code><u>a</u>[<u>i</u>]</code><td>element from start<td><code><u>label</u>[<span>1</span>]</code>
<tr><td><code><u>a</u>[-<u>i</u>]</code><td>element from end<td><code><u>label</u>[<span>-1</span>]</code>
<tr><td><code><u>a</u>[<u>:</u>]</code><td>copy as tuple<td><code><u>label</u>[:]</code>
<tr><td><code><u>a</u>[<u>s</u>:]</code><td>cut off start, as tuple<td><code><u>label</u>[<span>1</span>:]</code>
<tr><td><code><u>a</u>[:-<u>s</u>]</code><td>cut off end, as tuple<td><code><u>label</u>[:<span>-1</span>]</code>
<tr><td><code><u>a</u>[<u>s</u>]</code><td>reverse, as tuple<td><code><u>label</u>[::<span>-1</span>]</code>
</table></div>

<pre>
mydata  <b class="d">.word</b> <span>1</span>, <span>4</span>, <span>3</span>
mycode  <b class="k">.block</b>
local   <b>lda</b> #<span>0</span>
        <b class="k">.endblock</b>

        <b>ldx</b> #<span class="k">size</span>(<u>mydata</u>) <i>;6 bytes (3*2)</i>
        <b>ldx</b> #<span class="k">len</span>(<u>mydata</u>)  <i>;3 elements</i>
        <b>ldx</b> #<u>mycode</u>[<span>0</span>]    <i>;lda instruction, $a9</i>
        <b>ldx</b> #<u>mydata</u>[<span>1</span>]    <i>;2nd element, 4</i>
        <b>jmp</b> <u>mycode</u>.<u>local</u>  <i>;address of local label</i>
</pre>

<h3>Addressing modes<a name="addressing" href="#addressing"></a></h3>

<p>Addressing modes are used for determining addressing modes of
instructions.

<p>For indexing there must be no white space between the comma and the register letter,
otherwise the indexing operator is not recognized. On the other hand put a space between
the comma and a single letter symbol in a list to avoid it being recognized
as an operator.

<div><table border="0">
<caption>Addressing mode operators</caption>
<tr><td><code>#</code><td>immediate
<tr><td><code>#+</code><td>signed immediate
<tr><td><code>#-</code><td>signed immediate
<tr><td><code>( )</code><td>indirect
<tr><td><code>[ ]</code><td>long indirect
<tr><td><code>,b</code><td>data bank indexed
<tr><td><code>,d</code><td>direct page indexed
<tr><td><code>,k</code><td>program bank indexed
<tr><td><code>,r</code><td>data stack pointer indexed
<tr><td><code>,s</code><td>stack pointer indexed
<tr><td><code>,x</code><td>x register indexed
<tr><td><code>,y</code><td>y register indexed
<tr><td><code>,z</code><td>z register indexed
</table></div>

<p>Parentheses are used for indirection and square brackets for long
indirection. These operations are only available after instructions and
functions to not interfere with their normal use in expressions.

<p>Several addressing mode operators can be combined together. <b>Currently the
complexity is limited to 4 operators. This is enough to describe all addressing
modes of the supported CPUs.</b>

<div><table border="0">
<caption>Valid addressing mode operator combinations</caption>
<tr><td><code>#</code><td>immediate<td><code><b>lda</b>&nbsp;#<span>$12</span></code>
<tr><td><code>#+</code><td>signed immediate<td><code><b>lda</b>&nbsp;#<span>+127</span></code>
<tr><td><code>#-</code><td>signed immediate<td><code><b>lda</b>&nbsp;#<span>-128</span></code>
<tr><td><code>#<u>addr</u>,#<u>addr</u></code><td>move<td><code><b>mvp</b>&nbsp;#<span>5</span>,#<span>6</span></code>
<tr><td><code><u>addr</u></code><td>direct or relative<td><code><b>lda</b>&nbsp;<span>$12</span> <b>lda</b>&nbsp;<span>$1234</span> <b>bne</b>&nbsp;<span>$1234</span></code>
<tr><td><code><u>bit</u>,<u>addr</u></code><td>direct page bit<td><code><b>rmb</b>&nbsp;<span>5</span>,<span>$12</span></code>
<tr><td><code><u>bit</u>,<u>addr</u>,<u>addr</u></code><td>direct page bit relative jump<td><code><b>bbs</b>&nbsp;<span>5</span>,<span>$12</span>,<span>$1234</span></code>
<tr><td><code>(<u>addr</u>)</code><td>indirect<td><code><b>lda</b>&nbsp;(<span>$12</span>) <b>jmp</b>&nbsp;(<span>$1234</span></code>)
<tr><td><code>(<u>addr</u>),y</code><td>indirect y indexed<td><code><b>lda</b>&nbsp;(<span>$12</span>),y</code>
<tr><td><code>(<u>addr</u>),z</code><td>indirect z indexed<td><code><b>lda</b>&nbsp;(<span>$12</span>),z</code>
<tr><td><code>(<u>addr</u>,x)</code><td>x indexed indirect<td><code><b>lda</b>&nbsp;(<span>$12</span>,x) <b>jmp</b>&nbsp;(<span>$1234</span>,x)</code>
<tr><td><code>[<u>addr</u>]</code><td>long indirect<td><code><b>lda</b>&nbsp;[<span>$12</span>] <b>jmp</b>&nbsp;[<span>$1234</span>]</code>
<tr><td><code>[<u>addr</u>],y</code><td>long indirect y indexed<td><code><b>lda</b>&nbsp;[<span>$12</span>],y</code>
<tr><td><code>#<u>addr</u>,b</code><td>data bank indexed<td><code><b>lda</b>&nbsp;#<span>0</span>,b</code>
<tr><td><code>#<u>addr</u>,b,x</code><td>data bank x indexed<td><code><b>lda</b>&nbsp;#<span>0</span>,b,x</code>
<tr><td><code>#<u>addr</u>,b,y</code><td>data bank y indexed<td><code><b>lda</b>&nbsp;#<span>0</span>,b,y</code>
<tr><td><code>#<u>addr</u>,d</code><td>direct page indexed<td><code><b>lda</b>&nbsp;#<span>0</span>,d</code>
<tr><td><code>#<u>addr</u>,d,x</code><td>direct page x indexed<td><code><b>lda</b>&nbsp;#<span>0</span>,d,x</code>
<tr><td><code>#<u>addr</u>,d,y</code><td>direct page y indexed<td><code><b>ldx</b>&nbsp;#<span>0</span>,d,y</code>
<tr><td><code>(#<u>addr</u>,d)</code><td>direct page indirect<td><code><b>lda</b>&nbsp;(#<span>$12</span>,d)</code>
<tr><td><code>(#<u>addr</u>,d,x)</code><td>direct page x indexed indirect<td><code><b>lda</b>&nbsp;(#<span>$12</span>,d,x)</code>
<tr><td><code>(#<u>addr</u>,d),y</code><td>direct page indirect y indexed<td><code><b>lda</b>&nbsp;(#<span>$12</span>,d),y</code>
<tr><td><code>(#<u>addr</u>,d),z</code><td>direct page indirect z indexed<td><code><b>lda</b>&nbsp;(#<span>$12</span>,d),z</code>
<tr><td><code>[#<u>addr</u>,d]</code><td>direct page long indirect<td><code><b>lda</b>&nbsp;[#<span>$12</span>,d]</code>
<tr><td><code>[#<u>addr</u>,d],y</code><td>direct page long indirect y indexed<td><code><b>lda</b>&nbsp;[#<span>$12</span>,d],y</code>
<tr><td><code>#<u>addr</u>,k</code><td>program bank indexed<td><code><b>jsr</b>&nbsp;#<span>0</span>,k</code>
<tr><td><code>(#<u>addr</u>,k,x)</code><td>program bank x indexed indirect<td><code><b>jmp</b>&nbsp;(#<span>$1234</span>,k,x)</code>
<tr><td><code>#<u>addr</u>,r</code><td>data stack indexed<td><code><b>lda</b>&nbsp;#<span>1</span>,r</code>
<tr><td><code>(#<u>addr</u>,r),y</code><td>data stack indexed indirect y indexed<td><code><b>lda</b>&nbsp;(#<span>$12</span>,r),y</code>
<tr><td><code>#<u>addr</u>,s</code><td>stack indexed<td><code><b>lda</b>&nbsp;#<span>1</span>,s</code>
<tr><td><code>(#<u>addr</u>,s),y</code><td>stack indexed indirect y indexed<td><code><b>lda</b>&nbsp;(#<span>$12</span>,s),y</code>
<tr><td><code><u>addr</u>,x</code><td>x indexed<td><code><b>lda</b>&nbsp;<span>$12</span>,x</code>
<tr><td><code><u>addr</u>,y</code><td>y indexed<td><code><b>lda</b>&nbsp;<span>$12</span>,y</code>
</table></div>

<p>Direct page, data bank, program bank indexed and long addressing modes
of instructions are intelligently chosen based on the instruction type,
the address ranges set up by <a href="#d_dpage"><code>.dpage</code></a>, <a href="#d_databank"><code>.databank</code></a>
and the current program counter address. Therefore the <q><code>,d</code></q>,
<q><code>,b</code></q> and <q><code>,k</code></q> indexing is only used in very special cases.

<p>The immediate direct page indexed <q><code>#0,d</code></q> addressing
mode is usable for direct page access. The 8&nbsp;bit constant is a
direct offset from the start of actual direct page. Alternatively it may
be written as <q><code>0,d</code></q>.

<p>The immediate data bank indexed <q><code>#0,b</code></q> addressing
mode is usable for data bank access. The 16&nbsp;bit constant is a direct
offset from the start of actual data bank. Alternatively it may be
written as <q><code>0,b</code></q>.

<p>The immediate program bank indexed <q><code>#0,k</code></q> addressing mode
is usable for program bank jumps, branches and calls. The 16&nbsp;bit constant
is a direct offset from the start of actual program bank. Alternatively it may
be written as <q><code>0,k</code></q>.

<p>The immediate stack indexed <q><code>#0,s</code></q> and data stack indexed
<q><code>#0,r</code></q> accept 8&nbsp;bit constants as an offset from the
start of (data) stack. These are sometimes written without the immediate
notation, but this makes it more clear what's going on. For the same reason the
move instructions are written with an immediate addressing mode <q><code>#0,#0</code></q> as well.

<p>The immediate (<code>#</code>) addressing mode expects unsigned values of byte or
word size. Therefore it only accepts constants of 1 byte or in range 0&ndash;255
or 2 bytes or in range 0&ndash;65535.

<p>The signed immediate (<code>#+</code> and <code>#-</code>) addressing
mode is to allow signed numbers to be used as immediate constants. It accepts
a single byte or an integer in range &minus;128&ndash;127, or two bytes or an integer of
&minus;32768&ndash;32767.

<p>The use of signed immediate (like <code>#-3</code>) is seamless, but
it needs to be explicitly written out for variables or expressions
(<code>#+variable</code>). In case the unsigned variant is needed but the
expression starts with a negation then it needs to be put into parentheses
(<code>#(-variable)</code>) or else it'll change the address mode to
signed.

<p>Normally addressing mode operators are used in expressions right after
instructions. They can also be used for defining stack variable symbols when
using a 65816, or to force a specific addressing mode.

<pre>
param   <b>=</b> #<span>1</span>,s            <i>;define a stack variable</i>
const   <b>=</b> #<span>1</span>              <i>;immediate constant</i>
        <b>lda</b> #<span>0</span>,b          <i>;always "absolute" lda $0000</i>
        <b>lda</b> <u>param</u>         <i>;results in lda #$01,s</i>
        <b>lda</b> <u>param</u>+<span>1</span>       <i>;results in lda #$02,s</i>
        <b>lda</b> (<u>param</u>),y     <i>;results in lda (#$01,s),y</i>
        <b>ldx</b> <u>const</u>         <i>;results in ldx #$01</i>
        <b>lda</b> #<span>-2</span>           <i>;negative constant, $fe</i>
</pre>

<h3>Uninitialized memory<a name="uninitialized" href="#uninitialized"></a></h3>

<p>There's a special value for uninitialized memory, it's represented by a
question mark. Whenever it's used to generate data it creates a <q>hole</q>
where the previous content of memory is visible.

<p>Uninitialized memory holes without previous content are not saved unless
it's really necessary for the output format, in that case it's replaced with
zeros.

<p>It's not just data generation statements (e.g. <a href="#d_byte"><code>.byte</code></a>) that can
create uninitialized memory, but <a href="#d_fill"><code>.fill</code></a>, <a href="#d_align"><code>.align</code></a> or address manipulation as
well.

<pre>
*       <b>=</b> <span>$200</span>          <i>;bytes as necessary</i>
        <b class="d">.word</b> <span>?</span>         <i>;2 bytes</i>
        <b class="d">.fill</b> <span>10</span>        <i>;10 bytes</i>
        <b class="k">.align</b> <span>64</span>       <i>;bytes as necessary</i>
</pre>

<h3>Booleans<a name="booleans" href="#booleans"></a></h3>

<p>There are two predefined boolean constant variables, <code>true</code> and <code>false</code>.

<p>Booleans are created by comparison operators (<code>&lt;</code>,
<code>&lt;=</code>, <code>!=</code>, <code>==</code>, <code>&gt;=</code>, <code>&gt;</code>),
logical operators (<code>&amp;&amp;</code>, <code>||</code>, <code>^^</code>,
<code>!</code>), the membership operator (<code>in</code>) and the
<code>all</code> and <code>any</code> functions.

<p>Normally in numeric expressions <code>true</code> is <code>1</code> and
<code>false</code> is <code>0</code>, unless the <q><a href="#o_Wstrict-bool"><code>-Wstrict-bool</code></a></q> command line option was
used.

<p>Other types can be converted to boolean by using the type <code>bool</code>.

<div><table border="0">
<caption>Boolean values of various types</caption>
<tr><td><code><u>bits</u></code><td>At least one non-zero bit
<tr><td><code><u>bool</u></code><td>When true
<tr><td><code><u>bytes</u></code><td>At least one non-zero byte
<tr><td><code><u>code</u></code><td>Address is non-zero
<tr><td><code><u>float</u></code><td>Not <code><span>0.0</span></code>
<tr><td><code><u>int</u></code><td>Not zero
<tr><td><code><u>str</u></code><td>At least one non-zero byte after translation
</table></div>

<h3>Types<a name="type" href="#type"></a></h3>

<p>The various types mentioned earlier have predefined names. These can
used for conversions or type checks.

<div><table border="0">
<caption>Built-in type names</caption>
<tr><td><code><a name="t_address"><u>address</u></a></code><td>Address type
<tr><td><code><a name="t_bits"><u>bits</u></a></code><td>Bit string type
<tr><td><code><a name="t_bool"><u>bool</u></a></code><td>Boolean type
<tr><td><code><a name="t_bytes"><u>bytes</u></a></code><td>Byte string type
<tr><td><code><a name="t_code"><u>code</u></a></code><td>Code type
<tr><td><code><a name="t_dict"><u>dict</u></a></code><td>Dictionary type
<tr><td><code><a name="t_float"><u>float</u></a></code><td>Floating point type
<tr><td><code><a name="t_gap"><u>gap</u></a></code><td>Uninitialized memory type
<tr><td><code><a name="t_int"><u>int</u></a></code><td>Integer type
<tr><td><code><a name="t_list"><u>list</u></a></code><td>List type
<tr><td><code><a name="t_str"><u>str</u></a></code><td>Character string type
<tr><td><code><a name="t_symbol"><u>symbol</u></a></code><td>Symbol type
<tr><td><code><a name="t_tuple"><u>tuple</u></a></code><td>Tuple type
<tr><td><code><a name="t_type"><u>type</u></a></code><td>Type type
</table></div>

<p>Bit and byte string conversions can take a second parameter to specify an
exact size. Values which can fit in shorter space will be padded but longer ones
give an error.

<dl class="dir">
<dt><b>bits(</b>&lt;expression&gt;[, &lt;bit count&gt;]<b>)</b>
<dd>Convert to the specific number of bits. If the number of bits is negative then it's a signed.</dd>
<dt><b>bytes(</b>&lt;expression&gt;[, &lt;byte count&gt;]<b>)</b>
<dd>Convert to the specific number of bytes. If the number of bits is negative then it's a signed.</dd>
</dl>

<p>Dictionaries can be built from a single iterable of key and value pairs, or
from two iterables where the keys come from the first and the values from the
second parameter.

<dl class="dir">
<dt><b>dict(</b>&lt;iterable&gt;[, &lt;values iterable&gt;]<b>)</b>
<dd>Build dictionary from iterables</dd>
</dl>

<pre>
        <b class="k">.cerror</b> <span class="k">type</span>(<u>var</u>) != <span class="k">str</span>, <span class="s">"Not a string!"</span>
        <b class="d">.text</b> <span class="k">str</span>(<u>year</u>)   <i>; convert to string</i>
</pre>

<h3>Symbols<a name="symbols" href="#symbols"></a></h3>

<p>Symbols are used to reference objects. Regularly named, anonymous and local
symbols are supported. These can be constant or re-definable.

<p>Scopes are where symbols are stored and looked up. The global scope is
always defined and it can contain any number of nested scopes.

<p>Symbols must be uniquely named in a scope, therefore in big programs it's
hard to come up with useful and easy to type names. That's why local and anonymous symbols
exists. And grouping certain related symbols into a scope makes sense sometimes
too.

<p>Scopes are usually created by <a href="#d_proc"><code>.proc</code></a> and <a href="#d_block"><code>.block</code></a>
directives, but there are a few other ways. Symbols in a scope can be accessed
by using the dot operator, which is applied between the name of the scope and the symbol (e.g. <code>myconsts.math.pi</code>).

<h4>Regular symbols<a name="symbols-regular" href="#symbols-regular"></a></h4>

<p>Regular symbol names are starting with a letter and containing
letters, numbers and underscores. Unicode letters are allowed if the <q><a href="#o_ascii"><code>-a</code></a></q> command line option was used.
There's no restriction on the length of symbol names.

<p>Care must be taken to not use duplicate names in the same scope when
the symbol is used as a constant as there can be only one definition for them.

<p>Duplicate names in parent scopes are not a problem and this gives the
ability to override names defined in lower scopes. However this can just as well lead to mistakes if
a lower scoped symbol with the same name was meant so there's a
<q><a href="#o_Wshadow"><code>-Wshadow</code></a></q> command line option to warn if such ambiguity exists.

<p>Case sensitivity can be enabled with the
<q><a href="#o_case-sensitive"><code>-C</code></a></q> command line option, otherwise all
symbols are matched case insensitive.

<p>For case insensitive matching it's possible to check for consistent symbol name use
with the <q><a href="#o_Wcase-symbol"><code>-Wcase-symbol</code></a></q> command
line option.

<p>A regular symbol is looked up first in the current scope, then in lower scopes
until the global scope is reached.

<pre>
f       <b class="k">.block</b>
g        <b class="k">.block</b>
n        <b>nop</b>            <i>;jump here</i>
         <b class="k">.endblock</b>
        <b class="k">.endblock</b>

        <b>jsr</b> <u>f</u>.<u>g</u>.<u>n</u>       <i>;reference from a scope</i>
f.x     <b>=</b> <span>3</span>             <i>;create x in scope f with value 3</i>
</pre>

<h4>Local symbols<a name="symbols-local" href="#symbols-local"></a></h4>

<p>Local symbols have their own scope between two regularly named code symbols
and are assigned to the code symbol above them.

<p>Therefore they're easy to reuse without explicit scope declaration directives.

<p>Not all regularly named symbols can be scope boundaries just plain code symbol ones
without anything or an opcode after them (no macros!). Symbols defined as procedures, blocks,
macros, functions, structures and unions are ignored. Also symbols defined by
<a href="#d_var"><code>.var</code></a>, <code>:=</code> or <code>=</code> don't apply, and there are a few more
exceptions, so stick to using plain code labels.

<p>The name must start with an underscore (<code>_</code>), otherwise the same character
restrictions apply as for regular symbols. There's no restriction on the length of the name.

<p>Care must be taken to not use the duplicate names in the same scope when the
symbol is used as a constant.

<p>A local symbol is only looked up in it's own scope and nowhere else.

<pre>
incr    <b>inc</b> <u>ac</u>
        <b>bne</b> <u>_skip</u>
        <b>inc</b> <u>ac</u>+<span>1</span>
_skip   <b>rts</b>

decr    <b>lda</b> <u>ac</u>
        <b>bne</b> <u>_skip</u>
        <b>dec</b> <u>ac</u>+<span>1</span>
_skip   <b>dec</b> <u>ac</u>          <i>;symbol reused here</i>
        <b>jmp</b> <u>incr</u>.<u>_skip</u>  <i>;this works too, but is not advised</i>
</pre>

<h4>Anonymous symbols<a name="symbols-anonymous" href="#symbols-anonymous"></a></h4>

<p>Anonymous symbols don't have a unique name and are always called as a single plus or minus sign. They are also called as forward (<code>+</code>)
and backward (<code>-</code>) references.

<p>When referencing them <q><code>-</code></q> means the first backward,
<q><code>--</code></q> means the second backwards and so on. It's the same for forward, but with
<q><code>+</code></q>. In expressions it may be necessary to put them into brackets.

<pre>
        <b>ldy</b> #<span>4</span>
-       <b>ldx</b> #<span>0</span>
-       <b>txa</b>
        <b>cmp</b> #<span>3</span>
        <b>bcc</b> +
        <b>adc</b> #<span>44</span>
+       <b>sta</b> <span>$400</span>,x
        <b>inx</b>
        <b>bne</b> <u>-</u>
        <b>dey</b>
        <b>bne</b> <u>--</u>
</pre>

<p>Excessive nesting or long distance references create poorly readable code.
It's also very easy to copy-paste a few lines of code with these references into
a code fragment already containing similar references. The result is usually a
long debugging session to find out what went wrong.

<p>These references are also useful in segments, but this can create a nice
trap when segments are copied into the code with their internal references.

<pre>
        <b>bne</b> +
        <b class="k">#somemakro</b>      <i>;let's hope that this segment does</i>
+       <b>nop</b>             <i>;not contain forward references...</i>
</pre>

<p>Anonymous symbols are looked up first in the current scope, then in lower scopes
until the global scope is reached.

<p>Anonymous labels within conditionally assembled code are counted even
if the code itself is not compiled and the label won't get defined.
This ensures that anonymous labels are always at the same "distance"
independent of the conditions in between.

<h4>Constant and re-definable symbols<a name="symbols-constant" href="#symbols-constant"></a></h4>

<p>Constant symbols can be created with the equal sign. These are not
re-definable. Forward referencing of them is allowed as they retain the
objects over compilation passes.

<p>Symbols in front of code or certain assembler directives are created as
constant symbols too. They are bound to the object following them.

<p>Re-definable symbols can be created by the <a href="#d_var"><code>.var</code></a> directive
or <code>:=</code> construct. These are also called as variables. They
don't carry their content over from the previous pass therefore it's not
possible to use them before their definition.

<p>If the variable already exists in the current scope it'll get updated.
If an existing variable needs to be updated in a parent scope then the
<code>::=</code> variable reassign operator is able to do that.

<p>Variables can be conditionally defined using the <code>:?=</code> construct.
If the variable was defined already then the original value is retained
otherwise a new one is created with this value.

<pre>
WIDTH   <b>=</b> <span>40</span>            <i>;a constant</i>
        <b>lda</b> #<u>WIDTH</u>      <i>;lda #$28</i>
variabl <b class="k">.var</b> <span>1</span>          <i>;a variable</i>
var2    <b>:=</b> <span>1</span>            <i>;another variable</i>
variabl <b class="k">.var</b> <u>variabl</u> + <span>1</span><i>;update it verbosely</i>
var2    <b>+=</b> <span>1</span>            <i>;compound assignment (add one)</i>
var3    <b>:?=</b> <span>5</span>           <i>;assign 5 if undefined</i>
</pre>

<h4>The star label<a name="star" href="#star"></a></h4>

<p>The <q><code>*</code></q> symbol denotes the current program
counter value. When accessed it's value is the program counter at the
beginning of the line. Assigning to it changes the program counter and
the compiling offset.

<h3>Built-in functions<a name="builtin-functions" href="#builtin-functions"></a></h3>

<p>Built-in functions are pre-assigned to the symbols listed below. If you reuse these
symbols in a scope for other purposes then they become inaccessible, or can
perform a different function.

<p>Built-in functions can be assigned to symbols (e.g. <code>sinus = sin</code>), and
the new name can be used as the original function. They can even be passed as
parameters to functions.

<h4>Mathematical functions<a name="math-functions" href="#math-functions"></a></h4>

<dl class="dir">
<dt><b>floor(</b>&lt;expression&gt;<b>)</b><a name="f_floor" href="#f_floor"></a>
<dd>Round down. E.g.
<code><span class="k">floor</span>(<span>-4.8</span>)</code> is <code><span>-5.0</span></code></dd>

<dt><b>round(</b>&lt;expression&gt;<b>)</b><a name="f_round" href="#f_round"></a>
<dd>Round to nearest away from zero. E.g.
<code><span class="k">round</span>(<span>4.8</span>)</code> is <code><span>5.0</span></code></dd>

<dt><b>ceil(</b>&lt;expression&gt;<b>)</b><a name="f_ceil" href="#f_ceil"></a>
<dd>Round up. E.g.
<code><span class="k">ceil</span>(<span>1.1</span>)</code> is <code><span>2.0</span></code></dd>

<dt><b>trunc(</b>&lt;expression&gt;<b>)</b><a name="f_trunc" href="#f_trunc"></a>
<dd>Round down towards zero. E.g.
<code><span class="k">trunc</span>(<span>-1.9</span>)</code> is <code><span>-1</span></code></dd>

<dt><b>frac(</b>&lt;expression&gt;<b>)</b><a name="f_frac" href="#f_frac"></a>
<dd>Fractional part. E.g.
<code><span class="k">frac</span>(<span>1.1</span>)</code> is <code><span>0.1</span></code></dd>

<dt><b>sqrt(</b>&lt;expression&gt;<b>)</b><a name="f_sqrt" href="#f_sqrt"></a>
<dd>Square root. E.g.
<code><span class="k">sqrt</span>(<span>16.0</span>)</code> is <code><span>4.0</span></code></dd>

<dt><b>cbrt(</b>&lt;expression&gt;<b>)</b><a name="f_cbrt" href="#f_cbrt"></a>
<dd>Cube root. E.g.
<code><span class="k">cbrt</span>(<span>27.0</span>)</code> is <code><span>3.0</span></code></dd>

<dt><b>log10(</b>&lt;expression&gt;<b>)</b><a name="f_log10" href="#f_log10"></a>
<dd>Common logarithm. E.g.
<code><span class="k">log10</span>(<span>100.0</span>)</code> is <code><span>2.0</span></code></dd>

<dt><b>log(</b>&lt;expression&gt;[, &lt;expression base&gt;]<b>)</b><a name="f_log" href="#f_log"></a>
<dd>Logarithm, natural by default. E.g.
<code><span class="k">log</span>(<span>1</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>exp(</b>&lt;expression&gt;<b>)</b><a name="f_exp" href="#f_exp"></a>
<dd>Exponential. E.g.
<code><span class="k">exp</span>(<span>0</span>)</code> is <code><span>1.0</span></code></dd>

<dt><b>pow(</b>&lt;expression a&gt;, &lt;expression b&gt;<b>)</b><a name="f_pow" href="#f_pow"></a>
<dd>A raised to power of B. E.g.
<code><span class="k">pow</span>(<span>2.0, 3.0</span>)</code> is <code><span>8.0</span></code></dd>

<dt><b>sin(</b>&lt;expression&gt;<b>)</b><a name="f_sin" href="#f_sin"></a>
<dd>Sine. E.g.
<code><span class="k">sin</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>asin(</b>&lt;expression&gt;<b>)</b><a name="f_asin" href="#f_asin"></a>
<dd>Arc sine. E.g.
<code><span class="k">asin</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>sinh(</b>&lt;expression&gt;<b>)</b><a name="f_sinh" href="#f_sinh"></a>
<dd>Hyperbolic sine. E.g.
<code><span class="k">sinh</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>cos(</b>&lt;expression&gt;<b>)</b><a name="f_cos" href="#f_cos"></a>
<dd>Cosine. E.g.
<code><span class="k">cos</span>(<span>0.0</span>)</code> is <code><span>1.0</span></code></dd>

<dt><b>acos(</b>&lt;expression&gt;<b>)</b><a name="f_acos" href="#f_acos"></a>
<dd>Arc cosine. E.g.
<code><span class="k">acos</span>(<span>1.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>cosh(</b>&lt;expression&gt;<b>)</b><a name="f_cosh" href="#f_cosh"></a>
<dd>Hyperbolic cosine. E.g.
<code><span class="k">cosh</span>(<span>0.0</span>)</code> is <code><span>1.0</span></code></dd>

<dt><b>tan(</b>&lt;expression&gt;<b>)</b><a name="f_tan" href="#f_tan"></a>
<dd>Tangent. E.g.
<code><span class="k">tan</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>atan(</b>&lt;expression&gt;<b>)</b><a name="f_atan" href="#f_atan"></a>
<dd>Arc tangent. E.g.
<code><span class="k">atan</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>tanh(</b>&lt;expression&gt;<b>)</b><a name="f_tanh" href="#f_tanh"></a>
<dd>Hyperbolic tangent. E.g.
<code><span class="k">tanh</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>rad(</b>&lt;expression&gt;<b>)</b><a name="f_rad" href="#f_rad"></a>
<dd>Degrees to radian. E.g.
<code><span class="k">rad</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>deg(</b>&lt;expression&gt;<b>)</b><a name="f_deg" href="#f_deg"></a>
<dd>Radian to degrees. E.g.
<code><span class="k">deg</span>(<span>0.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>hypot(</b>[&lt;expression&gt;, &hellip;]<b>)</b><a name="f_hypot" href="#f_hypot"></a>
<dd>Euclidean distance, any dimensions. E.g.
<code><span class="k">hypot</span>(<span>4.0</span>, <span>3.0</span>)</code> is <code><span>5.0</span></code></dd>

<dt><b>atan2(</b>&lt;expression y&gt;, &lt;expression x&gt;<b>)</b><a name="f_atan2" href="#f_atan2"></a>
<dd>Polar angle in &minus;pi to +pi range. E.g.
<code><span class="k">atan2</span>(<span>0.0</span>, <span>3.0</span>)</code> is <code><span>0.0</span></code></dd>

<dt><b>abs(</b>&lt;expression&gt;<b>)</b><a name="f_abs" href="#f_abs"></a>
<dd>Absolute value. E.g.
<code><span class="k">abs</span>(<span>-1</span>)</code> is <code><span>1</span></code></dd>

<dt><b>sign(</b>&lt;expression&gt;<b>)</b><a name="f_sign" href="#f_sign"></a>
<dd>Returns the sign of value as &minus;1, 0 or 1 for negative, zero and positive. E.g.
<code><span class="k">sign</span>(<span>-5</span>)</code> is <code><span>-1</span></code></dd>

</dl>

<h4>Byte string functions<a name="byte-functions" href="#byte-functions"></a></h4>

<p>These functions return byte strings of various lengths for signed numbers,
unsigned numbers and addresses.

<p>The naming of functions is not a coincidence and they return the bytes what
the <a href="#data-dumping">data directives</a> with the same names normally emit.

<dl class="dir">
<dt><b>byte(</b>&lt;expression&gt;<b>)</b><a name="f_byte" href="#f_byte"></a>
<dt><b>char(</b>&lt;expression&gt;<b>)</b><a name="f_char" href="#f_char"></a>
<dd>Return a single byte string from a 8&nbsp;bit unsigned (0&ndash;255) or signed number (&minus;128&ndash;127). E.g.
<code><span class="k">byte</span>(<span>0</span>)</code> is <code><span class="s">x"00"</span></code> and
<code><span class="k">char</span>(<span>-1</span>)</code> is <code><span class="s">x"ff"</span></code></dd>

<dt><b>word(</b>&lt;expression&gt;<b>)</b><a name="f_word" href="#f_word"></a>
<dt><b>sint(</b>&lt;expression&gt;<b>)</b><a name="f_sint" href="#f_sint"></a>
<dd>Return a little endian byte string of 2&nbsp;bytes from a 16&nbsp;bit unsigned (0&ndash;65535) or signed number (&minus;32768&ndash;32767). E.g.
<code><span class="k">word</span>(<span>1024</span>)</code> is <code><span class="s">x"0004"</span></code> and
<code><span class="k">sint</span>(<span>-1</span>)</code> is <code><span class="s">x"ffff"</span></code></dd>

<dt><b>long(</b>&lt;expression&gt;<b>)</b><a name="f_long" href="#f_long"></a>
<dt><b>lint(</b>&lt;expression&gt;<b>)</b><a name="f_lint" href="#f_lint"></a>
<dd>Return a little endian byte string of 3&nbsp;bytes from a 24&nbsp;bit unsigned (0&ndash;16777216) or signed number (&minus;8388608&ndash;8388607). E.g.
<code><span class="k">long</span>(<span>123456</span>)</code> is <code><span class="s">x"40E201"</span></code> and
<code><span class="k">lint</span>(<span>-1</span>)</code> is <code><span class="s">x"ffffff"</span></code></dd>

<dt><b>dword(</b>&lt;expression&gt;<b>)</b><a name="f_dword" href="#f_dword"></a>
<dt><b>dint(</b>&lt;expression&gt;<b>)</b><a name="f_dint" href="#f_dint"></a>
<dd>Return a little endian byte string of 4&nbsp;bytes from a 32&nbsp;bit unsigned (0&ndash;4294967296) or signed number (&minus;2147483648&ndash;2147483647). E.g.
<code><span class="k">dword</span>(<span>123456789</span>)</code> is <code><span class="s">x"15CD5B07"</span></code> and
<code><span class="k">dint</span>(<span>-1</span>)</code> is <code><span class="s">x"ffffffff"</span></code></dd>

<dt><b>addr(</b>&lt;expression&gt;<b>)</b><a name="f_addr" href="#f_addr"></a>
<dd>Return a little endian byte string of 2&nbsp;bytes from an address in the current program bank. E.g.
<code><span class="k">addr</span>(start)</code> is <code><span class="s">x"0d08"</span></code></dd>

<dt><b>rta(</b>&lt;expression&gt;<b>)</b><a name="f_rta" href="#f_rta"></a>
<dd>Return a little endian byte string of 2&nbsp;bytes from a return address in the current program bank. E.g.
<code><span class="k">rta</span>(<span>4096</span>)</code> is <code><span class="s">x"ff0f"</span></code></dd>

</dl>

<h4>Other functions<a name="other-functions" href="#other-functions"></a></h4>

<dl class="dir">

<dt><b>all(</b>&lt;expression&gt;<b>)</b><a name="f_all" href="#f_all"></a>
<dd>Return truth for various definitions of <q>all</q>.

<div><table border="0">
<caption>All function</caption>
<tr><td width="50%">all bits set or no bits at all<td><code><span class="k">all</span>(<span>$f</span>)</code> is <code><span>true</span></code>
<tr><td>all characters non-zero or empty string<td><code><span class="k">all</span>(<span class="s">"c"</span>)</code> is <code><span>true</span></code>
<tr><td>all bytes non-zero or no bytes<td><code><span class="k">all</span>(<span class="s">x"ac24"</span>)</code> is <code><span>true</span></code>
<tr><td>all elements true or empty list<td><code><span class="k">all</span>([<span>true</span>, <span>true</span>, <span>false</span>])</code> is <code><span>false</span></code>
</table></div>

<p>Only booleans in a list are accepted with the <q><a href="#o_Wstrict-bool"><code>-Wstrict-bool</code></a></q> command line option.</p></dd>

<dt><b>any(</b>&lt;expression&gt;<b>)</b><a name="f_any" href="#f_any"></a>
<dd>Return truth for various definitions of <q>any</q>.

<div><table border="0">
<caption>Any function</caption>
<tr><td width="50%">at least one bit set<td><code><span class="k">any</span>(~<span>$f</span>)</code> is <code><span>false</span></code>
<tr><td>at least one non-zero character<td><code><span class="k">any</span>(<span class="s">"c"</span>)</code> is <code><span>true</span></code>
<tr><td>at least one non-zero byte<td><code><span class="k">any</span>(<span class="s">x"ac24"</span>)</code> is <code><span>true</span></code>
<tr><td>at least one true element<td><code><span class="k">any</span>([<span>true</span>, <span>true</span>, <span>false</span>])</code> is <code><span>true</span></code>
</table></div>

<p>Only booleans in a list are accepted with the <q><a href="#o_Wstrict-bool"><code>-Wstrict-bool</code></a></q> command line option.</p></dd>

<dt><b>binary(</b>&lt;string expression&gt;[, &lt;offset&gt;[, &lt;length&gt;]]<b>)</b><a name="f_binary" href="#f_binary"></a>
<dd>Returns the binary file content as bytes.

<p>This function reads the content of a binary file as a <a href="#byte-string">byte string</a>. It also accepts optional offset and length parameters.

<div><table border="0">
<caption>Binary function invocation types</caption>
<tr><td>Read everything<td><code><span class="k">binary</span>(<u>name</u>)</code>
<tr><td>Skip starting bytes<td><code><span class="k">binary</span>(<u>name</u>, <u>offset</u>)</code>
<tr><td>Some bytes from offset<td><code><span class="k">binary</span>(<u>name</u>, <u>offset</u>, <u>length</u>)</code>
</table></div>

<pre>
sid     <b>=</b> <span class="k">binary</span>(<span class="s">"music.sid"</span>)<i>; read in the SID file as bytes</i>
offs    <b>:=</b> <u>sid</u>[[<span>$7</span>, <span>$6</span>]]     <i>; data offset (big endian)</i>
load    <b>:=</b> <u>sid</u>[[<span>$9</span>, <span>$8</span>]]     <i>; load address (big endian)</i>
init    <b>=</b> <u>sid</u>[[<span>$b</span>, <span>$a</span>]]      <i>; init address (big endian)</i>
play    <b>=</b> <u>sid</u>[[<span>$d</span>, <span>$c</span>]]      <i>; play address (big endian)</i>

<i>; if load address is zero then it's the first 2 bytes of data</i>
        <b class="k">.if</b> <u>load</u> == <span>0</span>
load    := <u>sid</u>[<u>offs</u>:<u>offs</u>+<span>2</span>]  <i>; load address (little endian)</i>
offs    += <span>2</span>                 <i>; skip load address bytes</i>
        <b class="k">.endif</b>

*       <b>=</b> <u>load</u>               <i>; set pc to load address</i>
        <b class="d">.text</b> <u>sid</u>[<u>offs</u>:]     <i>; dump music data</i>
</pre></dd>

<dt><b>format(</b>&lt;string expression&gt;[, &lt;expression&gt;, &hellip;]<b>)</b><a name="f_format" href="#f_format"></a>
<dd>Create string from values according to a format string.
<p>The <code>format</code> function converts a list of values into a character string.
The converted values are inserted in place of the <code>%</code> sign. Optional
conversion flags and minimum field length may follow, before the conversion
type character. These flags can be used:</p>

<div><table border="0">
<caption>Formatting flags</caption>
<tr><td width="40"><code>#</code><td>alternate form (<code><span>-$a</span></code>, <code><span>~$a</span></code>, <code><span>-%10</span></code>, <code><span>~%10</span></code>, <code><span>-10.</span></code>)
<tr><td><code>*</code><td>width/precision from list
<tr><td><code>.</code><td>precision
<tr><td><code>0</code><td>pad with zeros
<tr><td><code>-</code><td>left adjusted (default right)
<tr><td><code>&nbsp;</code><td>blank when positive or minus sign
<tr><td><code>+</code><td>sign even if positive
<tr><td><code>~</code><td>binary and hexadecimal as bits
</table></div>

<p>The following conversion types are implemented:</p>

<div><table border="0">
<caption>Formatting conversion types</caption>
<tr><td width="40"><code>b</code><td>binary
<tr><td><code>c</code><td>Unicode character
<tr><td><code>d</code><td>decimal
<tr><td><code>e&nbsp;E</code><td>exponential float (uppercase)
<tr><td><code>f&nbsp;F</code><td>floating point (uppercase)
<tr><td><code>g&nbsp;G</code><td>exponential/floating point
<tr><td><code>s</code><td>string
<tr><td><code>r</code><td>representation
<tr><td><code>x&nbsp;X</code><td>hexadecimal (uppercase)
<tr><td><code>%</code><td>percent sign
</table></div>

<pre>
        <b class="d">.text</b> <span class="k">format</span>(<span class="s">"<span>%#04x</span> bytes left"</span>, <span>1000</span>)<i>; $03e8 bytes left</i>
</pre></dd>

<dt><b>len(</b>&lt;expression&gt;<b>)</b><a name="f_len" href="#f_len"></a>
<dd>Returns the number of elements.

<div><table border="0">
<caption>Length of various types</caption>
<tr><td>bit string<td>length in bits<td><code><span class="k">len</span>(<span>$034</span>)</code> is <code><span>12</span></code>
<tr><td>character string<td>number of characters<td><code><span class="k">len</span>(<span class="s">"abc"</span>)</code> is <code><span>3</span></code>
<tr><td>byte string<td>number of bytes<td><code><span class="k">len</span>(<span class="s">x"abcd23"</span>)</code> is <code><span>3</span></code>
<tr><td>tuple, list<td>number of elements<td><code><span class="k">len</span>([<span>1</span>, <span>2</span>, <span>3</span>])</code> is <code><span>3</span></code>
<tr><td>dictionary<td>number of elements<td><code><span class="k">len</span>({<span>1</span>:<span>2</span>, <span>3</span>:<span>4</span>])</code> is <code><span>2</span></code>
<tr><td>code<td>number of elements<td><code><span class="k">len</span>(<u>label</u>)</code>
</table></div></dd>

<dt><b>random(</b>[&lt;expression&gt;, &hellip;]<b>)</b><a name="f_random" href="#f_random"></a>
<dd>Returns a pseudo random number.

<p>The sequence does not change across compilations and is the same every time.
Different sequences can be generated by seeding with <a href="#d_seed"><code>.seed</code></a>.</p>

<div><table border="0">
<caption>Random function invocation types</caption>
<tr><td>floating point number <code><span>0.0</span> &lt;= <u>x</u> &lt; <span>1.0</span></code><td><code><span class="k">random</span>()</code>
<tr><td>integer in range of <code><span>0</span> &lt;= <u>x</u> &lt; <u>e</u></code><td><code><span class="k">random</span>(<u>e</u>)</code>
<tr><td>integer in range of <code><u>s</u> &lt;= <u>x</u> &lt; <u>e</u></code><td><code><span class="k">random</span>(<u>s</u>, <u>a</u>)</code>
<tr><td>integer in range of <code><u>s</u> &lt;= <u>x</u> &lt; <u>e</u></code>, step <code><u>t</u></code><td><code><span class="k">random</span>(<u>s</u>, <u>a</u>, <u>t</u>)</code>
</table></div>
<pre>
        <b class="k">.seed</b> <span>1234</span>      <i>; default is boring, seed the generator</i>
        <b class="d">.byte</b> <span class="k">random</span>(<span>256</span>)<i>; a pseudo random byte (0&ndash;255)</i>
        <b class="d">.byte</b> <span class="k">random</span>([<span>16</span>] x <span>8</span>)<i>; 8 pseudo random bytes (0&ndash;15)</i>
</pre></dd>

<dt><b>range(</b>&lt;expression&gt;[, &lt;expression&gt;, &hellip;]<b>)</b><a name="f_range" href="#f_range"></a>
<dd>Returns a list of integers in a range, with optional stepping.

<div><table border="0">
<caption>Range function invocation types</caption>
<tr><td>integers from <code><span>0</span></code> to <code><u>e</u>-<span>1</span></code><td><code><span class="k">range</span>(<u>e</u>)</code>
<tr><td>integers from <code><u>s</u></code> to <code><u>e</u>-<span>1</span></code><td><code><span class="k">range</span>(<u>s</u>, <u>a</u>)</code>
<tr><td>integers from <code><u>s</u></code> to <code><u>e</u></code> (not including <code><u>e</u></code>), step <code><u>t</u></code><td><code><span class="k">range</span>(<u>s</u>, <u>a</u>, <u>t</u>)</code>
</table></div>

<pre>
        <b class="d">.byte</b> <span class="k">range</span>(<span>16</span>) <i>; 0, 1, ..., 14, 15</i>
        <b class="d">.char</b> <span class="k">range</span>(<span>-5</span>, <span>6</span>)<i>; -5, -4, ..., 4, 5</i>
mylist  <b>=</b> <span class="k">range</span>(<span>10</span>, <span>0</span>, <span>-2</span>)<i>; [10, 8, 6, 4, 2]</i>
</pre></dd>

<dt><b>repr(</b>&lt;expression&gt;<b>)</b><a name="f_repr" href="#f_repr"></a>
<dd>Returns a string representation of value.
<pre>
        <b class="k">.warn</b> <span class="k">repr</span>(<u>var</u>) <i>; pretty print value, for debugging</i>
</pre></dd>

<dt><b>size(</b>&lt;expression&gt;<b>)</b><a name="f_size" href="#f_size"></a>
<dd>Returns the size of code, structure or union in bytes.
<pre>
var     <b class="d">.word</b> <span>0</span>, <span>0</span>, <span>0</span>
        <b>ldx</b> #<span class="k">size</span>(<u>var</u>)  <i>; 6 bytes</i>
var2    <b>=</b> <u>var</u> + <span>2</span>       <i>; start 2 bytes later</i>
        <b>ldx</b> #<span class="k">size</span>(<u>var2</u>) <i>; what remains is 4 bytes</i>
</pre></dd>

<dt><b>sort(</b>&lt;list expression&gt;<b>)</b><a name="f_sort" href="#f_sort"></a>
<dd>Returns a sorted list or tuple.

<p>If the original list contains further lists then these must
be all of the same length. In this case the order of lists is determined by
comparing their elements from the start until a difference is found. The sort is stable.</p>

<pre>
<i>; sort IRQ routines by their raster lines</i>
sorted  <b>=</b> <span class="k">sort</span>([(<span>60</span>, <u>irq1</u>), (<span>50</span>, <u>irq2</u>)])
lines   <b class="d">.byte</b> <u>sorted</u>[:, <span>0</span>] <i>; 50, 60</i>
irqs    <b class="d">.addr</b> <u>sorted</u>[:, <span>1</span>] <i>; irq2, irq1</i>
</pre>

</dl>

<h3>Expressions<a name="expressions" href="#expressions"></a></h3>

<h4>Operators<a name="operators" href="#operators"></a></h4>

<p>The following operators are available. Not all are defined for all types of
arguments and their meaning might slightly vary depending on the type.

<div><table width="100%" border="0">
<caption>Unary operators</caption>
<tr><td width="6%"><code>-</code><td width="44%">negative
<td width="6%"><code>+</code><td width="44%">positive
<tr><td><code>!</code><td>not
<td><code>~</code><td>invert
<tr><td><code>*</code><td>convert to arguments
<td><code>^</code><td><i>decimal string</i>
</table></div>

<p><b>The <q><code>^</code></q> decimal string operator will be changed to mean the
bank byte soon. Please update your sources to use <code>format("%d", xxx)</code> instead!</b>
This is done to be in line with it's use in most other assemblers.

<div><table width="100%" border="0">
<caption>Binary operators</caption>
<tr><td width="6%"><code>+</code><td width="44%">add
<td width="6%"><code>-</code><td width="44%">subtract
<tr><td><code>*</code><td>multiply
<td><code>/</code><td>divide
<tr><td><code>%</code><td>modulo
<td><code>**</code><td>raise to power
<tr><td><code>|</code><td>binary or
<td><code>^</code><td>binary xor
<tr><td><code>&amp;</code><td>binary and
<td><code>&lt;&lt;</code><td>shift left
<tr><td><code>&gt;&gt;</code><td>shift right
<td><code>.</code><td>member
<tr><td><code>..</code><td>concat
<td><code>x</code><td>repeat
<tr><td><code>in</code><td>contains
<td><code>!in</code><td>excludes
</table></div>

<p>Spacing must be used for the <q><code>x</code></q> and <q><code>in</code></q> operators or else they won't
be recognized as such. For example the expression <q><code>[1,2]x2</code></q> should be written as <q><code>[1,2]x 2</code></q> instead.

<p>Parenthesis (<code>( )</code>) can be used to override operator precedence.
Don't forget that they also denote indirect addressing mode for certain
opcodes.

<pre>
        <b>lda</b> #(<span>4</span>+<span>2</span>)*<span>3</span>
</pre>

<h4>Comparison operators<a name="comparison" href="#comparison"></a></h4>

<p>Traditional comparison operators give false or true depending on the result.

<p>The compare operator (<code>&lt;=&gt;</code>) gives &minus;1 for less, 0 for equal and 1 for more.

<div><table width="100%" border="0">
<caption>Comparison operators</caption>
<tr><td width="6%"><code>&lt;=&gt;</code><td width="44%">compare
<td width="6%">&nbsp;<td width="44%">&nbsp;
<tr><td><code>==</code><td>equals
<td><code>!=</code><td>not equal
<tr><td><code>&lt;</code><td>less than
<td><code>&gt;=</code><td>more than or equals
<tr><td><code>&gt;</code><td>more than
<td><code>&lt;=</code><td>less than or equals
<tr><td><code>===</code><td>identical
<td><code>!==</code><td>not identical
</table></div>

<h4>Bit string extraction operators<a name="bitstringextractor" href="#bitstringextractor"></a></h4>

<p>These unary operators extract 8 or 16&nbsp;bits. Usually they are used to get
parts of a memory address.

<div><table width="100%" border="0">
<caption>Bit string extraction operators</caption>
<tr><td width="6%"><code>&lt;</code><td width="44%">lower byte
<td width="6%"><code>&gt;</code><td width="44%">higher byte
<tr><td><code>&lt;&gt;</code><td>lower word
<td><code>&gt;`</code><td>higher word
<tr><td><code>&gt;&lt;</code><td>lower byte swapped word
<td><code>`</code><td>bank byte
</table></div>

<pre>
        <b>lda</b> #&lt;<u>label</u>     <i>; low byte of address</i>
        <b>ldy</b> #&gt;<u>label</u>     <i>; high byte of address</i>
        <b>jsr</b> <span>$ab1e</span>

        <b>ldx</b> #&lt;&gt;<u>source</u>   <i>; word extraction</i>
        <b>ldy</b> #&lt;&gt;<u>dest</u>
        <b>lda</b> #<span class="k">size</span>(<u>source</u>)-<span>1</span>
        <b>mvn</b> #`<u>source</u>, #`<u>dest</u><i>; bank extraction</i>
</pre>

<p>Please note that these prefix operators are not strongly binding like
negation or inversion. Instead they apply to the whole expression to the right.
This may be unexpected but is required for compatibility with old sources which
expect this behaviour.

<pre>
        <b>lda</b> #&lt;<u>label</u>+<span>10</span>  <i>;This is &lt;(label+10) and not (&lt;label)+10</i>

<i>;The check below is wrong and should be written as (&gt;start) != (&gt;end)</i>
        <b class="k">.cerror</b> &gt;<u>start</u> != &gt;<u>end</u><i>;Effectively this is &gt;(start != (&gt;end))</i>
</pre>

<h4>Conditional operators<a name="conditionals" href="#conditionals"></a></h4>

<p>Boolean conditional operators give false or true or one of the
operands as the result.

<div><table border="0">
<caption>Logical and conditional operators</caption>
<tr><td width="80"><code><u>x</u> || <u>y</u></code><td>if <code><u>x</u></code> is true then <code><u>x</u></code> otherwise <code><u>y</u></code>
<tr><td><code><u>x</u> ^^ <u>y</u></code><td>if both false or true then <code><span>false</span></code> otherwise <code><u>x</u> || <u>y</u></code>
<tr><td><code><u>x</u> &amp;&amp; <u>y</u></code><td>if <code><u>x</u></code> is true then <code><u>y</u></code> otherwise <code><u>x</u></code>
<tr><td><code>!<u>x</u></code><td>if <code><u>x</u></code> is true then <code><span>false</span></code> otherwise <code><span>true</span></code>
<tr><td><code><u>c</u>&nbsp;?&nbsp;<u>x</u>&nbsp;:&nbsp;<u>y</u></code><td>if <code><u>c</u></code> is true then <code><u>x</u></code> otherwise <code><u>y</u></code>
<tr><td><code><u>c</u>&nbsp;??&nbsp;<u>x</u>&nbsp;:&nbsp;<u>y</u></code><td>if <code><u>c</u></code> is true then <code><u>x</u></code> otherwise <code><u>y</u></code> (broadcasting)
<tr><td><code><u>x</u>&nbsp;&lt;?&nbsp;<u>y</u></code><td>if <code><u>x</u></code> is smaller then <code><u>x</u></code> otherwise <code><u>y</u></code>
<tr><td><code><u>x</u>&nbsp;&gt;?&nbsp;<u>y</u></code><td>if <code><u>x</u></code> is greater then <code><u>x</u></code> otherwise <code><u>y</u></code>
</table></div>

<pre>
<i>;Silly example for 1=&gt;"simple", 2=&gt;"advanced", else "normal"</i>
        <b class="d">.text</b> <u>MODE</u> == <span>1</span> &amp;&amp; <span class="s">"simple"</span> || <u>MODE</u> == <span>2</span> &amp;&amp; <span class="s">"advanced"</span> || <span class="s">"normal"</span>
        <b class="d">.text</b> <u>MODE</u> == <span>1</span> ? <span class="s">"simple"</span> : <u>MODE</u> == <span>2</span> ? <span class="s">"advanced"</span> : <span class="s">"normal"</span>
<i>;Limit result to 0 .. 8</i>
light   <b class="d">.byte</b> <span>0</span> &gt;? <span class="k">range</span>(<span>-16</span>, <span>101</span>)/<span>6</span> &lt;? <span>8</span>
</pre>

<p>Please note that these are not short circuiting operations and both sides are
calculated even if thrown away later.

<p>With the <q><a href="#o_Wstrict-bool"><code>-Wstrict-bool</code></a></q> command line option
booleans are required as arguments and only the <q><code>?</code></q> operator may return something else.

<h4>Address length forcing<a name="addresslength" href="#addresslength"></a></h4>

<p>Special addressing length forcing operators in front of an expression can be
used to make sure the expected addressing mode is used. Only applicable when used
directly at the mnemonic.

<div><table border="0">
<caption>Address size forcing</caption>
<tr><td width="80"><code>@b</code><td>to force 8 bit address
<tr><td><code>@w</code><td>to force 16 bit address
<tr><td><code>@l</code><td>to force 24 bit address (65816)
</table></div>

<pre>
        <b>lda</b> @w <span>$0000</span>    <i>; force the use of 2 byte absolute addressing</i>
        <b>bne</b> @b <u>label</u>    <i>; prevent upgrade to beq+jmp with long branches in use</i>
        <b>lda</b> @w #<span>$00</span>     <i>; use 2 bytes independent of accumulator size</i>
</pre>

<h4>Compound assignment<a name="compound" href="#compound"></a></h4>

<p>These assignment operators are short hands for updating variables.
Constants can't be changed of course.

<p>The variables on the left must be defined beforehand by
<q><code>:=</code></q> or <q><a href="#d_var"><code>.var</code></a></q>.

<p>Compound assignment operators can modify variables defined in parent
scopes as well.

<div><table width="100%" border="0">
<caption>Compound assignments</caption>
<tr><td width="6%"><code>+=</code><td width="44%">add
<td width="6%"><code>-=</code><td width="44%">subtract
<tr><td><code>*=</code><td>multiply
<td><code>/=</code><td>divide
<tr><td><code>%=</code><td>modulo
<td><code>**=</code><td>raise to power
<tr><td><code>|=</code><td>binary or
<td><code>^=</code><td>binary xor
<tr><td><code>&amp;=</code><td>binary and
<td><code>||=</code><td>logical or
<tr><td><code>&amp;&amp;=</code><td>logical and
<td><code>&lt;&lt;=</code><td>shift left
<tr><td><code>&gt;&gt;=</code><td>shift right
<td><code>..=</code><td>concat
<tr><td><code>&lt;?=</code><td>smaller
<td><code>&gt;?=</code><td>greater
<tr><td><code>x=</code><td>repeat
<td><code>.=</code><td>member
</table></div>

<pre>
v       <b>+=</b> <span>1</span>            <i>; same as 'v ::= v + 1'</i>
</pre>

<h4>Slicing and indexing<a name="slicing_indexing" href="#slicing_indexing"></a></h4>

<p>Lists, character strings, byte strings and bit strings support various
slicing and indexing possibilities through the <code>[]</code> operator.

<p>Indexing elements with positive integers is zero based. Negative indexes
are transformed to positive by adding the number of elements to them, therefore
&minus;1 is the last element. Indexing with list of integers is possible as well so
<code>[1, 2, 3][(-1, 0, 1)]</code> is <code>[3, 1, 2]</code>.

<p>Slicing is an operation when parts of sequence is extracted from a start
position to an end position with a step value. These parameters are separated
with colons enclosed in square brackets and are all optional. Their default
values are <code>[start:maximum:step=1]</code>. Negative start and end characters are
converted to positive internally by adding the length of string to them.
Negative step operates in reverse direction, non-single steps will jump over
elements.

<p>This is quite powerful and therefore a few examples will be given here:</p>

<dl>
<dt>Positive indexing <code>a[x]</code>
<dd>It'll simply extracts a numbered element. It is zero based, therefore
<code>"abcd"[1]</code> results in <code>"b"</code>.</dd>
<dt>Negative indexing <code>a[-x]</code>
<dd>This extracts an element counted from the end, &minus;1 is the last one. So <code>"abcd"[-2]</code> results in <code>"c"</code>.</dd>
<dt>Cut off end <code>a[:to]</code>
<dd>Extracts a continuous range stopping before <q>to</q>. So <code>[10,20,30,40][:-1]</code> results in <code>[10,20,30]</code>.</dd>
<dt>Cut off start <code>a[from:]</code>
<dd>Extracts a continuous range starting from <q>from</q>. So <code>[10,20,30,40][-2:]</code> results in <code>[30,40]</code>.</dd>
<dt>Slicing <code>a[from:to]</code>
<dd>Extracts a continuous range starting from element <q>from</q> and stopping
before <q>to</q>. The two end positions can be positive or negative indexes. So
<code>[10,20,30,40][1:-1]</code> results in <code>[20,30]</code>.</dd>
<dt>Everything <code>a[:]</code>
<dd>Giving no start or end will cover everything and therefore results in a complete copy.</dd>
<dt>Reverse <code>a[::-1]</code>
<dd>This gives everything in reverse, so <code>"abcd"[::-1]</code> is <code>"dcba"</code>.</dd>
<dt>Stepping through <code>a[from:to:step]</code>
<dd>Extracts every <q>step</q>th element starting from <q>from</q> and stopping
before <q>to</q>. So <code>"abcdef"[1:4:2]</code> results in <code>"bd"</code>.
The <q>from</q> and <q>to</q> can be omitted in case it starts from the
beginning or end at the end. If the <q>step</q> is negative then it's done in reverse.</dd>
<dt>Extract multiple elements <code>a[list]</code>
<dd>Extract elements based on a list. So <code>"abcd"[[1,3]]</code> will be <code>"bd"</code>.</dd>
</dl>

<p>The fun start with nested lists and tuples, as these can be used to create a matrix. The
examples will be given for a two dimensional matrix for easier understanding,
but this also works in higher dimensions.</p>

<dl>
<dt>Extract row <code>a[x]</code>
<dd>Given a <code>[(1,2),(3,4)]</code> matrix <code>[0]</code> will give the first row which is <code>(1,2)</code></dd>
<dt>Extract row range <code>a[from:to]</code>
<dd>Given a <code>[(1,2),(3,4),(5,6),(7,8)]</code> matrix <code>[1:3]</code> will give <code>[(3,4),(5,6)]</code></dd>
<dt>Extract column <code>a[x]</code>
<dd>Given a <code>[(1,2),(3,4)]</code> matrix <code>[:,0]</code> will give the first column of all rows which is <code>[1,3]</code></dd>
<dt>Extract column range <code>a[:,from:to]</code>
<dd>Given a <code>[(1,2,3,4),(5,6,7,8)]</code> matrix <code>[:,1:3]</code> will give <code>[(2,3),(6,7)]</code></dd>
</dl>

<p>And it works for list of indexes, negative indexes, stepped ranges,
reversing, etc. on all axes in too many ways to show all possibilities.

<p>Basically it's just the indexing and slicing applied on nested
constructs, where each nesting level is separated by a comma.</p>

<hr>
<h2>Compiler directives<a name="compiler-directives" href="#compiler-directives"></a></h2>

<h3>Controlling the compile offset and program counter<a name="program-counter" href="#program-counter"></a></h3>

<p>Two counters are used while assembling.

<p>The compile offset is where the data and code ends up in memory (or in image file).

<p>The program counter is what labels get set to and what the special star
label refers to.

<p>Normally both are the same (code is compiled to the location it runs from)
but it does not need to be.</p>

<dl class="dir">
<dt><b>*=</b> &lt;expression&gt;<a name="d_star" href="#d_star"></a>
<dd>The compile offset is adjusted so that the program counter
will match the requested address in the expression.

<pre>
<i>;Offset ;PC     ;Hex            ;Monitor        ;Source</i>
                                                *       <b>=</b> <span>$0800</span>
.0800                                           label1
                                                        <b class="k">.logical</b> <span>$1000</span>
.0800   1000                                    label2
                                                *       = <span>$1200</span>
.0a00   1200                                    label3
                                                        <b class="k">.endlogical</b>
.0a00                                           label4
</pre></dd>

<dt><b>.offs</b> &lt;expression&gt;<a name="d_offs" href="#d_offs"></a>
<dd>Sets the compile offset relative to the program counter.

<p>Popular in old TASM code where this was the only way to create
relocated code, otherwise it's use is not recommended as there are easier
to use alternatives below.</p>

<pre>
<i>;Offset ;PC     ;Hex            ;Monitor        ;Source</i>
                                                *       <b>=</b> <span>$1000</span>
.1000           ea              nop                     <b>nop</b>
                                                        <b class="k">.offs</b> <span>100</span>
.1065   1001    ea              nop                     <b>nop</b>
</pre></dd>

<dt><b>.logical</b> &lt;expression&gt;<a name="d_logical" href="#d_logical"></a>
<dd>Starts a relocation block</dd>
<dt><b>.here</b><a name="d_here" href="#d_here"></a>
<dt><b>.endlogical</b><a name="d_endlogical" href="#d_endlogical"></a>
<dd>Ends a relocation block

<p>Changes the program counter only, the compile offset is not changed. When finished all continues where it was left off before.</p>

<p>The naming is not logical at all for relocated code, but that's how it was named in old 6502tass.</p>

<p>It's used for code copied to it's proper location at runtime. Can be nested of course.</p>

<pre>
<i>;Offset ;PC     ;Hex            ;Monitor        ;Source</i>
                                                *       <b>=</b> <span>$1000</span>
                                                        <b class="k">.logical</b> <span>$300</span>
.1000   0300     a9 80          lda #$80        drive   <b>lda</b> #<span>$80</span>
.1002   0302     85 00          sta $00                 <b>sta</b> <span>$00</span>
.1004   0304     4c 00 03       jmp $0300               <b>jmp</b> <u>drive</u>
                                                        <b class="k">.endlogical</b>
</pre></dd>

<dt><b>.virtual</b> [&lt;expression&gt;]<a name="d_virtual" href="#d_virtual"></a>
<dd>Starts a virtual block</dd>
<dt><b>.endv</b><a name="d_endv" href="#d_endv"></a>
<dt><b>.endvirtual</b><a name="d_endvirtual" href="#d_endvirtual"></a>
<dd>Ends a virtual block

<p>Changes the program counter to the expression (if given) and discards the result of compilation.
This is useful to define structures to fixed addresses.</p>

<pre>
        <b class="k">.virtual</b> <span>$d400</span>  <i>; base address</i>
sid     <b class="k">.block</b>
freq    <b class="d">.word</b> <span>?</span>         <i>; frequency</i>
pulsew  <b class="d">.word</b> <span>?</span>         <i>; pulse width</i>
control <b class="d">.byte</b> <span>?</span>         <i>; control</i>
ad      <b class="d">.byte</b> <span>?</span>         <i>; attack/decay</i>
sr      <b class="d">.byte</b> <span>?</span>         <i>; sustain/release</i>
        <b class="k">.endblock</b>
        <b class="k">.endvirtual</b>
</pre>

<p>Or to define stack "allocated" variables on 65816.</p>

<pre>
        <b class="k">.virtual</b> #<span>1</span>,s
p1      <b class="d">.addr</b> <span>?</span>         <i>; at #1,s</i>
tmp     <b class="d">.byte</b> <span>?</span>         <i>; at #3,s</i>
        <b class="k">.endvirtual</b>
        <b>lda</b> (<u>p1</u>),y      <i>; lda ($01,s),y</i>
</pre></dd>
</dl>

<h3>Aligning data or code<a name="alignment" href="#alignment"></a></h3>

<p>Alignment is about constraining data/code placement in memory. 

<p>The processor architecture doesn't have hard constraints on instruction or
data placement still pages (256 bytes) come up quite often in instruction cycle
times tables. Or even in errata like the indirect JMP bug which happens only
if the word of the vector is crossing such page.

<p>Other components like video chips can only display object if placed at an
address divisible by 64 for example.

<p>For code half of an address table might be spared if it's known that all the
addresses have the same high bytes. Or if all interrupt routines are on the
same page then it's enough to change the low byte of the vector when selecting
another one.

<p>Now it shouldn't come as a surprise that the following directives are mainly
concerned about how dividing the program counter address gives a certain remainder.

<p>The divisor in this context is called the alignment interval and is
usually a number which is a power of two. Quite often 256, so that's the
default.

<p>The remainder is called offset and is by default 0. Negative offsets are a
convenience feature and are internally corrected by adding the interval to it.

<p>An interval sized memory area is called a page. It's boundary is at it's
start. If data spans more than one page it's known as a page boundary cross.

<p>Having a non-zero offset effectively shifts the boundary of a page in memory
further up or down (if negative). An interval of 256 with offset of 8 gives page
boundaries of <code>$1008</code>, <code>$1108</code> or <code>$1208</code> for
example.

<p>If the alignment is not good enough some alignment directives might try to
correct it by adding padding. This is by default <a
href="#uninitialized">uninitialized</a> (skip forward) but may be a fixed byte
or anything more complex similarly to what the <a
href="#d_fill"><code>.fill</code></a> directive accepts.

<p>When alignment is done within named structures then it's relative to the start
of the structure. This means the structure layout will always be the same
independent of which address it's instantiated at. Anonymous structures do not
change the way the alignment works.

<p>The <q><a href="#o_Walign"><code>-Walign</code></a></q> command line option can be used to emit
warnings on where and how much padding was necessary for alignment.</p>

<dl class="dir">
<dt><b>.page</b> [&lt;interval&gt;[, &lt;offset&gt;]]<a name="d_page" href="#d_page"></a>
<dd>Start of page check block</dd>
<dt><b>.endp</b><a name="d_endp" href="#d_endp"></a>
<dt><b>.endpage</b><a name="d_endpage" href="#d_endpage"></a>
<dd>End of page check block

<p>This directive is a passive assertion and checks for a page difference or page
crossing.

<p>By default or with a negative interval parameter it verifies that the
start and end directives are on the same page. This is what's needed to guard
relative branches against jumping across pages:</p>

<pre>
        <b>ldx</b> #<span>3</span>
        <b class="k">.page</b>           <i>;now this will execute</i>
-       <b>dex</b>             <i>;in 14 cycles for sure</i>
        <b>bne</b> <u>-</u>
        <b class="k">.endpage</b>
</pre>

<p>With a positive size parameter it verifies that there's no page cross in the
memory range between the directives. This is what's needed to guard against
indexed access page cross cycle penalties:</p>

<pre>
*       <b>=</b> <span>$10c0</span>
        <b class="k">.page</b> <span>256</span>
table   <b class="d">.fill</b> <span>$40</span>       <i>;table within the same page</i>
        <b class="k">.endpage</b>        <i>;different page here but no crossing</i>
</pre>

<p>Normally a page check results in an error but the <q><a
href="#o_Wpage"><code>-Wno-error=page</code></a></q> command line option can
reduce it into a warning.

<p>Once this directive reports an error it's time to rearrange the source in
a way that the check passes. Or alternatively the alignment
directives below can be used to avoid violating the assertion.</p></dd>

<dt><b>.align</b> [&lt;interval&gt;[, &lt;fill&gt;[, &lt;offset&gt;]]]<a name="d_align" href="#d_align"></a>
<dd>Align the program counter to a page boundary

<p>This directive is useful when code/data needs to be placed exactly to a page
boundary. If that's not already the case sufficient padding is added until the
next one is reached.</p>

<pre>
        <b class="k">.align</b> <span>$40</span>      <i>;sprite bitmap (64 byte aligned)</i>
sprite  <b class="d">.fill</b> <span>63</span>
        <b class="k">.align</b> <span>$400</span>     <i>;screen memory (1024 byte aligned)</i>
screen  <b class="d">.fill</b> <span>1000</span>
        <b class="k">.align</b> <span>$400</span>, <span>?</span>, <span>-8</span><i>;sprite pointers (last 8 bytes)</i>
spritep <b class="d">.fill</b> <span>8</span>
        <b class="k">.align</b>          <i>; page sized buffer at page boundary</i>
sendbuf <b class="d">.fill</b> <span>256</span>       <i>;to avoid indexing penalty cycles</i>
</pre></dd>

<dt><b>.alignblk</b> [&lt;interval&gt;[, &lt;fill&gt;[, &lt;offset&gt;]]]<a name="d_alignblk" href="#d_alignblk"></a>
<dd>Starts alignment block.</dd>
<dt><b>.endalignblk</b><a name="d_endalignblk" href="#d_endalignblk"></a>
<dd>Ends alignment block.

<p>Often the start address is not important only avoiding the page boundary matters.

<p>This often can be achieved without any padding at all. If padding is necessary then this directive works
the same as <a href="#d_align"><code>.align</code></a> including alignment within structures.

<p>It's typically used to place tables so that absolute indexed read accesses
won't suffer page crossing cycle penalties.</p>

<pre>
        <b class="k">.alignblk</b>       <i>;avoid page cross</i>
table   <b class="d">.byte</b> <span>0</span>, <span>1</span>, <span>2</span>, <span>3</span>, <span>4</span>, <span>5</span>, <span>6</span>, <span>7</span>
        <b class="k">.endalignblk</b>
        <b>lda</b> <u>table</u>,x     <i>;no cycles wasted on access</i>
</pre>

<p>In case the stronger guarantee of having both the start and the end directives in
the same page is required then the alignment interval needs to be given as a negative number (e.g. &minus;256).
This may be necessary for aligning code with relative branches.

<p>If the block size varies based on its memory location then doing the
alignment may become impossible.</p></dd>

<dt><b>.alignpageind</b> &lt;target&gt;[, &lt;interval&gt;[, &lt;fill&gt;[, &lt;offset&gt;]]]<a name="d_alignpageind" href="#d_alignpageind"></a>
<dd>Alignment of a page block indirectly.

<p>Using <a href="#d_alignblk"><code>.alignblk</code></a> in the middle of
executable code is usually problematic as the alignment is done there as well.
This directive can do the alignment padding outside of the execution flow.

<pre>
        <b>rts</b>
        <b class="k">.alignpageind</b> <u>pageblk</u><i>;add alignment padding here</i>
wait    <b>ldx</b> #<span>3</span>
pageblk <b class="k">.page</b>           <i>;now this will execute</i>
-       <b>dex</b>             <i>;in 14 cycles for sure</i>
        <b>bne</b> <u>-</u>
        <b class="k">.endpage</b>
</pre>

<p>By default and with a negative interval it tries to avoids page differences.
With positive intervals page crosses. Same as the <a
href="#d_page"><code>.page</code></a> assertion block.

<p>It is assumed that the padding inserted will move the target block
as if it'd be right in front of it. If this isn't the case the alignment
will fail.</p>

<p>If the block size varies based on its memory location then doing the
alignment may become impossible.</p></dd>

<dt><b>.alignind</b> &lt;target&gt;[, &lt;interval&gt;[, &lt;fill&gt;[, &lt;offset&gt;]]]<a name="d_alignind" href="#d_alignind"></a>
<dd>Align the target location to a page boundary indirectly

<p>This directive tries to align the target to a page boundary. If not already
on one then sufficient padding will be added until the next one is
reached. 

<pre>
<i>;Align "pos" to page boundary. It must come right after "neg".</i>
        <b class="k">.alignind</b> <u>pos</u>
neg     <b class="d">.fill</b> <span>8</span>
pos     <b class="d">.fill</b> <span>8</span>
        <b class="k">.cerror</b> (&lt;<u>pos</u>) != <span>0</span>, <span class="s">"pos should be page aligned"</span>
        <b class="k">.cerror</b> <u>pos</u> - <u>neg</u> != size(<u>neg</u>), <span class="s">"there should be no gap"</span>
</pre>

<p>It is assumed that the padding inserted will move the target
as if it'd be right in front of it. If this isn't the case the alignment
will fail.</p></dd>

<dt><b>.fill</b> &lt;length&gt;
<dd>Usually the <a href="#d_fill"><code>.fill</code></a> directive is used to
reserve space but it may be useful to do alignments as well.

<pre>
<i>;replacement for a .cerror overrun check and *= combo</i>
        <b class="d">.fill</b> <u>start_address</u> - <u>*</u>
<i>;align the vectors "block" so it ends at end_address</i>
        <b class="d">.fill</b> <u>end_address</u> - size(<u>vectors</u>) - <u>*</u>
vectors <b class="k">.logical</b> <u>*</u>      <i>;dummy non-scoped block for size()</i>
...
<i>;screen memory is needed but if at $9xxx then take $a000 instead</i>
        <b class="k">.align</b> <span>$400</span>     <i>;next 1024 byte alignment</i>
        <b class="d">.fill</b> (<u>*</u> &gt;&gt; <span>12</span>) == <span>$9</span> ? (<span>$a000</span> - <u>*</u>) : <span>0</span>
screen  <b class="d">.fill</b> <span>1000</span>
</pre></dd>

</dl>

<h3>Dumping data<a name="data-dumping" href="#data-dumping"></a></h3>

<h4>Storing numeric values<a name="data-numeric" href="#data-numeric"></a></h4>

<p>Multi byte numeric data is stored in the little-endian order, which is the
natural byte order for 65xx processors. Numeric ranges are enforced depending
on the directives used. Signed numbers are stored as two's complement.

<p>When using lists or tuples their content will be used one by one.
Uninitialized data (<q><a href="#uninitialized"><code>?</code></a></q>) creates holes of different sizes. Character string constants
are converted using the current encoding.

<p>Please note that multi character strings usually don't fit into 8&nbsp;bits
and therefore the <a href="#d_byte"><code>.byte</code></a> directive is not appropriate for them.
Use <a href="#d_text"><code>.text</code></a> instead which accepts strings of any length.</p>

<dl class="dir">
<dt><b>.byte</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_byte" href="#d_byte"></a>
<dd>Create bytes from 8&nbsp;bit unsigned constants (0&ndash;255)</dd>
<dt><b>.char</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_char" href="#d_char"></a>
<dd>Create bytes from 8&nbsp;bit signed constants (&minus;128&ndash;127)

<pre>
&gt;1000  ff 03                             <b class="d">.byte</b> <span>255</span>, <span>$03</span>
&gt;1002  41                                <b class="d">.byte</b> <span class="s">"a"</span>
&gt;1003                                    <b class="d">.byte</b> <span>?</span>        <i>; reserve 1 byte</i>
&gt;1004  fd                                <b class="d">.char</b> <span>-3</span>
<i>;Store 4.4 signed fixed point constants</i>
&gt;1005  c8 34 32                          <b class="d">.char</b> (<span>-3.5</span>, <span>3.25</span>, <span>3.125</span>) * <span>1p4</span>
<i>;Compact computed jumps using self modifying code</i>
.1008  bd 0f 10  lda $1010,x             <b>lda</b> <u>jumps</u>,x
.100b  8d 0e 10  sta $100f               <b>sta</b> <u>smod</u>+<span>1</span>
.100e  d0 fe     bne $100e       smod    <b>bne</b> <u>*</u>
<i>;Routines nearby (-128 to 127 bytes)</i>
&gt;1010  23 49                     jumps   <b class="d">.char</b> (<u>routine1</u>, <u>routine2</u>)-<u>smod</u>-<span>2</span>
</pre></dd>

<dt><b>.word</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_word" href="#d_word"></a>
<dd>Create bytes from 16&nbsp;bit unsigned constants (0&ndash;65535)</dd>
<dt><b>.sint</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_sint" href="#d_sint"></a>
<dd>Create bytes from 16&nbsp;bit signed constants (&minus;32768&ndash;32767)

<pre>
&gt;1000  42 23 55 45                       <b class="d">.word</b> <span>$2342</span>, <span>$4555</span>
&gt;1004                                    <b class="d">.word</b> <span>?</span>        <i>; reserve 2 bytes</i>
&gt;1006  eb fd 51 11                       <b class="d">.sint</b> <span>-533</span>, <span>4433</span>
<i>;Store 8.8 signed fixed point constants</i>
&gt;100a  80 fc 40 03 20 03                 <b class="d">.sint</b> (<span>-3.5</span>, <span>3.25</span>, <span>3.125</span>) * <span>1p8</span>
.1010  bd 19 10  lda $1019,x             <b>lda</b> <u>texts</u>,x
.1013  bc 1a 10  ldy $101a,x             <b>ldy</b> <u>texts</u>+<span>1</span>,x
.1016  4c 1e ab  jmp $ab1e               <b>jmp</b> <span>$ab1e</span>
&gt;1019  33 10 59 10               texts   <b class="d">.word</b> <u>text1</u>, <u>text2</u>
</pre></dd>

<dt><b>.addr</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_addr" href="#d_addr"></a>
<dd>Create 16&nbsp;bit address constants for addresses (in current program bank)</dd>
<dt><b>.rta</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_rta" href="#d_rta"></a>
<dd>Create 16&nbsp;bit return address constants for addresses (in current program bank)

<pre>
                                        *       <b>=</b> <span>$12000</span>
.012000 7c 03 20        jmp ($012003,x)         <b>jmp</b> (<u>jumps</u>,x)
&gt;012003 50 20 32 03 92 15               jumps   <b class="d">.addr</b> <span>$12050</span>, <u>routine1</u>, <u>routine2</u>
<i>;Computed jumps by using stack (current bank)</i>
                                        *       <b>=</b> <span>$103000</span>
.103000 bf 0c 30 10     lda $10300c,x           <b>lda</b> <u>rets</u>+<span>1</span>,x
.103004 48              pha                     <b>pha</b>
.103005 bf 0b 30 10     lda $10300b,x           <b>lda</b> <u>rets</u>,x
.103009 48              pha                     <b>pha</b>
.10300a 60              rts                     <b>rts</b>
&gt;10300b ff ef a1 36 f3 42               rets    <b class="d">.rta</b> <span>$10f000</span>, <u>routine1</u>, <u>routine2</u>
</pre></dd>

<dt><b>.long</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_long" href="#d_long"></a>
<dd>Create bytes from 24&nbsp;bit unsigned constants (0&ndash;16777215)</dd>
<dt><b>.lint</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_lint" href="#d_lint"></a>
<dd>Create bytes from 24&nbsp;bit signed constants (&minus;8388608&ndash;8388607)

<pre>
&gt;1000   56 34 12                         <b class="d">.long</b> <span>$123456</span>
&gt;1003                                    <b class="d">.long</b> <span>?</span>        <i>; reserve 3 bytes</i>
&gt;1006   eb fd ff 51 11 00                <b class="d">.lint</b> <span>-533</span>, <span>4433</span>
<i>;Store 8.16 signed fixed point constants</i>
&gt;100c   5d 8f fc 66 66 03 1e 85          <b class="d">.lint</b> (<span>-3.44</span>, <span>3.4</span>, <span>3.52</span>) * <span>1p16</span>
&gt;1014   03
<i>;Computed long jumps with jump table (65816)</i>
.1015   bd 2a 10        lda $102a,x      <b>lda</b> <u>jumps</u>,x
.1018   8d 11 03        sta $0311        <b>sta</b> <u>ind</u>
.101b   bd 2b 10        lda $102b,x      <b>lda</b> <u>jumps</u>+<span>1</span>,x
.101e   8d 12 03        sta $0312        <b>sta</b> <u>ind</u>+<span>1</span>
.1021   bd 2c 10        lda $102c,x      <b>lda</b> <u>jumps</u>+<span>2</span>,x
.1024   8d 13 03        sta $0313        <b>sta</b> <u>ind</u>+<span>2</span>
.1027   dc 11 03        jmp [$0311]      <b>jmp</b> [<u>ind</u>]
&gt;102a   32 03 01 92 05 02        jumps   <b class="d">.long</b> <u>routine1</u>, <u>routine2</u>
</pre></dd>

<dt><b>.dword</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_dword" href="#d_dword"></a>
<dd>Create bytes from 32&nbsp;bit unsigned constants (0&ndash;4294967295)</dd>
<dt><b>.dint</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_dint" href="#d_dint"></a>
<dd>Create bytes from 32&nbsp;bit signed constants (&minus;2147483648&ndash;2147483647)

<pre>
&gt;1000   78 56 34 12             <b class="d">.dword</b> <span>$12345678</span>
&gt;1004                           <b class="d">.dword</b> <span>?</span>        <i>; reserve 4 bytes</i>
&gt;1008   5d 7a 79 e7             <b class="d">.dint</b> <span>-411469219</span>
<i>;Store 16.16 signed fixed point constants</i>
&gt;100c   5d 8f fc ff 66 66 03 00 <b class="d">.dint</b> (<span>-3.44</span>, <span>3.4</span>, <span>3.52</span>) * <span>1p16</span>
&gt;1014   1e 85 03 00
</pre></dd>

<dt><b>.text</b> bits(&lt;expression&gt;[, &lt;bit count&gt;])
<dd>Create bytes from arbitrary precision unsigned and signed numbers.</dd>
<dt><b>.text</b> bytes(&lt;expression&gt;[, &lt;byte count&gt;])
<dd>Create bytes from arbitrary precision unsigned and signed numbers.

<p>For cases not covered by the numeric store directives above it's possible to
convert numbers to byte or bit strings and store the resulting string. If the
count expression of <code>bytes()</code> and <code>bits()</code> is negative then the stored number is
signed otherwise unsigned.</p>

<pre>
&gt;1000   74 65 78 74 00 00 00 00 <b class="d">.text</b> <span class="k">bytes</span>(<span class="s">"text"</span>, <span>8</span>)<i>;pad up to 8 bytes</i>
&gt;1008   f4 ff ff ff ff ff ff ff <b class="d">.text</b> <span class="k">bytes</span>(<span>-12</span>, <span>-8</span>)  <i>;8 bytes signed</i>
&gt;1010   00 04 00 00 00 00       <b class="d">.text</b> <span class="k">bits</span>(<span>1024</span>, <span>48</span>)  <i>;48 bits unsigned</i>
&gt;1016   f4 ff ff ff ff ff       <b class="d">.text</b> <span class="k">bits</span>(<span>-12</span>, <span>-48</span>)  <i>;48 bits signed</i>
</pre></dd>

</dl>

<h4>Storing string values<a name="data-text" href="#data-text"></a></h4>

<p>The following directives store strings of characters, bytes or bits as bytes. Small
numeric constants can be mixed in to represent single byte control characters.

<p>When using lists or tuples their content will be used one by one.
Uninitialized data (<q><a href="#uninitialized"><code>?</code></a></q>) creates byte sized holes. Character string constants
are converted using the current encoding.</p>

<dl class="dir">
<dt><b>.text</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_text" href="#d_text"></a>
<dd>Assemble strings into 8&nbsp;bit bytes.

<pre>
&gt;1000   4f 45 d5  <b class="d">.text</b> <span class="s">"oeU"</span>
&gt;1003   4f 45 d5  <b class="d">.text</b> <span class="s">'oeU'</span>
&gt;1006   17 33     <b class="d">.text</b> <span>23</span>, <span>$33</span>  <i>; bytes</i>
&gt;1008   0d 0a     <b class="d">.text</b> <span>$0a0d</span>    <i>; $0d, $0a, little endian!</i>
&gt;100a   1f        <b class="d">.text</b> <span>%00011111</span><i>; more bytes</i>
</pre></dd>

<dt><b>.fill</b> &lt;length&gt;[, &lt;fill&gt;]<a name="d_fill" href="#d_fill"></a>
<dd>Reserve space (using uninitialized data), or fill with repeated bytes.

<pre>
&gt;1000             <b class="d">.fill</b> <span>$100</span>      <i>;no fill, just reserve $100 bytes</i>
&gt;1100   00 00 00  <b class="d">.fill</b> <span>$4000</span>, <span>0</span>  <i>;16384 bytes of 0</i>
...
&gt;5100   55 aa 55  <b class="d">.fill</b> <span>8000</span>, [<span>$55</span>, <span>$aa</span>]<i>;8000 bytes of alternating $55, $aa</i>
...
&gt;7040   ff ff ff  <b class="d">.fill</b> <span>$8000</span> - <u>*</u>, <span>$ff</span><i>;fill up rest of EPROM with $ff</i>
...
</pre></dd>

<dt><b>.shift</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_shift" href="#d_shift"></a>
<dd>Assemble strings of 7&nbsp;bit bytes and mark the last byte by setting it's most significant bit.

<p>Any byte which already has the most significant bit set will cause an error.
The last byte can't be uninitialized or missing of course.</p>

<p>The naming comes from old TASM and is a reference to setting the high bit of alphabetic letters which results in it's uppercase version in PETSCII.</p>

<pre>
.1000   a2 00         ldx #$00                <b>ldx</b> #<span>0</span>
.1002   bd 10 10      lda $1010,x     loop    <b>lda</b> <u>txt</u>,x
.1005   08            php                     <b>php</b>
.1006   29 7f         and #$7f                <b>and</b> #<span>$7f</span>
.1008   20 d2 ff      jsr $ffd2               <b>jsr</b> <span>$ffd2</span>
.100b   e8            inx                     <b>inx</b>
.100c   28            plp                     <b>plp</b>
.100d   10 f3         bpl $1002               <b>bpl</b> <u>loop</u>
.100f   60            rts                     <b>rts</b>
&gt;1010   53 49 4e 47 4c 45 20 53       txt     <b class="d">.shift</b> <span class="s">"single"</span>, <span>32</span>, <span class="s">"string"</span>
&gt;1018   54 52 49 4e c7
</pre></dd>

<dt><b>.shiftl</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_shiftl" href="#d_shiftl"></a>
<dd>Assemble strings of 7&nbsp;bit bytes shifted to the left once with the last byte's least significant bit set.

<p>Any byte which already has the most significant
bit set will cause an error as this is cut off on shifting.
The last byte can't be uninitialized or missing of course.</p>

<p>The naming is a reference to left shifting.</p>

<pre>
.1000   a2 00         ldx #$00                <b>ldx</b> #<span>0</span>
.1002   bd 0d 10      lda $100d,x     loop    <b>lda</b> <u>txt</u>,x
.1005   4a            lsr a                   <b>lsr</b> <b>a</b>
.1006   9d 00 04      sta $0400,x             <b>sta</b> <span>$400</span>,x      <i>;screen memory</i>
.1009   e8            inx                     <b>inx</b>
.100a   90 f6         bcc $1002               <b>bcc</b> <u>loop</u>
.100c   60            rts                     <b>rts</b>
                                              <b class="k">.enc</b> <span class="s">"screen"</span>
&gt;100d   a6 92 9c 8e 98 8a 40 a6       txt     <b class="d">.shiftl</b> <span class="s">"single"</span>, <span>32</span>, <span class="s">"string"</span>
&gt;1015   a8 a4 92 9c 8f                        <b class="k">.enc</b> <span class="s">"none"</span>
</pre></dd>

<dt><b>.null</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_null" href="#d_null"></a>
<dd>Same as <a href="#d_text"><code>.text</code></a>, but adds a zero byte to the end. An existing
zero byte is an error as it'd cause a false end marker.

<pre>
.1000   a9 07         lda #$07                <b>lda</b> #&lt;<u>txt</u>
.1002   a0 10         ldy #$10                <b>ldy</b> #&gt;<u>txt</u>
.1004   20 1e ab      jsr $ab1e               <b>jsr</b> <span>$ab1e</span>
&gt;1007   53 49 4e 47 4c 45 20 53       txt     <b class="d">.null</b> <span class="s">"single"</span>, <span>32</span>, <span class="s">"string"</span>
&gt;100f   54 52 49 4e 47 00
</pre></dd>

<dt><b>.ptext</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]<a name="d_ptext" href="#d_ptext"></a>
<dd>Same as <a href="#d_text"><code>.text</code></a>, but prepend the number of bytes in front of the
string (pascal style string). Therefore it can't do more than 255 bytes.

<pre>
.1000   a9 1d         lda #$1d                <b>lda</b> #&lt;<u>txt</u>
.1002   a2 10         ldx #$10                <b>ldx</b> #&gt;<u>txt</u>
.1004   20 08 10      jsr $1008               <b>jsr</b> <u>print</u>
.1007   60            rts                     <b>rts</b>

.1008   85 fb         sta $fb         print   <b>sta</b> <span>$fb</span>
.100a   86 fc         stx $fc                 <b>stx</b> <span>$fc</span>
.100c   a0 00         ldy #$00                <b>ldy</b> #<span>0</span>
.100e   b1 fb         lda ($fb),y             <b>lda</b> (<span>$fb</span>),y
.1010   f0 0a         beq $101c               <b>beq</b> <u>null</u>
.1012   aa            tax                     <b>tax</b>
.1013   c8            iny             -       <b>iny</b>
.1014   b1 fb         lda ($fb),y             <b>lda</b> (<span>$fb</span>),y
.1016   20 d2 ff      jsr $ffd2               <b>jsr</b> <span>$ffd2</span>
.1019   ca            dex                     <b>dex</b>
.101a   d0 f7         bne $1013               <b>bne</b> <u>-</u>
.101c   60            rts             null    <b>rts</b>
&gt;101d   0d 53 49 4e 47 4c 45 20       txt     <b class="d">.ptext</b> <span class="s">"single"</span>, <span>32</span>, <span class="s">"string"</span>
&gt;1025   53 54 52 49 4e 47
</pre></dd>
</dl>

<h3>Text encoding<a name="text-encoding" href="#text-encoding"></a></h3>

<p>64tass supports sources written in UTF-8, UTF-16 (be/le) and RAW 8&nbsp;bit encoding. To take
advantage of this capability custom encodings can be defined to map Unicode characters
to 8&nbsp;bit values in strings. Even in plain ASCII sources it could be
useful to define escape sequences for control codes.</p>

<dl class="dir">
<dt><b>.enc</b> &lt;expression&gt;<a name="d_enc" href="#d_enc"></a>
<dd>Selects text encoding by a character string name or from an encoding object

<p>Predefined encodings names are <q>none</q> and <q>screen</q> (screen code),
anything else is user defined. All user encodings start without any character
or escape definitions, add some as required. Please note that the encoding names
are global.

<p>This directive changes the text encoding after it therefore it's usually
placed somewhere at the beginning of the source to make sure everything is
covered.

<p>While it is possible to juggle with multiple encodings throughout the source
code using the <code>.enc</code> directive this is not recommended. For such
use case <a href="#d_encode"><code>.encode</code></a> is better suited.</p>

<p>In the past the <code>.enc</code> directive accepted an unquoted string but currently it
needs to be an expression.</p>

<pre>
                                <b class="k">.enc</b> <span class="s">"screen"</span><i>;screen code mode</i>
&gt;1000   13 03 12 05 05 0e 20 03 <b class="d">.text</b> <span class="s">"screen codes"</span>
&gt;1008   0f 04 05 13
.100c   c9 15    cmp #$15       <b>cmp</b> #<span class="s">"u"</span>    <i>;compare screen code</i>
                                <b class="k">.enc</b> <span class="s">"none"</span> <i>;normal mode again</i>
.100e   c9 55    cmp #$55       <b>cmp</b> #<span class="s">"u"</span>    <i>;compare PETSCII</i>
</pre></dd>

<dt><b>.encode</b> [&lt;expression&gt;]<a name="d_encode" href="#d_encode"></a>
<dd>Encoding area start</dd>
<dt><b>.endencode</b><a name="d_endencode" href="#d_endencode"></a>
<dd>Encoding area end

<p>This directive either creates a new text encoding (if used without a
parameter) or makes the one in the parameter effective within the enclosed
area.

<p>The text encoding can be assigned to a symbol in front of the directive so
it can be reused whenever it's needed. This symbol can also act as a conversion
function which converts a character string to a byte string using the encoding.

<pre>
        <b class="k">.encode</b>         <i>;starts anonymous local encoding scope</i>
        <b class="k">.enc</b> <span class="s">"titlefont"</span><i>;special character set</i>
        <b class="d">.text</b> <span class="s">"game title"</span>
        <b class="k">.endencode</b>      <i>;restores original encoding</i>

vt100   <b class="k">.encode</b>         <i>;define custom encoding</i>
        <b class="k">.cdef</b> <span class="s">" ~"</span>, <span>32</span>
        <b class="k">.edef</b> <span class="s">"{esc}"</span>, <span>27</span><i>;add escape codes</i>
        <b class="k">.edef</b> <span class="s">"{moff}"</span>, [<span>27</span>, <span class="s">"["</span>, <span class="s">"m"</span>]
        <b class="k">.edef</b> <span class="s">"{bold}"</span>, [<span>27</span>, <span class="s">"["</span>, <span class="s">"1"</span>, <span class="s">"m"</span>]
        <b class="k">.endencode</b>

        <b class="k">.encode</b> <u>vt100</u>   <i>;use custom encoding from here</i>
        <b class="d">.text</b> <span class="s">"<span>{bold}</span>bold<span>{moff}</span> text"</span>
        <b>lda</b> #<span class="s">"<span>{esc}"</span></span>
        <b class="k">.endencode</b>      <i>;restores original encoding</i>
        <b>cmp</b> #<u>vt100</u>(<span class="s">"<span>{esc}</span>"</span>)<i>;conversion when not in scope</i>
        <b class="k">.enc</b> <u>vt100</u>      <i>;select custom encoding (at start of source)</i>
</pre></dd>

<dt><b>.cdef</b> &lt;start&gt;, &lt;end&gt;, &lt;coded&gt; [, &lt;start&gt;, &lt;end&gt;, &lt;coded&gt;, &hellip;]<a name="d_cdef" href="#d_cdef"></a>
<dt><b>.cdef</b> "&lt;start&gt;&lt;end&gt;", &lt;coded&gt; [, "&lt;start&gt;&lt;end&gt;", &lt;coded&gt;, &hellip;]
<dd>Assigns characters in a range to single bytes.

<p>This is a simple single character to byte translation definition. It's
useful to map a range of Unicode characters to a range of bytes. The start and
end positions are Unicode character codes either by numbers or by typing them.
Overlapping ranges are not allowed.</p>

<pre>
        <b class="k">.enc</b> <span class="s">"ascii"</span>    <i>;define an ascii encoding</i>
        <b class="k">.cdef</b> <span class="s">" ~"</span>, <span>32</span>  <i>;identity mapping for printable</i>
</pre></dd>

<dt><b>.tdef</b> &lt;expression&gt;, &lt;expression&gt; [, &lt;expression&gt;, &lt;expression&gt;, &hellip;]<a name="d_tdef" href="#d_tdef"></a>
<dd>Assign single characters to byte values.

<p>Similar to <a href="#d_cdef"><code>.cdef</code></a> it is a single character to byte translation
definition. It's easier to use when the character codes are not consecutive.
Overlapping ranges with the former and itself are not allowed.

<p>It tries to assign Unicode character codes from the first expression to byte
values from the second. More than one pair of such assignments can be given.

<p>If the byte value expression is not iterable then it will get incremented
for each character definition. This allows easy assignment of randomly
scattered Unicode values to a consecutive range of bytes values.</p>

<pre>
        <b class="k">.tdef</b> <span class="s">"A"</span>, <span>65</span>   <i>;A -> 65</i>
        <b class="k">.tdef</b> <span class="s">"ACX"</span>, <span>65</span> <i>;A -> 65, C-> 66, X -> 67</i>
        <b class="k">.tdef</b> <span class="s">"ACX"</span>, [<span>65</span>, <span>33</span>, <span>11</span>]<i>;A -> 65, C-> 33, X -> 11</i>
</pre></dd>

<dt><b>.edef</b> "&lt;escapetext&gt;", &lt;value&gt; [, "&lt;escapetext&gt;", &lt;value&gt;, &hellip;]<a name="d_edef" href="#d_edef"></a>
<dd>Assigns strings to byte sequences as a translated value.

<p>When these substrings are found in a text they are replaced by bytes defined here.
When strings with common prefixes are used the longest match wins. Useful for defining
non-typeable control code aliases, or as a simple tokeniser.</p>

<pre>
        <b class="k">.edef</b> <span class="s">"\n"</span>, <span>13</span>  <i>;one byte control codes</i>
        <b class="k">.edef</b> <span class="s">"{clr}"</span>, <span>147</span>
        <b class="k">.edef</b> <span class="s">"{crlf}"</span>, [<span>13</span>, <span>10</span>]<i>;two byte control code</i>
        <b class="k">.edef</b> <span class="s">"&lt;nothing&gt;"</span>, []<i>;replace with no bytes</i>
</pre></dd>
</dl>

<p>The example below shows how all this fits together:

<pre>
petscii <b class="k">.namespace</b>
common  <b class="k">.segment</b><i>;common definitions</i>
        <b class="k">.cdef</b> <span class="s">" @"</span>, <span>$20</span><i>;32-64 is identical</i>
        <b class="k">.tdef</b> <span class="s">"[£]↑←"</span>, <span>$5b</span>, <span class="s">"┼🮌🭳"</span>, <span>$db</span>
        <b class="k">.edef</b> <span class="s">"{clr}"</span>, <span>147</span>, <span class="s">"{cr}"</span>, <span>13</span>
        <b class="k">.endsegment</b>
upper   <b class="k">.encode</b><i>;uppercase PETSCII</i>
        <b class="k">#common</b>
        <b class="k">.cdef</b> <span class="s">"AZ"</span>, <span>$41</span>
        <b class="k">.tdef</b> <span class="s">"▌▄▔▁▏▒▕🮏◤🮇├▗└┐▂┌┴┬┤▎▍🮈🮂🮃▃🭿▖▝┘▘▚🭹"</span>, <span>$a1</span>
        <b class="k">.tdef</b> <span class="s">"♠🭲🭸🭷🭶🭺🭱🭴╮╰╯🭼╲╱🭽🭾●🭻♥🭰╭╳○♣🭵♦"</span>, <span>$c1</span>
        <b class="k">.tdef</b> <span class="s">"◥π─│"</span>, [<span>$df</span>, <span>$ff</span>, <span>$c0</span>, <span>$dd</span>]
        <b class="k">.endencode</b>

lower   <b class="k">.encode</b><i>;lowercase PETSCII</i>
        <b class="k">#common</b>
        <b class="k">.cdef</b> <span class="s">"az"</span>, <span>$41</span>, <span class="s">"AZ"</span>, <span>$c1</span><i>;the easy ranges</i>
        <b class="k">.tdef</b> <span class="s">"▌▄▔▁▏▒▕🮏🮙🮇├▗└┐▂┌┴┬┤▎▍🮈🮂🮃▃✓▖▝┘▘▚🭹"</span>, <span>$a1</span>
        <b class="k">.tdef</b> <span class="s">"🮘🮕─│"</span>, [<span>$df</span>, <span>$ff</span>, <span>$c0</span>, <span>$dd</span>]<i>;random one to ones</i>
        <b class="k">.endencode</b>
        <b class="k">.endnamespace</b>

                                    <b class="k">.encode</b> <u>petscii</u>.<u>lower</u>
&gt;1000   93 d4 45 58 54 20 49 4e    <b class="d">.text</b> <span class="s">"<span>{clr}</span>Text in PETSCII<span>{cr}</span>"</span>
&gt;1008   20 d0 c5 d4 d3 c3 c9 c9 0d
                                    <b class="k">.endencode</b>
</pre>

<h3>Structured data<a name="structures" href="#structures"></a></h3>

<p>Structures and unions can be defined to create complex data types. The
offset of fields are available by using the definition's name. The fields
themselves by using the instance name.

<p>The initialization method is very similar to macro parameters, the
difference is that unset parameters always return uninitialized data (<q><a href="#uninitialized"><code>?</code></a></q>)
instead of an error.

<h4>Structure<a name="structure" href="#structure"></a></h4>

<p>Structures are for organizing sequential data, so the length of a structure
is the sum of lengths of all items.</p>

<dl class="dir">
<dt><b>.struct</b> [&lt;name&gt;][=&lt;default&gt;]][, [&lt;name&gt;][=&lt;default&gt;] &hellip;]<a name="d_struct" href="#d_struct"></a>
<dd>Begins a structure block</dd>
<dt><b>.ends</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_ends" href="#d_ends"></a>
<dt><b>.endstruct</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endstruct" href="#d_endstruct"></a>
<dd>Ends a structure block

<p>Structure definition, with named parameters and default values</p></dd>

<dt><b>.dstruct</b> &lt;name&gt;[, &lt;initialization values&gt;]<a name="d_dstruct" href="#d_dstruct"></a>
<dt><b>.&lt;name&gt;</b> [&lt;initialization values&gt;]
<dd>Create instance of structure with initialization values</dd>
</dl>

<pre>
        <b class="k">.struct</b>         <i>;anonymous structure</i>
x       <b class="d">.byte</b> <span>0</span>         <i>;labels are visible</i>
y       <b class="d">.byte</b> <span>0</span>         <i>;content compiled here</i>
        <b class="k">.endstruct</b>      <i>;useful inside unions</i>

nn_s    <b class="k">.struct</b> <u>col</u>, <u>row</u><i>;named structure</i>
x       <b class="d">.byte</b> <span class="k">\col</span>      <i>;labels are not visible</i>
y       <b class="d">.byte</b> <span class="k">\row</span>      <i>;no content is compiled here</i>
        <b class="k">.endstruct</b>      <i>;it's just a definition</i>

nn      <b class="d">.dstruct</b> <u>nn_s</u>, <span>1</span>, <span>2</span><i>;structure instance (within label)</i>

        <b>lda</b> <u>nn</u>.<u>x</u>        <i>;direct field access</i>
        <b>ldy</b> #<u>nn_s</u>.<u>x</u>     <i>;get offset of field</i>
        <b>lda</b> <u>nn</u>,y        <i>;and use it indirectly</i>

nnarray <b class="k">.brept</b> <span>4</span>        <i>;4 element "array" here</i>
        <b class="d">.dstruct</b> <u>nn_s</u>   <i>;fields directly here (without a label)</i>
        <b class="k">.endrept</b>

        <b>lda</b> <u>nnarray</u>[<span>0</span>].<u>y</u><i>;access of "array" field</i>

coords2 <b class="k">.bfor</b> <u>x2</u>, <u>y2</u> <span class="k">in</span> [(<span>1</span>,<span>3</span>),(<span>4</span>,<span>2</span>),(<span>7</span>,<span>5</span>)]
        <b class="d">.dstruct</b> <u>nn_s</u>, <u>x2</u>, <u>y2</u>
        <b class="k">.endfor</b>         <i>;initialized "array" from list</i>
</pre>

<h4>Union<a name="union" href="#union"></a></h4>

<p>Unions can be used for overlapping data as the compile offset and program
counter remains the same on each line. Therefore the length of a union is the
length of it's longest item.</p>

<dl class="dir">
<dt><b>.union</b> [&lt;name&gt;][=&lt;default&gt;]][, [&lt;name&gt;][=&lt;default&gt;] &hellip;]<a name="d_union" href="#d_union"></a>
<dd>Begins a union block</dd>
<dt><b>.endu</b><a name="d_endu" href="#d_endu"></a>
<dt><b>.endunion</b><a name="d_endunion" href="#d_endunion"></a>
<dd>Ends a union block

<p>Union definition, with named parameters and default values</p></dd>

<dt><b>.dunion</b> &lt;name&gt;[, &lt;initialization values&gt;]<a name="d_dunion" href="#d_dunion"></a>
<dt><b>.&lt;name&gt;</b> [&lt;initialization values&gt;]
<dd>Create instance of union with initialization values</dd>
</dl>

<pre>
        <b class="k">.union</b>          <i>;anonymous union</i>
x       <b class="d">.byte</b> <span>0</span>         <i>;labels are visible</i>
y       <b class="d">.word</b> <span>0</span>         <i>;content compiled here</i>
        <b class="k">.endunion</b>

nn_u    <b class="k">.union</b>          <i>;named union</i>
x       <b class="d">.byte</b> <span>?</span>         <i>;labels are not visible</i>
y       <b class="d">.word</b> <span class="k">\1</span>        <i>;no content is compiled here</i>
        <b class="k">.endunion</b>       <i>;it's just a definition</i>

nn      <b class="d">.dunion</b> <u>nn_u</u>, <span>1</span> <i>;union instance here</i>

        <b>lda</b> <u>nn</u>.<u>x</u>        <i>;direct field access</i>
        <b>ldy</b> #<u>nn_u</u>.<u>x</u>     <i>;get offset of field</i>
        <b>lda</b> <u>nn</u>,y        <i>;and use it indirectly</i>
</pre>

<h4>Combined use of structures and unions<a name="struct-and-union" href="#struct-and-union"></a></h4>

<p>The example below shows how to define structure to a binary include.

<pre>
        <b class="k">.union</b>
        <b class="d">.binary</b> <span class="s">"pic.drp"</span>, <span>2</span>
        <b class="k">.struct</b>
color   <b class="d">.fill</b> <span>1024</span>
screen  <b class="d">.fill</b> <span>1024</span>
bitmap  <b class="d">.fill</b> <span>8000</span>
backg   <b class="d">.byte</b> <span>?</span>
        <b class="k">.endstruct</b>
        <b class="k">.endunion</b>
</pre>

<p>Anonymous structures and unions in combination with sections are useful for
overlapping memory assignment. The example below shares zero page allocations
for two separate parts of a bigger program. The common subroutine variables
are assigned after in the <q>zp</q> section.

<pre>
*       <b>=</b> <span>$02</span>
        <b class="k">.union</b>          <i>;spare some memory</i>
         <b class="k">.struct</b>
          <b class="d">.dsection</b> <u>zp1</u> <i>;declare zp1 section</i>
         <b class="k">.endstruct</b>
         <b class="k">.struct</b>
          <b class="d">.dsection</b> <u>zp2</u> <i>;declare zp2 section</i>
         <b class="k">.endstruct</b>
        <b class="k">.endunion</b>
        <b class="d">.dsection</b> <u>zp</u>    <i>;declare zp section</i>
</pre>

<h3>Macros<a name="macros" href="#macros"></a></h3>

<p>Macros can be used to reduce typing of frequently used source lines.
Each invocation is a copy of the macro's content with parameter references
replaced by the parameter texts.</p>

<dl class="dir">
<dt><b>.segment</b> [&lt;name&gt;][=&lt;default&gt;]][, [&lt;name&gt;][=&lt;default&gt;] &hellip;]<a name="d_segment" href="#d_segment"></a>
<dd>Start of segment block</dd>
<dt><b>.endsegment</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endsegment" href="#d_endsegment"></a>
<dd>End of segment block

<p>Copies the code segment as it is, so symbols can be used from
outside, but this also means multiple use will result in double defines
unless anonymous labels are used.</p></dd>

<dt><b>.macro</b> [&lt;name&gt;][=&lt;default&gt;]][, [&lt;name&gt;][=&lt;default&gt;] &hellip;]<a name="d_macro" href="#d_macro"></a>
<dd>Start of macro block</dd>
<dt><b>.endmacro</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endmacro" href="#d_endmacro"></a>
<dd>End of macro block

<p>The code is enclosed in it's own block so symbols inside are
non-accessible, unless a label is prefixed at the place of use, then local
labels can be accessed through that label.</p></dd>

<dt><b>#&lt;name&gt;</b> [&lt;param&gt;][[,][&lt;param&gt;] &hellip;]
<dt><b>.&lt;name&gt;</b> [&lt;param&gt;][[,][&lt;param&gt;] &hellip;]
<dd>Invoke the macro after <q><code>#</code></q> or <q><code>.</code></q> with the parameters. Normally the name of
the macro is used, but it can be any expression.</dd>

<dt><b>.endm</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endm" href="#d_endm"></a>
<dd>Closing directive of <a href="#d_macro"><code>.macro</code></a>
and <a href="#d_segment"><code>.segment</code></a> for compatibility.</dd>
</dl>

<pre>
<i>;A simple macro</i>
copy    <b class="k">.macro</b>
        <b>ldx</b> #<span class="k">size</span>(<span class="k">\1</span>)
lp      <b>lda</b> <span class="k">\1</span>,x
        <b>sta</b> <span class="k">\2</span>,x
        <b>dex</b>
        <b>bpl</b> <u>lp</u>
        <b class="k">.endmacro</b>

        <b class="k">#copy</b> <u>label</u>, <span>$500</span>

<i>;Use macro as an assembler directive</i>
lohi    <b class="k">.macro</b>
lo      <b class="d">.byte</b> &lt;(<span class="k">\@</span>)
hi      <b class="d">.byte</b> &gt;(<span class="k">\@</span>)
        <b class="k">.endmacro</b>

var     <b class="k">.lohi</b> <span>1234</span>, <span>5678</span>

        <b>lda</b> <u>var</u>.<u>lo</u>,y
        <b>ldx</b> <u>var</u>.<u>hi</u>,y
</pre>

<h4>Parameter references<a name="macro-parameters" href="#macro-parameters"></a></h4>

<p>The first 9 parameters can be referenced by <q><code>\1</code></q>&ndash;<q><code>\9</code></q>.
The entire parameter list including separators is <q><code>\@</code></q>.

<pre>
name    <b class="k">.macro</b>
        <b>lda</b> #<span class="k">\1</span>         <i>;first parameter 23+1</i>
        <b class="k">.endmacro</b>

        <b class="k">#name</b> <span>23</span>+<span>1</span>      <i>;call macro</i>
</pre>

<p>Parameters can be named, and it's possible to set a default value after an
equal sign which is used as a replacement when the parameter is missing.

<p>These named parameters can be referenced by <code>\name</code> or
<code>\{name}</code>. Names must match completely, if unsure use the quoted
name reference syntax.

<pre>
name    <b class="k">.macro</b> first, b=<span>2</span>, , last
        <b>lda</b> #<span class="k">\first</span>     <i>;first parameter</i>
        <b>lda</b> #<span class="k">\b</span>         <i>;second parameter</i>
        <b>lda</b> #<span class="k">\3</span>         <i>;third parameter</i>
        <b>lda</b> #<span class="k">\last</span>      <i>;fourth parameter</i>
        <b class="k">.endmacro</b>

        <b class="k">#name</b> <span>1</span>, , <span>3</span>, <span>4</span> <i>;call macro</i>
</pre>

<h4>Text references<a name="macro-textreference" href="#macro-textreference"></a></h4>

<p>In the original turbo assembler normal references are passed by value and
can only appear in place of one. Text references on the other hand can appear
everywhere and will work in place of e.g. quoted text or opcodes and labels. The
first 9 parameters can be referenced as text by
<code>@1</code>&ndash;<code>@9</code>.

<pre>
name    <b class="k">.macro</b>
        <b>jsr</b> <u>print</u>
        <b class="d">.null</b> <span class="s">"Hello <span>@1</span>!"</span><i>;first parameter</i>
        <b class="k">.endm</b>

        <b class="k">#name</b> <span class="s">"wth?"</span>    <i>;call macro</i>
</pre>

<h3>Custom functions<a name="user-functions" href="#user-functions"></a></h3>

<p>Beyond the built-in functions mentioned earlier it's possible to define
custom ones for frequently used calculations.</p>

<dl class="dir">
<dt><b>.sfunction</b> [&lt;name&gt;[:&lt;expression&gt;][=&lt;default&gt;], &hellip;][*&lt;name&gt;,] &lt;expression&gt;<a name="d_sfunction" href="#d_sfunction"></a>
<dd>Defines a simple function to return the result of a parametrised expression</dd>
<dt><b>.function</b> &lt;name&gt;[:&lt;expression&gt;][=&lt;default&gt;]], &lt;name&gt;[=&lt;default&gt;] &hellip;][, *&lt;name&gt;]<a name="d_function" href="#d_function"></a>
<dd>Defines a multi line function</dd>
<dt><b>.endf</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endf" href="#d_endf"></a>
<dt><b>.endfunction</b> [&lt;result&gt;][, &lt;result&gt; &hellip;]<a name="d_endfunction" href="#d_endfunction"></a>
<dd>End of a multi line function</dd>
<dt><b>#&lt;name&gt;</b> [&lt;param&gt;][[,][&lt;param&gt;] &hellip;]
<dt><b>.&lt;name&gt;</b> [&lt;param&gt;][[,][&lt;param&gt;] &hellip;]
<dt><b>&lt;name&gt;</b> [&lt;param&gt;][[,][&lt;param&gt;] &hellip;]
<dd>Invoke a multi line function like a macro, directive or pseudo instruction</dd>
</dl>

<p>Function parameters are assigned to comma separated variable names on
invocation. These variables are visible in the function scope.

<p>Parameter values may be converted using a function whose name can be given
after a colon following the variable name.

<p>Default values may be supplied for each parameter after an equal sign. These
values are calculated at function definition time only and are used when a
parameter was not specified.

<p>Extra parameters are not accepted, unless the last parameter symbol is
preceded with a star, in this case these parameters are collected into a tuple.

<p>Only those external variables and functions are available which were accessible at
the place of definition, but not those at the place of invocation.

<pre>
vicmem  <b class="k">.sfunction</b> <u>_font</u>, <u>_scr</u>=<span>0</span>, ((<u>_font</u> &gt;&gt; <span>10</span>) &amp; <span>$0f</span>) | ((<u>_scr</u> &gt;&gt; <span>6</span>) &amp; <span>$f0</span>)

        <b>lda</b> #<u>vicmem</u>(<span>$2000</span>, <span>$0400</span>)<i>; calculate constant</i>
        <b>sta</b> <span>$d018</span>
</pre>

<p>If a multi line function is used in an expression only the returned result is
used. If multiple values are returned these will form a tuple.

<p>If a multi line function is used as macro, directive or pseudo instruction
and there's a label in front then the returned value is assigned to it. If
nothing is returned then it's used as regular label.

<pre>
mva     <b class="k">.function</b> <u>value</u>, <u>target</u>
        <b>lda</b> <u>value</u>
        <b>sta</b> <u>target</u>
        <b class="k">.endfunction</b>

        <b class="k">mva</b> #<span>1</span>, <u>label</u>
</pre>

<h3>Conditional assembly<a name="conditional-assembly" href="#conditional-assembly"></a></h3>

<p>To prevent parts of source from compiling conditional constructs can be
used. This is useful when multiple slightly different versions needs to be
compiled from the same source.

<p>Anonymous labels are still recognized in the non-compiling parts even if
they won't get defined. This ensures consistent relative referencing
across conditionally compiled areas with such labels.

<h4>If, else if, else<a name="conditional-if" href="#conditional-if"></a></h4>
<dl class="dir">
<dt><b>.if</b> &lt;condition&gt;<a name="d_if" href="#d_if"></a>
<dd>Compile if condition is true</dd>
<dt><b>.elsif</b> &lt;condition&gt;<a name="d_elsif" href="#d_elsif"></a>
<dd>Compile if previous conditions were not met and the condition is true</dd>
<dt><b>.else</b><a name="d_else" href="#d_else"></a>
<dd>Compile if previous conditions were not met</dd>
<dt><b>.ifne</b> &lt;value&gt;<a name="d_ifne" href="#d_ifne"></a>
<dd>Compile if value is not zero</dd>
<dt><b>.ifeq</b> &lt;value&gt;<a name="d_ifeq" href="#d_ifeq"></a>
<dd>Compile if value is zero</dd>
<dt><b>.ifpl</b> &lt;value&gt;<a name="d_ifpl" href="#d_ifpl"></a>
<dd>Compile if value is greater or equal zero</dd>
<dt><b>.ifmi</b> &lt;value&gt;<a name="d_ifmi" href="#d_ifmi"></a>
<dd>Compile if value is less than zero

<p>The <a href="#d_ifne"><code>.ifne</code></a>, <a href="#d_ifeq"><code>.ifeq</code></a>, <a href="#d_ifpl"><code>.ifpl</code></a> and
<a href="#d_ifmi"><code>.ifmi</code></a> directives exists for compatibility only, in practice it's
better to use comparison operators instead.

<pre>
        <b class="k">.if</b> <u>wait</u>==<span>2</span>     <i>;2 cycles</i>
        <b>nop</b>
        <b class="k">.elsif</b> <u>wait</u>==<span>3</span>  <i>;3 cycles</i>
        <b>bit</b> <span>$ea</span>
        <b class="k">.elsif</b> <u>wait</u>==<span>4</span>  <i>;4 cycles</i>
        <b>bit</b> <span>$eaea</span>
        <b class="k">.else</b>           <i>;else 5 cycles</i>
        <b>inc</b> <span>$2</span>
        <b class="k">.endif</b>
</pre></dd>

<dt><b>.fi</b><a name="d_fi" href="#d_fi"></a>
<dt><b>.endif</b><a name="d_endif" href="#d_endif"></a>
<dd>End of conditional compilation.</dd>
<dt><b>.elif</b> &lt;condition&gt;<a name="d_elif" href="#d_elif"></a>
<dd>Same as <a href="#d_elsif"><code>.elsif</code></a> because it's a popular typo and it's difficult to notice.</dd>
</dl>

<h4>Switch, case, default<a name="conditional-switch" href="#conditional-switch"></a></h4>

<p>Similar to the <a href="#d_if"><code>.if</code></a>, <a href="#d_elsif"><code>.elsif</code></a>, <a href="#d_else"><code>.else</code></a>, <a href="#d_endif"><code>.endif</code></a>
construct, but the compared value needs to be written only once in the switch
statement.</p>

<dl class="dir">
<dt><b>.switch</b> &lt;expression&gt;<a name="d_switch" href="#d_switch"></a>
<dd>Evaluate expression and remember it</dd>
<dt><b>.case</b> &lt;expression&gt;[, &lt;expression&gt; &hellip;]<a name="d_case" href="#d_case"></a>
<dd>Compile if the previous conditions were all skipped and one of the values equals</dd>
<dt><b>.default</b><a name="d_default" href="#d_default"></a>
<dd>Compile if the previous conditions were all skipped

<pre>
        <b class="k">.switch</b> <u>wait</u>
        <b class="k">.case</b> <span>2</span>         <i>;2 cycles</i>
        <b>nop</b>
        <b class="k">.case</b> <span>3</span>         <i>;3 cycles</i>
        <b>bit</b> <span>$ea</span>
        <b class="k">.case</b> <span>4</span>         <i>;4 cycles</i>
        <b>bit</b> <span>$eaea</span>
        <b class="k">.default</b>        <i>;else 5 cycles</i>
        <b>inc</b> <span>$2</span>
        <b class="k">.endswitch</b>
</pre></dd>

<dt><b>.endswitch</b><a name="d_endswitch" href="#d_endswitch"></a>
<dd>End of <a href="#d_switch"><code>.switch</code></a> conditional compilation block.</dd>
</dl>

<h4>Comment<a name="conditional-comment" href="#conditional-comment"></a></h4>

<dl class="dir">
<dt><b>.comment</b><a name="d_comment" href="#d_comment"></a>
<dd>Never compile.

<pre>
        <b class="k">.comment</b>
<i>        lda #1          ;this won't be compiled</i>
<i>        sta $d020</i>
        <b class="k">.endcomment</b>
</pre></dd>

<dt><b>.endc</b><a name="d_endc" href="#d_endc"></a>
<dt><b>.endcomment</b><a name="d_endcomment" href="#d_endcomment"></a>
<dd>End of <a href="#d_comment"><code>.comment</code></a> block.</dd>
</dl>

<h3>Repetitions<a name="repetitions" href="#repetitions"></a></h3>

<p>The following directives are used to repeat code or data.

<p>The regular non-scoped variants cover most cases except when normal labels
are required as those will be double defined.

<p>Scoped variants (those starting with the letter b) create a new scope
for each iteration. This allows normal labels without collision but it's a bit more
resource intensive.

<p>If the scoped variant is prefixed with a label then the list of individual scopes for
each iteration will be assigned to it. This allows accessing labels within.</p>

<dl class="dir">
<dt><b>.for</b> [&lt;assignment&gt;], [&lt;condition&gt;], [&lt;assignment&gt;]<a name="d_for" href="#d_for"></a>
<dt><b>.bfor</b> [&lt;assignment&gt;], [&lt;condition&gt;], [&lt;assignment&gt;]<a name="d_bfor" href="#d_bfor"></a>
<dd>Assign initial value, loop while the condition is true and modify value.

<p>First a variable is set, usually this is used for counting. This is optional, the variable may be set already before the loop.</p>

<p>Then the condition is checked and the enclosed lines are compiled if it's true. If there's no condition then it's an infinite loop and <a href="#d_break"><code>.break</code></a> must be used to terminate it.</p>

<p>After an iteration the second assignment is calculated, usually it's updating the loop counter variable. This is optional as well.</p>

<pre>
        <b>ldx</b> #<span>0</span>
        <b>lda</b> #<span>32</span>
lp      <b class="k">.for</b> <u>ue</u> := <span>$400</span>, <u>ue</u> &lt; <span>$800</span>, <u>ue</u> += <span>$100</span>
        <b>sta</b> <u>ue</u>,x         <i>;do $400, $500, $600 and $700</i>
        <b class="k">.endfor</b>
        <b>dex</b>
        <b>bne</b> <u>lp</u>
</pre></dd>

<dt><b>.for</b> &lt;variable&gt;[, &lt;variable&gt;, &hellip;] <b class="k">in</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]
<dt><b>.bfor</b> &lt;variable&gt;[, &lt;variable&gt;, &hellip;] <b class="k">in</b> &lt;expression&gt;[, &lt;expression&gt;, &hellip;]
<dd>Assign variable(s) to values in sequence one-by-one in order.

<p>Usually one variable is used to loop through all values. The values can be
supplied by <a href="#f_range"><code>range</code></a> function or some sort of
<a href="#list-tuples">list</a>.

<p>It's also possible to use more than one variable for each iteration. These
can be assigned to a collection of values each time (row oriented) or a single
value from each collection (column oriented).

<p>A row oriented for loop expects collections of the same number of values as
the number of variables as each variable gets assigned to one of them. The
loop iteration count depends on how many such collections were supplied.

<p>A column oriented for loop expects the same number of collections (comma
separated) as the number of variables. On each iteration a single value is
taken from each and is assigned to the matching variable. All collections should
have the same length so that all variables can be assigned. This length also
determines the loop iteration count.</p>

<pre>
<i>;loop through on iterable or on comma separated values</i>
        <b class="k">.for</b> <u>col</u> <span class="k">in</span> <span>0</span>, <span>11</span>, <span>12</span>, <span>15</span>, <span>1</span>
        <b>lda</b> #<u>col</u>         <i>;0, 11, 12, 15 and 1</i>
        <b>sta</b> <span>$d020</span>
        <b class="k">.endfor</b>
<i>;row oriented iterating for loop, on list of tuples</i>
        <b class="k">.for</b> <u>dest</u>, <u>val</u> <span class="k">in</span> [(<span>$d011</span>, <span>$3b</span>), (<span>$d020</span>, <span>0</span>), (<span>$d018</span>, <span>$18</span>)]
        <b>lda</b> #<u>val</u>
        <b>sta</b> <u>dest</u>
        <b class="k">.endfor</b>
<i>;column oriented iterating for loop, one iterable for each variable.</i>
        <b class="k">.for</b> <u>dest</u>, <u>val</u> <span class="k">in</span> (<span>$d011</span>, <span>$d020</span>, <span>$d018</span>), (<span>$3b</span>, <span>0</span>, <span>$18</span>)
        <b>lda</b> #<u>val</u>
        <b>sta</b> <u>dest</u>
        <b class="k">.endfor</b>
</pre></dd>

<dt><b>.endfor</b><a name="d_endfor" href="#d_endfor"></a>
<dd>End of a <a href="#d_for"><code>.for</code></a> or <a href="#d_bfor"><code>.bfor</code></a> loop block</dd>

<dt><b>.rept</b> &lt;expression&gt;<a name="d_rept" href="#d_rept"></a>
<dt><b>.brept</b> &lt;expression&gt;<a name="d_brept" href="#d_brept"></a>
<dd>Repeat enclosed lines the specified number of times.

<pre>
        <b class="k">.rept</b> <span>100</span>
-       <b>inx</b>
        <b>bne</b> <u>-</u>
        <b class="k">.endrept</b>

lst     <b class="k">.brept</b> <span>100</span>       <i>;each iteration into a tuple</i>
label   <b>jmp</b> <u>label</u>        <i>;not a duplicate definition</i>
        <b class="k">.endrept</b>
        <b>jmp</b> <u>lst</u>[<span>5</span>].<u>label</u> <i>;use label of 6th iteration</i>
</pre></dd>

<dt><b>.endrept</b><a name="d_endrept" href="#d_endrept"></a>
<dd>End of a <a href="#d_rept"><code>.rept</code></a> or <a href="#d_brept"><code>.brept</code></a> block</dd>

<dt><b>.while</b> &lt;condition&gt;<a name="d_while" href="#d_while"></a>
<dt><b>.bwhile</b> &lt;condition&gt;<a name="d_bwhile" href="#d_bwhile"></a>
<dd>Repeat enclosed lines until the condition holds.

<p>Works as expected however the scoped variant might be tricky to use as
variables of the condition are usually part of the parent scope. So
modifying them in the loop body should be done with compound assignments
or the reassign operator (<code>::=</code>).</p></dd>

<dt><b>.endwhile</b><a name="d_endwhile" href="#d_endwhile"></a>
<dd>End of a <a href="#d_while"><code>.while</code></a> or <a href="#d_bwhile"><code>.bwhile</code></a> loop block</dd>

<dt><b>.break</b><a name="d_break" href="#d_break"></a>
<dd>Exit current repetition loop immediately.</dd>

<dt><b>.breakif</b> &lt;condition&gt;<a name="d_breakif" href="#d_breakif"></a>
<dd>Exit current repetition loop immediately if the condition holds.

<p>It's a shorthand for a <a href="#d_if"><code>.if</code></a>, <a href="#d_break"><code>.break</code></a>, <a href="#d_endif"><code>.endif</code></a> sequence.</p></dd>

<dt><b>.continue</b><a name="d_continue" href="#d_continue"></a>
<dd>Continue current repetition loop's next iteration.</dd>

<dt><b>.continueif</b> &lt;condition&gt;<a name="d_continueif" href="#d_continueif"></a>
<dd>Continue current repetition loop's next iteration if the condition holds.

<p>It's a shorthand for a <a href="#d_if"><code>.if</code></a>, <a href="#d_continue"><code>.continue</code></a>, <a href="#d_endif"><code>.endif</code></a> sequence.</p></dd>

<dt><b>.next</b><a name="d_next" href="#d_next"></a>
<dd>Closing directive of <a href="#d_for"><code>.for</code></a>,
<a href="#d_bfor"><code>.bfor</code></a>, <a href="#d_rept"><code>.rept</code></a>,
<a href="#d_brept"><code>.brept</code></a>, <a href="#d_while"><code>.while</code></a>
and <a href="#d_while"><code>.bwhile</code></a> loop for compatibility.</dd>

<dt><b>.lbl</b><a name="d_lbl" href="#d_lbl"></a>
<dd>Creates a special jump label that can be referenced by <a href="#d_goto"><code>.goto</code></a></dd>
<dt><b>.goto</b> &lt;labelname&gt;<a name="d_goto" href="#d_goto"></a>
<dd>Causes assembler to continue assembling from the jump label. No
forward references of course, handle with care. Should only be used in
classic TASM sources for creating loops.

<pre>
i       <b class="k">.var</b> <span>100</span>
loop    <b class="k">.lbl</b>
        <b>nop</b>
i       <b class="k">.var</b> <u>i</u> - <span>1</span>
        <b class="k">.ifne</b> <u>i</u>
        <b class="k">.goto</b> <u>loop</u>       <i>;generates 100 nops</i>
        <b class="k">.endif</b>           <i>;the hard way ;)</i>
</pre></dd>

</dl>
<h3>Including files<a name="including" href="#including"></a></h3>

<p>Longer sources are usually separated into multiple files for easier
handling. Precomputed binary data can also be included directly without
converting it into source code first.

<p>Search path is relative to the location of current source file. If it's not
found there the include search path is consulted for further possible
locations.

<p>To make your sources portable please always use forward slashes
(<code>/</code>) as a directory separator and use lower/uppercase consistently
in file names!</p>

<dl class="dir">
<dt><b>.include</b> &lt;filename&gt;<a name="d_include" href="#d_include"></a>
<dd>Include source file here.</dd>
<dt><b>.binclude</b> &lt;filename&gt;<a name="d_binclude" href="#d_binclude"></a>
<dd>Include source file here in it's local block. If the directive is prefixed
with a label then all labels are local and are accessible through that label
only, otherwise not reachable at all.
<pre>

        <b class="k">.include</b> <span class="s">"macros.asm"</span>       <i>;include macros</i>
menu    <b class="k">.binclude</b> <span class="s">"menu.asm"</span>        <i>;include in a block</i>
        <b>jmp</b> <u>menu</u>.<u>start</u>
</pre></dd>

<dt><b>.binary</b> &lt;filename&gt;[, &lt;offset&gt;[, &lt;length&gt;]]<a name="d_binary" href="#d_binary"></a>
<dd>Include raw binary data from file.

<p>By using offset and length it's possible to break out chunks of data from a
file separately, like bitmap and colors for example. Negative offsets are calculated from the end of file.

<pre>
        <b class="d">.binary</b> <span class="s">"stuffz.bin"</span>        <i>;simple include, all bytes</i>
        <b class="d">.binary</b> <span class="s">"stuffz.bin"</span>, <span>2</span>     <i>;skip start address</i>
        <b class="d">.binary</b> <span class="s">"stuffz.bin"</span>, <span>2</span>, <span>1000</span><i>;skip start address, 1000 bytes max</i>
</pre></dd>

</dl>
<h3>Scopes<a name="scopes" href="#scopes"></a></h3>

<p>Scopes may contain symbols or further nested scopes. The same symbol name
can be reused as long as it's in a different scope.

<p>A symbol is looked up in the local scope first. If it's a non-local symbol
then parent scopes and the global scope may be searched in addition.  This means
that a symbol in a parent or global scope may be <q>shadowed</q>.

<p>Symbols of a named scope can be looked up using the <q><code>.</code></q> operator.
The searched symbol stands on the right and it's looked up in the scope on the
left. More than one symbol may be looked up at the same time and the result
will be a list or tuple.

<pre>
        <b>lda</b> #<span>0</span>
        <b>sta</b> <u>vic</u>.<u>sprite</u>.<u>enable</u>
<i>; same as .byte colors.red, colors.green, colors.blue</i>
ctable  <b class="d">.byte</b> <u>colors</u>.(<u>red</u>, <u>green</u>, <u>blue</u>)
</pre>

<dl class="dir">
<dt><b>.proc</b><a name="d_proc" href="#d_proc"></a>
<dd>Start of a procedure block</dd>
<dt><b>.pend</b><a name="d_pend" href="#d_pend"></a>
<dt><b>.endproc</b><a name="d_endproc" href="#d_endproc"></a>
<dd>End of a procedure block

<p>If the symbol in front is not referenced anywhere then the enclosed source
won't be compiled.</p>

<p>Symbols inside are enclosed in a scope and are accessible through the
symbol of the procedure using the dot notation. This forces compilation of the
whole procedure of course.</p>

<pre>
ize     <b class="k">.proc</b>
        <b>nop</b>
cucc    <b>nop</b>
        <b class="k">.endproc</b>

        <b>jsr</b> <u>ize</u>
        <b>jmp</b> <u>ize</u>.<u>cucc</u>
</pre>

<p>The <q>compilation only if used</q> behaviour of <code>.proc</code> eases the building of <q>libraries</q> from a
collection of subroutines and tables where not everything is needed all the time.</p>

<p>Alternative dead-code reduction techniques I encountered:</p>

<dl>
<dt>Separate source files
<dd>This potentially results in a lot of small files and manually managed include
directives. This is popular on external linker based systems where object files
may be excluded if unused.</dd>
<dt>Conditional compilation
<dd>Few larger files with conditional compilation directives all over the place to
exclude or include various parts. The source which does the include manually declares
somewhere what's actually needed or not. There may be a lot of options if it's
fine grained enough.</dd>
<dt>Wrap parts with macros
<dd>If a part is needed then a single macro call is placed
somewhere to <q>include</q> that part. Much better than conditional compilation
but these macro calls still need to be manually managed.</dd>
</dl></dd>

<dt><b>.block</b><a name="d_block" href="#d_block"></a>
<dd>Block scoping area start</dd>
<dt><b>.bend</b><a name="d_bend" href="#d_bend"></a>
<dt><b>.endblock</b><a name="d_endblock" href="#d_endblock"></a>
<dd>Block scoping area end

<p>All symbols inside a block are enclosed in a scope. If the block had a symbol
then local symbols are accessible through that using the dot notation.</p>

<pre>
        <b class="k">.block</b>
        <b>inc</b> <u>count</u> + <span>1</span>
count   <b>ldx</b> #<span>0</span>
        <b class="k">.endblock</b>
</pre></dd>

<dt><b>.namespace</b> [&lt;expression&gt;]<a name="d_namespace" href="#d_namespace"></a>
<dd>Namespace area start</dd>
<dt><b>.endn</b><a name="d_endn" href="#d_endn"></a>
<dt><b>.endnamespace</b><a name="d_endnamespace" href="#d_endnamespace"></a>
<dd>Namespace area end

<p>This directive either creates a new scope (if used without a parameter) or activates the one in the parameter.</p>

<p>The scope can be assigned to a symbol in front of the directive so that it
can be reactivated later. This enables label definitions into the same scope in
different files.</p>

<pre>
colors  <b class="k">.namespace</b>
red     <b>=</b> <span>2</span>
blue    <b>=</b> <span>6</span>
        <b class="k">.endnamespace</b>
        <b>lda</b> #<u>colors</u>.<u>red</u>
</pre></dd>

<dt><b>.weak</b><a name="d_weak" href="#d_weak"></a>
<dt><b>.endweak</b><a name="d_endweak" href="#d_endweak"></a>
<dd>Weak symbol area

<p>Any symbols defined inside can be overridden by <q>stronger</q> symbols in
the same scope from outside. Can be nested as necessary.</p>

<p>This gives the possibility of giving default values for symbols which might
not always exist without resorting to <code>.ifdef</code>/<code>.ifndef</code> or
similar directives in other assemblers.</p>

<pre>
symbol  <b>=</b> <span>1</span>            <i>;stronger symbol than the one below</i>
        <b class="k">.weak</b>
symbol  <b>=</b> <span>0</span>            <i>;default value if the one above does not exists</i>
        <b class="k">.endweak</b>
        <b class="k">.if</b> <u>symbol</u>     <i>;almost like an .ifdef ;)</i>
</pre>

<p>Other use of weak symbols might be in included libraries to change default values or
replace stub functions and data structures.</p>

<p>If these stubs are defined using
<a href="#d_proc"><code>.proc</code></a>/<a href="#d_endproc"><code>.endproc</code></a> then their default implementations will
not even exists in the output at all when a stronger symbol overrides them.</p>

<p>Multiple definition of a symbol with the same <q>strength</q> in the same
scope is of course not allowed and it results in double definition error.</p>

<p>Please note that <code>.ifdef</code>/<code>.ifndef</code> directives are
left out from 64tass for of technical reasons, so don't wait for them to appear
anytime soon.</p></dd>

<dt><b>.with</b> &lt;expression&gt;<a name="d_with" href="#d_with"></a>
<dt><b>.endwith</b><a name="d_endwith" href="#d_endwith"></a>
<dd>Namespace access

<p>This directive is similar to <a href="#d_namespace"><code>.namespace</code></a> but it gives access to
another scope's variables without leaving the current scope. May be
useful to allow a short hand access in some situations.</p>

<p>It's advised to use the <q><a href="#o_Wshadow"><code>-Wshadow</code></a></q> command line
option to warn about any unexpected symbol ambiguity.</p></dd>
</dl>

<h3>Sections<a name="sections" href="#sections"></a></h3>

<p>Sections can be used to collect data or code into separate memory areas
without moving source code lines around. This is achieved by having separate
compile offset and program counters for each defined section.</p>

<dl class="dir">
<dt><b>.section</b> &lt;name&gt;<a name="d_section" href="#d_section"></a>
<dd>Starts a segment block</dd>
<dt><b>.send</b> [&lt;name&gt;]<a name="d_send" href="#d_send"></a>
<dt><b>.endsection</b> [&lt;name&gt;]<a name="d_endsection" href="#d_endsection"></a>
<dd>Ends a segment block

<p>Defines a section fragment. The name at <code>.endsection</code> must match but
it's optional.</p></dd>

<dt><b>.dsection</b> &lt;name&gt;<a name="d_dsection" href="#d_dsection"></a>
<dd>Collect the section fragments here.</dd>
</dl>

<p>All <a href="#d_section"><code>.section</code></a> fragments are compiled to the memory area
allocated by the <a href="#d_dsection"><code>.dsection</code></a> directive. Compilation happens as the
code appears, this directive only assigns enough space to hold all the content
in the section fragments.

<p>The space used by section fragments is calculated from the difference of
starting compile offset and the maximum compile offset reached. It is possible
to manipulate the compile offset in fragments, but putting code before the
start of <a href="#d_dsection"><code>.dsection</code></a> is not allowed.

<pre>
*       <b>=</b> <span>$02</span>
        <b class="d">.dsection</b> <u>zp</u>   <i>;declare zero page section</i>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$30</span>, <span class="s">"Too many zero page variables"</span>

*       <b>=</b> <span>$334</span>
        <b class="d">.dsection</b> <u>bss</u>   <i>;declare uninitialized variable section</i>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$400</span>, <span class="s">"Too many variables"</span>

*       <b>=</b> <span>$0801</span>
        <b class="d">.dsection</b> <u>code</u>   <i>;declare code section</i>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$1000</span>, <span class="s">"Program too long!"</span>

*       <b>=</b> <span>$1000</span>
        <b class="d">.dsection</b> <u>data</u>   <i>;declare data section</i>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$2000</span>, <span class="s">"Data too long!"</span>
<i>;--------------------</i>
        <b class="k">.section</b> <u>code</u>
        <b class="d">.word</b> <u>ss</u>, <span>2005</span>
        <b class="d">.null</b> <span>$9e</span>, <span class="k">format</span>(<span class="s">"%4d"</span>, <u>start</u>)
ss      <b class="d">.word</b> <span>0</span>

start   <b>sei</b>
        <b class="k">.section</b> <u>zp</u>     <i>;declare some new zero page variables</i>
p2      <b class="d">.addr</b> <span>?</span>         <i>;a pointer</i>
        <b class="k">.endsection</b> <u>zp</u>
        <b class="k">.section</b> <u>bss</u>    <i>;new variables</i>
buffer  <b class="d">.fill</b> <span>10</span>        <i>;temporary area</i>
        <b class="k">.endsection</b> <u>bss</u>

        <b>lda</b> (<u>p2</u>),y
        <b>lda</b> #&lt;<u>label</u>
        <b>ldy</b> #&gt;<u>label</u>
        <b>jsr</b> <u>print</u>

        <b class="k">.section</b> <u>data</u>   <i>;some data</i>
label   <b class="d">.null</b> <span class="s">"message"</span>
        <b class="k">.endsection</b> <u>data</u>

        <b>jmp</b> <u>error</u>
        <b class="k">.section</b> <u>zp</u>     <i>;declare some more zero page variables</i>
p3      <b class="d">.addr</b> <span>?</span>         <i>;a pointer</i>
        <b class="k">.endsection</b> <u>zp</u>
        <b class="k">.endsection</b> <u>code</u>
</pre>

<p>The compiled code will look like:

<pre>
&gt;0801   0b 08 d5 07                             <b class="d">.word</b> <u>ss</u>, <span>2005</span>
&gt;0805   9e 32 30 36 31 00                       <b class="d">.null</b> <span>$9e</span>, <span class="k">format</span>(<span class="s">"%4d"</span>, <u>start</u>)
&gt;080b   00 00                           ss      <b class="d">.word</b> <span>0</span>

.080d   78                              start   <b>sei</b>

&gt;0002                                   p2      <b class="d">.addr</b> <span>?</span>         <i>;a pointer</i>
&gt;0334                                   buffer  <b class="d">.fill</b> <span>10</span>        <i>;temporary area</i>

.080e   b1 02                                   <b>lda</b> (<u>p2</u>),y
.0810   a9 00                                   <b>lda</b> #&lt;<u>label</u>
.0812   a0 10                                   <b>ldy</b> #&gt;<u>label</u>
.0814   20 1e ab                                <b>jsr</b> <u>print</u>

&gt;1000   6d 65 73 73 61 67 65 00         label   <b class="d">.null</b> <span class="s">"message"</span>

.0817   4c e2 fc                                <b>jmp</b> <u>error</u>

&gt;0004                                   p2      <b class="d">.addr</b> ?         <i>;a pointer</i>
</pre>

<p>Sections can form a hierarchy by nesting a <a href="#d_dsection"><code>.dsection</code></a> into
another section. The section names must only be unique within a section but can
be reused otherwise. Parent section names are visible for children, siblings can be
reached through parents.

<p>In the following example the included sources don't have to know which
<q>code</q> and <q>data</q> sections they use, while the <q>bss</q> section is
shared for all banks.

<pre>
<i>;First 8K bank at the beginning, PC at $8000</i>
*       <b>=</b> <span>$0000</span>
        <b class="k">.logical</b> <span>$8000</span>
        <b class="d">.dsection</b> <u>bank1</u>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$a000</span>, <span class="s">"Bank1 too long"</span>
        <b class="k">.endlogical</b>

bank1   <b class="k">.block</b>          <i>;Make all symbols local</i>
        <b class="k">.section</b> <u>bank1</u>
        <b class="d">.dsection</b> <u>code</u>  <i>;Code and data sections in bank1</i>
        <b class="d">.dsection</b> <u>data</u>
        <b class="k">.section</b> <u>code</u>   <i>;Pre-open code section</i>
        <b class="k">.include</b> <span class="s">"code.asm"</span><i>; see below</i>
        <b class="k">.include</b> <span class="s">"iter.asm"</span>
        <b class="k">.endsection</b> <u>code</u>
        <b class="k">.endsection</b> <u>bank1</u>
        <b class="k">.endblock</b>

<i>;Second 8K bank at $2000, PC at $8000</i>
*       <b>=</b> <span>$2000</span>
        <b class="k">.logical</b> <span>$8000</span>
        <b class="d">.dsection</b> <u>bank2</u>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$a000</span>, <span class="s">"Bank2 too long"</span>
        <b class="k">.endlogical</b>

bank2   <b class="k">.block</b>          <i>;Make all symbols local</i>
        <b class="k">.section</b> <u>bank2</u>
        <b class="d">.dsection</b> <u>code</u>  <i>;Code and data sections in bank2</i>
        <b class="d">.dsection</b> <u>data</u>
        <b class="k">.section</b> <u>code</u>   <i>;Pre-open code section</i>
        <b class="k">.include</b> <span class="s">"scr.asm"</span>
        <b class="k">.endsection</b> <u>code</u>
        <b class="k">.endsection</b> <u>bank2</u>
        <b class="k">.endblock</b>

<i>;Common data, avoid initialized variables here!</i>
*       <b>=</b> <span>$c000</span>
        <b class="d">.dsection</b> <u>bss</u>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$d000</span>, <span class="s">"Too much common data"</span>
<i>;------------- The following is in "code.asm"</i>
code    <b>sei</b>

        <b class="k">.section</b> <u>bss</u>   <i>;Common data section</i>
buffer  <b class="d">.fill</b> <span>10</span>
        <b class="k">.endsection</b> <u>bss</u>

        <b class="k">.section</b> <u>data</u>  <i>;Data section (in bank1)</i>
routine <b class="d">.addr</b> <u>print</u>
        <b class="k">.endsection</b> <u>bss</u>
</pre>

<h3>65816 related<a name="w65816" href="#w65816"></a></h3>

<dl class="dir">
<dt><b>.as</b><a name="d_as" href="#d_as"></a>
<dt><b>.al</b><a name="d_al" href="#d_al"></a>
<dd>Select short (8&nbsp;bit) or long (16&nbsp;bit) accumulator immediate constants.

<pre>
        <b class="k">.al</b>
        <b>lda</b> #<span>$4322</span>
</pre></dd>

<dt><b>.xs</b><a name="d_xs" href="#d_xs"></a>
<dt><b>.xl</b><a name="d_xl" href="#d_xl"></a>
<dd>Select short (8&nbsp;bit) or long (16&nbsp;bit) index register immediate constants.
<pre>
        <b class="k">.xl</b>
        <b>ldx</b> #<span>$1000</span>
</pre></dd>

<dt><b>.autsiz</b><a name="d_autsiz" href="#d_autsiz"></a>
<dt><b>.mansiz</b><a name="d_mansiz" href="#d_mansiz"></a>
<dd>Select automatic adjustment of immediate constant sizes based on
<code>SEP</code>/<code>REP</code> instructions.

<pre>
        <b class="k">.autsiz</b>
        <b>rep</b> #<span>$10</span>        <i>;implicit .xl</i>
        <b>ldx</b> #<span>$1000</span>
</pre></dd>

<dt><b>.databank</b> &lt;expression&gt;<a name="d_databank" href="#d_databank"></a>
<dd>Data bank (absolute) addressing is only used for addresses falling into this 64&nbsp;KiB
bank. The default is 0, which means addresses in bank zero.

<p>When data bank is switched off only data bank indexed (,b) addresses create data bank accessing instructions.</p>

<pre>
        <b class="k">.databank</b> <span>$10</span>   <i>;data bank at $10xxxx</i>
        <b>lda</b> <span>$101234</span>     <i>;results in $ad, $34, $12</i>
        <b class="k">.databank</b> <span>?</span>     <i>;no data bank</i>
        <b>lda</b> <span>$1234</span>       <i>;direct page or long addressing</i>
        <b>lda</b> #<span>$1234</span>,b    <i>;results in $ad, $34, $12</i>
</pre></dd>

<dt><b>.dpage</b> &lt;expression&gt;<a name="d_dpage" href="#d_dpage"></a>
<dd>Direct (zero) page addressing is only used for addresses falling
into a specific 256 byte address range. The default is 0, which is the first page of bank zero.

<p>When direct page is switched off only the direct page indexed (,d) addresses create direct page accessing instructions.</p>

<pre>
        <b class="k">.dpage</b> <span>$400</span>     <i>;direct page $400-$4ff</i>
        <b>lda</b> <span>$456</span>        <i>;results in $a5, $56</i>
        <b class="k">.dpage</b> <span>?</span>        <i>;no direct page</i>
        <b>lda</b> <span>$56</span>         <i>;data bank or long addressing</i>
        <b>lda</b> #<span>$56</span>,d      <i>;results in $a5, $56</i>
</pre></dd>
</dl>

<h3>Controlling errors<a name="compiletime-checks" href="#compiletime-checks"></a></h3>

<dl class="dir">
<dt><b>.option</b> allow_branch_across_page<a name="d_option" href="#d_option"></a>
<dd>Switches error generation on page boundary crossing during relative branch.
Such a condition on 6502 adds 1 extra cycle to the execution time, which
can ruin the timing of a carefully cycle counted code.

<pre>
        <b class="k">.option</b> allow_branch_across_page = <span>0</span>
        <b>bcc</b> <u>+</u>           <i>;same execution time</i>
        <b>inx</b>             <i>;needed in both cases</i>
+       <b>bcs</b> <u>+</u>
        <b>dex</b>
+       <b class="k">.option</b> allow_branch_across_page = <span>1</span>
</pre></dd>

<dt><b>.error</b> &lt;message&gt; [, &lt;message&gt;, &hellip;]<a name="d_error" href="#d_error"></a>
<dt><b>.cerror</b> &lt;condition&gt;, &lt;message&gt; [, &lt;message&gt;, &hellip;]<a name="d_cerror" href="#d_cerror"></a>
<dd>Exit with error or conditionally exit with error

<pre>
        <b class="k">.error</b> <span class="s">"Unfinished here..."</span>
        <b class="k">.cerror</b> <u>*</u> &gt; <span>$1200</span>, <span class="s">"Program too long by "</span>, <u>*</u> - <span>$1200</span>, <span class="s">" bytes"</span>
</pre></dd>

<dt><b>.warn</b> &lt;message&gt; [, &lt;message&gt;, &hellip;]<a name="d_warn" href="#d_warn"></a>
<dt><b>.cwarn</b> &lt;condition&gt;, &lt;message&gt; [, &lt;message&gt;, &hellip;]<a name="d_cwarn" href="#d_cwarn"></a>
<dd>Display a warning message always or depending on a condition

<pre>
        <b class="k">.warn</b> <span class="s">"FIXME: handle negative values too!"</span>
        <b class="k">.cwarn</b> <u>*</u> &gt; <span>$1200</span>, <span class="s">"This may not work!"</span>
</pre></dd>

</dl>

<h3>Target<a name="target-cpu" href="#target-cpu"></a></h3>

<dl class="dir">
<dt><b>.cpu</b> &lt;expression&gt;<a name="d_cpu" href="#d_cpu"></a>
<dd>Selects CPU according to the string argument.

<p>In the past the <code>.cpu</code> directive accepted an unquoted string but
currently it needs to be an expression.</p>

<pre>
        <b class="k">.cpu</b> <span class="s">"6502"</span>     <i>;standard 65xx</i>
        <b class="k">.cpu</b> <span class="s">"65c02"</span>    <i>;CMOS 65C02</i>
        <b class="k">.cpu</b> <span class="s">"65ce02"</span>   <i>;CSG 65CE02</i>
        <b class="k">.cpu</b> <span class="s">"6502i"</span>    <i>;NMOS 65xx</i>
        <b class="k">.cpu</b> <span class="s">"65816"</span>    <i>;W65C816</i>
        <b class="k">.cpu</b> <span class="s">"65dtv02"</span>  <i>;65dtv02</i>
        <b class="k">.cpu</b> <span class="s">"65el02"</span>   <i>;65el02</i>
        <b class="k">.cpu</b> <span class="s">"r65c02"</span>   <i>;R65C02</i>
        <b class="k">.cpu</b> <span class="s">"w65c02"</span>   <i>;W65C02</i>
        <b class="k">.cpu</b> <span class="s">"4510"</span>     <i>;CSG 4510</i>
        <b class="k">.cpu</b> <span class="s">"45gs02"</span>   <i>;45GS02</i>
        <b class="k">.cpu</b> <span class="s">"default"</span>  <i>;cpu set on command line</i>
</pre></dd>
</dl>

<h3>Misc<a name="misc" href="#misc"></a></h3>

<dl class="dir">
<dt><b>.end</b><a name="d_end" href="#d_end"></a>
<dd>Terminate assembly. Any content after this directive is ignored.</dd>

<dt><b>.eor</b> &lt;expression&gt;<a name="d_eor" href="#d_eor"></a>
<dd>XOR output with an 8&nbsp;bit value. Useful for reverse screen code text for example,
or for silly <q>encryption</q>.</dd>

<dt><b>.seed</b> &lt;expression&gt;<a name="d_seed" href="#d_seed"></a>
<dd>Seed the pseudo random number generator with an unsigned integer of
maximum 128 bits to make the generated numbers less boring.</dd>

<dt><b>.var</b> &lt;expression&gt;<a name="d_var" href="#d_var"></a>
<dd>Defines a variable identified by the label preceding, which
is set to the value of expression or reference of variable.

<pre>
counter <b class="k">.var</b> <span>0</span>                <i>;define, same as :=</i>
counter <b class="k">.var</b> <u>counter</u> + <span>1</span>      <i>;redefine, same as += 1</i>
</pre></dd>

<dt><b>.from</b> &lt;scope&gt;<a name="d_from" href="#d_from"></a>
<dd>Defines a symbol to the value of the same symbol from another scope.

<p>This directive looks up the symbol name to be defined in the other scope for
its value. Useful for shorthand definitions without repeating the name if it's unchanged.</p>

<pre>
red     <b class="k">.from</b> <u>vic</u>.<u>colors</u>      <i>;same as red = vic.colors.red</i>

init    <b class="k">.from</b> <u>+</u>               <i>;expose these symbols publicly</i>
play    <b class="k">.from</b> <u>+</u>
+       <b class="k">.block</b>                <i>;other symbols hidden in block</i>
init    <b>sei</b>
...
</pre></dd>

<dt><b>.assert</b><a name="d_assert" href="#d_assert"></a>
<dt><b>.check</b><a name="d_check" href="#d_check"></a>
<dd>Do not use these, the syntax will change in next version!</dd>
</dl>

<h3>Printer control<a name="listing-control" href="#listing-control"></a></h3>

<dl class="dir">
<dt><b>.pron</b><a name="d_pron" href="#d_pron"></a>
<dt><b>.proff</b><a name="d_proff" href="#d_proff"></a>
<dd>Turn on or off source listing on part of the file.

<pre>
        <b class="k">.proff</b>           <i>;Don't put filler bytes into listing</i>
*       <b>=</b> <span>$8000</span>
        <b class="d">.fill</b> <span>$2000</span>, <span>$ff</span> <i>;Pre-fill ROM area</i>
        <b class="k">.pron</b>
*       <b>=</b> <span>$8000</span>
        <b class="d">.addr</b> <u>reset</u>, <u>restore</u>
        <b class="d">.text</b> <span class="s">"CBM80"</span>
reset   <b>cld</b>
</pre></dd>

<dt><b>.hidemac</b><a name="d_hidemac" href="#d_hidemac"></a>
<dt><b>.showmac</b><a name="d_showmac" href="#d_showmac"></a>
<dd>Ignored for compatibility.</dd>
</dl>

<hr>
<h2>Pseudo instructions<a name="pseudo-instructions" href="#pseudo-instructions"></a></h2>

<h3>Aliases<a name="aliases" href="#aliases"></a></h3>

<p>For better code readability <code>BCC</code> has an alias named <code>BLT</code>
(<b>B</b>ranch <b>L</b>ess <b>T</b>han) and <code>BCS</code> one named <code>BGE</code> (<b>B</b>ranch <b>G</b>reater <b>E</b>qual).

<pre>
        <b>cmp</b> #<span>3</span>
        <b>blt</b> <u>exit</u>        <i>; less than 3?</i>
</pre>

<p>For similar reasons <code>ASL</code> has an alias named <code>SHL</code>
(<b>SH</b>ift <b>L</b>eft) and <code>LSR</code> one named <code>SHR</code>
(<b>SH</b>ift <b>R</b>ight). This naming however is not very common.

<p>The implied variants <code>LSR</code>, <code>ROR</code>, <code>ASL</code> and <code>ROL</code> are a
shorthand for <code>LSR A</code>, <code>ROR A</code>, <code>ASL A</code> and
<code>ROL A</code>. Using the implied form is considered poor coding style.

<p>For compatibility <code>INA</code> and <code>DEA</code> are a shorthand of
<code>INC A</code> and <code>DEC A</code>. Therefore there's no <q>implied</q>
variants like <code>INC</code> or <code>DEC</code>. The full form with the
accumulator is preferred.

<p>Many illegal opcodes have aliases for compatibility as there's no standard
naming convention.

<h3>Generic instructions<a name="generic-instructions" href="#generic-instructions"></a></h3>

<p>Instructions operating on different registers have different mnemonics, for
example <code>CMP</code> and <code>CPX</code>. That makes writing code fast and
easy but sometimes it'd be nice to parametrize the register as well not just
the address. It's not like it's unsolvable through conditional compilation
directives or macro text replacement but this is an alternative.

<p>The processor registers have predefined single letter symbols like
<code>A</code>, <code>X</code> or <code>Y</code>. These can be assigned to
symbols with longer names if needed. 

<p>Parametrizing register increment and decrement instructions is
straightforward by using the register as the address similar like <code>ASL&nbsp;A</code>:</p>

<div><table width="100%" class="opcodes">
<caption>Register addressing modes of increment and decrement</caption>
<tr><td width="12%">DEA<td width="12%">DEX<td width="12%">DEY<td width="12%">DEZ<td width="12%">INA<td width="12%">INX<td width="12%">INY<td width="12%">INZ
<tr><td>DEC&nbsp;A<td>DEC&nbsp;X<td>DEC&nbsp;Y<td>DEC&nbsp;Z<td>INC&nbsp;A<td>INC&nbsp;X<td>INC&nbsp;Y<td>INC&nbsp;Z
</table></div>

<p>Push and pull instructions have a generic version called
<code>PSH</code> and <code>PUL</code>. The user stack ones for 65EL02 are
called <code>RSH</code> and <code>RUL</code>. These take a register
address:</p>

<div><table width="100%" class="opcodes">
<caption>Register parametrized push and pull instructions</caption>
<tr><td width="12%">PHA<td width="12%">PHB<td width="12%">PHD<td width="12%">PHK<td width="12%">PHP<td width="12%">PHX<td width="12%">PHY<td width="12%">PHZ
<tr><td>PSH&nbsp;A<td>PSH&nbsp;B<td>PSH&nbsp;D<td>PSH&nbsp;K<td>PSH&nbsp;P<td>PSH&nbsp;X<td>PSH&nbsp;Y<td>PSH&nbsp;Z
<tr><td>PLA<td>PLB<td>PLD<td>&nbsp;&nbsp;&nbsp;<td>PLP<td>PLX<td>PLY<td>PLZ
<tr><td>PUL&nbsp;A<td>PUL&nbsp;B<td>PUL&nbsp;D<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>PUL&nbsp;P<td>PUL&nbsp;X<td>PUL&nbsp;Y<td>PUL&nbsp;Z
<tr><td>RHA<td>RHI<td>RHX<td>RHY<td>RLA<td>RLI<td>RLX<td>RLY
<tr><td>RSH&nbsp;A<td>RSH&nbsp;I<td>RSH&nbsp;X<td>RSH&nbsp;Y<td>RUL&nbsp;A<td>RUL&nbsp;I<td>RUL&nbsp;X<td>RUL&nbsp;Y
</table></div>

<p>The parametrized version of load and store instructions are
<code>LDR</code> and <code>STR</code>, respectively. The first parameter is the
register to be used and then the regular addressing mode can be written after a coma. For
example <code>LDX&nbsp;$1000,Y</code> is equivalent to <code>LDR&nbsp;X,&nbsp;$1000,Y</code>.
It is recommended to leave a space before the addressing mode.</p>

<div><table width="100%" class="opcodes">
<caption>Register parametrized load, store and compare instructions</caption>
<tr><td width="12%">LDA<td width="12%">LDX<td width="12%">LDY<td width="12%">LDZ<td width="12%">STA<td width="12%">STX<td width="12%">STY<td width="12%">STZ
<tr><td>LDR&nbsp;A,<td>LDR&nbsp;X,<td>LDR&nbsp;Y,<td>LDR&nbsp;Z,<td>STR&nbsp;A,<td>STR&nbsp;X,<td>STR&nbsp;Y,<td>STR&nbsp;Z,
<tr><td width="12%">CPA<td width="12%">CPX<td width="12%">CPY<td width="12%">CPZ<td width="12%">&nbsp;&nbsp;&nbsp;<td width="12%">LDQ<td width="12%">STQ<td width="12%">CPQ
<tr><td>CMP&nbsp;A,<td>CMP&nbsp;X,<td>CMP&nbsp;Y,<td>CMP&nbsp;Z,<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>LDR&nbsp;Q,<td>STR&nbsp;Q,<td>CMP&nbsp;Q,
</table></div>

<p>Transfer instructions have generic versions as well, actually in two
variants. The first one is when only one of the registers need to be variable.
A register address can be used with regular load instructions to get those
setting the flags, like <code>TAX</code> which is <code>LDA&nbsp;X</code>.
Store instructions are used for those which don't, like <code>TXS</code> which
is <code>STX&nbsp;S</code>.</p>

<div><table width="100%" class="opcodes">
<caption>Register transfer parametrization through load and stores</caption>
<tr><td width="12%">TBA<td width="12%">TDC<td width="12%">TSC<td width="12%">TXA<td width="12%">TYA<td width="12%">TZA<td width="12%">&nbsp;&nbsp;&nbsp;<td width="12%">&nbsp;&nbsp;&nbsp;
<tr><td>LDA&nbsp;B<td>LDA&nbsp;D<td>LDA&nbsp;S<td>LDA&nbsp;X<td>LDA&nbsp;Y<td>LDA&nbsp;Z<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<tr><td>&nbsp;&nbsp;&nbsp;<td>TAX<td>TIX<td>TRX<td>TSX<td>TYX<td>TAY<td>TSY
<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>LDX&nbsp;A<td>LDX&nbsp;I<td>LDX&nbsp;R<td>LDX&nbsp;S<td>LDX&nbsp;Y<td>LDY&nbsp;A<td>LDY&nbsp;S
<tr><td>TXY<td>TAZ<td>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;&nbsp;<td>TAB<td>TCS<td>TXS<td>TYS
<tr><td>LDY&nbsp;X<td>LDZ&nbsp;A<td>&nbsp;&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;&nbsp;&nbsp;<td>STA&nbsp;B<td>STA&nbsp;S<td>STX&nbsp;S<td>STY&nbsp;S
</table></div>

<p>The second variant allows parametrizing both the source and target register.
This can be done with <code>LDR</code> for those setting the flags and
<code>STR</code> for those which don't. Here it's especially important to leave
a space after the coma to not create an unintended register indexing
mode.

<div><table width="100%" class="opcodes">
<caption>Register transfer fully parametrized form</caption>
<tr><td width="12%">TBA<td width="12%">TDC<td width="12%">TSC<td width="12%">TXA<td width="12%">TYA<td width="12%">TZA<td width="12%">TCD<td width="12%">TXI
<tr><td>LDR&nbsp;A,&nbsp;B<td>LDR&nbsp;A,&nbsp;D<td>LDR&nbsp;A,&nbsp;S<td>LDR&nbsp;A,&nbsp;X<td>LDR&nbsp;A,&nbsp;Y<td>LDR&nbsp;A,&nbsp;Z<td>LDR&nbsp;D,&nbsp;A<td>LDR&nbsp;I,&nbsp;X
<tr><td>TXR<td>TAX<td>TIX<td>TRX<td>TSX<td>TYX<td>TAY<td>TSY
<tr><td>LDR&nbsp;R,&nbsp;X<td>LDR&nbsp;X,&nbsp;A<td>LDR&nbsp;X,&nbsp;I<td>LDR&nbsp;X,&nbsp;R<td>LDR&nbsp;X,&nbsp;S<td>LDR&nbsp;X,&nbsp;Y<td>LDR&nbsp;Y,&nbsp;A<td>LDR&nbsp;Y,&nbsp;S
<tr><td>TXY<td>TAZ<td>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;&nbsp;<td>TAB<td>TCS<td>TXS<td>TYS
<tr><td>LDR&nbsp;Y,&nbsp;X<td>LDR&nbsp;Z,&nbsp;A<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<td>STR&nbsp;A,&nbsp;B<td>STR&nbsp;A,&nbsp;S<td>STR&nbsp;X,&nbsp;S<td>STR&nbsp;Y,&nbsp;S
</table></div>

<p>In the following subroutine has input parameters in registers.
These were given symbols and are used to load them at the call site using
<code>LDR</code>. The pointer address is a pair of registers in a tuple and is
stored with <code>STR</code>. The the <code>Y</code> register was named as
pos to show that it's possible even if it's not very useful in this case.</p>

<pre>
=$ffd2                                  out     <b>=</b> <span>$ffd2</span>

                                        *       <b>=</b> <span>$1000</span>

.1000                                   print   <b class="k">.proc</b>
=$02                                    txtp    <b>=</b> <span>$02</span>
=register("x")                          length  <b>=</b> <u>x</u>
=(register("y"),register("a"))          txtadr  <b>=</b> (<u>y</u>, <u>a</u>)
=register("y")                          pos     <b>=</b> <u>y</u>

.1000   84 02           sty $02                 <b>str</b> <u>txtadr</u>, <u>txtp</u>+(<span>0</span>, <span>1</span>)
.1002   85 03           sta $03
.1004   a0 00           ldy #$00                <b>ldr</b> <u>pos</u>, #<span>0</span>
.1006   b1 02           lda ($02),y     -       <b>lda</b> (<u>txtp</u>),<u>pos</u>
.1008   20 d2 ff        jsr $ffd2               <b>jsr</b> <u>out</u>
.100b   c8              iny                     <b>inc</b> <u>pos</u>
.100c   ca              dex                     <b>dec</b> <u>length</u>
.100d   d0 f7           bne $1006               <b>bne</b> <u>-</u>
.100f   60              rts                     <b>rts</b>
                                                <b class="k">.pend</b>

&gt;1011   52 45 41 44 59 2e               text    <b class="d">.text</b> <span class="s">"ready."</span>

.1017   a0 11           ldy #$11                <b>ldr</b> <u>print</u>.<u>txtadr</u>, #(&lt;<u>text</u>, &gt;<u>text</u>)
.1019   a9 10           lda #$10
.101b   a2 06           ldx #$06                <b>ldr</b> <u>print</u>.<u>length</u>, #<span class="k">size</span>(<u>text</u>)
.101d   20 00 10        jsr $1000               <b>jsr</b> <u>print</u>
</pre>

<p>A simpler example to push and pull multiple registers on a 65C02:</p>

<pre>
irq     <b>psh</b> (<u>a</u>, <u>x</u>, <u>y</u>,)  <i>;pha, phx, phy</i>
        ...
        <b>pul</b> (<u>y</u>, <u>x</u>, <u>a</u>,)  <i>;ply, plx, pla</i>
        <b>rti</b>
</pre>

<h3>Always taken branches<a name="branch-always" href="#branch-always"></a></h3>

<p>Special pseudo instructions exist for using shorter conditional branches in place of
longer jump instructions. Their names are derived from conditional branches and are:
<code>GEQ</code>, <code>GNE</code>, <code>GCC</code>, <code>GCS</code>,
<code>GPL</code>, <code>GMI</code>, <code>GVC</code>, <code>GVS</code>,
<code>GLT</code> and <code>GGE</code>. Arranging the flags so that these
branch are always taken is the responsibility of the programmer of course.

<p>The main use case is that these 2 byte branches automatically turn into a 3
byte <code>JMP</code> or <code>BRL</code> once the target gets too far.

<pre>
.0000   a9 03           lda #$03        in1     <b>lda</b> #<span>3</span>          <i>;not zero</i>
.0002   d0 02           bne $0006               <b>gne</b> <u>at</u>          <i>;branch always</i>
.0004   a9 02           lda #$02        in2     <b>lda</b> #<span>2</span>
.0006   4c 00 10        jmp $1000       at      <b>gne</b> <span>$1000</span>       <i>;branch farther</i>
</pre>

<p>If the branch destination is a <code>RTS</code>, <code>RTI</code> or
<code>RTL</code> instruction then this opcode will used in place of the branch to save space.
This only works if the destination label is on the same line as the return instruction.</p>

<pre>
.1000   60              rts                     <b>gne</b> <u>exit</u>        <i>;just return</i>
.1001   ea              nop                     <b>nop</b>
.1002   60              rts             exit    <b>rts</b>
</pre>

<p>There's special support for short forward branches. These only work with
labels or anonymous labels as <code>*+2</code> or hardcoded numbers would cause
a contradiction.

<p>If the branch pseudo instructions would not skip anything at all then no
code is generated. This is useful for <q>fall-through</q> cases.

<pre>
.000c                                           <b>geq</b> <u>at2</u>         <i>;dummy branch</i>
.000c   ea              nop             at2     <b>nop</b>
</pre>

<p>If the branch would skip only one byte then the opposite condition is
compiled (turns it to never taken) and only a single opcode byte is emitted. As
the following byte becomes part of the instruction it gets skipped.
<pre>
.0009   18              clc             in3     <b>clc</b>
.000a   b0              bcs                     <b>gcc</b> <u>+</u>           <i>;one byte skip</i>
.000b   38              sec             in4     <b>sec</b>             <i>;sec is skipped!</i>
.000c   ea              nop             +       <b>nop</b>
</pre>

<p>If the CPU has long conditional branches (65CE02 / 4510 / 45GS02) then the
same trick above is applied to produce two byte skips as well.

<p>There's a pseudo opcode called <code>GRA</code> for CPUs having
<code>BRA</code> which can turn into a <code>BRL</code> (if available) or
<code>JMP</code> for longer distances. The condition can't be reversed for a
one byte skip but if the CPU has a <code>NOP</code> immediate instruction
(R65C02 / W65C02) then that'll be used for this special case.

<pre>
.1000   82              nop #                   <b>gra</b> <u>skip</u>        <i>;on r65c02</i>
.1001   60              rts                     <b>rts</b>
.1002                                   skip
</pre>

<h3>Long branches<a name="branch-long" href="#branch-long"></a></h3>

<p>Conditional branches usually have limited range. This limitation can be worked around by
jumping over a <code>JMP</code> or <code>BRL</code> instruction with the opposite condition.

<p>To avoid hardcoding potentially unnecessary long branches 64tass can apply
this trick automatically when necessary. This can be enabled with the <q><a
href="#o_long-branch"><code>--long-branch</code></a></q> option.

<pre>
.0000   ea              nop                     <b>nop</b>
.0001   b0 03           bcs $0006               <b>bcc</b> <span>$1000</span>       <i>;long branch</i>
.0003   4c 00 10        jmp $1000
.0006   1f 17 03        bbr 1,$17,$000c         <b>bbs</b> <span>1</span>,<span>23</span>,<span>$1000</span>  <i>;on R65C02</i>
.0009   4c 00 10        jmp $1000
.000c   30 03           bmi $0011               <b>bpl</b> <span>$1000</span>       <i>;on 65816</i>
.000e   82 e9 lf        brl $1000
.0011   ea              nop                     <b>nop</b>
</pre>

<p>In the listing above an extra <code>JMP</code> instructions is shown for
each long branch. In practice that's not really the case as the assembler can
avoid redundant <code>JMP</code> instructions if several long branches target
the same destination. But for that to work a numeric address match alone isn't
sufficient.

<pre>
.1000   b0 03           bcs $1005               <b>bcc</b> <u>target</u>
.1002   4c 00 20        jmp $2000
.1003   ea              nop                     <b>nop</b>
.1006   d0 fb           bne $1002               <b>bne</b> <u>target</u>       <i>;jump reused</i>
.2000                                   target
</pre>

<p>If the branch destination is a <code>RTS</code>, <code>RTI</code> or
<code>RTL</code> instruction then this opcode will used in place of the jump instruction to save space.
This only works if the destination label is on the same line as the return instruction.

<pre>
.1000   b0 01           bcs $1003               <b>bcc</b> <u>exit</u>        <i>;uses rts</i>
.1002   60              rts
.1003   ea              nop                     <b>nop</b>
.2000   60              rts             exit    <b>rts</b>
</pre>

<p>It's possible to figure out without reading the listing file or disabling
the long branch function which branches were turned into long ones by using the <q><a
href="#o_Wlong-branch"><code>-Wlong-branch</code></a></q> command line option.

<p>Forcing address size using <code>@b</code> on a branch disables the
automatic long branch function there.

<hr>
<h2>Original turbo assembler compatibility<a name="tasm-compatibility" href="#tasm-compatibility"></a></h2>

<h3>How to convert source code for use with 64tass<a name="tasm-convert" href="#tasm-convert"></a></h3>

<p>Currently there are two options, either use <q>TMPview</q> by Style to convert the
source file directly, or do the following:

<ul>
<li>load turbo assembler, start (by <code>SYS 9*4096</code> or <code>SYS 8*4096</code> depending on version)</li>
<li>&larr; then l to load a source file</li>
<li>&larr; then w to write a source file in PETSCII format</li>
<li>convert the result to ASCII using petcat (from the vice package)</li>
</ul>

<p>The resulting file should then (with the restrictions below) assemble using the
following command line:

<pre>
64tass -C -T -a -W -i source.asm -o outfile.prg
</pre>

<h3>Differences to the original turbo ass macro on the C64<a name="tasm-diff" href="#tasm-diff"></a></h3>

<p>64tass is nearly 100% compatible with the original <q>Turbo Assembler</q>, and supports
most of the features of the original <q>Turbo Assembler Macro</q>.
The remaining notable differences are listed here.

<h3>Labels<a name="tasm-labels" href="#tasm-labels"></a></h3>

<p>The original turbo assembler uses case sensitive labels, use the <q><a href="#o_case-sensitive"><code>--case-sensitive</code></a></q>
command line option to enable this behaviour.

<h3>Expression evaluation<a name="tasm-expression" href="#tasm-expression"></a></h3>

<p>There are a few differences which can be worked around by the <q><a href="#o_tasm-compatible"><code>--tasm-compatible</code></a></q> command line option.
These are:

<p>The original expression parser has no operator precedence, but 64tass has. That
means that you will have to fix expressions using braces accordingly, for example
<code>1+2*3</code> becomes <code>(1+2)*3</code>.

<p>The following operators used by the original Turbo Assembler are different:

<div><table border="0">
<caption>TASM Operator differences</caption>
<tr><td width="80"><code>.</code><td>bitwise or, now <code>|</code>
<tr><td><code>:</code><td>bitwise eor, now <code>^</code>
<tr><td><code>!</code><td>force 16&nbsp;bit address, now <code>@w</code>
</table></div>

<p>The default expression evaluation is not limited to 16&nbsp;bit unsigned numbers anymore.

<h3>Macros<a name="tasm-macros" href="#tasm-macros"></a></h3>

<p>Macro parameters are referenced by <q><code>\1</code></q>&ndash;<q><code>\9</code></q> instead of using the pound sign.

<p>Parameters are always copied as text into the macro and not passed by value as the
original turbo assembler does, which sometimes may lead to unexpected behaviour. You may
need to make use of braces around arguments and/or references to fix this.

<h3>Bugs<a name="tasm-bugs" href="#tasm-bugs"></a></h3>

<p>Some versions of the original turbo assembler had bugs that are not reproduced
by 64tass, you will have to fix the code instead.

<p>In some versions labels used in the first <a href="#d_block"><code>.block</code></a> are globally available. If
you get a related error move the respective label out of the <a href="#d_block"><code>.block</code></a>.</p>

<hr>
<h2>Command line options<a name="commandline-options" href="#commandline-options"></a></h2>

<p>Short command line options consist of <q><code>-</code></q> and a letter, long options
start with <q><code>--</code></q>.

<p>If <q><code>--</code></q> is encountered then further options are not recognized and are
assumed to be file names.

<p>Options requiring file names are marked with <q>&lt;filename&gt;</q>. A
single <q><code>-</code></q> as name means standard input or output. File name quoting is
system specific.

<h3>Output options<a name="commandline-output" href="#commandline-output"></a></h3>

<dl class="dir">
<dt><b>-o</b> &lt;filename&gt;, <b>--output</b> &lt;filename&gt;<a name="o_output" href="#o_output"></a>
<dd>Place output into &lt;filename&gt;. The default output filename is <q><code>a.out</code></q>. This option changes it.

<pre>
64tass a.asm -o a.prg
</pre>

<p>This option may be used multiple times to output different sections in
different formats of a single compilation.</p>

<p>For multiple outputs the format options and output section selection must be
placed before this option. The format selection will be unchanged if no new
selection was made but the output section selection and the map file must be
repeated for each output. The maximum image size will be the smallest of all
selected formats. Using the same name multiple times is not a good idea.</p></dd>

<dt><b>--output-append</b> &lt;filename&gt;<a name="o_output-append" href="#o_output-append"></a>
<dd>Same as the <a href="#o_output"><code>--output</code></a> option but appends instead of overwrites.

<p>Normally output files are overwritten but in some cases it's useful to append them instead.</p></dd>

<dt><b>--no-output</b><a name="o_no-output" href="#o_no-output"></a>
<dd>No output file will be written.

<p>Useful for test compiles.</p></dd>

<dt><b>--map</b> &lt;file&gt;<a name="o_map" href="#o_map"></a>
<dd>Specify memory map output file.

<p>Normally the memory map is displayed on the standard output together with
other messages. It's possible to write it to a file or to the standard output
by using <q><code>-</code></q> as the file name.</p></dd>

<dt><b>--map-append</b> &lt;filename&gt;<a name="o_map-append" href="#o_map-append"></a>
<dd>Same as the <a href="#o_map"><code>--map</code></a> option but appends instead of overwrites.</dd>

<dt><b>--no-map</b><a name="o_no_map" href="#o_no_map"></a>
<dd>Do not display or record the memory map.</dd>

<dt><b>--output-section</b> &lt;sectionname&gt;<a name="o_output-section" href="#o_output-section"></a>
<dd>Specify which section to write in the output.

<p>By default all sections go into the output file. Using this option limits
the output to specific section and it's children.  This is useful to split a
larger program into several files.</p>

<pre>
64tass a.asm --output-section main -o main.prg \
             --output-section loader -o loader.prg
</pre></dd>

<dt><b>--output-exec</b> &lt;expression&gt;<a name="o_output-exec" href="#o_output-exec"></a>
<dd>Sets execution address for output formats which support this.

<p>While it's possible to enter the address as a number it's recommended to use
a label instead.</p></dd>

<dt><b>-X</b>, <b>--long-address</b><a name="o_long-address" href="#o_long-address"></a>
<dd>Use 3 byte address/length for CBM and nonlinear output instead of 2
bytes. Also increases the size of raw output to 16&nbsp;MiB and prevent the use
of S19 for S-record.

<pre>
64tass --long-address --m65816 a.asm
</pre></dd>

<dt><b>--cbm-prg</b><a name="o_cbm-prg" href="#o_cbm-prg"></a>
<dd>Generate CBM format binaries (default)

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros.  Uninitialized memory before the first and after the last valid bytes
are not saved. Up to 64&nbsp;KiB normally or 16&nbsp;MiB with the <a
href="#o_long-address"><code>--long-address</code></a> command line parameter.

<p>Used for C64 binaries. The first 2 bytes are the little endian address of
the first valid byte (load address). This is followed by the data.</p>

<pre>
64tass --cbm-prg a.asm
*       <b>=</b> <span>$2000</span>
start   <b>rts</b>
</pre>

<div><table border="0">
<caption>Example CBM format binary output</caption>
<tr><td width="100"><code>00 20</code><td>load to $2000
<tr><td><code>60</code><td>data
</table></div></dd>

<dt><b>-b</b>, <b>--nostart</b><a name="o_nostart" href="#o_nostart"></a>
<dd>Output raw binary data.

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros. Uninitialized memory before the first and after the last valid bytes are
not saved. Up to 64&nbsp;KiB normally or 16&nbsp;MiB with the <a
href="#o_long-address"><code>--long-address</code></a> command line parameter.

<p>Useful for small ROM files.</p>

<pre>
64tass --nostart a.asm
*       <b>=</b> <span>$2000</span>
        <b>rts</b>
</pre>

<div><table border="0">
<caption>Example raw output</caption>
<tr><td width="100"><code>60</code><td>data
</table></div></dd>

<dt><b>-f</b><a name="o_f"></a>, <b>--flat</b><a name="o_flat" href="#o_flat"></a>
<dd>Flat address space output mode.

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros. Uninitialized memory after the last valid byte is not saved. Up to 4&nbsp;GiB.

<p>Useful for creating huge multi bank ROM files. See sections for an example.</p></dd>

<dt><b>-n</b><a name="o_n"></a>, <b>--nonlinear</b><a name="o_nonlinear" href="#o_nonlinear"></a>
<dd>Generate nonlinear output file.

<p>Overlapping blocks are flattened. Blocks are saved in sorted order and
uninitialized memory is skipped. Up to 64&nbsp;KiB normally or 16&nbsp;MiB with the <a
href="#o_long-address"><code>--long-address</code></a> command line parameter.

<p>Used for linkers and downloading. Before writing each memory block the
length and the memory address is saved in a little endian order. Once
everything was saved a zero length block is written without an address or data.
These zeros serve as an end marker.</p>

<pre>
64tass --nonlinear a.asm
*       <b>=</b> <span>$1000</span>          <i>;1st segment</i>
        <b>lda</b> #<span>2</span>
*       <b>=</b> <span>$2000</span>          <i>;2nd segment</i>
        <b>rts</b>
</pre>

<div><table border="0">
<caption>Example 64&nbsp;KiB nonlinear output</caption>
<tr><td width="100"><code>02 00</code><td>load 2 bytes
<tr><td><code>00 10</code><td>to <code>$1000</code>
<tr><td><code>a9 02</code><td>data
<tr><td><code>01 00</code><td>load 1 byte
<tr><td><code>00 20</code><td>to <code>$2000</code>
<tr><td><code>60</code><td>data
<tr><td><code>00 00</code><td>load 0 bytes, end marker
</table></div></dd>

<dt><b>--atari-xex</b><a name="o_atari-xex" href="#o_atari-xex"></a>
<dd>Generate an Atari XEX output file.

<p>Overlapping blocks are kept, continuing blocks are concatenated. Saving
happens in the definition order without sorting, and uninitialized memory is
skipped in the output. Up to 64&nbsp;KiB.

<p>Used for Atari executables. First 2 bytes of signature is written. Then
before saving each memory block the words of load address and last byte address is
written in little endian format.

<p>If the <a href="#o_output-exec"><code>--output-exec</code></a> command line
parameter was given then a 6 byte run block is added to the end of the
output.</p>

<pre>
64tass --output-exec=start --atari-xex a.asm
*       <b>=</b> <span>$2000</span>
start   <b>rts</b>
</pre>

<div><table border="0">
<caption>Example Atari XEX format output</caption>
<tr><td width="100"><code>ff ff</code><td>header
<tr><td><code>00 20</code><td>load to <code>$2000</code>
<tr><td><code>00 20</code><td>until <code>$2000</code>
<tr><td><code>60</code><td>data
<tr><td><code>e0 02 e1 02</code><td>run marker
<tr><td><code>00 20</code><td>run address (<code>$2000</code>)
</table></div></dd>

<dt><b>--apple-ii</b><a name="o_apple-ii" href="#o_apple-ii"></a>
<dd>Generate an Apple II output file (DOS 3.3).

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros. Uninitialized memory before the first and after the last valid bytes are
not saved. Up to 64&nbsp;KiB.

<p>Used for Apple II executables. First the load address and the data length
words are written in little endian format. This is followed by the data.</p>

<pre>
64tass --apple-ii a.asm
*       <b>=</b> <span>$0c00</span>
        <b>rts</b>
</pre>

<div><table border="0">
<caption>Example of Apple II format output</caption>
<tr><td width="100"><code>00 0c</code><td>load to <code>$0c00</code>
<tr><td><code>01 00</code><td>length is 1 byte
<tr><td><code>60</code><td>data
</table></div></dd>

<dt><b>--c256-pgx</b><a name="o_c256-pgx" href="#o_c256-pgx"></a>
<dd>Generate C256 Foenix PGX output file.

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros. Uninitialized memory before the first and after the last valid bytes are
not saved. Up to 16&nbsp;MiB.

<p>Used for single segment C256 Foenix executables. After the PGX signature a
four byte little endian load address is written. This is followed by the
data.</p>

<pre>
64tass --c256-pgx a.asm
*       <b>=</b> <span>$1000</span>
        <b>rts</b>
</pre>

<div><table border="0">
<caption>Example PGX format output</caption>
<tr><td width="100"><code>50 47 58 01</code><td>PGX signature
<tr><td><code>00 10 00 00</code><td>load to <code>$1000</code>
<tr><td><code>60</code><td>data
</table></div></dd>

<dt><b>--c256-pgz</b><a name="o_c256-pgz" href="#o_c256-pgz"></a>
<dd>Generate C256 Foenix PGZ output file.

<p>Overlapping blocks are flattened. Blocks are saved in sorted order and
uninitialized memory is skipped. Up to 16&nbsp;MiB.

<p>Used for multi segment C256 Foenix binaries. It starts with a single
byte signature. Then before each memory block a three byte load address and
length is written in little endian format.

<p>If the <a href="#o_output-exec"><code>--output-exec</code></a> command line
parameter was given then a 6 byte execution block is added to the end of the output.</p>

<pre>
64tass --output-exec=start --c256-pgz a.asm
*       <b>=</b> <span>$1000</span>
start   <b>rts</b>
</pre>

<div><table border="0">
<caption>Example PGZ format output</caption>
<tr><td width="100"><code>5a</code><td>PGZ signature byte
<tr><td><code>00 10 00</code><td>load to <code>$1000</code>
<tr><td><code>01 00 00</code><td>length is 1 bytes
<tr><td><code>60</code><td>data
<tr><td><code>00 10 00</code><td>execute at <code>$1000</code>
<tr><td><code>00 00 00</code><td>execution marker
</table></div></dd>

<dt><b>--cody-bin</b><a name="o_cody-bin" href="#o_cody-bin"></a>
<dd>Generate a Cody binary output file

<p>Overlapping blocks are flattened and uninitialized memory is filled up with
zeros. Uninitialized memory before the first and after the last valid bytes are
not saved. Up to 64&nbsp;KiB.

<p>Used for Cody executables. First the load address and last byte's address
words are written in little endian format. This is followed by the data.</p>

<pre>
64tass --cody-bin a.asm
*       <b>=</b> <span>$6300</span>
        <b>nop</b>
        <b>rts</b>
</pre>

<div><table border="0">
<caption>Example of Cody format output</caption>
<tr><td width="100"><code>00 63</code><td>load to <code>$6300</code>
<tr><td><code>01 63</code><td>last byte
<tr><td><code>EA 60</code><td>data
</table></div></dd>

<dt><b>--wdc-bin</b><a name="o_wdc-bin" href="#o_wdc-bin"></a>
<dd>Generate WDC binary output file. Also known as zardoz binary.

<p>Overlapping blocks are flattened. Blocks are saved in sorted order and
uninitialized memory is skipped. Up to 16&nbsp;MiB.

<p>It starts with a single byte signature. Then before each memory block a
three byte load address and length is written in little endian format. Ends
with a zero load and start address.

<pre>
64tass --output-exec=start --wdc-bin a.asm
*       <b>=</b> <span>$1000</span>
start   <b>rts</b>
</pre>

<div><table border="0">
<caption>Example WDC binary (zardoz) format output</caption>
<tr><td width="100"><code>5a</code><td>Z signature byte
<tr><td><code>00 10 00</code><td>load to <code>$1000</code>
<tr><td><code>01 00 00</code><td>length is 1 bytes
<tr><td><code>60</code><td>data
<tr><td><code>00 00 00</code><td>end
<tr><td><code>00 00 00</code><td>marker
</table></div></dd>

<dt><b>--intel-hex</b><a name="o_intel-hex" href="#o_intel-hex"></a>
<dd>Use Intel HEX output file format.

<p>Overlapping blocks are kept, data is stored in the definition order,
and uninitialized areas are skipped. I8HEX up to 64&nbsp;KiB, I32HEX up to 4&nbsp;GiB.

<p>Used for EPROM programming or downloading. Data bytes are written using
<code>00</code> records. If the file is larger than 64&nbsp;KiB then <code>04</code>
records are used as needed. The output ends with a <code>01</code> record.

<p>If the <a href="#o_output-exec"><code>--output-exec</code></a> command line
parameter was given then a <code>05</code> record is added with the execution
address right before the end <code>01</code> record.</p>

<pre>
64tass --intel-hex a.asm
*       <b>=</b> <span>$0c00</span>
        <b>rts</b>
</pre>

<p>Example Intel HEX output:</p>

<pre>
:010C00006093
:00000001FF
</pre></dd>

<dt><b>--mos-hex</b><a name="o_mos-hex" href="#o_mos-hex"></a>
<dd>Use MOS Technology output file format. Also known as Paper Tape Format.

<p>Overlapping blocks are kept, data is stored in the definition order,
and uninitialized areas are skipped. Up to 64&nbsp;KiB.</p>

<pre>
64tass --mos-hex a.asm
*       <b>=</b> <span>$0c00</span>
        <b>rts</b>
</pre>

<p>Example MOS Technology output:</p>

<pre>
;010C0060006D
;0000010001
</pre></dd>

<dt><b>--s-record</b><a name="o_s-record" href="#o_s-record"></a>
<dd>Use Motorola S-record output file format.

<p>Overlapping blocks are kept, data is stored in the definition order,
and uninitialized memory areas are skipped. S19 up to 64&nbsp;KiB, S28 up to 16&nbsp;MiB
and S37 up to 4&nbsp;GiB.

<p>Used for EPROM programming or downloading. First a <code>S0</code> header record is
written which is followed by <code>S1</code>, <code>S2</code>, or
<code>S3</code> data records. Then an <code>S5</code> or <code>S6</code> count
record comes and a <code>S9</code>, <code>S8</code> or <code>S7</code> termination record.

<p>If the <a href="#o_output-exec"><code>--output-exec</code></a> command line
parameter was given then the termination record will use this address.
Without this the address of the first data record is used.

<p>The <a href="#o_long-address"><code>--long-address</code></a> command line
parameter can be used to avoid the use of S19 format.</p>

<pre>
64tass --s-record a.asm
*       <b>=</b> <span>$0c00</span>
        <b>rts</b>
</pre>

<p>Example Motorola S-record output:</p>

<pre>
S00600004844521B
S1040C00608F
S5030001FB
S9030C00F0
</pre></dd>
</dl>

<h3>Operation options<a name="commandline-operation" href="#commandline-operation"></a></h3>

<dl class="dir">
<dt><b>-a</b><a name="o_a"></a>, <b>--ascii</b><a name="o_ascii" href="#o_ascii"></a>
<dd>Use ASCII/Unicode text encoding instead of raw 8-bit

<p>Normally no conversion takes place, this is for backwards compatibility with
a DOS based Turbo Assembler editor, which could create PETSCII files for
6502tass. (including control characters of course)</p>

<p>Using this option will change the default <q>none</q> and <q>screen</q> encodings to
map <code>'a'&ndash;'z'</code> and <code>'A'&ndash;'Z'</code> into the correct PETSCII range of <code>$41&ndash;$5A</code> and <code>$C1&ndash;$DA</code>,
which is more suitable for an ASCII editor. It also adds predefined petcat style
PETSCII literals to the default encodings, and enables Unicode letters in symbol names.</p>

<p><b>For writing sources in UTF-8/UTF-16 encodings this option is required!</b></p>

<pre>
64tass a.asm

.0000   a9 61           lda #$61        <b>lda</b> #<span class="s">"a"</span>

&gt;0002   31 61 41                        <b class="d">.text</b> <span class="s">"1aA"</span>
&gt;0005   7b 63 6c 65 61 72 7d 74         <b class="d">.text</b> <span class="s">"{clear}text{return}more"</span>
&gt;000e   65 78 74 7b 72 65 74 75
&gt;0016   72 6e 7d 6d 6f 72 65

64tass --ascii a.asm

.0000   a9 41           lda #$41        <b>lda</b> #<span class="s">"a"</span>
&gt;0002   31 41 c1                        <b class="d">.text</b> <span class="s">"1aA"</span>
&gt;0005   93 54 45 58 54 0d 4d 4f         <b class="d">.text</b> <span class="s">"<span>{clear}</span>text<span>{return}</span>more"</span>
&gt;000e   52 45
</pre></dd>

<dt><b>-B</b>, <b>--long-branch</b><a name="o_long-branch" href="#o_long-branch"></a>
<dd>Automatic <code>BXX *+5 JMP xxx</code>. Branch too long messages are usually solved
by manually rewriting them as <code>BXX *+5 JMP xxx</code>.
64tass can do this automatically if this option is used. <code>BRA</code>
is of course not converted.

<pre>
64tass a.asm
*       <b>=</b> <span>$1000</span>
        <b>bcc</b> <span>$1233</span>       <i>;error...</i>

64tass a.asm
*       <b>=</b> <span>$1000</span>
        <b>bcs</b> *+<span>5</span>         <i>;opposite condition</i>
        <b>jmp</b> <span>$1233</span>       <i>;as simple workaround</i>

64tass --long-branch a.asm
*       <b>=</b> <span>$1000</span>
        <b>bcc</b> <span>$1233</span>       <i>;no error, automatically converted to the one above</i>
        <b>bcs</b> @b <span>$1233</span>    <i>;keep this one short regardless and fail if too far</i>
</pre></dd>

<dt><b>-C</b>, <b>--case-sensitive</b><a name="o_case-sensitive" href="#o_case-sensitive"></a>
<dd>Make all symbols (variables, opcodes, directives, operators, etc.) case
sensitive. Otherwise everything is case insensitive by default.

<pre>
64tass a.asm
label   <b>nop</b>
Label   <b>nop</b>     <i>;double defined...</i>

64tass --case-sensitive a.asm
label   <b>nop</b>
Label   <b>nop</b>     <i>;Ok, it's a different label...</i>
</pre></dd>

<dt><b>-D</b> &lt;label&gt;=&lt;value&gt;<a name="o_D" href="#o_D"></a>
<dd>Command line definition.

<p>Same syntax is allowed as in source files. Be careful with strings, the
shell might eat the quotes unless escaped.</p>

<p>Using hexadecimal numbers might be tricky as the shell might try to expand
them as variables. Either quoting or backslash escaping might help.</p>

<p>In Makefiles all $ signs need to be escaped by doubling them. This needs to
be done over the normal shell escaping. For example <q><code>$1000</code></q> becomes <q><code>\$$1000</code></q>.</p>

<pre>
64tass -D ii=2 -D var=\"string\" -D FAST:=true a.asm
        <b>lda</b> #<u>ii</u> <i>;result: $a9, $02</i>
FAST    <b>:?=</b> <span>false</span> <i>;define if undefined</i>
</pre></dd>

<dt><b>-q</b><a name="o_q"></a>, <b>--quiet</b><a name="o_quiet" href="#o_quiet"></a>
<dd>Suppress messages. Disables header and summary messages.

<pre>
64tass --quiet a.asm
</pre></dd>

<dt><b>-T</b>, <b>--tasm-compatible</b><a name="o_tasm-compatible" href="#o_tasm-compatible"></a>
<dd>Enable TASM compatible operators and precedence

<p>Switches the expression evaluator into compatibility mode. This
enables <q><code>.</code></q>, <q><code>:</code></q> and <q><code>!</code></q> operators and disables 64tass specific extensions, disables precedence handling
and forces 16&nbsp;bit unsigned evaluation (see <q>differences to original Turbo Assembler</q> below)</p></dd>

<dt><b>-I</b> &lt;path&gt;<a name="o_I" href="#o_I"></a>
<dd>Specify include search path

<p>If an included source or binary file can't be found in the directory of the
source file then this path is tried. More than one directories can be specified
by repeating this option. If multiple matches exist the first one is used.</p></dd>

<dt><b>-M</b> &lt;file&gt;, <b>--dependencies</b> &lt;file&gt;<a name="o_dependencies" href="#o_dependencies"></a>
<dd>Specify make rule output file

<p>Writes a dependency rules suitable for <q>make</q> from the list of files used during compilation.</p>

<p>Please choose source file names which are compatible with Makefiles as there
are very little escaping possibilities.</p></dd>

<dt><b>--dependencies-append</b> &lt;file&gt;<a name="o_dependencies-append" href="#o_dependencies-append"></a>
<dd>Same as the <a href="#o_dependencies"><code>--dependencies</code></a> option but appends instead of overwrites.</dd>

<dt><b>--make-phony</b><a name="o_make-phony" href="#o_make-phony"></a>
<dd>Enable phony targets for dependencies

<p>This is useful for automatic dependency generation to avoid missing target errors on file rename.</p>

<p>The following Makefile uses the rules generated by 64tass (in <q>.dep</q>)
to achieve automatic dependency tracking:</p>

<pre class="make">
<span>demo:</span> demo.asm .dep
        <span class="cmd">64tass --make-phony -M.dep</span> $&lt; <span class="cmd">-o</span> $@

<span>.dep:</span>
-<b>include</b> .dep
</pre></dd>
</dl>

<h3>Diagnostic options<a name="commandline-diagnostic" href="#commandline-diagnostic"></a></h3>

<p>Diagnostic message switched start with a <q><code>-W</code></q> and can have an optional <q><code>no-</code></q> prefix to
disable them. The options below with this prefix are enabled by default, the others are disabled.</p>

<dl class="dir">
<dt><b>-E</b> &lt;file&gt;, <b>--error</b> &lt;file&gt;<a name="o_error" href="#o_error"></a>
<dd>Specify error output file

<p>Normally compilation errors a written to the standard error output.
It's possible to redirect them to a file or to the standard output by
using <q><code>-</code></q> as the file name.</p></dd>

<dt><b>--error-append</b> &lt;filename&gt;<a name="o_error-append" href="#o_error-append"></a>
<dd>Same as the <a href="#o_error"><code>--error</code></a> option but appends instead of overwrites.</dd>

<dt><b>--no-error</b><a name="o_no_error" href="#o_no_error"></a>
<dd>Do not output any error messages, just count them.</dd>

<dt><b>-w</b>, <b>--no-warn</b><a name="o_no-warn" href="#o_no-warn"></a>
<dd>Suppress warnings.

<p>Disables warnings during compile. For fine grained diagnostic message suppression see the <a href="#commandline-diagnostic">diagnostic options</a> section.</p>

<pre>
64tass --no-warn a.asm
</pre></dd>

<dt><b>--no-caret-diag</b><a name="o_no-caret-diag" href="#o_no-caret-diag"></a>
<dd>Suppress displaying of faulty source line and fault position after
fault messages.

<p>This is for cases where the fault log is automatically processed and no one
ever looks at it and therefore there's no point to display the source lines.</p>

<pre>
64tass --no-caret-diag a.asm
</pre></dd>

<dt><b>--macro-caret-diag</b><a name="o_macro-caret-diag" href="#o_macro-caret-diag"></a>
<dd>Restrict source line and fault position display to macro expansions only.

<p>This is for cases where the fault log is processed by an editor which also
displays the compilation output somewhere. Only lines which are the result of
macro processing will be output to aid debugging. Those which would just
duplicate what's in the source editor window will be not.</p>

<pre>
64tass --macro-caret-diag a.asm
</pre></dd>

<dt><b>-Wall</b><a name="o_Wall" href="#o_Wall"></a>
<dd>Enable most diagnostic warnings, except those individually disabled. Or with the <q><code>no-</code></q> prefix disable all except those enabled.</dd>

<dt><b>-Werror</b><a name="o_Werror" href="#o_Werror"></a>
<dd>Make all diagnostic warnings to an error, except those individually set to a warning.</dd>

<dt><b>-Werror=</b>&lt;name&gt;
<dd>Change a diagnostic warning to an error.

<p>For example <q><code>-Werror=implied-reg</code></q> makes this check an error. The <q><code>-Wno-error=</code></q> variant is useful with <q><code>-Werror</code></q> to set some to warnings.</p></dd>

<dt><b>-Walias</b><a name="o_Walias" href="#o_Walias"></a>
<dd>Warns about alias opcodes.

<p>There are several opcodes for the same task, especially for the "6502i" target. This warning helps to find where their use.</p></dd>

<dt><b>-Walign</b><a name="o_Walign" href="#o_Walign"></a>
<dd>Warns when padding bytes were used for alignment.

<p>Can be used to see where space is wasted for alignment.</p></dd>

<dt><b>-Waltmode</b><a name="o_Waltmode" href="#o_Waltmode"></a>
<dd>Warn about alternative address modes.

<p>Sometimes alternative addressing modes are used as the fitting one is not
available. For example there's no lda direct page y so instead data bank y is
used with a warning.</p></dd>

<dt><b>-Wbranch-page</b><a name="o_Wbranch-page" href="#o_Wbranch-page"></a>
<dd>Warns if a branch is crossing a page.

<p>Page crossing branches execute with a penalty cycle. This option helps to locate them easily.</p></dd>

<dt><b>-Wcase-symbol</b><a name="o_Wcase-symbol" href="#o_Wcase-symbol"></a>
<dd>Warn if symbol letter case is used inconsistently.

<p>This option can be used to enforce letter case matching of symbols in case
insensitive mode. This gives similar results to the case sensitive mode (symbols
must match exactly) with the main difference of disallowing symbol name
definitions differing only in case (these are reported as duplicates).</p></dd>

<dt><b>-Wimmediate</b><a name="o_Wimmediate" href="#o_Wimmediate"></a>
<dd>Warns for cases where immediate addressing is more likely.

<p>It may be hard to notice if a <q><code>#</code></q> was missed. The code still compiles but
there's a huge difference between <q><code>cpx #const</code></q> and
<q><code>cpx const</code></q>. Unless the right sort of garbage was on zero
page at the time of testing...

<p>This check might have a lot of false positives if zero page locations are
accessed by using small numbers, which is a popular coding style. But there are
ways to reduce them.

<p>For "known" fixed locations <code>address(x)</code> can be used, preferably
bound to a symbol. Automatic allocation of zero page variables works too
(e.g. <code>zpstuff .byte ?</code>). And basically everything which is a
traditional "label" or derived from a label with an offset.</p></dd>

<dt><b>-Wimplied-reg</b><a name="o_Wimplied-reg" href="#o_Wimplied-reg"></a>
<dd>Warns if implied addressing is used instead of register.

<p>Some instructions have implied aliases like <q><code>asl</code></q>
for <q><code>asl a</code></q> for compatibility
reasons, but this shorthand is not the preferred form.</p></dd>

<dt><b>-Wleading-zeros</b><a name="o_Wleading-zeros" href="#o_Wleading-zeros"></a>
<dd>Warns if about leading zeros.

<p>A leading zero could be a prefix for an octal number but as octals
are not supported the result will be decimal.</p></dd>

<dt><b>-Wlong-branch</b><a name="o_Wlong-branch" href="#o_Wlong-branch"></a>
<dd>Warns when a long branch is used.

<p>This option gives a warning for instructions which were modified by the long branch function.
Less intrusive than disabling long branches and see where it fails.</p></dd>

<dt><b>-Wmacro-prefix</b><a name="o_Wmacro-prefix" href="#o_Wmacro-prefix"></a>
<dd>Warn about macro call without prefix.

<p>Such macro calls can easily be mistaken to be labels if invoked without parameters.
Also it's hard to notice that an unchanged call turned into label after the
definition got renamed. This warning helps to find such calls so that prefixes
can be added.</p></dd>

<dt><b>-Wno-deprecated</b><a name="o_Wdeprecated" href="#o_Wdeprecated"></a>
<dd>Don't warn about deprecated features.

<p>Unfortunately there were some features added previously which shouldn't have
been included. This option disables warnings about their uses.</p></dd>

<dt><b>-Wno-float-compare</b><a name="o_Wfloat-compare" href="#o_Wfloat-compare"></a>
<dd>Don't warn if floating point comparisons are only approximate.

<p>Floating point numbers have a finite precision and comparing them might give
unexpected results.</p>

<p>For example <code>2.1 + 0.2 == 2.3</code> is true but gives a warning as the left side
is actually bigger by approximately 4.44E&minus;16.</p>

<p>Normally this is solved by rounding or changing the comparison values.</p></dd>

<dt><b>-Wfloat-round</b><a name="o_Wfloat-round" href="#o_Wfloat-round"></a>
<dd>Warn when floating point numbers are implicitly rounded.

<p>A lot of parameters and the data dumping directives need integers but
floating point numbers are accepted as well. The style of rounding used may or
may not be what you wanted.

<p>By default floor rounding (to lower) is used and not truncate (towards
zero). The reason for this is to enable calculation of fixed point integers by
using floating point.

<p>The difference is subtle and only noticable for negative numbers. The division
of <code>-300/256</code> is <code>-2</code> which matches <code>floor(-300/256.0)</code> but not
<code>trunc(-300/256.0)</code>.

<p>To get symmetric sine waves around zero <code><a href="#f_trunc">trunc</a>()</code> needs to be used. Some other
calculation might result in <code>126.9999997</code> due to inaccuracies in logarithm which
would need <code><a href="#f_round">round</a>()</code>.

<p>To avoid unexpected rounding this option helps to find those places where no
explicit rounding was done.</p></dd>

<dt><b>-Wno-ignored</b><a name="o_Wignored" href="#o_Wignored"></a>
<dd>Don't warn about ignored directives.</dd>

<dt><b>-Wno-jmp-bug</b><a name="o_Wjmp-bug" href="#o_Wjmp-bug"></a>
<dd>Don't warn about the <code>jmp ($xxff)</code> bug.

<p>With this option it's fine that the high byte is read from the <q>wrong</q>
address on a 6502, NMOS 6502 and 65DTV02.</p>

<pre>
        <b>jmp</b> (<u>vector</u>)
        <b class="k">.alignpageind</b> <u>vector</u>, <span>256</span><i>; jmp bug workaround</i>
vector  <b class="d">.addr</b> <span>?</span>         <i>; by avoiding page cross</i>
</pre></dd>

<dt><b>-Wno-label-left</b><a name="o_Wlabel-left" href="#o_Wlabel-left"></a>
<dd>Don't warn about certain labels not being on left side.

<p>You may disable this if you use labels which look like mistyped versions of
implied addressing mode instructions and you don't want to put them in the first
column.

<p>This check is there to catch typos, unsupported implied instructions, or
unknown aliases and not for enforcing label placement.</p></dd>

<dt><b>-Wno-page</b><a name="o_Wpage" href="#o_Wpage"></a>
<dd>Ignore page assertion failures

<p>Can be used to ignore <a href="#d_page"><code>.page</code></a> assertion
block failures. As a middle ground <q><code>-Wno-error=page</code></q> can turn
the assertion to a warning only.</p></dd>

<dt><b>-Wno-pitfalls</b><a name="o_Wpitfalls" href="#o_Wpitfalls"></a>
<dd>Don't note about common pitfalls.

<p>There are some common mistakes, but experts and those who read this don't
need extra notes about them. These are:</p>

<dl>
<dt>Use multi character strings with <q><code>.byte</code></q> instead of <q><code>.text</code></q>.
<dd>This fails because <q><code>.byte</code></q> enforces the 0&ndash;255 range for each value.</dd>
<dt>Using <q><code>label *=*+1</code></q> style space reservations.
<dd>Warns as <q><code>*=</code></q> is also the compound multiply operator. The <q><code>*=*+1</code></q> needs to be on a separate line without a label. A better alternatively is to use <q><code>.fill 1</code></q> or <q><code>.byte ?</code></q>.</dd>
<dt>Negative numbers with <q><code>.byte</code></q> or <q><code>.word</code></q>
<dd>There are other directives which accept them with proper range checks like <q><code>.char</code></q>, <q><code>.sint</code></q>.</dd>
<dt>Negative numbers with <q><code>lda #xxx</code></q>
<dd>There's a signed variant for the immediate addressing so <q><code>lda #+xx</code></q> will make it work</dd>
</dl></dd>

<dt><b>-Wno-portable</b><a name="o_Wportable" href="#o_Wportable"></a>
<dd>Don't warn about source portability problems.

<p>These cross platform development annoyances are checked for:</p>

<ul>
<li>Case insensitive use of file names or use of short names.</li>
<li>Use of backslashes for path separation instead of forward slashes.</li>
<li>Use of reserved characters in file names.</li>
<li>Absolute paths</li>
</ul></dd>

<dt><b>-Wno-priority</b><a name="o_Wpriority" href="#o_Wpriority"></a>
<dd>Don't warn about operator priority problems.

<p>Not all of the unary operators are strongly binding and this may cause
surprises. This warning is intended to catch mistakes like this:</p>

<pre>
        <b class="k">.cerror</b> &gt;<u>start</u> != &gt;<u>end</u><i>; possibly wrong it's &gt;(start != (&gt;end))</i>
        <b class="k">.cerror</b> (&gt;<u>start</u>) != &gt;<u>end</u><i>; correct high byte check</i>
</pre></dd>

<dt><b>-Wno-size-larger</b><a name="o_Wsize-larger" href="#o_Wsize-larger"></a>
<dd>Don't warn if size is larger due to negative offset

<p><code><a href="#f_size">size</a>()</code> and <code><a href="#f_len">len</a>()</code> can be used to measure a memory area.
Normally there's no offset used but a positive offset may be used to reduce
available space up until nothing remains.</p>

<p>On the other hand if a negative offset is used then more space will be
available (ahead of the area) which may or may not be desired.</p>

<pre>
var     <b class="d">.byte</b> <span>?</span>, <span>?</span>, <span>?</span>
var2    <b>=</b> <u>var</u> - <span>2</span>       <i>; start 2 bytes earlier</i>
        <b>ldx</b> #<span class="k">size</span>(<u>var2</u>) <i>; size is 5 bytes as it's 2 bytes ahead</i>
</pre></dd>

<dt><b>-Wno-star-assign</b><a name="o_Wstar-assign" href="#o_Wstar-assign"></a>
<dd>Don't warn about ignored compound multiply.

<p>Normally <q><code>symbol *= ...</code></q> means compound multiply of the variable in front.
Unfortunately this looks the same a <q><code>label *=*+x</code></q> which is an old-school way to allocate space.

<p>If the symbol was a variable defined earlier then the multiply is performed without a warning.
If it's a new label definition then this warning is used to note that possibly a variable definition was missed earlier.</p>
<p>If the intention was really a label definition then the <q><code>*=</code></q>
can be moved to a separate line, or in case of space allocation it could be
improved to use <q><code>.byte ?</code></q> or <q><code>.fill x</code></q>.</p></dd>

<dt><b>-Wno-wrap-addr</b><a name="o_Wwrap-addr" href="#o_Wwrap-addr"></a>
<dd>Don't warn about memory location address space wrap around.

<p>Applying offsets to memory locations may result in addresses which end up
outside of the processors address space.

<p>For example <code>"tmp"</code> is at <code>$1000</code> and then it's
addressed as <code>lda tmp-$2000</code> then the result will be <code>lda $f000</code>
or <code>lda $fff000</code> depending on the CPU. If this is fine then this
warning can be disabled otherwise it can be made into an error by using
<code>-Werror=wrap-addr</code>.</p></dd>

<dt><b>-Wno-wrap-bank0</b><a name="o_Wwrap-bank0" href="#o_Wwrap-bank0"></a>
<dd>Don't warn for bank 0 wrap around.

<p>Adding an offset to a bank 0 address may end up outside of bank 0. If this
happens a warning is issued and the address wraps around.

<p>The warning may be ignored using this command line parameter. Alternatively
it could be turned into an error by using <code>-Werror=wrap-bank0</code>.</p></dd>

<dt><b>-Wno-wrap-dpage</b><a name="o_Wwrap-dpage" href="#o_Wwrap-dpage"></a>
<dd>Don't warn for direct page wrap around.

<p>Adding an offset to a direct page address may end up outside of the direct
page. For a 65816 or 65EL02 an alternative addressing mode is used but on other
processors if this happens a warning is issued and the address wraps
around.

<p>The warning may be ignored using this command line parameter. Alternatively
it could be turned into an error by using <code>-Werror=wrap-dpage</code>.</p></dd>

<dt><b>-Wno-wrap-mem</b><a name="o_Wwrap-mem" href="#o_Wwrap-mem"></a>
<dd>Don't warn for compile offset wrap around.

<p>While assembling the compile offset may reach the end of memory image. If
this happens a warning is issued and the compile offset is set to the start of
image.

<p>The warning may be ignored using this command line parameter. Alternatively
it could be turned into an error by using <code>-Werror=wrap-mem</code>.

<p>The image size depends on the output format. See the <a href="#commandline-output">Output options</a> section above.</p></dd>

<dt><b>-Wno-wrap-pc</b><a name="o_Wwrap-pc" href="#o_Wwrap-pc"></a>
<dd>Don't warn for program counter bank crossing.

<p>While assembling the program counter may reach the end of the current
program bank. If this happens a warning is issued as a real CPU will not cross
the bank on execution. On the other hand some addressing modes handle bank
crosses so this might not be actually a problem for data.

<p>The warning may be ignored using this command line parameter. Alternatively
it could be turned into an error by using <code>-Werror=wrap-pc</code>.</p></dd>

<dt><b>-Wno-wrap-pbank</b><a name="o_Wwrap-pbank" href="#o_Wwrap-pbank"></a>
<dd>Don't warn for program bank address calculation wrap around.

<p>Adding an offset to a program bank address may end up outside of the current
program bank. If this happens a warning is issued and the address wraps around.

<p>The warning may be ignored using this command line parameter. Alternatively
it could be turned into an error by using <code>-Werror=wrap-pbank</code>.</p></dd>

<dt><b>-Wold-equal</b><a name="o_Wold-equal" href="#o_Wold-equal"></a>
<dd>Warn about old equal operator.

<p>The single <q><code>=</code></q> operator is only there for compatibility reasons and should be written as <q><code>==</code></q> normally.</p></dd>

<dt><b>-Woptimize</b><a name="o_Woptimize" href="#o_Woptimize"></a>
<dd>Warn about optimizable code.

<p>Warns on things that could be optimized, at least according to the limited
analysis done. Currently it's easy to fool with these constructs:</p>

<ul>
<li>Self modifying code, especially modifying immediate addressing mode instructions or branch targets</li>
<li>Using <code>.byte $2c</code> and similar tricks to skip instructions.</li>
<li>Using <code>*+5</code> and similar tricks to skip instructions, or to loop like <code>*-1</code>.</li>
<li>Any other method of flow control not involving referenced labels. E.g. calculated returns.</li>
<li>Register re-mappings on 65DTV02 with SIR and SAC.</li>
<li>32 bit operations on 45GS02.</li>
</ul>

<p>It's also rather simple and conservative, so some opportunities will be
missed. Most CPUs are supported with the notable exception of 65816 and 65EL02,
but this could improve in later versions.</p></dd>

<dt><b>-Wshadow</b><a name="o_Wshadow" href="#o_Wshadow"></a>
<dd>Warn about symbol shadowing.

<p>Checks if local variables <q>shadow</q> other variables of same name in upper scopes in
ambiguous ways.

<p>This is useful to detect hard to notice bugs where a new local
variable takes the place of a global one by mistake.</p>

<pre>
bl      <b class="k">.block</b>
a       <b class="d">.byte</b> <span>2</span>         <i>;'a' is a built-in register</i>
x       <b class="d">.byte</b> <span>2</span>         <i>;'x' is a built-in register</i>
        <b>asl</b> <u>a</u>           <i>; accumulator or the byte above?</i>
        <b class="k">.end</b>
        <b>asl</b> <u>bl</u>.<u>x</u>        <i>; not ambiguous</i>
</pre></dd>

<dt><b>-Wstrict-bool</b><a name="o_Wstrict-bool" href="#o_Wstrict-bool"></a>
<dd>Warn about implicit boolean conversions.

<p>Boolean values can be interpreted as numeric 0/1 and other types as
booleans. This is convenient but may cause mistakes.

<p>To pass this option the following constructs need improvements:</p>

<ul>
<li><q><code>1</code></q> and <q><code>0</code></q> as boolean constants. Use the slightly longer <q><code>true</code></q> and <q><code>false</code></q>.</li>
<li>Implicit non-zero checks. Write it out like <q><code>.if (lbl &amp; 1) != 0</code></q>.</li>
<li>Zero checks with <q><code>!</code></q>. Write it out like <q><code>lbl == 0</code></q>.</li>
<li>Binary operators on booleans. Use the proper <q><code>||</code></q>, <q><code>&amp;&amp;</code></q> and <q><code>^^</code></q> operators.</li>
<li>Numeric expressions like <q><code>1 + (lbl &gt; 3)</code></q>. It's better as <q><code>(lbl &gt; 3) ? 2 : 1</code></q>.</li>
</ul></dd>

<dt><b>-Wunused</b><a name="o_Wunused" href="#o_Wunused"></a>
<dd>Warn about unused constant symbols.

<p>Symbols which have no references to them are likely redundant. Before
removing them check if there's any conditionally compiled out code which might
still need them.

<p>The following options can be used to be more specific:</p>

<dl class="dir">
<dt><b>-Wunused-const</b><a name="o_Wunused-const" href="#o_Wunused-const"></a>
<dd>Warn about unused constants.</dd>

<dt><b>-Wunused-label</b><a name="o_Wunused-label" href="#o_Wunused-label"></a>
<dd>Warn about unused labels.</dd>

<dt><b>-Wunused-macro</b><a name="o_Wunused-macro" href="#o_Wunused-macro"></a>
<dd>Warn about unused macros.</dd>

<dt><b>-Wunused-variable</b><a name="o_Wunused-variable" href="#o_Wunused-variable"></a>
<dd>Warn about unused variables.</dd>
</dl>

<p>Symbols which appear in a default 64tass symbol list file and their root
symbols are treated as used for exporting purposes.</p></dd>

</dl>

<h3>Target selection on command line<a name="commandline-target" href="#commandline-target"></a></h3>

<p>These options will select the default architecture. It can be overridden by
using the <q><a href="#d_cpu"><code>.cpu</code></a></q> directive in the source.</p>

<dl class="dir">
<dt><b>--m65xx</b><a name="o_m65xx" href="#o_m65xx"></a>
<dd>Standard 65xx (default). For writing compatible code, no extra codes. This
is the default.

<pre>
64tass --m65xx a.asm
        <b>lda</b> <span>$14</span>         <i>;regular instructions</i>
</pre></dd>

<dt><b>-c</b>, <b>--m65c02</b><a name="o_m65c02" href="#o_m65c02"></a>
<dd>CMOS 65C02. Enables extra opcodes and addressing modes specific to this
CPU.

<pre>
64tass --m65c02 a.asm
        <b>stz</b> <span>$d020</span>       <i>;65c02 instruction</i>
</pre></dd>

<dt><b>--m65ce02</b><a name="o_m65ce02" href="#o_m65ce02"></a>
<dd>CSG 65CE02. Enables extra opcodes and addressing modes specific to this
CPU.

<pre>
64tass --m65ce02 a.asm
        <b>inz</b>
</pre></dd>

<dt><b>-i</b>, <b>--m6502</b><a name="o_m6502" href="#o_m6502"></a>
<dd>NMOS 65xx. Enables extra illegal opcodes. Useful for demo coding for C64,
disk drive code, etc.

<pre>
64tass --m6502 a.asm
        <b>lax</b> <span>$14</span>         <i>;illegal instruction</i>
</pre></dd>

<dt><b>-t</b>, <b>--m65dtv02</b><a name="o_m65dtv02" href="#o_m65dtv02"></a>
<dd>65DTV02. Enables extra opcodes specific to DTV.

<pre>
64tass --m65dtv02 a.asm
        <b>sac</b> #<span>$00</span>
</pre></dd>

<dt><b>-x</b>, <b>--m65816</b><a name="o_m65816" href="#o_m65816"></a>
<dd>W65C816. Enables extra opcodes. Useful for SuperCPU projects.

<pre>
64tass --m65816 a.asm
        <b>lda</b> <span>$123456</span>,x
</pre></dd>

<dt><b>-e</b><a name="o_e"></a>, <b>--m65el02</b><a name="o_m65el02" href="#o_m65el02"></a>
<dd>65EL02. Enables extra opcodes, useful <a href="http://www.eloraam.com/nonwp/redcpu.php">RedPower CPU</a> projects. Probably you'll need <q><a href="#o_nostart"><code>--nostart</code></a></q> as well.

<pre>
64tass --m65el02 a.asm
        <b>lda</b> #<span>0</span>,r
</pre></dd>

<dt><b>--mr65c02</b><a name="o_mr65c02" href="#o_mr65c02"></a>
<dd>R65C02. Enables extra opcodes and addressing modes specific to this CPU.

<pre>
64tass --mr65c02 a.asm
        <b>rmb</b> <span>7</span>,<span>$20</span>
</pre></dd>

<dt><b>--mw65c02</b><a name="o_mw65c02" href="#o_mw65c02"></a>
<dd>W65C02. Enables extra opcodes and addressing modes specific to this CPU.

<pre>
64tass --mw65c02 a.asm
        <b>wai</b>
</pre></dd>

<dt><b>--m4510</b><a name="o_m4510" href="#o_m4510"></a>
<dd>CSG 4510. Enables extra opcodes and addressing modes specific to this CPU. Useful for C65 projects.

<pre>
64tass --m4510 a.asm
        <b>map</b>
        <b>eom</b>
</pre></dd>

<dt><b>--m45gs02</b><a name="o_m45gs02" href="#o_m45gs02"></a>
<dd>45GS02. Enables extra opcodes and addressing modes specific to this CPU. Useful for MEGA65 projects.

<pre>
64tass --m45gs02 a.asm
        <b>ldq</b> <span>$1000</span>
</pre></dd>
</dl>

<h3>Symbol listing<a name="commandline-symbol" href="#commandline-symbol"></a></h3>

<dl class="dir">
<dt><b>-l</b> &lt;file&gt;, <b>--labels</b>=&lt;file&gt;<a name="o_labels" href="#o_labels"></a>
<dd>List symbols into &lt;file&gt;.

<pre>
64tass -l labels.txt a.asm
*       <b>=</b> <span>$1000</span>
label   <b>jmp</b> <u>label</u>

result (labels.txt):
label           = $1000
</pre>

<p>This option may be used multiple times. In this case the format and root scope
options must be placed before this option. Using the same name multiple times is not a good idea.</p>

<pre>
64tass --vice-labels -l all.l --export-labels --labels-root=export -l myexport.inc source.asm
</pre>

<p>This writes symbols for VICE into <q>all.l</q> and symbols from scope
<q>export</q> into <q>myexport.inc</q>.</p></dd>

<dt><b>--labels-append</b>=&lt;file&gt;<a name="o_labels-append" href="#o_labels-append"></a>
<dd>Same as the <a href="#o_labels"><code>--labels</code></a> option but appends instead of overwrites.</dd>

<dt><b>--labels-root</b>=&lt;expression&gt;<a name="o_labels-root" href="#o_labels-root"></a>
<dd>Specify the scope to list labels from

<p>This option can be used to limit the output to only a subset of labels. The
parameter is an expression which must resolve to a namespace. It's usually just
the name of a label in the root scope which contains the labels to be listed.</p></dd>

<dt><b>--labels-section</b>=&lt;sectionname&gt;<a name="o_labels-section" href="#o_labels-section"></a>
<dd>Specify the section to list labels from

<p>This option can be used to limit the output to a section which code labels refer to.</p></dd>

<dt><b>--labels-add-prefix</b>=&lt;string&gt;<a name="o_labels-add-prefix" href="#o_labels-add-prefix"></a>
<dd>Add prefix to labels

<p>If defined adds a prefix to labels for some formats.</p></dd>

<dt><b>--normal-labels</b><a name="o_normal-labels" href="#o_normal-labels"></a>
<dd>Lists labels in a 64tass readable format. (default)

<p>List labels without any side effects. Usually for display purposes or for later
include.</p></dd>

<dt><b>--export-labels</b><a name="o_export-labels" href="#o_export-labels"></a>
<dd>List labels for include in a 64tass readable format.

<p>The difference to normal symbol listing is that 64tass assumes these
symbols will be used in another source. In practice this means that any
<a href="#d_proc"><code>.proc</code></a>/<a
href="#d_endproc"><code>.endproc</code></a> blocks appearing in the symbol file will
always be compiled even if unused otherwise.</p></dd>

<dt><b>--vice-labels</b><a name="o_vice-labels" href="#o_vice-labels"></a>
<dd>List labels in a VICE readable format.

<p>This format may be used to translate memory locations to something readable in
VICE monitor. Therefore simple numeric constants will not show up unless
converted to an address first.

<p>VICE symbols may only contain ASCII letters, numbers and underscore. Symbols
not meeting this requirement will be omitted.

<p>There's a good chance VICE will complain about already existing labels on
import. In the past an attempt was made to filter out such duplicates to
eliminate these warnings. However soon it was pointed out that omitted labels
are now unavailable for commands like setting breakpoints. As the latter use
case is rather more important than some bogus import warnings one has to
live with them.</p>

<pre>
64tass --vice-labels -l labels.l a.asm
*       <b>=</b> <span>$1000</span>
label   <b>jmp</b> <u>label</u>

result (labels.l):
al 1000 .label
</pre>

<p><b>For now colons are used as scope delimiter due to a VICE limitation, but
this will be changed to dots in the future.</b></p></dd>

<dt><b>--vice-labels-numeric</b><a name="o_vice-labels-numeric" href="#o_vice-labels-numeric"></a>
<dd>List address like symbols in a VICE readable format including numeric constants.

<p>The normal VICE label list does not include symbols like <code>chrout =
$ffd2</code> or <code>keybuff = 631</code> as these are numeric constants and
not memory addresses.

<p>Of course there are ways around that. For example:</p>

<pre>
chrout  <b>=</b> <span class="k">address</span>(<span>$ffd2</span>)
keybuff <b>=</b> <span class="k">address</span>(<span>631</span>)
*       <b>=</b> <span>$ffd2</span>
chrout  <b class="d">.fill</b> <span>3</span>
*       <b>=</b> <span>631</span>
keybuff <b class="d">.fill</b> <span>10</span>
</pre>

<p>For those who don't want to waste time on explicitly marking addresses as
such there's an easy way out by using this command line option.

<p>The tradeoff is that depending on the coding style the label list will become
polluted by non-address constants to various degrees. However if one mostly
uses numeric constants for addresses only this may be acceptable.</p></dd>

<dt><b>--dump-labels</b><a name="o_dump-labels" href="#o_dump-labels"></a>
<dd>List labels for debugging.

<p>The output will contain symbol locations and paths.</p></dd>

<dt><b>--simple-labels</b><a name="o_simple-labels" href="#o_simple-labels"></a>
<dd>List labels in a simple <code>label = $x</code> fashion for interoperatibility.

<p>Somewhat limited but much easier to parse than the normal output with all
it's data types.</p></dd>

<dt><b>--mesen-labels</b><a name="o_mesen-labels" href="#o_mesen-labels"></a>
<dd>List labels in Mesen format

<p>It's a text file in the following format:

<p>&lt;type&gt;:&lt;range&gt;:&lt;name&gt;</p>

<ul>
<li>type: the prefix set by the <a href="#o_labels-add-prefix"><code>--labels-add-prefix</code></a> command line option</li>
<li>range: a single hexadecimal number or two with a dash for a multibyte range</li>
<li>label: name of the label</li>
</ul>

<p>If the <a href="#o_labels-section"><code>--labels-section</code></a> command
line option was given then the range is relative to the section start.

<p>If more than one type of labels need to be listed then the <a href="#o_labels-append"><code>--labels-append</code></a> command
line option can be used to append them.</p>

<pre>
64tass --mesen-labels @labeloptions.txt a.asm

Option file (labeloptions.txt):
--labels-section=rom --labels-add-prefix=P --labels labels.mlb 
--labels-section=ram --labels-add-prefix=R --labels-append labels.mlb
--labels-section=save --labels-add-prefix=S --labels-append labels.mlb
--labels-section=work --labels-add-prefix=W --labels-append labels.mlb
--labels-section=registers --labels-add-prefix=G --labels-append labels.mlb
</pre></dd>

<dt><b>--ctags-labels</b><a name="o_ctags-labels" href="#o_ctags-labels"></a>
<dd>List labels in ctags format

<p>Can be useful to jump to global definitions if the editor supports it.</p>

</dl>

<h3>Assembly listing<a name="commandline-assembly" href="#commandline-assembly"></a></h3>

<dl class="dir">
<dt><b>-L</b> &lt;file&gt;, <b>--list</b>=&lt;file&gt;<a name="o_list" href="#o_list"></a>
<dd>List into &lt;file&gt;. Dumps source code and compiled code into file.
Useful for debugging, it's much easier to identify the code in memory within
the source files.

<pre>
; 64tass Turbo Assembler Macro V1.5x listing file
; 64tass -L list.txt a.asm
; Fri Dec  9 19:08:55 2005

;Offset ;Hex            ;Monitor        ;Source

;******  Processing input file: a.asm

.1000   a2 00           ldx #$00                ldx #0
.1002   ca              dex             loop    dex
.1003   d0 fd           bne $1002               bne loop
.1005   60              rts                     rts

;******  End of listing
</pre></dd>

<dt><b>--list-append</b>=&lt;file&gt;<a name="o_list-append" href="#o_list-append"></a>
<dd>Same as the <a href="#o_list"><code>--list</code></a> option but appends instead of overwrites.</dd>

<dt><b>-m</b>, <b>--no-monitor</b><a name="o_no-monitor" href="#o_no-monitor"></a>
<dd>Don't put monitor code into listing. There won't be any monitor listing in the list file.

<pre>
; 64tass Turbo Assembler Macro V1.5x listing file
; 64tass --no-monitor -L list.txt a.asm
; Fri Dec  9 19:11:43 2005

;Offset ;Hex            ;Source

;******  Processing input file: a.asm

.1000   a2 00                   ldx #0
.1002   ca              loop    dex
.1003   d0 fd                   bne loop
.1005   60                      rts

;******  End of listing
</pre></dd>

<dt><b>-s</b><a name="o_s"></a>, <b>--no-source</b><a name="o_no-source" href="#o_no-source"></a>
<dd>Don't put source code into listing. There won't be any source listing in the list file.

<pre>
; 64tass Turbo Assembler Macro V1.5x listing file
; 64tass --no-source -L list.txt a.asm
; Fri Dec  9 19:13:25 2005

;Offset ;Hex            ;Monitor

;******  Processing input file: a.asm

.1000   a2 00           ldx #$00
.1002   ca              dex
.1003   d0 fd           bne $1002
.1005   60              rts

;******  End of listing
</pre></dd>

<dt><b>--line-numbers</b><a name="o_line-numbers" href="#o_line-numbers"></a>

<dd>This option creates a new column for showing line numbers for easier
identification of source origin. The line number is followed with an optional colon
separated file number in case it comes from a different file then the previous lines.

<pre>
; 64tass Turbo Assembler Macro V1.5x listing file
; 64tass --line-numbers -L list.txt a.asm
; Fri Dec  9 19:13:25 2005

;Line   ;Offset ;Hex            ;Monitor        ;Source

:1      ;******  Processing input file: a.asm

3       .1000   a2 00           ldx #$00                ldx #0
4       .1002   ca              dex             loop    dex
5       .1003   d0 fd           bne $1002               bne loop
6       .1005   60              rts                     rts

;******  End of listing
</pre></dd>

<dt><b>--tab-size</b>=&lt;number&gt;<a name="o_tab-size" href="#o_tab-size"></a>

<dd>By default the listing file is using a tab size of 8 to align the
disassembly. This can be changed to other more favorable values like 4.
Only spaces are used if 1 is selected. Please note that this has
no effect on the source code on the right hand side.</dd>

<dt><b>--verbose-list</b><a name="o_verbose-list" href="#o_verbose-list"></a>

<dd>Normally the assembler tries to minimize listing output by omitting
"unimportant" lines. But sometimes it's better to just list everything
including comments and empty lines.

<pre>
; 64tass Turbo Assembler Macro V1.5x listing file
; 64tass --verbose-list -L list.txt a.asm
; Fri Dec  9 19:13:25 2005

;Offset ;Hex            ;Monitor        ;Source

;******  Processing input file: a.asm

                                        *       = $1000

.1000   a2 00           ldx #$00                ldx #0
.1002   ca              dex             loop    dex
.1003   d0 fd           bne $1002               bne loop
.1005   60              rts                     rts

;******  End of listing
</pre></dd>
</dl>

<h3>Other options<a name="commandline-other" href="#commandline-other"></a></h3>

<dl class="dir">
<dt><b>-?</b>, <b>--help</b><a name="o_help" href="#o_help"></a>
<dd>Give this help list. Prints help about command line options.</dd>

<dt><b>--usage</b><a name="o_usage" href="#o_usage"></a>
<dd>Give a short usage message. Prints short help about command line options.</dd>

<dt><b>-V</b><a name="o_V"></a>, <b>--version</b><a name="o_version" href="#o_version"></a>
<dd>Print program version</dd>
</dl>

<h3>Command line from file<a name="commandline-file" href="#commandline-file"></a></h3>

<p>Command line arguments can be read from a file as well. This is useful to store
common options for multiple files in one place or to overcome the argument list length
limitations of some systems.

<p>The filename needs to be prefixed with an at sign, so <q>@argsfile</q>
reads options from <q>argsfile</q>. It will only work if there's not another file
named <q>@argsfile</q>. The content is expanded in-place of <q>@argsfile</q>.

<p>Stored options must be separated by white space. Single or double quotes can
be used in case file names have white space in their names.

<p>Backslash can be used to escape the character following it and it must
be used to escape itself. Single and double quotes need to be escaped if
needed for string quoting.

<p>Forward slashes can be used as a portable path separation on all systems.</p>

<hr>
<h2>Messages<a name="messages" href="#messages"></a></h2>

<p>Faults and warnings encountered are sent to the standard error for logging. To
redirect them to a file use the <q><a href="#o_error"><code>-E</code></a></q> command
line option. The message format is the following:

<p>&lt;filename&gt;:&lt;line&gt;:&lt;character&gt;: &lt;severity&gt;: &lt;message&gt;

<ul>
<li>filename: The name and path of source file where the error happened.</li>
<li>line: Line number in file, starts from 1.</li>
<li>character: Character in line, starts from 1. Tabs are not expanded.</li>
<li>severity: Note, warning, error or fatal.</li>
<li>message: The fault message itself.</li>
</ul>

<p>The faulty line will be displayed after the message with a caret pointing to
the error location unless this is disabled by using <q><a
href="#o_no-caret-diag"><code>--no-caret-diag</code></a></q> option.

<pre class="diag">
<strong>a.asm:3:21: <span class="error">error:</span> not defined symbol 'label'</strong>
                 lda label
                     <strong><span class="caret">^</span></strong>
<strong>a.asm:3:21: <span class="note">note:</span></strong> searched in the global scope
</pre>

<p>This is helpful for macro expansions as it displays the processed line which usually
looks different to the one in the original source file.

<p>Error buried deep in included files or macros display a backtrace of files after an <q>In
file included from</q> text where all the files and positions involved are listed down to the main file.

<pre class="diag">
In file included from <strong>main.asm:3:3</strong>:
<strong>included.asm:2:11: <span class="error">error:</span> not defined symbol 'test'</strong>
                #macro1 test
                        <strong><span class="caret">^</span></strong>
In file included from <strong>included.asm:2:3</strong>,
                      <strong>main.asm:3:3</strong>:
<strong>macros.asm:3:7: <span class="note">note:</span></strong> original location in an expanded macro was here
                lda test
                    <strong><span class="caret">^</span></strong>
</pre>

<p>Messages ending with <q><code>[-Wxxx]</code></q> are user controllable. This means
that using <q><code>-Wno-xxx</code></q> on the command line will silence them and
<q><code>-Werror=xxx</code></q> will turn them it into a fault. See <a
href="#commandline-diagnostic">Diagnostic options</a> for more details.

<h3>Warnings<a name="messages-warnings" href="#messages-warnings"></a></h3>

<dl class="errorlist">
<dt>aligned by ? bytes<dd>alignment was necessary</dd>
<dt>approximate floating point<dd>floating point comparisons are not exact and the numbers were close but maybe not quite</dd>
<dt>bank 0 address overflow<dd>the calculated memory location address ended up outside of bank 0 and is now wrapped.</dd>
<dt>case ignored, value already handled<dd>this value was already used in an earlier case so here it's ignored</dd>
<dt>compile offset overflow<dd>compile continues at the bottom ($0000) as end of compile area was reached</dd>
<dt>constant result, possibly changeable to 'lda'<dd>a pre-calculated value could be loaded instead as the result seems to be always the same</dd>
<dt>could be shorter by using 'xxx' instead<dd>this shorter instruction gives the same result according to the optimizer</dd>
<dt>could be simpler by using 'xxx' instead<dd>this instruction gives the same result but with less dependencies according to the optimizer</dd>
<dt>deprecated directive, only for TASM compatible mode<dd>.goto and .lbl should only be used in TASM compatible mode and there are better ways to loop</dd>
<dt>deprecated equal operator, use '==' instead<dd>single equal sign for comparisons is going away soon, update source</dd>
<dt>deprecated modulo operator, use '%' instead<dd>double slash for modulo is going away soon, update source</dd>
<dt>deprecated not equal operator, use '!=' instead<dd>non-standard not equal operators which will stop working in the future, update source</dd>
<dt>direct page address overflow<dd>the calculated memory location address ended up outside of direct page and is now wrapped.</dd>
<dt>directive ignored<dd>an assembler directive was ignored for compatibility reasons</dd>
<dt>for ? variables got ? values in ?<dd>the number of variables must match the number of values when unpacking</dd>
<dt>file name uses reserved character '?'<dd>do not use \ : * ? " &lt; &gt; | in file names as some operating systems don't like these</dd>
<dt>immediate addressing mode suggested<dd>numeric constant was used as an address which was likely meant as an immediate value</dd>
<dt>implicit floating point rounding<dd>a floating point number with fractional part was used for an integer parameter</dd>
<dt>independent result, possibly changeable to 'lda'<dd>the result does not seem to depend on the input so it could be just loaded instead</dd>
<dt>instruction 'xxx' is an alias of 'xxx'<dd>an alternative instruction name was used</dd>
<dt>label defined instead of variable multiplication for compatibility<dd>move the '*=' construct to a separate line or define the variable first as this construct is ambiguous</dd>
<dt>label not on left side<dd>check if an instruction name was not mistyped and if the current CPU has it, or remove white space before label</dd>
<dt>leading zeros ignored<dd>leading zeros in front of decimals are redundant and don't denote an octal number</dd>
<dt>long branch used<dd>branch distance was too long so long branch was used (<code>bxx *+5 jmp</code>)</dd>
<dt>memory location address overflow<dd>the calculated memory location address ended up outside of the processors address space</dd>
<dt>not enough values in ?<dd>all variables in a column oriented for loop should be fed with the same amount of values</dd>
<dt>over the boundary by ? bytes, aligned by ? bytes<dd>crossed boundary so alignment was necessary</dd>
<dt>please separate @b, @w or @l from label or number for future compatibility<dd>future versions will have longer symbols after <q><code>@</code></q> and so will interpret the immediately following numbers and letters as part if the symbol. Please insert a space between <code>@b</code>, <code>@w</code> or <code>@l</code> and the following label or number now to avoid surprises!</dd>
<dt>please use format("%d", ...) as '^' will change it's meaning<dd>this operator will be changed to mean the bank byte later, please update your sources</dd>
<dt>possible jmp ($xxff) bug with argument ?<dd>some 6502 variants read don't increment the high byte on page cross and this may be unexpected</dd>
<dt>possibly redundant as ...<dd>according to the optimizer this might not be needed</dd>
<dt>possibly redundant if last 'jsr' is changed to 'jmp'<dd>tail call elimination possibility was detected</dd>
<dt>possibly redundant indexing with a constant value<dd>the index register used seems to be constant and there's a way to eliminate indexing by a constant offset</dd>
<dt>processor program counter crossed bank<dd>pc address had crossed into another 64&nbsp;KiB program bank</dd>
<dt>program bank address overflow<dd>the calculated memory location address ended up outside of the current program bank and is now wrapped.</dd>
<dt>symbol case mismatch '?'<dd>the symbol is matching case insensitively but it's not all letters are exactly the same</dd>
<dt>the file's real name is not '?'<dd>check if all characters match including their case as this is not the real name of the file</dd>
<dt>unused symbol '?'<dd>this symbol has is not referred anywhere and therefore may be unused</dd>
<dt>use '/' as path separation '?'<dd>backslash is not a path separator on all systems while forward slash will work independent of the host operating system</dd>
<dt>use relative path for '?'<dd>file's path is absolute and depends on the file system layout and the source will not compile without the exact same environment</dd>
</dl>

<h3>Errors<a name="messages-errors" href="#messages-errors"></a></h3>

<dl class="errorlist">
<dt>'?' expected<dd>something is missing</dd>
<dt>? argument is missing<dd>not enough arguments supplied</dd>
<dt>address in different program bank<dd>this instruction is only limited to access the current bank</dd>
<dt>address not in processor address space<dd>value larger than current CPU address space</dd>
<dt>address out of section<dd>moving the address around is fine as long as it does not end up before the start of the section</dd>
<dt>addressing mode too complex<dd>too much indexing or indirection for a valid address</dd>
<dt>at least one byte is needed<dd>the expression didn't yield any bytes but it's needed here</dd>
<dt>block to long for alignment by ? bytes<dd>impossible to align if larger than or equals alignment interval</dd>
<dt>branch crosses page by ? bytes<dd>page crossing was on branch was detected</dd>
<dt>branch too far by ? bytes<dd>branches have limited range and this went over by some bytes</dd>
<dt>can't calculate stable value<dd>somehow it's impossible to calculate this expression</dd>
<dt>can't calculate this<dd>could not get any value, is this a circular reference?</dd>
<dt>can't encode character '?' ($xx) in encoding '?'<dd>can't translate character in this encoding as no definition was given</dd>
<dt>can't get absolute value of<dd>not possible to calculate the absolute value of this type</dd>
<dt>can't get boolean value of<dd>not possible to determine if this value is true or false</dd>
<dt>can't get integer value of<dd>this value is not a number</dd>
<dt>can't get length of<dd>this type has no length</dd>
<dt>can't get sign of<dd>this type does not have a sign as it's not a number</dd>
<dt>can't get size of<dd>this type has no size</dd>
<dt>closing/opening directive '?' not found<dd>couldn't find the other half of block directive pair</dd>
<dt>conflict<dd>at least one feature is provided, which shouldn't be there</dd>
<dt>conversion of ? '?' to ? is not possible<dd>this type conversion can't be done</dd>
<dt>crossing of ? byte page by ? bytes<dd>the page directive detected a page cross between start and end directives</dd>
<dt>division by zero<dd>dividing with zero can't be done</dd>
<dt>double defined escape<dd>escape sequence already defined in another .edef differently</dd>
<dt>double defined range<dd>part of a character range was already defined by another .cdef and these ranges can't overlap</dd>
<dt>duplicate definition<dd>symbol defined more than once</dd>
<dt>encoded value ? larger than 8 bit<dd>the value for the end of character range for an encoding is too large</dd>
<dt>empty list not allowed<dd>at least one element is required</dd>
<dt>empty range not allowed<dd>invalid range but there must be at least one element</dd>
<dt>empty string not allowed<dd>at least one character is required</dd>
<dt>expected exactly/at least/at most ? arguments, got ?<dd>wrong number of function arguments used</dd>
<dt>expression syntax<dd>syntax error</dd>
<dt>extra characters on line<dd>there's some garbage on the end of line</dd>
<dt>floating point overflow<dd>infinity reached during a calculation</dd>
<dt>format character expected<dd>string ended before a format character was found</dd>
<dt>general syntax<dd>can't do anything with this</dd>
<dt>index out of range<dd>not enough elements in list</dd>
<dt>invalid logarithm base<dd>logarithm base should be positive and not one</dd>
<dt>key not in dictionary<dd>key not in the dictionary</dd>
<dt>label required<dd>a label is mandatory for this directive</dd>
<dt>larger than original due to negative offset<dd>if a negative offset is used the size gets larger than the original as this effectively adds bytes to the front.</dd>
<dt>last byte must not be gap<dd>.shift or .shiftl needs a normal byte at the end</dd>
<dt>logarithm of non-positive number<dd>only positive numbers have a logarithm</dd>
<dt>macro call without prefix<dd>macro call was found without a prefix and without parameters</dd>
<dt>more than a single character<dd>no more than a single character is allowed</dd>
<dt>more than two characters<dd>no more than two characters are allowed</dd>
<dt>most significant bit must be clear in byte<dd>for .shift and .shiftl only 7 bit "bytes" are valid</dd>
<dt>must be used within a loop<dd>.break or .continue must be used within a loop</dd>
<dt>must be defined later<dd>remote alignment must placed before the aligned label</dd>
<dt>negative number raised on fractional power<dd>can't calculate this</dd>
<dt>no ? addressing mode for opcode 'xxx'<dd>this addressing mode is not valid for this instruction</dd>
<dt>not a bank 0 address<dd>value must be a bank zero address</dd>
<dt>not a data bank address<dd>value must be a data bank address</dd>
<dt>not a direct page address<dd>value must be a direct page address</dd>
<dt>not a key and value pair<dd>dictionaries are built from key and value pairs separated by a colon</dd>
<dt>not a variable<dd>only variables are changeable</dd>
<dt>not defined '?'<dd>can't find this label at this point</dd>
<dt>not hashable<dd>the type can't be used as a key in a dictionary</dd>
<dt>not in range -1.0 to 1.0<dd>the function is only valid in the -1.0 to 1.0 range</dd>
<dt>not iterable<dd>value is not a list or other iterable object</dd>
<dt>not measurable as start offset beyond size of original<dd>the applied offset was larger than the original size. For example if size(data) is 2 then size(data + 1) is 1. However size(data + 3) makes no sense as there's no such thing as a negative size.</dd>
<dt>offset out of range<dd>code offset too much</dd>
<dt>operands could not be broadcast together with shapes ? and ?<dd>list length must match or must have a single element only</dd>
<dt>ptext too long by ? bytes<dd>.ptext is limited to 255 bytes maximum</dd>
<dt>requirements not met<dd>not all features are provided, at least one is missing</dd>
<dt>reserved symbol name '?'<dd>do not use this symbol name</dd>
<dt>shadow definition<dd>symbol is defined in an upper scope as well and is used ambiguously</dd>
<dt>some operation '?' of type '?' and type '?' not possible<dd>can't do this calculation with these values</dd>
<dt>square root of negative number<dd>can't calculate the square root of a negative number</dd>
<dt>start ? not on same ? byte page as end ?<dd>the endpage directive detected a mismatch of page to the page directive</dd>
<dt>too large for a ? bit signed/unsigned integer<dd>value out of range</dd>
<dt>unexpected character '?'<dd>unexpected control or Unicode character</dd>
<dt>unknown processor '?'<dd>unknown CPU name</dd>
<dt>unknown argument name '?'<dd>no parameter argument known like this</dd>
<dt>unknown format character '?'<dd>no format character known like this</dd>
<dt>use '?' instead of '?'<dd>wrong sort of character was used. For example a left double quotation mark was used instead of a regular quotation mark.</dd>
<dt>value needs to be non-negative<dd>only positive numbers or zero is accepted here</dd>
<dt>wrong type &lt;?&gt;<dd>wrong object type used</dd>
<dt>zero raised to negative power<dd>can't calculate this</dd>
<dt>zero value not allowed<dd>do not use zero for example with .null</dd>
</dl>

<h3>Fatal errors<a name="messages-fatal" href="#messages-fatal"></a></h3>

<dl class="errorlist">
<dt>can't open file<dd>cannot open file</dd>
<dt>can't write ? file '?'<dd>cannot write an output file</dd>
<dt>compilation was interrupted<dd>shows the line where the interruption happened</dd>
<dt>error reading file<dd>error while reading</dd>
<dt>file recursion<dd>wrong nesting of .include</dd>
<dt>function recursion too deep<dd>wrong use of nested functions</dd>
<dt>macro recursion too deep<dd>wrong use of nested macros</dd>
<dt>option '?' doesn't allow an argument<dd>command line option doesn't need any argument</dd>
<dt>option '?' is ambiguous<dd>command line option abbreviation is too short</dd>
<dt>option '?' not recognized<dd>no such command line option</dd>
<dt>option '?' requires an argument<dd>command line option needs an argument</dd>
<dt>out of memory<dd>won't happen ;)</dd>
<dt>section '?' for output not found<dd>the section given on command line couldn't be found</dd>
<dt>too many passes<dd>with a carefully crafted source file it's possible to create unresolvable situations but try to avoid this</dd>
<dt>unknown option '?'<dd>option not known</dd>
<dt>weak recursion<dd>excessive nesting of .weak</dd>
</dl>

<hr>
<h2>Credits<a name="credits" href="#credits"></a></h2>

<p>Original 6502tass written for DOS by Marek Matula of Taboo.

<p>It was ported to ANSI C by BigFoot/Breeze. This is when it's name changed to 64tass.

<p>Soci/Singular reworked the code over the years to the point that practically
nothing was left from original at this point.

<p>Improved TASS compatibility, PETSCII codes by Groepaz.

<p>Additional code: my_getopt command-line argument parser by Benjamin
Sittler, avl tree code by Franck Bui-Huu, ternary tree code by Daniel
Berlin, snprintf Alain Magloire, Amiga OS4 support files by Janne Per&auml;aho.

<p>Pierre Zero helped to uncover a lot of faults by fuzzing. Also there were a
lot of discussions with oziphantom about the need of various features.

<p>Main developer and maintainer: soci at c64.rulez.org</p>

<hr>
<h2>Default translation and escape sequences<a name="builtin-translations-escapes" href="#builtin-translations-escapes"></a></h2>
<h3>Raw 8-bit source<a name="translate-raw8" href="#translate-raw8"></a></h3>

<p>By default raw 8-bit encoding is used and nothing is translated or escaped.
This mode is for compiling sources which are already PETSCII.

<h4>The <q>none</q> encoding for raw 8-bit<a name="translate-raw8-none" href="#translate-raw8-none"></a></h4>

<p>Does no translation at all, no translation table, no escape sequences.

<h4>The <q>screen</q> encoding for raw 8-bit<a name="translate-raw8-screen" href="#translate-raw8-screen"></a></h4>

<p>The following translation table applies, no escape sequences.

<div><table width="100%" class="trans2">
<caption>Built-in PETSCII to PETSCII screen code translation table</caption>
<thead>
<tr><th>Input<th>Byte
<th>Input<th>Byte
<tbody>
<tr><td>00&ndash;1F<td>80&ndash;9F
<td>20&ndash;3F<td>20&ndash;3F
<tr><td>40&ndash;5F<td>00&ndash;1F
<td>60&ndash;7F<td>40&ndash;5F
<tr><td>80&ndash;9F<td>80&ndash;9F
<td>A0&ndash;BF<td>60&ndash;7F
<tr><td>C0&ndash;FE<td>40&ndash;7E
<td>FF<td>5E
</table></div>

<h3>Unicode and ASCII source<a name="translate-unicode" href="#translate-unicode"></a></h3>

<p>Unicode encoding is used when the <q><a href="#o_ascii"><code>-a</code></a></q> option is given on the command line.

<h4>The <q>none</q> encoding for Unicode<a name="translate-unicode-none" href="#translate-unicode-none"></a></h4>

<p>This is a Unicode to PETSCII mapping, including escape sequences for control codes.

<div><table width="100%" class="trans">
<caption>Built-in Unicode to PETSCII translation table</caption>
<thead>
<tr><th>Glyph<th>Unicode<th>Byte
<th>Glyph<th>Unicode<th>Byte
<tbody>
<tr><td>&nbsp;&ndash;@<td>U+0020&ndash;U+0040<td>20&ndash;40
<td>A&ndash;Z<td>U+0041&ndash;U+005A<td>C1&ndash;DA
<tr><td>[<td>U+005B<td>5B
<td>]<td>U+005D<td>5D
<tr><td>a&ndash;z<td>U+0061&ndash;U+007A<td>41&ndash;5A
<td>&#163;<td>U+00A3<td>5C
<tr><td>&#960;<td>U+03C0<td>FF
<td>&#8592;<td>U+2190<td>5F
<tr><td>&#8593;<td>U+2191<td>5E
<td>&#9472;<td>U+2500<td>C0
<tr><td>&#9474;<td>U+2502<td>DD
<td>&#9484;<td>U+250C<td>B0
<tr><td>&#9488;<td>U+2510<td>AE
<td>&#9492;<td>U+2514<td>AD
<tr><td>&#9496;<td>U+2518<td>BD
<td>&#9500;<td>U+251C<td>AB
<tr><td>&#9508;<td>U+2524<td>B3
<td>&#9516;<td>U+252C<td>B2
<tr><td>&#9524;<td>U+2534<td>B1
<td>&#9532;<td>U+253C<td>DB
<tr><td>&#9581;<td>U+256D<td>D5
<td>&#9582;<td>U+256E<td>C9
<tr><td>&#9583;<td>U+256F<td>CB
<td>&#9584;<td>U+2570<td>CA
<tr><td>&#9585;<td>U+2571<td>CE
<td>&#9586;<td>U+2572<td>CD
<tr><td>&#9587;<td>U+2573<td>D6
<td>&#9601;<td>U+2581<td>A4
<tr><td>&#9602;<td>U+2582<td>AF
<td>&#9603;<td>U+2583<td>B9
<tr><td>&#9604;<td>U+2584<td>A2
<td>&#9612;<td>U+258C<td>A1
<tr><td>&#9613;<td>U+258D<td>B5
<td>&#9614;<td>U+258E<td>B4
<tr><td>&#9615;<td>U+258F<td>A5
<td>&#9618;<td>U+2592<td>A6
<tr><td>&#9620;<td>U+2594<td>A3
<td>&#9621;<td>U+2595<td>A7
<tr><td>&#9622;<td>U+2596<td>BB
<td>&#9623;<td>U+2597<td>AC
<tr><td>&#9624;<td>U+2598<td>BE
<td>&#9626;<td>U+259A<td>BF
<tr><td>&#9629;<td>U+259D<td>BC
<td>&#9675;<td>U+25CB<td>D7
<tr><td>&#9679;<td>U+25CF<td>D1
<td>&#9700;<td>U+25E4<td>A9
<tr><td>&#9701;<td>U+25E5<td>DF
<td>&#9824;<td>U+2660<td>C1
<tr><td>&#9827;<td>U+2663<td>D8
<td>&#9829;<td>U+2665<td>D3
<tr><td>&#9830;<td>U+2666<td>DA
<td>&#10003;<td>U+2713<td>BA
<tr><td>&#129904;<td>U+1FB70<td>D4
<td>&#129905;<td>U+1FB71<td>C7
<tr><td>&#129906;<td>U+1FB72<td>C2
<td>&#129907;<td>U+1FB73<td>DD
<tr><td>&#129908;<td>U+1FB74<td>C8
<td>&#129909;<td>U+1FB75<td>D9
<tr><td>&#129910;<td>U+1FB76<td>C5
<td>&#129911;<td>U+1FB77<td>C4
<tr><td>&#129912;<td>U+1FB78<td>C3
<td>&#129913;<td>U+1FB79<td>C0
<tr><td>&#129914;<td>U+1FB7A<td>C6
<td>&#129915;<td>U+1FB7B<td>D2
<tr><td>&#129916;<td>U+1FB7C<td>CC
<td>&#129917;<td>U+1FB7D<td>CF
<tr><td>&#129918;<td>U+1FB7E<td>D0
<td>&#129919;<td>U+1FB7F<td>BA
<tr><td>&#129922;<td>U+1FB82<td>B7
<td>&#129923;<td>U+1FB83<td>B8
<tr><td>&#129927;<td>U+1FB87<td>AA
<td>&#129928;<td>U+1FB88<td>B6
<tr><td>&#129932;<td>U+1FB8C<td>DC
<td>&#129935;<td>U+1FB8F<td>A8
<tr><td>&#129941;<td>U+1FB95<td>FF
<td>&#129944;<td>U+1FB98<td>DF
<tr><td>&#129945;<td>U+1FB99<td>A9
<td><td><td>
</table></div>

<div><table width="100%" class="esc">
<caption>Built-in PETSCII escape sequences</caption>
<thead>
<tr><th>Escape<th>Byte
<th>Escape<th>Byte
<th>Escape<th>Byte
<tbody>
<tr><td>{bell}<td>07
<td>{black}<td>90
<td>{blk}<td>90
<tr><td>{blue}<td>1F
<td>{blu}<td>1F
<td>{brn}<td>95
<tr><td>{brown}<td>95
<td>{cbm-*}<td>DF
<td>{cbm-+}<td>A6
<tr><td>{cbm--}<td>DC
<td>{cbm-0}<td>30
<td>{cbm-1}<td>81
<tr><td>{cbm-2}<td>95
<td>{cbm-3}<td>96
<td>{cbm-4}<td>97
<tr><td>{cbm-5}<td>98
<td>{cbm-6}<td>99
<td>{cbm-7}<td>9A
<tr><td>{cbm-8}<td>9B
<td>{cbm-9}<td>29
<td>{cbm-@}<td>A4
<tr><td>{cbm-^}<td>DE
<td>{cbm-a}<td>B0
<td>{cbm-b}<td>BF
<tr><td>{cbm-c}<td>BC
<td>{cbm-d}<td>AC
<td>{cbm-e}<td>B1
<tr><td>{cbm-f}<td>BB
<td>{cbm-g}<td>A5
<td>{cbm-h}<td>B4
<tr><td>{cbm-i}<td>A2
<td>{cbm-j}<td>B5
<td>{cbm-k}<td>A1
<tr><td>{cbm-l}<td>B6
<td>{cbm-m}<td>A7
<td>{cbm-n}<td>AA
<tr><td>{cbm-o}<td>B9
<td>{cbm-pound}<td>A8
<td>{cbm-p}<td>AF
<tr><td>{cbm-q}<td>AB
<td>{cbm-r}<td>B2
<td>{cbm-s}<td>AE
<tr><td>{cbm-t}<td>A3
<td>{cbm-up&nbsp;arrow}<td>DE
<td>{cbm-u}<td>B8
<tr><td>{cbm-v}<td>BE
<td>{cbm-w}<td>B3
<td>{cbm-x}<td>BD
<tr><td>{cbm-y}<td>B7
<td>{cbm-z}<td>AD
<td>{clear}<td>93
<tr><td>{clr}<td>93
<td>{control-0}<td>92
<td>{control-1}<td>90
<tr><td>{control-2}<td>05
<td>{control-3}<td>1C
<td>{control-4}<td>9F
<tr><td>{control-5}<td>9C
<td>{control-6}<td>1E
<td>{control-7}<td>1F
<tr><td>{control-8}<td>9E
<td>{control-9}<td>12
<td>{control-:}<td>1B
<tr><td>{control-;}<td>1D
<td>{control-=}<td>1F
<td>{control-@}<td>00
<tr><td>{control-a}<td>01
<td>{control-b}<td>02
<td>{control-c}<td>03
<tr><td>{control-d}<td>04
<td>{control-e}<td>05
<td>{control-f}<td>06
<tr><td>{control-g}<td>07
<td>{control-h}<td>08
<td>{control-i}<td>09
<tr><td>{control-j}<td>0A
<td>{control-k}<td>0B
<td>{control-left&nbsp;arrow}<td>06
<tr><td>{control-l}<td>0C
<td>{control-m}<td>0D
<td>{control-n}<td>0E
<tr><td>{control-o}<td>0F
<td>{control-pound}<td>1C
<td>{control-p}<td>10
<tr><td>{control-q}<td>11
<td>{control-r}<td>12
<td>{control-s}<td>13
<tr><td>{control-t}<td>14
<td>{control-up&nbsp;arrow}<td>1E
<td>{control-u}<td>15
<tr><td>{control-v}<td>16
<td>{control-w}<td>17
<td>{control-x}<td>18
<tr><td>{control-y}<td>19
<td>{control-z}<td>1A
<td>{cr}<td>0D
<tr><td>{cyan}<td>9F
<td>{cyn}<td>9F
<td>{delete}<td>14
<tr><td>{del}<td>14
<td>{dish}<td>08
<td>{down}<td>11
<tr><td>{ensh}<td>09
<td>{esc}<td>1B
<td>{f10}<td>82
<tr><td>{f11}<td>84
<td>{f12}<td>8F
<td>{f1}<td>85
<tr><td>{f2}<td>89
<td>{f3}<td>86
<td>{f4}<td>8A
<tr><td>{f5}<td>87
<td>{f6}<td>8B
<td>{f7}<td>88
<tr><td>{f8}<td>8C
<td>{f9}<td>80
<td>{gray1}<td>97
<tr><td>{gray2}<td>98
<td>{gray3}<td>9B
<td>{green}<td>1E
<tr><td>{grey1}<td>97
<td>{grey2}<td>98
<td>{grey3}<td>9B
<tr><td>{grn}<td>1E
<td>{gry1}<td>97
<td>{gry2}<td>98
<tr><td>{gry3}<td>9B
<td>{help}<td>84
<td>{home}<td>13
<tr><td>{insert}<td>94
<td>{inst}<td>94
<td>{lblu}<td>9A
<tr><td>{left&nbsp;arrow}<td>5F
<td>{left}<td>9D
<td>{lf}<td>0A
<tr><td>{lgrn}<td>99
<td>{lower&nbsp;case}<td>0E
<td>{lred}<td>96
<tr><td>{lt&nbsp;blue}<td>9A
<td>{lt&nbsp;green}<td>99
<td>{lt&nbsp;red}<td>96
<tr><td>{orange}<td>81
<td>{orng}<td>81
<td>{pi}<td>FF
<tr><td>{pound}<td>5C
<td>{purple}<td>9C
<td>{pur}<td>9C
<tr><td>{red}<td>1C
<td>{return}<td>0D
<td>{reverse&nbsp;off}<td>92
<tr><td>{reverse&nbsp;on}<td>12
<td>{rght}<td>1D
<td>{right}<td>1D
<tr><td>{run}<td>83
<td>{rvof}<td>92
<td>{rvon}<td>12
<tr><td>{rvs&nbsp;off}<td>92
<td>{rvs&nbsp;on}<td>12
<td>{shift&nbsp;return}<td>8D
<tr><td>{shift-*}<td>C0
<td>{shift-+}<td>DB
<td>{shift-,}<td>3C
<tr><td>{shift--}<td>DD
<td>{shift-.}<td>3E
<td>{shift-/}<td>3F
<tr><td>{shift-0}<td>30
<td>{shift-1}<td>21
<td>{shift-2}<td>22
<tr><td>{shift-3}<td>23
<td>{shift-4}<td>24
<td>{shift-5}<td>25
<tr><td>{shift-6}<td>26
<td>{shift-7}<td>27
<td>{shift-8}<td>28
<tr><td>{shift-9}<td>29
<td>{shift-:}<td>5B
<td>{shift-;}<td>5D
<tr><td>{shift-@}<td>BA
<td>{shift-^}<td>DE
<td>{shift-a}<td>C1
<tr><td>{shift-b}<td>C2
<td>{shift-c}<td>C3
<td>{shift-d}<td>C4
<tr><td>{shift-e}<td>C5
<td>{shift-f}<td>C6
<td>{shift-g}<td>C7
<tr><td>{shift-h}<td>C8
<td>{shift-i}<td>C9
<td>{shift-j}<td>CA
<tr><td>{shift-k}<td>CB
<td>{shift-l}<td>CC
<td>{shift-m}<td>CD
<tr><td>{shift-n}<td>CE
<td>{shift-o}<td>CF
<td>{shift-pound}<td>A9
<tr><td>{shift-p}<td>D0
<td>{shift-q}<td>D1
<td>{shift-r}<td>D2
<tr><td>{shift-space}<td>A0
<td>{shift-s}<td>D3
<td>{shift-t}<td>D4
<tr><td>{shift-up&nbsp;arrow}<td>DE
<td>{shift-u}<td>D5
<td>{shift-v}<td>D6
<tr><td>{shift-w}<td>D7
<td>{shift-x}<td>D8
<td>{shift-y}<td>D9
<tr><td>{shift-z}<td>DA
<td>{space}<td>20
<td>{sret}<td>8D
<tr><td>{stop}<td>03
<td>{swlc}<td>0E
<td>{swuc}<td>8E
<tr><td>{tab}<td>09
<td>{up&nbsp;arrow}<td>5E
<td>{up/lo&nbsp;lock off}<td>09
<tr><td>{up/lo&nbsp;lock on}<td>08
<td>{upper&nbsp;case}<td>8E
<td>{up}<td>91
<tr><td>{white}<td>05
<td>{wht}<td>05
<td>{yellow}<td>9E
<tr><td>{yel}<td>9E
<td><td>
<td><td>
</table></div>

<h4>The <q>screen</q> encoding for Unicode<a name="translate-unicode-screen" href="#translate-unicode-screen"></a></h4>

<p>This is a Unicode to PETSCII screen code mapping, including escape sequences for control code screen codes.

<div><table width="100%" class="trans">
<caption>Built-in Unicode to PETSCII screen code translation table</caption>
<thead>
<tr><th>Glyph<th>Unicode<th>Translated
<th>Glyph<th>Unicode<th>Translated
<tbody>
<tr><td>&nbsp;&ndash;?<td>U+0020&ndash;U+003F<td>20&ndash;3F
<td>@<td>U+0040<td>00
<tr><td>A&ndash;Z<td>U+0041&ndash;U+005A<td>41&ndash;5A
<td>[<td>U+005B<td>1B
<tr><td>]<td>U+005D<td>1D
<td>a&ndash;z<td>U+0061&ndash;U+007A<td>01&ndash;1A
<tr><td>&#163;<td>U+00A3<td>1C
<td>&#960;<td>U+03C0<td>5E
<tr><td>&#8592;<td>U+2190<td>1F
<td>&#8593;<td>U+2191<td>1E
<tr><td>&#9472;<td>U+2500<td>40
<td>&#9474;<td>U+2502<td>5D
<tr><td>&#9484;<td>U+250C<td>70
<td>&#9488;<td>U+2510<td>6E
<tr><td>&#9492;<td>U+2514<td>6D
<td>&#9496;<td>U+2518<td>7D
<tr><td>&#9500;<td>U+251C<td>6B
<td>&#9508;<td>U+2524<td>73
<tr><td>&#9516;<td>U+252C<td>72
<td>&#9524;<td>U+2534<td>71
<tr><td>&#9532;<td>U+253C<td>5B
<td>&#9581;<td>U+256D<td>55
<tr><td>&#9582;<td>U+256E<td>49
<td>&#9583;<td>U+256F<td>4B
<tr><td>&#9584;<td>U+2570<td>4A
<td>&#9585;<td>U+2571<td>4E
<tr><td>&#9586;<td>U+2572<td>4D
<td>&#9587;<td>U+2573<td>56
<tr><td>&#9601;<td>U+2581<td>64
<td>&#9602;<td>U+2582<td>6F
<tr><td>&#9603;<td>U+2583<td>79
<td>&#9604;<td>U+2584<td>62
<tr><td>&#9612;<td>U+258C<td>61
<td>&#9613;<td>U+258D<td>75
<tr><td>&#9614;<td>U+258E<td>74
<td>&#9615;<td>U+258F<td>65
<tr><td>&#9618;<td>U+2592<td>66
<td>&#9620;<td>U+2594<td>63
<tr><td>&#9621;<td>U+2595<td>67
<td>&#9622;<td>U+2596<td>7B
<tr><td>&#9623;<td>U+2597<td>6C
<td>&#9624;<td>U+2598<td>7E
<tr><td>&#9626;<td>U+259A<td>7F
<td>&#9629;<td>U+259D<td>7C
<tr><td>&#9675;<td>U+25CB<td>57
<td>&#9679;<td>U+25CF<td>51
<tr><td>&#9700;<td>U+25E4<td>69
<td>&#9701;<td>U+25E5<td>5F
<tr><td>&#9824;<td>U+2660<td>41
<td>&#9827;<td>U+2663<td>58
<tr><td>&#9829;<td>U+2665<td>53
<td>&#9830;<td>U+2666<td>5A
<tr><td>&#10003;<td>U+2713<td>7A
<td>&#129904;<td>U+1FB70<td>54
<tr><td>&#129905;<td>U+1FB71<td>47
<td>&#129906;<td>U+1FB72<td>42
<tr><td>&#129907;<td>U+1FB73<td>5D
<td>&#129908;<td>U+1FB74<td>48
<tr><td>&#129909;<td>U+1FB75<td>59
<td>&#129910;<td>U+1FB76<td>45
<tr><td>&#129911;<td>U+1FB77<td>44
<td>&#129912;<td>U+1FB78<td>43
<tr><td>&#129913;<td>U+1FB79<td>40
<td>&#129914;<td>U+1FB7A<td>46
<tr><td>&#129915;<td>U+1FB7B<td>52
<td>&#129916;<td>U+1FB7C<td>4C
<tr><td>&#129917;<td>U+1FB7D<td>4F
<td>&#129918;<td>U+1FB7E<td>50
<tr><td>&#129919;<td>U+1FB7F<td>7A
<td>&#129922;<td>U+1FB82<td>77
<tr><td>&#129923;<td>U+1FB83<td>78
<td>&#129927;<td>U+1FB87<td>6A
<tr><td>&#129928;<td>U+1FB88<td>76
<td>&#129932;<td>U+1FB8C<td>5C
<tr><td>&#129935;<td>U+1FB8F<td>68
<td>&#129941;<td>U+1FB95<td>5E
<tr><td>&#129944;<td>U+1FB98<td>5F
<td>&#129945;<td>U+1FB99<td>69
</table></div>

<div><table width="100%" class="esc">
<caption>Built-in PETSCII screen code escape sequences</caption>
<thead>
<tr><th>Escape<th>Byte
<th>Escape<th>Byte
<th>Escape<th>Byte
<tbody>
<tr><td>{cbm-*}<td>5F
<td>{cbm-+}<td>66
<td>{cbm--}<td>5C
<tr><td>{cbm-0}<td>30
<td>{cbm-9}<td>29
<td>{cbm-@}<td>64
<tr><td>{cbm-^}<td>5E
<td>{cbm-a}<td>70
<td>{cbm-b}<td>7F
<tr><td>{cbm-c}<td>7C
<td>{cbm-d}<td>6C
<td>{cbm-e}<td>71
<tr><td>{cbm-f}<td>7B
<td>{cbm-g}<td>65
<td>{cbm-h}<td>74
<tr><td>{cbm-i}<td>62
<td>{cbm-j}<td>75
<td>{cbm-k}<td>61
<tr><td>{cbm-l}<td>76
<td>{cbm-m}<td>67
<td>{cbm-n}<td>6A
<tr><td>{cbm-o}<td>79
<td>{cbm-pound}<td>68
<td>{cbm-p}<td>6F
<tr><td>{cbm-q}<td>6B
<td>{cbm-r}<td>72
<td>{cbm-s}<td>6E
<tr><td>{cbm-t}<td>63
<td>{cbm-up&nbsp;arrow}<td>5E
<td>{cbm-u}<td>78
<tr><td>{cbm-v}<td>7E
<td>{cbm-w}<td>73
<td>{cbm-x}<td>7D
<tr><td>{cbm-y}<td>77
<td>{cbm-z}<td>6D
<td>{left&nbsp;arrow}<td>1F
<tr><td>{pi}<td>5E
<td>{pound}<td>1C
<td>{shift-*}<td>40
<tr><td>{shift-+}<td>5B
<td>{shift-,}<td>3C
<td>{shift--}<td>5D
<tr><td>{shift-.}<td>3E
<td>{shift-/}<td>3F
<td>{shift-0}<td>30
<tr><td>{shift-1}<td>21
<td>{shift-2}<td>22
<td>{shift-3}<td>23
<tr><td>{shift-4}<td>24
<td>{shift-5}<td>25
<td>{shift-6}<td>26
<tr><td>{shift-7}<td>27
<td>{shift-8}<td>28
<td>{shift-9}<td>29
<tr><td>{shift-:}<td>1B
<td>{shift-;}<td>1D
<td>{shift-@}<td>7A
<tr><td>{shift-^}<td>5E
<td>{shift-a}<td>41
<td>{shift-b}<td>42
<tr><td>{shift-c}<td>43
<td>{shift-d}<td>44
<td>{shift-e}<td>45
<tr><td>{shift-f}<td>46
<td>{shift-g}<td>47
<td>{shift-h}<td>48
<tr><td>{shift-i}<td>49
<td>{shift-j}<td>4A
<td>{shift-k}<td>4B
<tr><td>{shift-l}<td>4C
<td>{shift-m}<td>4D
<td>{shift-n}<td>4E
<tr><td>{shift-o}<td>4F
<td>{shift-pound}<td>69
<td>{shift-p}<td>50
<tr><td>{shift-q}<td>51
<td>{shift-r}<td>52
<td>{shift-space}<td>60
<tr><td>{shift-s}<td>53
<td>{shift-t}<td>54
<td>{shift-up&nbsp;arrow}<td>5E
<tr><td>{shift-u}<td>55
<td>{shift-v}<td>56
<td>{shift-w}<td>57
<tr><td>{shift-x}<td>58
<td>{shift-y}<td>59
<td>{shift-z}<td>5A
<tr><td>{space}<td>20
<td>{up&nbsp;arrow}<td>1E
<td><td>
</table></div>

<hr>
<h2>Opcodes<a name="opcodes" href="#opcodes"></a></h2>

<h3>Standard 6502 opcodes<a name="opcodes-6502" href="#opcodes-6502"></a></h3>

<div><table width="100%" class="opcodes">
<caption>The standard 6502 opcodes</caption>
<tr><th width="4%">ADC<td width="46%">61 65 69 6D 71 75 79 7D
<th width="4%">AND<td width="46%">21 25 29 2D 31 35 39 3D
<tr><th>ASL<td>06 0A 0E 16 1E
<th>BCC<td>90
<tr><th>BCS<td>B0
<th>BEQ<td>F0
<tr><th>BIT<td>24 2C
<th>BMI<td>30
<tr><th>BNE<td>D0
<th>BPL<td>10
<tr><th>BRK<td>00
<th>BVC<td>50
<tr><th>BVS<td>70
<th>CLC<td>18
<tr><th>CLD<td>D8
<th>CLI<td>58
<tr><th>CLV<td>B8
<th>CMP<td>C1 C5 C9 CD D1 D5 D9 DD
<tr><th>CPX<td>E0 E4 EC
<th>CPY<td>C0 C4 CC
<tr><th>DEC<td>C6 CE D6 DE
<th>DEX<td>CA
<tr><th>DEY<td>88
<th>EOR<td>41 45 49 4D 51 55 59 5D
<tr><th>INC<td>E6 EE F6 FE
<th>INX<td>E8
<tr><th>INY<td>C8
<th>JMP<td>4C 6C
<tr><th>JSR<td>20
<th>LDA<td>A1 A5 A9 AD B1 B5 B9 BD
<tr><th>LDX<td>A2 A6 AE B6 BE
<th>LDY<td>A0 A4 AC B4 BC
<tr><th>LSR<td>46 4A 4E 56 5E
<th>NOP<td>EA
<tr><th>ORA<td>01 05 09 0D 11 15 19 1D
<th>PHA<td>48
<tr><th>PHP<td>08
<th>PLA<td>68
<tr><th>PLP<td>28
<th>ROL<td>26 2A 2E 36 3E
<tr><th>ROR<td>66 6A 6E 76 7E
<th>RTI<td>40
<tr><th>RTS<td>60
<th>SBC<td>E1 E5 E9 ED F1 F5 F9 FD
<tr><th>SEC<td>38
<th>SED<td>F8
<tr><th>SEI<td>78
<th>STA<td>81 85 8D 91 95 99 9D
<tr><th>STX<td>86 8E 96
<th>STY<td>84 8C 94
<tr><th>TAX<td>AA
<th>TAY<td>A8
<tr><th>TSX<td>BA
<th>TXA<td>8A
<tr><th>TXS<td>9A
<th>TYA<td>98
</table></div>

<div><table width="100%" class="opcodes">
<caption>6502 aliases, pseudo instructions</caption>
<tr><th width="4%">ASL<td width="46%">0A
<th width="4%">BGE<td width="46%">B0
<tr><th>BLT<td>90
<th>CMP<td>C0 C4 CC E0 E4 EC
<tr><th>CPA<td>C1 C5 C9 CD D1 D5 D9 DD
<th>GCC<td>4C 90
<tr><th>GCS<td>4C B0
<th>GEQ<td>4C F0
<tr><th>GGE<td>4C B0
<th>GLT<td>4C 90
<tr><th>GMI<td>30 4C
<th>GNE<td>4C D0
<tr><th>GPL<td>10 4C
<th>GVC<td>4C 50
<tr><th>GVS<td>4C 70
<th>LDR<td>8A 98 A0 A1 A2 A4 A5 A6 A8 A9 AA AC AD AE B1 B4 B5 B6 B9 BA BC BD BE
<tr><th>LSR<td>4A
<th>ORR<td>01 05 09 0D 11 15 19 1D
<tr><th>PSH<td>08 48
<th>PUL<td>28 68
<tr><th>ROL<td>2A
<th>ROR<td>6A
<tr><th>SHL<td>06 0A 0E 16 1E
<th>SHR<td>46 4A 4E 56 5E
<tr><th>STR<td>81 84 85 86 8C 8D 8E 91 94 95 96 99 9A 9D
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<h3>6502 illegal opcodes<a name="opcodes-6502i" href="#opcodes-6502i"></a></h3>

<p>This processor is a standard 6502 with the NMOS illegal opcodes.

<div><table width="100%" class="opcodes">
<caption>Additional NMOS 6502 opcodes</caption>
<tr><th width="4%">ANC<td width="46%">0B
<th width="4%">ANE<td width="46%">8B
<tr><th>ARR<td>6B
<th>ASR<td>4B
<tr><th>DCP<td>C3 C7 CF D3 D7 DB DF
<th>ISB<td>E3 E7 EF F3 F7 FB FF
<tr><th>JAM<td>02
<th>LAX<td>A3 A7 AB AF B3 B7 BF
<tr><th>LDS<td>BB
<th>NOP<td>04 0C 14 1C 80
<tr><th>RLA<td>23 27 2F 33 37 3B 3F
<th>RRA<td>63 67 6F 73 77 7B 7F
<tr><th>SAX<td>83 87 8F 97
<th>SBX<td>CB
<tr><th>SHA<td>93 9F
<th>SHS<td>9B
<tr><th>SHX<td>9E
<th>SHY<td>9C
<tr><th>SLO<td>03 07 0F 13 17 1B 1F
<th>SRE<td>43 47 4F 53 57 5B 5F
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional NMOS 6502 aliases</caption>
<tr><th width="4%">AHX<td width="46%">93 9F
<th width="4%">ALR<td width="46%">4B
<tr><th>AXS<td>CB
<th>DCM<td>C3 C7 CF D3 D7 DB DF
<tr><th>INS<td>E3 E7 EF F3 F7 FB FF
<th>ISC<td>E3 E7 EF F3 F7 FB FF
<tr><th>LAE<td>BB
<th>LAS<td>BB
<tr><th>LXA<td>AB
<th>TAS<td>9B
<tr><th>XAA<td>8B
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<h3>65DTV02 opcodes<a name="opcodes-65dtv02" href="#opcodes-65dtv02"></a></h3>

<p>This processor is an enhanced version of standard 6502 with some illegal opcodes.

<div><table width="100%" class="opcodes">
<caption>Additional 65DTV02 opcodes</caption>
<tr><th width="4%">BRA<td width="46%">12
<th width="4%">SAC<td width="46%">32
<tr><th>SIR<td>42
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 65DTV02 pseudo instructions</caption>
<tr><th width="4%">GRA<td width="46%">12 4C
<th width="4%">&nbsp;&nbsp;&nbsp;<td width="46%">&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>These illegal opcodes are not valid</caption>
<tr><th width="4%">ANC<td width="46%">0B
<th width="4%">JAM<td width="46%">02
<tr><th>LDS<td>BB
<th>NOP<td>04 0C 14 1C 80
<tr><th>SBX<td>CB
<th>SHA<td>93 9F
<tr><th>SHS<td>9B
<th>SHX<td>9E
<tr><th>SHY<td>9C
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>These aliases are not valid</caption>
<tr><th width="4%">AHX<td width="46%">93 9F
<th width="4%">AXS<td width="46%">CB
<tr><th>LAE<td>BB
<th>LAS<td>BB
<tr><th>TAS<td>9B
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<h3>Standard 65C02 opcodes<a name="opcodes-65c02" href="#opcodes-65c02"></a></h3>

<p>This processor is an enhanced version of standard 6502.

<div><table width="100%" class="opcodes">
<caption>Additional 65C02 opcodes</caption>
<tr><th width="4%">ADC<td width="46%">72
<th width="4%">AND<td width="46%">32
<tr><th>BIT<td>34 3C 89
<th>BRA<td>80
<tr><th>CMP<td>D2
<th>DEC<td>3A
<tr><th>EOR<td>52
<th>INC<td>1A
<tr><th>JMP<td>7C
<th>LDA<td>B2
<tr><th>ORA<td>12
<th>PHX<td>DA
<tr><th>PHY<td>5A
<th>PLX<td>FA
<tr><th>PLY<td>7A
<th>SBC<td>F2
<tr><th>STA<td>92
<th>STZ<td>64 74 9C 9E
<tr><th>TRB<td>14 1C
<th>TSB<td>04 0C
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 65C02 aliases and pseudo instructions</caption>
<tr><th width="4%">CLR<td width="46%">64 74 9C 9E
<th width="4%">CPA<td width="46%">D2
<tr><th>DEA<td>3A
<th>GRA<td>4C 80
<tr><th>INA<td>1A
<th>LDR<td>B2
<tr><th>ORR<td>12
<th>PSH<td>5A DA
<tr><th>PUL<td>7A FA
<th>STR<td>64 74 92 9C 9E
</table></div>

<h3>R65C02 opcodes<a name="opcodes-r65c02" href="#opcodes-r65c02"></a></h3>

<p>This processor is an enhanced version of standard 65C02.

<p>Please note that the bit number is not part of the instruction name (like
<code>RMB7 $20</code>). Instead it's the first element of coma separated
parameters (e.g. <code>RMB 7,$20</code>).

<div><table width="100%" class="opcodes">
<caption>Additional R65C02 opcodes over 65C02</caption>
<tr><th width="4%">BBR<td width="46%">0F 1F 2F 3F 4F 5F 6F 7F
<th width="4%">BBS<td width="46%">8F 9F AF BF CF DF EF FF
<tr><th>NOP<td>44 54 82 DC
<th>RMB<td>07 17 27 37 47 57 67 77
<tr><th>SMB<td>87 97 A7 B7 C7 D7 E7 F7
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<h3>W65C02 opcodes<a name="opcodes-w65c02" href="#opcodes-w65c02"></a></h3>

<p>This processor is an enhanced version of R65C02.

<div><table width="100%" class="opcodes">
<caption>Additional W65C02 opcodes over R65C02</caption>
<tr><th width="4%">STP<td width="46%">DB
<th width="4%">WAI<td width="46%">CB
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional W65C02 aliases over R65C02</caption>
<tr><th width="4%">HLT<td width="46%">DB
<th width="4%">&nbsp;&nbsp;&nbsp;<td width="46%">&nbsp;&nbsp;
</table></div>

<h3>W65816 opcodes<a name="opcodes-w65816" href="#opcodes-w65816"></a></h3>

<p>This processor is an enhanced version of 65C02.

<div><table width="100%" class="opcodes">
<caption>Additional W65816 opcodes over 65C02</caption>
<tr><th width="4%">ADC<td width="46%">63 67 6F 73 77 7F
<th width="4%">AND<td width="46%">23 27 2F 33 37 3F
<tr><th>BRL<td>82
<th>CMP<td>C3 C7 CF D3 D7 DF
<tr><th>COP<td>02
<th>EOR<td>43 47 4F 53 57 5F
<tr><th>JMP<td>5C DC
<th>JSL<td>22
<tr><th>JSR<td>FC
<th>LDA<td>A3 A7 AF B3 B7 BF
<tr><th>MVN<td>54
<th>MVP<td>44
<tr><th>ORA<td>03 07 0F 13 17 1F
<th>PEA<td>F4
<tr><th>PEI<td>D4
<th>PER<td>62
<tr><th>PHB<td>8B
<th>PHD<td>0B
<tr><th>PHK<td>4B
<th>PLB<td>AB
<tr><th>PLD<td>2B
<th>REP<td>C2
<tr><th>RTL<td>6B
<th>SBC<td>E3 E7 EF F3 F7 FF
<tr><th>SEP<td>E2
<th>STA<td>83 87 8F 93 97 9F
<tr><th>STP<td>DB
<th>TCD<td>5B
<tr><th>TCS<td>1B
<th>TDC<td>7B
<tr><th>TSC<td>3B
<th>TXY<td>9B
<tr><th>TYX<td>BB
<th>WAI<td>CB
<tr><th>WDM<td>42
<th>XBA<td>EB
<tr><th>XCE<td>FB
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional W65816 aliases over 65C02</caption>
<tr><th width="4%">CLP<td width="46%">C2
<th width="4%">CPA<td width="46%">C3 C7 CF D3 D7 DF
<tr><th>CSP<td>02
<th>HLT<td>DB
<tr><th>JML<td>5C DC
<th>LDR<td>3B 7B 9B A3 A7 AF B3 B7 BB BF
<tr><th>ORR<td>03 07 0F 13 17 1F
<th>PSH<td>0B 4B 8B D4 F4
<tr><th>PUL<td>2B AB
<th>STR<td>1B 83 87 8F 93 97 9F
<tr><th>SWA<td>EB
<th>TAD<td>5B
<tr><th>TAS<td>1B
<th>TDA<td>7B
<tr><th>TSA<td>3B
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<h3>65EL02 opcodes<a name="opcodes-65el02" href="#opcodes-65el02"></a></h3>

<p>This processor is an enhanced version of standard 65C02.

<div><table width="100%" class="opcodes">
<caption>Additional 65EL02 opcodes over 65C02</caption>
<tr><th width="4%">ADC<td width="46%">63 67 73 77
<th width="4%">AND<td width="46%">23 27 33 37
<tr><th>CMP<td>C3 C7 D3 D7
<th>DIV<td>4F 5F 6F 7F
<tr><th>ENT<td>22
<th>EOR<td>43 47 53 57
<tr><th>JSR<td>FC
<th>LDA<td>A3 A7 B3 B7
<tr><th>MMU<td>EF
<th>MUL<td>0F 1F 2F 3F
<tr><th>NXA<td>42
<th>NXT<td>02
<tr><th>ORA<td>03 07 13 17
<th>PEA<td>F4
<tr><th>PEI<td>D4
<th>PER<td>62
<tr><th>PHD<td>DF
<th>PLD<td>CF
<tr><th>REA<td>44
<th>REI<td>54
<tr><th>REP<td>C2
<th>RER<td>82
<tr><th>RHA<td>4B
<th>RHI<td>0B
<tr><th>RHX<td>1B
<th>RHY<td>5B
<tr><th>RLA<td>6B
<th>RLI<td>2B
<tr><th>RLX<td>3B
<th>RLY<td>7B
<tr><th>SBC<td>E3 E7 F3 F7
<th>SEA<td>9F
<tr><th>SEP<td>E2
<th>STA<td>83 87 93 97
<tr><th>STP<td>DB
<th>SWA<td>EB
<tr><th>TAD<td>BF
<th>TDA<td>AF
<tr><th>TIX<td>DC
<th>TRX<td>AB
<tr><th>TXI<td>5C
<th>TXR<td>8B
<tr><th>TXY<td>9B
<th>TYX<td>BB
<tr><th>WAI<td>CB
<th>XBA<td>EB
<tr><th>XCE<td>FB
<th>ZEA<td>8F
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 65EL02 aliases over 65C02</caption>
<tr><th width="4%">CLP<td width="46%">C2
<th width="4%">CPA<td width="46%">C3 C7 D3 D7
<tr><th>HLT<td>DB
<th>LDR<td>9B A3 A7 AB AF B3 B7 BB DC
<tr><th>ORR<td>03 07 13 17
<th>PSH<td>D4 DF F4
<tr><th>PUL<td>CF
<th>RSH<td>0B 1B 44 4B 54 5B
<tr><th>RUL<td>2B 3B 6B 7B
<th>STR<td>83 87 93 97
</table></div>

<h3>65CE02 opcodes<a name="opcodes-65ce02" href="#opcodes-65ce02"></a></h3>

<p>There's a small deviation in the use of <code>TAD</code> and <code>TDA</code>
for the base page. That's consistent with the direct page addressing
mode, <a href="#d_dpage"><code>.dpage</code></a> directive and convention of other
processors. Therefore <code>TAB</code> and <code>TBA</code> mnemonics are aliases only.

<p>For similar reason the base page register needs to be referenced as
<code>D</code> instead of <code>B</code> as the latter is the data bank
register on other processors.

<p>As later variants have both left and right rotating multi byte instructions
the rotate left word <code>ROW</code> mnemonic should be written as
<code>RLW</code> in new code to avoid a potential confusion.

<div><table width="100%" class="opcodes">
<caption>Additional 65CE02 opcodes over R65C02</caption>
<tr><th width="4%">ASR<td width="46%">43 44 54
<th width="4%">ASW<td width="46%">CB
<tr><th>BCC<td>93
<th>BCS<td>B3
<tr><th>BEQ<td>F3
<th>BMI<td>33
<tr><th>BNE<td>D3
<th>BPL<td>13
<tr><th>BRA<td>83
<th>BSR<td>63
<tr><th>BVC<td>53
<th>BVS<td>73
<tr><th>CLE<td>02
<th>CPZ<td>C2 D4 DC
<tr><th>DEW<td>C3
<th>DEZ<td>3B
<tr><th>INW<td>E3
<th>INZ<td>1B
<tr><th>JSR<td>22 23
<th>LDA<td>E2
<tr><th>LDZ<td>A3 AB BB
<th>NEG<td>42
<tr><th>PHW<td>F4 FC
<th>PHZ<td>DB
<tr><th>PLZ<td>FB
<th>RLW<td>EB
<tr><th>RTS<td>62
<th>SEE<td>03
<tr><th>STA<td>82
<th>STX<td>9B
<tr><th>STY<td>8B
<th>TAD<td>5B
<tr><th>TAZ<td>4B
<th>TDA<td>7B
<tr><th>TSY<td>0B
<th>TYS<td>2B
<tr><th>TZA<td>6B
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 65CE02 aliases over R65C02</caption>
<tr><th width="4%">ASR<td width="46%">43
<th width="4%">BGE<td width="46%">B3
<tr><th>BLT<td>93
<th>CMP<td>C2 D4 DC
<tr><th>LDR<td>0B 4B 6B 7B A3 AB BB E2
<th>NEG<td>42
<tr><th>ROW<td>EB
<th>RTN<td>62
<tr><th>STR<td>2B 5B 82 8B 9B
<th>TAB<td>5B
<tr><th>TBA<td>7B
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>Aliases of R65C02 not valid for 65CE02</caption>
<tr><th width="4%">CLR<td width="46%">64 74 9C 9E
<th width="4%">&nbsp;&nbsp;&nbsp;<td width="46%">&nbsp;&nbsp;
</table></div>

<h3>CSG 4510 opcodes<a name="opcodes-4510" href="#opcodes-4510"></a></h3>

<p>This processor is an enhanced version of 65CE02.

<div><table width="100%" class="opcodes">
<caption>Additional CSG 4510 opcodes over 65CE02</caption>
<tr><th width="4%">MAP<td width="46%">5C
<th width="4%"><td width="46%">
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional CSG 4510 aliases over 65CE02</caption>
<tr><th width="4%">EOM<td width="46%">EA
<th width="4%"><td width="46%">
</table></div>

<h3>45GS02 opcodes<a name="opcodes-45gs02" href="#opcodes-45gs02"></a></h3>

<p>Unfortunately the original naming convention couldn't be adopted as it
used four letter mnemonics for most new operations. If these longer names are
preferred it's quite easy to define macros named like that using <a
href="#d_segment"><code>.segment</code></a> and <q><code>\@</code></q>.

<p>The four letter mnemonics got shortened so that all register
<code>Q</code> operations are ending with the name of the register. That leaves two
letters to describe the function which isn't much.

<p>Alternatively the <a href="#generic-instructions">generic instruction</a>
syntax can be used with register <code>Q</code> parameter to get more
descriptive and familiar mnemonics.

<div><table border="0" width="100%">
<caption>Q register memory 45GS02 mnemonics</caption>
<tr><th width="6%"><code>ADQ</code><th width="12%"><code>ADC&nbsp;Q,</code><td width="50%">Add with carry to register <code>Q</code><td width="32%">(also known as <code>ADCQ</code>)
<tr><th><code>ANQ</code><th><code>AND&nbsp;Q,</code><td>Logical and register <code>Q</code><td>(also known as <code>ANDQ</code>)
<tr><th><code>BTQ</code><th><code>BIT&nbsp;Q,</code><td>Bit test register <code>Q</code><td>(also known as <code>BITQ</code>)
<tr><th><code>CPQ</code><th><code>CMP&nbsp;Q,</code><td>Compare register <code>Q</code><td>(also known as <code>CMPQ</code>)
<tr><th><code>EOQ</code><th><code>EOR&nbsp;Q,</code><td>Exclusive or register <code>Q</code><td>(also known as <code>EORQ</code>)
<tr><th><code>LDQ</code><th><code>LDR&nbsp;Q,</code><td>Load register <code>Q</code><td>
<tr><th><code>ORQ</code><th><code>ORR&nbsp;Q,</code><td>Logical or register <code>Q</code><td>
<tr><th><code>SBQ</code><th><code>SBC&nbsp;Q,</code><td>Subtract with carry from register <code>Q</code><td>(also known as <code>SBCQ</code>)
<tr><th><code>STQ</code><th><code>STR&nbsp;Q,</code><td>Store register <code>Q</code><td>
</table></div>

<p>The <code>Q</code> register modify instructions detach the register from the
mnemonic just like <code>ASL&nbsp;A</code>. The four letter convention had it
in both the mnmemonic and the parameter which is redundant.

<div><table border="0" width="100%">
<caption>Q register modify 45GS02 mnemonics</caption>
<tr><th width="6%"><code>&nbsp;&nbsp;&nbsp;</code><th width="12%"><code>ASL&nbsp;Q&nbsp;</code><td width="50%">Arithmetic shift left register <code>Q</code><td width="32%">(also known as <code>ASRQ&nbsp;Q</code>)
<tr><th><code>&nbsp;&nbsp;&nbsp;</code><th><code>ASR&nbsp;Q&nbsp;</code><td>Arithmetic shift right register <code>Q</code><td>(also known as <code>ASLQ&nbsp;Q</code>)
<tr><th><code>DEQ</code><th><code>DEC&nbsp;Q&nbsp;</code><td>Decrement register <code>Q</code><td>(also known as <code>DEQ&nbsp;Q</code>)
<tr><th><code>INQ</code><th><code>INC&nbsp;Q&nbsp;</code><td>Increment register <code>Q</code><td>(also known as <code>INQ&nbsp;Q</code>)
<tr><th><code>&nbsp;&nbsp;&nbsp;</code><th><code>LSR&nbsp;Q&nbsp;</code><td>Logical shift right register <code>Q</code><td>(also known as <code>LSRQ&nbsp;Q</code>)
<tr><th><code>&nbsp;&nbsp;&nbsp;</code><th><code>ROL&nbsp;Q&nbsp;</code><td>Rotate left register <code>Q</code><td>(also known as <code>ROLQ&nbsp;Q</code>)
<tr><th><code>&nbsp;&nbsp;&nbsp;</code><th><code>ROR&nbsp;Q&nbsp;</code><td>Rotate right register <code>Q</code><td>(also known as <code>RORQ&nbsp;Q</code>)
</table></div>

<p>The <code>INQ</code> and <code>DEQ</code> mnemonics have only implied
addressing mode just like <code>INX</code> or <code>INY</code>. These
can't be used on memory as register <code>Q</code> is not involved in the
operation. No <code>Q</code> register parameter either, the name makes it clear
already.

<p>The double word memory modify instructions are ending with the letter
<code>D</code>. That's consistent with pre-existing word operations like <code>INW</code>,
<code>DEW</code>, <code>ASW</code> and others.

<div><table border="0" width="100%">
<caption>Double word memory modify 45GS02 mnemonics</caption>
<tr><th width="6%"><code>ARD</code><th width="12%"><td width="50%">Arithmetic shift right double word<td width="32%">(also known as <code>ASRQ</code>)
<tr><th><code>ASD</code><th><td>Arithmetic shift left double word<td>(also known as <code>ASLQ</code>)
<tr><th><code>DED</code><th><td>Decrement double word<td>(also known as <code>DEQ</code>)
<tr><th><code>IND</code><th><td>Increment double word<td>(also known as <code>INQ</code>)
<tr><th><code>LSD</code><th><td>Logical shift right double word<td>(also known as <code>LSRQ</code>)
<tr><th><code>RLD</code><th><td>Rotate left double word<td>(also known as <code>ROLQ</code>)
<tr><th><code>RRD</code><th><td>Rotate right double word<td>(also known as <code>RORQ</code>)
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 45GS02 opcodes over CSG 4510</caption>
<tr><th width="4%">ADC<td width="46%">72
<th width="4%">ADQ<td width="46%">65 6D 72
<tr><th>AND<td>32
<th>ANQ<td>25 2D 32
<tr><th>ARD<td>43 44 54
<th>ASD<td>0A 06 0E 16 1E
<tr><th>ASL<td>0A
<th>ASR<td>43
<tr><th>BTQ<td>24 2C
<th>CMP<td>D2
<tr><th>CPQ<td>C5 CD D2
<th>DEC<td>3A
<tr><th>DED<td>3A C6 CE D6 DE
<th>DEQ<td>3A
<tr><th>EOQ<td>45 4D 52
<th>EOR<td>52
<tr><th>INC<td>1A
<th>IND<td>1A E6 EE F6 FE
<tr><th>INQ<td>1A
<th>LDA<td>B2
<tr><th>LDQ<td>A5 AD B2
<th>LSD<td>46 4A 4E 56 5E
<tr><th>LSR<td>4A
<th>ORA<td>12
<tr><th>ORQ<td>05 0D 12
<th>RLD<td>26 2A 2E 36 3E
<tr><th>ROL<td>2A
<th>ROR<td>6A
<tr><th>RRD<td>66 6A 6E 76 7E
<th>SBC<td>F2
<tr><th>SBQ<td>E5 ED F2
<th>STA<td>92
<tr><th>STQ<td>85 8D 92
<th>&nbsp;&nbsp;&nbsp;<td>&nbsp;&nbsp;
</table></div>

<div><table width="100%" class="opcodes">
<caption>Additional 45GS02 aliases over CSG 4510</caption>
<tr><th width="4%">CPA<td width="46%">D2
<th width="4%">LDR<td width="46%">A5 AD B2
<tr><th>ORR<td>05 0D 12
<th>SHL<td>0A
<tr><th>SHR<td>4A
<th>STR<td>85 8D 92
</table></div>

<hr>
<h2>Appendix<a name="appendix" href="#appendix"></a></h2>

<nav>
<h3>Assembler directives<a name="directives" href="#directives"></a></h3>

<p class="links">
<a href="#d_addr">.addr</a>
<a href="#d_al">.al</a>
<a href="#d_align">.align</a>
<a href="#d_alignblk">.alignblk</a>
<a href="#d_alignind">.alignind</a>
<a href="#d_alignpageind">.alignpageind</a>
<a href="#d_as">.as</a>
<a href="#d_assert">.assert</a>
<a href="#d_autsiz">.autsiz</a>
<a href="#d_bend">.bend</a>
<a href="#d_binary">.binary</a>
<a href="#d_binclude">.binclude</a>
<a href="#d_bfor">.bfor</a>
<a href="#d_block">.block</a>
<a href="#d_break">.break</a>
<a href="#d_breakif">.breakif</a>
<a href="#d_brept">.brept</a>
<a href="#d_bwhile">.bwhile</a>
<a href="#d_byte">.byte</a>
<a href="#d_case">.case</a>
<a href="#d_cdef">.cdef</a>
<a href="#d_cerror">.cerror</a>
<a href="#d_char">.char</a>
<a href="#d_check">.check</a>
<a href="#d_comment">.comment</a>
<a href="#d_continue">.continue</a>
<a href="#d_continueif">.continueif</a>
<a href="#d_cpu">.cpu</a>
<a href="#d_cwarn">.cwarn</a>
<a href="#d_databank">.databank</a>
<a href="#d_default">.default</a>
<a href="#d_dint">.dint</a>
<a href="#d_dpage">.dpage</a>
<a href="#d_dsection">.dsection</a>
<a href="#d_dstruct">.dstruct</a>
<a href="#d_dunion">.dunion</a>
<a href="#d_dword">.dword</a>
<a href="#d_edef">.edef</a>
<a href="#d_elif">.elif</a>
<a href="#d_else">.else</a>
<a href="#d_elsif">.elsif</a>
<a href="#d_enc">.enc</a>
<a href="#d_encode">.encode</a>
<a href="#d_end">.end</a>
<a href="#d_endblock">.endblock</a>
<a href="#d_endc">.endc</a>
<a href="#d_endalignblk">.endalignblk</a>
<a href="#d_endcomment">.endcomment</a>
<a href="#d_endencode">.endencode</a>
<a href="#d_endf">.endf</a>
<a href="#d_endfor">.endfor</a>
<a href="#d_endfunction">.endfunction</a>
<a href="#d_endif">.endif</a>
<a href="#d_endlogical">.endlogical</a>
<a href="#d_endm">.endm</a>
<a href="#d_endmacro">.endmacro</a>
<a href="#d_endn">.endn</a>
<a href="#d_endnamespace">.endnamespace</a>
<a href="#d_endp">.endp</a>
<a href="#d_endpage">.endpage</a>
<a href="#d_endproc">.endproc</a>
<a href="#d_endrept">.endrept</a>
<a href="#d_ends">.ends</a>
<a href="#d_endsection">.endsection</a>
<a href="#d_endsegment">.endsegment</a>
<a href="#d_endstruct">.endstruct</a>
<a href="#d_endswitch">.endswitch</a>
<a href="#d_endu">.endu</a>
<a href="#d_endunion">.endunion</a>
<a href="#d_endv">.endv</a>
<a href="#d_endvirtual">.endvirtual</a>
<a href="#d_endweak">.endweak</a>
<a href="#d_endwhile">.endwhile</a>
<a href="#d_endwith">.endwith</a>
<a href="#d_eor">.eor</a>
<a href="#d_error">.error</a>
<a href="#d_fi">.fi</a>
<a href="#d_fill">.fill</a>
<a href="#d_for">.for</a>
<a href="#d_from">.from</a>
<a href="#d_function">.function</a>
<a href="#d_goto">.goto</a>
<a href="#d_here">.here</a>
<a href="#d_hidemac">.hidemac</a>
<a href="#d_if">.if</a>
<a href="#d_ifeq">.ifeq</a>
<a href="#d_ifmi">.ifmi</a>
<a href="#d_ifne">.ifne</a>
<a href="#d_ifpl">.ifpl</a>
<a href="#d_include">.include</a>
<a href="#d_lbl">.lbl</a>
<a href="#d_lint">.lint</a>
<a href="#d_logical">.logical</a>
<a href="#d_long">.long</a>
<a href="#d_macro">.macro</a>
<a href="#d_mansiz">.mansiz</a>
<a href="#d_namespace">.namespace</a>
<a href="#d_next">.next</a>
<a href="#d_null">.null</a>
<a href="#d_offs">.offs</a>
<a href="#d_option">.option</a>
<a href="#d_page">.page</a>
<a href="#d_pend">.pend</a>
<a href="#d_proc">.proc</a>
<a href="#d_proff">.proff</a>
<a href="#d_pron">.pron</a>
<a href="#d_ptext">.ptext</a>
<a href="#d_rept">.rept</a>
<a href="#d_rta">.rta</a>
<a href="#d_section">.section</a>
<a href="#d_seed">.seed</a>
<a href="#d_segment">.segment</a>
<a href="#d_send">.send</a>
<a href="#d_sfunction">.sfunction</a>
<a href="#d_shift">.shift</a>
<a href="#d_shiftl">.shiftl</a>
<a href="#d_showmac">.showmac</a>
<a href="#d_sint">.sint</a>
<a href="#d_struct">.struct</a>
<a href="#d_switch">.switch</a>
<a href="#d_tdef">.tdef</a>
<a href="#d_text">.text</a>
<a href="#d_union">.union</a>
<a href="#d_var">.var</a>
<a href="#d_virtual">.virtual</a>
<a href="#d_warn">.warn</a>
<a href="#d_weak">.weak</a>
<a href="#d_while">.while</a>
<a href="#d_with">.with</a>
<a href="#d_word">.word</a>
<a href="#d_xl">.xl</a>
<a href="#d_xs">.xs</a>
</p>
</nav>

<nav>
<h3>Built-in functions<a name="functions" href="#functions"></a></h3>

<p class="links">
<a href="#f_abs">abs</a>
<a href="#f_acos">acos</a>
<a href="#f_addr">addr</a>
<a href="#f_all">all</a>
<a href="#f_any">any</a>
<a href="#f_asin">asin</a>
<a href="#f_atan">atan</a>
<a href="#f_atan2">atan2</a>
<a href="#f_binary">binary</a>
<a href="#f_byte">byte</a>
<a href="#f_cbrt">cbrt</a>
<a href="#f_ceil">ceil</a>
<a href="#f_char">char</a>
<a href="#f_cos">cos</a>
<a href="#f_cosh">cosh</a>
<a href="#f_deg">deg</a>
<a href="#f_dint">dint</a>
<a href="#f_dword">dword</a>
<a href="#f_exp">exp</a>
<a href="#f_floor">floor</a>
<a href="#f_format">format</a>
<a href="#f_frac">frac</a>
<a href="#f_hypot">hypot</a>
<a href="#f_len">len</a>
<a href="#f_lint">lint</a>
<a href="#f_log">log</a>
<a href="#f_log10">log10</a>
<a href="#f_long">long</a>
<a href="#f_pow">pow</a>
<a href="#f_rad">rad</a>
<a href="#f_random">random</a>
<a href="#f_range">range</a>
<a href="#f_repr">repr</a>
<a href="#f_round">round</a>
<a href="#f_rta">rta</a>
<a href="#f_sign">sign</a>
<a href="#f_sin">sin</a>
<a href="#f_sinh">sinh</a>
<a href="#f_sint">sint</a>
<a href="#f_size">size</a>
<a href="#f_sort">sort</a>
<a href="#f_sqrt">sqrt</a>
<a href="#f_tan">tan</a>
<a href="#f_tanh">tanh</a>
<a href="#f_trunc">trunc</a>
<a href="#f_word">word</a>
</p>
</nav>

<nav>
<h3>Built-in types<a name="types" href="#types"></a></h3>

<p class="links">
<a href="#t_address">address</a>
<a href="#t_bits">bits</a>
<a href="#t_bool">bool</a>
<a href="#t_bytes">bytes</a>
<a href="#t_code">code</a>
<a href="#t_dict">dict</a>
<a href="#t_float">float</a>
<a href="#t_gap">gap</a>
<a href="#t_int">int</a>
<a href="#t_list">list</a>
<a href="#t_str">str</a>
<a href="#t_symbol">symbol</a>
<a href="#t_tuple">tuple</a>
<a href="#t_type">type</a>
</p>
</nav>
</div>
</body></html>