Refactor Document

[mossheim]

See previous discussions for background:
#1208
#1396
#2314
Mailing list discussion (most recent)

Goals

The main purpose here is to replace the existing Document class with a more constrained, consistent, and flexible interface that will allow other IDEs/editors to easily link into and use SuperCollider's Document class. A few major steps need to be taken:

• Disentangle Document from ScIDE (see esp. method extensions warnings for non-existent class Document when using sclang without of the IDE #1208 and Compile ERROR when starting sclang: Class extension for nonexistent class 'Document' #1396)
• Reduce and refactor Document (see setter for Document text adds instead of setting it, getter returns nothing #2314, mailing list discussion)
• Bring Document's interface into alignment with TextView (see mailing list discussion)

Progress

So far, I've make progress toward step 1 by following @scztt's recommendations in #1208/#1396 and moving Document out of ScIDE.sc and into its own file in /SCClassLibrary/Common/Core. In addition, I've added a linkedIDE classvar that will be linked with the proper IDE class at runtime, and directed all simple method calls on ScIDE to linkedIDE. I haven't replaced the primitives, because some of them are a little entangled and I haven't decided how to proceed yet.

Plans

I'd like to reduce and/or deprecate a good number of methods in Document. The interface is bloated. For instance, Document should not IMO have knowledge of allDocuments—this should be the responsibility of the IDE.

Per @jamshark70's suggestion, I'd also like to expand knowledge of lines in Document. For instance: count lines, index-in by line, select line(s), replace line(s), and so on. While some of this could conceivably be handled by String, I don't think it's a good idea to tie String to Document's particular understanding of lines (i.e. how various combinations of \r and \n could be considered line breaks or not).

@telephon suggested the possibility of moving the old Document to a Quark. While I see nothing harmful in this necessarily, I think (as many people have pointed out) this is a very broken bit of SC, and it should be allowed to die gracefully. Let's save that discussion until later on please, unless it has direct bearing on the path of development.

TBD

This is a stub/WiP PR, and so some points of development are open for discussion. Some issues can also be taken to the mailing list for more feedback/ideas as needed. At the moment, I'd like to focus on

• any issues people might have with how I've begun,
• whether Document.sc should really be in /SCClassLibrary/Common/Core (/GUI seems like another good option, but which subfolder?), and
• what the next steps might be in slimming down Document's interface.

[telephon]

Should there be a superclass for IDEs which settles an IDE-independent API? It would be good to be able to still open a document programmatically.

[mossheim]

Yes, I'd be totally open to that! Am I correct that in thinking that the advantage there is leaving the possibility open for alternate editors to link into that functionality, at the slight cost of additional work for this PR? I suppose Document should not really be in charge of choosing its linked IDE...

[telephon]

yes, it would make it easier for developers of editors to know what is expected. Some things that are now in Document, esp. allDocuments and currentDocument are really quite important for the minimal set of programmatic functionality and should be required.

I am not completely sure if it might be better to keep the above two methods in Document, but I see your point.

[mossheim]

Great! Yeah, I see now how I've already implied that architecture by leaving a comment about "IDEs should implement these methods"—it plainly calls for a "subclass responsibility" stub.

[mossheim]

Closing until I have time to work on this again.