Find and add undocumented features to the manual

[RPGHacker]

trafficstars

There still seem to exist a couple of undocumented features within Asar. Find them and add them to the manual.

[trillllian]

Line 880 of assembleblock.cpp: //this part is not mentioned in the manual Also from the 0x.asm test it looks like 0x80 is a possible alternative to $80, but I can't figure out why it works.

[RPGHacker]

Yeah, I came across the first one before. I'm not sure if I added it to the manual, and since probably not many people know about it and/or use it, I think I'd leave it out of the manual intentionally, since it's some really ugly ambiguity with defines (this would come in handy should someone ever decide to rewrite Asar from scratch).

Didn't know about 0x literals, though (or maybe I forgot about it). That should definitely go into the manual (I think there's a section for number literals). Some other undocumented features currently on my list (which I found either from reading old changelogs or from looking at code, not all of them may actually be valid in the current version anymore):

• 'x' = $1234 is a valid operation. It's equivalent to table file, but it accepts math.
• db 'x'+4 is a valid operation in the math parser.
• !a = abc : !{a}def is valid operation; it's equivalent to abcdef. You can nest defines inside the !{}s; a!{b!{c!def}g}h is accepted (assuming all defines exist). (Honestly not quite sure what this one means, but I assume it lets you resolve defines dynamically?)
• You can use if !condition to negate the statement. Note that you may need an extra set of parentheses due to conflicts with define syntax. (See above, would probably leave this one out of documentation)
• The define !assembler has a special meaning: Its value is always "asar", even if you assign something else to it. Intended usage: !assembler = xkas : %freespace_!assembler(), where %freespace_xkas() requires the user to set freespace and %freespace_asar() contains a freecode.
• freespace fixed is a synonym of freespace static. (Not sure if anyone uses it and if we should put it into the documentation, not a fan of aliases)
• autoclear (See above, not a fan of aliases)
• Labels may be defined as Main(), not just Main:
• sizeof/objectsize functions

As I said, not all of those may even be valid anymore. For example: I searched the entire solution for "assembler", but found nothing indicating that a define like that actually exists (however, it would certainly be useful to have, even with xkas support being dropped eventually, since in theory someone could make a new assembler in the future which was only partially compatible with Asar, but also had this define, just with a different value).

That's about all I've found so far.

[RPGHacker]

Added deprecation warnings for "freespace fixed" and "autoclear" - they're useless aliases I don't want to support forever. Might also add a deprecation warning to !condition later on, again something I don't want to keep supporting. Tested assembling a patch with !assembler in it. It doesn't seem to exist in the current version and was probably remove (thinking about whether we should add back certain intrinsic defines to the compiler - doesn't seem like a horrible idea, even C++ compilers have that, and can make it possible to support multiple different compilers should we ever rewrite this thing or write a new compiler). Will add everything else to the documentation later.

[RPGHacker]

Alright, this can be closed with the latest commit.

A few notes:

• Main() didn't seem to exist in Asar 1.50 at all and I didn't bother adding it back since it would just complicated things.
• I've gone ahead and removed if !condition immediately. The original plan was to just deprecated it and have it throw a warning, but after inspecting the code, I determined that the only way to use it at all was by using the ! escape sequence which didn't exist in prior versions, so I don't think people could have uses the feature before. Additionally, it was sloppily implemented, anyways, and didn't work as it should have if it had been usable. I hope my observations here weren't wrong and there wasn't some other secret way of using this in previous versions.
• The built-in !assembler define didn't exist in Asar 1.50, but I've actually reactivated it and added support for built-in defines along with an !assembler_ver define since I consider it somewhat useful to have (although currently the usefulness is rather limited - it's rather something that could be useful in the feature).
• Also added stringsequal() and stringsequalnocase() functions so that Asar finally has some simple means of comparing strings, This can be used with the new !assembler define, which can be wrapped inside double quotes like "!assembler" and then passed to this function. There are probably also some other use cases, I imagine.

Aside from that, I've now covered every undocumented feature I was aware of. If anyone finds further ones, feel free to reopen this issue.

With that we've closed all issues that are currently assigned to the 1.60 milestone, so maybe we should start discussing a 1.60 beta release now (either in a new issue or on SMW Central).

[trillllian]

a very late reply but if !condition was actually used by the SA1 pack, as if !!LZ3 (check the end of boost/lzx.asm). I fixed that and I think i'll submit an update to that, but it shows that it was possible to use this feature. I think it should be re-added with a deprecation warning.

[RPGHacker]

Interesting to know. Reopening this for now. I guess the only scenario in which it was actually usable then was in combination with a define. I think in any other case, it would actually complain about a missing define, at least from what I've tried.

[trillllian]

Just tried some stuff and apparently if !(condition) works too without complaining about defines. So you don't have to use a define, but i agree that the use cases of this are very limited.

[RPGHacker]

That's weird. I remember specifically trying if !(condition) and it not working... :/

[trillllian]

I made a new issue for that (#113).

[RPGHacker]

Found more undocumented stuff: fill/skip align and fill/skip offset. I don't quite remember what these do, but reopening the issue so that we don't forget to document them at some point.

[trillllian]

fill/skip align were documented at some point, so this is done again (for now...)