From a0228c8a640edd842eff025d2542153404f38842 Mon Sep 17 00:00:00 2001 From: ericm Date: Fri, 28 Apr 2000 00:47:48 +0000 Subject: * doc/library.n: Added entries for auto_qualify and auto_import [Bug: 1271]. * doc/Init.3: Manual entry for Tcl_Init [Bug: 1820]. * doc/expr.n: Added documentation for each of the math library functions that expr supports [Bug: 1054]. FossilOrigin-Name: 3429c5f93a5cc5289544ad5bb92f65f23dd39bd2 --- ChangeLog | 10 ++++ doc/DumpActiveMemory.3 | 4 +- doc/Init.3 | 37 ++++++++++++++ doc/TCL_MEM_DEBUG.3 | 4 +- doc/expr.n | 88 ++++++++++++++++++++++++++++----- doc/library.n | 129 +++++++++++++++++++++++++++---------------------- doc/memory.n | 4 +- unix/mkLinks | 8 +++ 8 files changed, 210 insertions(+), 74 deletions(-) create mode 100644 doc/Init.3 diff --git a/ChangeLog b/ChangeLog index 0d1a365..390a778 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2000-04-27 Eric Melski + + * doc/library.n: Added entries for auto_qualify and auto_import + [Bug: 1271]. + + * doc/Init.3: Manual entry for Tcl_Init [Bug: 1820]. + + * doc/expr.n: Added documentation for each of the math library + functions that expr supports [Bug: 1054]. + 2000-04-26 Eric Melski * doc/memory.n: Man page for Tcl "memory" command, which is diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3 index ab2a766..02b8d81 100644 --- a/doc/DumpActiveMemory.3 +++ b/doc/DumpActiveMemory.3 @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: DumpActiveMemory.3,v 1.1 2000/04/27 01:46:59 ericm Exp $ +'\" RCS: @(#) $Id: DumpActiveMemory.3,v 1.2 2000/04/28 00:47:48 ericm Exp $ '\" .so man.macros .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures" @@ -59,7 +59,7 @@ which case validation of all blocks occurs when \fBckalloc\fR and \fBckfree\fR are called. This function forces the validation to occur at any point. -.SH SEE ALSO +.SH "SEE ALSO" TCL_MEM_DEBUG, memory .SH KEYWORDS diff --git a/doc/Init.3 b/doc/Init.3 new file mode 100644 index 0000000..8066fd3 --- /dev/null +++ b/doc/Init.3 @@ -0,0 +1,37 @@ +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id: Init.3,v 1.1 2000/04/28 00:47:48 ericm Exp $ +'\" +.so man.macros +.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Init \- find and source initialization script +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_Init\fR(\fIinterp\fR) +.SH ARGUMENTS +.AP Tcl_Interp *interp in +Interpreter to initialize. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the +\fBinit.tcl\fR script, which should exist somewhere on the Tcl library +path. On Macintosh systems, it additionally checks for an \fBInit\fR +resource and sources the contents of that resource if \fBinit.tcl\fR +cannot be found. +.PP +\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. + +.SH "SEE ALSO" +Tcl_AppInit, Tcl_Main + +.SH KEYWORDS +application, initialization, interpreter diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index bf6e2fe..6b1ec78 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.1 2000/04/27 01:46:59 ericm Exp $ +'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.2 2000/04/28 00:47:49 ericm Exp $ '\" .so man.macros .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" @@ -72,7 +72,7 @@ If you are desperate and validating memory on every call to of the caller, but they can actually be anything you want. Remember to remove the calls after you find the problem. -.SH SEE ALSO +.SH "SEE ALSO" memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory .SH KEYWORDS diff --git a/doc/expr.n b/doc/expr.n index 25f6ad6..44bc0b5 100644 --- a/doc/expr.n +++ b/doc/expr.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: expr.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.3 2000/04/28 00:47:49 ericm Exp $ '\" .so man.macros .TH expr n 8.0 Tcl "Tcl Built-In Commands" @@ -184,30 +184,80 @@ invoking the \fBexpr\fR command. Tcl supports the following mathematical functions in expressions: .DS .ta 3c 6c 9c -\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR -\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR -\fBatan2\fR \fBfloor\fR \fBpow\fR \fBtanh\fR -\fBceil\fR \fBfmod\fR \fBsin\fR +\fBabs\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR +\fBacos\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR +\fBasin\fR \fBexp\fR \fBpow\fR \fBtan\fR +\fBatan\fR \fBfloor\fR \fBrand\fR \fBtanh\fR +\fBatan2\fR \fBfmod\fR \fBround\fR +\fBceil\fR \fBhypot\fR \fBsin\fR +\fBcos\fR \fBint\fR \fBsinh\fR .DE -Each of these functions invokes the math library function of the same -name; see the manual entries for the library functions for details -on what they do. Tcl also implements the following functions for -conversion between integers and floating-point numbers and the -generation of random numbers: +.PP .TP \fBabs(\fIarg\fB)\fR Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. .TP +\fBacos(\fIarg\fB)\fR +Returns the arc cosine of \fIarg\fR, in the range [0,pi] +radians. \fIArg\fR should be in the range [-1,1]. +.TP +\fBasin(\fIarg\fB)\fR +Returns the arc sine of \fIarg\fR, in the range [-pi/2,pi/2] radians. +\fIArg\fR should be in the range [-1,1]. +.TP +\fBatan(\fIarg\fB)\fR +Returns the arc tangent of \fIarg\fR, in the range [-pi/2,pi/2] radians. +.TP +\fBatan2(\fIx, y\fB)\fR +Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [-pi,pi] +radians. \fIx\fR and \fIy\fR cannot both be 0. +.TP +\fBceil(\fIarg\fB)\fR +Returns the smallest integer value not less than \fIarg\fR. +.TP +\fBcos(\fIarg\fB)\fR +Returns the cosine of \fIarg\fR, measured in radians. +.TP +\fBcosh(\fIarg\fB)\fR +Returns the hyperbolic cosine of \fIarg\fR. If the result would cause +an overflow, an error is returned. +.TP \fBdouble(\fIarg\fB)\fR If \fIarg\fR is a floating value, returns \fIarg\fR, otherwise converts \fIarg\fR to floating and returns the converted value. .TP +\fBexp(\fIarg\fB)\fR +Returns the exponential of \fIarg\fR, defined as e**\fIarg\fR. If the +result would cause an overflow, an error is returned. +.TP +\fBfloor(\fIarg\fB)\fR +Returns the largest integral value not greater than \fIarg\fR. +.TP +\fBfmod(\fIx, y\fB)\fR +Returns the floating-point remainder of the division of \fIx\fR by +\fIy\fR. If \fIy\fR is 0, an error is returned. +.TP +\fBhypot(\fIx, y\fB)\fR +Computes the length of the hypotenuse of a right-angled triangle +(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fR). +.TP \fBint(\fIarg\fB)\fR If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by truncation and returns the converted value. .TP +\fBlog(\fIarg\fB)\fR +Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a +positive value. +.TP +\fBlog10(\fIarg\fB)\fR +Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a +positive value. +.TP +\fBpow(\fIx, y\fB)\fR +Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR +is negative, \fIy\fR must be an integer value. +.TP \fBrand()\fR Returns a floating point number from zero to just less than one or, in mathematical terms, the range [0,1). The seed comes from the @@ -218,10 +268,26 @@ function. If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. .TP +\fBsin(\fIarg\fB)\fR +Returns the sine of \fIarg\fR, measured in radians. +.TP +\fBsinh(\fIarg\fB)\fR +Returns the hyperbolic sine of \fIarg\fR. If the result would cause +an overflow, an error is returned. +.TP +\fBsqrt(\fIarg\fB)\fR +Returns the square root of \fIarg\fR. \fIArg\fR must be non-negative. +.TP \fBsrand(\fIarg\fB)\fR The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator. Returns the first random number from that seed. Each interpreter has it's own seed. +.TP +\fBtan(\fIarg\fB)\fR +Returns the tangent of \fIarg\fR, measured in radians. +.TP +\fBtanh(\fIarg\fB)\fR +Returns the hyperbolic tangent of \fIarg\fR. .PP In addition to these predefined functions, applications may define additional functions using \fBTcl_CreateMathFunc\fR(). diff --git a/doc/library.n b/doc/library.n index ea3b5ed..5e00b1e 100644 --- a/doc/library.n +++ b/doc/library.n @@ -5,18 +5,20 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: library.n,v 1.12 2000/04/26 22:36:10 ericm Exp $ +'\" RCS: @(#) $Id: library.n,v 1.13 2000/04/28 00:47:49 ericm Exp $ .so man.macros .TH library n "8.0" Tcl "Tcl Built-In Commands" .BS .SH NAME -auto_execok, auto_load, auto_mkindex, auto_mkindex_old, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures +auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures .SH SYNOPSIS .nf \fBauto_execok \fIcmd\fR +\fBauto_import \fIpattern\fR \fBauto_load \fIcmd\fR \fBauto_mkindex \fIdir pattern pattern ...\fR \fBauto_mkindex_old \fIdir pattern pattern ...\fR +\fBauto_qualify \fIcommand namespace\fR \fBauto_reset\fR \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR \fBparray \fIarrayName\fR @@ -73,65 +75,61 @@ remembers information about previous searches in an array named same \fIcmd\fR. The command \fBauto_reset\fR may be used to force \fBauto_execok\fR to forget its cached information. .TP +\fBauto_import \fIpattern\fR +\fBAuto_import\fR is invoked during \fBnamespace import\fR to see if +the imported commands specified by \fIpattern\fR reside in an +autoloaded library. If so, the commands are loaded so that they will +be available to the interpreter for creating the import links. If the +commands do not reside in an autoloaded library, \fBauto_import\fR +does nothing. +.TP \fBauto_load \fIcmd\fR This command attempts to load the definition for a Tcl command named -\fIcmd\fR. -To do this, it searches an \fIauto-load path\fR, which is a list of -one or more directories. -The auto-load path is given by the global variable \fB$auto_path\fR -if it exists. -If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment -variable is used, if it exists. -Otherwise the auto-load path consists of just the Tcl library directory. -Within each directory in the auto-load path there must be a file -\fBtclIndex\fR that describes one -or more commands defined in that directory -and a script to evaluate to load each of the commands. -The \fBtclIndex\fR file should be generated with the -\fBauto_mkindex\fR command. -If \fIcmd\fR is found in an index file, then the appropriate -script is evaluated to create the command. -The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully -created. -The command returns 0 if there was no index entry for \fIcmd\fR -or if the script didn't actually define \fIcmd\fR (e.g. because -index information is out of date). -If an error occurs while processing the script, then that error -is returned. -\fBAuto_load\fR only reads the index information once and saves it -in the array \fBauto_index\fR; future calls to \fBauto_load\fR -check for \fIcmd\fR in the array rather than re-reading the index -files. -The cached index information may be deleted with the command -\fBauto_reset\fR. -This will force the next \fBauto_load\fR command to reload the -index database from disk. +\fIcmd\fR. To do this, it searches an \fIauto-load path\fR, which is +a list of one or more directories. The auto-load path is given by the +global variable \fB$auto_path\fR if it exists. If there is no +\fB$auto_path\fR variable, then the TCLLIBPATH environment variable is +used, if it exists. Otherwise the auto-load path consists of just the +Tcl library directory. Within each directory in the auto-load path +there must be a file \fBtclIndex\fR that describes one or more +commands defined in that directory and a script to evaluate to load +each of the commands. The \fBtclIndex\fR file should be generated +with the \fBauto_mkindex\fR command. If \fIcmd\fR is found in an +index file, then the appropriate script is evaluated to create the +command. The \fBauto_load\fR command returns 1 if \fIcmd\fR was +successfully created. The command returns 0 if there was no index +entry for \fIcmd\fR or if the script didn't actually define \fIcmd\fR +(e.g. because index information is out of date). If an error occurs +while processing the script, then that error is returned. +\fBAuto_load\fR only reads the index information once and saves it in +the array \fBauto_index\fR; future calls to \fBauto_load\fR check for +\fIcmd\fR in the array rather than re-reading the index files. The +cached index information may be deleted with the command +\fBauto_reset\fR. This will force the next \fBauto_load\fR command to +reload the index database from disk. .TP \fBauto_mkindex \fIdir pattern pattern ...\fR -Generates an index suitable for use by \fBauto_load\fR. -The command searches \fIdir\fR for all files whose names match -any of the \fIpattern\fR arguments -(matching is done with the \fBglob\fR command), -generates an index of all the Tcl command -procedures defined in all the matching files, and stores the -index information in a file named \fBtclIndex\fR in \fIdir\fR. -If no pattern is given a pattern of \fB*.tcl\fR will be assumed. -For example, the command +Generates an index suitable for use by \fBauto_load\fR. The command +searches \fIdir\fR for all files whose names match any of the +\fIpattern\fR arguments (matching is done with the \fBglob\fR +command), generates an index of all the Tcl command procedures defined +in all the matching files, and stores the index information in a file +named \fBtclIndex\fR in \fIdir\fR. If no pattern is given a pattern of +\fB*.tcl\fR will be assumed. For example, the command .RS .CS \fBauto_mkindex foo *.tcl\fR .CE .LP -will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR -and generate a new index file \fBfoo/tclIndex\fR. +will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and +generate a new index file \fBfoo/tclIndex\fR. .PP -\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them -into a slave interpreter and monitoring the proc and -namespace commands that are executed. -Extensions can use the (undocumented) -auto_mkindex_parser package to register other commands that -can contribute to the auto_load index. -You will have to read through auto.tcl to see how this works. +\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a +slave interpreter and monitoring the proc and namespace commands that +are executed. Extensions can use the (undocumented) +auto_mkindex_parser package to register other commands that can +contribute to the auto_load index. You will have to read through +auto.tcl to see how this works. .PP \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively unsophisticated way: if any line contains the word \fBproc\fR @@ -147,12 +145,29 @@ code or procedure names with special characters like \fB$\fR, .TP \fBauto_reset\fR Destroys all the information cached by \fBauto_execok\fR and -\fBauto_load\fR. -This information will be re-read from disk the next time it is -needed. -\fBAuto_reset\fR also deletes any procedures listed in the auto-load -index, so that fresh copies of them will be loaded the next time -that they're used. +\fBauto_load\fR. This information will be re-read from disk the next +time it is needed. \fBAuto_reset\fR also deletes any procedures +listed in the auto-load index, so that fresh copies of them will be +loaded the next time that they're used. +.TP +\fBauto_qualify \fIcommand namespace\fR +Computes a list of fully qualified names for \fIcommand\fR. This list +mirrors the path a standard Tcl interpreter follows for command +lookups: first it looks for the command in the current namespace, and +then in the global namespace. Accordingly, if \fIcommand\fR is +relative and \fInamespace\fR is not \fB::\fR, the list returned has +two elements: \fIcommand\fR scoped by \fInamespace\fR, as if it were +a command in the \fInamespace\fR namespace; and \fIcommand\fR as if it +were a command in the global namespace. Otherwise, if either +\fIcommand\fR is absolute (it begins with \fB::\fR), or +\fInamespace\fR is \fB::\fR, the list contains only \fIcommand\fR as +if it were a command in the global namespace. +.RS +.PP +\fBAuto_qualify\fR is used by the auto-loading facilities in Tcl, both +for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for +performing the actual auto-loading of functions at runtime. +.RE .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR This is a standard search procedure for use by extensions during diff --git a/doc/memory.n b/doc/memory.n index 4815ec4..3f7ca66 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: memory.n,v 1.1 2000/04/27 01:47:00 ericm Exp $ +'\" RCS: @(#) $Id: memory.n,v 1.2 2000/04/28 00:47:49 ericm Exp $ '\" .so man.macros .TH memory n 8.1 Tcl "Tcl Built-In Commands" @@ -73,7 +73,7 @@ command mode. \fB memory display\fR \fIfile\fR Write a list of all currently allocated memory to the specified file. -.SH SEE ALSO +.SH "SEE ALSO" ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG .SH KEYWORDS diff --git a/unix/mkLinks b/unix/mkLinks index 86e9609..e7c34fd 100644 --- a/unix/mkLinks +++ b/unix/mkLinks @@ -446,6 +446,10 @@ if test -r Hash.3; then ln Hash.3 Tcl_NextHashEntry.3 ln Hash.3 Tcl_HashStats.3 fi +if test -r Init.3; then + rm -f Tcl_Init.3 + ln Init.3 Tcl_Init.3 +fi if test -r InitStubs.3; then rm -f Tcl_InitStubs.3 ln InitStubs.3 Tcl_InitStubs.3 @@ -912,9 +916,11 @@ if test -r http.n; then fi if test -r library.n; then rm -f auto_execok.n + rm -f auto_import.n rm -f auto_load.n rm -f auto_mkindex.n rm -f auto_mkindex_old.n + rm -f auto_qualify.n rm -f auto_reset.n rm -f tcl_findLibrary.n rm -f parray.n @@ -924,9 +930,11 @@ if test -r library.n; then rm -f tcl_wordBreakAfter.n rm -f tcl_wordBreakBefore.n ln library.n auto_execok.n + ln library.n auto_import.n ln library.n auto_load.n ln library.n auto_mkindex.n ln library.n auto_mkindex_old.n + ln library.n auto_qualify.n ln library.n auto_reset.n ln library.n tcl_findLibrary.n ln library.n parray.n -- cgit v0.12