Difference between revisions of "Nyquist Property List Tutorial"

From Audacity Wiki
Jump to: navigation, search
(Variables and Property Lists: begin Examples section)
(*TRACK* Examples: extend first *track* example)
Line 21: Line 21:
  
 
=== *TRACK* Examples===
 
=== *TRACK* Examples===
As an example, if we have a variable called '''*TRACK*''' (which we do in version 4 plug-ins), and it has a property called '''NAME''' (which it does), then we can "get" the value of that property with:
+
When the [[Nyquist_Plug-in_Headers#type|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.
  (GET '*TRACK* 'NAME) ; Lisp
 
 
 
  return get(quote(*TRACK*), quote(NAME)) ; SAL
 
 
 
  
 +
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 [http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/xlisp/xlisp-ref/xlisp-ref-130.htm GET] command.
 +
<pre>
 +
;codetype lisp
 +
(get '*TRACK* 'NAME)
 +
</pre>
 +
<pre>
 +
;codetype sal
 +
return get(quote(*TRACK*), quote(NAME))
 +
</pre>
 +
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:
 +
<pre>
 +
;codetype lisp
 +
(setf track-name (get '*TRACK* 'NAME))
 +
(format nil "The name of the current track is ~s." track-name)
 +
</pre>
 
{{advice|See also [http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/xlisp/xlisp-man/xlisp-man-014.htm Property List Functions] in the XLisp manual.}}
 
{{advice|See also [http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/xlisp/xlisp-man/xlisp-man-014.htm Property List Functions] in the XLisp manual.}}
  
 
[[Category:Nyquist]][[Category:Nyquist:Tutorials]]
 
[[Category:Nyquist]][[Category:Nyquist:Tutorials]]

Revision as of 00:32, 11 January 2019

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))

Examples

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.