could we replace usage of "privileged" with "singleton"? it's a more accurate term and will make the pattern usage apparent to people who know it.

ok, done

could this be shortened to "configuration"?

also, to match style, the first word of each subsection should be capitalized

done

this method is missing a description

done

The name in the description should match the name of the argument in the method, which is num.

done

what does the lines arg to new do? that needs to be documented

done

i would really appreciate it if you could put some newlines between methods. it's hard to read in the current state.

sure, done

mixed whitespace after this comment

actually the commented-out post can just be removed, so I did that.

missing newline

done

i don't think you need to capitalize "failed" here. also, it might be a good idea to post the error message in addition to the line that failed

The scenario is that you play back a history, possibly in edited form, so the current state is not exactly the same, and some lines may fail.
Then I want to know when a line went wrong, and which one, so this should warn visibly.
So I would prefer changing this to:
warn("History code evaluation failed for line: ...")

As there may be multiple lines that fail, they should not spam the post window with long error posts every 2 seconds. Maybe we want a flag whether to post errors on playback?

As there may be multiple lines that fail, they should not spam the post window with long error posts every 2 seconds.

Wouldn't it be a good idea to stop at the first line that fails? And you can just take the error message, not the whole stack trace. Also, isn't this method also putting out quite a lot of extra information itself anyway? (4 lines per line evaluated)

Hm, seems we need two error modes for two use cases of History.play:

1. historian mode - reconstruct History to replay as accurately as possible
   -> on error, stop and throw, so one can edit history to fix it
2. showtime mode - replay history in segments, maybe in modified orders
   -> on error, keep playing, just post short info - next line might work again.

I'm confused, sorry... I'm just talking about evaluateAtLine, not play. Are they related in some way? It doesn't seem that History.play would ever result in calling this method.

But, I agree that's a good distinction to make. Would you rather do it as two functions or one?

Ah yes, you are right,
History.play does it differently, and should actually also protect against errors.
evaluateLineAt gets used from HistoryGui, and there it is not guaranteed that every line will work - state may not be as needed for the line, esp. if the line is code shared from other players by network.
ok, will consider what is best here.

does this mean "and then perform the filter"? i think that would be hard to understand for a non-native English speaker

yes, it does, added

this is a code smell IMO. but if there's no way to just pass it directly to a method call, I guess it works.

Generally it would be, yes :-) specifically here, it server two purposes:
when recording code experiments, you always write code that does not compile
or stops with errors, forgotten semicolons, etc etc.
all these broken lines would clutter recorded history, so it is useful to have th option to just forget them.
when performing with history playback, such as (First Rule of the Avantgarde:) Try it Backwards. in that case, any lines that depend on historically previous ones will produce errors.

a = [1, 2, 3]; // line 1
a.scramble; // line 2
// playing back line2 before line1 will produce 30 lines of Error post:
-> ERROR: Message 'scramble' not understood.
RECEIVER:
   nil
ARGS:
CALL STACK:
	DoesNotUnderstandError:reportError
		arg this = <instance of DoesNotUnderstandError>
	Nil:handleError
		arg this = nil
		arg error = <instance of DoesNotUnderstandError>
	Thread:handleError
		arg this = <instance of Thread>
		arg error = <instance of DoesNotUnderstandError>
	Object:throw
		arg this = <instance of DoesNotUnderstandError>
	Object:doesNotUnderstand
		arg this = nil
		arg selector = 'scramble'
		arg args = [*0]
	Interpreter:interpretPrintCmdLine
		arg this = <instance of Interpreter>
		var res = nil
		var func = <instance of Function>
		var code = "a.scramble"
		var doc = nil
		var ideClass = <instance of Meta_ScIDE>
	Process:interpretPrintCmdLine
		arg this = <instance of Main>
^^ The preceding error dump is for ERROR: Message 'scramble' not understood.
RECEIVER: nil

having your post window flooded with error messages in a show is annoying, and can slow down the IDE responses, so you want the option to suppress error posting - if you ever try turning it off, you will know exactly why you want it on ;-)
makes sense?

hm, not sure if that answers your comment - did it?

my question was more about it having class scope as opposed to function scope, but I get what you're saying.

The recording functions of History (and the related variables) are all class methods (class variables), because there is only one instance of Interpreter which we can add it to. I suppose instances could be useful for other kinds of logs, but this is not what the class is intended for currently.

The playback functions of History are all instance methods, because there are multple recordings that could be played back. So in such a way, it assumes that history happens only once, but leaves many traces.

I suspect that for clarity these could be two classes, or the recorder could have a single instance it redirects to. But for now, this looks good and has always worked rather well.

If you're going to abbreviate 'eval' below, you should do it here too.

done

this isn't strictly true, right? not sure why this check was added in preference to just doing a no-op.

Well, when users play a history (current or recorded) and nothing happens, they may be surprised. Next thing they would check is probably whether this history is empty - so why not tell them? History is used in live coding performances, and anything that helps and speeds up orientation live is desirable I think.
Maybe the line should be "History:play - the history is empty, so there is nothing play yet.".postln;
?

changed it be more accurate, informative, and less worry-inducing:

		if (lines.isEmpty) {
			"% - % is empty, so there is nothing to play.".postf(
				thisMethod,
				if (this == History.current) { "History.current" } { "this history" }
			);

are these comments stil relevant?

I guess yes - Document:path_ still gives a NotYetImplemented error. would be noce to be able to set a path where this document would be saved when you hit save, rather than having to navigate and type in the path.
hm, could write it as a file first, and then read in the file...
I'll think about that some more.

Tried again, setting path still does not work,
and IDE save dialog does not take the document title...
so I would keep the comment like this:
//.path_(docTitle); // path not working yet in Qt
// - would be nice to set and show a path
// where the doc can be saved later, by hand or automatically.

thanks! in the future, would be good to mark that with TODO or FIXME so it can be easily found in the codebase

please move this method to the deprecated folder

done.