$$Include{docs/siteMacros.textCarver}

# 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:

$$exampleSimple{}
\$\$chapterStart{Animals of Australia}
\$\$sectionStart{The Wombat}<br><br>

\$\$topicStart{Wombats of the sea}
...
\$\$topicEnd{}<br><br>

\$\$topicStart{Wombats of the sky}
...
\$\$topicEnd{}<br><br>

\$\$sectionEnd{}
\$\$chapterEnd{}<br><br>

\$\$chapterStart{Animals of New Zealand}<br><br>

$$endExample{}

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:
$$exampleSimple{}
\$\$chapterStart{Animals of Australia}
\$\$sectionStart{The Wombat}<br><br>

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

\$\$topicStart{Wombats of the sky}
...<br><br>

\$\$chapterStart{Animals of New Zealand}<br><br>

$$endExample{}


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

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

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

\$\$chapterStart{Animals of Australia}

$$exampleRight{}
\<div class="chapter">
\<h1>Animals of Australia\<h1>

$$endExample{}

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:
$$example{}
\$\$chapterStart{Animals of New Zealand}

$$exampleRight{}
\</div>
\<div class="chapter">
\<h1>Animals of New Zealand\</h1>

$$endExample{}

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:

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

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

\/\/ Same thing for h2, h3

\# Animals of Australia
\## The Wombat<br><br>

\### Wombats of the sea
...
\### Wombats of the sky
...<br><br>

\# Animals of New Zealand

$$endExample{}


### 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:
$$exampleSimple{}
\$\$PushCodeStack{code}
\$\$PopCodeStack{}
$$endExample{}

And you can query the level of the code stack:
$$exampleSimple{}
There are \$\$CodeStackLevel{} items on the code stack.
$$endExample{}



[Next: Deferred Evaluation](3dDeferredEvaluation.html)