History | SuperCollider 3.13.0 Help

Description

History stores all code strings as they are being evaluated, in order to reuse code written earlier, to forward code to other players, or to store, reproduce, edit and analyse live-coded performances. It records every evaluated code string into a singleton instance of History - History.current.

First examples:History.clear.end; // if needed, clear History first History.start; // starts recording, opens log file // execute these lines one by one, as a little performance history 1 + 2; p = ProxySpace.push(s.boot); ~a = {Dust.ar([1,1] * 30 ) * 0.3 }; ~a.play; ~a.end(3); History.started; // is it on now? // stops recording history and ends logging. History.end; History.started; History.document; // creates a document with current history History.showLogFolder; // opens the folder where logs are written. History.showLogFile; // opens the current log file as it was written. // make a gui window, to access code history lines at will, // e.g. for code reuse in performance, adaptation, sharing, etc: g = History.makeWin; // specify left-bottom position, and number of lines in textview g = History.makeWin(0@20, 5); // play back the recorded history line by line History.play(0); // history can even record and play back stops with CmdPeriod. // run these lines one at a time: History.clear.start; 1 + 2; 2 + 3; s.boot; (dur: inf).play; CmdPeriod.run; // or hit the Stop key command, Cmd-., or ctrl-. 3 + 4; // continue recording into history 4 + 5; History.end; // Replays history, including a CmdPeriod, and keeps replaying history. History.play;

Class Methods

NOTE: Many class methods are redirected to the privileged instance of History, History.current. This is intended to provide a simple code user interface.

History.start

start adding interpreted code to (current) history.

History.end

end adding interpreted code to (current) history.

History.started

boolean whether History is started.

History.document: METHOD NOT FOUND!

post the history in a new document (as story). The document title is a string formatted as follows: "%Y-%m-%d-%Hh%M-History".

History.current

History.current = value

the current History instance

History.lines

History.lineShorts

the currently recorded lines in History.current. lineShorts is a copy with shortened strings for display.

History.makeWin: METHOD NOT FOUND!

make a HistoryGui for History.current. argument: where a point that sets left top of the HistoryGui window, argument: numItems the number of lines in the textview

Configuration

History.keepsLog

History.keepsLog = value

get and set flag whether to log History to a file.

History.verbose

History.verbose = value

get and set flag whether to post debug messages from History operations.

History.recordLocally

History.recordLocally = value

get and set flag to turn recording local code evaluation on and off

History.localOff

History.localOn

convenience to turn recording of local code evaluation on and off

History.forwardFunc

History.forwardFunc = value

a function to run on incoming new lines, can be used to send code by network. See the Utopia quark for examples of networking code history.

Save and load history logs

History.showLogFolder

open folder where logfiles are stored

History.showLogFile

open current log file

History.saveCS(path, forward: false)

store history as one compileString.

History.loadCS(path, forward: false)

load a history from (compilestring) file.

History.saveStory(path)

store in a file, in historical order as individual code snippets.

History.loadStory(path)

read history into current, from a file in story format.

History.rewrite(path, open: true)

Write a properly formatted code file from a history.

Arguments:

path	The filename is the original name with "_rewritten." appended.
open	If open is true (default: true), open a text window with the string.

History.readFromDoc(path)

read in a history from a code file created with .rewrite

Editing history

History.clear

remove all items from (current) history.

History.enter(lineStr, id: 'me')

add an entry to (current) history by hand.

History.drop(num)

drop the newest num lines from history. if n is negative, drop the oldest n lines.

History.keep(num)

keep only the newest num lines from history. if n is negative, keep the oldest n lines.

History.removeAt(index)

remove a specific line

History.removeLast

remove last line from history

Repeating history

Repeating history can have different uses: A. Reconstruction, e.g. redoing a history of coding steps as closely as possible, or replaying a full performance as closely as possible; here, all errors are important and should be handled individually. B. Experimental live performance, e.g. replaying snippets from a recorded networked live-coding show in nonlinear orders; here, errors will occur more often because the current state will not always fit with what a particular line would require. Thus, one will likely prefer the robustness to just keep going.

History.ignoreErrors

History.ignoreErrors = value

global flag whether evaluating code lines via History will ignore errors or stop and throw them.

History.eval(codeString, ignoreError)

evaluate codeString, and optionally, use ignoreError to override global ignoreErrors flag.History.ignoreErrors = true; History.eval("2 + 1").postln; // correct code, so is just evaluated History.eval("2 + qwe"); 123; // compile error, but keeps going and posts 123 History.eval("1.blonk"); 123; // runtime error, keeps going -> posts 123 History.eval("1.blonk", false); 123; // throws error and stops, code after it never happens.

History.evalLineAt(index)

evaluate the line at index in History.current.lines

History.play(start: 0, end, verbose: true)

play back current history from start to end line, per default verbose.

History.stop

stop current history playback.

Date, time, string functions

History.startTimeStamp

History.formatTime(val)

History.unformatTime(str)

History.shorten(line, maxLength)

History.prettyString(str)

History.new(lines)

create a new instance containing the lines given.

Inherited class methods

Undocumented class methods

History.playCmdPeriod

Instance Methods

NOTE: the instance methods

