Feature request - Compiled remarks

[tom-leys]

I saw a construct I liked in some hand-written logic. Remarks that are not meant to be executed (see the jumps over the print statements)

Potentially have a type of comment block (say ///) that creates these. Kind of a

/// blah
/// blah2

to

if false 
    print("blah")
    print("blah2") 
end

which does not get optimized away.

It would be super-neat if you could use printf type statements which get fully condensed. That would be useful for loop unrolling.

[cardillan]

That would indeed be a good feature to have! Especially coupled with an option to omit these remarks from the resulting code.

I'll need to figure out a way to have these remarks make it through the optimization. The optimizer is quite keen on removing unreachable code :D

[cardillan]

What about this:

• There will be a new function remark with the same syntax and rules as printf.
• print instructions generated by the remark function will be merged together only if they originate from the same remark call. This would serve to generate two separate print instructions (as in the example above) using two separate remark calls. They will also be always merged using the aggressive merging rules, even if the optimization level is basic (they won't be merged if the optimization is off).
• There will be a new compiler setting remarks with possible values of none, passive and active.
  • none: the remarks will not be compiled into the code,
  • passive: the remarks will be included in the code, with a jump instruction around them (the default setting),
  • active: the remarks will be included in the code without a jump around them, meaning they'll output the text into the text buffer.
• An enhanced comment (/// text) will be the same as remark("text"). The text after the three slashes will be trimmed.
  • There will be no support for variables or expressions in enhanced comment.
  • Exactly three slashes must be present at the beginning of the line, to make sure that double commented lines (//// this is a comment that has been commented out again) won't become unwanted remarks.
  • This will probably only be included in a new, rewritten grammar I'm planning (see #120).

This allows two uses for the remark function: either placing the remarks into the code as in the example above, or using it to activate/deactivate additional output (say, for debugging) using a compiler switch.

Example:

/// Configurable options:
IMPACT_STAR = 1
POWER_OUT = 236

/// Don't touch anything below
/// It's encrypted with dark magic

for i in 1 ... 10
    remark("Iteration $i:")
    ...
end

I'm open to suggestions of a better name for the remark function.

[tom-leys]

Sounds perfect. remark() is a great name for this. An alternative name is rem, which is what was used in MS-DOS batch files. But I prefer the longer name remark.

[cardillan]

There's a small problem I forgot to address: remarks are kept as a "virtual" instruction which is analogous to print, but gets processed at the end - after all optimizations are done, but before labels are resolved - and is either removed from the code, made passive by adding a jump around it, or just left in depending on compiler option remarks. This means that this instruction, unlike any other, doesn't have a fixed size. When the setting is none, the effective size is 0, in active mode the size is 1 and in passive mode the size is 2 or 1 (2 for the first instruction in a block, but 1 for subsequent ones, as there's just one jump over the entire block). Currently the size is always taken as 2. This makes the size calculations for optimizations for speed a bit off.

I won't handle the varying instruction size in passive mode (in some circumstances the calculation will be a bit off on the safe side), but I'll be able to correctly calculate the size in none and active modes. This will be in the next release.