Extension Template Example with HTML Documentation

Extension name: `ext-template1`

This extension is intended only to illustrate how to create an extension.

Author Name: Azarakhsh Keipour and Roger B. Dannenberg;
Author Email: akeipour@andrew.cmu.edu and rbd@cs.cmu.edu;

Additional File: c4-player.sal;
Additional File: piano-player.sal;
Additional File: pluck-player.sal;
Additional File: autoload.lsp;
Additional File: nyquistwords.txt;

Usage:

In SAL mode:

exec play-piano-c4() 
exec play-pluck-c4()

Description

This example uses an HTML file as the "root" of the extension. This is the preferred format when there is separate documentation and code.

This file is parsed by the Extension Manager of the NyquistIDE up to the line containing "End Metadata" (which in this file is inside an HTML comment).

The parser looks for:

"Version 1.0", which is the version of the extension file format, not the version of the extension. To avoid confusing users, this string appears inside an HTML comment.
"Additional File:", which indicates the installer should install an additional file.
- The additional file name is a path relative to the URL for this file.
- The file name must be terminated with a semicolon (;) or newline (<br> or other HTML tags will be parsed as part of the file name).
- There may be any number of additional files listed.
"Author Name:" and "Author Email:" fields are recommended, but not currently parsed by the Extension Manager.

Functions

This section describes the functions and global variables (if any) that are provided by this extension. Notice in the HTML source code of this file that each definition is named using an HTML anchor, e.g. <a name=play-piano-c4> before the definition of play-piano-c4().

Completion List Processing

There is an optional additional extension file named nyquistwords.txt that is parsed by NyquistIDE when it starts. The words in that file are added to the IDE Completion List system so that users can see these functions as completions. Users can also click on the completions to find documentation.

The nyquistwords.txt for this extension contains:

play-piano-c4 ) 
ext-template1/ext-template1.html#play-piano-c4 
play-pluck-c4 ) 
ext-template1/ext-template1.html#play-pluck-c4

The meaning is as follows: Entries are pairs of lines. The first line of each pair gives the name to appear in the completion list. If the name is a function, follow the function name with a space, a list of parameters (possibly empty as in this case) and end with a close parenthesis ")". (There is no open parenthesis.) For example,

eq-highshelf signal hz gain [slope])

describes the eq-highshelf function which takes 3 required positional and one optional parameters.

The second line of each pair is a URL, starting with the template name. Notice that the URL includes the anchor that directs the browser to exactly the definition of the function or variable. The NyquistIDE will complete the URL based on the location of the local copies of extensions (which will be in the lib directory.)

If you install this extension (ext-template1), and start to type "play-pian..." you will see play-piano-c4() in the Completion List.

Sample Function Documentation

play-piano-c4() [SAL]: play a C4 note on the piano synthesizer.
play-pluck-c4() [SAL]: play a C4 note on the pluck synthesizer.

Autoload Facility

Nyquist had many built-in functions, so users may be confused if they have to explicitly load extensions. On the other hand, loading all extensions at start-up will make loading slower and use more memory. A compromise is autoloading, where stubs are loaded to load real functions the first time the stub is called. The actual implementations overwrite the stubs so the next time the stub is called, no loading is needed or even checked.

To enable autoloading, simply add the file autoload.lsp to your files. Notice above that autoload.lsp is one of the “Additional Files.”

The autoload.txt file for this extension is:

;; autoload the ext-template1 functions 
(autoload "c4-player.sal" 'play-piano-c4 'play-pluck-c4)

This is a Lisp expression. The autoload function is built-in, and the first parameter is the (double-quoted) name of the file to load to load the extension. Note that there is no path (it will be loaded relative to the extension directory.)

The remaining parameters are simply the names of (some of) the functions that are declared by this extension. Any function on this list will be defined as a stub that loads the extension when the stub is called the first time. Note the use of the single quote.

Notice that

There are no commas separating parameters. This is how Lisp syntax works;
Function names have a single quote prefix. This denotes a symbol, one of Lisp's built-in types. Do no even think about a double quote, “closing” the single quote, or any other syntax.

If you autoload functions, your "Usage" instructions near the top of the file should probably not say anything about loading.

If you do not autoload functions, your "Usage" instructions in this extension would probably mention the load command, i.e.:

load "ext-template1/c4-player.sal"
exec play-piano-c4() 
exec play-pluck-c4()

In this case, it is important to include the name of the extension in the path. Simply loading "c4-player.sal" will not work because ext-template1 is not on Nyquist's load path. However, lib is on the load path, and ext-template1 is in lib, so "ext-template1/c4-player.sal" will work.