MagicPreset explanation of what MagicPreset is and/or does

Inherits from: Object

There are several techniques for saving objects to files in SuperCollider (e.g. Object.writeArchive and readArchive), but sometimes it's useful to keep your data in the same file as the code that refers to it.  

MagicPreset makes this possible by storing the data in "magic presets," which are specially formatted comments at the bottom of the current Document.  This allows you to see at a glance all the data that's associated with your code, and avoid keeping track of multiple files.

See also: Object, Archive

Some Important Issues Regarding MagicPreset

MagicPreset has only been tested with the SuperCollider app on OS X, and may not function correctly in other environments.

The specially formatted comments can be moved to anywhere in the file, but they must each be on a single line.  Editing or deleting the special comments will of course change or remove the data.

Creation / Class Methods

*put (key, value, doc)

Store some data in a magic preset.  The data can be any object that can be stored using asCompileString (i.e. most SuperCollider objects apart from some Functions).

key - A name for the magic preset.

value - An object to be stored.

doc - A Document in which to store the magic preset.  Defaults to the current Document.

// example: store the data [1,2,3,4,5] in the magic preset presetName:

MagicPreset.put("presetName", [1,2,3,4,5]);

// or the equivalent

MagicPreset.["presetName"] = [1,2,3,4,5];

*at (key, doc)

Retrieve the data stored in a "magic preset."  If a magic preset with the given name does not exist, this method will return nil.

key - A String or Symbol representing the name of the magic preset.

doc - The Document in which the magic preset is stored.  Default is the current Document.

// example: get the data stored in presetName and store it in x.

x = MagicPreset.at("presetName");

// or the equivalent

x = MagicPreset.["presetName"];

Storing multiple data items

A handy way to store multiple data items in one magic preset is to use an Event:

// create an event and store it in a magic preset

(

d = (

answer: 42.0,

anArray: [1,2,3,4,5],

aString: "Hello"

);

MagicPreset.["myData"] = e;

)

// retrieve the data and examine part of it

(

e = MagicPreset.["myData"];

e.answer.postln;

)

Backing up magic presets

You can easily back up magic presets by copying the corresponding comment at the bottom of the file and giving it a new name (i.e. by changing the text in parentheses after ___MAGIC_PRESET).  This will create a new magic preset with the new name, containing a copy of the data.

Examples

// store some magic presets:

MagicPreset.[\test1] = [1,2,3];

MagicPreset.[\test2] = [4,5,6];

// note that the magic presets have appeared at the bottom of the file.

// retrieve the data:

MagicPreset.[\test1].postln;

MagicPreset.[\test2].postln;

// you can update already existing magic presets:

MagicPreset.[\test1] = [7,8,9];

// note that the existing "test1" magic preset has been updated, rather than a new one being added.