Author:         Ashok P. Nadkarni <[email protected]>
State:          Draft
Type:           Project
Tcl-Version:    9.1
Tcl-Branch:     tip-701

---

Abstract

This TIP proposes a C API to expand ~ and ~user leading components in file paths.

Rationale

TIP 602 removed the implicit tilde substitution from Tcl's handling of file paths. The file home and file tildeexpand commands made equivalent functionality explicitly available to scripts. However, no comparable C API was made available to extensions. This TIP remedies the oversight.

Specification

The following new function will be exposed to extensions and applications.

int Tcl_FSTildeExpand(
    Tcl_Interp *interp,
    const char *path,
    Tcl_DString *dsPtr)

The function copies the path passed in path[] to the output dsPtr substituting leading ~ and ~user components in the path, if present, as described in TIP 602. The interp argument is used only for error messages and may be NULL.

The function returns TCL_OK on success with dsPtr containing the path with any leading tilde components substituted.

The function may return TCL_ERROR in (at least) the following cases:

• In the case of ~, the HOME environment variable does not exist.

• In the case of ~user, the specified user is not known to the system.

The function makes no guarantees about the form of the returned path such as the path separators used. The returned result should be passed to other Tcl C API functions such as Tcl_FSGetNormalizedPath or Tcl_FSGetNativePath if necessary.

Implementation

The tip-701 branch contains an implementation for 9.0.

Copyright

This document has been placed in the public domain.