[SS] 30Dec2004 - [cfile] is a object based interface for file I/O in Tcl; an alternative to the usual commands operating on channels. I wrote this code because I use [chan] a lot, and it makes more simple to write programs that have to deal with files, and is in general a very tclish way to do it (very similar to [Tk]). The library exports two commands in the global namespace that are used to create file objects. The first command is called ''cfile'', and it takes exactly the same arguments of the Tcl [open] command, but instead of returning a file descriptor, it returns the name of a command that can be used to perform operations on that file. Example: % set f [cfile /etc/passwd] ::cfile::file1 % $f gets root:x:0:0:root:/root:/bin/zsh The first line of code opens the /etc/passwd file and creates the file object. The name of the file object is returned, and is used as a command in the second line, where the ''gets'' method is called. An alternative way to create file objects is to call the ''cfileFromChannel'' command, with a Tcl channel as argument. This will create a file object from an already open channel (useful to work with stdin, stdout, stderr, and other kind of channels). This is the list of available methods: '''close''' - close the file and release the object associated '''channel''' - return the Tcl channel of the file object '''content''' - return the whole file content '''gets''' ?varName? - like the [gets] command. '''read''' ?numChars? - like the [read] command. '''puts''' string - like the [puts] command. '''write''' string - like the [puts] command with the -nonewline option. '''foreach''' var body - execute ''body'' for every line of the file, assigning the value of the line to ''var'' at every iteration. '''map''' var body - like the ''foreach'' method, but returns a list composed of the return values of ''body'' at every iteration. '''lines''' - returns a Tcl list where every element is a line of the file '''putlist''' list - write every element of ''list'' to the file using [puts]. '''seek''' offset ?origin? - like the [seek] Tcl command '''rewind''' - the same as ''seek 0'' '''tell''' - like the [tell] Tcl command '''blocking''' boolean - set/unset the file blocking mode '''encoding''' value - set the file encoding to the specified value '''translation''' value - set the file translation to the specified value '''buffering''' value - set the file buffering to the specified value '''flush''' - like the [flush] Tcl command '''readable''' script - register a file readable event for the file, using the given script '''writable''' script - register a file writable event for the file, using the given script '''autoclean''' - automatically close the file when the current procedure exists There is very little need to comment the methods, most things are the same of Tcl commands. The ''autoclean'' method makes the file scope similar to a local variable, when the procedure exists the file is closed and the relative object released. Some example: source cfile.tcl # Example 1: counts the number of lines inside /etc/passwd set f [cfile /etc/passwd] set lines [llength [$f lines]] puts "/etc/passwd is composed of $lines lines" $f close # Example 2: put the whole file content into the $content variable set f [cfile /etc/passwd] set content [$f content] puts "/etc/passwd contains [string length $content] characters" $f close # Example 3: counts the number of lines inside /etc/passwd matching */bin/sh* set f [cfile /etc/passwd] set matches 0 $f foreach line { if {[string match {*/bin/sh*} $line]} { incr matches } } $f close puts "It contains $matches lines matching */bin/sh*" # Example 4: Alternative of Example 3 using the 'map' method. set f [cfile /etc/passwd] set matches [expr [join [$f map line {string match {*/bin/sh*} $line}] +]] puts "It contains $matches lines matching */bin/sh* (2)" $f close # Example 5: Sorts the lines of /etc/passwd and write the sorted # version of the file in /tmp/sorted.txt set f [cfile /etc/passwd] set lines [lsort [$f lines]] $f close set f [cfile /tmp/sorted.txt w] $f putlist $lines $f close # Example 6: Auto close a file when a procedure exits proc foobar {} { set f [cfile /etc/passwd] $f autoclean # Do some work, possibly complex with handling of special coditions... # The $f file will be automatically closed when the procedure returns. } foobar And finally the implementation: # Cfile - Object based interface for file handling in Tcl. # Copyright (C) 2004 Salvatore Sanfilippo # This software is released under the BSD license. package provide cfile 0.1 namespace eval cfile {} set ::cfile::id 0 array set ::cfile::fd {} proc cfile {filename args} { switch -- [llength $args] { 0 {set fd [open $filename]} 1 {set fd [open $filename [lindex $args 0]]} 2 {set fd [open $filename [lindex $args 0] [lindex $args 1]]} default { return -code error "wrong # of args for command" } } set id [incr ::cfile::id] set ::cfile::fd($id) $fd interp alias {} ::cfile::file$id {} ::cfile::__dispatch__ $id } proc cfileFromChannel channel { set id [incr ::cfile::id] set ::cfile::fd($id) $channel interp alias {} ::cfile::file$id {} ::cfile::__dispatch__ $id } proc ::cfile::__dispatch__ {id method args} { if {[info command ::cfile::__method__$method] eq {}} { return -code error "cfile: no such subcommand: '$method'" } set fd $::cfile::fd($id) uplevel 1 [list ::cfile::__method__$method $id $fd] $args } # Close the file proc ::cfile::__method__close {id fd} { catch {close $fd} catch {unset ::cfile::fd($id)} catch {interp alias {} $::cfile::file$id {}} } # Return the file channel proc ::cfile::__method__channel {id fd} { return $fd } # Return the whole content of the file. proc ::cfile::__method__content {id fd} { catch {seek $fd 0} set buf [read $fd] return $buf } # method similar to the [gets] command. proc ::cfile::__method__gets {id fd args} { if {![llength $args]} { gets $fd } else { upvar 1 [lindex $args 0] var gets $fd var } } # method similar to the [read] command. proc ::cfile::__method__read {id fd {count {}}} { if {$count eq {}} { return [read $fd] } else { return [read $fd $count] } } # method similar to the [puts] command. proc ::cfile::__method__puts {id fd buf} { puts $fd $buf } # method similar to the [puts] command with the -nonewline option proc ::cfile::__method__write {id fd buf} { puts -nonewline $fd $buf } # method foreach: # Execute a Tcl script for each line of file proc ::cfile::__method__foreach {id fd var script} { catch {seek $fd 0} upvar 1 $var line while {[gets $fd line] != -1} { uplevel 1 $script } } # method map: # Execute a Tcl script for each line of file, accumulate the result # of every iteration into a list, returned as result. proc ::cfile::__method__map {id fd var script} { catch {seek $fd 0} set result {} upvar 1 $var line while {[gets $fd line] != -1} { lappend result [uplevel 1 $script] } return $result } # method lines: return all the file lines as a Tcl list. proc ::cfile::__method__lines {id fd} { catch {seek $fd 0} set result {} while {[gets $fd line] != -1} { lappend result $line } return $result } # method putlist: write every element of $list as a file line. proc ::cfile::__method__putlist {id fd list} { foreach e $list { puts $fd $e } } # method similar to the [seek] command. proc ::cfile::__method__seek {id fd offset {origin start}} { seek $fd $offset $origin } # method rewind: equivalent to "seek 0" proc ::cfile::__method__rewind {id fd} { seek $fd 0 } # method similar to the [tell] command. proc ::cfile::__method__tell {id fd} { tell $fd } # method blocking: set the channel blocking mode on/off proc ::cfile::__method__blocking {id fd val} { fconfigure $fd -blocking $val } # method encoding: set the channel encoding proc ::cfile::__method__encoding {id fd val} { fconfigure $fd -encoding $val } # method translation: set the channel translation mode proc ::cfile::__method__translation {id fd val} { fconfigure $fd -translation $val } # method buffering: set the channel buffering mode proc ::cfile::__method__buffering {id fd val} { fconfigure $fd -buffering $val } # method flush: calls [flush] against the file channel proc ::cfile::__method__flush {id fd} { flush $fd } # method readable: set a callback for the 'fileevent readable' event. proc ::cfile::__method__readable {id fd script} { fileevent $fd readable $script } # method writable: set a callback for the 'fileevent writable' event. proc ::cfile::__method__readable {id fd script} { fileevent $fd writable $script } # method to automatically free a cfile once the current procedure returns. proc ::cfile::__method__autoclean {id fd} { set var __cfile__autoclean__$id uplevel 1 [list set $var {}] uplevel 1 [list trace add variable $var unset ::cfile::autocleanCallback] } # The trace callback handler for the 'autoclean' method. proc ::cfile::autocleanCallback {name1 name2 op} { set id [string range $name1 21 end] ::cfile::file$id close } Comments are very welcomed. This is new code that I hope to use many times in the future, so to improve it is one of my goal. [jcw] - Looks very nice. I have often wished channels to be more object-like at the core level (one can always wrap 'em of course). For a different angle on the file/directory side of things, see also a little project called [iohan], which brings dirs-of-files and many other collections into a Tcl setting. It address another issue than cfile, but it shows how there too one can take very simple OO-style APIs further towards implementation-independence. [RS] feels reminded of [Peter da Silva]'s '''stream''' extension discussed on [Tcl 2.1] :) I like the ''lines'' and ''map'' methods - that would be nice to have in the core. [SS] seems like that the very bad (IMHO) [chan] was adopted instead. [NEM] Note that all of the useful "methods" of [chan] take the channel as first argument, allowing you to wrap an object-like sugar around these channels: proc chan: {c cmd args} { uplevel 1 [linsert $args 0 ::chan $cmd $c] } interp alias {} log {} chan: [open myapp.log w] log configure -buffering line -encoding utf-8 log puts "INFO: this is a test..." ... log close The only exceptions are the ''create'' and ''names'' sub-commands, which do not take a channel at all (and do not make sense as instance methods), and the ''-nonewline'' options to ''puts'' and ''read'', which cannot be specified using this technique. Of course, this doesn't address the higher-level operations that cfile supports, but these can be added in tcllib or by further TIPs. See for instance [a higher-level channel API] for a start at this. ---- [Category Package]