OMG!!!! This is so cool! Now I don't have to remember all the hexadecimal opcodes! (But first I need a link cable )

Now I don't have an excuse. Now I have to learn ASM.

RTFM. It is not implemented yet.
Edit from the future : Sorry if I offended anyone. That's just how you get when you know the Minecraft community which tends to avoid reading /any/ doc and complains about it not working.

So, #define (as used in tasm/spasm) has two fundamentally different purposes:

- "Expression-like" macros:
    #define SUM(x,y) (x + y)
    #define PC ($)

- "Instruction-like" macros:
    #define CP_HL(reg) or a / sbc hl,reg / add hl,reg
    #define CRASH rst 00h

I probably won't implement the former type unless there is huge demand.  But as DrDnar points out, often macros of this sort are really just constants, and an equate would do equally well.  (I suppose it's also worth mentioning that since Mimas is a true multi-pass assembler, you can use equates in ways that wouldn't work in spasm or tasm.)


As far as instruction-like macros, I've thought quite a bit about them since I first started the project.  There are several ways that they could be implemented:

 - Call by value: arguments to a macro must be constant numeric expressions, which are evaluated before calling the macro.  This would be the easiest to implement but also very limited (registers can't be used as arguments; symbols used as args can't be modified; the behavior of PC, @B, and @F would be unlike the way macros are expected to work.)  Many folks would rightly say that this isn't really a macro.

 - Call by reference: arguments could be either constant expressions or literal symbols.  The bookkeeping gets a little bit more complicated than call-by-value; this would allow a macro to define symbols that are passed as arguments.

 - Call by name: arguments could be any expression not involving a register, and would be evaluated at the point in the macro where they're used (so PC would work the way you'd expect, and arguments that aren't used wouldn't be evaluated.)

 - Any of the above plus special support for registers: I could add special syntax that would let you choose a register by number.  For example, CP_HL above could be written as "OR A / SBC HL,R#(reg) / ADD HL,R#(reg)", and to call it you could write "CP_HL(\BC)" (note the backslash), or equivalently write "CP_HL(8)" (8 being the internal code for BC.)  (Obviously the exact syntax is up for debate.)

 - Call by syntactic substitution: arguments could be any valid expression (including registers), and would essentially be pasted into the syntax tree at the appropriate location.  This would require special syntax for parameter names (such as "SBC HL,{reg}") so that Mimas knows not to fully parse the instruction until compile time.  This would be a PITA to implement (especially if macros defined in one source file can be called from a different file, which I think is important to support.)

 - Call by textual substitution: take the text of the argument and paste it into the text of the macro, then parse the result.  This is, I think, less semantically "correct" than syntactic substitution (you lose symbol scoping) and possibly also a bit slower than the other options, but is arguably closest to the way tasm does it.  Like syntactic substitution, this would require special syntax for parameter names within the body of the macro.


Mostly unrelated to the above, I've also considered having macros use numbered parameters rather than named ones; e.g., you'd have to write CP_HL as "or a / sbc hl,#1 / add hl,#1" - sort of like function parameters in a shell script.  This would be considerably easier to implement than named parameters, plus would offer the possibility of variadic macros - the downside would be decreased readability.  In fact, the easiest way to implement this would be for all macros to be variadic, but then you lose error checking.

What do you folks think?  What do you typically use macros for, and how do you intuitively expect them to work?

Mostly unrelated to the above, did you released any documentation on writing plug-ins for Mimas ? I dig through all the files included in TiCalc's mimas-0.4.zip and found many docs on how to use them, install them etc but nothing about how to create one

But I'm not good enough in ASM to understand how a system works from a code

So I think writing a plugin requires modifying and recompiling Mimas ? If so, it doesn't make plugins portable

And I wanted to write a plugin to add to the parser CHIP-8 pseudo-assembly mnemonics, I wonder if that's possible.

Right, well, there isn't a fixed ABI partly because the plugin feature is new and experimental, but also because a fixed ABI would require some space to store a table of addresses.  The same goes for hooks: it would be nice to have a system of hooks whereby plugins could register their interest in various sorts of events - but implementing that would take up valuable space.

I'm not really familiar with CHIP-8.  Are you saying you want to be able to generate CHIP-8 bytecode, or that you want to use CHIP-8 mnemonics and have them compiled into Z80 machine code?  Either way it is definitely possible.  Here's what needs to be done to define a new instruction type:

 - Choose a bytecode format.  Special instructions consist of a 7-bit ID (23 of which are currently defined) and up to 62 bytes of argument data.  The arguments can either be expressions or raw binary data (indicated by bit 7 of the ID byte.)
 - Write a routine to parse text into a bytecode instruction.
 - Write a routine to format a bytecode instruction as text.
 - Write a routine to assemble a bytecode instruction.
 - Optional but recommended: also patch asmto8xv and 8xvtoasm

So this would require three calls to the plugin: one in ParseInstruction, one in FormatInstruction, and one in AssembleProgramInstr.