gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-26 13:02:07 +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 DB "Hello,\ \[rs]\ \ ;\ Space before the \[rs] is included
world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included
.Ed .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 .Sh EXPRESSIONS
An expression can be composed of many things. An expression can be composed of many things.
Numerical expressions are always evaluated using signed 32-bit math. 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 or
.Ql \[rs]n . .Ql \[rs]n .
.Pp .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. 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! 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)" .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 .Ql %spec
pattern replaced by interpolating the format pattern replaced by interpolating the format
.Ar spec .Ar spec
.Pq c.f. Sx Symbol interpolation
with its corresponding argument in with its corresponding argument in
.Ar args .Ar args
.Pq So %% Sc is replaced by the So % Sc character . .Pq So %% Sc is replaced by the So % Sc character .