TIP #459: TCL PACKAGE INTROSPECTION IMPROVEMENTS 
==================================================
 Version:      $Revision: 1.6 $
 Author:       Jan Nijtmans <jan.nijtmans_at_gmail.com>
 State:        Draft
 Type:         Project
 Tcl-Version:  8.7
 Vote:         Pending
 Created:      Thursday, 08 December 2016
 URL:          https://tip.tcl-lang.org459.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes to improve package introspection by providing a new 
 command *package files*. 

 RATIONALE 
===========

 This TIP is inspired by a request from FlightAware to improve Tcl's 
 package introspection possibilities. Although only a *package files* 
 command was requested, extending *info loaded* gives the possibility to 
 find a shared library contained in a package more easily than searching 
 a list. 

 SPECIFICATION OF THE PROPOSED CHANGE 
======================================

 Two new additions are proposed, to the *package* and *info* commands. 

    1. *package files* /name/ 

       This command returns a list of filenames which were sourced 
       during the initialization of package /name/. More specific, the 
       files that were sourced during running the script registered 
       using *package ifneeded*. Left out are Tcl's own tclIndex and 
       pkgIndex.tcl files, which might have been accessed due to 
       dependancy searches, otherwise this would give very misleading 
       results. 

    2. *info loaded* ?/interpreter/? ?/name/? 

       The *info loaded* command already exists, it gives a list of 
       package names with corresponding shared library names which were 
       actually loaded in the give interpreter. The additional /name/ 
       argument restricts the result to the filename of the loaded 
       library only. 

 Tcl packages don't have to do anything special in order to be 
 introspected correctly, just note that files containing auto_loaded 
 commands cannot be introspected because they are not sourced during 
 package initialization. 

 REJECTED ALTERNATIVES 
=======================

       Use of /source -nopkg/ in tclIndex files. Even though this 
       addition in the earlier TIP was explicitly undocumented, it lead 
       to the misunderstanding that other Tcl extensions should do the 
       same. 

       Earlier implementation of this TIP didn't handle the second 
       argument of *info loaded* correctly in all cases, and the 
       handling in safe interpreters was not complete. This is all 
       corrected in the current implementation. 

       All filenames should be converted to absolute. This is rejected 
       for performance and for practical reasons. It could be quite 
       expensive to calculate because the disk has to be accessed for 
       possible hyper-links. Second, the package mechanism is already 
       designed such that all sourced paths are absolute (see below 
       example). Extensions using the *source* command with relative 
       paths are in danger already, this should be fixed in the 
       extension in stead of being masked in the *package files* 
       command. 

       Additional information about the sourced files (like mtime or 
       checksum) was suggested to be part of the introspection 
       information, but this has been rejected as overkill. It is much 
       more than requested in the Tcl-bounty, and it is difficult to 
       imagine what actual use this would bring. 

 REFERENCE IMPLEMENTATION 
==========================

 This is available in the /package_files/ branch 
 [<URL:http://core.tcl.tk/tcl/timeline?r=package_files>]. 

 EXAMPLES 
==========

   $ tclsh8.7
   % package files Tcl
   /usr/lib/tcl8.7/init.tcl
   % package require Tk
   8.7a0
   % package files msgcat
   /usr/lib/tcl8/8.5/msgcat-1.6.0.tm
   % package files Tk
   /usr/lib/tk8.7/tk.tcl /usr/lib/tk8.7/msgs/en.msg /usr/lib/tk8.7/icons.tcl ...
   % info loaded {} Tk
   /usr/lib/libtk8.7.so

 Note that *package require Tk* has the side-effect of loading the 
 /msgcat/ package, which is required by Tk. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

 Please note that any correspondence to the author concerning this TIP 
 is considered in the public domain unless otherwise specifically 
 requested by the individual(s) authoring said correspondence. This is 
 to allow information about the TIP to be placed in a public forum for 
 discussion. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows