Add/Extend Macro Documentation

[scolsen]

I think it'd be worthwhile to have a doc page dedicated to writing macros in Carp--there are some restrictions when it comes to writing macros that may not be immediately obvious to new users:

• If one wants to recur in a macro, one needs(Or so it seems? I might be wrong about this.) to define a dynamic function using defndynamic -- macros themselves cannot recur.
• Not all special forms are supported in macros--this is mentioned in passing in the Language Guide, but it'd be nice to have a definitive list. For example the is not supported (afaik).
• Macros can't be called in macros (at least that's my observation from my scant experience defining them when I tried using e.g. case in the definition of another macro, it resulted in unexpected unable to find symbol errors on the argument passed to case. Then again, I may have made a tangential error that caused this and the actual use may not be problematic.
• expand is a super useful function to be aware of when writing macros, but you have to do some digging to find out it exists. (as it turns out, it's documented in the docs for Dynamic. I wound up finding it through a search in the source. So this is a lesser point--but I do think giving it a bit more exposure would be a benefit).

Since my observations are highly anecdotal, there may be some other explanations for the restrictions/behaviors I'm citing here, but I think a dedicated doc would help clarify macro definition and usage!

I'm happy to work on this, but I will probably need to call in reinforcements for elaboration on some points and a healthy dose of peer-editing.

Here are the existing available macro docs (that I'm aware of):

• https://github.com/carp-lang/Carp/blob/master/docs/LanguageGuide.md -- I think the extent of Macro info covered in this doc is perfect for a quick intro and summary, which is precisely what this doc is trying to accomplish.
• https://blog.veitheller.de/Carp.html -- Veit's first post on Carp is really great, and the Macro section provides a nice concise example for those looking for guidance.
• https://blog.veitheller.de/Carp_and_derive.html -- Veit's recent post is a great deep dive on defining a macro (and an interesting one at that!), and mentions some of the points above, such as using defndynamic to implement recursion.

I think pooling together some of the knowledge in each of these resources into a general Macros reference doc is a good first step.

[eriksvedang]

I hadn't really thought about this at all, but you're absolutely right – of course we need such a document!

While I hope that some of these idiosyncrasies you mention will be removed in the future, many things will of course stay the same and until they are fixed it's very good to have some docs on it, for sure.

All in all – feel free to open a PR with a draft of this document and I'll make sure to chime in!

[hellerve]

I’m more than happy to help as well. Sadly blog posts are prone to aging and they get outdated fairly quickly, so an up-to-date-by-default document would be great!

[eriksvedang]

This document exists now!