@ -419,7 +419,10 @@ namespace eval shellfilter::chan {
} }
method initialize {transform_handle mode} { method initialize {transform_handle mode} {
#return [list initialize read drain write flush clear finalize] #return [list initialize read drain write flush clear finalize]
return [list initialize write flush clear finalize] #'clear' deliberately NOT declared: when a transform declares it, the core
#delivers a 'clear' op before EVERY write (tclIORTrans.c ReflectOutput), not
#just on seek - see goals/archive/G-145-piped-usage-ansi-remnants.md.
return [list initialize write flush finalize]
} }
method finalize {transform_handle} { method finalize {transform_handle} {
#Note that an error in the finalize can stop 'chan pop' from running properly. #Note that an error in the finalize can stop 'chan pop' from running properly.
@ -430,8 +433,15 @@ namespace eval shellfilter::chan {
# must be present but we ignore it because we do not # must be present but we ignore it because we do not
# post any events # post any events
} }
#G-145 defect class: 'clear' must NOT discard o_encbuf (held partial multi-byte
#character). With clear declared, the core calls it before every write; dropping
#the carry leaves the next chunk starting with orphan continuation bytes, making
#whole chunks unconvertible - they accumulate in o_encbuf and successive clears
#discard them, eating contiguous ranges of multibyte-dense output (the 2026-08-03
#unix repl result-echo corruption). Kept as a state-preserving no-op in case
#'clear' is ever re-declared; this write-only transform has no read-side state
#(the documented scope of 'clear').
method clear {transform_handle} { method clear {transform_handle} {
set o_encbuf ""
return return
} }
#method drain {transform_handle} { #method drain {transform_handle} {
@ -471,16 +481,22 @@ namespace eval shellfilter::chan {
# return $clear # return $clear
#} #}
method flush {transform_handle} { method flush {transform_handle} {
set clear $o_buffered$o_encbuf #this class holds only o_encbuf (raw bytes of a trailing incomplete
if {[catch {tcl::encoding::convertfrom $o_enc $clear} stringdata]} { #multi-byte character) - there is no o_buffered ansi-carry here (that
#if we can't convert the buffer contents to a string - does it make sense to emit the raw bytes? #belongs to the ansiwrap/ansistrip style transforms).
# - probably not. #An incomplete char is not decodable on its own: hold it for the next write
#REVIEW? #rather than emitting garbage or discarding (G-145: dropping held stream
#state corrupts content split across write chunks). finalize dropping it at
#true end of stream is acceptable.
if {$o_encbuf eq ""} {
return ""
}
if {[catch {tcl::encoding::convertfrom $o_enc $o_encbuf} stringdata]} {
return "" return ""
} }
set o_buffered ""
set o_encbuf "" set o_encbuf ""
return $stringdata puts -nonewline $o_localchan $stringdata
return [tcl::encoding::convertto $o_enc $stringdata]
} }
method write {transform_handle bytes} { method write {transform_handle bytes} {
#set logdata [tcl::encoding::convertfrom $o_enc $bytes] #set logdata [tcl::encoding::convertfrom $o_enc $bytes]
@ -570,16 +586,19 @@ namespace eval shellfilter::chan {
# return $clear # return $clear
#} #}
method flush {transform_handle} { method flush {transform_handle} {
set clear $o_buffered$o_encbuf #only o_encbuf exists in this class (no o_buffered ansi-carry as in ansiwrap).
if {[catch {tcl::encoding::convertfrom $o_enc $clear} stringdata]} { #An incomplete multi-byte char is not decodable on its own: hold it for the
#if we can't convert the buffer contents to a string - does it make sense to emit the raw bytes? #next write rather than discarding (G-145: dropping held stream state
# - probably not. #corrupts content split across write chunks).
#REVIEW? if {$o_encbuf eq ""} {
return ""
}
if {[catch {tcl::encoding::convertfrom $o_enc $o_encbuf} stringdata]} {
return "" return ""
} }
set o_buffered ""
set o_encbuf "" set o_encbuf ""
return $stringdata ::shellfilter::log::write $o_logsource $stringdata
return [tcl::encoding::convertto $o_enc $stringdata]
} }
method write {ch bytes} { method write {ch bytes} {
#set logdata [tcl::encoding::convertfrom $o_enc $bytes] #set logdata [tcl::encoding::convertfrom $o_enc $bytes]
@ -668,16 +687,19 @@ namespace eval shellfilter::chan {
# return # return
#} #}
method flush {transform_handle} { method flush {transform_handle} {
set clear $o_buffered$o_encbuf #only o_encbuf exists in this class (no o_buffered ansi-carry as in ansiwrap).
if {[catch {tcl::encoding::convertfrom $o_enc $clear} stringdata]} { #logonly emits nothing downstream. An incomplete multi-byte char is not
#if we have data in the buffer that we haven't been able to convert to a string #decodable on its own: hold it for the next write rather than discarding
#- then we probably have some kind of encoding mismatch. Is it safer to discard it than to emit garbage chars to the log? #(G-145: dropping held stream state corrupts content split across write
#REVIEW. - we are writing the raw bytes to the log here because we can't convert them to a string. #chunks); if it decodes anyway (e.g after an encoding change), log it now.
#This may be useful for debugging issues, but it may also result in garbage data in the log. if {$o_encbuf eq ""} {
::shellfilter::log::write $o_logsource $o_encbuf return ""
}
if {![catch {tcl::encoding::convertfrom $o_enc $o_encbuf} stringdata]} {
::shellfilter::log::write $o_logsource $stringdata
set o_encbuf "" set o_encbuf ""
} }
return return ""
} }
method write {transform_handle bytes} { method write {transform_handle bytes} {
#set logdata [encoding convertfrom $o_enc $bytes] #set logdata [encoding convertfrom $o_enc $bytes]
@ -3838,5 +3860,5 @@ namespace eval shellfilter {
package provide shellfilter [namespace eval shellfilter { package provide shellfilter [namespace eval shellfilter {
variable version variable version
set version 0.2.4 set version 0.2.5
}] }]
