HelpSource/Classes/History.schelp

   1 class:: History
   2 summary:: keeps a history of interpreted lines of code
   3 related:: Classes/Archive
   4 categories:: Streams-Patterns-Events
   5
   6 description::
   7
   8 History keeps track of all code lines that are being executed, in order to forward them to other players, to easily reuse earlier versions, or to store and reproduce a performance. Since it records everything that is interpreted, there is only one privileged instance of History - code::History.current::.
   9 (adc 2006/7)
  10
  11 ClassMethods::
  12
  13 private::initClass
  14
  15 method::start
  16 start adding interpreted code to (current) history.
  17
  18 method::end
  19 end adding interpreted code to (current) history.
  20
  21 method::clear
  22 remove all items from (current) history.
  23
  24 method::enter
  25 add an entry by hand.
  26
  27 method::document
  28 post the history in a new document (as story).
  29
  30 method::drop
  31 drop the newest n lines from history. if n is negative, drop the oldest n lines.
  32
  33 method::keep
  34 keep only the newest n lines from history. if n is negative, keep the oldest n lines.
  35
  36 method::saveCS
  37 store history as one compileString.
  38
  39 method::loadCS
  40 load a history from (compilestring) file.
  41
  42 method::saveStory
  43 store in a file, in historical order as individual code snippets.
  44
  45 method::loadStory
  46 read history into current, from a file in story format.
  47
  48 method::play
  49 play back current history from start to end line, per default verbose.
  50
  51 method::stop
  52 stop current history playback.
  53
  54 method::rewrite
  55 Write a properly formatted code file from a history.
  56
  57 argument::path
  58 The filename is the original name with "_rewritten." appended.
  59
  60 argument::open
  61 If open is true (default: true), open a text window with the string.
  62
  63 Examples::
  64
  65 code::
  66 History.clear.end;              // clear to start over
  67 History.start;                  // starts recording, opens log file
  68
  69                                 // execute these lines one by one
  70 1 + 2;
  71 p = ProxySpace.push(s.boot);
  72 ~a = {Dust.ar([1,1] * 30 ) * 0.3 }; //
  73 ~a.play;
  74 ~a.end;
  75
  76 History.end;            // NOTE: change of interface! History.end ends logging now.
  77
  78
  79 History.document; // create a document with all the changes
  80
  81 History.showLogFile; //
  82
  83 g = History.makeWin(0@20); // make a gui window, put it where you like
  84 g = History.makeWin(0@20, 5); // lines to see in textview
  85
  86 History.play;                   // posts lines by default;
  87
  88 History.play(verbose: false);   // just do it, no posting;
  89
  90         // continue recording
  91 History.start;
  92
  93 10 + 200;                       // enter 5 more lines
  94 p.push;
  95 ~b = { |freq=500| LFDNoise3.ar(freq.dup(2)) * 0.2 };
  96 ~b.play;
  97 ~b.set(\freq, 1000);
  98 ~b.end(2);
  99
 100 History.end;
 101
 102
 103         // save current history to a file.
 104 History.saveCS("~/Desktop/TestHist.scd");
 105 h = History.new.loadCS("~/Desktop/TestHist.scd");
 106 h.lines.printcsAll; "";
 107
 108         // under the hood: History.someCommand goes to History.current:
 109
 110         // History.current is where new codelines always go.
 111 h = History.current;
 112 h.lines.printcsAll; "";
 113 h.lineShorts.printcsAll; "";    // lineshorts are for gui display
 114
 115 History.enter("2 + 2");         // make a simple entry by hand.
 116 h.lines.printcsAll; "";
 117
 118                 // one can edit a history:
 119
 120 History.drop(-1); // drop the oldest memory
 121 History.drop(1); // drop the newest memory
 122
 123 h.keep(9);              h.lines.printAll; "";
 124 h.drop(3);              h.lines.printAll; "";
 125 h.removeLast;           h.lines.printAll;"";
 126 h.removeAt([3, 4]);     h.lines.printAll;"";
 127
 128
 129 // more examples
 130 History.clear.start;
 131
 132 1 + 2;                  // code lines get stored
 133
 134 (nil + 2).postln;       // error lines are ignored
 135
 136         // comment-only line is kept, empty lines not:
 137
 138         // save and load as text files
 139
 140
 141 History.saveCS; // save as compilestring for reloading.
 142                         // save with name, in forward time order.
 143 History.saveCS("~/Desktop/testHist.scd", forward: true);
 144                         // load back in from file
 145 h = History.new.loadCS("~/Desktop/testHist.scd", forward: true);
 146 h.lines.postcs; "";
 147
 148         // save as human-readable/hand-playable story
 149 History.saveStory               // write all to time-stamped file in historical order
 150 History.saveStory("~/Desktop/myTestStory.scd"); // ... with given filename.
 151 History.loadStory("~/Desktop/myTestStory.scd"); // load from story format file
 152
 153 Document.open("~/Desktop/myTestStory.scd");     // the story file is human-readable.
 154
 155
 156         // Various Internals
 157         // make a new instance of History by hand:
 158 h = History([[0, \me, "1+2"], [1.234, \me, "q = q ? ();"], [3, \me, "\"History\".speak"]]);
 159 h.lines.printcsAll; "";
 160 h.lineShorts.printcsAll; "";
 161
 162 h.play; // play it
 163 h.stop;
 164
 165
 166         // string formatting utils
 167 h.storyString;
 168 History.formatTime(1234.56);
 169 History.unformatTime("0:20:34.56");
 170 (
 171 History.prettyString("
 172 /* removes line returns at start and end of code strings ... */
 173
 174 ").postcs;
 175 )       // convert a line to a short string of n characters for gui display
 176 History.shorten(h.lines.first.postcs, 60).postcs;
 177
 178
 179         // in networked setups, one may turn off local recording and rely on remote recording:
 180 History.recordLocally
 181 History.localOff
 182 History.recordLocally
 183 History.localOn
 184 History.recordLocally
 185
 186
 187         // by default, history always logs here (and makes the folder if not there yet):
 188 History.logFolder;
 189 History.showLogFolder;
 190 History.logPath;
 191 History.showLogFile;    // current logfile...
 192         // todo: optionally, one should be able to turn logging off?
 193
 194         // filtering lines, to get subsets of all lines by key and/or searchstring:
 195
 196         // get indices for specific keys
 197 h = History([[0, \me, "a=1+2"], [1, \me, "3+5"], [1.234, \you, "q = q ? ();"], [3, \her, "\"Herstory ==== \".speak"]]);
 198 h.keys;
 199 h.matchKeys(\me);
 200 h.matchKeys(\you);
 201 h.matchKeys(\her);
 202 h.matchKeys;            // nil if no test
 203 h.matchKeys(\all);      // all keys match
 204 h.matchKeys([\me, \her])
 205 h.matchKeys(\isidor)    // empty array if no line found
 206
 207 h.matchString("Herst");
 208 h.matchString("q");
 209 h.matchString("1+");
 210 h.matchString("herStory", false); // ignoreCase is false by default
 211 h.matchString("herStory", true); // ignoreCase
 212
 213 h.indicesFor([\me, \her], "="); // indices for line written by \me or \her AND containing "=";
 214
 215         // searching is only an interface/access feature,
 216         // so please read on at HistoryGui help ...
 217 h.makeWin;
 218
 219 HistoryGui.openHelpFile;
 220 ::