home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.n / library.n < prev    next >
Encoding:
Text File  |  1995-07-17  |  13.0 KB  |  421 lines
  1. '\"
  2. '\" Copyright (c) 1991-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/library.n,v 1.11 93/08/28 16:05:59 ouster Exp $ SPRITE (Berkeley)
  22. '
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .de UL
  206. \\$1\l'|0\(ul'\\$2
  207. ..
  208. .HS library tcl
  209. .BS
  210. .SH NAME
  211. library \- standard library of Tcl procedures
  212. .SH SYNOPSIS
  213. .nf
  214. \fBauto_execok \fIcmd\fR
  215. \fBauto_load \fIcmd\fR
  216. \fBauto_mkindex \fIdir pattern pattern ...\fR
  217. \fBauto_reset\fR
  218. \fBparray \fIarrayName\fR
  219. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  220. .fi
  221. .BE
  222.  
  223. .SH INTRODUCTION
  224. .PP
  225. Tcl includes a library of Tcl procedures for commonly-needed functions.
  226. The procedures defined in the Tcl library are generic ones suitable
  227. for use by many different applications.
  228. The location of the Tcl library is returned by the \fBinfo library\fR
  229. command.
  230. In addition to the Tcl library, each application will normally have
  231. its own library of support procedures as well;  the location of this
  232. library is normally given by the value of the \fB$\fIapp\fB_library\fR
  233. global variable, where \fIapp\fR is the name of the application.
  234. For example, the location of the Tk library is kept in the variable
  235. \fB$tk_library\fR.
  236. .PP
  237. To access the procedures in the Tcl library, an application should
  238. source the file \fBinit.tcl\fR in the library, for example with
  239. the Tcl command
  240. .DS
  241. \fBsource [info library]/init.tcl
  242. .DE
  243. This will define the \fBunknown\fR procedure and arrange for the
  244. other procedures to be loaded on-demand using the auto-load
  245. mechanism defined below.
  246.  
  247. .SH "COMMAND PROCEDURES"
  248. .PP
  249. The following procedures are provided in the Tcl library:
  250. .TP
  251. \fBauto_execok \fIcmd\fR
  252. Determines whether there is an executable file by the name \fIcmd\fR.
  253. This command examines the directories in the current search path
  254. (given by the PATH enviornment variable) to see if there is an
  255. executable file named \fIcmd\fR in any of those directories.
  256. If so, it returns 1;  if not it returns 0.  \fBAuto_exec\fR
  257. remembers information about previous searches in an array
  258. named \fBauto_execs\fR;  this avoids the path search in
  259. future calls for the same \fIcmd\fR.  The command \fBauto_reset\fR
  260. may be used to force \fBauto_execok\fR to forget its cached
  261. information.
  262. .TP
  263. \fBauto_load \fIcmd\fR
  264. This command attempts to load the definition for a Tcl command named
  265. \fIcmd\fR.
  266. To do this, it searches an \fIauto-load path\fR, which is a list of
  267. one or more directories.
  268. The auto-load path is given by the global variable \fB$auto_path\fR
  269. if it exists.
  270. If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
  271. variable is used, if it exists.
  272. Otherwise the auto-load path consists of just the Tcl library directory.
  273. Within each directory in the auto-load path there must be a file
  274. \fBtclIndex\fR that describes one
  275. .VS
  276. or more commands defined in that directory
  277. and a script to evaluate to load each of the commands.
  278. The \fBtclIndex\fR file should be generated with the
  279. \fBauto_mkindex\fR command.
  280. If \fIcmd\fR is found in an index file, then the appropriate
  281. script is evaluated to create the command.
  282. .VE
  283. The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully
  284. created.
  285. The command returns 0 if there was no index entry for \fIcmd\fR
  286. or if the script didn't actually define \fIcmd\fR (e.g. because
  287. index information is out of date).
  288. If an error occurs while processing the script, then that error
  289. is returned.
  290. \fBAuto_load\fR only reads the index information once and saves it
  291. in the array \fBauto_index\fR;  future calls to \fBauto_load\fR
  292. check for \fIcmd\fR in the array rather than re-reading the index
  293. files.
  294. The cached index information may be deleted with the command
  295. \fBauto_reset\fR.
  296. This will force the next \fBauto_load\fR command to reload the
  297. index database from disk.
  298. .TP
  299. \fBauto_mkindex \fIdir pattern pattern ...\fR
  300. .VS
  301. Generates an index suitable for use by \fBauto_load\fR.
  302. The command searches \fIdir\fR for all files whose names match
  303. any of the \fIpattern\fR arguments
  304. .VE
  305. (matching is done with the \fBglob\fR command),
  306. generates an index of all the Tcl command
  307. procedures defined in all the matching files, and stores the
  308. index information in a file named \fBtclIndex\fR in \fIdir\fR.
  309. For example, the command
  310. .RS
  311. .DS
  312. \fBauto_mkindex foo *.tcl\fR
  313. .DE
  314. .LP
  315. will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
  316. and generate a new index file \fBfoo/tclIndex\fR.
  317. .PP
  318. \fBAuto_mkindex\fR parses the Tcl scripts in a relatively
  319. unsophisticated way:  if any line contains the word \fBproc\fR
  320. as its first characters then it is assumed to be a procedure
  321. definition and the next word of the line is taken as the
  322. procedure's name.
  323. Procedure definitions that don't appear in this way (e.g. they
  324. have spaces before the \fBproc\fR) will not be indexed.
  325. .RE
  326. .TP
  327. \fBauto_reset\fR
  328. Destroys all the information cached by \fBauto_execok\fR and
  329. \fBauto_load\fR.
  330. This information will be re-read from disk the next time it is
  331. needed.
  332. \fBAuto_reset\fR also deletes any procedures listed in the auto-load
  333. index, so that fresh copies of them will be loaded the next time
  334. that they're used.
  335. .TP
  336. \fBparray \fIarrayName\fR
  337. Prints on standard output the names and values of all the elements
  338. in the array \fIarrayName\fR.
  339. \fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
  340. It may be either local or global.
  341. .TP
  342. \fBunknown \fIcmd \fR?\fIarg arg ...\fR?
  343. This procedure is invoked automatically by the Tcl interpreter
  344. whenever the name of a command doesn't exist.
  345. The \fBunknown\fR procedure receives as its arguments the
  346. name and arguments of the missing command.
  347. .VS
  348. \fBUnknown\fR first calls \fBauto_load\fR to load the command.
  349. .VE
  350. If this succeeds, then it executes the original command with its
  351. original arguments.
  352. If the auto-load fails then \fBunknown\fR calls \fBauto_execok\fR
  353. to see if there is an executable file by the name \fIcmd\fR.
  354. If so, it invokes the Tcl \fBexec\fR command
  355. with \fIcmd\fR and all the \fIargs\fR as arguments.
  356. If \fIcmd\fR can't be auto-executed, \fBunknown\fR checks to
  357. see if the command was invoked at top-level and outside of any
  358. script.  If so, then \fBunknown\fR takes takes two additional steps.
  359. First, it sees if \fIcmd\fR has one of the following three forms:
  360. \fB!!\fR, \fB!\fIevent\fR, or \fB^\fIold\fB^\fInew\fR?\fB^\fR?.
  361. If so, then \fBunknown\fR carries out history substitution
  362. in the same way that \fBcsh\fR would for these constructs.
  363. Second, and last, \fBunknown\fR checks to see if \fIcmd\fR is
  364. a unique abbreviation for an existing Tcl command.
  365. If so, it expands the command name and executes the command with
  366. the original arguments.
  367. If none of the above efforts has been able to execute
  368. the command, \fBunknown\fR generates an error return.
  369. If the global variable \fBauto_noload\fR is defined, then the auto-load
  370. step is skipped.
  371. If the global variable \fBauto_noexec\fR is defined then the
  372. auto-exec step is skipped.
  373. Under normal circumstances the return value from \fBunknown\fR
  374. is the return value from the command that was eventually
  375. executed.
  376.  
  377. .SH "VARIABLES"
  378. .PP
  379. The following global variables are defined or used by the procedures in
  380. the Tcl library:
  381. .TP
  382. \fBauto_execs\fR
  383. Used by \fBauto_execok\fR to record information about whether
  384. particular commands exist as executable files.
  385. .TP
  386. \fBauto_index\fR
  387. Used by \fBauto_load\fR to save the index information read from
  388. disk.
  389. .TP
  390. \fBauto_noexec\fR
  391. If set to any value, then \fBunknown\fR will not attempt to auto-exec
  392. any commands.
  393. .TP
  394. \fBauto_noload\fR
  395. If set to any value, then \fBunknown\fR will not attempt to auto-load
  396. any commands.
  397. .TP
  398. \fBauto_path\fR
  399. If set, then it must contain a valid Tcl list giving directories to
  400. search during auto-load operations.
  401. .TP
  402. \fBenv(TCL_LIBRARY)\fR
  403. If set, then it specifies the location of the directory containing
  404. library scripts (the value of this variable will be returned by
  405. the command \fBinfo library\fR).  If this variable isn't set then
  406. a default value is used.
  407. .TP
  408. \fBenv(TCLLIBPATH)\fR
  409. If set, then it must contain a valid Tcl list giving directories to
  410. search during auto-load operations.
  411. This variable is only used if \fBauto_path\fR is not defined.
  412. .TP
  413. \fBunknown_active\fR
  414. This variable is set by \fBunknown\fR to indicate that it is active.
  415. It is used to detect errors where \fBunknown\fR recurses on itself
  416. infinitely.
  417. The variable is unset before \fBunknown\fR returns.
  418.  
  419. .SH KEYWORDS
  420. auto-exec, auto-load, library, unknown
  421.