More on Getting Help


SuperCollider 3 is a work in progress. As such much is undocumented. Many of the helpfiles have been copied over from SC2, and have unworking examples, etc. These are in the process of being updated. 


Below are listed a few techniques for tracking down documentation and functionality. Note: If some of the terms used below (e.g. class, method, inheritance, etc.) are unclear to you, you may wish to read the Language helpfiles which are listed in the main help window for detail on some of these concepts. Reading a general tutorial on Object Oriented Programming at some point could also be useful, as could reading a FAQ, etc. about Smalltalk. Smalltalk is the general purpose OOP language upon which the the design of the SuperCollider language is based. It's syntax is different than SC's, but conceptually it has much in common.


NB: Be sure to check out the Further Info section at the bottom of this page.


Basics 


As you've probably already learned selecting any text and pressing Cmd-Shift-? will open the corresponding helpfile. Usually helpfiles are either concept related, or document particular classes. In the SC language classes begin with capital letters. Try Cmd-Shift-? on the following (double click on the first word; the stuff after the two slashes is a comment):


Class // this is a class


A few methods also have helpfiles. Methods begin with lower-case letters, as do many other things in the language.


play // Cmd-shift-? on this will open a helpfile detailing different implementations of this method


In addition there are a many helpfiles which explain important concepts. Most of these are listed in the main help window (Help.help.rtf, which will open if you press Cmd-Shift-? with no text selected), or in the overviews listed there. Cmd-Shift-? on this text for an example: Tutorial


A convention of the documentation is that text in bold face or between brackets [] refers to other helpfiles. Double-click to select that text and press Cmd-Shift-? to open the corresponding helpfile. An example is the text Undocumented-Classes in the next section.


Note that many helpful methods print information to the 'post window'. Unless you have explicitly changed it (see the Window menu) this is the window which opened when you launched. Pressing Cmd-\ will bring the current post window to the front.


Tracking Down Information


Executing the following


Help.all;


will open a new window which lists all helpfiles by directory. Similarly the helpfile Undocumented-Classes contains a (possibly out of date) list of all classes which have no helpfiles. This can be a good place to start looking for functionality which may already be implemented.


Looking in class definitions (select any class and press Cmd-j to open its class definition file) can help you to figure out what undocumented methods do.


Array // Try Cmd-j on this


Since many methods use other classes, you may need to continue your search in other class definitions or helpfiles.


Executing the method dumpInterface on any class will list its class and instance methods and their arguments (if any).


Array.dumpInterface; // Look at the post window (the one that opened when you started SC)


Note that since the SuperCollider language is object-oriented many classes inherit methods from farther up the class hierarchy. (The many subclasses of Collection are a good example of this. See the Collections overview for more detail.) It would be impractical and redundant to document every inherited method that a class responds to, so it is important to be able to track down documentation and method definitions.  


The method dumpFullInterface applied to any Class will list all class and instance methods that a class responds to, sorted by the class in which they are implemented. This will include inherited methods. Methods overidden in a subclass are listed under the subclass.


Array.dumpFullInterface;


This can be a lot of information, so dumpAllMethods or class.dumpAllMethods will show only instance and class methods respectively.


Array.class.dumpAllMethods; // Only class methods that this responds to (including inherited ones)

Array.dumpAllMethods; // Only instance methods (including inherited ones)


There is also a graphical Class browser which will show all methods, arguments, subclasses, instance variables and class variables. (Currently this is only OSX.) Using the browser's buttons you can easily navigate to the class' superclass, subclasses, class source, method source, helpfile (if there is one), check references or implementation of methods, or even open a web browser to view the corresponding entry in the online CVS repository. (Note that the web repository is a backup often a day or two behind the status of what is available to developers.)


SequenceableCollection.browse;


Selecting any method and pressing Cmd-y will open a window with a list of all the classes that implement that method. (See the Polymorphism helpfile for detail on why different classes might implement methods with the same name.)


select // try it on this method


Similarly, selecting any text and typing shift-cmd-y will open a window showing all references to the selected text, i.e. each place it is used within the class library. (This will not find methods calls compiled with special byte codes like 'value'.)


// try it on these

asStream 

SCWindow


In the resulting window selecting any class and method and pressing Cmd-j will take you to that method definition in that class definition. For example try selecting Pattern-select in the window resulting from the previous example. Note that SC supports defining methods in separate files, so a class' methods may be defined in more than one place. If you try Cmd-j on the following you will see that it will open a file called dumpFullInterface.sc rather than one called Class.sc (its main class definition file). The + Class {.... syntax indicates that these are additional methods.


Class-dumpFullInterface


If you know that a class responds to a particular message, you can use findRespondingMethod to find out which class it inherits the corresponding method from.


Array.findRespondingMethodFor('select'); // you can Cmd-J on the result in the post window


Similarly, helpFileForMethod will open the helpfile of the class in which the responding method is defined (if the helpfile exists). Note that this does not guarantee that the method is documented therein. As noted above, some documentation is incomplete, and some methods are 'private' or not intended for general use.


Array.helpFileForMethod('select'); // this will open the Collection helpfile; scroll down for select


In general poking around can be a good way to learn about how things work. See Internal-Snooping for more advanced information about how to look 'under the hood.'


For Further Info


A good starting place for figuring out how to do something are the numerous files in the Examples folder. The SuperCollider swiki is another good source of tips, examples, and information:


http://swiki.hfbk-hamburg.de:8888/MusicTechnology/6


To edit or add pages on the swiki use: username: sc password: sc


Further help can be obtained by subscribing and sending questions to the sc-users mailing list:


http://www.create.ucsb.edu/mailman/listinfo/sc-users


An archive of the list can be searched from this page:


http://swiki.hfbk-hamburg.de:8888/MusicTechnology/437


Requests for documentation of undocumented methods or classes, as well as reports of errata, omissions, etc. in helpfiles can be sent to: mullmusik@users.sourceforge.net or to the user's list above.