TIP 594: Modernize "file stat" interface

Author:         Emiliano Gavil├ín <[email protected]>
Author:         aspect <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        13-Jan-2021
Keywords:       Tcl, file
Tcl-Version:    8.7
Tcl-Branch:     tip-594
Vote-Summary    Accepted 4/0/2
Votes-For:      FV, JN, KBK, SL
Votes-Against:  none
Votes-Present:  DGP, MC


This TIP proposes extending the file stat and file lstat commands to return a dictionary if no varName argument is provided.


The result of file stat is traditionally stored in an array named by its second argument. Now that dicts are available, a more ergonomic alternative is to simply return a value that the caller can process with the dict command, pass to other procs or return as a result. The original usage is preserved by making the varName argument optional.


The file stat and file lstat commands are both changed in exactly the same way. Using file stat as an example, its signature is changed from:

file stat name varName


file stat name ?varName?

With two arguments, it behaves exactly like before. With only one argument:

Previously, calling file stat with only one argument would raise a {TCL WRONGARGS} error.


Old (and preserved) usage:

% file stat / st
% parray st
st(atime)   = 1610459586
st(blksize) = 4096
st(blocks)  = 8
st(ctime)   = 1605692955
st(dev)     = 64769
st(gid)     = 0
st(ino)     = 2
st(mode)    = 16749
st(mtime)   = 1605692955
st(nlink)   = 18
st(size)    = 4096
st(type)    = directory
st(uid)     = 0

New usage:

% file stat /
type directory size 4096 mtime 1605692955 ino 2 dev 64769 atime 1610459586 uid 0 ctime 1605692955 nlink 18 gid 0 blksize 4096 mode 16749 blocks 8


The ticket modernize "file stat" interface includes a patch by Emiliano Galivan. This patch includes an update to the manual, a new test cmdAH-28.14 and changes two existing tests to accomodate the new interface (cmdAH-28.1 and cmdAH-28.2).


This document is placed in public domain.