TIP 594: modernize "file stat" interface

Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Emiliano Galivan <[email protected]>
Author:         aspect <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        13-Jan-2021
Keywords:       Tcl, file
Tcl-Version:    8.7
Tcl-Ticket:     560c5e438c47f5fdd34846dbb333ab96cb905416


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.