gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-26 04:52:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Move section interpolation to its own section

Browse Source 
Fixes #907
This commit is contained in:
ISSOtm
2021-07-27 09:22:20 +02:00
committed by Eldred Habert
parent 9111157b82
commit 50d6403c72
1 changed files with 124 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
src/asm/rgbasm.5
View File

@@ -69,6 +69,129 @@ To do so, put a backslash at the end of the line:
DB "Hello,\ \[rs]\ \ ;\ Space before the \[rs] is included
world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included
.Ed
.Ss Symbol interpolation
A funky feature is
.Ql {symbol}
within a string, called
.Dq symbol interpolation .
This will paste the contents of
.Ql symbol
as if they were part of the source file.
If it is a string equate, its characters are simply inserted as-is.
If it is a numerical symbol, its value is converted to hexadecimal notation with a dollar sign
.Sq $
prepended.
.Pp
Symbol interpolations can be nested, too!
.Bd -literal -offset indent
DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
DEF meaning EQUS "answer"
;\ Defines answer = 42
DEF {meaning} = 42
;\ Prints "The answer to life, the universe, and "everything" is $2A"
PRINTLN "The {meaning} to {topic} is {{meaning}}"
PURGE topic, meaning, {meaning}
.Ed
.Pp
Symbols can be
.Em interpolated
even in the contexts that disable automatic
.Em expansion
of string equates:
.Ql name
will be expanded in all of
.Ql DEF({name}) ,
.Ql DEF {name} EQU/SET/EQUS/etc ... ,
.Ql PURGE {name} ,
and
.Ql MACRO {name} ,
but, for example, won't be in
.Ql DEF(name) .
.Pp
It's possible to change the way symbols are printed by specifying a print format like so:
.Ql {fmt:symbol} .
The
.Ql fmt
specifier consists of these parts:
.Ql <sign><prefix><align><pad><width><frac><type> .
These parts are:
.Bl -column "<prefix>"
.It Sy Part Ta Sy Meaning
.It Ql <sign> Ta May be
.Ql +
or
.Ql \ .
If specified, prints this character in front of non-negative numbers.
.It Ql <prefix> Ta May be
.Ql # .
If specified, prints the appropriate prefix for numbers,
.Ql $ ,
.Ql & ,
or
.Ql % .
.It Ql <align> Ta May be
.Ql - .
If specified, aligns left instead of right.
.It Ql <pad> Ta May be
.Ql 0 .
If specified, pads right-aligned numbers with zeros instead of spaces.
.It Ql <width> Ta May be one or more
.Ql 0
\[en]
.Ql 9 .
If specified, pads the value to this width, right-aligned with spaces by default.
.It Ql <frac> Ta May be
.Ql \&.
followed by one or more
.Ql 0
\[en]
.Ql 9 .
If specified, prints this many digits of a fixed-point fraction.
Defaults to 5 digits, maximum 255 digits.
.It Ql <type> Ta Specifies the type of value.
.El
.Pp
All the format specifier parts are optional except the
.Ql <type> .
Valid print types are:
.Bl -column -offset indent "Print type" "Lowercase hexadecimal" "Example"
.It Sy Print type Ta Sy Format Ta Sy Example
.It Ql d Ta Signed decimal Ta -42
.It Ql u Ta Unsigned decimal Ta 42
.It Ql x Ta Lowercase hexadecimal Ta 2a
.It Ql X Ta Uppercase hexadecimal Ta 2A
.It Ql b Ta Binary Ta 101010
.It Ql o Ta Octal Ta 52
.It Ql f Ta Fixed-point Ta 1234.56789
.It Ql s Ta String Ta \&"example\&"
.El
.Pp
Examples:
.Bd -literal -offset indent
SECTION "Test", ROM0[2]
X: ;\ This works with labels **whose address is known**
Y = 3 ;\ This also works with mutable constants
SUM equ X + Y ;\ Likewise with immutable constants
; Prints "%0010 + $3 == 5"
PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"
rsset 32
PERCENT rb 1 ;\ Same with offset constants
VALUE = 20
RESULT = MUL(20.0, 0.32)
; Prints "32% of 20 = 6.40"
PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"
WHO equs STRLWR("WORLD")
; Prints "Hello world!"
PRINTLN "Hello {s:WHO}!"
.Ed
.Pp
Although, for these examples,
.Ic STRFMT
would be more approriate; see
.Sx String Expressions
further below.
.Sh EXPRESSIONS
An expression can be composed of many things.
Numerical expressions are always evaluated using signed 32-bit math.
@@ -255,129 +378,6 @@ characters will be included as-is, without needing to escape them with
or
.Ql \[rs]n .
.Pp
A funky feature is
.Ql {symbol}
within a string, called
.Dq symbol interpolation .
This will paste the contents of
.Ql symbol
as if they were part of the source file.
If it's a string symbol, its characters are simply inserted.
If it's a numerical symbol, its value is converted to hexadecimal notation with a dollar sign
.Sq $
prepended.
.Pp
Symbols can be
.Em interpolated
even in the contexts that disable
.Em expansion
of string equates:
.Ql DEF({name}) ,
.Ql DEF {name} EQU/SET/EQUS/etc ... ,
.Ql PURGE {name} ,
and
.Ql MACRO {name}
will all interpolate the contents of
.Ql {name} .
.Pp
Symbol interpolations can be nested, too!
.Bd -literal -offset indent
DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
DEF meaning EQUS "answer"
;\ Defines answer = 42
DEF {meaning} = 42
;\ Prints "The answer to life, the universe, and "everything" is 42"
PRINTLN "The {meaning} to {topic} is {d:{meaning}}"
PURGE topic, meaning, {meaning}
.Ed
.Pp
It's possible to change the way symbols are converted by specifying a print format like so:
.Ql {fmt:symbol} .
The
.Ql fmt
specifier consists of parts
.Ql <sign><prefix><align><pad><width><frac><type> .
These parts are:
.Bl -column "<prefix>"
.It Sy Part Ta Sy Meaning
.It Ql <sign> Ta May be
.Ql +
or
.Ql \ .
If specified, prints this character in front of non-negative numbers.
.It Ql <prefix> Ta May be
.Ql # .
If specified, prints the appropriate prefix for numbers,
.Ql $ ,
.Ql & ,
or
.Ql % .
.It Ql <align> Ta May be
.Ql - .
If specified, aligns left instead of right.
.It Ql <pad> Ta May be
.Ql 0 .
If specified, pads right-aligned numbers with zeros instead of spaces.
.It Ql <width> Ta May be one or more
.Ql 0
\[en]
.Ql 9 .
If specified, pads the value to this width, right-aligned with spaces by default.
.It Ql <frac> Ta May be
.Ql \&.
followed by one or more
.Ql 0
\[en]
.Ql 9 .
If specified, prints this many digits of a fixed-point fraction.
Defaults to 5 digits, maximum 255 digits.
.It Ql <type> Ta Specifies the type of value.
.El
.Pp
All the format specifier parts are optional except the
.Ql <type> .
Valid print types are:
.Bl -column -offset indent "Print type" "Lowercase hexadecimal" "Example"
.It Sy Print type Ta Sy Format Ta Sy Example
.It Ql d Ta Signed decimal Ta -42
.It Ql u Ta Unsigned decimal Ta 42
.It Ql x Ta Lowercase hexadecimal Ta 2a
.It Ql X Ta Uppercase hexadecimal Ta 2A
.It Ql b Ta Binary Ta 101010
.It Ql o Ta Octal Ta 52
.It Ql f Ta Fixed-point Ta 1234.56789
.It Ql s Ta String Ta \&"example\&"
.El
.Pp
Examples:
.Bd -literal -offset indent
; Prints "%0010 + $3 == 5"
PRINTLN STRFMT("%#05b + %#x == %d", 2, 3, 2+3)
; Prints "32% of 20 = 6.40"
PRINTLN STRFMT("%d%% of %d = %.2f", 32, 20, MUL(20.0, 0.32))
; Prints "Hello world!"
PRINTLN STRFMT("Hello %s!", STRLWR("WORLD"))
.Ed
.Pp
HINT: The
.Ic {symbol}
construct can also be used outside strings.
The symbol's value is again inserted directly.
.Bd -literal -offset indent
def NAME equs "ITEM"
def FMT equs "d"
def ZERO_NUM equ 0
def ZERO_STR equs "0"
;\ Defines INDEX as 100
INDEX = 1{ZERO_STR}{{FMT}:ZERO_NUM}
;\ Defines ITEM_100 as "\[rs]"hundredth\[rs]""
def {NAME}_{d:INDEX} equs "\[rs]"hundredth\[rs]""
;\ Prints "ITEM_100 is hundredth"
PRINTLN STRCAT("{NAME}_{d:INDEX} is ", {NAME}_{d:INDEX})
;\ Purges ITEM_100
PURGE {NAME}_{d:INDEX}
.Ed
.Pp
The following functions operate on string expressions.
Most of them return a string, however some of these functions actually return an integer and can be used as part of an integer expression!
.Bl -column "STRSUB(str, pos, len)"
@@ -395,6 +395,7 @@ Most of them return a string, however some of these functions actually return an
.Ql %spec
pattern replaced by interpolating the format
.Ar spec
.Pq c.f. Sx Symbol interpolation
with its corresponding argument in
.Ar args
.Pq So %% Sc is replaced by the So % Sc character .