writing-your-own.org

Writing your own patterns

A guide on how to define your own pattern classes. For a tutorial on how to make music with this library, see tutorial.org.

Note that this guide is still a work in progress.

Style

Just a basic overview of things you should do when defining a pattern, for consistency.

pattern slots should be called length when they determine the total length of the pattern, and repeats when they determine the number of times the pattern (or the list the pattern refers to) repeats.

For example, pser uses length because it only yields LENGTH outputs, while pseq uses repeats because it yields the full list REPEATS times.

Use defpattern to create patterns. defpattern generates and exports the function that creates a pattern. Only override the function generated if absolutely necessary.

Provide sensible defaults for pattern slots, i.e. by default pseries starts at 0, increases by 1, and has a length of infinity. pgeom starts at 1, multiplies by 2, and has a length of infinity.

Any length or repeats slots should default to :inf for infinity.

Avoid yielding values that might cause problems, i.e. if your pattern is likely to be used for a pbind’s :dur key, avoid yielding 0. 0 may also cause problems when divided by.

If you have to override the pattern instantiation function generated by defpattern then make sure you use the same docstring you provided to defpattern for consistency.

Provide docstrings for patterns you write.

Provide at least one example in the docstring.

Prefix each line of code in the examples with two semicolons.

Try to provide a “See also” section in the docstring to point to similar or related patterns or functions.

Surround the names of functions or patterns in backquote notation (i.e. ~`foobar’~).

Write tests for the patterns you create

Use proper terminology:

output: whatever a pstream returns when its next method is called.

yield: when a pstream returns something, it’s called yielding, since it’s not the same as a regular function.

value: generally anything that isn’t an event: number, symbol, etc.

event: an object representing a mapping of keys to values, defined in event.lisp.