diff --git a/src/asm/rgbasm.5 b/src/asm/rgbasm.5 index 11129add..3ee73f95 100644 --- a/src/asm/rgbasm.5 +++ b/src/asm/rgbasm.5 @@ -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 . +These parts are: +.Bl -column "" +.It Sy Part Ta Sy Meaning +.It Ql Ta May be +.Ql + +or +.Ql \ . +If specified, prints this character in front of non-negative numbers. +.It Ql Ta May be +.Ql # . +If specified, prints the appropriate prefix for numbers, +.Ql $ , +.Ql & , +or +.Ql % . +.It Ql Ta May be +.Ql - . +If specified, aligns left instead of right. +.It Ql Ta May be +.Ql 0 . +If specified, pads right-aligned numbers with zeros instead of spaces. +.It Ql 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 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 Ta Specifies the type of value. +.El +.Pp +All the format specifier parts are optional except the +.Ql . +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 . -These parts are: -.Bl -column "" -.It Sy Part Ta Sy Meaning -.It Ql Ta May be -.Ql + -or -.Ql \ . -If specified, prints this character in front of non-negative numbers. -.It Ql Ta May be -.Ql # . -If specified, prints the appropriate prefix for numbers, -.Ql $ , -.Ql & , -or -.Ql % . -.It Ql Ta May be -.Ql - . -If specified, aligns left instead of right. -.It Ql Ta May be -.Ql 0 . -If specified, pads right-aligned numbers with zeros instead of spaces. -.It Ql 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 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 Ta Specifies the type of value. -.El -.Pp -All the format specifier parts are optional except the -.Ql . -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 .