Nyquist Property List Tutorial

From Audacity Wiki
Revision as of 00:32, 11 January 2019 by Stevethefiddle (talk | contribs) (*TRACK* Examples: extend first *track* example)
Jump to: navigation, search

Variables and Property Lists

In general terms, a variable is a symbol which contains a value. The symbol can be any valid name, and its value may be changed (hence "variable"). In Nyquist, the value may be of any data type (for example, a number, a character, or even a sound) and may be changed from one data type to another. Unlike some programming languages, variables do not need to be declared before use - they can just be set, and then they exist.
In addition to the value of the variable, one or more "properties" may also be attached to the symbol. Each "property" has a name and a value. The properties are known collectively as the symbol's "property list".

Setting the value of a symbol "binds" the value to the symbol. A symbol that has no value (not even "nil") is said to be "unbound".

In addition to the value of a symbol, we can also attach properties. This is a way of associating a list of items, each with their own value, to a single variable. Each item is called a key or indicator, and we can give each key a value. This list of items is called a "property list" (or plist for short).

To get the value of a property, we use the GET command.

When getting the value of a property, we do NOT want to evaluate either the variable (symbol) or the key symbol, so we must "quote" both symbols to prevent evaluation.

  • Lisp syntax
(get 'varaiable-name 'property-name)
  • SAL syntax
set v = get(quote(varaiable-name ), quote(property-name))


The following examples may be run in the Nyquist Prompt.
For the full list of global property lists, refer to the Nyquist Plug-ins Reference.

*TRACK* Examples

When the type of a plug-in is process or analyze, Audacity sets the value of *TRACK* to the currently selected audio, and sets a lists of properties related to that track. The plug-in processes one track at a time in sequence, and the *TRACK* variable is set each time for the track that is being processed.

The value of *TRACK* provides direct access to the selected audio, and its property list provides access to other properties of the track. The NAME property provides the name of the Audacity track that is currently being processed. To access the value of the NAME property, we use the GET command.

;codetype lisp
(get '*TRACK* 'NAME)
;codetype sal
return get(quote(*TRACK*), quote(NAME))

The GET command returns the value of the property (the name of the track), which may be assigned to another variable and used elsewhere in the code. For example, to print a pretty message:

;codetype lisp
(setf track-name (get '*TRACK* 'NAME))
(format nil "The name of the current track is ~s." track-name)
Warning icon See also Property List Functions in the XLisp manual.