Document what's intentionally changed or removed from RGBDS

[Rangi42]

Given that this is still very in-progress, it would be helpful to see an ongoing document of which changes are intentional instead of to-do items. Off the top of my head I'm aware of:

• Removed EQUS expansion (which we wanted to do eventually anyway, as per https://github.com/gbdev/rgbds/issues/905, once user-defined functions can replace it)
• Removed [[ inline section fragment literals ]] (unclear how difficult they would be to add in this architecture; maybe reconsider once SECTION FRAGMENTs are implemented, since inline ones were a simple extension in C++)
• Removed READFILE (although I'm sure it won't be too hard to PR just by reading how other string functions and INCLUDE/INCBIN work)
• Removed delayed ("red-painted") \{interpolations\} (this will need some alternative; my own use case might be satisfied by a FOREACH+FOREACHSTR block -- or just an array-style workaround)
• Removed ld [$ff00+c]
• Interpolation behavior changed? (The .err output will of course be different -- although many .err files are testing for specific failures to happen -- but .out files should always have a documented reason for changing)

There's plenty else, especially from the most recent additions in 0.9.4 and upcoming 1.0.0, but I expect most of that will be caught up to eventually. (Including 'character' literals, rgbasm -MC -MG -MP -MT -MQ behavior with different flag names, etc.)

[ISSOtm]

Such a list is still quite in flux, since I am rearchitecting the project still. For example, with the switch to a proper parser generator, supporting [$ff00 + c] should become feasible again.

In general, changes that have been “enshrined” in .stderr files should be final and intentional, and the rest is TODOs. So, for the time being, I propose the following heuristic: “a change is intentional if and only if it's present in a passing test”.

I agree such a list of changes is a good idea, if only because it'll be valuable to end users; I just don't have right now the bandwidth to maintain such a list in parallel with the development proper.

[Rangi42]

974b50832b875653273497ccfe93a63c2a59d859 mentions "This does remove the ability to export a symbol before it's defined, but I don't think anyone uses that anyway." This is exactly the kind of subtle little difference that should immediately have a test case and/or documentation so it doesn't get forgotten.

[ISSOtm]

d007b53 changes the rules around underscores in numeric literals slightly.

[ISSOtm]

Also, I think I'm going to drop the \<{...}> syntax, as it appears redundant with \<...> and would be difficult to support.

[Rangi42]

There is no \<{...}> syntax. There is \<...> syntax, and interpolation is allowed within the .... "Within" can still mean "entire", but it's redundant to do so. (Just like ld a, {x:num} is valid but redundant.)

On the other hand, \<arr{d:idx}> to get the arr[idx]th macro argument is not pointless. (Or just \<arr{idx}> now that arr$42 is a valid identifier!) I expect there are some X macro techniques that would involve that kind of thing.

I don't know of a real-world example yet, partly because pret and polishedcrystal don't use X macros (yet?), but instead repeat the same sequences of "do something for Bulbasaur, do something for Ivysaur, do something for Venusaur, do something for Charmander, ..." many times over, instead of MACRO X :: something \1 :: ENDM :: INCLUDE "x_pokemon.inc". But I definitely have used triple-nested {interp{arr{idx}}} (for rectallocate.asm); and at least in our original/current RGBDS architecture, supporting expansions inside interpolations is no more difficult than supporting expansions inside macro arguments.

[ISSOtm]

rsgbasm does not have support for selectively disabling expansions (peek has them enabled, whereas with_active_context_raw doesn't), so they must be manually managed when disabled, including when reading the contents of a macro arg. Expanding manually inside of an interpolation is not problematic besides handling a :, but macro args need to switch between two different modes and that adds a lot of complexity.

There is a workaround:

def TMP equ arr{idx}
println "\<TMP>"
purge TMP

Not as convenient, but workable.

[ISSOtm]

ba3cacc changed the trimming of macro args to always occur, even after block comments.

[Rangi42]

Didn't we intentionally choose to stop trimming space at a block comment, so that passing both leading and trailing space in a macro is at least possible in the (unlikely) case where someone wants to?

Edit: 6e805cd3 implemented macro args in the new lexer, trimming left and right whitespace; 1f579dea updated the comments to note the "stop at block comment or line continuation" behavior (which may not have been intentional in the original?); d51ab352 made left trimming continue past line continuations, but chose not to continue past block comments. (Discord discussion of that change)

Edit 2: If we do want to keep this change, I've copied it to rgbds as well (which simplifies the code somewhat): https://github.com/gbdev/rgbds/pull/1831

Edit 3: RGBDS 1.0 will already have incorporated this change.