Equates .
RosAsm offers four variants and forms of Equates:
User defined Equates.
OS Equates.
Text Equates.
Body Equates.
User defined Equates
[true 1, false 0, MayBe 00101010101010101]
Are user defined equates. Equates cannot be redefined; double declarations are not allowed. They are simple substitutions, for any instance of evocations, in the Statements. You can use equates evocations inside macros declarations, data, and code. Even though it is not really useful, you can as well use Equates Evocations inside Equates Declaration:
[aaa 012, bbb aaa+1, ccc bbb+2]
mov eax bbb ; eax = 13
sub eax ccc ; eax = -1
OS Equates
mov eax &TRUE
The leading '&', of &TRUE indicates that this is an OS Equate. You do not have to declare anything, because RosAsm includes a complete encoded Table of OS Equates.
How it works:
In your RosAsmFiles Folder, there is a File called Equates.equ, that actually contains more than 60,000 Equates Declarations. The first time you run RosAsm, it searches for this file, and, if found, it computes it, and outputs two more Files: Equates.nam and Equates.num. The first one is a Table of dWords CheckSums of the Names. The second one is a Table of dWords for the values of all Equates Names. The Assembler holds these two Tables in Memory when compiling your Application.
When you use such an OS Equate, The Assembler, first, recomputes the CheckSum of the Name and searches for this Checksum, in the Names-CheckSums Table. Then, the value is found at the corresponding Displacement, in the Values Table.
The purpose of this particular implementation is, first, to save you from any boring include, - or from having to declare these Equates, in your Source -, second to speed-up the Compilation.
The User Defined Equates and the OS Equates are two independent things. For example, even though there is an OS Equate saying that &TRUE is 1, you can, as well, declare a User Equate saying that [TRUE 3], and there will be no conflict.
When downloading an update of the Equates.equ File, after having saved it, in your RosAsmFiles Directory, you have to update your Equates.nam and Equates.num Files by the Menu [Tool] / [Rebuild Equates] Option.
If you wish to implement some Equates of your own as OS Equates, this is possible: You simply save some MyEquates.equ File aside Equates.equ, you run the [Rebuild Equates] Option, and this is done. Though, this possibility is really not recommended, as therefore, nobody but you will be able to recompile your Appplications. Modifying the list of OS Equates should be reserved to the Maintainers of RosAsm only.
Usage
For 'multi-Equates' parameters, the internal operation is always OR unless you specify some '+imm' after the evocation. You can write as well:
&MB_ICONINFORMATION + &MB_SYSTEMMODAL ; readable
&MB_ICONINFORMATION+&MB_SYSTEMMODAL ; less readable
&MB_ICONINFORMATION___&MB_SYSTEMMODAL ; _____hhhmmmm_____
&MB_ICONINFORMATION&MB_SYSTEMMODAL ; unreadable but shorter
But not:
&MB_ICONINFORMATION__&MBSYSTEMMODAL ; > Missing '_' in 'MB_SYSTEMMODAL'
The Win Equates Parser considers '+' '_' or 'nothing', between 2 &Equates as an OR operation and not as an addition, because this is a frequent error to list 2 different Equates that have same values (and meaning) but with different misleading names.
Note that this does not apply to immediates. example:
mov eax &TRUE+1 ; >>> eax = 2 (and not 1)
You can easily verify any Win Equates values by Right-Clicks on the symbol (it will fail if not in upper case because the same fast search routine is used here, as in encodage). Heavy use of Win32 Equates does not spoil any compilation time. This replacement is blazingly fast.
Text Equates
Text Equates are nothing but the Text form of User Defined Equates:
[SomeText 'Some text declared by Equate' ]
[SomeData: SomeText , 0] ; is same as:
[SomeData: 'Some text declared by Equate' , 0 ]
Even multi-Lines 'Text' is allowed (with double quotes, of course).
The single or double quotes are part of the Equate replacement.
Body Equates
Body Equates are also User Defined Equates. They can contain anything, in between angle Brackets:
[BodyEquate < 'Some Text' , 0, 0654, &NULL > ]
The delimiters of Body Equates are: < > . This implies, of course, that you cannot make any use of these two Characters inside the Equate body, even inside declared 'Text'. In the upper example, the two spaces (after <, and before >), are not part of the Equate body and are stripped off by the Parser. The other ones are. This is to prevent from logical problems, in cases of evocations requiring Spaces: The leading space is to be given in the Evocation.
This feature is useful, for example, to declare Expressions inside Equates:
[SomeEquate < (24 shl 2) > ]
The two differences between Text Equates and Body Equates are that Text Equates include the Quotes, while Body Equates do not include the angle Brackets, and that Body Equates do not include the leading and ending spaces , whereas, Text Equates do.
~~~~~~~