ref: a378d1e8cbb2950d0341893a2e27983aed4d045f
parent: 81ea39effe3a9cd4cd03312f5cc7b2701e26c7a4
author: Eldred Habert <[email protected]>
date: Sun Oct 31 16:20:57 EDT 2021
Reword label definition docs (#887) * Reword label definition docs A bunch of short sentences isn't very readable, this should be better * Use correct wording for "computing difference" Co-authored-by: Rangi <[email protected]> * Explain how to define a label before mentioning local ones * Move double-colon paragraph to make the explanation flow better * Clarify what a label's value is Co-authored-by: Rangi <[email protected]>
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -860,7 +860,7 @@
A text string that can be expanded later, similarly to a macro.
.El
.Pp
-Symbol names can contain letters, numbers, underscores
+Symbol names can contain ASCII letters, numbers, underscores
.Sq _ ,
hashes
.Sq #
@@ -867,18 +867,57 @@
and at signs
.Sq @ .
However, they must begin with either a letter or an underscore.
-Periods
-.Sq \&.
-are allowed exclusively in labels, as described below.
+Additionally, label names can contain up to a single dot
+.Ql \&. ,
+which may not be the first character.
+.Pp
A symbol cannot have the same name as a reserved keyword.
-.Ss Label declaration
-One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of "magic" numbers.
+.Ss Labels
+One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of
+.Dq magic
+numbers.
+Labels enable just that: a label ties a name to a specific location within a section.
+A label resolves to a bank and address, determined at the same time as its parent section's (see further in this section).
.Pp
-This can be done in a number of ways:
+A label is defined by writing its name at the beginning of a line, followed by one or two colons, without any whitespace between the label name and the colon(s).
+Declaring a label (global or local) with two colons
+.Ql ::
+will define and
+.Ic EXPORT
+it at the same time.
+(See
+.Sx Exporting and importing symbols
+below).
+When defining a local label, the colon can be omitted, and
+.Nm
+will act as if there was only one.
+.Pp
+A label is said to be
+.Em local
+if its name contains a dot
+.Ql \&. ;
+otherwise, it is said to be
+.Em global
+(not to be mistaken with
+.Dq exported ,
+explained in
+.Sx Exporting and importing symbols
+further below).
+More than one dot in label names is not allowed.
+.Pp
+For convenience, local labels can use a shorthand syntax: when a symbol name starting with a dot is found (for example, inside an expression, or when declaring a label), then the current
+.Dq label scope
+is implicitly prepended.
+.Pp
+Defining a global label sets it as the current
+.Dq label scope ,
+until the next global label definition, or the end of the current section.
+.Pp
+Here are some examples of label definitions:
.Bd -literal -offset indent
GlobalLabel:
AnotherGlobal:
-\&.locallabel
+\&.locallabel ;\ This defines "AnotherGlobal.locallabel"
\&.another_local:
AnotherGlobal.with_another_local:
ThisWillBeExported:: ;\ Note the two colons
@@ -885,33 +924,37 @@
ThisWillBeExported.too::
.Ed
.Pp
-Any label whose name does not contain a period is a global label.
-Declaring a global label sets it as the current scoped label, until the next global one.
-Global labels must be followed by one or two colons.
+In a numeric expression, a label evaluates to its address in memory.
+.Po To obtain its bank, use the
+.Ql BANK()
+function described in
+.Sx Other functions
+.Pc .
+For example, given the following,
+.Ql ld de, vPlayerTiles
+would be equivalent to
+.Ql ld de, $80C0
+assuming the section ends up at
+.Ad $80C0 :
+.Bd -literal -offset indent
+SECTION "Player tiles", VRAM
+PlayerTiles:
+ ds 6 * 16
+.end
+.Ed
.Pp
-Any label whose name contains a single period is a local label.
-Label names cannot contain more than one period.
-If the period is the first character, it will have the current scoped label's name implicitly prepended.
-Local labels may optionally be followed by one or two colons.
-Local labels can be declared as
-.Ql scoped.local
-or simply as
-.Ql .local .
-If the former notation is used, then
-.Ql scoped
-must actually be the current scoped label.
+A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
+However, if the section in which the label is defined has a fixed base address, its value is known at assembly time.
.Pp
-Declaring a label (global or local) with two colons
-.Ql ::
-will
-.Ic EXPORT
-and define it at the same time.
-(See
-.Sx Exporting and importing symbols
-below).
-.Pp
-.Sy Anonymous labels
-are useful for short blocks of code.
+Also, while
+.Nm
+obviously can compute the difference between two labels if both are constant, it is also able to compute the difference between two non-constant labels if they both belong to the same section, such as
+.Ql PlayerTiles
+and
+.Ql PlayerTiles.end
+above.
+.Ss Anonymous labels
+Anonymous labels are useful for short blocks of code.
They are defined like normal labels, but without a name before the colon.
Anonymous labels are independent of label scoping, so defining one does not change the scoped label, and referencing one is not affected by the current scoped label.
.Pp
@@ -940,12 +983,6 @@
: ; referenced by "ld hl"
dw $7FFF, $1061, $03E0, $58A5
.Ed
-.Pp
-A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
-However, if the section in which the label is declared has a fixed base address, its value is known at assembly time.
-.Pp
-.Nm
-is able to compute the subtraction of two labels either if both are constant as described above, or if both belong to the same section.
.Ss Immutable constants
.Ic EQU
is used to define numerical constant symbols.