🗺️ I'm not married to this name. Suggestions for a better name are welcome.

🗺️ I didn't want to overload writeTo. Naming suggestions welcome here if you can think of a better one.

🗺️ This was the bug in the finish() (now flush()) implementation.

🗺️ Moved so that the KDoc links will work. For some reason, KDoc links didn't seem to work when the IDE sees it's in a "TODO" item.

🗺️ It just occurred to me that precomputing and/or memoizing this information in the TemplateMacro would also make it easier to break up this large method into smaller methods. The reason I didn't break this up into smaller methods is because of the awkwardness of passing around the numberOfTimesToStepOut array.

I'll leave that as a TODO for later though.

🗺️ Previously, this would just throw an IndexOutOfBoundsException (or something like that). I ran into this unhelpful exception while I was testing things, so I put in a more useful message.

🗺️ The only real difference here is that instead of a lambda expression, we have an anonymous class with a useful toString() implementation.

🗺️ It would be even safer to replace . with $, but that was not playing nicely with the expected output in the test case because Kotlin uses $ to indicate string interpolation.

🗺️ If we want people to be able to define macros for their own types, I think we do need a builder of some sort. It's so much easier to use a builder than it is to construct the expressions directly.

🗺️ I rearranged this file so that the Ion 1.0 symbols are first, and any added Ion 1.1 symbols come afterwards. I also added ANNOTATE, EXPORT, TDL_EXPRESSION_GROUP, LITERAL, and MAKE_SEXP.

🗺️ There is a lot of repetitive code here. Most of it is interfaces that define what methods may be called when stepped into various container types for each of DataModelExpression, TemplateBodyExpression, and EExpressionBodyExpression. This is what lets us elegantly write things like

templateBody {
    list {
        int(1)
        variable(0)
        macro("foo") {
            string("bar")
        }
    }
}

Should this check the newMacros first so new definitions shadow the old ones?

No—at least not here—because this uses deep equality of the macro signature and body. (In practice, though, it should be short-circuited by a this === other check most of the time.)

However, your question is making me rethink the addMacro(...): MacroRef function because MacroRef could outlive an encoding context with no good way to determine whether it's still valid.

Should the writing logic live in the WriteAsIon impl for the various expression kinds?

After this is called, how does the writer know that it needs to write a new encoding directive before the next value?

The next time the user values are flushed, if newSymbols or newMacros is non-empty, then the managed writer will write an encoding directive before it flushes the user values. If both are empty, then we know that there are no SIDs or E-Expressions in the user values being flushed, and so no encoding directive is needed because it makes no difference.

Now that I think about it, there might be an edge case for Ion text if a system macro was being shadowed—it would end up writing incorrect data. This can be solved by making the managed writer emit an IVM if a value is written after finish() has been called.

Is this just a duplicate of the previous test?

Yes, it is. Oops.

+1, I think this will be very important for readability.