# The \*SCRATCH\* Symbol Tutorial

\**SCRATCH\** is a global symbol, specific to Nyquist in Audacity, which is not deleted in-between plugin runs. It provides a way for information to survive from one invocation of a plugin to the next. However, you should not rely on the *"value"* of \*SCRATCH\* beyond a single invocation of a plugin as it could be overwritten by another plugin. It is better to use property lists of \*SCRATCH\*. That way, you get a whole name space rather than a single variable name, and with careful naming of the property keys, name collisions can be avoided.

To pass data from plugin "effectX-partA" to "effectX-partB":

1\. Assign a property name based on the effect name, e.g.: 'EFFECTX \[or in SAL, which does not support the single-quote notation of LISP, write QUOTE(EFFECTX). ]

2\. "effectX-partA" should delete any old property value:

```lisp
exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
(remprop '*SCRATCH* 'effectx) ;; in LISP
```

3\. "effectX-partA" should compute a new property value **v** and save it:

```lisp
 exec putprop(quote(*SCRATCH*), v, quote(effectx)) ;; in SAL
 (putprop '*SCRATCH* v 'effectx) ;; in LISP
```

4\. "effectX-partB" should access the property using:

```lisp
 set v = get(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (get '*SCRATCH* 'effectx) ;; in LISP
```

5\. When "effectX-partB" finishes, it should remove the property:

```lisp
 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (remprop '*SCRATCH* 'effectx) ;; in LISP
```

But there may be cases where you do some analysis and want to use the analysis data multiple times. You might even have multiple analysis plugins operating on different inputs to collect data to feed into a plugin with multiple inputs. In this case, which might be quite common, you should not call REMPROP(), but this has the problem of leaving data on the \*SCRATCH\* property list indefinitely.

In cases where \*SCRATCH\* data is not deleted immediately after use, and where there is the potential to leave large amounts of memory there, there should be another effect, e.g. "effectX-partCleanup", that simply calls:

```lisp
 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (remprop '*SCRATCH* 'effectx) ;; in LISP
```

allowing the user to explicitly free up any data stored on the 'EFFECTX property. It would be reasonable to omit the "effectX-partCleanup" effect if the data stored on the property list has a maximum size of, say, 10KB. The problem we want to avoid is properties with unbounded size getting left in the heap until Audacity is restarted.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://plugins.audacityteam.org/contributing/developing-your-own-plugins-and-scripts/creating-your-own-nyquist-plugins/tutorials/the-scratch-symbol-tutorial.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.