PURE DATA Português
Dollar Sign Arguments
Sometimes when you are programming, you want to mark a position where you will later put a value. In Pd this is done by using dollar sign arguments. They are used in object boxes and message boxes, but careful, they have different meanings when used in message boxes versus object boxes. In both cases, they could be called "replacement variables": they mark the spot where you want to replace them with an actual value.
In Object Boxes
In the same way as objects like [metro], [random] or [osc~] accept arguments (as in [metro 1000]) an abstraction can accept arguments that can be used inside of it. Consider an abstraction that combines [metro] and [random] objects to produce random numbers that also denote time intervals at which they are produced. In its basic form it could look like this:
The abstraction above has two inlets, at left it would receive on/off (1/0 float) input and at right the range for the [random] which will then pass random numbers to [metro] and at abstraction's outlet. As it can be seen, the abstraction will initialize with 1000ms to [metro] object and range from 0 to 1000 to [random] object. Now, imagine you are writing an abstraction not knowing what specific arguments you want to pass on to it. Or, if you would like to change the value of the random object dynamically, you would have to change the value that is passed on to the right inlet.
However, this can be done differently by passing arguments to the abstraction at the creation time using dollarsigns inside the abstraction. Consider this change including demonstration of usage. (Note: the loadbang object outputs a single bang when the sketch is opened):
At the creation time two arguments (1000 and 1100) are passed to an abstraction [randometro1]. Inside the abstraction, $1 is substituted with the first argument (1000), and $2 with the second (1100). The effect (which was goal in the first place) is to be able to define the min-max range (as opposed to only 0-max) at which abstraction works. Because [random] inside the object needs a 0-max range, first argument (presumably smaller) is subtracted from the second. The result is passed to random to produce random numbers which are then added to the first argument. In demonstration of usage in the window behind the abstraction this construct produces random numbers between 1000 and 1100 in the first case, and 500 and 600 in the second.
While $1, $2, ... etc. represent first, second, etc .. argument to the abstraction, there is one special dollarsign that is extremely useful in Pure Data. $0 is a variable that is internally substituted by unique four-digit number per patch or instance of abstraction. In other words, Pd takes care that each instance of an abstraction or patch will be assigned this unique number and stored in $0 variable. The usefulness of this is immediately apparent in the following example of simple delay abstraction where delay-lines with the same name in multiple instances of same abstraction must be avoided:
It is important to understand that, despite $0 isn't actually substituted with the unique number inside the delwrite~ object, the latter actually writes audio signal to delay-line named "1026-dline". $0 variable is assigned in every opened or called patch, which also solves the problem of two or more instances of same patch (i.e.: simple synth). $0 also saves from situations from unwanted crosstalk of frequently used variables in different patches. An attentive reader/user could also point out a possibility to use $1, to use an argument passed to an abstraction (like "one" and "two" in above example), in which case care must be still taken to assign unique arguments to abstractions used in the same Pd session.
$0 is at times called localized variable, however, in my view, that is not entirely true. A variable constructed with $0-something can still be accessed from the global namespace by simply finding that unique number and than calling that appropriate variable (like for example to read the delay-line named 1026-dline from above example from within another independent patch). In fact this can sometimes be even useful. It is however true that using dollar variables is a localization technique.
In Message Boxes
A frequent confusion arrises from the use of dollarsigns in message boxes. It is important to understand that dollar variables in message boxes are actually totally local to that message box itself regardless where they appear. They will be substituted only by what a message box receives on its inlet. In an example of abstraction within which both types of dollar variables are used:
