title:: Internal Snooping (Introspection)
summary:: Snooping around SuperCollider
categories:: Debugging, Internals

You can inspect much of the internal structure of the class library and other data structures.
This can be useful for research and debugging purposes.

note:: The keyboard shortcuts mentioned here only apply to the standard SuperCollider IDE.::

section:: Class Definitions, Implementations, and References

subsection::Look up Implementation
Selecting the name of any method (e.g. play) and then the menu item teletype::Language>Look up Implementation:: will open a window showing all implementations of that method and their arguments. Selecting one of those classes and methods (e.g. Sample:play) and typing enter will open the class definition at that method. Note that this only shows implementations, and does not indicate inheritance.

(see link::Reference/KeyboardShortcuts::)


subsection::Look up References
Selecting any text (e.g. Window or asStream) and then the menu item teletype::Language>Look up References:: will open a window showing all references to the selected text, i.e. each place it is used within the class library. Note that this will not find methods calls compiled with special byte codes like 'value'.

(see link::Reference/KeyboardShortcuts::)

subsection::Graphical Class browser
SC has a graphical Class browser which will show all methods, arguments, subclasses, instance variables and class variables. 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.

code::
SequenceableCollection.browse;
::



subsection:: Snooping in Classes

code::
// print all instance methods defined for this class
Collection.dumpInterface;

// print all class methods defined for this class
Collection.class.dumpInterface;



// print all instance methods that instances of this class respond to
Collection.methods.collect(_.name);

// print all class methods that this class responds to
// includes inherited methods
Collection.class.methods.collect(_.name);

// print all instance and class methods that this class responds to
// includes inherited methods
Collection.dumpFullInterface;

// print instance methods of this class and superclasses, in alpha order
// also shows from which class the method is inherited
// does not include Object or Class methods
// for class methods, do Meta_Collection.dumpMethodList
Collection.dumpMethodList;

// dump all subclasses of this class
Collection.dumpClassSubtree;

// dump all subclasses, in alphabetical order
Collection.dumpSubclassList;

// dump all instance variable names of this class
Server.instVarNames.dump;

// dump all class variable names of this class
Server.classVarNames.dump;

// the path to the file that defines this class
// Note that there might be extensions to this class in other files
Server.filenameSymbol.postln;

(
// print all classes whose names start with 'F'
Class.allClasses.do { | class |
	if (class.name.asString.beginsWith("F")) {
		class.name.postln
	}
}
)

(
// find and print all class variable names defined in the system
Class.allClasses.do { | class |
	if (class.classVarNames.notNil) {
		// classVarNames is an Array of Symbols
        class.classVarNames.do { | varname |
            (class.name.asString ++ " " ++ varname.asString).postln
        }
    }
}
)

(
// find and print all methods that contain "ascii"
Class.allClasses.do { | class |
   	class.methods.do { | sel |
   			if(sel.name.asString.find("ascii").notNil) {
            		(class.name.asString + "-" + sel.name).postln
            }
	}
}
)
::

subsection:: Snooping in Methods

code::
// does the class implement this method?
Collection.findMethod('select');
// -> Collection:select

// this class doesn't
Array.findMethod('select');
// -> nil

// but a superclass might implement it, so
// climb the class tree to check
Array.findRespondingMethodFor('select');
// -> Collection:select


// find a method object and dump its argument names and
// its local variable names
Collection.findMethod('select').dump;
Collection.findMethod('select').argNames.dump;
Collection.findMethod('select').varNames.dump;
// -> nil // doesn't have any varNames


// dump its code. mostly for debugging the compiler.
Collection.findMethod('select').dumpByteCodes;

// a shorter version of the above
Collection.dumpByteCodes('select');


{ 1 + 2 }.dump;              // this is a Function
{ 1 + 2 }.def.dump;          // dump its FunctionDef
{ 1 + 2 }.asCompileString;   // show its implementation
{ 1 + 2 }.def.dumpByteCodes; // dump its code.
::

subsection:: Snooping in GUI Windows

code::
(
// create some windows to snoop in
5.do { | i |
	var w, b;
	w = Window.new("snoop " ++ i.asString,
		Rect.new( 200 + 400.rand, 69 + 300.rand, 172, 90 ));
	w.front;
	b = Button.new( w, Rect.new( 23, 28, 127, 25 ));
	b.states = [["BLAM-O", Color.red]];
}
)

Window.allWindows.dump;	// dump a list of all open Windows

// a little more helpful, dump their names
Window.allWindows.collect { | w | w.name }.postln;

(
// change background colors of all open windows
Window.allWindows.do { | window |
	window.view.background = Color.new(0.5 + 0.5.rand, 0.5 + 0.5.rand, 0.5 + 0.5.rand);
}
)

Window.closeAll; // close all the windows
::

subsection:: Snooping in SynthDefs
code::
// a synthdef to snoop in
(
f = SynthDef(\snoop, { | out=0 |
		Out.ar(out, PinkNoise.ar(0.1))
});
)

// get the ugens, listed in order of execution, with rate,
// index and inputs
f.dumpUGens;
::

subsection:: Snooping on the Server

Lots of information on server-related snooping can be found in the link::Classes/Server:: helpfile under "Information and debugging".

Some examples code::
s.boot;

f = { PinkNoise.ar(0.1) * SinOsc.ar }; // a function
x = f.play;

// look at all the nodes on the server
s.queryAllNodes;

// parsed contents
s.dumpOSC(1);
x.free;
x = f.play;

// contents in hexadecimal
// status messages are not filtered
s.dumpOSC(2);
x.free;
x = f.play;

// turn off
s.dumpOSC(0);
::


subsection:: Snooping in the Interpreter

When evaluating text in the interpreter, the variable 'this' always refers to the interpreter.
code::
// display the values of all the interpreter variables a-z
this.dump;

// set all variables a-z to nil
this.clearAll;


// compile some text into a Function
g = this.compile("(1 + 2).postln");
g.postln;   // g is a Function
g.value;    // evaluate g

// interpret some text
this.interpret("(1 + 2).postln");

// interpret some text and print the result
this.interpretPrint("1 + 2");
::
