The Code Stack

The code stack is an optional but super-powerful feature that makes it easier to build structured documents.

Let’s say you’re writing a book that has chapters, each of which contains sections, each of which contains topics. Each chapter, section, and topic begin and end with a chunk of boilerplate.

You could do it like this:

$$chapterStart{Animals of Australia}
$$sectionStart{The Wombat}

$$topicStart{Wombats of the sea}
...
$$topicEnd{}

$$topicStart{Wombats of the sky}
...
$$topicEnd{}

$$sectionEnd{}
$$chapterEnd{}

$$chapterStart{Animals of New Zealand}

That seems like a lot of work, doesn’t it? In an ideal world, the computer would be smart enough to know that every time you start a topic you want to close the old topic, and every time you start a chapter you want to close the previous chapter, as well as any sections or topics that might be open.

Here’s what we'd like to write instead:

$$chapterStart{Animals of Australia}
$$sectionStart{The Wombat}

$$topicStart{Wombats of the sea}
...

$$topicStart{Wombats of the sky}
...

$$chapterStart{Animals of New Zealand}

Introducing the code stack

The code stack is a way to solve this problem. It looks like this:

This

$$chapterStart = {{
$$SetCodeStack{1 | </div>}

<div class="chapter">
<h1>$$Args[0]{}</h1>
}}

$$chapterStart{Animals of Australia}

Becomes

<div class="chapter">
<h1>Animals of Australia<h1>

What’s going on here? The main body is pretty standard: when you call $$chapterStart{}, it generates a div and an h1. At the very beginning, however, we call $$SetCodeStack. That tells the code stack system that we’re creating a new level 1 object, and we want to insert </div> to when it’s time to close that object.

Now, if we we add a new chapter, we get this:

This

$$chapterStart{Animals of New Zealand}

Becomes

</div>
<div class="chapter">
<h1>Animals of New Zealand</h1>

When we call $$chapterStart again, it tries to add a new level 1 object to the code stack. But before it can do that, it needs to pop any existing level 1 object (also any level 2, 3, ... objects). So it inserts the </div> that was left on the stack by the previous $$chapterStart.

Note that in this case, we were calling the same level 1 object twice, so the code we popped off the stack was the same as the code we were adding. But if we were calling $$specialChapterStart, it could add a different and more complex item to the stack. Each object gets its own closing code, which will be called later.

Whenever we call $$SetCodeStack{1}, it pops any items at level 1 or greater (beginning with the highest level and working backward). So if we have a topic (level 3), a section (level 2), and a chapter (level 1) on the stack, starting a new section will close the existing topic, then the existing section, then open a new section.

If you get to the end of the document with items still on the stack, they will all be popped in order at the very end.

Combining the code stack with ATX headers

Sometimes it’s nice to keep TextCarver code completely out of your source documents, especially if they’re being authored by non-technical people. Combining the code stack with ATX headers is a great way to do that:

$$h1 = {{
$$SetCodeStack{1 | </div>}

<div class="chapter">
<h1>$$Args[0]{}</h1>
}}

// Same thing for h2, h3

# Animals of Australia
## The Wombat

### Wombats of the sea
...
### Wombats of the sky
...

# Animals of New Zealand

Code stack commands

We’ve already looked at $$SetCodeStack{level | code}. There are a few other commands you might occasionally need:

You can push and pop the code stack:

$$PushCodeStack{code}
$$PopCodeStack{}

And you can query the level of the code stack:

There are $$CodeStackLevel{} items on the code stack.

Next: Deferred Evaluation