open-input-text-editor in Editors

• (open-input-text-editor text-editor start-position end-position snip-filter port-name expect-to-read-all?) -> input-port
     text-editor : text% object
     start-position = 0 : exact non-negative integer
     end-position = 'end : exact non-negative integer or 'end
   snip-filter = (lambda (s) s) : a procedure of one argument: a snip% object
     port-name = text-editor : value
     expect-to-read-all? = #f : boolean

  Creates an input port that draws its content from text-editor. The editor content between positions start-position and end-position is the content of the port. If end-position is 'end, the content runs until the end of the editor. If a snip that is not a string-snip% object spans start-position or end-position, the entire snip contributes to the port. If a string-snip% instance spans start-position, only the part of the snip after start-position contributes, and if a string-snip% object spans end-position, only the part before end-position contributes.

  An instance of string-snip% in text-editor generates a character sequence in the resulting port. All other kinds of snips are passed to snip-filter to obtain a ``special'' value for the port. If a snip is returned as the first result from snip-filter, and if the snip is an instance of readable-snip<%>, the snip generates a special value for the port through the read-special method. If snip-filter returns any other kind of snip, it is copied for the special result. Finally, a non-snip first result from snip-filter is used directly as the special result.

  The port-name argument is used for the input port's name. The expect-to-read-all? argument is a performance hint; use #t if the entire port's stream will be read.

  The result port must not be used if text-editor changes in any of the following ways: a snip is inserted (see after-insert), a snip is deleted (see after-delete), a snip is split (see after-split-snip), snips are merged (see after-merge-snips), or a snip changes its count (which is rare; see recounted). The get-revision-number method can be used to detect any of these changes.