[mtlmtlmtlmtl]

In my experience, macros in lisp codebases are mainly abstracting away common boilerplate patterns. Common Lisp has WITH-OPEN-FILE to open a file and make sure it closes if the stack unwinds. This is a macro based on the UNWIND-PROTECT primitive, which ensures execution of a form if the stack unwinds. Many projects will have various with-foo macros to express this pattern for arbitray things that are useful in the context of that project(though not all with- macros need UNWIND-PROTECT). Another example is custom loops that happen over and over.

Let's say I'm writing a chess engine. I regularly want to iterate over the legal moves in a position. So I might make a macro so I can write (do-moves (mv pos) ...)

I find that because doing this is so simple, well written lisp codebases tend to be pretty easy to read. There's less of that learning curve in a new codebase of getting used to the codebase's particular boilerplate rituals, and learning to pick out the code that's interesting. In a good lisp codebase all the ritual is hidden away in self-documenting macros.

Of course this can get taken too far and then it becomes nightmarish to understand the codebase because so much stuff is in various complex macros that it's hard to tell where the shit goes down.

[turboponyy]

What I don't understand is where the advantage of macros over functions lies in your example. In essence, what can't I do with the following?

    var position = new Position();

    var newPositions = GetLegalMoves(position)
        .Select(move => position.Clone().Perform(move));

Moreover, besides this "sending remote commands example" portrayed in the article, when would I ever want to pass around unevaluated code?

Perhaps I should pick up lisp.

[mtlmtlmtlmtl]

I'm not a JS programmer, but I didn't find that code terribly readable. And from a performance point of view, I would not want to copy the board state n times, though that's beside the point. It's a bit of a contrived example of course. But what this looks like in a real engine would be something like(no language in particular):

  pseudo_legal = move_generator(pos, PSEUDOLEGAL);
  while true {
    mv = pseudo_legal.next();

    if !mv {
      break;
    }
  
    if mv == tt.excluded_move || !pos.legal(mv){
      continue;
    }

    pos.make_move(mv);
    ...
    pos.unmake_move();
  }

The pseudolegal stuff and all that has to do with various performance considerations. This is roughly what Stockfish' move loop looks like. It looks overly verbose because abstracting away these things with functions adds runtime overhead.

With macros you can have your cake and eat it too. While it's technically true you're passing around unevaluated code, none of this is happening at runtime but at compile-time(technically macro-expansion time but that's beyond the scope of this comment). Think of it as the ability to inline pretty much anything you want.

[phoe-krk]

In this particular example, there's little to none: truth be told, I don't like WITH-FOO as a good example of why macros are fun. That's because WITH-FOO macros are commonly implemented/implementable as simple wrappers around CALL-WITH-FOO functions.

For instance, if we had a CALL-WITH-OPEN-FILE function (it's not too hard to write one yourself!), the following two syntaxes - one macro, one functional - would be equivalent:

    (with-open-file (stream #p"/tmp/foo" :element-type 'character)
      (read stream))
    
    (call-with-open-file 
     #p"/tmp/foo" (lambda (stream) (read stream))
     :element-type 'character)

Notice that both of these accept a pathname, additional arguments passed to OPEN, and code to be called with the opened stream. The only differences are that the functional variant needs to have its code forms wrapped in an anonymous function and that the function object passed to it is replaceable (since it's just a value).

---------------

For a more serious example, try thinking of how to implement something like CL:LOOP (a complex iteration construct) without a macro system.

[mtlmtlmtlmtl]

Sure, LOOP is a very complex macro. But my point was that most macros in real codebases are these simple boilerplate wrappers that help readability.

I don't like codebases too full of DSLs, necessarily.

A less trivial example is defining different types of subroutine. In StumpWM, a tiling WM written in common lisp, there is the concept of commands. They're functions, but they executed as a string. "command arg1 arg2". And these strings can be bound to keys. But args might be numbers, windows, frames, strings etc.

Commands are defined through a defcommand macro. It takes types! And there's a macro for defining arbitrary types and how to parse them from a string. A command is actually a function under the hood, with a bunch of boilerplate to: parse the arguments, stick the name in a hash table, call pre- and post-command hooks, set some dynamic bindings. and so on. Defcommand abstracts this away and you can just write it just like a normal Lisp function except for the types.

[kazinator]

These don't look like functions to me:

   var
   new
   .
   =>

If any of these were removed, how would you code them back in?

[agumonkey]

Well there's an old debate about macros and functions, especially when you have closures, since closures can also delay assembly of bits of logic (half the work macros do, the rest being actual syntactic processing when people do that).

You have to understand too that mainstream languages didn't have closure until very recently, so a lot of things look less obvious now.