List Modification with PUSH and POP

1. push: Adding an Element and Updating a Variable

In the previous lesson, if we wanted to add an element to the front of a list and update the variable, we would write:

(setq my-list '(b c))
(setq my-list (cons 'a my-list))
;; my-list is now (a b c)

This pattern is so common that Lisp provides a more concise and expressive way to do it: the push macro. The push macro handles both the cons operation and the setq assignment in one step.

As the manual states, (push ELEMENT LISTNAME) is the standard way to prepend an element to a list stored in a variable. Let's try it in your *scratch* buffer.

1. Define a list of your FOSS tools:

   (setq foss-tools '("Linux" "Git"))
   

2. Now, use push to add Emacs to the front:

   (push "Emacs" foss-tools)
   

   Evaluate this expression with C-x C-e. The return value will be the full list: ("Emacs" "Linux" "Git").
3. Now, check the value of the foss-tools variable itself:

   foss-tools
   

   Placing your cursor after the symbol and pressing C-x C-e will show ("Emacs" "Linux" "Git") in the echo area. The foss-tools variable has been permanently modified to point to this new list.

2. How push Works: Reassigning Pointers

It's important to understand what "modifying the variable" really means. The push macro does not destructively alter the existing cons cells of the original list. Instead, it performs a non-destructive cons operation to create a new list, and then it reassigns the variable to point to this new list.

This distinction is subtle but crucial for understanding how Lisp manages memory.

The key takeaway is that push is a macro, not a function. It rewrites your short, expressive code (push "Emacs" foss-tools) into the longer, underlying implementation (setq foss-tools (cons "Emacs" foss-tools)) before it gets evaluated. This "code that writes code" is a manifestation of Lisp's homoiconicity, a topic you were interested in. You write in a high-level way, and the macro handles the low-level details.

3. pop: Removing an Element and Updating a Variable

The logical counterpart to push is pop. The pop macro performs two actions at once:

1. It returns the first element (car) of the list.
2. It modifies the list variable to point to the rest (cdr) of the list.

This makes pop perfect for processing items from a list one by one.

Let's continue with our foss-tools list in the *scratch* buffer. It should currently be ("Emacs" "Linux" "Git").

1. Evaluate the following pop expression:

   (pop foss-tools)
   

   The *Messages* buffer (or echo area) will display "Emacs", which was the first element of the list.

2. Now, check the value of foss-tools again:

   foss-tools
   

   Evaluating this will show ("Linux" "Git"). The variable has been updated.

Together, push and pop perfectly implement a stack. You push items onto the top, and you pop them off the top. This LIFO (Last-In, First-Out) behavior is a fundamental pattern in programming.

4. The Idiomatic Use of push: Accumulating Results

One of the most common uses for push is to build a list by accumulating results inside a loop or an iterator. You start with an empty list and push each new item onto it.

The image below shows a real-world example from the Emacs source code.

This pattern is powerful and efficient. It's often followed by (nreverse list) to put the elements back in their original order, since push naturally reverses them. (We will discuss nreverse in a future lesson on destructive operations).

The Emacs Lisp manual even explicitly recommends this approach for building lists in your programs.

5. Hands-On Application: Managing a Writing To-Do List

Given your background in creative writing and project management, let's build a simple to-do list manager for your next speculative fiction piece.

In your *scratch* buffer, follow these steps:

1. Initialize Your Task List: Use defvar to create a global variable for your tasks. This is good practice for variables you might want to inspect or interact with.

   (defvar speculative-fiction-tasks '("Outline the core world-building rules" "Draft the opening scene")
     "A list of tasks for my current writing project.")
   

   Evaluate this defvar form.

2. Add a New Task: You just had a great idea for a new character. Use push to add this task to the top of your list.

   (push "Develop the protagonist's backstory" speculative-fiction-tasks)
   

   Evaluate this, and then evaluate speculative-fiction-tasks to confirm the list has been updated.

3. Work on a Task: Now, you're ready to get to work. Use pop to grab the most recent task off the list.

   (pop speculative-fiction-tasks)
   

   Evaluate this expression. Notice that the echo area shows you the task you just popped: "Develop the protagonist's backstory".

4. Check Your Remaining Tasks: Finally, evaluate speculative-fiction-tasks one more time. You'll see that it now only contains the original two items.

This simple exercise perfectly mimics a stack-based workflow, a common pattern for managing nested tasks or tracking state.

Conclusion

In this lesson, you've learned how to use the push and pop macros to efficiently manage lists stored in variables. This is a fundamental skill that moves beyond simple data storage into dynamic data manipulation.

Key Takeaways:

• push is a macro that adds an element to the front of a list and updates the variable in a single step. It is a convenient shorthand for (setq my-list (cons element my-list)).
• pop is a macro that removes the first element from a list, modifies the variable to point to the rest of the list, and returns the removed element.
• Together, push and pop treat a list variable as a stack (Last-In, First-Out).
• Using push to accumulate items into a list is the idiomatic and recommended way to build lists dynamically in Elisp programs.

Preview of the Next Lesson

We've now seen non-destructive list-building (cons, append) and variable-modifying macros (push, pop). However, we have yet to see a truly destructive function—one that modifies the cons cells of a list in-place.

In the next lesson, we will explore nconc, the destructive counterpart to append. This will complete your understanding of the critical difference between non-destructive and destructive operations, a specific area you wanted to master.