Author:         Emiliano Gavilán <[email protected]>
Author:         aspect <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        13-Jan-2021
Post-History:
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

Abstract

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

Rationale

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.

Specification

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

to:

file stat name ?varName?

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

errors are reported exactly as they would be if varName was provided
if no error occurs, the result is returned as a dict instead of by populating an array

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

Example

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

Implementation

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).

Copyright