[hasMovedOn_, hasMovedOn, play, stop, lines, lineShorts, removeAt, removeLast, keep, drop, clear, saveCS, loadCS, saveStory, evalLineAt, loadStory, makeWin, document]

are also implemented as class methods, and documented above.

.isCurrent

flag whether this history is History.current

.makeCurrent

make this history History.current

.player

the player task for ths history

.keys

all keys of code authors in this history

.addLine(now, authID, lineStr)

add a line to history with current time, id, and code string

.indicesFor(keys, string: "")

find line indices created by keys and containing string. used for filtering.

Inherited instance methods

Examples

// same as first example:
History.clear.end;      // clear to start over
History.start;          // starts recording, opens log file

// execute these lines one by one
1 + 2;
p = ProxySpace.push(s.boot);
~a = {Dust.ar([1,1] * 30 ) * 0.3 };
~a.play;
~a.end;

History.end; // History.end ends logging as well.

History.document; // create a document with all the changes
History.showLogFile; // open the log file as it was written.

g = History.makeWin(0@20); // make a gui window, put it where you like
g = History.makeWin(0@20, 5); // number of lines in textview

History.play;                  // posts lines by default
History.play(verbose: false);  // just do it, no posting

// continue recording
History.start;

// enter 5 more lines
10 + 200;
p.push;
~b = { |freq=500| LFDNoise3.ar(freq.dup(2)) * 0.2 };
~b.play;
~b.set(\freq, 1000);
~b.end(2);

History.end;

// save current history to a file.
History.saveCS("~/Desktop/TestHist.scd");
h = History.new.loadCS("~/Desktop/TestHist.scd");
h.lines.printcsAll; "";

// Many History methods are redirected to History.current:

// History.current is where new codelines always go.
h = History.current;
h.lines.printcsAll; "";

// lineshorts are for gui display:
h.lineShorts.printcsAll; "";

// make a simple entry by hand.
History.enter("2 + 2");
h.lines.printcsAll; "";

// one can edit a history:
History.drop(-1); // drop the oldest memory
History.drop(1); // drop the newest memory

h.keep(9); h.lines.printAll; "";
h.drop(3); h.lines.printAll; "";
h.removeLast;       h.lines.printAll;"";
h.removeAt([3, 4]); h.lines.printAll;"";

// more examples
History.clear.start;

1 + 2; // code lines get stored

(nil + 2).postln; // error lines are ignored

// comment-only line is kept, empty lines not:
History.enter("// comment only");
History.enter(" ");

// save and load as text files

History.saveCS; // save as compilestring for reloading.

// save with name, in forward time order.
History.saveCS("~/Desktop/testHist.scd", forward: true);

// load back in from file
h = History.new.loadCS("~/Desktop/testHist.scd", forward: true);
h.lines.postcs; "";

// save as human-readable/hand-playable story
// write all to time-stamped file in historical order:
History.saveStory;

// ... with given filename.
History.saveStory("~/Desktop/myTestStory.scd");

// load from story format file
History.loadStory("~/Desktop/myTestStory.scd");

Document.open("~/Desktop/myTestStory.scd");    // the story file is human-readable.

// Various Internals
// make a new instance of History by hand:
h = History([
    [0, \me, "1+2"],
    [1.234, \me, "q = q ? ();"],
    [3, \me, "\"History\".postln"]]);
h.lines.printcsAll; "";
h.lineShorts.printcsAll; "";

h.play; // play it back
h.stop;

// string formatting utils
h.storyString;
History.formatTime(1234.56);
History.unformatTime("0:20:34.56");

(
History.prettyString("

/* removes line returns at start and end of code strings ... */

").postcs;
)

// convert a line to a short string of n characters for gui display
History.shorten(h.lines.first.postcs, 60).postcs;

// in networked setups, one may turn off local recording and rely on remote recording:
History.recordLocally
History.localOff
History.recordLocally
History.localOn
History.recordLocally

// by default, history always logs here (and makes the folder if not there yet):
History.logFolder;
History.showLogFolder;
History.logPath;
History.showLogFile; // current logfile...
// todo: optionally, one should be able to turn logging off?

// filtering lines, to get subsets of all lines by key and/or searchstring:

// get indices for specific keys
h = History([[0, \me, "a=1+2"], [1, \me, "3+5"], [1.234, \you, "q = q ? ();"], [3, \they, "\"The-story ==== \".postln"]]);
h.keys;
h.matchKeys(\me);
h.matchKeys(\you);
h.matchKeys(\they);
h.matchKeys;        // nil if no test
h.matchKeys(\all);  // all keys match
h.matchKeys([\me, \they])
h.matchKeys(\isidor) // empty array if no line found for this key

h.matchString("The-s");
h.matchString("q");
h.matchString("1+");
h.matchString("the-Story", false); // ignoreCase is false by default
h.matchString("the-Story", true); // ignoreCase

h.indicesFor([\me, \they], "=");    // indices for line written by \me or \her AND containing "=";

// searching is only an interface/access feature,
// so please read on at HistoryGui help ...
h.makeWin;

HistoryGui.help;

helpfile source: https://github.com/supercollider/supercollider/tree/3.13/HelpSource/Classes/History.schelp
link::Classes/History::

History : Object