ref: 50d6403c72b5e177dffd47e0d09350e0fa7126e5
parent: 9111157b82a268ff4172f693733e9e9ecf152e91
author: ISSOtm <[email protected]>
date: Tue Jul 27 05:22:20 EDT 2021
Move section interpolation to its own section Fixes #907
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -69,6 +69,129 @@
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 @@
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 @@
.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 .