Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | merge novem |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | novem-purge-literals |
| Files: | files | file ages | folders |
| SHA3-256: |
a72a317ba0c2cc89e32117dda75541fc |
| User & Date: | dgp 2019-06-12 19:34:43 |
Context
|
2019-06-17
| ||
| 18:38 | merge novem Leaf check-in: 5f6508a146 user: dgp tags: novem-purge-literals | |
|
2019-06-12
| ||
| 19:34 | merge novem check-in: a72a317ba0 user: dgp tags: novem-purge-literals | |
| 18:41 | merge trunk check-in: 9b0d0c83a1 user: dgp tags: novem | |
|
2018-03-15
| ||
| 15:43 | merge novem check-in: 700b9a198f user: dgp tags: novem-purge-literals | |
Changes
Deleted .fossil-settings/crnl-glob.
1 -compat/zlib/contrib/dotzlib/DotZLib/UnitTests.cs 2 -compat/zlib/contrib/vstudio/readme.txt 3 -compat/zlib/contrib/vstudio/*/zlib.rc 4 -compat/zlib/win32/*.txt 5 -compat/zlib/win64/*.txt 6 -libtommath/*.dsp 7 -libtommath/*.sln 8 -libtommath/*.vcproj 9 -tools/tcl.hpj.in 10 -tools/tcl.wse.in 11 -win/buildall.vc.bat 12 -win/coffbase.txt 13 -win/makefile.vc 14 -win/rules.vc 15 -win/rules-ext.vc 16 -win/targets.vc 17 -win/tcl.dsp 18 -win/tcl.dsw 19 -win/tcl.hpj.in
Changes to .fossil-settings/ignore-glob.
15 15 */config.log 16 16 */config.status 17 17 */tclConfig.sh 18 18 */tclsh* 19 19 */tcltest* 20 20 */versions.vc 21 21 */version.vc 22 +*/libtcl.vfs 23 +*/libtcl_*.zip 22 24 html 23 25 libtommath/bn.ilg 24 26 libtommath/bn.ind 25 27 libtommath/pretty.build 26 28 libtommath/tommath.src 29 +libtommath/*.log 27 30 libtommath/*.pdf 28 31 libtommath/*.pl 29 32 libtommath/*.sh 33 +libtommath/doc/* 30 34 libtommath/tombc/* 31 35 libtommath/pre_gen/* 32 36 libtommath/pics/* 33 37 libtommath/mtest/* 34 38 libtommath/logs/* 35 39 libtommath/etc/* 36 40 libtommath/demo/*
Added .github/ISSUE_TEMPLATE.md.
1 +Important Note 2 +========== 3 +Please do not file issues with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.
Added .github/PULL_REQUEST_TEMPLATE.md.
1 +Important Note 2 +========== 3 +Please do not file pull requests with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues (including patches) are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.
Added .travis.yml.
1 +sudo: false 2 +language: c 3 + 4 +matrix: 5 + include: 6 + - os: linux 7 + dist: xenial 8 + compiler: clang 9 + env: 10 + - BUILD_DIR=unix 11 + - os: linux 12 + dist: xenial 13 + compiler: clang 14 + env: 15 + - CFGOPT=--disable-shared 16 + - BUILD_DIR=unix 17 + - os: linux 18 + dist: xenial 19 + compiler: gcc 20 + env: 21 + - BUILD_DIR=unix 22 + - os: linux 23 + dist: xenial 24 + compiler: gcc 25 + env: 26 + - CFGOPT=--disable-shared 27 + - BUILD_DIR=unix 28 + - os: linux 29 + dist: xenial 30 + compiler: gcc-4.9 31 + addons: 32 + apt: 33 + sources: 34 + - ubuntu-toolchain-r-test 35 + packages: 36 + - g++-4.9 37 + env: 38 + - BUILD_DIR=unix 39 + - os: linux 40 + dist: xenial 41 + compiler: gcc-5 42 + addons: 43 + apt: 44 + sources: 45 + - ubuntu-toolchain-r-test 46 + packages: 47 + - g++-5 48 + env: 49 + - BUILD_DIR=unix 50 + - os: linux 51 + dist: xenial 52 + compiler: gcc-6 53 + addons: 54 + apt: 55 + sources: 56 + - ubuntu-toolchain-r-test 57 + packages: 58 + - g++-6 59 + env: 60 + - BUILD_DIR=unix 61 + - os: linux 62 + dist: xenial 63 + compiler: gcc-7 64 + addons: 65 + apt: 66 + sources: 67 + - ubuntu-toolchain-r-test 68 + packages: 69 + - g++-7 70 + env: 71 + - BUILD_DIR=unix 72 + - os: linux 73 + dist: xenial 74 + compiler: gcc-7 75 + addons: 76 + apt: 77 + sources: 78 + - ubuntu-toolchain-r-test 79 + packages: 80 + - g++-7 81 + env: 82 + - BUILD_DIR=unix 83 + - CFGOPT=CFLAGS=-DTCL_UTF_MAX=6 84 + - os: linux 85 + dist: xenial 86 + compiler: gcc-7 87 + addons: 88 + apt: 89 + sources: 90 + - ubuntu-toolchain-r-test 91 + packages: 92 + - g++-7 93 + env: 94 + - BUILD_DIR=unix 95 + - CFGOPT=CFLAGS=-DTCL_UTF_MAX=3 96 + - os: linux 97 + dist: xenial 98 + compiler: gcc-7 99 + addons: 100 + apt: 101 + sources: 102 + - ubuntu-toolchain-r-test 103 + packages: 104 + - g++-7 105 + env: 106 + - BUILD_DIR=unix 107 + - CFGOPT=CFLAGS=-DTCL_NO_DEPRECATED=1 108 + - os: osx 109 + osx_image: xcode8 110 + env: 111 + - BUILD_DIR=unix 112 + - os: osx 113 + osx_image: xcode8 114 + env: 115 + - BUILD_DIR=macosx 116 + - NO_DIRECT_CONFIGURE=1 117 + - os: osx 118 + osx_image: xcode9 119 + env: 120 + - BUILD_DIR=macosx 121 + - NO_DIRECT_CONFIGURE=1 122 + - os: osx 123 + osx_image: xcode10.2 124 + env: 125 + - BUILD_DIR=macosx 126 + - NO_DIRECT_CONFIGURE=1 127 +### C builds not currently supported on Windows instances 128 +# - os: windows 129 +# env: 130 +# - BUILD_DIR=win 131 +### ... so proxy with a Mingw cross-compile 132 +# Test with mingw-w64 (32 bit) 133 + - os: linux 134 + dist: xenial 135 + compiler: i686-w64-mingw32-gcc 136 + addons: 137 + apt: 138 + packages: 139 + - gcc-mingw-w64-base 140 + - binutils-mingw-w64-i686 141 + - gcc-mingw-w64-i686 142 + - gcc-mingw-w64 143 + - gcc-multilib 144 + - wine 145 + env: 146 + - BUILD_DIR=win 147 + - CFGOPT=--host=i686-w64-mingw32 148 + - NO_DIRECT_TEST=1 149 + - os: linux 150 + dist: xenial 151 + compiler: i686-w64-mingw32-gcc 152 + addons: 153 + apt: 154 + packages: 155 + - gcc-mingw-w64-base 156 + - binutils-mingw-w64-i686 157 + - gcc-mingw-w64-i686 158 + - gcc-mingw-w64 159 + - gcc-multilib 160 + - wine 161 + env: 162 + - BUILD_DIR=win 163 + - CFGOPT="--host=i686-w64-mingw32 --disable-shared" 164 + - NO_DIRECT_TEST=1 165 + - os: linux 166 + dist: xenial 167 + compiler: i686-w64-mingw32-gcc 168 + addons: 169 + apt: 170 + packages: 171 + - gcc-mingw-w64-base 172 + - binutils-mingw-w64-i686 173 + - gcc-mingw-w64-i686 174 + - gcc-mingw-w64 175 + - gcc-multilib 176 + - wine 177 + env: 178 + - BUILD_DIR=win 179 + - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_UTF_MAX=6" 180 + - NO_DIRECT_TEST=1 181 + - os: linux 182 + dist: xenial 183 + compiler: i686-w64-mingw32-gcc 184 + addons: 185 + apt: 186 + packages: 187 + - gcc-mingw-w64-base 188 + - binutils-mingw-w64-i686 189 + - gcc-mingw-w64-i686 190 + - gcc-mingw-w64 191 + - gcc-multilib 192 + - wine 193 + env: 194 + - BUILD_DIR=win 195 + - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_UTF_MAX=3" 196 + - NO_DIRECT_TEST=1 197 + - os: linux 198 + dist: xenial 199 + compiler: i686-w64-mingw32-gcc 200 + addons: 201 + apt: 202 + packages: 203 + - gcc-mingw-w64-base 204 + - binutils-mingw-w64-i686 205 + - gcc-mingw-w64-i686 206 + - gcc-mingw-w64 207 + - gcc-multilib 208 + - wine 209 + env: 210 + - BUILD_DIR=win 211 + - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_NO_DEPRECATED=1" 212 + - NO_DIRECT_TEST=1 213 +# Test with mingw-w64 (64 bit) 214 + - os: linux 215 + dist: xenial 216 + compiler: x86_64-w64-mingw32-gcc 217 + addons: 218 + apt: 219 + packages: 220 + - gcc-mingw-w64-base 221 + - binutils-mingw-w64-x86-64 222 + - gcc-mingw-w64-x86-64 223 + - gcc-mingw-w64 224 + - wine 225 + env: 226 + - BUILD_DIR=win 227 + - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit" 228 + - NO_DIRECT_TEST=1 229 + - os: linux 230 + dist: xenial 231 + compiler: x86_64-w64-mingw32-gcc 232 + addons: 233 + apt: 234 + packages: 235 + - gcc-mingw-w64-base 236 + - binutils-mingw-w64-x86-64 237 + - gcc-mingw-w64-x86-64 238 + - gcc-mingw-w64 239 + - wine 240 + env: 241 + - BUILD_DIR=win 242 + - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit --disable-shared" 243 + - NO_DIRECT_TEST=1 244 + - os: linux 245 + dist: xenial 246 + compiler: x86_64-w64-mingw32-gcc 247 + addons: 248 + apt: 249 + packages: 250 + - gcc-mingw-w64-base 251 + - binutils-mingw-w64-x86-64 252 + - gcc-mingw-w64-x86-64 253 + - gcc-mingw-w64 254 + - wine 255 + env: 256 + - BUILD_DIR=win 257 + - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_UTF_MAX=6" 258 + - NO_DIRECT_TEST=1 259 + - os: linux 260 + dist: xenial 261 + compiler: x86_64-w64-mingw32-gcc 262 + addons: 263 + apt: 264 + packages: 265 + - gcc-mingw-w64-base 266 + - binutils-mingw-w64-x86-64 267 + - gcc-mingw-w64-x86-64 268 + - gcc-mingw-w64 269 + - wine 270 + env: 271 + - BUILD_DIR=win 272 + - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_UTF_MAX=3" 273 + - NO_DIRECT_TEST=1 274 + - os: linux 275 + dist: xenial 276 + compiler: x86_64-w64-mingw32-gcc 277 + addons: 278 + apt: 279 + packages: 280 + - gcc-mingw-w64-base 281 + - binutils-mingw-w64-x86-64 282 + - gcc-mingw-w64-x86-64 283 + - gcc-mingw-w64 284 + - wine 285 + env: 286 + - BUILD_DIR=win 287 + - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_NO_DEPRECATED=1" 288 + - NO_DIRECT_TEST=1 289 +before_install: 290 + - export ERROR_ON_FAILURES=1 291 + - cd ${BUILD_DIR} 292 +install: 293 + - test -n "$NO_DIRECT_CONFIGURE" || ./configure ${CFGOPT} 294 +script: 295 + - make 296 + # The styles=develop avoids some weird problems on OSX 297 + - test -n "$NO_DIRECT_TEST" || make test styles=develop
Changes to ChangeLog.
1 1 A NOTE ON THE CHANGELOG: 2 2 Starting in early 2011, Tcl source code has been under the management of 3 -fossil, hosted at http://core.tcl.tk/tcl/ . Fossil presents a "Timeline" 3 +fossil, hosted at https://core.tcl-lang.org/tcl/ . Fossil presents a "Timeline" 4 4 view of changes made that is superior in every way to a hand edited log file. 5 5 Because of this, many Tcl developers are now out of the habit of maintaining 6 6 this log file. You may still find useful things in it, but the Timeline is 7 7 a better first place to look now. 8 8 ============================================================================ 9 9 10 10 2013-09-19 Don Porter <[email protected]>
Changes to ChangeLog.2007.
1422 1422 an expr syntax error (masked by a [catch]). 1423 1423 1424 1424 * generic/tclCompCmds.c (TclCompileReturnCmd): Added crash protection 1425 1425 to handle callers other than TclCompileScript() failing to meet the 1426 1426 initialization assumptions of the TIP 280 code in CompileWord(). 1427 1427 1428 1428 * generic/tclCompExpr.c: Suppress the attempt to convert to 1429 - numeric when pre-compiling a constant expresion indicates an error. 1429 + numeric when pre-compiling a constant expression indicates an error. 1430 1430 1431 1431 2007-08-22 Miguel Sofer <[email protected]> 1432 1432 1433 1433 * generic/tclExecute.c (TEBC): disable the new shortcut to frequent 1434 1434 INSTs for debug builds. REVERTED (collision with alternative fix) 1435 1435 1436 1436 2007-08-21 Don Porter <[email protected]>
Name change from README to README.md.
1 -README: Tcl 2 - This is the Tcl 9.0a0 source distribution. 3 - http://sourceforge.net/projects/tcl/files/Tcl/ 4 - You can get any source release of Tcl from the URL above. 5 - 6 -Contents 7 --------- 8 - 1. Introduction 9 - 2. Documentation 10 - 3. Compiling and installing Tcl 11 - 4. Development tools 12 - 5. Tcl newsgroup 13 - 6. The Tcler's Wiki 14 - 7. Mailing lists 15 - 8. Support and Training 16 - 9. Tracking Development 17 - 10. Thank You 18 - 19 -1. Introduction 20 ---------------- 1 +# README: Tcl 2 + 3 +This is the **Tcl 9.0a0** source distribution. 4 + 5 +You can get any source release of Tcl from [our distribution 6 +site](https://sourceforge.net/projects/tcl/files/Tcl/). 7 + 8 +[](https://travis-ci.org/tcltk/tcl) 9 + 10 +## Contents 11 + 1. [Introduction](#intro) 12 + 2. [Documentation](#doc) 13 + 3. [Compiling and installing Tcl](#build) 14 + 4. [Development tools](#devtools) 15 + 5. [Tcl newsgroup](#complangtcl) 16 + 6. [The Tcler's Wiki](#wiki) 17 + 7. [Mailing lists](#email) 18 + 8. [Support and Training](#support) 19 + 9. [Tracking Development](#watch) 20 + 10. [Thank You](#thanks) 21 + 22 +## <a id="intro">1.</a> Introduction 21 23 Tcl provides a powerful platform for creating integration applications that 22 24 tie together diverse applications, protocols, devices, and frameworks. 23 25 When paired with the Tk toolkit, Tcl provides the fastest and most powerful 24 26 way to create GUI applications that run on PCs, Unix, and Mac OS X. 25 27 Tcl can also be used for a variety of web-related tasks and for creating 26 28 powerful command languages for applications. 27 29 28 30 Tcl is maintained, enhanced, and distributed freely by the Tcl community. 29 31 Source code development and tracking of bug reports and feature requests 30 -takes place at: 31 - 32 - http://core.tcl.tk/ 33 - 34 -Tcl/Tk release and mailing list services are hosted by SourceForge: 35 - 36 - http://sourceforge.net/projects/tcl/ 37 - 38 -with the Tcl Developer Xchange hosted at: 39 - 40 - http://www.tcl.tk/ 32 +takes place at [core.tcl-lang.org](https://core.tcl-lang.org/). 33 +Tcl/Tk release and mailing list services are [hosted by 34 +SourceForge](https://sourceforge.net/projects/tcl/) 35 +with the Tcl Developer Xchange hosted at 36 +[www.tcl-lang.org](https://www.tcl-lang.org). 41 37 42 38 Tcl is a freely available open source package. You can do virtually 43 39 anything you like with it, such as modifying it, redistributing it, 44 40 and selling it either in whole or in part. See the file 45 -"license.terms" for complete information. 41 +`license.terms` for complete information. 46 42 47 -2. Documentation 48 ----------------- 49 - 43 +## <a id="doc">2.</a> Documentation 50 44 Extensive documentation is available at our website. 51 45 The home page for this release, including new features, is 52 - http://www.tcl.tk/software/tcltk/9.0.html 53 - 54 -Detailed release notes can be found at the file distributions page 46 +[here](https://www.tcl.tk/software/tcltk/9.0.html). 47 +Detailed release notes can be found at the 48 +[file distributions page](https://sourceforge.net/projects/tcl/files/Tcl/) 55 49 by clicking on the relevant version. 56 - http://sourceforge.net/projects/tcl/files/Tcl/ 57 50 58 -Information about Tcl itself can be found at 59 - http://www.tcl.tk/about/ 51 +Information about Tcl itself can be found at the [Developer 52 +Xchange](https://www.tcl-lang.org/about/). 53 +There have been many Tcl books on the market. Many are mentioned in 54 +[the Wiki](https://wiki.tcl-lang.org/_/ref?N=25206). 60 55 61 -There have been many Tcl books on the market. Many are mentioned in the Wiki: 62 - http://wiki.tcl.tk/_/ref?N=25206 56 +The complete set of reference manual entries for Tcl 9.0 is [online, 57 +here](https://www.tcl-lang.org/man/tcl9.0/). 63 58 64 -To view the complete set of reference manual entries for Tcl 9.0 online, 65 -visit the URL: 66 - http://www.tcl.tk/man/tcl9.0/ 67 - 68 -2a. Unix Documentation 69 ----------------------- 70 - 71 -The "doc" subdirectory in this release contains a complete set of 72 -reference manual entries for Tcl. Files with extension ".1" are for 73 -programs (for example, tclsh.1); files with extension ".3" are for C 74 -library procedures; and files with extension ".n" describe Tcl 75 -commands. The file "doc/Tcl.n" gives a quick summary of the Tcl 59 +### <a id="doc.unix">2a.</a> Unix Documentation 60 +The `doc` subdirectory in this release contains a complete set of 61 +reference manual entries for Tcl. Files with extension "`.1`" are for 62 +programs (for example, `tclsh.1`); files with extension "`.3`" are for C 63 +library procedures; and files with extension "`.n`" describe Tcl 64 +commands. The file "`doc/Tcl.n`" gives a quick summary of the Tcl 76 65 language syntax. To print any of the man pages on Unix, cd to the 77 66 "doc" directory and invoke your favorite variant of troff using the 78 67 normal -man macros, for example 79 68 80 - ditroff -man Tcl.n 69 + groff -man -Tpdf Tcl.n >output.pdf 81 70 82 -to print Tcl.n. If Tcl has been installed correctly and your "man" program 71 +to print Tcl.n to PDF. If Tcl has been installed correctly and your "man" program 83 72 supports it, you should be able to access the Tcl manual entries using the 84 73 normal "man" mechanisms, such as 85 74 86 75 man Tcl 87 76 88 -2b. Windows Documentation 89 -------------------------- 90 - 77 +### <a id="doc.win">2b.</a> Windows Documentation 91 78 The "doc" subdirectory in this release contains a complete set of Windows 92 79 help files for Tcl. Once you install this Tcl release, a shortcut to the 93 80 Windows help Tcl documentation will appear in the "Start" menu: 94 81 95 - Start | Programs | Tcl | Tcl Help 82 + Start | Programs | Tcl | Tcl Help 96 83 97 -3. Compiling and installing Tcl 98 -------------------------------- 99 - 100 -There are brief notes in the unix/README, win/README, and macosx/README about 101 -compiling on these different platforms. There is additional information 102 -about building Tcl from sources at 84 +## <a id="build">3.</a> Compiling and installing Tcl 85 +There are brief notes in the `unix/README`, `win/README`, and `macosx/README` 86 +about compiling on these different platforms. There is additional information 87 +about building Tcl from sources 88 +[online](https://www.tcl-lang.org/doc/howto/compile.html). 103 89 104 - http://www.tcl.tk/doc/howto/compile.html 105 - 106 -4. Development tools 107 ---------------------------- 108 - 90 +## <a id="devtools">4.</a> Development tools 109 91 ActiveState produces a high quality set of commercial quality development 110 92 tools that is available to accelerate your Tcl application development. 111 93 Tcl Dev Kit builds on the earlier TclPro toolset and provides a debugger, 112 94 static code checker, single-file wrapping utility, bytecode compiler and 113 95 more. More information can be found at 114 96 115 97 http://www.ActiveState.com/Tcl 116 98 117 -5. Tcl newsgroup 118 ----------------- 119 - 120 -There is a USENET news group, "comp.lang.tcl", intended for the exchange of 99 +## <a id="complangtcl">5.</a> Tcl newsgroup 100 +There is a USENET news group, "`comp.lang.tcl`", intended for the exchange of 121 101 information about Tcl, Tk, and related applications. The newsgroup is a 122 102 great place to ask general information questions. For bug reports, please 123 103 see the "Support and bug fixes" section below. 124 104 125 -6. Tcl'ers Wiki 126 ---------------- 127 - 128 -A Wiki-based open community site covering all aspects of Tcl/Tk is at: 129 - 130 - http://wiki.tcl.tk/ 105 +## <a id="wiki">6.</a> Tcl'ers Wiki 106 +There is a [wiki-based open community site](https://wiki.tcl-lang.org/) 107 +covering all aspects of Tcl/Tk. 131 108 132 109 It is dedicated to the Tcl programming language and its extensions. A 133 110 wealth of useful information can be found there. It contains code 134 111 snippets, references to papers, books, and FAQs, as well as pointers to 135 112 development tools, extensions, and applications. You can also recommend 136 113 additional URLs by editing the wiki yourself. 137 114 138 -7. Mailing lists 139 ----------------- 140 - 141 -Several mailing lists are hosted at SourceForge to discuss development or 142 -use issues (like Macintosh and Windows topics). For more information and 143 -to subscribe, visit: 115 +## <a id="email">7.</a> Mailing lists 116 +Several mailing lists are hosted at SourceForge to discuss development or use 117 +issues (like Macintosh and Windows topics). For more information and to 118 +subscribe, visit [here](https://sourceforge.net/projects/tcl/) and go to the 119 +Mailing Lists page. 144 120 145 - http://sourceforge.net/projects/tcl/ 146 - 147 -and go to the Mailing Lists page. 148 - 149 -8. Support and Training 150 ------------------------- 151 - 152 -We are very interested in receiving bug reports, patches, and suggestions 153 -for improvements. We prefer that you send this information to us as 154 -tickets entered into our tracker at: 155 - 156 - http://core.tcl.tk/tcl/reportlist 121 +## <a id="support">8.</a> Support and Training 122 +We are very interested in receiving bug reports, patches, and suggestions for 123 +improvements. We prefer that you send this information to us as tickets 124 +entered into [our issue tracker](https://core.tcl-lang.org/tcl/reportlist). 157 125 158 126 We will log and follow-up on each bug, although we cannot promise a 159 127 specific turn-around time. Enhancements may take longer and may not happen 160 128 at all unless there is widespread support for them (we're trying to 161 129 slow the rate at which Tcl/Tk turns into a kitchen sink). It's very 162 130 difficult to make incompatible changes to Tcl/Tk at this point, due to 163 131 the size of the installed base. 164 132 165 -The Tcl community is too large for us to provide much individual support 166 -for users. If you need help we suggest that you post questions to 167 -comp.lang.tcl. We read the newsgroup and will attempt to answer esoteric 168 -questions for which no one else is likely to know the answer. In addition, 169 -see the following Web site for links to other organizations that offer 170 -Tcl/Tk training: 133 +The Tcl community is too large for us to provide much individual support for 134 +users. If you need help we suggest that you post questions to `comp.lang.tcl` 135 +or ask a question on [Stack 136 +Overflow](https://stackoverflow.com/questions/tagged/tcl). We read the 137 +newsgroup and will attempt to answer esoteric questions for which no one else 138 +is likely to know the answer. In addition, see the wiki for [links to other 139 +organizations](https://wiki.tcl-lang.org/training) that offer Tcl/Tk training. 171 140 172 - http://wiki.tcl.tk/training 173 - 174 -9. Tracking Development 175 ------------------------ 141 +## <a id="watch">9.</a> Tracking Development 142 +Tcl is developed in public. You can keep an eye on how Tcl is changing at 143 +[core.tcl-lang.org](https://core.tcl-lang.org/). 176 144 177 -Tcl is developed in public. To keep an eye on how Tcl is changing, see 178 - http://core.tcl.tk/ 179 - 180 -10. Thank You 181 -------------- 182 - 145 +## <a id="thanks">10.</a> Thank You 183 146 We'd like to express our thanks to the Tcl community for all the 184 147 helpful suggestions, bug reports, and patches we have received. 185 148 Tcl/Tk has improved vastly and will continue to do so with your help.
Changes to changes.
8827 8827 8828 8828 2017-12-08 (new)[TIP 477] nmake build system reform (nadkarni) 8829 8829 8830 8830 2017-12-19 (bug)[586e71] EvalObjv exception handling at level #0 (sebres,porter) 8831 8831 8832 8832 --- Released 8.6.8, December 22, 2017 --- http://core.tcl.tk/tcl/ for details 8833 8833 8834 +2018-02-11 (enhance) stop blocking conversion of object to/from class (coulter) 8835 + 8836 +2018-02-12 (enhance) NR-enable [package require] (coulter) 8837 + 8838 +2018-02-14 (bug)[9fd5c6] crash in object deletion, test oo-11.5 (coulter) 8839 + 8840 +2018-02-14 (bug)[3c32a3] crash deleting object with class mixed in (coulter) 8841 + 8842 +2018-02-15 (platform) stop using -lieee, removed from glibc-2.27 (porter) 8843 +***POTENTIAL INCOMPATIBILITY for math programs that embed Tcl*** 8844 + 8845 +2018-02-23 (bug)[8e6a9a] bad binary [string match], test string-11.55 (porter) 8846 + 8847 +2018-03-05 (bug)[1873ea] repair multi-thread std channel init (sebres) 8848 + 8849 +2018-03-09 (bug)[db36fa] broken bytecode for index values (porter) 8850 + 8851 +2018-03-13 (bug) broken compiled [string replace], test string-14.19 (porter) 8852 + 8853 +2018-03-14 (bug) [string trim*] engine crashed on invalid UTF (sebres) 8854 + 8855 +2018-04-17 (bug) missing trace in compiled [array set], test var-20.11 (porter) 8856 + 8857 +2018-04-22 (bug)[46a241] crash in unset array with search, var-13.[23] (goth) 8858 + 8859 +2018-04-30 (bug)[27b682] race made [file delete] raise "no such file" (sebres) 8860 + 8861 +2018-06-04 (bug)[925643] 32/64 cleanup of filesystem DIR operations (sebres) 8862 + 8863 +2018-06-18 (bug) leaks in TclSetEnv and env cache (coulter) 8864 + 8865 +2018-06-24 (bug)[3592747] [yieldto] dying namespace, tailcall-14.1 (coulter) 8866 + 8867 +2018-07-09 (bug)[270f78] race in [file mkdir] (sebres) 8868 + 8869 +2018-07-12 (bug)[3f7af0] [file delete] raised "permission denied" (sebres) 8870 + 8871 +2018-07-26 (bug)[d051b7] overflow crash in [format] (sebres) 8872 + 8873 +2018-08-29 revised quoting of [exec] args in generated command line (sebres) 8874 +***POTENTIAL INCOMPATIBILITY*** 8875 + 8876 +2018-09-20 HTTP Keep-Alive with pipelined requests (nash) 8877 +=> http 2.9.0 8878 + 8879 +2018-09-27 (new)[TIP 505] [lreplace] accepts all out of range indices (porter) 8880 + 8881 +2018-10-04 (bug) Prevent crash from NULL keyName (nijtmans) 8882 +=> registry 1.3.3 8883 + 8884 +2018-10-26 (enhance) advance dde version (nijtmans) 8885 +=> dde 1.4.1 8886 + 8887 +2018-10-27 tzdata updated to Olson's tzdata2018g (jima) 8888 + 8889 +2018-10-29 Update tcltest package for Travis support (fellows) 8890 +=> tcltest 2.5.0 8891 + 8892 +2018-11-09 (bug)[35a8f1] overlong string length of some lists (owens) 8893 + 8894 +2018-11-16 (bug)[00d04c] Repair [binary encode base64] (sebres) 8895 + 8896 +- Released 8.6.9, November 16, 2018 - details at http://core.tcl-lang.org/tcl/ - 8897 + 8834 8898 Changes to 8.7a1 include all changes to the 8.6 line through 8.6.7, 8835 8899 plus the following, which focuses on the high-level feature changes 8836 8900 in this changeset (new minor version) rather than bug fixes: 8837 8901 8838 8902 2016-03-17 (bug)[0b8c38] socket accept callbacks always in global ns (porter) 8839 8903 *** POTENTIAL INCOMPATIBILITY *** 8840 8904 ................................................................................ 8845 8909 2016-07-19 (bug)[0363f0] Partial array search ID reform (porter) 8846 8910 8847 8911 2016-07-19 (feature removed) Tcl_ObjType "array search" unregistered (porter) 8848 8912 *** POTENTIAL INCOMPATIBILITY for Tcl_GetObjType("array search") *** 8849 8913 8850 8914 2016-10-04 Server socket on port 0 chooses port supporting IPv4 * IPv6 (max) 8851 8915 8852 -2016-11-25 [array named -regexp] supports backrefs (goth) 8916 +2016-11-25 [array names -regexp] supports backrefs (goth) 8853 8917 8854 8918 2017-01-04 (TIP 456) New routine Tcl_OpenTcpServerEx() (limeboy) 8855 8919 8856 8920 2017-01-04 (TIP 459) New subcommand [package files] (nijtmans) 8857 8921 8858 8922 2017-01-16 threaded allocator initialization repair (vasiljevic,nijtmans) 8859 8923 ................................................................................ 8880 8944 8881 8945 --- Released 8.7a1, September 8, 2017 --- http://core.tcl.tk/tcl/ for details 8882 8946 8883 8947 2018-03-12 (TIP 490) add oo support for msgcat => msgcat 1.7.0 (oehlmann) 8884 8948 8885 8949 2018-03-12 (TIP 499) custom locale preference list (oehlmann) 8886 8950 => msgcat 1.7.0 8951 + 8952 +- Released 8.7a3, Nov 30, 2018 --- http://core.tcl-lang.org/tcl/ for details -
Deleted compat/fixstrtod.c.
1 -/* 2 - * fixstrtod.c -- 3 - * 4 - * Source code for the "fixstrtod" procedure. This procedure is 5 - * used in place of strtod under Solaris 2.4, in order to fix 6 - * a bug where the "end" pointer gets set incorrectly. 7 - * 8 - * Copyright (c) 1995 Sun Microsystems, Inc. 9 - * 10 - * See the file "license.terms" for information on usage and redistribution 11 - * of this file, and for a DISCLAIMER OF ALL WARRANTIES. 12 - */ 13 - 14 -#include <stdio.h> 15 - 16 -#undef strtod 17 - 18 -/* 19 - * Declare strtod explicitly rather than including stdlib.h, since in 20 - * somes systems (e.g. SunOS 4.1.4) stdlib.h doesn't declare strtod. 21 - */ 22 - 23 -extern double strtod(char *, char **); 24 - 25 -double 26 -fixstrtod( 27 - char *string, 28 - char **endPtr) 29 -{ 30 - double d; 31 - d = strtod(string, endPtr); 32 - if ((endPtr != NULL) && (*endPtr != string) && ((*endPtr)[-1] == 0)) { 33 - *endPtr -= 1; 34 - } 35 - return d; 36 -}
Changes to compat/opendir.c.
24 24 register int fd; 25 25 char *myname; 26 26 27 27 myname = ((*name == '\0') ? "." : name); 28 28 if ((fd = open(myname, 0, 0)) == -1) { 29 29 return NULL; 30 30 } 31 - dirp = (DIR *) ckalloc(sizeof(DIR)); 31 + dirp = (DIR *) Tcl_Alloc(sizeof(DIR)); 32 32 if (dirp == NULL) { 33 33 /* unreachable? */ 34 34 close(fd); 35 35 return NULL; 36 36 } 37 37 dirp->dd_fd = fd; 38 38 dirp->dd_loc = 0; ................................................................................ 102 102 void 103 103 closedir( 104 104 register DIR *dirp) 105 105 { 106 106 close(dirp->dd_fd); 107 107 dirp->dd_fd = -1; 108 108 dirp->dd_loc = 0; 109 - ckfree(dirp); 109 + Tcl_Free(dirp); 110 110 }
Changes to compat/stdlib.h.
25 25 extern void exit(int status); 26 26 extern int free(char *blockPtr); 27 27 extern char * getenv(const char *name); 28 28 extern char * malloc(unsigned int numBytes); 29 29 extern void qsort(void *base, int n, int size, int (*compar)( 30 30 const void *element1, const void *element2)); 31 31 extern char * realloc(char *ptr, unsigned int numBytes); 32 -extern double strtod(const char *string, char **endPtr); 33 32 extern long strtol(const char *string, char **endPtr, int base); 34 33 extern unsigned long strtoul(const char *string, char **endPtr, int base); 35 34 36 35 #endif /* _STDLIB */
Deleted compat/strtod.c.
1 -/* 2 - * strtod.c -- 3 - * 4 - * Source code for the "strtod" library procedure. 5 - * 6 - * Copyright (c) 1988-1993 The Regents of the University of California. 7 - * Copyright (c) 1994 Sun Microsystems, Inc. 8 - * 9 - * See the file "license.terms" for information on usage and redistribution 10 - * of this file, and for a DISCLAIMER OF ALL WARRANTIES. 11 - */ 12 - 13 -#include "tclInt.h" 14 - 15 -#ifndef TRUE 16 -#define TRUE 1 17 -#define FALSE 0 18 -#endif 19 -#ifndef NULL 20 -#define NULL 0 21 -#endif 22 - 23 -static const int maxExponent = 511; /* Largest possible base 10 exponent. Any 24 - * exponent larger than this will already 25 - * produce underflow or overflow, so there's 26 - * no need to worry about additional digits. 27 - */ 28 -static const double powersOf10[] = { /* Table giving binary powers of 10. Entry */ 29 - 10., /* is 10^2^i. Used to convert decimal */ 30 - 100., /* exponents into floating-point numbers. */ 31 - 1.0e4, 32 - 1.0e8, 33 - 1.0e16, 34 - 1.0e32, 35 - 1.0e64, 36 - 1.0e128, 37 - 1.0e256 38 -}; 39 - 40 -/* 41 - *---------------------------------------------------------------------- 42 - * 43 - * strtod -- 44 - * 45 - * This procedure converts a floating-point number from an ASCII 46 - * decimal representation to internal double-precision format. 47 - * 48 - * Results: 49 - * The return value is the double-precision floating-point 50 - * representation of the characters in string. If endPtr isn't 51 - * NULL, then *endPtr is filled in with the address of the 52 - * next character after the last one that was part of the 53 - * floating-point number. 54 - * 55 - * Side effects: 56 - * None. 57 - * 58 - *---------------------------------------------------------------------- 59 - */ 60 - 61 -double 62 -strtod( 63 - const char *string, /* A decimal ASCII floating-point number, 64 - * optionally preceded by white space. Must 65 - * have form "-I.FE-X", where I is the integer 66 - * part of the mantissa, F is the fractional 67 - * part of the mantissa, and X is the 68 - * exponent. Either of the signs may be "+", 69 - * "-", or omitted. Either I or F may be 70 - * omitted, or both. The decimal point isn't 71 - * necessary unless F is present. The "E" may 72 - * actually be an "e". E and X may both be 73 - * omitted (but not just one). */ 74 - char **endPtr) /* If non-NULL, store terminating character's 75 - * address here. */ 76 -{ 77 - int sign, expSign = FALSE; 78 - double fraction, dblExp; 79 - const double *d; 80 - register const char *p; 81 - register int c; 82 - int exp = 0; /* Exponent read from "EX" field. */ 83 - int fracExp = 0; /* Exponent that derives from the fractional 84 - * part. Under normal circumstatnces, it is 85 - * the negative of the number of digits in F. 86 - * However, if I is very long, the last digits 87 - * of I get dropped (otherwise a long I with a 88 - * large negative exponent could cause an 89 - * unnecessary overflow on I alone). In this 90 - * case, fracExp is incremented one for each 91 - * dropped digit. */ 92 - int mantSize; /* Number of digits in mantissa. */ 93 - int decPt; /* Number of mantissa digits BEFORE decimal 94 - * point. */ 95 - const char *pExp; /* Temporarily holds location of exponent in 96 - * string. */ 97 - 98 - /* 99 - * Strip off leading blanks and check for a sign. 100 - */ 101 - 102 - p = string; 103 - while (isspace(UCHAR(*p))) { 104 - p += 1; 105 - } 106 - if (*p == '-') { 107 - sign = TRUE; 108 - p += 1; 109 - } else { 110 - if (*p == '+') { 111 - p += 1; 112 - } 113 - sign = FALSE; 114 - } 115 - 116 - /* 117 - * Count the number of digits in the mantissa (including the decimal 118 - * point), and also locate the decimal point. 119 - */ 120 - 121 - decPt = -1; 122 - for (mantSize = 0; ; mantSize += 1) 123 - { 124 - c = *p; 125 - if (!isdigit(c)) { 126 - if ((c != '.') || (decPt >= 0)) { 127 - break; 128 - } 129 - decPt = mantSize; 130 - } 131 - p += 1; 132 - } 133 - 134 - /* 135 - * Now suck up the digits in the mantissa. Use two integers to collect 9 136 - * digits each (this is faster than using floating-point). If the mantissa 137 - * has more than 18 digits, ignore the extras, since they can't affect the 138 - * value anyway. 139 - */ 140 - 141 - pExp = p; 142 - p -= mantSize; 143 - if (decPt < 0) { 144 - decPt = mantSize; 145 - } else { 146 - mantSize -= 1; /* One of the digits was the point. */ 147 - } 148 - if (mantSize > 18) { 149 - fracExp = decPt - 18; 150 - mantSize = 18; 151 - } else { 152 - fracExp = decPt - mantSize; 153 - } 154 - if (mantSize == 0) { 155 - fraction = 0.0; 156 - p = string; 157 - goto done; 158 - } else { 159 - int frac1, frac2; 160 - 161 - frac1 = 0; 162 - for ( ; mantSize > 9; mantSize -= 1) { 163 - c = *p; 164 - p += 1; 165 - if (c == '.') { 166 - c = *p; 167 - p += 1; 168 - } 169 - frac1 = 10*frac1 + (c - '0'); 170 - } 171 - frac2 = 0; 172 - for (; mantSize > 0; mantSize -= 1) { 173 - c = *p; 174 - p += 1; 175 - if (c == '.') { 176 - c = *p; 177 - p += 1; 178 - } 179 - frac2 = 10*frac2 + (c - '0'); 180 - } 181 - fraction = (1.0e9 * frac1) + frac2; 182 - } 183 - 184 - /* 185 - * Skim off the exponent. 186 - */ 187 - 188 - p = pExp; 189 - if ((*p == 'E') || (*p == 'e')) { 190 - p += 1; 191 - if (*p == '-') { 192 - expSign = TRUE; 193 - p += 1; 194 - } else { 195 - if (*p == '+') { 196 - p += 1; 197 - } 198 - expSign = FALSE; 199 - } 200 - if (!isdigit(UCHAR(*p))) { 201 - p = pExp; 202 - goto done; 203 - } 204 - while (isdigit(UCHAR(*p))) { 205 - exp = exp * 10 + (*p - '0'); 206 - p += 1; 207 - } 208 - } 209 - if (expSign) { 210 - exp = fracExp - exp; 211 - } else { 212 - exp = fracExp + exp; 213 - } 214 - 215 - /* 216 - * Generate a floating-point number that represents the exponent. Do this 217 - * by processing the exponent one bit at a time to combine many powers of 218 - * 2 of 10. Then combine the exponent with the fraction. 219 - */ 220 - 221 - if (exp < 0) { 222 - expSign = TRUE; 223 - exp = -exp; 224 - } else { 225 - expSign = FALSE; 226 - } 227 - if (exp > maxExponent) { 228 - exp = maxExponent; 229 - errno = ERANGE; 230 - } 231 - dblExp = 1.0; 232 - for (d = powersOf10; exp != 0; exp >>= 1, ++d) { 233 - if (exp & 01) { 234 - dblExp *= *d; 235 - } 236 - } 237 - if (expSign) { 238 - fraction /= dblExp; 239 - } else { 240 - fraction *= dblExp; 241 - } 242 - 243 - done: 244 - if (endPtr != NULL) { 245 - *endPtr = (char *) p; 246 - } 247 - 248 - if (sign) { 249 - return -fraction; 250 - } 251 - return fraction; 252 -}
Changes to compat/strtol.c.
49 49 long result; 50 50 51 51 /* 52 52 * Skip any leading blanks. 53 53 */ 54 54 55 55 p = string; 56 - while (isspace(UCHAR(*p))) { 56 + while (TclIsSpaceProc(*p)) { 57 57 p += 1; 58 58 } 59 59 60 60 /* 61 61 * Check for a sign. 62 62 */ 63 63
Changes to compat/strtoul.c.
70 70 int overflow=0; 71 71 72 72 /* 73 73 * Skip any leading blanks. 74 74 */ 75 75 76 76 p = string; 77 - while (isspace(UCHAR(*p))) { 77 + while (TclIsSpaceProc(*p)) { 78 78 p += 1; 79 79 } 80 80 if (*p == '-') { 81 81 negative = 1; 82 82 p += 1; 83 83 } else { 84 84 if (*p == '+') {
Deleted compat/unistd.h.
1 -/* 2 - * unistd.h -- 3 - * 4 - * Macros, constants and prototypes for Posix conformance. 5 - * 6 - * Copyright 1989 Regents of the University of California Permission to use, 7 - * copy, modify, and distribute this software and its documentation for any 8 - * purpose and without fee is hereby granted, provided that the above 9 - * copyright notice appear in all copies. The University of California makes 10 - * no representations about the suitability of this software for any purpose. 11 - * It is provided "as is" without express or implied warranty. 12 - */ 13 - 14 -#ifndef _UNISTD 15 -#define _UNISTD 16 - 17 -#include <sys/types.h> 18 - 19 -#ifndef NULL 20 -#define NULL 0 21 -#endif 22 - 23 -/* 24 - * Strict POSIX stuff goes here. Extensions go down below, in the ifndef 25 - * _POSIX_SOURCE section. 26 - */ 27 - 28 -extern void _exit(int status); 29 -extern int access(const char *path, int mode); 30 -extern int chdir(const char *path); 31 -extern int chown(const char *path, uid_t owner, gid_t group); 32 -extern int close(int fd); 33 -extern int dup(int oldfd); 34 -extern int dup2(int oldfd, int newfd); 35 -extern int execl(const char *path, ...); 36 -extern int execle(const char *path, ...); 37 -extern int execlp(const char *file, ...); 38 -extern int execv(const char *path, char **argv); 39 -extern int execve(const char *path, char **argv, char **envp); 40 -extern int execvpw(const char *file, char **argv); 41 -extern pid_t fork(void); 42 -extern char * getcwd(char *buf, size_t size); 43 -extern gid_t getegid(void); 44 -extern uid_t geteuid(void); 45 -extern gid_t getgid(void); 46 -extern int getgroups(int bufSize, int *buffer); 47 -extern pid_t getpid(void); 48 -extern uid_t getuid(void); 49 -extern int isatty(int fd); 50 -extern long lseek(int fd, long offset, int whence); 51 -extern int pipe(int *fildes); 52 -extern int read(int fd, char *buf, size_t size); 53 -extern int setgid(gid_t group); 54 -extern int setuid(uid_t user); 55 -extern unsigned sleep(unsigned seconds); 56 -extern char * ttyname(int fd); 57 -extern int unlink(const char *path); 58 -extern int write(int fd, const char *buf, size_t size); 59 - 60 -#ifndef _POSIX_SOURCE 61 -extern char * crypt(const char *, const char *); 62 -extern int fchown(int fd, uid_t owner, gid_t group); 63 -extern int flock(int fd, int operation); 64 -extern int ftruncate(int fd, unsigned long length); 65 -extern int ioctl(int fd, int request, ...); 66 -extern int readlink(const char *path, char *buf, int bufsize); 67 -extern int setegid(gid_t group); 68 -extern int seteuidw(uid_t user); 69 -extern int setreuid(int ruid, int euid); 70 -extern int symlink(const char *, const char *); 71 -extern int ttyslot(void); 72 -extern int truncate(const char *path, unsigned long length); 73 -extern int vfork(void); 74 -#endif /* _POSIX_SOURCE */ 75 - 76 -#endif /* _UNISTD */
Changes to compat/waitpid.c.
96 96 result = waitPtr->pid; 97 97 *statusPtr = *((int *) &waitPtr->status); 98 98 if (prevPtr == NULL) { 99 99 deadList = waitPtr->nextPtr; 100 100 } else { 101 101 prevPtr->nextPtr = waitPtr->nextPtr; 102 102 } 103 - ckfree(waitPtr); 103 + Tcl_Free(waitPtr); 104 104 return result; 105 105 } 106 106 107 107 /* 108 108 * Wait for any process to stop or exit. If it's an acceptable one then 109 109 * return it to the caller; otherwise store information about it in the 110 110 * list of exited processes and try again. On systems that have only wait ................................................................................ 152 152 saveInfo: 153 153 for (waitPtr = deadList; waitPtr != NULL; waitPtr = waitPtr->nextPtr) { 154 154 if (waitPtr->pid == result) { 155 155 waitPtr->status = status; 156 156 goto waitAgain; 157 157 } 158 158 } 159 - waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo)); 159 + waitPtr = (WaitInfo *) Tcl_Alloc(sizeof(WaitInfo)); 160 160 waitPtr->pid = result; 161 161 waitPtr->status = status; 162 162 waitPtr->nextPtr = deadList; 163 163 deadList = waitPtr; 164 164 165 165 waitAgain: 166 166 continue; 167 167 } 168 168 }
Changes to compat/zlib/contrib/minizip/crypt.h.
24 24 25 25 The new AES encryption added on Zip format by Winzip (see the page 26 26 http://www.winzip.com/aes_info.htm ) and PKWare PKZip 5.x Strong 27 27 Encryption is not supported. 28 28 */ 29 29 30 30 #define CRC32(c, b) ((*(pcrc_32_tab+(((int)(c) ^ (b)) & 0xff))) ^ ((c) >> 8)) 31 + 32 +#ifdef Z_U4 33 + typedef Z_U4 z_crc_t; 34 +#else 35 + typedef unsigned long z_crc_t; 36 +#endif 31 37 32 38 /*********************************************************************** 33 39 * Return the next byte in the pseudo-random sequence 34 40 */ 35 41 static int decrypt_byte(unsigned long* pkeys, const z_crc_t* pcrc_32_tab) 36 42 { 37 43 unsigned temp; /* POTENTIAL BUG: temp*(temp^1) may overflow in an
Changes to compat/zlib/contrib/minizip/miniunz.c.
93 93 0,NULL,OPEN_EXISTING,0,NULL); 94 94 GetFileTime(hFile,&ftCreate,&ftLastAcc,&ftLastWrite); 95 95 DosDateTimeToFileTime((WORD)(dosdate>>16),(WORD)dosdate,&ftLocal); 96 96 LocalFileTimeToFileTime(&ftLocal,&ftm); 97 97 SetFileTime(hFile,&ftm,&ftLastAcc,&ftm); 98 98 CloseHandle(hFile); 99 99 #else 100 -#ifdef unix || __APPLE__ 100 +#if defined(unix) || defined(__APPLE__) 101 101 struct utimbuf ut; 102 102 struct tm newdate; 103 103 newdate.tm_sec = tmu_date.tm_sec; 104 104 newdate.tm_min=tmu_date.tm_min; 105 105 newdate.tm_hour=tmu_date.tm_hour; 106 106 newdate.tm_mday=tmu_date.tm_mday; 107 107 newdate.tm_mon=tmu_date.tm_mon;
Changes to compat/zlib/contrib/minizip/minizip.c.
8 8 Modifications of Unzip for Zip64 9 9 Copyright (C) 2007-2008 Even Rouault 10 10 11 11 Modifications for Zip64 support on both zip and unzip 12 12 Copyright (C) 2009-2010 Mathias Svensson ( http://result42.com ) 13 13 */ 14 14 15 - 16 15 #if (!defined(_WIN32)) && (!defined(WIN32)) && (!defined(__APPLE__)) 17 16 #ifndef __USE_FILE_OFFSET64 18 17 #define __USE_FILE_OFFSET64 19 18 #endif 20 19 #ifndef __USE_LARGEFILE64 21 20 #define __USE_LARGEFILE64 22 21 #endif ................................................................................ 24 23 #define _LARGEFILE64_SOURCE 25 24 #endif 26 25 #ifndef _FILE_OFFSET_BIT 27 26 #define _FILE_OFFSET_BIT 64 28 27 #endif 29 28 #endif 30 29 31 -#ifdef __APPLE__ 30 +#if defined(__APPLE__) || defined(IOAPI_NO_64) 32 31 // In darwin and perhaps other BSD variants off_t is a 64 bit value, hence no need for specific 64 bit functions 33 32 #define FOPEN_FUNC(filename, mode) fopen(filename, mode) 34 33 #define FTELLO_FUNC(stream) ftello(stream) 35 34 #define FSEEKO_FUNC(stream, offset, origin) fseeko(stream, offset, origin) 36 35 #else 37 36 #define FOPEN_FUNC(filename, mode) fopen64(filename, mode) 38 37 #define FTELLO_FUNC(stream) ftello64(stream) 39 38 #define FSEEKO_FUNC(stream, offset, origin) fseeko64(stream, offset, origin) 40 39 #endif 41 40 42 - 43 - 41 +#include "tinydir.h" 44 42 #include <stdio.h> 45 43 #include <stdlib.h> 46 44 #include <string.h> 47 45 #include <time.h> 48 46 #include <errno.h> 49 47 #include <fcntl.h> 50 48 ................................................................................ 90 88 FindClose(hFind); 91 89 ret = 1; 92 90 } 93 91 } 94 92 return ret; 95 93 } 96 94 #else 97 -#ifdef unix || __APPLE__ 95 +#if defined(unix) || defined(__APPLE__) 98 96 uLong filetime(f, tmzip, dt) 99 97 char *f; /* name of file to get info on */ 100 98 tm_zip *tmzip; /* return value: access, modific. and creation times */ 101 99 uLong *dt; /* dostime */ 102 100 { 103 101 int ret=0; 104 102 struct stat s; /* results of stat() */ ................................................................................ 168 166 printf("MiniZip 1.1, demo of zLib + MiniZip64 package, written by Gilles Vollant\n"); 169 167 printf("more info on MiniZip at http://www.winimage.com/zLibDll/minizip.html\n\n"); 170 168 } 171 169 172 170 void do_help() 173 171 { 174 172 printf("Usage : minizip [-o] [-a] [-0 to -9] [-p password] [-j] file.zip [files_to_add]\n\n" \ 173 + " -r Scan directories recursively\n" \ 175 174 " -o Overwrite existing file.zip\n" \ 176 175 " -a Append to existing file.zip\n" \ 177 176 " -0 Store only\n" \ 178 177 " -1 Compress faster\n" \ 179 178 " -9 Compress better\n\n" \ 180 179 " -j exclude path. store only the file name.\n\n"); 181 180 } ................................................................................ 238 237 largeFile = 1; 239 238 240 239 fclose(pFile); 241 240 } 242 241 243 242 return largeFile; 244 243 } 244 + 245 +void addFileToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) { 246 + FILE * fin; 247 + int size_read; 248 + const char *savefilenameinzip; 249 + zip_fileinfo zi; 250 + unsigned long crcFile=0; 251 + int zip64 = 0; 252 + int err=0; 253 + int size_buf=WRITEBUFFERSIZE; 254 + unsigned char buf[WRITEBUFFERSIZE]; 255 + zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour = 256 + zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0; 257 + zi.dosDate = 0; 258 + zi.internal_fa = 0; 259 + zi.external_fa = 0; 260 + filetime(filenameinzip,&zi.tmz_date,&zi.dosDate); 261 + 262 +/* 263 + err = zipOpenNewFileInZip(zf,filenameinzip,&zi, 264 + NULL,0,NULL,0,NULL / * comment * /, 265 + (opt_compress_level != 0) ? Z_DEFLATED : 0, 266 + opt_compress_level); 267 +*/ 268 + if ((password != NULL) && (err==ZIP_OK)) 269 + err = getFileCrc(filenameinzip,buf,size_buf,&crcFile); 270 + 271 + zip64 = isLargeFile(filenameinzip); 272 + 273 + /* The path name saved, should not include a leading slash. */ 274 + /*if it did, windows/xp and dynazip couldn't read the zip file. */ 275 + savefilenameinzip = filenameinzip; 276 + while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' ) 277 + { 278 + savefilenameinzip++; 279 + } 280 + 281 + /*should the zip file contain any path at all?*/ 282 + if( opt_exclude_path ) 283 + { 284 + const char *tmpptr; 285 + const char *lastslash = 0; 286 + for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++) 287 + { 288 + if( *tmpptr == '\\' || *tmpptr == '/') 289 + { 290 + lastslash = tmpptr; 291 + } 292 + } 293 + if( lastslash != NULL ) 294 + { 295 + savefilenameinzip = lastslash+1; // base filename follows last slash. 296 + } 297 + } 298 + 299 + /**/ 300 + err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi, 301 + NULL,0,NULL,0,NULL /* comment*/, 302 + (opt_compress_level != 0) ? Z_DEFLATED : 0, 303 + opt_compress_level,0, 304 + /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */ 305 + -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, 306 + password,crcFile, zip64); 307 + 308 + if (err != ZIP_OK) 309 + printf("error in opening %s in zipfile\n",filenameinzip); 310 + else 311 + { 312 + fin = FOPEN_FUNC(filenameinzip,"rb"); 313 + if (fin==NULL) 314 + { 315 + err=ZIP_ERRNO; 316 + printf("error in opening %s for reading\n",filenameinzip); 317 + } 318 + } 319 + 320 + if (err == ZIP_OK) 321 + do 322 + { 323 + err = ZIP_OK; 324 + size_read = (int)fread(buf,1,size_buf,fin); 325 + if (size_read < size_buf) 326 + if (feof(fin)==0) 327 + { 328 + printf("error in reading %s\n",filenameinzip); 329 + err = ZIP_ERRNO; 330 + } 331 + 332 + if (size_read>0) 333 + { 334 + err = zipWriteInFileInZip (zf,buf,size_read); 335 + if (err<0) 336 + { 337 + printf("error in writing %s in the zipfile\n", 338 + filenameinzip); 339 + } 340 + 341 + } 342 + } while ((err == ZIP_OK) && (size_read>0)); 343 + 344 + if (fin) 345 + fclose(fin); 346 + 347 + if (err<0) 348 + err=ZIP_ERRNO; 349 + else 350 + { 351 + err = zipCloseFileInZip(zf); 352 + if (err!=ZIP_OK) 353 + printf("error in closing %s in the zipfile\n", 354 + filenameinzip); 355 + } 356 +} 357 + 358 + 359 +void addPathToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) { 360 + tinydir_dir dir; 361 + int i; 362 + char newname[512]; 363 + 364 + tinydir_open_sorted(&dir, filenameinzip); 365 + 366 + for (i = 0; i < dir.n_files; i++) 367 + { 368 + tinydir_file file; 369 + tinydir_readfile_n(&dir, &file, i); 370 + if(strcmp(file.name,".")==0) continue; 371 + if(strcmp(file.name,"..")==0) continue; 372 + sprintf(newname,"%s/%s",dir.path,file.name); 373 + if (file.is_dir) 374 + { 375 + addPathToZip(zf,newname,password,opt_exclude_path,opt_compress_level); 376 + } else { 377 + addFileToZip(zf,newname,password,opt_exclude_path,opt_compress_level); 378 + } 379 + } 380 + 381 + tinydir_close(&dir); 382 +} 383 + 245 384 246 385 int main(argc,argv) 247 386 int argc; 248 387 char *argv[]; 249 388 { 250 389 int i; 251 - int opt_overwrite=0; 390 + int opt_recursive=0; 391 + int opt_overwrite=1; 252 392 int opt_compress_level=Z_DEFAULT_COMPRESSION; 253 393 int opt_exclude_path=0; 254 394 int zipfilenamearg = 0; 255 395 char filename_try[MAXFILENAME+16]; 256 396 int zipok; 257 397 int err=0; 258 398 int size_buf=0; ................................................................................ 281 421 opt_overwrite = 1; 282 422 if ((c=='a') || (c=='A')) 283 423 opt_overwrite = 2; 284 424 if ((c>='0') && (c<='9')) 285 425 opt_compress_level = c-'0'; 286 426 if ((c=='j') || (c=='J')) 287 427 opt_exclude_path = 1; 288 - 428 + if ((c=='r') || (c=='R')) 429 + opt_recursive = 1; 289 430 if (((c=='p') || (c=='P')) && (i+1<argc)) 290 431 { 291 432 password=argv[i+1]; 292 433 i++; 293 434 } 294 435 } 295 436 } ................................................................................ 388 529 389 530 for (i=zipfilenamearg+1;(i<argc) && (err==ZIP_OK);i++) 390 531 { 391 532 if (!((((*(argv[i]))=='-') || ((*(argv[i]))=='/')) && 392 533 ((argv[i][1]=='o') || (argv[i][1]=='O') || 393 534 (argv[i][1]=='a') || (argv[i][1]=='A') || 394 535 (argv[i][1]=='p') || (argv[i][1]=='P') || 536 + (argv[i][1]=='r') || (argv[i][1]=='R') || 395 537 ((argv[i][1]>='0') || (argv[i][1]<='9'))) && 396 538 (strlen(argv[i]) == 2))) 397 539 { 398 - FILE * fin; 399 - int size_read; 400 - const char* filenameinzip = argv[i]; 401 - const char *savefilenameinzip; 402 - zip_fileinfo zi; 403 - unsigned long crcFile=0; 404 - int zip64 = 0; 405 - 406 - zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour = 407 - zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0; 408 - zi.dosDate = 0; 409 - zi.internal_fa = 0; 410 - zi.external_fa = 0; 411 - filetime(filenameinzip,&zi.tmz_date,&zi.dosDate); 412 - 413 -/* 414 - err = zipOpenNewFileInZip(zf,filenameinzip,&zi, 415 - NULL,0,NULL,0,NULL / * comment * /, 416 - (opt_compress_level != 0) ? Z_DEFLATED : 0, 417 - opt_compress_level); 418 -*/ 419 - if ((password != NULL) && (err==ZIP_OK)) 420 - err = getFileCrc(filenameinzip,buf,size_buf,&crcFile); 421 - 422 - zip64 = isLargeFile(filenameinzip); 423 - 424 - /* The path name saved, should not include a leading slash. */ 425 - /*if it did, windows/xp and dynazip couldn't read the zip file. */ 426 - savefilenameinzip = filenameinzip; 427 - while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' ) 428 - { 429 - savefilenameinzip++; 430 - } 431 - 432 - /*should the zip file contain any path at all?*/ 433 - if( opt_exclude_path ) 434 - { 435 - const char *tmpptr; 436 - const char *lastslash = 0; 437 - for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++) 438 - { 439 - if( *tmpptr == '\\' || *tmpptr == '/') 440 - { 441 - lastslash = tmpptr; 442 - } 443 - } 444 - if( lastslash != NULL ) 445 - { 446 - savefilenameinzip = lastslash+1; // base filename follows last slash. 447 - } 448 - } 449 - 450 - /**/ 451 - err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi, 452 - NULL,0,NULL,0,NULL /* comment*/, 453 - (opt_compress_level != 0) ? Z_DEFLATED : 0, 454 - opt_compress_level,0, 455 - /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */ 456 - -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, 457 - password,crcFile, zip64); 458 - 459 - if (err != ZIP_OK) 460 - printf("error in opening %s in zipfile\n",filenameinzip); 461 - else 462 - { 463 - fin = FOPEN_FUNC(filenameinzip,"rb"); 464 - if (fin==NULL) 465 - { 466 - err=ZIP_ERRNO; 467 - printf("error in opening %s for reading\n",filenameinzip); 468 - } 469 - } 470 - 471 - if (err == ZIP_OK) 472 - do 473 - { 474 - err = ZIP_OK; 475 - size_read = (int)fread(buf,1,size_buf,fin); 476 - if (size_read < size_buf) 477 - if (feof(fin)==0) 478 - { 479 - printf("error in reading %s\n",filenameinzip); 480 - err = ZIP_ERRNO; 481 - } 482 - 483 - if (size_read>0) 484 - { 485 - err = zipWriteInFileInZip (zf,buf,size_read); 486 - if (err<0) 487 - { 488 - printf("error in writing %s in the zipfile\n", 489 - filenameinzip); 490 - } 491 - 492 - } 493 - } while ((err == ZIP_OK) && (size_read>0)); 494 - 495 - if (fin) 496 - fclose(fin); 497 - 498 - if (err<0) 499 - err=ZIP_ERRNO; 500 - else 501 - { 502 - err = zipCloseFileInZip(zf); 503 - if (err!=ZIP_OK) 504 - printf("error in closing %s in the zipfile\n", 505 - filenameinzip); 540 + if(opt_recursive) { 541 + addPathToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level); 542 + } else { 543 + addFileToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level); 506 544 } 507 545 } 508 546 } 509 547 errclose = zipClose(zf,NULL); 510 548 if (errclose != ZIP_OK) 511 549 printf("error in closing %s\n",filename_try); 512 550 }
Added compat/zlib/contrib/minizip/tinydir.h.
1 +/* 2 +Copyright (c) 2013-2017, tinydir authors: 3 +- Cong Xu 4 +- Lautis Sun 5 +- Baudouin Feildel 6 +- Andargor <[email protected]> 7 +All rights reserved. 8 + 9 +Redistribution and use in source and binary forms, with or without 10 +modification, are permitted provided that the following conditions are met: 11 + 12 +1. Redistributions of source code must retain the above copyright notice, this 13 + list of conditions and the following disclaimer. 14 +2. Redistributions in binary form must reproduce the above copyright notice, 15 + this list of conditions and the following disclaimer in the documentation 16 + and/or other materials provided with the distribution. 17 + 18 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 19 +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 20 +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 21 +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 22 +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23 +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24 +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 25 +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 27 +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 +*/ 29 +#ifndef TINYDIR_H 30 +#define TINYDIR_H 31 + 32 +#ifdef __cplusplus 33 +extern "C" { 34 +#endif 35 + 36 +#if ((defined _UNICODE) && !(defined UNICODE)) 37 +#define UNICODE 38 +#endif 39 + 40 +#if ((defined UNICODE) && !(defined _UNICODE)) 41 +#define _UNICODE 42 +#endif 43 + 44 +#include <errno.h> 45 +#include <stdlib.h> 46 +#include <string.h> 47 +#ifdef _MSC_VER 48 +# define WIN32_LEAN_AND_MEAN 49 +# include <windows.h> 50 +# include <tchar.h> 51 +# pragma warning(push) 52 +# pragma warning (disable : 4996) 53 +#else 54 +# include <dirent.h> 55 +# include <libgen.h> 56 +# include <sys/stat.h> 57 +# include <stddef.h> 58 +#endif 59 +#ifdef __MINGW32__ 60 +# include <tchar.h> 61 +#endif 62 + 63 + 64 +/* types */ 65 + 66 +/* Windows UNICODE wide character support */ 67 +#if defined _MSC_VER || defined __MINGW32__ 68 +# define _tinydir_char_t TCHAR 69 +# define TINYDIR_STRING(s) _TEXT(s) 70 +# define _tinydir_strlen _tcslen 71 +# define _tinydir_strcpy _tcscpy 72 +# define _tinydir_strcat _tcscat 73 +# define _tinydir_strcmp _tcscmp 74 +# define _tinydir_strrchr _tcsrchr 75 +# define _tinydir_strncmp _tcsncmp 76 +#else 77 +# define _tinydir_char_t char 78 +# define TINYDIR_STRING(s) s 79 +# define _tinydir_strlen strlen 80 +# define _tinydir_strcpy strcpy 81 +# define _tinydir_strcat strcat 82 +# define _tinydir_strcmp strcmp 83 +# define _tinydir_strrchr strrchr 84 +# define _tinydir_strncmp strncmp 85 +#endif 86 + 87 +#if (defined _MSC_VER || defined __MINGW32__) 88 +# include <windows.h> 89 +# define _TINYDIR_PATH_MAX MAX_PATH 90 +#elif defined __linux__ 91 +# include <limits.h> 92 +# define _TINYDIR_PATH_MAX PATH_MAX 93 +#elif defined(__unix__) || (defined(__APPLE__) && defined(__MACH__)) 94 +# include <sys/param.h> 95 +# if defined(BSD) 96 +# include <limits.h> 97 +# define _TINYDIR_PATH_MAX PATH_MAX 98 +# endif 99 +#endif 100 + 101 +#ifndef _TINYDIR_PATH_MAX 102 +#define _TINYDIR_PATH_MAX 4096 103 +#endif 104 + 105 +#ifdef _MSC_VER 106 +/* extra chars for the "\\*" mask */ 107 +# define _TINYDIR_PATH_EXTRA 2 108 +#else 109 +# define _TINYDIR_PATH_EXTRA 0 110 +#endif 111 + 112 +#define _TINYDIR_FILENAME_MAX 256 113 + 114 +#if (defined _MSC_VER || defined __MINGW32__) 115 +#define _TINYDIR_DRIVE_MAX 3 116 +#endif 117 + 118 +#ifdef _MSC_VER 119 +# define _TINYDIR_FUNC static __inline 120 +#elif !defined __STDC_VERSION__ || __STDC_VERSION__ < 199901L 121 +# define _TINYDIR_FUNC static __inline__ 122 +#else 123 +# define _TINYDIR_FUNC static inline 124 +#endif 125 + 126 +/* readdir_r usage; define TINYDIR_USE_READDIR_R to use it (if supported) */ 127 +#ifdef TINYDIR_USE_READDIR_R 128 + 129 +/* readdir_r is a POSIX-only function, and may not be available under various 130 + * environments/settings, e.g. MinGW. Use readdir fallback */ 131 +#if _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||\ 132 + _POSIX_SOURCE 133 +# define _TINYDIR_HAS_READDIR_R 134 +#endif 135 +#if _POSIX_C_SOURCE >= 200112L 136 +# define _TINYDIR_HAS_FPATHCONF 137 +# include <unistd.h> 138 +#endif 139 +#if _BSD_SOURCE || _SVID_SOURCE || \ 140 + (_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700) 141 +# define _TINYDIR_HAS_DIRFD 142 +# include <sys/types.h> 143 +#endif 144 +#if defined _TINYDIR_HAS_FPATHCONF && defined _TINYDIR_HAS_DIRFD &&\ 145 + defined _PC_NAME_MAX 146 +# define _TINYDIR_USE_FPATHCONF 147 +#endif 148 +#if defined __MINGW32__ || !defined _TINYDIR_HAS_READDIR_R ||\ 149 + !(defined _TINYDIR_USE_FPATHCONF || defined NAME_MAX) 150 +# define _TINYDIR_USE_READDIR 151 +#endif 152 + 153 +/* Use readdir by default */ 154 +#else 155 +# define _TINYDIR_USE_READDIR 156 +#endif 157 + 158 +/* MINGW32 has two versions of dirent, ASCII and UNICODE*/ 159 +#ifndef _MSC_VER 160 +#if (defined __MINGW32__) && (defined _UNICODE) 161 +#define _TINYDIR_DIR _WDIR 162 +#define _tinydir_dirent _wdirent 163 +#define _tinydir_opendir _wopendir 164 +#define _tinydir_readdir _wreaddir 165 +#define _tinydir_closedir _wclosedir 166 +#else 167 +#define _TINYDIR_DIR DIR 168 +#define _tinydir_dirent dirent 169 +#define _tinydir_opendir opendir 170 +#define _tinydir_readdir readdir 171 +#define _tinydir_closedir closedir 172 +#endif 173 +#endif 174 + 175 +/* Allow user to use a custom allocator by defining _TINYDIR_MALLOC and _TINYDIR_FREE. */ 176 +#if defined(_TINYDIR_MALLOC) && defined(_TINYDIR_FREE) 177 +#elif !defined(_TINYDIR_MALLOC) && !defined(_TINYDIR_FREE) 178 +#else 179 +#error "Either define both alloc and free or none of them!" 180 +#endif 181 + 182 +#if !defined(_TINYDIR_MALLOC) 183 + #define _TINYDIR_MALLOC(_size) malloc(_size) 184 + #define _TINYDIR_FREE(_ptr) free(_ptr) 185 +#endif /* !defined(_TINYDIR_MALLOC) */ 186 + 187 +typedef struct tinydir_file 188 +{ 189 + _tinydir_char_t path[_TINYDIR_PATH_MAX]; 190 + _tinydir_char_t name[_TINYDIR_FILENAME_MAX]; 191 + _tinydir_char_t *extension; 192 + int is_dir; 193 + int is_reg; 194 + 195 +#ifndef _MSC_VER 196 +#ifdef __MINGW32__ 197 + struct _stat _s; 198 +#else 199 + struct stat _s; 200 +#endif 201 +#endif 202 +} tinydir_file; 203 + 204 +typedef struct tinydir_dir 205 +{ 206 + _tinydir_char_t path[_TINYDIR_PATH_MAX]; 207 + int has_next; 208 + size_t n_files; 209 + 210 + tinydir_file *_files; 211 +#ifdef _MSC_VER 212 + HANDLE _h; 213 + WIN32_FIND_DATA _f; 214 +#else 215 + _TINYDIR_DIR *_d; 216 + struct _tinydir_dirent *_e; 217 +#ifndef _TINYDIR_USE_READDIR 218 + struct _tinydir_dirent *_ep; 219 +#endif 220 +#endif 221 +} tinydir_dir; 222 + 223 + 224 +/* declarations */ 225 + 226 +_TINYDIR_FUNC 227 +int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path); 228 +_TINYDIR_FUNC 229 +int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path); 230 +_TINYDIR_FUNC 231 +void tinydir_close(tinydir_dir *dir); 232 + 233 +_TINYDIR_FUNC 234 +int tinydir_next(tinydir_dir *dir); 235 +_TINYDIR_FUNC 236 +int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file); 237 +_TINYDIR_FUNC 238 +int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i); 239 +_TINYDIR_FUNC 240 +int tinydir_open_subdir_n(tinydir_dir *dir, size_t i); 241 + 242 +_TINYDIR_FUNC 243 +int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path); 244 +_TINYDIR_FUNC 245 +void _tinydir_get_ext(tinydir_file *file); 246 +_TINYDIR_FUNC 247 +int _tinydir_file_cmp(const void *a, const void *b); 248 +#ifndef _MSC_VER 249 +#ifndef _TINYDIR_USE_READDIR 250 +_TINYDIR_FUNC 251 +size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp); 252 +#endif 253 +#endif 254 + 255 + 256 +/* definitions*/ 257 + 258 +_TINYDIR_FUNC 259 +int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path) 260 +{ 261 +#ifndef _MSC_VER 262 +#ifndef _TINYDIR_USE_READDIR 263 + int error; 264 + int size; /* using int size */ 265 +#endif 266 +#else 267 + _tinydir_char_t path_buf[_TINYDIR_PATH_MAX]; 268 +#endif 269 + _tinydir_char_t *pathp; 270 + 271 + if (dir == NULL || path == NULL || _tinydir_strlen(path) == 0) 272 + { 273 + errno = EINVAL; 274 + return -1; 275 + } 276 + if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX) 277 + { 278 + errno = ENAMETOOLONG; 279 + return -1; 280 + } 281 + 282 + /* initialise dir */ 283 + dir->_files = NULL; 284 +#ifdef _MSC_VER 285 + dir->_h = INVALID_HANDLE_VALUE; 286 +#else 287 + dir->_d = NULL; 288 +#ifndef _TINYDIR_USE_READDIR 289 + dir->_ep = NULL; 290 +#endif 291 +#endif 292 + tinydir_close(dir); 293 + 294 + _tinydir_strcpy(dir->path, path); 295 + /* Remove trailing slashes */ 296 + pathp = &dir->path[_tinydir_strlen(dir->path) - 1]; 297 + while (pathp != dir->path && (*pathp == TINYDIR_STRING('\\') || *pathp == TINYDIR_STRING('/'))) 298 + { 299 + *pathp = TINYDIR_STRING('\0'); 300 + pathp++; 301 + } 302 +#ifdef _MSC_VER 303 + _tinydir_strcpy(path_buf, dir->path); 304 + _tinydir_strcat(path_buf, TINYDIR_STRING("\\*")); 305 +#if (defined WINAPI_FAMILY) && (WINAPI_FAMILY != WINAPI_FAMILY_DESKTOP_APP) 306 + dir->_h = FindFirstFileEx(path_buf, FindExInfoStandard, &dir->_f, FindExSearchNameMatch, NULL, 0); 307 +#else 308 + dir->_h = FindFirstFile(path_buf, &dir->_f); 309 +#endif 310 + if (dir->_h == INVALID_HANDLE_VALUE) 311 + { 312 + errno = ENOENT; 313 +#else 314 + dir->_d = _tinydir_opendir(path); 315 + if (dir->_d == NULL) 316 + { 317 +#endif 318 + goto bail; 319 + } 320 + 321 + /* read first file */ 322 + dir->has_next = 1; 323 +#ifndef _MSC_VER 324 +#ifdef _TINYDIR_USE_READDIR 325 + dir->_e = _tinydir_readdir(dir->_d); 326 +#else 327 + /* allocate dirent buffer for readdir_r */ 328 + size = _tinydir_dirent_buf_size(dir->_d); /* conversion to int */ 329 + if (size == -1) return -1; 330 + dir->_ep = (struct _tinydir_dirent*)_TINYDIR_MALLOC(size); 331 + if (dir->_ep == NULL) return -1; 332 + 333 + error = readdir_r(dir->_d, dir->_ep, &dir->_e); 334 + if (error != 0) return -1; 335 +#endif 336 + if (dir->_e == NULL) 337 + { 338 + dir->has_next = 0; 339 + } 340 +#endif 341 + 342 + return 0; 343 + 344 +bail: 345 + tinydir_close(dir); 346 + return -1; 347 +} 348 + 349 +_TINYDIR_FUNC 350 +int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path) 351 +{ 352 + /* Count the number of files first, to pre-allocate the files array */ 353 + size_t n_files = 0; 354 + if (tinydir_open(dir, path) == -1) 355 + { 356 + return -1; 357 + } 358 + while (dir->has_next) 359 + { 360 + n_files++; 361 + if (tinydir_next(dir) == -1) 362 + { 363 + goto bail; 364 + } 365 + } 366 + tinydir_close(dir); 367 + 368 + if (tinydir_open(dir, path) == -1) 369 + { 370 + return -1; 371 + } 372 + 373 + dir->n_files = 0; 374 + dir->_files = (tinydir_file *)_TINYDIR_MALLOC(sizeof *dir->_files * n_files); 375 + if (dir->_files == NULL) 376 + { 377 + goto bail; 378 + } 379 + while (dir->has_next) 380 + { 381 + tinydir_file *p_file; 382 + dir->n_files++; 383 + 384 + p_file = &dir->_files[dir->n_files - 1]; 385 + if (tinydir_readfile(dir, p_file) == -1) 386 + { 387 + goto bail; 388 + } 389 + 390 + if (tinydir_next(dir) == -1) 391 + { 392 + goto bail; 393 + } 394 + 395 + /* Just in case the number of files has changed between the first and 396 + second reads, terminate without writing into unallocated memory */ 397 + if (dir->n_files == n_files) 398 + { 399 + break; 400 + } 401 + } 402 + 403 + qsort(dir->_files, dir->n_files, sizeof(tinydir_file), _tinydir_file_cmp); 404 + 405 + return 0; 406 + 407 +bail: 408 + tinydir_close(dir); 409 + return -1; 410 +} 411 + 412 +_TINYDIR_FUNC 413 +void tinydir_close(tinydir_dir *dir) 414 +{ 415 + if (dir == NULL) 416 + { 417 + return; 418 + } 419 + 420 + memset(dir->path, 0, sizeof(dir->path)); 421 + dir->has_next = 0; 422 + dir->n_files = 0; 423 + _TINYDIR_FREE(dir->_files); 424 + dir->_files = NULL; 425 +#ifdef _MSC_VER 426 + if (dir->_h != INVALID_HANDLE_VALUE) 427 + { 428 + FindClose(dir->_h); 429 + } 430 + dir->_h = INVALID_HANDLE_VALUE; 431 +#else 432 + if (dir->_d) 433 + { 434 + _tinydir_closedir(dir->_d); 435 + } 436 + dir->_d = NULL; 437 + dir->_e = NULL; 438 +#ifndef _TINYDIR_USE_READDIR 439 + _TINYDIR_FREE(dir->_ep); 440 + dir->_ep = NULL; 441 +#endif 442 +#endif 443 +} 444 + 445 +_TINYDIR_FUNC 446 +int tinydir_next(tinydir_dir *dir) 447 +{ 448 + if (dir == NULL) 449 + { 450 + errno = EINVAL; 451 + return -1; 452 + } 453 + if (!dir->has_next) 454 + { 455 + errno = ENOENT; 456 + return -1; 457 + } 458 + 459 +#ifdef _MSC_VER 460 + if (FindNextFile(dir->_h, &dir->_f) == 0) 461 +#else 462 +#ifdef _TINYDIR_USE_READDIR 463 + dir->_e = _tinydir_readdir(dir->_d); 464 +#else 465 + if (dir->_ep == NULL) 466 + { 467 + return -1; 468 + } 469 + if (readdir_r(dir->_d, dir->_ep, &dir->_e) != 0) 470 + { 471 + return -1; 472 + } 473 +#endif 474 + if (dir->_e == NULL) 475 +#endif 476 + { 477 + dir->has_next = 0; 478 +#ifdef _MSC_VER 479 + if (GetLastError() != ERROR_SUCCESS && 480 + GetLastError() != ERROR_NO_MORE_FILES) 481 + { 482 + tinydir_close(dir); 483 + errno = EIO; 484 + return -1; 485 + } 486 +#endif 487 + } 488 + 489 + return 0; 490 +} 491 + 492 +_TINYDIR_FUNC 493 +int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file) 494 +{ 495 + if (dir == NULL || file == NULL) 496 + { 497 + errno = EINVAL; 498 + return -1; 499 + } 500 +#ifdef _MSC_VER 501 + if (dir->_h == INVALID_HANDLE_VALUE) 502 +#else 503 + if (dir->_e == NULL) 504 +#endif 505 + { 506 + errno = ENOENT; 507 + return -1; 508 + } 509 + if (_tinydir_strlen(dir->path) + 510 + _tinydir_strlen( 511 +#ifdef _MSC_VER 512 + dir->_f.cFileName 513 +#else 514 + dir->_e->d_name 515 +#endif 516 + ) + 1 + _TINYDIR_PATH_EXTRA >= 517 + _TINYDIR_PATH_MAX) 518 + { 519 + /* the path for the file will be too long */ 520 + errno = ENAMETOOLONG; 521 + return -1; 522 + } 523 + if (_tinydir_strlen( 524 +#ifdef _MSC_VER 525 + dir->_f.cFileName 526 +#else 527 + dir->_e->d_name 528 +#endif 529 + ) >= _TINYDIR_FILENAME_MAX) 530 + { 531 + errno = ENAMETOOLONG; 532 + return -1; 533 + } 534 + 535 + _tinydir_strcpy(file->path, dir->path); 536 + _tinydir_strcat(file->path, TINYDIR_STRING("/")); 537 + _tinydir_strcpy(file->name, 538 +#ifdef _MSC_VER 539 + dir->_f.cFileName 540 +#else 541 + dir->_e->d_name 542 +#endif 543 + ); 544 + _tinydir_strcat(file->path, file->name); 545 +#ifndef _MSC_VER 546 +#ifdef __MINGW32__ 547 + if (_tstat( 548 +#else 549 + if (stat( 550 +#endif 551 + file->path, &file->_s) == -1) 552 + { 553 + return -1; 554 + } 555 +#endif 556 + _tinydir_get_ext(file); 557 + 558 + file->is_dir = 559 +#ifdef _MSC_VER 560 + !!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY); 561 +#else 562 + S_ISDIR(file->_s.st_mode); 563 +#endif 564 + file->is_reg = 565 +#ifdef _MSC_VER 566 + !!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NORMAL) || 567 + ( 568 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DEVICE) && 569 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) && 570 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_ENCRYPTED) && 571 +#ifdef FILE_ATTRIBUTE_INTEGRITY_STREAM 572 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_INTEGRITY_STREAM) && 573 +#endif 574 +#ifdef FILE_ATTRIBUTE_NO_SCRUB_DATA 575 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NO_SCRUB_DATA) && 576 +#endif 577 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_OFFLINE) && 578 + !(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_TEMPORARY)); 579 +#else 580 + S_ISREG(file->_s.st_mode); 581 +#endif 582 + 583 + return 0; 584 +} 585 + 586 +_TINYDIR_FUNC 587 +int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i) 588 +{ 589 + if (dir == NULL || file == NULL) 590 + { 591 + errno = EINVAL; 592 + return -1; 593 + } 594 + if (i >= dir->n_files) 595 + { 596 + errno = ENOENT; 597 + return -1; 598 + } 599 + 600 + memcpy(file, &dir->_files[i], sizeof(tinydir_file)); 601 + _tinydir_get_ext(file); 602 + 603 + return 0; 604 +} 605 + 606 +_TINYDIR_FUNC 607 +int tinydir_open_subdir_n(tinydir_dir *dir, size_t i) 608 +{ 609 + _tinydir_char_t path[_TINYDIR_PATH_MAX]; 610 + if (dir == NULL) 611 + { 612 + errno = EINVAL; 613 + return -1; 614 + } 615 + if (i >= dir->n_files || !dir->_files[i].is_dir) 616 + { 617 + errno = ENOENT; 618 + return -1; 619 + } 620 + 621 + _tinydir_strcpy(path, dir->_files[i].path); 622 + tinydir_close(dir); 623 + if (tinydir_open_sorted(dir, path) == -1) 624 + { 625 + return -1; 626 + } 627 + 628 + return 0; 629 +} 630 + 631 +/* Open a single file given its path */ 632 +_TINYDIR_FUNC 633 +int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path) 634 +{ 635 + tinydir_dir dir; 636 + int result = 0; 637 + int found = 0; 638 + _tinydir_char_t dir_name_buf[_TINYDIR_PATH_MAX]; 639 + _tinydir_char_t file_name_buf[_TINYDIR_FILENAME_MAX]; 640 + _tinydir_char_t *dir_name; 641 + _tinydir_char_t *base_name; 642 +#if (defined _MSC_VER || defined __MINGW32__) 643 + _tinydir_char_t drive_buf[_TINYDIR_PATH_MAX]; 644 + _tinydir_char_t ext_buf[_TINYDIR_FILENAME_MAX]; 645 +#endif 646 + 647 + if (file == NULL || path == NULL || _tinydir_strlen(path) == 0) 648 + { 649 + errno = EINVAL; 650 + return -1; 651 + } 652 + if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX) 653 + { 654 + errno = ENAMETOOLONG; 655 + return -1; 656 + } 657 + 658 + /* Get the parent path */ 659 +#if (defined _MSC_VER || defined __MINGW32__) 660 +#if ((defined _MSC_VER) && (_MSC_VER >= 1400)) 661 + _tsplitpath_s( 662 + path, 663 + drive_buf, _TINYDIR_DRIVE_MAX, 664 + dir_name_buf, _TINYDIR_FILENAME_MAX, 665 + file_name_buf, _TINYDIR_FILENAME_MAX, 666 + ext_buf, _TINYDIR_FILENAME_MAX); 667 +#else 668 + _tsplitpath( 669 + path, 670 + drive_buf, 671 + dir_name_buf, 672 + file_name_buf, 673 + ext_buf); 674 +#endif 675 + 676 +/* _splitpath_s not work fine with only filename and widechar support */ 677 +#ifdef _UNICODE 678 + if (drive_buf[0] == L'\xFEFE') 679 + drive_buf[0] = '\0'; 680 + if (dir_name_buf[0] == L'\xFEFE') 681 + dir_name_buf[0] = '\0'; 682 +#endif 683 + 684 + if (errno) 685 + { 686 + errno = EINVAL; 687 + return -1; 688 + } 689 + /* Emulate the behavior of dirname by returning "." for dir name if it's 690 + empty */ 691 + if (drive_buf[0] == '\0' && dir_name_buf[0] == '\0') 692 + { 693 + _tinydir_strcpy(dir_name_buf, TINYDIR_STRING(".")); 694 + } 695 + /* Concatenate the drive letter and dir name to form full dir name */ 696 + _tinydir_strcat(drive_buf, dir_name_buf); 697 + dir_name = drive_buf; 698 + /* Concatenate the file name and extension to form base name */ 699 + _tinydir_strcat(file_name_buf, ext_buf); 700 + base_name = file_name_buf; 701 +#else 702 + _tinydir_strcpy(dir_name_buf, path); 703 + dir_name = dirname(dir_name_buf); 704 + _tinydir_strcpy(file_name_buf, path); 705 + base_name =basename(file_name_buf); 706 +#endif 707 + 708 + /* Open the parent directory */ 709 + if (tinydir_open(&dir, dir_name) == -1) 710 + { 711 + return -1; 712 + } 713 + 714 + /* Read through the parent directory and look for the file */ 715 + while (dir.has_next) 716 + { 717 + if (tinydir_readfile(&dir, file) == -1) 718 + { 719 + result = -1; 720 + goto bail; 721 + } 722 + if (_tinydir_strcmp(file->name, base_name) == 0) 723 + { 724 + /* File found */ 725 + found = 1; 726 + break; 727 + } 728 + tinydir_next(&dir); 729 + } 730 + if (!found) 731 + { 732 + result = -1; 733 + errno = ENOENT; 734 + } 735 + 736 +bail: 737 + tinydir_close(&dir); 738 + return result; 739 +} 740 + 741 +_TINYDIR_FUNC 742 +void _tinydir_get_ext(tinydir_file *file) 743 +{ 744 + _tinydir_char_t *period = _tinydir_strrchr(file->name, TINYDIR_STRING('.')); 745 + if (period == NULL) 746 + { 747 + file->extension = &(file->name[_tinydir_strlen(file->name)]); 748 + } 749 + else 750 + { 751 + file->extension = period + 1; 752 + } 753 +} 754 + 755 +_TINYDIR_FUNC 756 +int _tinydir_file_cmp(const void *a, const void *b) 757 +{ 758 + const tinydir_file *fa = (const tinydir_file *)a; 759 + const tinydir_file *fb = (const tinydir_file *)b; 760 + if (fa->is_dir != fb->is_dir) 761 + { 762 + return -(fa->is_dir - fb->is_dir); 763 + } 764 + return _tinydir_strncmp(fa->name, fb->name, _TINYDIR_FILENAME_MAX); 765 +} 766 + 767 +#ifndef _MSC_VER 768 +#ifndef _TINYDIR_USE_READDIR 769 +/* 770 +The following authored by Ben Hutchings <[email protected]> 771 +from https://womble.decadent.org.uk/readdir_r-advisory.html 772 +*/ 773 +/* Calculate the required buffer size (in bytes) for directory * 774 +* entries read from the given directory handle. Return -1 if this * 775 +* this cannot be done. * 776 +* * 777 +* This code does not trust values of NAME_MAX that are less than * 778 +* 255, since some systems (including at least HP-UX) incorrectly * 779 +* define it to be a smaller value. */ 780 +_TINYDIR_FUNC 781 +size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp) 782 +{ 783 + long name_max; 784 + size_t name_end; 785 + /* parameter may be unused */ 786 + (void)dirp; 787 + 788 +#if defined _TINYDIR_USE_FPATHCONF 789 + name_max = fpathconf(dirfd(dirp), _PC_NAME_MAX); 790 + if (name_max == -1) 791 +#if defined(NAME_MAX) 792 + name_max = (NAME_MAX > 255) ? NAME_MAX : 255; 793 +#else 794 + return (size_t)(-1); 795 +#endif 796 +#elif defined(NAME_MAX) 797 + name_max = (NAME_MAX > 255) ? NAME_MAX : 255; 798 +#else 799 +#error "buffer size for readdir_r cannot be determined" 800 +#endif 801 + name_end = (size_t)offsetof(struct _tinydir_dirent, d_name) + name_max + 1; 802 + return (name_end > sizeof(struct _tinydir_dirent) ? 803 + name_end : sizeof(struct _tinydir_dirent)); 804 +} 805 +#endif 806 +#endif 807 + 808 +#ifdef __cplusplus 809 +} 810 +#endif 811 + 812 +# if defined (_MSC_VER) 813 +# pragma warning(pop) 814 +# endif 815 + 816 +#endif
compat/zlib/win32/zdll.lib became a regular file.
cannot compute difference between binary files
Changes to doc/AddErrInfo.3.
54 54 this points to the first byte of an array of \fIlength\fR bytes 55 55 containing a string to append to the \fB\-errorinfo\fR return option. 56 56 This byte array may contain embedded null bytes 57 57 unless \fIlength\fR is negative. 58 58 .AP Tcl_Obj *objPtr in 59 59 A message to be appended to the \fB\-errorinfo\fR return option 60 60 in the form of a Tcl_Obj value. 61 -.AP int length in 61 +.AP size_t length in 62 62 The number of bytes to copy from \fImessage\fR when 63 63 appending to the \fB\-errorinfo\fR return option. 64 -If negative, all bytes up to the first null byte are used. 64 +If TCL_AUTO_LENGTH, all bytes up to the first null byte are used. 65 65 .AP Tcl_Obj *errorObjPtr in 66 66 The \fB\-errorcode\fR return option will be set to this value. 67 67 .AP char *element in 68 68 String to record as one element of the \fB\-errorcode\fR return option. 69 69 Last \fIelement\fR argument must be NULL. 70 70 .AP va_list argList in 71 71 An argument list which must have been initialized using
Changes to doc/Alloc.3.
4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 7 .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" 8 8 .so man.macros 9 9 .BS 10 10 .SH NAME 11 -Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory 11 +Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- allocate or free heap memory 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 16 char * 17 17 \fBTcl_Alloc\fR(\fIsize\fR) 18 18 .sp 19 19 void 20 20 \fBTcl_Free\fR(\fIptr\fR) 21 21 .sp 22 -char * 22 +void * 23 23 \fBTcl_Realloc\fR(\fIptr, size\fR) 24 24 .sp 25 -char * 25 +void * 26 26 \fBTcl_AttemptAlloc\fR(\fIsize\fR) 27 27 .sp 28 -char * 28 +void * 29 29 \fBTcl_AttemptRealloc\fR(\fIptr, size\fR) 30 -.sp 31 -char * 32 -\fBckalloc\fR(\fIsize\fR) 33 -.sp 34 -void 35 -\fBckfree\fR(\fIptr\fR) 36 -.sp 37 -char * 38 -\fBckrealloc\fR(\fIptr, size\fR) 39 -.sp 40 -char * 41 -\fBattemptckalloc\fR(\fIsize\fR) 42 -.sp 43 -char * 44 -\fBattemptckrealloc\fR(\fIptr, size\fR) 45 30 .SH ARGUMENTS 46 31 .AS char *size 47 32 .AP "unsigned int" size in 48 33 Size in bytes of the memory block to allocate. 49 34 .AP char *ptr in 50 35 Pointer to memory block to free or realloc. 51 36 .BE ................................................................................ 75 60 function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that 76 61 \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl 77 62 interpreter to \fBpanic\fR if the memory allocation fails. If the 78 63 allocation fails, these functions will return NULL. Note that on some 79 64 platforms, but not all, attempting to allocate a zero-sized block of 80 65 memory will also cause these functions to return NULL. 81 66 .PP 82 -The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR, 83 -\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented 84 -as macros. Normally, they are synonyms for the corresponding 85 -procedures documented on this page. When Tcl and all modules 86 -calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however, 87 -these macros are redefined to be special debugging versions 88 -of these procedures. To support Tcl's memory debugging within a 89 -module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc. 67 +When a module or Tcl itself is compiled with \fBTCL_MEM_DEBUG\fR defined, 68 +the procedures \fBTcl_Alloc\fR, \fBTcl_Free\fR, \fBTcl_Realloc\fR, 69 +\fBTcl_AttemptAlloc\fR, and \fBTcl_AttempRealloc\fR are implemented 70 +as macros, redefined to be special debugging versions of these procedures. 90 71 91 72 .SH KEYWORDS 92 73 alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG
Changes to doc/AssocData.3.
9 9 .BS 10 10 .SH NAME 11 11 Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 -ClientData 16 +void * 17 17 \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR) 18 18 .sp 19 19 \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR) 20 20 .sp 21 21 \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR) 22 22 .SH ARGUMENTS 23 23 .AS Tcl_InterpDeleteProc **delProcPtr ................................................................................ 27 27 Key for association with which to store data or from which to delete or 28 28 retrieve data. Typically the module prefix for a package. 29 29 .AP Tcl_InterpDeleteProc *delProc in 30 30 Procedure to call when \fIinterp\fR is deleted. 31 31 .AP Tcl_InterpDeleteProc **delProcPtr in 32 32 Pointer to location in which to store address of current deletion procedure 33 33 for association. Ignored if NULL. 34 -.AP ClientData clientData in 34 +.AP void *clientData in 35 35 Arbitrary one-word value associated with the given key in this 36 36 interpreter. This data is owned by the caller. 37 37 .BE 38 38 39 39 .SH DESCRIPTION 40 40 .PP 41 41 These procedures allow extensions to associate their own data with ................................................................................ 60 60 If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a 61 61 procedure to invoke if the interpreter is deleted before the association 62 62 is deleted. \fIDeleteProc\fR should have arguments and result that match 63 63 the type \fBTcl_InterpDeleteProc\fR: 64 64 .PP 65 65 .CS 66 66 typedef void \fBTcl_InterpDeleteProc\fR( 67 - ClientData \fIclientData\fR, 67 + void *\fIclientData\fR, 68 68 Tcl_Interp *\fIinterp\fR); 69 69 .CE 70 70 .PP 71 71 When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR 72 72 arguments will be the same as the corresponding arguments passed to 73 73 \fBTcl_SetAssocData\fR. 74 74 The deletion procedure will \fInot\fR be invoked if the association
Changes to doc/Async.3.
26 26 .sp 27 27 int 28 28 \fBTcl_AsyncReady\fR() 29 29 .SH ARGUMENTS 30 30 .AS Tcl_AsyncHandler clientData 31 31 .AP Tcl_AsyncProc *proc in 32 32 Procedure to invoke to handle an asynchronous event. 33 -.AP ClientData clientData in 33 +.AP void *clientData in 34 34 One-word value to pass to \fIproc\fR. 35 35 .AP Tcl_AsyncHandler async in 36 36 Token for asynchronous event handler. 37 37 .AP Tcl_Interp *interp in 38 38 Tcl interpreter in which command was being evaluated when handler was 39 39 invoked, or NULL if handler was invoked when there was no interpreter 40 40 active. ................................................................................ 80 80 the world is in a safe state, and \fIproc\fR can then carry out 81 81 the actions associated with the asynchronous event. 82 82 \fIProc\fR should have arguments and result that match the 83 83 type \fBTcl_AsyncProc\fR: 84 84 .PP 85 85 .CS 86 86 typedef int \fBTcl_AsyncProc\fR( 87 - ClientData \fIclientData\fR, 87 + void *\fIclientData\fR, 88 88 Tcl_Interp *\fIinterp\fR, 89 89 int \fIcode\fR); 90 90 .CE 91 91 .PP 92 92 The \fIclientData\fR will be the same as the \fIclientData\fR 93 93 argument passed to \fBTcl_AsyncCreate\fR when the handler was 94 94 created.
Changes to doc/ByteArrObj.3.
25 25 unsigned char * 26 26 \fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) 27 27 .SH ARGUMENTS 28 28 .AS "const unsigned char" *lengthPtr in/out 29 29 .AP "const unsigned char" *bytes in 30 30 The array of bytes used to initialize or set a byte-array value. May be NULL 31 31 even if \fIlength\fR is non-zero. 32 -.AP int length in 33 -The length of the array of bytes. It must be >= 0. 32 +.AP size_t length in 33 +The length of the array of bytes. 34 34 .AP Tcl_Obj *objPtr in/out 35 35 For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to 36 36 byte-array type. For \fBTcl_GetByteArrayFromObj\fR and 37 37 \fBTcl_SetByteArrayLength\fR, this points to the value from which to get 38 38 the byte-array value; if \fIobjPtr\fR does not already point to a byte-array 39 39 value, it will be converted to one. 40 40 .AP int *lengthPtr out
Changes to doc/CallDel.3.
19 19 \fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) 20 20 .SH ARGUMENTS 21 21 .AS Tcl_InterpDeleteProc clientData 22 22 .AP Tcl_Interp *interp in 23 23 Interpreter with which to associated callback. 24 24 .AP Tcl_InterpDeleteProc *proc in 25 25 Procedure to call when \fIinterp\fR is deleted. 26 -.AP ClientData clientData in 26 +.AP void *clientData in 27 27 Arbitrary one-word value to pass to \fIproc\fR. 28 28 .BE 29 29 .SH DESCRIPTION 30 30 .PP 31 31 \fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by 32 32 \fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future 33 33 time. \fIProc\fR will be invoked just before the interpreter ................................................................................ 34 34 is deleted, but the interpreter will still be valid at the 35 35 time of the call. 36 36 \fIProc\fR should have arguments and result that match the 37 37 type \fBTcl_InterpDeleteProc\fR: 38 38 .PP 39 39 .CS 40 40 typedef void \fBTcl_InterpDeleteProc\fR( 41 - ClientData \fIclientData\fR, 41 + void *\fIclientData\fR, 42 42 Tcl_Interp *\fIinterp\fR); 43 43 .CE 44 44 .PP 45 45 The \fIclientData\fR and \fIinterp\fR parameters are 46 46 copies of the \fIclientData\fR and \fIinterp\fR arguments given 47 47 to \fBTcl_CallWhenDeleted\fR. 48 48 Typically, \fIclientData\fR points to an application-specific
Changes to doc/Cancel.3.
26 26 not NULL, this object will have its reference count decremented before 27 27 \fBTcl_CancelEval\fR returns. 28 28 .AP int flags in 29 29 ORed combination of flag bits that specify additional options. 30 30 For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently 31 31 supported. For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and 32 32 \fBTCL_CANCEL_UNWIND\fR are currently supported. 33 -.AP ClientData clientData in 33 +.AP void *clientData in 34 34 Currently reserved for future use. 35 35 It should be set to NULL. 36 36 .BE 37 37 .SH DESCRIPTION 38 38 .PP 39 39 \fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after 40 40 the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be
Changes to doc/ChnlStack.3.
28 28 .sp 29 29 .SH ARGUMENTS 30 30 .AS Tcl_ChannelType clientData 31 31 .AP Tcl_Interp *interp in 32 32 Interpreter for error reporting. 33 33 .AP "const Tcl_ChannelType" *typePtr in 34 34 The new channel I/O procedures to use for \fIchannel\fR. 35 -.AP ClientData clientData in 35 +.AP void *clientData in 36 36 Arbitrary one-word value to pass to channel I/O procedures. 37 37 .AP int mask in 38 38 Conditions under which \fIchannel\fR will be used: OR-ed combination of 39 39 \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. 40 40 This can be a subset of the operations currently allowed on \fIchannel\fR. 41 41 .AP Tcl_Channel channel in 42 42 An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.
Changes to doc/Class.3.
37 37 .sp 38 38 Tcl_Object 39 39 \fBTcl_CopyObjectInstance\fR(\fIinterp, object, name, nsName\fR) 40 40 .sp 41 41 int 42 42 \fBTcl_ObjectDeleted\fR(\fIobject\fR) 43 43 .sp 44 -ClientData 44 +void * 45 45 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR) 46 46 .sp 47 47 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR) 48 48 .sp 49 -ClientData 49 +void * 50 50 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR) 51 51 .sp 52 52 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR) 53 53 .sp 54 54 Tcl_ObjectMapMethodNameProc 55 55 \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR) 56 56 .sp 57 57 \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR) 58 58 .SH ARGUMENTS 59 -.AS ClientData metadata in/out 59 +.AS void *metadata in/out 60 60 .AP Tcl_Interp *interp in/out 61 61 Interpreter providing the context for looking up or creating an object, and 62 62 into whose result error messages will be written on failure. 63 63 .AP Tcl_Obj *objPtr in 64 64 The name of the object to look up. 65 65 .AP Tcl_Object object in 66 66 Reference to the object to operate upon. ................................................................................ 79 79 The arguments to the command to create the instance of the class. 80 80 .AP int skip in 81 81 The number of arguments at the start of the argument array, \fIobjv\fR, that 82 82 are not arguments to any constructors. 83 83 .AP Tcl_ObjectMetadataType *metaTypePtr in 84 84 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or 85 85 retrieved with \fBTcl_ClassGetMetadata\fR. 86 -.AP ClientData metadata in 86 +.AP void *metadata in 87 87 An item of metadata to attach to the class, or NULL to remove the metadata 88 88 associated with a particular \fImetaTypePtr\fR. 89 89 .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in 90 90 A pointer to a function to call to adjust the mapping of objects and method 91 91 names to implementations, or NULL when no such mapping is required. 92 92 .BE 93 93 .SH DESCRIPTION ................................................................................ 167 167 .SS "TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE" 168 168 .PP 169 169 Functions matching this signature are used to delete metadata associated with 170 170 a class or object. 171 171 .PP 172 172 .CS 173 173 typedef void \fBTcl_ObjectMetadataDeleteProc\fR( 174 - ClientData \fImetadata\fR); 174 + void *\fImetadata\fR); 175 175 .CE 176 176 .PP 177 177 The \fImetadata\fR argument gives the address of the metadata to be 178 178 deleted. 179 179 .SS "TCL_CLONEPROC FUNCTION SIGNATURE" 180 180 .PP 181 181 Functions matching this signature are used to create copies of metadata 182 182 associated with a class or object. 183 183 .PP 184 184 .CS 185 185 typedef int \fBTcl_CloneProc\fR( 186 186 Tcl_Interp *\fIinterp\fR, 187 - ClientData \fIsrcMetadata\fR, 188 - ClientData *\fIdstMetadataPtr\fR); 187 + void *\fIsrcMetadata\fR, 188 + void **\fIdstMetadataPtr\fR); 189 189 .CE 190 190 .PP 191 191 The \fIinterp\fR argument gives a place to write an error message when the 192 192 attempt to clone the object is to fail, in which case the clone procedure must 193 193 also return TCL_ERROR; it should return TCL_OK otherwise. 194 194 The \fIsrcMetadata\fR argument gives the address of the metadata to be cloned, 195 195 and the cloned metadata should be written into the variable pointed to by
Changes to doc/CrtChannel.3.
13 13 .SH SYNOPSIS 14 14 .nf 15 15 \fB#include <tcl.h>\fR 16 16 .sp 17 17 Tcl_Channel 18 18 \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR) 19 19 .sp 20 -ClientData 20 +void * 21 21 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) 22 22 .sp 23 23 const Tcl_ChannelType * 24 24 \fBTcl_GetChannelType\fR(\fIchannel\fR) 25 25 .sp 26 26 const char * 27 27 \fBTcl_GetChannelName\fR(\fIchannel\fR) ................................................................................ 124 124 can be called to perform I/O and other functions on the channel. 125 125 .AP "const char" *channelName in 126 126 The name of this channel, such as \fBfile3\fR; must not be in use 127 127 by any other channel. Can be NULL, in which case the channel is 128 128 created without a name. If the created channel is assigned to one 129 129 of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR), 130 130 the assigned channel name will be the name of the standard channel. 131 -.AP ClientData instanceData in 131 +.AP void *instanceData in 132 132 Arbitrary one-word value to be associated with this channel. This 133 133 value is passed to procedures in \fItypePtr\fR when they are invoked. 134 134 .AP int mask in 135 135 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate 136 136 whether a channel is readable and writable. 137 137 .AP Tcl_Channel channel in 138 138 The channel to operate on. 139 139 .AP int direction in 140 140 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR 141 141 means the output handle is wanted. 142 -.AP ClientData *handlePtr out 142 +.AP void **handlePtr out 143 143 Points to the location where the desired OS-specific handle should be 144 144 stored. 145 145 .AP int size in 146 146 The size, in bytes, of buffers to allocate in this channel. 147 147 .AP int mask in 148 148 An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR 149 149 and \fBTCL_EXCEPTION\fR that indicates events that have occurred on ................................................................................ 395 395 .PP 396 396 The \fIblockModeProc\fR field contains the address of a function called by 397 397 the generic layer to set blocking and nonblocking mode on the device. 398 398 \fIBlockModeProc\fR should match the following prototype: 399 399 .PP 400 400 .CS 401 401 typedef int \fBTcl_DriverBlockModeProc\fR( 402 - ClientData \fIinstanceData\fR, 402 + void *\fIinstanceData\fR, 403 403 int \fImode\fR); 404 404 .CE 405 405 .PP 406 406 The \fIinstanceData\fR is the same as the value passed to 407 407 \fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR 408 408 argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to 409 409 set the device into blocking or nonblocking mode. The function should ................................................................................ 430 430 .PP 431 431 The \fIcloseProc\fR field contains the address of a function called by the 432 432 generic layer to clean up driver-related information when the channel is 433 433 closed. \fICloseProc\fR must match the following prototype: 434 434 .PP 435 435 .CS 436 436 typedef int \fBTcl_DriverCloseProc\fR( 437 - ClientData \fIinstanceData\fR, 437 + void *\fIinstanceData\fR, 438 438 Tcl_Interp *\fIinterp\fR); 439 439 .CE 440 440 .PP 441 441 The \fIinstanceData\fR argument is the same as the value provided to 442 442 \fBTcl_CreateChannel\fR when the channel was created. The function should 443 443 release any storage maintained by the channel driver for this channel, and 444 444 close the input and output devices encapsulated by this channel. All queued ................................................................................ 452 452 Alternatively, channels that support closing the read and write sides 453 453 independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set 454 454 \fIclose2Proc\fR to the address of a function that matches the 455 455 following prototype: 456 456 .PP 457 457 .CS 458 458 typedef int \fBTcl_DriverClose2Proc\fR( 459 - ClientData \fIinstanceData\fR, 459 + void *\fIinstanceData\fR, 460 460 Tcl_Interp *\fIinterp\fR, 461 461 int \fIflags\fR); 462 462 .CE 463 463 .PP 464 464 The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed 465 465 combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to 466 466 indicate that the driver should close the read and/or write side of ................................................................................ 483 483 .PP 484 484 The \fIinputProc\fR field contains the address of a function called by the 485 485 generic layer to read data from the file or device and store it in an 486 486 internal buffer. \fIInputProc\fR must match the following prototype: 487 487 .PP 488 488 .CS 489 489 typedef int \fBTcl_DriverInputProc\fR( 490 - ClientData \fIinstanceData\fR, 490 + void *\fIinstanceData\fR, 491 491 char *\fIbuf\fR, 492 492 int \fIbufSize\fR, 493 493 int *\fIerrorCodePtr\fR); 494 494 .CE 495 495 .PP 496 496 \fIInstanceData\fR is the same as the value passed to 497 497 \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR ................................................................................ 527 527 .PP 528 528 The \fIoutputProc\fR field contains the address of a function called by the 529 529 generic layer to transfer data from an internal buffer to the output device. 530 530 \fIOutputProc\fR must match the following prototype: 531 531 .PP 532 532 .CS 533 533 typedef int \fBTcl_DriverOutputProc\fR( 534 - ClientData \fIinstanceData\fR, 534 + void *\fIinstanceData\fR, 535 535 const char *\fIbuf\fR, 536 536 int \fItoWrite\fR, 537 537 int *\fIerrorCodePtr\fR); 538 538 .CE 539 539 .PP 540 540 \fIInstanceData\fR is the same as the value passed to 541 541 \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR ................................................................................ 566 566 The \fIseekProc\fR field contains the address of a function called by the 567 567 generic layer to move the access point at which subsequent input or output 568 568 operations will be applied. \fISeekProc\fR must match the following 569 569 prototype: 570 570 .PP 571 571 .CS 572 572 typedef int \fBTcl_DriverSeekProc\fR( 573 - ClientData \fIinstanceData\fR, 573 + void *\fIinstanceData\fR, 574 574 long \fIoffset\fR, 575 575 int \fIseekMode\fR, 576 576 int *\fIerrorCodePtr\fR); 577 577 .CE 578 578 .PP 579 579 The \fIinstanceData\fR argument is the same as the value given to 580 580 \fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and ................................................................................ 596 596 within files larger than 2GB. The \fIwideSeekProc\fR will be called 597 597 in preference to the \fIseekProc\fR, but both must be defined if the 598 598 \fIwideSeekProc\fR is defined. \fIWideSeekProc\fR must match the 599 599 following prototype: 600 600 .PP 601 601 .CS 602 602 typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR( 603 - ClientData \fIinstanceData\fR, 603 + void *\fIinstanceData\fR, 604 604 Tcl_WideInt \fIoffset\fR, 605 605 int \fIseekMode\fR, 606 606 int *\fIerrorCodePtr\fR); 607 607 .CE 608 608 .PP 609 609 The arguments and return values mean the same thing as with 610 610 \fIseekProc\fR above, except that the type of offsets and the return ................................................................................ 618 618 .PP 619 619 The \fIsetOptionProc\fR field contains the address of a function called by 620 620 the generic layer to set a channel type specific option on a channel. 621 621 \fIsetOptionProc\fR must match the following prototype: 622 622 .PP 623 623 .CS 624 624 typedef int \fBTcl_DriverSetOptionProc\fR( 625 - ClientData \fIinstanceData\fR, 625 + void *\fIinstanceData\fR, 626 626 Tcl_Interp *\fIinterp\fR, 627 627 const char *\fIoptionName\fR, 628 628 const char *\fInewValue\fR); 629 629 .CE 630 630 .PP 631 631 \fIoptionName\fR is the name of an option to set, and \fInewValue\fR is 632 632 the new value for that option, as a string. The \fIinstanceData\fR is the ................................................................................ 659 659 .PP 660 660 The \fIgetOptionProc\fR field contains the address of a function called by 661 661 the generic layer to get the value of a channel type specific option on a 662 662 channel. \fIgetOptionProc\fR must match the following prototype: 663 663 .PP 664 664 .CS 665 665 typedef int \fBTcl_DriverGetOptionProc\fR( 666 - ClientData \fIinstanceData\fR, 666 + void *\fIinstanceData\fR, 667 667 Tcl_Interp *\fIinterp\fR, 668 668 const char *\fIoptionName\fR, 669 669 Tcl_DString *\fIoptionValue\fR); 670 670 .CE 671 671 .PP 672 672 \fIOptionName\fR is the name of an option supported by this type of 673 673 channel. If the option name is not NULL, the function stores its current ................................................................................ 697 697 The \fIwatchProc\fR field contains the address of a function called 698 698 by the generic layer to initialize the event notification mechanism to 699 699 notice events of interest on this channel. 700 700 \fIWatchProc\fR should match the following prototype: 701 701 .PP 702 702 .CS 703 703 typedef void \fBTcl_DriverWatchProc\fR( 704 - ClientData \fIinstanceData\fR, 704 + void *\fIinstanceData\fR, 705 705 int \fImask\fR); 706 706 .CE 707 707 .PP 708 708 The \fIinstanceData\fR is the same as the value passed to 709 709 \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR 710 710 argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR 711 711 and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in ................................................................................ 728 728 .PP 729 729 The \fIgetHandleProc\fR field contains the address of a function called by 730 730 the generic layer to retrieve a device-specific handle from the channel. 731 731 \fIGetHandleProc\fR should match the following prototype: 732 732 .PP 733 733 .CS 734 734 typedef int \fBTcl_DriverGetHandleProc\fR( 735 - ClientData \fIinstanceData\fR, 735 + void *\fIinstanceData\fR, 736 736 int \fIdirection\fR, 737 - ClientData *\fIhandlePtr\fR); 737 + void **\fIhandlePtr\fR); 738 738 .CE 739 739 .PP 740 740 \fIInstanceData\fR is the same as the value passed to 741 741 \fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR 742 742 argument is either \fBTCL_READABLE\fR to retrieve the handle used 743 743 for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for 744 744 output. ................................................................................ 757 757 .PP 758 758 The \fIflushProc\fR field is currently reserved for future use. 759 759 It should be set to NULL. 760 760 \fIFlushProc\fR should match the following prototype: 761 761 .PP 762 762 .CS 763 763 typedef int \fBTcl_DriverFlushProc\fR( 764 - ClientData \fIinstanceData\fR); 764 + void *\fIinstanceData\fR); 765 765 .CE 766 766 .PP 767 767 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns 768 768 a pointer to the function. 769 769 .SS HANDLERPROC 770 770 .PP 771 771 The \fIhandlerProc\fR field contains the address of a function called by ................................................................................ 772 772 the generic layer to notify the channel that an event occurred. It should 773 773 be defined for stacked channel drivers that wish to be notified of events 774 774 that occur on the underlying (stacked) channel. 775 775 \fIHandlerProc\fR should match the following prototype: 776 776 .PP 777 777 .CS 778 778 typedef int \fBTcl_DriverHandlerProc\fR( 779 - ClientData \fIinstanceData\fR, 779 + void *\fIinstanceData\fR, 780 780 int \fIinterestMask\fR); 781 781 .CE 782 782 .PP 783 783 \fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR 784 784 when this channel was created. The \fIinterestMask\fR is an OR-ed 785 785 combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what 786 786 type of event occurred on this channel. ................................................................................ 801 801 The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the 802 802 driver that it should update or initialize any thread-specific data it 803 803 might be maintaining using the calling thread as the associate. See 804 804 \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail. 805 805 .PP 806 806 .CS 807 807 typedef void \fBTcl_DriverThreadActionProc\fR( 808 - ClientData \fIinstanceData\fR, 808 + void *\fIinstanceData\fR, 809 809 int \fIaction\fR); 810 810 .CE 811 811 .PP 812 812 \fIInstanceData\fR is the same as the value passed to 813 813 \fBTcl_CreateChannel\fR when this channel was created. 814 814 .PP 815 815 These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR, ................................................................................ 818 818 .PP 819 819 The \fItruncateProc\fR field contains the address of the function 820 820 called by the generic layer when a channel is truncated to some 821 821 length. It can be NULL. 822 822 .PP 823 823 .CS 824 824 typedef int \fBTcl_DriverTruncateProc\fR( 825 - ClientData \fIinstanceData\fR, 825 + void *\fIinstanceData\fR, 826 826 Tcl_WideInt \fIlength\fR); 827 827 .CE 828 828 .PP 829 829 \fIInstanceData\fR is the same as the value passed to 830 830 \fBTcl_CreateChannel\fR when this channel was created, and 831 831 \fIlength\fR is the new length of the underlying file, which should 832 832 not be negative. The result should be 0 on success or an errno code
Changes to doc/CrtChnlHdlr.3.
28 28 .AP int mask in 29 29 Conditions under which \fIproc\fR should be called: OR-ed combination of 30 30 \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify 31 31 a zero value to temporarily disable an existing handler. 32 32 .AP Tcl_FileProc *proc in 33 33 Procedure to invoke whenever the channel indicated by \fIchannel\fR meets 34 34 the conditions specified by \fImask\fR. 35 -.AP ClientData clientData in 35 +.AP void *clientData in 36 36 Arbitrary one-word value to pass to \fIproc\fR. 37 37 .BE 38 38 .SH DESCRIPTION 39 39 .PP 40 40 \fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the 41 41 future whenever input or output becomes possible on the channel identified 42 42 by \fIchannel\fR, or whenever an exceptional condition exists for ................................................................................ 44 44 invoked are specified by the \fImask\fR argument. 45 45 See the manual entry for \fBfileevent\fR for a precise description of 46 46 what it means for a channel to be readable or writable. 47 47 \fIProc\fR must conform to the following prototype: 48 48 .PP 49 49 .CS 50 50 typedef void \fBTcl_ChannelProc\fR( 51 - ClientData \fIclientData\fR, 51 + void *\fIclientData\fR, 52 52 int \fImask\fR); 53 53 .CE 54 54 .PP 55 55 The \fIclientData\fR argument is the same as the value passed to 56 56 \fBTcl_CreateChannelHandler\fR when the handler was created. Typically, 57 57 \fIclientData\fR points to a data structure containing application-specific 58 58 information about the channel. \fIMask\fR is an integer mask indicating
Changes to doc/CrtCloseHdlr.3.
22 22 .sp 23 23 .SH ARGUMENTS 24 24 .AS Tcl_CloseProc clientData 25 25 .AP Tcl_Channel channel in 26 26 The channel for which to create or delete a close callback. 27 27 .AP Tcl_CloseProc *proc in 28 28 The procedure to call as the callback. 29 -.AP ClientData clientData in 29 +.AP void *clientData in 30 30 Arbitrary one-word value to pass to \fIproc\fR. 31 31 .BE 32 32 .SH DESCRIPTION 33 33 .PP 34 34 \fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when 35 35 \fIchannel\fR is closed with \fBTcl_Close\fR or 36 36 \fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command. 37 37 \fIProc\fR should match the following prototype: 38 38 .PP 39 39 .CS 40 40 typedef void \fBTcl_CloseProc\fR( 41 - ClientData \fIclientData\fR); 41 + void *\fIclientData\fR); 42 42 .CE 43 43 .PP 44 44 The \fIclientData\fR is the same as the value provided in the call to 45 45 \fBTcl_CreateCloseHandler\fR. 46 46 .PP 47 47 \fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR. 48 48 The \fIproc\fR and \fIclientData\fR identify which close callback to
Changes to doc/CrtCommand.3.
21 21 .AP Tcl_Interp *interp in 22 22 Interpreter in which to create new command. 23 23 .AP "const char" *cmdName in 24 24 Name of command. 25 25 .AP Tcl_CmdProc *proc in 26 26 Implementation of new command: \fIproc\fR will be called whenever 27 27 \fIcmdName\fR is invoked as a command. 28 -.AP ClientData clientData in 28 +.AP voie *clientData in 29 29 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR. 30 30 .AP Tcl_CmdDeleteProc *deleteProc in 31 31 Procedure to call before \fIcmdName\fR is deleted from the interpreter; 32 32 allows for command-specific cleanup. If NULL, then no procedure is 33 33 called before the command is deleted. 34 34 .BE 35 35 .SH DESCRIPTION ................................................................................ 71 71 the process of being deleted, then it does not create a new command 72 72 and it returns NULL. 73 73 \fIProc\fR should have arguments and result that match the type 74 74 \fBTcl_CmdProc\fR: 75 75 .PP 76 76 .CS 77 77 typedef int \fBTcl_CmdProc\fR( 78 - ClientData \fIclientData\fR, 78 + void *\fIclientData\fR, 79 79 Tcl_Interp *\fIinterp\fR, 80 80 int \fIargc\fR, 81 81 const char *\fIargv\fR[]); 82 82 .CE 83 83 .PP 84 84 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR 85 85 parameters will be copies of the \fIclientData\fR and \fIinterp\fR ................................................................................ 127 127 \fIDeleteProc\fR is invoked before the command is deleted, and gives the 128 128 application an opportunity to release any structures associated 129 129 with the command. \fIDeleteProc\fR should have arguments and 130 130 result that match the type \fBTcl_CmdDeleteProc\fR: 131 131 .PP 132 132 .CS 133 133 typedef void \fBTcl_CmdDeleteProc\fR( 134 - ClientData \fIclientData\fR); 134 + void *\fIclientData\fR); 135 135 .CE 136 136 .PP 137 137 The \fIclientData\fR argument will be the same as the \fIclientData\fR 138 138 argument passed to \fBTcl_CreateCommand\fR. 139 139 .SH "SEE ALSO" 140 140 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, 141 141 Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult 142 142 .SH KEYWORDS 143 143 bind, command, create, delete, interpreter, namespace
Changes to doc/CrtFileHdlr.3.
25 25 Conditions under which \fIproc\fR should be called: 26 26 OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, 27 27 and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable 28 28 a handler. 29 29 .AP Tcl_FileProc *proc in 30 30 Procedure to invoke whenever the file or device indicated 31 31 by \fIfile\fR meets the conditions specified by \fImask\fR. 32 -.AP ClientData clientData in 32 +.AP void *clientData in 33 33 Arbitrary one-word value to pass to \fIproc\fR. 34 34 .BE 35 35 .SH DESCRIPTION 36 36 .PP 37 37 \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be 38 38 invoked in the future whenever I/O becomes possible on a file 39 39 or an exceptional condition exists for the file. The file ................................................................................ 47 47 as \fBvwait\fR. 48 48 .PP 49 49 \fIProc\fR should have arguments and result that match the 50 50 type \fBTcl_FileProc\fR: 51 51 .PP 52 52 .CS 53 53 typedef void \fBTcl_FileProc\fR( 54 - ClientData \fIclientData\fR, 54 + void *\fIclientData\fR, 55 55 int \fImask\fR); 56 56 .CE 57 57 .PP 58 58 The \fIclientData\fR parameter to \fIproc\fR is a copy 59 59 of the \fIclientData\fR 60 60 argument given to \fBTcl_CreateFileHandler\fR when the callback 61 61 was created. Typically, \fIclientData\fR points to a data
Changes to doc/CrtObjCmd.3.
4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 7 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" 8 8 .so man.macros 9 9 .BS 10 10 .SH NAME 11 -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C 11 +Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 16 Tcl_Command 17 17 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR) 18 18 .sp ................................................................................ 38 38 \fBTcl_GetCommandName\fR(\fIinterp, token\fR) 39 39 .sp 40 40 void 41 41 \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR) 42 42 .sp 43 43 Tcl_Command 44 44 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR) 45 +.sp 46 +.VS "info cmdtype feature" 47 +void 48 +\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR) 49 +.sp 50 +const char * 51 +\fBTcl_GetCommandTypeName\fR(\fItoken\fR) 52 +.VE "info cmdtype feature" 45 53 .SH ARGUMENTS 46 54 .AS Tcl_CmdDeleteProc *deleteProc in/out 47 55 .AP Tcl_Interp *interp in 48 56 Interpreter in which to create a new command or that contains a command. 49 57 .AP char *cmdName in 50 58 Name of command. 51 59 .AP Tcl_ObjCmdProc *proc in 52 60 Implementation of the new command: \fIproc\fR will be called whenever 53 61 \fIcmdName\fR is invoked as a command. 54 -.AP ClientData clientData in 62 +.AP void *clientData in 55 63 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR. 56 64 .AP Tcl_CmdDeleteProc *deleteProc in 57 65 Procedure to call before \fIcmdName\fR is deleted from the interpreter; 58 66 allows for command-specific cleanup. If NULL, then no procedure is 59 67 called before the command is deleted. 60 68 .AP Tcl_Command token in 61 69 Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR. 62 70 The command must not have been deleted. 63 71 .AP Tcl_CmdInfo *infoPtr in/out 64 72 Pointer to structure containing various information about a 65 73 Tcl command. 66 74 .AP Tcl_Obj *objPtr in 67 75 Value containing the name of a Tcl command. 76 +.AP "const char" *typeName in 77 +Indicates the name of the type of command implementation associated 78 +with a particular \fIproc\fR, or NULL to break the association. 68 79 .BE 69 80 .SH DESCRIPTION 70 81 .PP 71 82 \fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR 72 83 and associates it with procedure \fIproc\fR 73 84 such that whenever \fIname\fR is 74 85 invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR) ................................................................................ 87 98 the process of being deleted, then it does not create a new command 88 99 and it returns NULL. 89 100 \fIproc\fR should have arguments and result that match the type 90 101 \fBTcl_ObjCmdProc\fR: 91 102 .PP 92 103 .CS 93 104 typedef int \fBTcl_ObjCmdProc\fR( 94 - ClientData \fIclientData\fR, 105 + void *\fIclientData\fR, 95 106 Tcl_Interp *\fIinterp\fR, 96 107 int \fIobjc\fR, 97 108 Tcl_Obj *const \fIobjv\fR[]); 98 109 .CE 99 110 .PP 100 111 When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters 101 112 will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to ................................................................................ 160 171 \fIDeleteProc\fR is invoked before the command is deleted, and gives the 161 172 application an opportunity to release any structures associated 162 173 with the command. \fIDeleteProc\fR should have arguments and 163 174 result that match the type \fBTcl_CmdDeleteProc\fR: 164 175 .PP 165 176 .CS 166 177 typedef void \fBTcl_CmdDeleteProc\fR( 167 - ClientData \fIclientData\fR); 178 + void *\fIclientData\fR); 168 179 .CE 169 180 .PP 170 181 The \fIclientData\fR argument will be the same as the \fIclientData\fR 171 182 argument passed to \fBTcl_CreateObjCommand\fR. 172 183 .PP 173 184 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter. 174 185 Once the call completes, attempts to invoke \fIcmdName\fR in ................................................................................ 202 213 pointed to by \fIinfoPtr\fR and returns 1. 203 214 A \fBTcl_CmdInfo\fR structure has the following fields: 204 215 .PP 205 216 .CS 206 217 typedef struct Tcl_CmdInfo { 207 218 int \fIisNativeObjectProc\fR; 208 219 Tcl_ObjCmdProc *\fIobjProc\fR; 209 - ClientData \fIobjClientData\fR; 220 + void *\fIobjClientData\fR; 210 221 Tcl_CmdProc *\fIproc\fR; 211 - ClientData \fIclientData\fR; 222 + void *\fIclientData\fR; 212 223 Tcl_CmdDeleteProc *\fIdeleteProc\fR; 213 - ClientData \fIdeleteData\fR; 224 + void *\fIdeleteData\fR; 214 225 Tcl_Namespace *\fInamespacePtr\fR; 215 226 } \fBTcl_CmdInfo\fR; 216 227 .CE 217 228 .PP 218 229 The \fIisNativeObjectProc\fR field has the value 1 219 230 if \fBTcl_CreateObjCommand\fR was called to register the command; 220 231 it is 0 if only \fBTcl_CreateCommand\fR was called. ................................................................................ 232 243 that implements the command. 233 244 If \fBTcl_CreateCommand\fR was called for this command, 234 245 this is the procedure passed to it; 235 246 otherwise, this is a compatibility procedure 236 247 registered by \fBTcl_CreateObjCommand\fR 237 248 that simply calls the command's 238 249 value-based procedure after converting its string arguments to Tcl values. 239 -The field \fIdeleteData\fR is the ClientData value 250 +The field \fIdeleteData\fR is the clientData value 240 251 to pass to \fIdeleteProc\fR; it is normally the same as 241 252 \fIclientData\fR but may be set independently using the 242 253 \fBTcl_SetCommandInfo\fR procedure. 243 254 The field \fInamespacePtr\fR holds a pointer to the 244 255 Tcl_Namespace that contains the command. 245 256 .PP 246 257 \fBTcl_GetCommandInfoFromToken\fR is identical to 247 258 \fBTcl_GetCommandInfo\fR except that it uses a command token returned 248 259 from \fBTcl_CreateObjCommand\fR in place of the command name. If the 249 260 \fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1 250 261 and fills in the structure designated by \fIinfoPtr\fR. 251 262 .PP 252 263 \fBTcl_SetCommandInfo\fR is used to modify the procedures and 253 -ClientData values associated with a command. 264 +clientData values associated with a command. 254 265 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR. 255 266 \fIcmdName\fR may include \fB::\fR namespace qualifiers 256 267 to identify a command in a particular namespace. 257 268 If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0. 258 269 Otherwise, it copies the information from \fI*infoPtr\fR to 259 270 Tcl's internal structure for the command and returns 1. 260 271 .PP ................................................................................ 262 273 \fBTcl_SetCommandInfo\fR except that it takes a command token as 263 274 returned by \fBTcl_CreateObjCommand\fR instead of the command name. 264 275 If the \fItoken\fR parameter is NULL, it returns 0. Otherwise, it 265 276 copies the information from \fI*infoPtr\fR to Tcl's internal structure 266 277 for the command and returns 1. 267 278 .PP 268 279 Note that \fBTcl_SetCommandInfo\fR and 269 -\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a 280 +\fBTcl_SetCommandInfoFromToken\fR both allow the clientData for a 270 281 command's deletion procedure to be given a different value than the 271 -ClientData for its command procedure. 282 +clientData for its command procedure. 272 283 .PP 273 284 Note that neither \fBTcl_SetCommandInfo\fR nor 274 285 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace. 275 286 Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that. 276 287 .PP 277 288 \fBTcl_GetCommandName\fR provides a mechanism for tracking commands 278 289 that have been renamed. ................................................................................ 292 303 The name, including all namespace prefixes, 293 304 is appended to the value specified by \fIobjPtr\fR. 294 305 .PP 295 306 \fBTcl_GetCommandFromObj\fR returns a token for the command 296 307 specified by the name in a \fBTcl_Obj\fR. 297 308 The command name is resolved relative to the current namespace. 298 309 Returns NULL if the command is not found. 310 +.PP 311 +.VS "info cmdtype feature" 312 +\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the 313 +\fItypeName\fR argument) with a particular implementation function so that it 314 +can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is 315 +called with a command token that information is wanted for and which returns 316 +the name of the type that was registered for the implementation function used 317 +for that command. (The lookup functionality is surfaced virtually directly in Tcl via 318 +\fBinfo cmdtype\fR.) If there is no function registered for a particular 319 +function, the result will be the string literal 320 +.QW \fBnative\fR . 321 +The registration of a name can be undone by registering a mapping to NULL 322 +instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that 323 +string which was registered, and not a copy; use of a compile-time constant 324 +string is \fIstrongly recommended\fR. 325 +.VE "info cmdtype feature" 299 326 .SH "SEE ALSO" 300 327 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) 301 328 .SH KEYWORDS 302 329 bind, command, create, delete, namespace, value
Changes to doc/CrtTimerHdlr.3.
20 20 \fBTcl_DeleteTimerHandler\fR(\fItoken\fR) 21 21 .SH ARGUMENTS 22 22 .AS Tcl_TimerToken milliseconds 23 23 .AP int milliseconds in 24 24 How many milliseconds to wait before invoking \fIproc\fR. 25 25 .AP Tcl_TimerProc *proc in 26 26 Procedure to invoke after \fImilliseconds\fR have elapsed. 27 -.AP ClientData clientData in 27 +.AP void *clientData in 28 28 Arbitrary one-word value to pass to \fIproc\fR. 29 29 .AP Tcl_TimerToken token in 30 30 Token for previously created timer handler (the return value 31 31 from some previous call to \fBTcl_CreateTimerHandler\fR). 32 32 .BE 33 33 .SH DESCRIPTION 34 34 .PP ................................................................................ 47 47 \fIproc\fR, then the call to \fIproc\fR will be delayed. 48 48 .PP 49 49 \fIProc\fR should have arguments and return value that match 50 50 the type \fBTcl_TimerProc\fR: 51 51 .PP 52 52 .CS 53 53 typedef void \fBTcl_TimerProc\fR( 54 - ClientData \fIclientData\fR); 54 + void *\fIclientData\fR); 55 55 .CE 56 56 .PP 57 57 The \fIclientData\fR parameter to \fIproc\fR is a 58 58 copy of the \fIclientData\fR argument given to 59 59 \fBTcl_CreateTimerHandler\fR when the callback 60 60 was created. Typically, \fIclientData\fR points to a data 61 61 structure containing application-specific information about
Changes to doc/CrtTrace.3.
37 37 Flags governing the trace execution. See below for details. 38 38 .AP Tcl_CmdObjTraceProc *objProc in 39 39 Procedure to call for each command that is executed. See below for 40 40 details of the calling sequence. 41 41 .AP Tcl_CmdTraceProc *proc in 42 42 Procedure to call for each command that is executed. See below for 43 43 details on the calling sequence. 44 -.AP ClientData clientData in 44 +.AP void *clientData in 45 45 Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. 46 46 .AP Tcl_CmdObjTraceDeleteProc *deleteProc in 47 47 Procedure to call when the trace is deleted. See below for details of 48 48 the calling sequence. A NULL pointer is permissible and results in no 49 49 callback when the trace is deleted. 50 50 .AP Tcl_Trace trace in 51 51 Token for trace to be removed (return value from previous call ................................................................................ 62 62 interpreter. 63 63 .PP 64 64 \fIobjProc\fR should have arguments and result that match the type, 65 65 \fBTcl_CmdObjTraceProc\fR: 66 66 .PP 67 67 .CS 68 68 typedef int \fBTcl_CmdObjTraceProc\fR( 69 - \fBClientData\fR \fIclientData\fR, 69 + \fBvoid *\fR \fIclientData\fR, 70 70 \fBTcl_Interp\fR* \fIinterp\fR, 71 71 int \fIlevel\fR, 72 72 const char *\fIcommand\fR, 73 73 \fBTcl_Command\fR \fIcommandToken\fR, 74 74 int \fIobjc\fR, 75 75 \fBTcl_Obj\fR *const \fIobjv\fR[]); 76 76 .CE 77 77 .PP 78 78 The \fIclientData\fR and \fIinterp\fR parameters are copies of the 79 79 corresponding arguments given to \fBTcl_CreateTrace\fR. 80 -\fIClientData\fR typically points to an application-specific data 80 +\fIclientData\fR typically points to an application-specific data 81 81 structure that describes what to do when \fIobjProc\fR is invoked. The 82 82 \fIlevel\fR parameter gives the nesting level of the command (1 for 83 83 top-level commands passed to \fBTcl_Eval\fR by the application, 2 for 84 84 the next-level commands passed to \fBTcl_Eval\fR as part of parsing or 85 85 interpreting level-1 commands, and so on). The \fIcommand\fR parameter 86 86 points to a string containing the text of the command, before any 87 87 argument substitution. The \fIcommandToken\fR parameter is a Tcl ................................................................................ 140 140 When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the 141 141 \fIdeleteProc\fR that was passed as a parameter to 142 142 \fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, 143 143 \fBTcl_CmdObjTraceDeleteProc\fR: 144 144 .PP 145 145 .CS 146 146 typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 147 - \fBClientData\fR \fIclientData\fR); 147 + \fBvoid *\fR \fIclientData\fR); 148 148 .CE 149 149 .PP 150 150 The \fIclientData\fR parameter will be the same as the 151 151 \fIclientData\fR parameter that was originally passed to 152 152 \fBTcl_CreateObjTrace\fR. 153 153 .PP 154 154 \fBTcl_CreateTrace\fR is an alternative interface for command tracing, ................................................................................ 156 156 compatibility with code that was developed for older versions of the 157 157 Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except 158 158 that its \fIproc\fR parameter should have arguments and result that 159 159 match the type \fBTcl_CmdTraceProc\fR: 160 160 .PP 161 161 .CS 162 162 typedef void \fBTcl_CmdTraceProc\fR( 163 - ClientData \fIclientData\fR, 163 + void *\fIclientData\fR, 164 164 Tcl_Interp *\fIinterp\fR, 165 165 int \fIlevel\fR, 166 166 char *\fIcommand\fR, 167 167 Tcl_CmdProc *\fIcmdProc\fR, 168 - ClientData \fIcmdClientData\fR, 168 + void *\fIcmdClientData\fR, 169 169 int \fIargc\fR, 170 170 const char *\fIargv\fR[]); 171 171 .CE 172 172 .PP 173 173 The parameters to the \fIproc\fR callback are similar to those of the 174 174 \fIobjProc\fR callback above. The \fIcommandToken\fR is 175 175 replaced with \fIcmdProc\fR, a pointer to the (string-based) command
Changes to doc/DString.3.
22 22 char * 23 23 \fBTcl_DStringAppendElement\fR(\fIdsPtr, element\fR) 24 24 .sp 25 25 \fBTcl_DStringStartSublist\fR(\fIdsPtr\fR) 26 26 .sp 27 27 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR) 28 28 .sp 29 -int 29 +size_t 30 30 \fBTcl_DStringLength\fR(\fIdsPtr\fR) 31 31 .sp 32 32 char * 33 33 \fBTcl_DStringValue\fR(\fIdsPtr\fR) 34 34 .sp 35 35 \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR) 36 36 .sp ................................................................................ 43 43 .AS Tcl_DString newLength in/out 44 44 .AP Tcl_DString *dsPtr in/out 45 45 Pointer to structure that is used to manage a dynamic string. 46 46 .AP "const char" *bytes in 47 47 Pointer to characters to append to dynamic string. 48 48 .AP "const char" *element in 49 49 Pointer to characters to append as list element to dynamic string. 50 -.AP int length in 51 -Number of bytes from \fIbytes\fR to add to dynamic string. If -1, 50 +.AP size_t length in 51 +Number of bytes from \fIbytes\fR to add to dynamic string. If TCL_AUTO_LENGTH, 52 52 add all characters up to null terminating character. 53 -.AP int newLength in 53 +.AP size_t newLength in 54 54 New length for dynamic string, not including null terminating 55 55 character. 56 56 .AP Tcl_Interp *interp in/out 57 57 Interpreter whose result is to be set from or moved to the 58 58 dynamic string. 59 59 .BE 60 60
Changes to doc/DoWhenIdle.3.
17 17 \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) 18 18 .sp 19 19 \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) 20 20 .SH ARGUMENTS 21 21 .AS Tcl_IdleProc clientData 22 22 .AP Tcl_IdleProc *proc in 23 23 Procedure to invoke. 24 -.AP ClientData clientData in 24 +.AP coid *clientData in 25 25 Arbitrary one-word value to pass to \fIproc\fR. 26 26 .BE 27 27 .SH DESCRIPTION 28 28 .PP 29 29 \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked 30 30 when the application becomes idle. The application is 31 31 considered to be idle when \fBTcl_DoOneEvent\fR has been ................................................................................ 39 39 use \fBTcl_DoOneEvent\fR to dispatch events. 40 40 .PP 41 41 \fIProc\fR should have arguments and result that match the 42 42 type \fBTcl_IdleProc\fR: 43 43 .PP 44 44 .CS 45 45 typedef void \fBTcl_IdleProc\fR( 46 - ClientData \fIclientData\fR); 46 + void *\fIclientData\fR); 47 47 .CE 48 48 .PP 49 49 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR 50 50 argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR 51 51 points to a data structure containing application-specific information about 52 52 what \fIproc\fR should do. 53 53 .PP
Changes to doc/DumpActiveMemory.3.
39 39 They are only functional when Tcl has been compiled with 40 40 \fBTCL_MEM_DEBUG\fR defined at compile-time. When \fBTCL_MEM_DEBUG\fR 41 41 is not defined, these functions are all no-ops. 42 42 .PP 43 43 \fBTcl_DumpActiveMemory\fR will output a list of all currently 44 44 allocated memory to the specified file. The information output for 45 45 each allocated block of memory is: starting and ending addresses 46 -(excluding guard zone), size, source file where \fBckalloc\fR was 46 +(excluding guard zone), size, source file where \fBTcl_Alloc\fR was 47 47 called to allocate the block and line number in that file. It is 48 48 especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl 49 49 interpreter has been deleted. 50 50 .PP 51 51 \fBTcl_InitMemory\fR adds the Tcl \fBmemory\fR command to the 52 52 interpreter given by \fIinterp\fR. \fBTcl_InitMemory\fR is called 53 53 by \fBTcl_Main\fR. 54 54 .PP 55 55 \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of 56 56 all currently allocated blocks of memory. Normally validation of a 57 57 block occurs when its freed, unless full validation is enabled, in 58 -which case validation of all blocks occurs when \fBckalloc\fR and 59 -\fBckfree\fR are called. This function forces the validation to occur 58 +which case validation of all blocks occurs when \fBTcl_Alloc\fR and 59 +\fBTcl_Free\fR are called. This function forces the validation to occur 60 60 at any point. 61 61 62 62 .SH "SEE ALSO" 63 63 TCL_MEM_DEBUG, memory 64 64 65 65 .SH KEYWORDS 66 66 memory, debug 67 67 68 68
Changes to doc/Encoding.3.
79 79 .AP "const char" *src in 80 80 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the 81 81 specified encoding that are to be converted to UTF-8. For the 82 82 \fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of 83 83 UTF-8 characters to be converted to the specified encoding. 84 84 .AP "const TCHAR" *tsrc in 85 85 An array of Windows TCHAR characters to convert to UTF-8. 86 -.AP int srcLen in 86 +.AP size_t srcLen in 87 87 Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the 88 88 encoding-specific length of the string is used. 89 89 .AP Tcl_DString *dstPtr out 90 90 Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted 91 91 result will be stored. 92 92 .AP int flags in 93 93 Various flag bits OR-ed together. ................................................................................ 304 304 .PP 305 305 .CS 306 306 typedef struct Tcl_EncodingType { 307 307 const char *\fIencodingName\fR; 308 308 Tcl_EncodingConvertProc *\fItoUtfProc\fR; 309 309 Tcl_EncodingConvertProc *\fIfromUtfProc\fR; 310 310 Tcl_EncodingFreeProc *\fIfreeProc\fR; 311 - ClientData \fIclientData\fR; 311 + void *\fIclientData\fR; 312 312 int \fInullSize\fR; 313 313 } \fBTcl_EncodingType\fR; 314 314 .CE 315 315 .PP 316 316 The \fIencodingName\fR provides a string name for the encoding, by 317 317 which it can be referred in other procedures such as 318 318 \fBTcl_GetEncoding\fR. The \fItoUtfProc\fR refers to a callback ................................................................................ 335 335 CNS11643) are not accepted. 336 336 .PP 337 337 The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the 338 338 type \fBTcl_EncodingConvertProc\fR: 339 339 .PP 340 340 .CS 341 341 typedef int \fBTcl_EncodingConvertProc\fR( 342 - ClientData \fIclientData\fR, 342 + void *\fIclientData\fR, 343 343 const char *\fIsrc\fR, 344 344 int \fIsrcLen\fR, 345 345 int \fIflags\fR, 346 346 Tcl_EncodingState *\fIstatePtr\fR, 347 347 char *\fIdst\fR, 348 348 int \fIdstLen\fR, 349 349 int *\fIsrcReadPtr\fR, ................................................................................ 367 367 procedure will be a non-NULL location. 368 368 .PP 369 369 The callback procedure \fIfreeProc\fR, if non-NULL, should match the type 370 370 \fBTcl_EncodingFreeProc\fR: 371 371 .PP 372 372 .CS 373 373 typedef void \fBTcl_EncodingFreeProc\fR( 374 - ClientData \fIclientData\fR); 374 + void *\fIclientData\fR); 375 375 .CE 376 376 .PP 377 377 This \fIfreeProc\fR function is called when the encoding is deleted. The 378 378 \fIclientData\fR parameter is the same as the \fIclientData\fR field 379 379 specified to \fBTcl_CreateEncoding\fR when the encoding was created. 380 380 .PP 381 381 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
Changes to doc/Exit.3.
38 38 Exact meaning may 39 39 be platform-specific. 0 usually means a normal exit, any nonzero value 40 40 usually means that an error occurred. 41 41 .AP Tcl_ExitProc *proc in 42 42 Procedure to invoke before exiting application, or (for 43 43 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit 44 44 procedure. 45 -.AP ClientData clientData in 45 +.AP void *clientData in 46 46 Arbitrary one-word value to pass to \fIproc\fR. 47 47 .BE 48 48 49 49 .SH DESCRIPTION 50 50 .PP 51 51 The procedures described here provide a graceful mechanism to end the 52 52 execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the ................................................................................ 60 60 Note that if other code invokes \fBexit\fR system procedure directly, or 61 61 otherwise causes the application to terminate without calling 62 62 \fBTcl_Exit\fR, the exit handlers will not be run. 63 63 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never 64 64 returns control to its caller. 65 65 If an application exit handler has been installed (see 66 66 \fBTcl_SetExitProc\fR), that handler is invoked with an argument 67 -consisting of the exit status (cast to ClientData); the application 67 +consisting of the exit status (cast to void *); the application 68 68 exit handler should not return control to Tcl. 69 69 .PP 70 70 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not 71 71 exit from the current process. 72 72 It is useful for cleaning up when a process is finished using \fBTcl\fR but 73 73 wishes to continue executing, and when \fBTcl\fR is used in a dynamically 74 74 loaded extension that is about to be unloaded. ................................................................................ 89 89 by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR. 90 90 This provides a hook for cleanup operations such as flushing buffers 91 91 and freeing global memory. 92 92 \fIProc\fR should match the type \fBTcl_ExitProc\fR: 93 93 .PP 94 94 .CS 95 95 typedef void \fBTcl_ExitProc\fR( 96 - ClientData \fIclientData\fR); 96 + void *\fIclientData\fR); 97 97 .CE 98 98 .PP 99 99 The \fIclientData\fR parameter to \fIproc\fR is a 100 100 copy of the \fIclientData\fR argument given to 101 101 \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when 102 102 the callback 103 103 was created. Typically, \fIclientData\fR points to a data ................................................................................ 129 129 \fBTcl_SetExitProc\fR installs an application exit handler, returning 130 130 the previously-installed application exit handler or NULL if no 131 131 application handler was installed. If an application exit handler is 132 132 installed, that exit handler takes over complete responsibility for 133 133 finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an 134 134 appropriate time. The argument passed to \fIproc\fR when it is 135 135 invoked will be the exit status code (as passed to \fBTcl_Exit\fR) 136 -cast to a ClientData value. 136 +cast to a void *value. 137 +.PP 138 +\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. 137 139 .SH "SEE ALSO" 138 140 exit(n) 139 141 .SH KEYWORDS 140 142 abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread
Changes to doc/FileSystem.3.
16 16 .sp 17 17 int 18 18 \fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR) 19 19 .sp 20 20 int 21 21 \fBTcl_FSUnregister\fR(\fIfsPtr\fR) 22 22 .sp 23 -ClientData 23 +void * 24 24 \fBTcl_FSData\fR(\fIfsPtr\fR) 25 25 .sp 26 26 void 27 27 \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR) 28 28 .sp 29 29 const Tcl_Filesystem * 30 30 \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR) ................................................................................ 121 121 .sp 122 122 Tcl_Obj * 123 123 \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR) 124 124 .sp 125 125 int 126 126 \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR) 127 127 .sp 128 -ClientData 128 +void * 129 129 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR) 130 130 .sp 131 131 Tcl_Obj * 132 132 \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR) 133 133 .sp 134 134 const char * 135 135 \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR) ................................................................................ 208 208 Only files or directories matching this pattern will be returned. 209 209 .AP Tcl_GlobTypeData *types in 210 210 Only files or directories matching the type descriptions contained in 211 211 this structure will be returned. This parameter may be NULL. 212 212 .AP Tcl_Interp *interp in 213 213 Interpreter to use either for results, evaluation, or reporting error 214 214 messages. 215 -.AP ClientData clientData in 215 +.AP void *clientData in 216 216 The native description of the path value to create. 217 217 .AP Tcl_Obj *firstPtr in 218 218 The first of two path values to compare. The value may be converted 219 219 to \fBpath\fR type. 220 220 .AP Tcl_Obj *secondPtr in 221 221 The second of two path values to compare. The value may be converted 222 222 to \fBpath\fR type. ................................................................................ 245 245 Name of a procedure to look up in the file's symbol table 246 246 .AP "const char" *sym2 in 247 247 Name of a procedure to look up in the file's symbol table 248 248 .AP Tcl_PackageInitProc **proc1Ptr out 249 249 Filled with the init function for this code. 250 250 .AP Tcl_PackageInitProc **proc2Ptr out 251 251 Filled with the safe-init function for this code. 252 -.AP ClientData *clientDataPtr out 252 +.AP void **clientDataPtr out 253 253 Filled with the clientData value to pass to this code's unload 254 254 function when it is called. 255 255 .AP Tcl_LoadHandle *loadHandlePtr out 256 256 Filled with an abstract token representing the loaded file. 257 257 .AP Tcl_FSUnloadFileProc **unloadProcPtr out 258 258 Filled with the function to use to unload this piece of code. 259 259 .AP Tcl_LoadHandle loadHandle in ................................................................................ 720 720 freed. This function is of little practical use, and 721 721 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually 722 722 better functions to use for most purposes. 723 723 .PP 724 724 \fBTcl_FSGetTranslatedStringPath\fR does the same as 725 725 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. 726 726 The string returned is dynamically allocated and owned by the caller, 727 -which must store it or call \fBckfree\fR to ensure it is freed. Again, 727 +which must store it or call \fBTcl_Free\fR to ensure it is freed. Again, 728 728 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually 729 729 better functions to use for most purposes. 730 730 .PP 731 731 \fBTcl_FSNewNativePath\fR performs something like the reverse of the 732 732 usual obj->path->nativerep conversions. If some code retrieves a path 733 733 in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path 734 734 is to be used at the Tcl level, then calling this function is an ................................................................................ 787 787 absolute. 788 788 .PP 789 789 It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or 790 790 \fBTCL_PATH_VOLUME_RELATIVE\fR 791 791 .SS "PORTABLE STAT RESULT API" 792 792 .PP 793 793 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which 794 -may be deallocated by being passed to \fBckfree\fR). This allows extensions to 794 +may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to 795 795 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the 796 796 size of the buffer. That in turn depends on the flags used to build Tcl. 797 797 .PP 798 798 .VS 8.6 799 799 The portable fields of a \fITcl_StatBuf\fR may be read using the following 800 800 functions, each of which returns the value of the corresponding field listed 801 801 in the table below. Note that on some platforms there may be other fields in ................................................................................ 837 837 not check if the same filesystem is registered multiple times (and in 838 838 general that is not a good thing to do). \fBTCL_OK\fR will be returned. 839 839 .PP 840 840 \fBTcl_FSUnregister\fR removes the given filesystem structure from 841 841 the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If 842 842 the filesystem is not currently registered, \fBTCL_ERROR\fR is returned. 843 843 .PP 844 -\fBTcl_FSData\fR will return the ClientData associated with the given 844 +\fBTcl_FSData\fR will return the clientData associated with the given 845 845 filesystem, if that filesystem is registered. Otherwise it will 846 846 return NULL. 847 847 .PP 848 848 \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that 849 849 the set of mount points for the given (already registered) filesystem 850 850 have changed, and that cached file representations may therefore no 851 851 longer be correct. ................................................................................ 1014 1014 cache the fact that this path belongs to this filesystem. Such caches 1015 1015 are invalidated when filesystem structures are added or removed from 1016 1016 Tcl's internal list of known filesystems. 1017 1017 .PP 1018 1018 .CS 1019 1019 typedef int \fBTcl_FSPathInFilesystemProc\fR( 1020 1020 Tcl_Obj *\fIpathPtr\fR, 1021 - ClientData *\fIclientDataPtr\fR); 1021 + void **\fIclientDataPtr\fR); 1022 1022 .CE 1023 1023 .SS DUPINTERNALREPPROC 1024 1024 .PP 1025 1025 This function makes a copy of a path's internal representation, and is 1026 1026 called when Tcl needs to duplicate a path value. If NULL, Tcl will 1027 1027 simply not copy the internal representation, which may then need to be 1028 1028 regenerated later. 1029 1029 .PP 1030 1030 .CS 1031 -typedef ClientData \fBTcl_FSDupInternalRepProc\fR( 1032 - ClientData \fIclientData\fR); 1031 +typedef void *\fBTcl_FSDupInternalRepProc\fR( 1032 + void *\fIclientData\fR); 1033 1033 .CE 1034 1034 .SS FREEINTERNALREPPROC 1035 1035 Free the internal representation. This must be implemented if internal 1036 1036 representations need freeing (i.e.\ if some memory is allocated when an 1037 1037 internal representation is generated), but may otherwise be NULL. 1038 1038 .PP 1039 1039 .CS 1040 1040 typedef void \fBTcl_FSFreeInternalRepProc\fR( 1041 - ClientData \fIclientData\fR); 1041 + void *\fIclientData\fR); 1042 1042 .CE 1043 1043 .SS INTERNALTONORMALIZEDPROC 1044 1044 .PP 1045 1045 Function to convert internal representation to a normalized path. Only 1046 1046 required if the filesystem creates pure path values with no string/path 1047 1047 representation. The return value is a Tcl value whose string 1048 1048 representation is the normalized path. 1049 1049 .PP 1050 1050 .CS 1051 1051 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( 1052 - ClientData \fIclientData\fR); 1052 + void *\fIclientData\fR); 1053 1053 .CE 1054 1054 .SS CREATEINTERNALREPPROC 1055 1055 .PP 1056 1056 Function to take a path value, and calculate an internal 1057 1057 representation for it, and store that native representation in the 1058 1058 value. May be NULL if paths have no internal representation, or if 1059 1059 the \fITcl_FSPathInFilesystemProc\fR for this filesystem always 1060 1060 immediately creates an internal representation for paths it accepts. 1061 1061 .PP 1062 1062 .CS 1063 -typedef ClientData \fBTcl_FSCreateInternalRepProc\fR( 1063 +typedef void *\fBTcl_FSCreateInternalRepProc\fR( 1064 1064 Tcl_Obj *\fIpathPtr\fR); 1065 1065 .CE 1066 1066 .SS NORMALIZEPATHPROC 1067 1067 .PP 1068 1068 Function to normalize a path. Should be implemented for all 1069 1069 filesystems which can have multiple string representations for the same 1070 1070 path value. In Tcl, every
Changes to doc/FindExec.3.
54 54 .PP 55 55 \fBTcl_GetNameOfExecutable\fR simply returns a pointer to the 56 56 internal full path name of the executable file as computed by 57 57 \fBTcl_FindExecutable\fR. This procedure call is the C API 58 58 equivalent to the \fBinfo nameofexecutable\fR command. NULL 59 59 is returned if the internal full path name has not been 60 60 computed or unknown. 61 - 61 +.PP 62 +\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. 62 63 .SH KEYWORDS 63 64 binary, executable file
Changes to doc/GetOpnFl.3.
24 24 String identifying channel, such as \fBstdin\fR or \fBfile4\fR. 25 25 .AP int write in 26 26 Non-zero means the file will be used for writing, zero means it will 27 27 be used for reading. 28 28 .AP int checkUsage in 29 29 If non-zero, then an error will be generated if the file was not opened 30 30 for the access indicated by \fIwrite\fR. 31 -.AP ClientData *filePtr out 31 +.AP void **filePtr out 32 32 Points to word in which to store pointer to FILE structure for 33 33 the file given by \fIchanID\fR. 34 34 .BE 35 35 36 36 .SH DESCRIPTION 37 37 .PP 38 38 \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
Changes to doc/GetTime.3.
23 23 .AP Tcl_Time *timePtr out 24 24 Points to memory in which to store the date and time information. 25 25 .AP Tcl_GetTimeProc getProc in 26 26 Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. 27 27 .AP Tcl_ScaleTimeProc scaleProc in 28 28 Pointer to handler function for the conversion of time delays in the 29 29 virtual domain to real-time. 30 -.AP ClientData clientData in 30 +.AP void *clientData in 31 31 Value passed through to the two handler functions. 32 32 .AP Tcl_GetTimeProc *getProcPtr out 33 33 Pointer to place the currently registered get handler function into. 34 34 .AP Tcl_ScaleTimeProc *scaleProcPtr out 35 35 Pointer to place the currently registered scale handler function into. 36 -.AP ClientData *clientDataPtr out 36 +.AP void **clientDataPtr out 37 37 Pointer to place the currently registered pass-through value into. 38 38 .BE 39 39 .SH DESCRIPTION 40 40 .PP 41 41 The \fBTcl_GetTime\fR function retrieves the current time as a 42 42 \fITcl_Time\fR structure in memory the caller provides. This 43 43 structure has the following definition: ................................................................................ 79 79 any argument which is NULL is ignored and not set. 80 80 .PP 81 81 The signatures of the handler functions are as follows: 82 82 .PP 83 83 .CS 84 84 typedef void \fBTcl_GetTimeProc\fR( 85 85 Tcl_Time *\fItimebuf\fR, 86 - ClientData \fIclientData\fR); 86 + void *\fIclientData\fR); 87 87 typedef void \fBTcl_ScaleTimeProc\fR( 88 88 Tcl_Time *\fItimebuf\fR, 89 - ClientData \fIclientData\fR); 89 + void *\fIclientData\fR); 90 90 .CE 91 91 .PP 92 92 The \fItimebuf\fR fields contain the time to manipulate, and the 93 93 \fIclientData\fR fields contain a pointer supplied at the time the handler 94 94 functions were registered. 95 95 .PP 96 96 Any handler pair specified has to return data which is consistent between
Changes to doc/Hash.3.
26 26 \fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR) 27 27 .sp 28 28 \fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR) 29 29 .sp 30 30 Tcl_HashEntry * 31 31 \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR) 32 32 .sp 33 -ClientData 33 +void * 34 34 \fBTcl_GetHashValue\fR(\fIentryPtr\fR) 35 35 .sp 36 36 \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR) 37 37 .sp 38 38 void * 39 39 \fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR) 40 40 .sp ................................................................................ 62 62 Key to use for probe into table. Exact form depends on 63 63 \fIkeyType\fR used to create table. 64 64 .AP int *newPtr out 65 65 The word at \fI*newPtr\fR is set to 1 if a new entry was created 66 66 and 0 if there was already an entry for \fIkey\fR. 67 67 .AP Tcl_HashEntry *entryPtr in 68 68 Pointer to hash table entry. 69 -.AP ClientData value in 70 -New value to assign to hash table entry. Need not have type 71 -ClientData, but must fit in same space as ClientData. 69 +.AP void *value in 70 +New value to assign to hash table entry. 72 71 .AP Tcl_HashSearch *searchPtr in 73 72 Pointer to record to use to keep track of progress in enumerating 74 73 all the entries in a hash table. 75 74 .BE 76 75 .SH DESCRIPTION 77 76 .PP 78 77 A hash table consists of zero or more entries, each consisting of a ................................................................................ 182 181 .PP 183 182 \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR 184 183 except that it does not create a new entry if the key doesn't exist; 185 184 instead, it returns NULL as result. 186 185 .PP 187 186 \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to 188 187 read and write an entry's value, respectively. 189 -Values are stored and retrieved as type 190 -.QW ClientData , 191 -which is 192 -large enough to hold a pointer value. On almost all machines this is 193 -large enough to hold an integer value too. 194 188 .PP 195 189 \fBTcl_GetHashKey\fR returns the key for a given hash table entry, 196 190 either as a pointer to a string, a one-word 197 191 .PQ "char *" 198 192 key, or 199 193 as a pointer to the first word of an array of integers, depending 200 194 on the \fIkeyType\fR used to create a hash table. ................................................................................ 225 219 \fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR. 226 220 .PP 227 221 \fBTcl_HashStats\fR returns a dynamically-allocated string with 228 222 overall information about a hash table, such as the number of 229 223 entries it contains, the number of buckets in its hash array, 230 224 and the utilization of the buckets. 231 225 It is the caller's responsibility to free the result string 232 -by passing it to \fBckfree\fR. 226 +by passing it to \fBTcl_Free\fR. 233 227 .PP 234 228 The header file \fBtcl.h\fR defines the actual data structures 235 229 used to implement hash tables. 236 230 This is necessary so that clients can allocate Tcl_HashTable 237 231 structures and so that macros can be used to read and write 238 232 the values of entries. 239 233 However, users of the hashing routines should never refer directly
Changes to doc/IntObj.3.
4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 7 .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures" 8 8 .so man.macros 9 9 .BS 10 10 .SH NAME 11 -Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers 11 +Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 16 Tcl_Obj * 17 17 \fBTcl_NewIntObj\fR(\fIintValue\fR) 18 18 .sp ................................................................................ 27 27 \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR) 28 28 .sp 29 29 \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR) 30 30 .sp 31 31 int 32 32 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR) 33 33 .sp 34 +int 35 +\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR) 36 +.sp 34 37 int 35 38 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR) 36 39 .sp 37 40 int 38 41 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR) 39 42 .sp 40 43 .sp ................................................................................ 51 54 int 52 55 \fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR) 53 56 .sp 54 57 int 55 58 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) 56 59 .SH ARGUMENTS 57 60 .AS Tcl_WideInt doubleValue in/out 61 +.AP int endValue in 62 +\fBTcl_GetIntForIndex\fR will return this when the input value is "end". 58 63 .AP int intValue in 59 64 Integer value used to initialize or set a Tcl value. 60 65 .AP long longValue in 61 66 Long integer value used to initialize or set a Tcl value. 62 67 .AP Tcl_WideInt wideValue in 63 68 Wide integer value used to initialize or set a Tcl value. 64 69 .AP Tcl_Obj *objPtr in/out ................................................................................ 110 115 and \fBTcl_SetBignumObj\fR routines each set the value of an existing 111 116 Tcl value pointed to by \fIobjPtr\fR to the integral value provided 112 117 by the other argument. The \fIobjPtr\fR argument must point to an 113 118 unshared Tcl value. Any attempt to set the value of a shared Tcl value 114 119 violates Tcl's copy-on-write policy. Any existing string representation 115 120 or internal representation in the unshared Tcl value will be freed 116 121 as a consequence of setting the new value. 122 +.PP 123 +The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index 124 +value from the Tcl value \fIobjPtr\fR. If the attempt succeeds, 125 +then \fBTCL_OK\fR is returned, and the value is written to the 126 +storage provided by the caller. The attempt might fail if 127 +\fIobjPtr\fR does not hold an index value. If the attempt fails, 128 +then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL, 129 +an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR 130 +of \fIobjPtr\fR may be changed to make subsequent calls to the 131 +same routine more efficient. 117 132 .PP 118 133 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, 119 134 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and 120 135 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral 121 136 value of the appropriate type from the Tcl value \fIobjPtr\fR. If the 122 137 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is 123 138 written to the storage provided by the caller. The attempt might
Changes to doc/Limit.3.
79 79 Function to call when a particular limit is exceeded. If the 80 80 \fIhandlerProc\fR removes or raises the limit during its processing, 81 81 the limited interpreter will be permitted to continue to process after 82 82 the handler returns. Many handlers may be attached to the same 83 83 interpreter limit; their order of execution is not defined, and they 84 84 must be identified by \fIhandlerProc\fR and \fIclientData\fR when they 85 85 are deleted. 86 -.AP ClientData clientData in 86 +.AP void *clientData in 87 87 Arbitrary pointer-sized word used to pass some context to the 88 88 \fIhandlerProc\fR function. 89 89 .AP Tcl_LimitHandlerDeleteProc *deleteProc in 90 90 Function to call whenever a handler is deleted. May be NULL if the 91 91 \fIclientData\fR requires no deletion. 92 92 .BE 93 93 .SH DESCRIPTION ................................................................................ 158 158 To add a handler callback to be invoked when a limit is exceeded, call 159 159 \fBTcl_LimitAddHandler\fR. The \fIhandlerProc\fR argument describes 160 160 the function that will actually be called; it should have the 161 161 following prototype: 162 162 .PP 163 163 .CS 164 164 typedef void \fBTcl_LimitHandlerProc\fR( 165 - ClientData \fIclientData\fR, 165 + void *\fIclientData\fR, 166 166 Tcl_Interp *\fIinterp\fR); 167 167 .CE 168 168 .PP 169 169 The \fIclientData\fR argument to the handler will be whatever is 170 170 passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR, 171 171 and the \fIinterp\fR is the interpreter that had its limit exceeded. 172 172 .PP ................................................................................ 175 175 \fBTCL_STATIC\fR or NULL if no deletion action is necessary, or 176 176 \fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with 177 177 \fBTcl_Free\fR. Otherwise, it should refer to a function with the 178 178 following prototype: 179 179 .PP 180 180 .CS 181 181 typedef void \fBTcl_LimitHandlerDeleteProc\fR( 182 - ClientData \fIclientData\fR); 182 + void *\fIclientData\fR); 183 183 .CE 184 184 .PP 185 185 A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the 186 186 handler removed will be the first one found (out of the handlers added 187 187 with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR, 188 188 \fIhandlerProc\fR and \fIclientData\fR arguments. This function 189 189 always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless 190 190 the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR). 191 191 .SH KEYWORDS 192 192 interpreter, resource, limit, commands, time, callback
Changes to doc/LinkVar.3.
5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 8 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" 9 9 .so man.macros 10 10 .BS 11 11 .SH NAME 12 -Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable 12 +Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable 13 13 .SH SYNOPSIS 14 14 .nf 15 15 \fB#include <tcl.h>\fR 16 16 .sp 17 17 int 18 18 \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR) 19 +.sp 20 +.VS "TIP 312" 21 +int 22 +\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR) 23 +.VE "TIP 312" 19 24 .sp 20 25 \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) 21 26 .sp 22 27 \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) 23 28 .SH ARGUMENTS 24 -.AS Tcl_Interp writable 29 +.AS Tcl_Interp varName in 25 30 .AP Tcl_Interp *interp in 26 31 Interpreter that contains \fIvarName\fR. 27 32 Also used by \fBTcl_LinkVar\fR to return error messages. 28 33 .AP "const char" *varName in 29 34 Name of global variable. 30 -.AP char *addr in 35 +.AP void *addr in 31 36 Address of C variable that is to be linked to \fIvarName\fR. 37 +.sp 38 +.VS "TIP 312" 39 +In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage 40 +for the array in the variable. 41 +.VE "TIP 312" 32 42 .AP int type in 33 -Type of C variable. Must be one of \fBTCL_LINK_INT\fR, 43 +Type of C variable for \fBTcl_LinkVar\fR or type of array element for 44 +\fBTcl_LinkArray\fR. Must be one of \fBTCL_LINK_INT\fR, 34 45 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR, 35 46 \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR, 36 47 \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR, 37 -\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, 38 -\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or 39 -\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR 40 -to make Tcl variable read-only. 48 +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR, 49 +\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below. 50 +.sp 51 +In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be 52 +used. 53 +.sp 54 +.VS "TIP 312" 55 +In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and 56 +\fBTCL_LINK_BYTES\fR may be used. 57 +.VE "TIP 312" 58 +.sp 59 +All the above for both functions may be 60 +optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl 61 +variable read-only. 62 +.AP size_t size in 63 +.VS "TIP 312" 64 +The number of elements in the C array. Must be greater than zero. 65 +.VE "TIP 312" 41 66 .BE 42 67 .SH DESCRIPTION 43 68 .PP 44 69 \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable 45 70 named by \fIvarName\fR in sync with the C variable at the address 46 71 given by \fIaddr\fR. 47 72 Whenever the Tcl variable is read the value of the C variable will 48 73 be returned, and whenever the Tcl variable is written the C 49 74 variable will be updated to have the same value. 50 75 \fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR; if an error occurs 51 76 while setting up the link (e.g. because \fIvarName\fR is the 52 77 name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result 53 78 contains an error message. 79 +.PP 80 +.VS "TIP 312" 81 +\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by 82 +the \fIsize\fR argument). When asked to allocate the backing C array 83 +storage (via the \fIaddr\fR argument being NULL), it writes the 84 +address that it allocated to the Tcl interpreter result. 85 +.VE "TIP 312" 54 86 .PP 55 87 The \fItype\fR argument specifies the type of the C variable, 88 +or the type of the elements of the C array, 56 89 and must have one of the following values, optionally OR'ed with 57 90 \fBTCL_LINK_READ_ONLY\fR: 58 91 .TP 59 92 \fBTCL_LINK_INT\fR 60 -The C variable is of type \fBint\fR. 93 +. 94 +The C variable, or each element of the C array, is of type \fBint\fR. 61 95 Any value written into the Tcl variable must have a proper integer 62 96 form acceptable to \fBTcl_GetIntFromObj\fR; attempts to write 63 97 non-integer values into \fIvarName\fR will be rejected with 64 98 Tcl errors. Incomplete integer representations (like the empty 65 99 string, '+', '-' or the hex/octal/binary prefix) are accepted 66 100 as if they are valid too. 67 101 .TP 68 102 \fBTCL_LINK_UINT\fR 69 -The C variable is of type \fBunsigned int\fR. 103 +. 104 +The C variable, or each element of the C array, is of type \fBunsigned int\fR. 70 105 Any value written into the Tcl variable must have a proper unsigned 71 106 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the 72 107 platform's defined range for the \fBunsigned int\fR type; attempts to 73 108 write non-integer values (or values outside the range) into 74 109 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer 75 110 representations (like the empty string, '+', '-' or the hex/octal/binary 76 111 prefix) are accepted as if they are valid too. 77 112 .TP 78 113 \fBTCL_LINK_CHAR\fR 79 -The C variable is of type \fBchar\fR. 114 +. 115 +The C variable, or each element of the C array, is of type \fBchar\fR. 80 116 Any value written into the Tcl variable must have a proper integer 81 117 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the 82 118 \fBchar\fR datatype; attempts to write non-integer or out-of-range 83 119 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete 84 120 integer representations (like the empty string, '+', '-' or the 85 121 hex/octal/binary prefix) are accepted as if they are valid too. 122 +.RS 123 +.PP 124 +.VS "TIP 312" 125 +If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead. 126 +.VE "TIP 312" 127 +.RE 128 +.TP 129 +\fBTCL_LINK_CHARS\fR 130 +.VS "TIP 312" 131 +The C array is of type \fBchar *\fR and is mapped into Tcl as a string. 132 +Any value written into the Tcl variable must have the same length as 133 +the underlying storage. Only supported with \fBTcl_LinkArray\fR. 134 +.VE "TIP 312" 86 135 .TP 87 136 \fBTCL_LINK_UCHAR\fR 88 -The C variable is of type \fBunsigned char\fR. 137 +. 138 +The C variable, or each element of the C array, is of type \fBunsigned char\fR. 89 139 Any value written into the Tcl variable must have a proper unsigned 90 140 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the 91 141 platform's defined range for the \fBunsigned char\fR type; attempts to 92 142 write non-integer values (or values outside the range) into 93 143 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer 94 144 representations (like the empty string, '+', '-' or the hex/octal/binary 95 145 prefix) are accepted as if they are valid too. 146 +.RS 147 +.PP 148 +.VS "TIP 312" 149 +If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead. 150 +.VE "TIP 312" 151 +.RE 152 +.TP 153 +\fBTCL_LINK_BYTES\fR 154 +.VS "TIP 312" 155 +The C array is of type \fBunsigned char *\fR and is mapped into Tcl 156 +as a bytearray. 157 +Any value written into the Tcl variable must have the same length as 158 +the underlying storage. Only supported with \fBTcl_LinkArray\fR. 159 +.VE "TIP 312" 96 160 .TP 97 161 \fBTCL_LINK_SHORT\fR 98 -The C variable is of type \fBshort\fR. 162 +. 163 +The C variable, or each element of the C array, is of type \fBshort\fR. 99 164 Any value written into the Tcl variable must have a proper integer 100 165 form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the 101 166 \fBshort\fR datatype; attempts to write non-integer or out-of-range 102 167 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete 103 168 integer representations (like the empty string, '+', '-' or the 104 169 hex/octal/binary prefix) are accepted as if they are valid too. 105 170 .TP 106 171 \fBTCL_LINK_USHORT\fR 107 -The C variable is of type \fBunsigned short\fR. 172 +. 173 +The C variable, or each element of the C array, is of type \fBunsigned short\fR. 108 174 Any value written into the Tcl variable must have a proper unsigned 109 175 integer form acceptable to \fBTcl_GetIntFromObj\fR and in the 110 176 platform's defined range for the \fBunsigned short\fR type; attempts to 111 177 write non-integer values (or values outside the range) into 112 178 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer 113 179 representations (like the empty string, '+', '-' or the hex/octal/binary 114 180 prefix) are accepted as if they are valid too. 115 181 .TP 116 182 \fBTCL_LINK_LONG\fR 117 -The C variable is of type \fBlong\fR. 183 +. 184 +The C variable, or each element of the C array, is of type \fBlong\fR. 118 185 Any value written into the Tcl variable must have a proper integer 119 186 form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write 120 187 non-integer or out-of-range 121 188 values into \fIvarName\fR will be rejected with Tcl errors. Incomplete 122 189 integer representations (like the empty string, '+', '-' or the 123 190 hex/octal/binary prefix) are accepted as if they are valid too. 124 191 .TP 125 192 \fBTCL_LINK_ULONG\fR 126 -The C variable is of type \fBunsigned long\fR. 193 +. 194 +The C variable, or each element of the C array, is of type \fBunsigned long\fR. 127 195 Any value written into the Tcl variable must have a proper unsigned 128 196 integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the 129 197 platform's defined range for the \fBunsigned long\fR type; attempts to 130 198 write non-integer values (or values outside the range) into 131 199 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer 132 200 representations (like the empty string, '+', '-' or the hex/octal/binary 133 201 prefix) are accepted as if they are valid too. 134 202 .TP 135 203 \fBTCL_LINK_DOUBLE\fR 136 -The C variable is of type \fBdouble\fR. 204 +. 205 +The C variable, or each element of the C array, is of type \fBdouble\fR. 137 206 Any value written into the Tcl variable must have a proper real 138 207 form acceptable to \fBTcl_GetDoubleFromObj\fR; attempts to write 139 208 non-real values into \fIvarName\fR will be rejected with 140 209 Tcl errors. Incomplete integer or real representations (like the 141 210 empty string, '.', '+', '-' or the hex/octal/binary prefix) are 142 211 accepted as if they are valid too. 143 212 .TP 144 213 \fBTCL_LINK_FLOAT\fR 145 -The C variable is of type \fBfloat\fR. 214 +. 215 +The C variable, or each element of the C array, is of type \fBfloat\fR. 146 216 Any value written into the Tcl variable must have a proper real 147 217 form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the 148 218 range acceptable for a \fBfloat\fR; attempts to 149 219 write non-real values (or values outside the range) into 150 220 \fIvarName\fR will be rejected with Tcl errors. Incomplete integer 151 221 or real representations (like the empty string, '.', '+', '-' or 152 222 the hex/octal/binary prefix) are accepted as if they are valid too. 153 223 .TP 154 224 \fBTCL_LINK_WIDE_INT\fR 155 -The C variable is of type \fBTcl_WideInt\fR (which is an integer type 225 +. 226 +The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR 227 +(which is an integer type 156 228 at least 64-bits wide on all platforms that can support it.) 157 229 Any value written into the Tcl variable must have a proper integer 158 230 form acceptable to \fBTcl_GetWideIntFromObj\fR; attempts to write 159 231 non-integer values into \fIvarName\fR will be rejected with 160 232 Tcl errors. Incomplete integer representations (like the empty 161 233 string, '+', '-' or the hex/octal/binary prefix) are accepted 162 234 as if they are valid too. 163 235 .TP 164 236 \fBTCL_LINK_WIDE_UINT\fR 165 -The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned 166 -integer type at least 64-bits wide on all platforms that can support 167 -it.) 237 +. 238 +The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR 239 +(which is an unsigned integer type at least 64-bits wide on all platforms that 240 +can support it.) 168 241 Any value written into the Tcl variable must have a proper unsigned 169 242 integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be 170 243 cast to unsigned); 171 244 .\" FIXME! Use bignums instead. 172 245 attempts to write non-integer values into \fIvarName\fR will be 173 246 rejected with Tcl errors. Incomplete integer representations (like 174 247 the empty string, '+', '-' or the hex/octal/binary prefix) are accepted 175 248 as if they are valid too. 176 249 .TP 177 250 \fBTCL_LINK_BOOLEAN\fR 178 -The C variable is of type \fBint\fR. 251 +. 252 +The C variable, or each element of the C array, is of type \fBint\fR. 179 253 If its value is zero then it will read from Tcl as 180 254 .QW 0 ; 181 255 otherwise it will read from Tcl as 182 256 .QW 1 . 183 257 Whenever \fIvarName\fR is 184 258 modified, the C variable will be set to a 0 or 1 value. 185 259 Any value written into the Tcl variable must have a proper boolean 186 260 form acceptable to \fBTcl_GetBooleanFromObj\fR; attempts to write 187 261 non-boolean values into \fIvarName\fR will be rejected with 188 262 Tcl errors. 189 263 .TP 190 264 \fBTCL_LINK_STRING\fR 265 +. 191 266 The C variable is of type \fBchar *\fR. 192 267 If its value is not NULL then it must be a pointer to a string 193 -allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. 268 +allocated with \fBTcl_Alloc\fR. 194 269 Whenever the Tcl variable is modified the current C string will be 195 270 freed and new memory will be allocated to hold a copy of the variable's 196 271 new value. 197 272 If the C variable contains a NULL pointer then the Tcl variable 198 273 will read as 199 274 .QW NULL . 275 +This is only supported by \fBTcl_LinkVar\fR. 200 276 .PP 201 277 If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the 202 278 variable will be read-only from Tcl, so that its value can only be 203 279 changed by modifying the C variable. 204 280 Attempts to write the variable from Tcl will be rejected with errors. 205 281 .PP 206 282 \fBTcl_UnlinkVar\fR removes the link previously set up for the
Changes to doc/Method.3.
5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 7 .TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions" 8 8 .so man.macros 9 9 .BS 10 10 '\" Note: do not modify the .SH NAME line immediately below! 11 11 .SH NAME 12 -Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts 12 +Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts 13 13 .SH SYNOPSIS 14 14 .nf 15 15 \fB#include <tclOO.h>\fR 16 16 .sp 17 17 Tcl_Method 18 -\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic, 19 - methodTypePtr, clientData\fR) 18 +\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr, 19 + clientData\fR) 20 20 .sp 21 21 Tcl_Method 22 -\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic, 23 - methodTypePtr, clientData\fR) 22 +\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr, 23 + clientData\fR) 24 24 .sp 25 25 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR) 26 26 .sp 27 27 \fBTcl_ClassSetDestructor\fR(\fIinterp, class, method\fR) 28 28 .sp 29 29 Tcl_Class 30 30 \fBTcl_MethodDeclarerClass\fR(\fImethod\fR) ................................................................................ 31 31 .sp 32 32 Tcl_Object 33 33 \fBTcl_MethodDeclarerObject\fR(\fImethod\fR) 34 34 .sp 35 35 Tcl_Obj * 36 36 \fBTcl_MethodName\fR(\fImethod\fR) 37 37 .sp 38 +.VS TIP500 38 39 int 39 40 \fBTcl_MethodIsPublic\fR(\fImethod\fR) 41 +.VE TIP500 42 +.sp 43 +int 44 +\fBTcl_MethodIsPrivate\fR(\fImethod\fR) 40 45 .sp 41 46 int 42 47 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR) 43 48 .sp 44 49 int 45 50 \fBTcl_ObjectContextInvokeNext\fR(\fIinterp, context, objc, objv, skip\fR) 46 51 .sp ................................................................................ 52 57 .sp 53 58 Tcl_Object 54 59 \fBTcl_ObjectContextObject\fR(\fIcontext\fR) 55 60 .sp 56 61 int 57 62 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR) 58 63 .SH ARGUMENTS 59 -.AS ClientData clientData in 64 +.AS void *clientData in 60 65 .AP Tcl_Interp *interp in/out 61 66 The interpreter holding the object or class to create or update a method in. 62 67 .AP Tcl_Object object in 63 68 The object to create the method in. 64 69 .AP Tcl_Class class in 65 70 The class to create the method in. 66 71 .AP Tcl_Obj *nameObj in 67 72 The name of the method to create. Should not be NULL unless creating 68 73 constructors or destructors. 69 -.AP int isPublic in 70 -A flag saying what the visibility of the method is. The only supported public 71 -values of this flag are 0 for a non-exported method, and 1 for an exported 72 -method. 74 +.AP int flags in 75 +A flag saying (currently) what the visibility of the method is. The supported 76 +public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1 77 +for backward compatibility) for an exported method, 78 +\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward 79 +compatibility) for a non-exported method, 80 +.VS TIP500 81 +and \fBTCL_OO_METHOD_PRIVATE\fR for a private method. 82 +.VE TIP500 73 83 .AP Tcl_MethodType *methodTypePtr in 74 84 A description of the type of the method to create, or the type of method to 75 85 compare against. 76 -.AP ClientData clientData in 86 +.AP void *clientData in 77 87 A piece of data that is passed to the implementation of the method without 78 88 interpretation. 79 -.AP ClientData *clientDataPtr out 89 +.AP void **clientDataPtr out 80 90 A pointer to a variable in which to write the \fIclientData\fR value supplied 81 91 when the method was created. If NULL, the \fIclientData\fR value will not be 82 92 retrieved. 83 93 .AP Tcl_Method method in 84 94 A reference to a method to query. 85 95 .AP Tcl_ObjectContext context in 86 96 A reference to a method-call context. Note that client code \fImust not\fR ................................................................................ 101 111 that class. 102 112 .PP 103 113 Given a method, the entity that declared it can be found using 104 114 \fBTcl_MethodDeclarerClass\fR which returns the class that the method is 105 115 attached to (or NULL if the method is not attached to any class) and 106 116 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is 107 117 attached to (or NULL if the method is not attached to an object). The name of 108 -the method can be retrieved with \fBTcl_MethodName\fR and whether the method 109 -is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method 118 +the method can be retrieved with \fBTcl_MethodName\fR, whether the method 119 +is exported is retrieved with \fBTcl_MethodIsPublic\fR, 120 +.VS TIP500 121 +and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR. 122 +.VE TIP500 123 +The type of the method 110 124 can also be introspected upon to a limited degree; the function 111 125 \fBTcl_MethodIsType\fR returns whether a method is of a particular type, 112 126 assigning the per-method \fIclientData\fR to the variable pointed to by 113 127 \fIclientDataPtr\fR if (that is non-NULL) if the type is matched. 114 128 .SS "METHOD CREATION" 115 129 .PP 116 130 Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR, 117 131 which 118 132 create a method attached to a class or an object respectively. In both cases, 119 133 the \fInameObj\fR argument gives the name of the method to create, the 120 -\fIisPublic\fR argument states whether the method should be exported 121 -initially, the \fImethodTypePtr\fR argument describes the implementation of 134 +\fIflags\fR argument states whether the method should be exported 135 +initially 136 +.VS TIP500 137 +or be marked as a private method, 138 +.VE TIP500 139 +the \fImethodTypePtr\fR argument describes the implementation of 122 140 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR 123 141 argument gives some implementation-specific data that is passed on to the 124 142 implementation of the method when it is called. 125 143 .PP 126 144 When the \fInameObj\fR argument to \fBTcl_NewMethod\fR is NULL, an 127 145 unnamed method is created, which is used for constructors and destructors. 128 146 Constructors should be installed into their class using the ................................................................................ 191 209 that the \fIclientData\fR can just be copied directly. 192 210 .SS "TCL_METHODCALLPROC FUNCTION SIGNATURE" 193 211 .PP 194 212 Functions matching this signature are called when the method is invoked. 195 213 .PP 196 214 .CS 197 215 typedef int \fBTcl_MethodCallProc\fR( 198 - ClientData \fIclientData\fR, 216 + void *\fIclientData\fR, 199 217 Tcl_Interp *\fIinterp\fR, 200 218 Tcl_ObjectContext \fIobjectContext\fR, 201 219 int \fIobjc\fR, 202 220 Tcl_Obj *const *\fIobjv\fR); 203 221 .CE 204 222 .PP 205 223 The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was ................................................................................ 212 230 .SS "TCL_METHODDELETEPROC FUNCTION SIGNATURE" 213 231 .PP 214 232 Functions matching this signature are used when a method is deleted, whether 215 233 through a new method being created or because the object or class is deleted. 216 234 .PP 217 235 .CS 218 236 typedef void \fBTcl_MethodDeleteProc\fR( 219 - ClientData \fIclientData\fR); 237 + void *\fIclientData\fR); 220 238 .CE 221 239 .PP 222 240 The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as 223 241 the value passed to the \fIclientData\fR argument to \fBTcl_NewMethod\fR or 224 242 \fBTcl_NewInstanceMethod\fR when the method was created. 225 243 .SS "TCL_CLONEPROC FUNCTION SIGNATURE" 226 244 .PP 227 245 Functions matching this signature are used to copy a method when the object or 228 246 class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR). 229 247 .PP 230 248 .CS 231 249 typedef int \fBTcl_CloneProc\fR( 232 250 Tcl_Interp *\fIinterp\fR, 233 - ClientData \fIoldClientData\fR, 234 - ClientData *\fInewClientDataPtr\fR); 251 + void *\fIoldClientData\fR, 252 + void **\fInewClientDataPtr\fR); 235 253 .CE 236 254 .PP 237 255 The \fIinterp\fR argument gives a place to write an error message when the 238 256 attempt to clone the object is to fail, in which case the clone procedure must 239 257 also return TCL_ERROR; it should return TCL_OK otherwise. 240 258 The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the 241 259 method being copied from, and the \fInewClientDataPtr\fR field will point to
Changes to doc/NRE.3.
1 1 .\" 2 2 .\" Copyright (c) 2008 by Kevin B. Kenny. 3 -.\" Copyright (c) 2018 by Nathan Coulter. 3 +.\" Copyright (c) 2018 by Nathan Coulter. 4 4 .\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 8 .TH NRE 3 8.6 Tcl "Tcl Library Procedures" 9 9 .so man.macros 10 10 .BS ................................................................................ 45 45 .AP Tcl_ObjCmdProc *proc in 46 46 Called in order to evaluate a command. Is often just a small wrapper that uses 47 47 \fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline. Behaves 48 48 in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3) 49 49 (\fIq.v.\fR). 50 50 .AP Tcl_ObjCmdProc *nreProc in 51 51 Called instead of \fIproc\fR when a trampoline is already in use. 52 -.AP ClientData clientData in 52 +.AP void *clientData in 53 53 Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR 54 54 and \fIobjProc\fR. 55 55 .AP Tcl_CmdDeleteProc *deleteProc in/out 56 56 Called before \fIcmdName\fR is deleted from the interpreter, allowing for 57 57 command-specific cleanup. May be NULL. 58 58 .AP int objc in 59 59 Number of items in \fIobjv\fR. ................................................................................ 68 68 Token to use instead of one derived from the first word of \fIobjv\fR in order 69 69 to evaluate a command. 70 70 .AP Tcl_Obj *resultPtr out 71 71 Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if 72 72 the return code is TCL_OK. 73 73 .AP Tcl_NRPostProc *postProcPtr in 74 74 A function to push. 75 -.AP ClientData data0 in 76 -.AP ClientData data1 in 77 -.AP ClientData data2 in 78 -.AP ClientData data3 in 75 +.AP void *data0 in 76 +.AP void *data1 in 77 +.AP void *data2 in 78 +.AP void *data3 in 79 79 \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed 80 80 to the function designated by \fIpostProcPtr\fR when it is invoked. 81 81 .BE 82 82 .SH DESCRIPTION 83 83 .PP 84 84 These functions provide an interface to the function stack that an interpreter 85 85 iterates through to evaluate commands. The routine behind a command is ................................................................................ 126 126 .PP 127 127 \fBTcl_NRAddCallback\fR pushes \fIpostProcPtr\fR. The signature for 128 128 \fBTcl_NRPostProc\fR is: 129 129 .PP 130 130 .CS 131 131 typedef int 132 132 \fBTcl_NRPostProc\fR( 133 - \fBClientData\fR \fIdata\fR[], 133 + \fBvoid *\fR \fIdata\fR[], 134 134 \fBTcl_Interp\fR *\fIinterp\fR, 135 135 int \fIresult\fR); 136 136 .CE 137 137 .PP 138 138 \fIdata\fR is a pointer to an array containing \fIdata0\fR through \fIdata3\fR. 139 139 \fIresult\fR is the value returned by the previous function implementing part 140 140 the routine. ................................................................................ 142 142 .PP 143 143 The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C 144 144 stack, to evalute a script: 145 145 .PP 146 146 .CS 147 147 int 148 148 \fITheCmdOldObjProc\fR( 149 - ClientData clientData, 149 + void *clientData, 150 150 Tcl_Interp *interp, 151 151 int objc, 152 152 Tcl_Obj *const objv[]) 153 153 { 154 154 int result; 155 155 Tcl_Obj *objPtr; 156 156 ................................................................................ 173 173 trampoline instead of consuming space on the C stack. A new version of 174 174 \fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to 175 175 call \fITheCmdNRObjProc\fR: 176 176 .PP 177 177 .CS 178 178 int 179 179 \fITheCmdOldObjProc\fR( 180 - ClientData clientData, 180 + void *clientData, 181 181 Tcl_Interp *interp, 182 182 int objc, 183 183 Tcl_Obj *const objv[]) 184 184 { 185 185 return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR, 186 186 clientData, objc, objv); 187 187 } 188 188 .CE 189 189 .PP 190 190 .CS 191 191 int 192 192 \fITheCmdNRObjProc\fR 193 - ClientData clientData, 193 + void *clientData, 194 194 Tcl_Interp *interp, 195 195 int objc, 196 196 Tcl_Obj *const objv[]) 197 197 { 198 198 Tcl_Obj *objPtr; 199 199 200 200 \fI... preparation ...\fR ................................................................................ 207 207 return \fBTcl_NREvalObj\fR(interp, objPtr, 0); 208 208 } 209 209 .CE 210 210 .PP 211 211 .CS 212 212 int 213 213 \fITheCmdNRPostProc\fR( 214 - ClientData data[], 214 + void *data[], 215 215 Tcl_Interp *interp, 216 216 int result) 217 217 { 218 218 /* \fIdata[0] .. data[3]\fR are the four words of data 219 219 * passed to \fBTcl_NRAddCallback\fR */ 220 220 221 221 \fI... postprocessing ...\fR
Changes to doc/Namespace.3.
53 53 .SH ARGUMENTS 54 54 .AS Tcl_NamespaceDeleteProc allowOverwrite in/out 55 55 .AP Tcl_Interp *interp in/out 56 56 The interpreter in which the namespace exists and where name lookups 57 57 are performed. Also where error result messages are written. 58 58 .AP "const char" *name in 59 59 The name of the namespace or command to be created or accessed. 60 -.AP ClientData clientData in 60 +.AP void *clientData in 61 61 A context pointer by the creator of the namespace. Not interpreted by 62 62 Tcl at all. 63 63 .AP Tcl_NamespaceDeleteProc *deleteProc in 64 64 A pointer to function to call when the namespace is deleted, or NULL 65 65 if no such callback is to be performed. 66 66 .AP Tcl_Namespace *nsPtr in 67 67 The namespace to be manipulated, or NULL (for other than ................................................................................ 113 113 the global namespace.) 114 114 .PP 115 115 \fBTcl_CreateNamespace\fR creates a new namespace. The 116 116 \fIdeleteProc\fR will have the following type signature: 117 117 .PP 118 118 .CS 119 119 typedef void \fBTcl_NamespaceDeleteProc\fR( 120 - ClientData \fIclientData\fR); 120 + void *\fIclientData\fR); 121 121 .CE 122 122 .PP 123 123 \fBTcl_DeleteNamespace\fR deletes a namespace, calling the 124 124 \fIdeleteProc\fR defined for the namespace (if any). 125 125 .PP 126 126 \fBTcl_AppendExportList\fR retrieves the export patterns for a 127 127 namespace given namespace and appends them (as list items) to
Changes to doc/Notifier.3.
34 34 .sp 35 35 Tcl_ThreadId 36 36 \fBTcl_GetCurrentThread\fR() 37 37 .sp 38 38 void 39 39 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) 40 40 .sp 41 -ClientData 41 +void * 42 42 \fBTcl_InitNotifier\fR() 43 43 .sp 44 44 void 45 45 \fBTcl_FinalizeNotifier\fR(\fIclientData\fR) 46 46 .sp 47 47 int 48 48 \fBTcl_WaitForEvent\fR(\fItimePtr\fR) ................................................................................ 74 74 .AS Tcl_EventDeleteProc *notifierProcPtr 75 75 .AP Tcl_EventSetupProc *setupProc in 76 76 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR. 77 77 .AP Tcl_EventCheckProc *checkProc in 78 78 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for 79 79 events. Checks to see if any events have occurred and, if so, 80 80 queues them. 81 -.AP ClientData clientData in 81 +.AP void *clientData in 82 82 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or 83 83 \fIdeleteProc\fR. 84 84 .AP "const Tcl_Time" *timePtr in 85 85 Indicates the maximum amount of time to wait for an event. This 86 86 is specified as an interval (how long to wait), not an absolute 87 87 time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR 88 88 is NULL, it means there is no maximum wait time: wait forever if 89 89 necessary. 90 90 .AP Tcl_Event *evPtr in 91 91 An event to add to the event queue. The storage for the event must 92 -have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR. 92 +have been allocated by the caller using \fBTcl_Alloc\fR. 93 93 .AP Tcl_QueuePosition position in 94 94 Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, 95 95 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. 96 96 .AP Tcl_ThreadId threadId in 97 97 A unique identifier for a thread. 98 98 .AP Tcl_EventDeleteProc *deleteProc in 99 99 Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR. ................................................................................ 226 226 The procedure \fBTcl_CreateEventSource\fR creates a new event source. 227 227 Its arguments specify the setup procedure and check procedure for 228 228 the event source. 229 229 \fISetupProc\fR should match the following prototype: 230 230 .PP 231 231 .CS 232 232 typedef void \fBTcl_EventSetupProc\fR( 233 - ClientData \fIclientData\fR, 233 + void *\fIclientData\fR, 234 234 int \fIflags\fR); 235 235 .CE 236 236 .PP 237 237 The \fIclientData\fR argument will be the same as the \fIclientData\fR 238 238 argument to \fBTcl_CreateEventSource\fR; it is typically used to 239 239 point to private information managed by the event source. 240 240 The \fIflags\fR argument will be the same as the \fIflags\fR ................................................................................ 304 304 The second procedure provided by each event source is its check 305 305 procedure, indicated by the \fIcheckProc\fR argument to 306 306 \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the 307 307 following prototype: 308 308 .PP 309 309 .CS 310 310 typedef void \fBTcl_EventCheckProc\fR( 311 - ClientData \fIclientData\fR, 311 + void *\fIclientData\fR, 312 312 int \fIflags\fR); 313 313 .CE 314 314 .PP 315 315 The arguments to this procedure are the same as those for \fIsetupProc\fR. 316 316 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited 317 317 for events. Presumably at least one event source is now prepared to 318 318 queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources ................................................................................ 395 395 Another example of deferring events happens in Tk if 396 396 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds 397 397 of window events. 398 398 .PP 399 399 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the 400 400 event from the event queue and free its storage. 401 401 Note that the storage for an event must be allocated by 402 -the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR) 402 +the event source (using \fBTcl_Alloc\fR) 403 403 before calling \fBTcl_QueueEvent\fR, but it 404 404 will be freed by \fBTcl_ServiceEvent\fR, not by the event source. 405 405 .PP 406 406 Threaded applications work in a 407 407 similar manner, except that there is a separate event queue for 408 408 each thread containing a Tcl interpreter. 409 409 Calling \fBTcl_QueueEvent\fR in a multithreaded application adds ................................................................................ 424 424 for each event in the queue, deleting those for with the procedure 425 425 returns 1. Events for which the procedure returns 0 are left in the 426 426 queue. \fIProc\fR should match the following prototype: 427 427 .PP 428 428 .CS 429 429 typedef int \fBTcl_EventDeleteProc\fR( 430 430 Tcl_Event *\fIevPtr\fR, 431 - ClientData \fIclientData\fR); 431 + void *\fIclientData\fR); 432 432 .CE 433 433 .PP 434 434 The \fIclientData\fR argument will be the same as the \fIclientData\fR 435 435 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to 436 436 private information managed by the event source. The \fIevPtr\fR will 437 437 point to the next event in the queue. 438 438 .PP
Changes to doc/Object.3.
107 107 .SH "THE TCL_OBJ STRUCTURE" 108 108 .PP 109 109 Each Tcl value is represented by a \fBTcl_Obj\fR structure 110 110 which is defined as follows. 111 111 .PP 112 112 .CS 113 113 typedef struct Tcl_Obj { 114 - int \fIrefCount\fR; 114 + size_t \fIrefCount\fR; 115 115 char *\fIbytes\fR; 116 - int \fIlength\fR; 116 + size_t \fIlength\fR; 117 117 const Tcl_ObjType *\fItypePtr\fR; 118 118 union { 119 119 long \fIlongValue\fR; 120 120 double \fIdoubleValue\fR; 121 121 void *\fIotherValuePtr\fR; 122 122 Tcl_WideInt \fIwideValue\fR; 123 123 struct {
Changes to doc/ObjectType.3.
182 182 We require the string representation's byte array 183 183 to have a null after the last byte, at offset \fIlength\fR, 184 184 and to have no null bytes before that; this allows string representations 185 185 to be treated as conventional null character-terminated C strings. 186 186 These restrictions are easily met by using Tcl's internal UTF encoding 187 187 for the string representation, same as one would do for other 188 188 Tcl routines accepting string values as arguments. 189 -Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR 190 -or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate 189 +Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR. 190 +Note that \fIupdateStringProc\fRs must allocate 191 191 enough storage for the string's bytes and the terminating null byte. 192 192 .PP 193 193 The \fIupdateStringProc\fR for Tcl's built-in double type, for example, 194 194 calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE, 195 195 then allocates and copies the string representation to just enough 196 196 space to hold it. A pointer to the allocated space is stored in 197 197 the \fIbytes\fR member.
Changes to doc/OpenFileChnl.3.
49 49 .sp 50 50 int 51 51 \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) 52 52 .sp 53 53 int 54 54 \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) 55 55 .sp 56 -int 56 +size_t 57 57 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) 58 58 .sp 59 -int 59 +size_t 60 60 \fBTcl_Gets\fR(\fIchannel, lineRead\fR) 61 61 .sp 62 -int 62 +size_t 63 63 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) 64 64 .sp 65 -int 65 +size_t 66 66 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) 67 67 .sp 68 -int 68 +size_t 69 69 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) 70 70 .sp 71 -int 71 +size_t 72 72 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) 73 73 .sp 74 -int 74 +size_t 75 75 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) 76 76 .sp 77 -int 77 +size_t 78 78 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) 79 79 .sp 80 80 int 81 81 \fBTcl_Eof\fR(\fIchannel\fR) 82 82 .sp 83 83 int 84 84 \fBTcl_Flush\fR(\fIchannel\fR) ................................................................................ 130 130 \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child 131 131 in the pipe is the pipe channel, otherwise it is the same as the standard 132 132 input of the invoking process; likewise for \fBTCL_STDOUT\fR and 133 133 \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can 134 134 redirect stdio handles to override the stdio handles for which 135 135 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it 136 136 is set, then such redirections cause an error. 137 -.AP ClientData handle in 137 +.AP void *handle in 138 138 Operating system specific handle for I/O to a file. For Unix this is a 139 139 file descriptor, for Windows it is a HANDLE. 140 140 .AP int readOrWrite in 141 141 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate 142 142 what operations are valid on \fIhandle\fR. 143 143 .AP "const char" *channelName in 144 144 The name of the channel. ................................................................................ 150 150 The pattern to match on, passed to Tcl_StringMatch, or NULL. 151 151 .AP Tcl_Channel channel in 152 152 A Tcl channel for input or output. Must have been the return value 153 153 from a procedure such as \fBTcl_OpenFileChannel\fR. 154 154 .AP Tcl_Obj *readObjPtr in/out 155 155 A pointer to a Tcl value in which to store the characters read from the 156 156 channel. 157 -.AP int charsToRead in 157 +.AP size_t charsToRead in 158 158 The number of characters to read from the channel. If the channel's encoding 159 159 is \fBbinary\fR, this is equivalent to the number of bytes to read from the 160 160 channel. 161 161 .AP int appendFlag in 162 162 If non-zero, data read from the channel will be appended to the value. 163 163 Otherwise, the data will replace the existing contents of the value. 164 164 .AP char *readBuf out 165 165 A buffer in which to store the bytes read from the channel. 166 -.AP int bytesToRead in 166 +.AP size_t bytesToRead in 167 167 The number of bytes to read from the channel. The buffer \fIreadBuf\fR must 168 168 be large enough to hold this many bytes. 169 169 .AP Tcl_Obj *lineObjPtr in/out 170 170 A pointer to a Tcl value in which to store the line read from the 171 171 channel. The line read will be appended to the current value of the 172 172 value. 173 173 .AP Tcl_DString *lineRead in/out 174 174 A pointer to a Tcl dynamic string in which to store the line read from the 175 175 channel. Must have been initialized by the caller. The line read will be 176 176 appended to any data already in the dynamic string. 177 177 .AP "const char" *input in 178 178 The input to add to a channel buffer. 179 -.AP int inputLen in 179 +.AP size_t inputLen in 180 180 Length of the input 181 181 .AP int addAtEnd in 182 182 Flag indicating whether the input should be added to the end or 183 183 beginning of the channel buffer. 184 184 .AP Tcl_Obj *writeObjPtr in 185 185 A pointer to a Tcl value whose contents will be output to the channel. 186 186 .AP "const char" *charBuf in 187 187 A buffer containing the characters to output to the channel. 188 188 .AP "const char" *byteBuf in 189 189 A buffer containing the bytes to output to the channel. 190 -.AP int bytesToWrite in 190 +.AP size_t bytesToWrite in 191 191 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and 192 192 output to the channel. 193 193 .AP Tcl_WideInt offset in 194 194 How far to move the access point in the channel at which the next input or 195 195 output operation will be applied, measured in bytes from the position 196 196 given by \fIseekMode\fR. May be either positive or negative. 197 197 .AP int seekMode in
Changes to doc/OpenTcp.3.
46 46 for the local end of the connection. If NULL, a default interface is 47 47 chosen. 48 48 .AP int async in 49 49 If nonzero, the client socket is connected asynchronously to the server. 50 50 .AP "unsigned int" flags in 51 51 ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional 52 52 informations about the socket being created. 53 -.AP ClientData sock in 53 +.AP void *sock in 54 54 Platform-specific handle for client TCP socket. 55 55 .AP Tcl_TcpAcceptProc *proc in 56 56 Pointer to a procedure to invoke each time a new connection is 57 57 accepted via the socket. 58 -.AP ClientData clientData in 58 +.AP void *clientData in 59 59 Arbitrary one-word value to pass to \fIproc\fR. 60 60 .BE 61 61 .SH DESCRIPTION 62 62 .PP 63 63 These functions are convenience procedures for creating 64 64 channels that communicate over TCP sockets. 65 65 The operations on a channel ................................................................................ 123 123 allow connections from any network interface. 124 124 Each time a client connects to this socket, Tcl creates a channel 125 125 for the new connection and invokes \fIproc\fR with information about 126 126 the channel. \fIProc\fR must match the following prototype: 127 127 .PP 128 128 .CS 129 129 typedef void \fBTcl_TcpAcceptProc\fR( 130 - ClientData \fIclientData\fR, 130 + void *\fIclientData\fR, 131 131 Tcl_Channel \fIchannel\fR, 132 132 char *\fIhostName\fR, 133 133 int \fIport\fR); 134 134 .CE 135 135 .PP 136 136 The \fIclientData\fR argument will be the same as the \fIclientData\fR 137 137 argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
Changes to doc/Panic.3.
3 3 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 4 4 '\" 5 5 .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures" 6 6 .so man.macros 7 7 .BS 8 8 '\" Note: do not modify the .SH NAME line immediately below! 9 9 .SH NAME 10 -Tcl_Panic, Tcl_SetPanicProc \- report fatal error and abort 10 +Tcl_Panic, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort 11 11 .SH SYNOPSIS 12 12 .nf 13 13 \fB#include <tcl.h>\fR 14 14 .sp 15 15 void 16 16 \fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) 17 17 .sp 18 18 void 19 19 \fBTcl_SetPanicProc\fR(\fIpanicProc\fR) 20 20 .sp 21 +void 22 +\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) 23 +.sp 21 24 .SH ARGUMENTS 22 25 .AS Tcl_PanicProc *panicProc 23 26 .AP "const char*" format in 24 27 A printf-style format string. 25 28 .AP "" arg in 26 29 Arguments matching the format string. 27 30 .AP va_list argList in ................................................................................ 46 49 In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted 47 50 error message to the standard error file of the process, and then 48 51 calls \fBabort\fR to terminate the process. \fBTcl_Panic\fR does not 49 52 return. On Windows, when a debugger is running, the formatted error 50 53 message is sent to the debugger in stead. If the windows executable 51 54 does not have a stderr channel (e.g. \fBwish.exe\fR), then a 52 55 system dialog box is used to display the panic message. 56 +.PP 57 +If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR 58 +and you want to implicitly use the stderr channel of your 59 +application's C runtime (in stead of the stderr channel of the 60 +C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR 61 +with \fBTcl_ConsolePanic\fR as its argument. On platforms which 62 +only have one C runtime (almost all platforms except Windows) 63 +\fBTcl_ConsolePanic\fR is equivalent to NULL. 53 64 .PP 54 65 \fBTcl_SetPanicProc\fR may be used to modify the behavior of 55 66 \fBTcl_Panic\fR. The \fIpanicProc\fR argument should match the 56 67 type \fBTcl_PanicProc\fR: 57 68 .PP 58 69 .CS 59 70 typedef void \fBTcl_PanicProc\fR( ................................................................................ 73 84 application or the platform. 74 85 .PP 75 86 Although the primary callers of \fBTcl_Panic\fR are the procedures of 76 87 the Tcl library, \fBTcl_Panic\fR is a public function and may be called 77 88 by any extension or application that wishes to abort the process and 78 89 have a panic message displayed the same way that panic messages from Tcl 79 90 will be displayed. 91 +.PP 92 +This function can not be used in stub-enabled extensions. 80 93 .SH "SEE ALSO" 81 94 abort(3), printf(3), exec(n), format(n) 82 95 .SH KEYWORDS 83 96 abort, fatal, error
Changes to doc/ParseArgs.3.
27 27 stored in \fIremObjv\fR. 28 28 .AP "Tcl_Obj *const" *objv in 29 29 The array of arguments to be parsed. 30 30 .AP Tcl_Obj ***remObjv out 31 31 Pointer to a variable that will hold the array of unprocessed arguments. 32 32 Should be NULL if no return of unprocessed arguments is required. If 33 33 \fIobjcPtr\fR is updated to a non-zero value, the array returned through this 34 -must be deallocated using \fBckfree\fR. 34 +must be deallocated using \fBTcl_Free\fR. 35 35 .BE 36 36 .SH DESCRIPTION 37 37 .PP 38 38 The \fBTcl_ParseArgsObjv\fR function provides a system for parsing argument 39 39 lists of the form 40 40 .QW "\fB\-someName \fIsomeValue\fR ..." . 41 41 Such argument lists are commonly found both in the arguments to a program and ................................................................................ 80 80 .CS 81 81 typedef struct { 82 82 int \fItype\fR; 83 83 const char *\fIkeyStr\fR; 84 84 void *\fIsrcPtr\fR; 85 85 void *\fIdstPtr\fR; 86 86 const char *\fIhelpStr\fR; 87 - ClientData \fIclientData\fR; 87 + void *\fIclientData\fR; 88 88 } \fBTcl_ArgvInfo\fR; 89 89 .CE 90 90 .PP 91 91 The \fIkeyStr\fR field contains the name of the option; by convention, this 92 92 will normally begin with a 93 93 .QW \fB\-\fR 94 94 character. The \fItype\fR, \fIsrcPtr\fR, \fIdstPtr\fR and \fIclientData\fR ................................................................................ 99 99 As noted above, the \fItype\fR field is used to describe the interpretation of 100 100 the argument's value. The following values are acceptable values for 101 101 \fItype\fR: 102 102 .TP 103 103 \fBTCL_ARGV_CONSTANT\fR 104 104 . 105 105 The argument does not take any following value argument. If this argument is 106 -present, the int pointed to by the \fIsrcPtr\fR field is copied to the 107 -\fIdstPtr\fR field. The \fIclientData\fR field is ignored. 106 +present, the \fIsrcPtr\fR field (casted to \fIint\fR) is copied to the variable 107 +pointed to by the \fIdstPtr\fR field. The \fIclientData\fR field is ignored. 108 108 .TP 109 109 \fBTCL_ARGV_END\fR 110 110 . 111 111 This value marks the end of all option descriptors in the table. All other 112 112 fields are ignored. 113 113 .TP 114 114 \fBTCL_ARGV_FLOAT\fR ................................................................................ 123 123 This argument optionally takes a following value argument; it is up to the 124 124 handler callback function passed in \fIsrcPtr\fR to decide. That function will 125 125 have the following signature: 126 126 .RS 127 127 .PP 128 128 .CS 129 129 typedef int (\fBTcl_ArgvFuncProc\fR)( 130 - ClientData \fIclientData\fR, 130 + void *\fIclientData\fR, 131 131 Tcl_Obj *\fIobjPtr\fR, 132 132 void *\fIdstPtr\fR); 133 133 .CE 134 134 .PP 135 135 The result is a boolean value indicating whether to consume the following 136 136 argument. The \fIclientData\fR is the value from the table entry, the 137 137 \fIobjPtr\fR is the value that represents the following argument or NULL if ................................................................................ 145 145 function passed in \fIsrcPtr\fR returns how many (or a negative number to 146 146 signal an error, in which case it should also set the interpreter result). The 147 147 function will have the following signature: 148 148 .RS 149 149 .PP 150 150 .CS 151 151 typedef int (\fBTcl_ArgvGenFuncProc\fR)( 152 - ClientData \fIclientData\fR, 152 + void *\fIclientData\fR, 153 153 Tcl_Interp *\fIinterp\fR, 154 154 int \fIobjc\fR, 155 155 Tcl_Obj *const *\fIobjv\fR, 156 156 void *\fIdstPtr\fR); 157 157 .CE 158 158 .PP 159 159 The \fIclientData\fR is the value from the table entry, the \fIinterp\fR is
Changes to doc/ParseCmd.3.
204 204 int \fInumTokens\fR; 205 205 ... 206 206 } \fBTcl_Parse\fR; 207 207 208 208 typedef struct Tcl_Token { 209 209 int \fItype\fR; 210 210 const char *\fIstart\fR; 211 - int \fIsize\fR; 212 - int \fInumComponents\fR; 211 + size_t \fIsize\fR; 212 + size_t \fInumComponents\fR; 213 213 } \fBTcl_Token\fR; 214 214 .CE 215 215 .PP 216 216 The first five fields of a Tcl_Parse structure 217 217 are filled in only by \fBTcl_ParseCommand\fR. 218 218 These fields are not used by the other parsing procedures. 219 219 .PP
Changes to doc/Preserve.3.
17 17 \fBTcl_Preserve\fR(\fIclientData\fR) 18 18 .sp 19 19 \fBTcl_Release\fR(\fIclientData\fR) 20 20 .sp 21 21 \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR) 22 22 .SH ARGUMENTS 23 23 .AS Tcl_FreeProc clientData 24 -.AP ClientData clientData in 24 +.AP void *clientData in 25 25 Token describing structure to be freed or reallocated. Usually a pointer 26 26 to memory for structure. 27 27 .AP Tcl_FreeProc *freeProc in 28 28 Procedure to invoke to free \fIclientData\fR. 29 29 .BE 30 30 .SH DESCRIPTION 31 31 .PP ................................................................................ 87 87 same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. 88 88 The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the 89 89 \fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical 90 90 reasons, but the value is the same. 91 91 .PP 92 92 When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR 93 93 refers to storage allocated and returned by a prior call to 94 -\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library, 94 +\fBTcl_Alloc\fR or another function of the Tcl library, 95 95 then the \fIfreeProc\fR argument should be given the special value of 96 96 \fBTCL_DYNAMIC\fR. 97 97 .PP 98 98 This mechanism can be used to solve the problem described above 99 99 by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around 100 100 actions that may cause undesired storage re-allocation. The 101 101 mechanism is intended only for short-term use (i.e. while procedures
Changes to doc/RegExp.3.
60 60 by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR. 61 61 .AP char *start in 62 62 If \fItext\fR is just a portion of some other string, this argument 63 63 identifies the beginning of the larger string. 64 64 If it is not the same as \fItext\fR, then no 65 65 .QW \fB^\fR 66 66 matches will be allowed. 67 -.AP int index in 67 +.AP size_t index in 68 68 Specifies which range is desired: 0 means the range of the entire 69 69 match, 1 or greater means the range that matched a parenthesized 70 70 sub-expression. 71 71 .AP "const char" **startPtr out 72 72 The address of the first character in the range is stored here, or 73 73 NULL if there is no such range. 74 74 .AP "const char" **endPtr out ................................................................................ 76 76 is stored here, or NULL if there is no such range. 77 77 .AP int cflags in 78 78 OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR, 79 79 \fBTCL_REG_EXTENDED\fR, \fBTCL_REG_BASIC\fR, \fBTCL_REG_EXPANDED\fR, 80 80 \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR, 81 81 \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and 82 82 \fBTCL_REG_CANMATCH\fR. See below for more information. 83 -.AP int offset in 83 +.AP size_t offset in 84 84 The character offset into the text where matching should begin. 85 85 The value of the offset has no impact on \fB^\fR matches. This 86 86 behavior is controlled by \fIeflags\fR. 87 -.AP int nmatches in 87 +.AP size_t nmatches in 88 88 The number of matching subexpressions that should be remembered for 89 89 later use. If this value is 0, then no subexpression match 90 -information will be computed. If the value is \-1, then 90 +information will be computed. If the value is TCL_INDEX_NONE, then 91 91 all of the matching subexpressions will be remembered. Any other 92 92 value will be taken as the maximum number of subexpressions to 93 93 remember. 94 94 .AP int eflags in 95 95 OR-ed combination of the execution flags \fBTCL_REG_NOTBOL\fR and 96 96 \fBTCL_REG_NOTEOL\fR. See below for more information. 97 97 .AP Tcl_RegExpInfo *infoPtr out ................................................................................ 333 333 \fBTcl_RegExpGetInfo\fR retrieves information about the last match 334 334 performed with a given regular expression \fIregexp\fR. The 335 335 \fIinfoPtr\fR argument contains a pointer to a structure that is 336 336 defined as follows: 337 337 .PP 338 338 .CS 339 339 typedef struct Tcl_RegExpInfo { 340 - int \fInsubs\fR; 340 + size_t \fInsubs\fR; 341 341 Tcl_RegExpIndices *\fImatches\fR; 342 - long \fIextendStart\fR; 342 + size_t \fIextendStart\fR; 343 343 } \fBTcl_RegExpInfo\fR; 344 344 .CE 345 345 .PP 346 346 The \fInsubs\fR field contains a count of the number of parenthesized 347 347 subexpressions within the regular expression. If the \fBTCL_REG_NOSUB\fR 348 348 was used, then this value will be zero. The \fImatches\fR field 349 349 points to an array of \fInsubs\fR+1 values that indicate the bounds of each ................................................................................ 351 351 range matched by the entire regular expression, and subsequent elements 352 352 refer to the parenthesized subexpressions in the order that they 353 353 appear in the pattern. Each element is a structure that is defined as 354 354 follows: 355 355 .PP 356 356 .CS 357 357 typedef struct Tcl_RegExpIndices { 358 - long \fIstart\fR; 359 - long \fIend\fR; 358 + size_t \fIstart\fR; 359 + size_t \fIend\fR; 360 360 } \fBTcl_RegExpIndices\fR; 361 361 .CE 362 362 .PP 363 363 The \fIstart\fR and \fIend\fR values are Unicode character indices 364 364 relative to the offset location within \fIobjPtr\fR where matching began. 365 365 The \fIstart\fR index identifies the first character of the matched 366 366 subexpression. The \fIend\fR index identifies the first character
Changes to doc/SaveResult.3.
1 1 '\" 2 2 '\" Copyright (c) 1997 by Sun Microsystems, Inc. 3 3 '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright) 4 +'\" Copyright (c) 2018 Nathan Coulter. 4 5 '\" 5 6 '\" See the file "license.terms" for information on usage and redistribution 6 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 8 '\" 8 9 .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" 9 10 .so man.macros 10 11 .BS 11 12 .SH NAME 12 -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state 13 +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, 14 +Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the 15 +state of an an interpreter. 13 16 .SH SYNOPSIS 14 17 .nf 15 18 \fB#include <tcl.h>\fR 16 19 .sp 17 20 Tcl_InterpState 18 21 \fBTcl_SaveInterpState\fR(\fIinterp, status\fR) 19 22 .sp ................................................................................ 26 29 .sp 27 30 \fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR) 28 31 .sp 29 32 \fBTcl_DiscardResult\fR(\fIsavedPtr\fR) 30 33 .SH ARGUMENTS 31 34 .AS Tcl_InterpState savedPtr 32 35 .AP Tcl_Interp *interp in 33 -Interpreter for which state should be saved. 36 +The interpreter for the operation. 34 37 .AP int status in 35 -Return code value to save as part of interpreter state. 38 +The return code for the state. 36 39 .AP Tcl_InterpState state in 37 -Saved state token to be restored or discarded. 40 +A token for saved state. 38 41 .AP Tcl_SavedResult *savedPtr in 39 -Pointer to location where interpreter result should be saved or restored. 42 +A pointer to storage for saved state. 40 43 .BE 41 44 .SH DESCRIPTION 42 45 .PP 43 -These routines allows a C procedure to take a snapshot of the current 44 -state of an interpreter so that it can be restored after a call 45 -to \fBTcl_Eval\fR or some other routine that modifies the interpreter 46 -state. There are two triplets of routines meant to work together. 46 +These routines save the state of an interpreter before a call to a routine such 47 +as \fBTcl_Eval\fR, and restore the state afterwards. 48 +.PP 49 +\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the 50 +result of a script, including the resulting value, the return code passed as 51 +\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR. 52 +It returns a token for the saved state. The interpreter result is not reset 53 +and no interpreter state is changed. 54 +.PP 55 +\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and 56 +returns the \fIstatus\fR originally passed in the corresponding call to 57 +\fBTcl_SaveInterpState\fR. 58 +.PP 59 +If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called 60 +to release it. A token used to discard or restore state must not be used 61 +again. 47 62 .PP 48 -The first triplet stores the snapshot of interpreter state in 49 -an opaque token returned by \fBTcl_SaveInterpState\fR. That token 50 -value may then be passed back to one of \fBTcl_RestoreInterpState\fR 51 -or \fBTcl_DiscardInterpState\fR, depending on whether the interp 52 -state is to be restored. So long as one of the latter two routines 53 -is called, Tcl will take care of memory management. 63 +\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are 64 +deprecated. Instead use \fBTcl_SaveInterpState\fR, 65 +\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more 66 +capable. 54 67 .PP 55 -The second triplet stores the snapshot of only the interpreter 56 -result (not its complete state) in memory allocated by the caller. 57 -These routines are passed a pointer to \fBTcl_SavedResult\fR 58 -that is used to store enough information to restore the interpreter result. 59 -\fBTcl_SavedResult\fR can be allocated on the stack of the calling 60 -procedure. These routines do not save the state of any error 61 -information in the interpreter (e.g. the \fB\-errorcode\fR or 62 -\fB\-errorinfo\fR return options, when an error is in progress). 68 +\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location 69 +\fIstatePtr\fR points to and returns the interpreter result to its initial 70 +state. It does not save options such as \fB\-errorcode\fR or 71 +\fB\-errorinfo\fR. 63 72 .PP 64 -Because the routines \fBTcl_SaveInterpState\fR, 65 -\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform 66 -a superset of the functions provided by the other routines, 67 -any new code should only make use of the more powerful routines. 68 -The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, 69 -and \fBTcl_DiscardResult\fR continue to exist only for the sake 70 -of existing programs that may already be using them. 73 +\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and 74 +moves the result from \fIstatePtr\fR back to \fIinterp\fR. \fIstatePtr\fR is 75 +then in an undefined state and must not be used until passed again to 76 +\fBTcl_SaveResult\fR. 71 77 .PP 72 -\fBTcl_SaveInterpState\fR takes a snapshot of those portions of 73 -interpreter state that make up the full result of script evaluation. 74 -This include the interpreter result, the return code (passed in 75 -as the \fIstatus\fR argument, and any return options, including 76 -\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress. 77 -This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR. 78 -The call to \fBTcl_SaveInterpState\fR does not itself change the 79 -state of the interpreter. Unlike \fBTcl_SaveResult\fR, it does 80 -not reset the interpreter. 81 -.PP 82 -\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token 83 -previously returned by \fBTcl_SaveInterpState\fR and restores the 84 -state of the interp to the state held in that snapshot. The return 85 -value of \fBTcl_RestoreInterpState\fR is the status value originally 86 -passed to \fBTcl_SaveInterpState\fR when the snapshot token was 87 -created. 88 -.PP 89 -\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR 90 -token previously returned by \fBTcl_SaveInterpState\fR when that 91 -snapshot is not to be restored to an interp. 92 -.PP 93 -The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR 94 -must eventually be passed to either \fBTcl_RestoreInterpState\fR 95 -or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once 96 -the \fBTcl_InterpState\fR token is passed to one of them, the 97 -token is no longer valid and should not be used anymore. 98 -.PP 99 -\fBTcl_SaveResult\fR moves the string and value results 100 -of \fIinterp\fR into the location specified by \fIstatePtr\fR. 101 -\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and 102 -leaves the result in its normal empty initialized state. 103 -.PP 104 -\fBTcl_RestoreResult\fR moves the string and value results from 105 -\fIstatePtr\fR back into \fIinterp\fR. Any result or error that was 106 -already in the interpreter will be cleared. The \fIstatePtr\fR is left 107 -in an uninitialized state and cannot be used until another call to 78 +\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is 79 +then in an undefined state and must not be used until passed again to 108 80 \fBTcl_SaveResult\fR. 109 81 .PP 110 -\fBTcl_DiscardResult\fR releases the saved interpreter state 111 -stored at \fBstatePtr\fR. The state structure is left in an 112 -uninitialized state and cannot be used until another call to 113 -\fBTcl_SaveResult\fR. 114 -.PP 115 -Once \fBTcl_SaveResult\fR is called to save the interpreter 116 -result, either \fBTcl_RestoreResult\fR or 117 -\fBTcl_DiscardResult\fR must be called to properly clean up the 118 -memory associated with the saved state. 82 +If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to 83 +release it. 119 84 .SH KEYWORDS 120 85 result, state, interp
Changes to doc/SplitList.3.
16 16 .sp 17 17 int 18 18 \fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR) 19 19 .sp 20 20 char * 21 21 \fBTcl_Merge\fR(\fIargc, argv\fR) 22 22 .sp 23 -int 23 +size_t 24 24 \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR) 25 25 .sp 26 -int 26 +size_t 27 27 \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR) 28 28 .sp 29 -int 29 +size_t 30 30 \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR) 31 31 .sp 32 -int 32 +size_t 33 33 \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR) 34 34 .SH ARGUMENTS 35 35 .AS "const char *const" ***argvPtr out 36 36 .AP Tcl_Interp *interp out 37 37 Interpreter to use for error reporting. If NULL, then no error message 38 38 is left. 39 39 .AP char *list in ................................................................................ 51 51 Array of strings to merge together into a single list. 52 52 Each string will become a separate element of the list. 53 53 .AP "const char" *src in 54 54 String that is to become an element of a list. 55 55 .AP int *flagsPtr in 56 56 Pointer to word to fill in with information about \fIsrc\fR. 57 57 The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR. 58 -.AP int length in 58 +.AP size_t length in 59 59 Number of bytes in string \fIsrc\fR. 60 60 .AP char *dst in 61 61 Place to copy converted list element. Must contain enough characters 62 62 to hold converted string. 63 63 .AP int flags in 64 64 Information about \fIsrc\fR. Must be value returned by previous 65 65 call to \fBTcl_ScanElement\fR, possibly OR-ed
Changes to doc/StaticPkg.3.
60 60 The \fIinterp\fR argument identifies the interpreter in which the package 61 61 is to be loaded. The initialization procedure must return \fBTCL_OK\fR or 62 62 \fBTCL_ERROR\fR to indicate whether or not it completed successfully; in 63 63 the event of an error it should set the interpreter's result to point to an 64 64 error message. The result or error from the initialization procedure will 65 65 be returned as the result of the \fBload\fR command that caused the 66 66 initialization procedure to be invoked. 67 +.PP 68 +This function can not be used in stub-enabled extensions. 67 69 .SH KEYWORDS 68 70 initialization procedure, package, static linking 69 71 .SH "SEE ALSO" 70 72 load(n), package(n), Tcl_PkgRequire(3)
Changes to doc/StringObj.3.
33 33 .sp 34 34 Tcl_UniChar * 35 35 \fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR) 36 36 .sp 37 37 Tcl_UniChar * 38 38 \fBTcl_GetUnicode\fR(\fIobjPtr\fR) 39 39 .sp 40 -Tcl_UniChar 40 +int 41 41 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) 42 42 .sp 43 43 int 44 44 \fBTcl_GetCharLength\fR(\fIobjPtr\fR) 45 45 .sp 46 46 Tcl_Obj * 47 47 \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) ................................................................................ 83 83 \fBTcl_ConcatObj\fR(\fIobjc, objv\fR) 84 84 .SH ARGUMENTS 85 85 .AS "const Tcl_UniChar" *appendObjPtr in/out 86 86 .AP "const char" *bytes in 87 87 Points to the first byte of an array of UTF-8-encoded bytes 88 88 used to set or append to a string value. 89 89 This byte array may contain embedded null characters 90 -unless \fInumChars\fR is negative. (Applications needing null bytes 90 +unless \fInumChars\fR is TCL_AUTO_LENGTH. (Applications needing null bytes 91 91 should represent them as the two-byte sequence \fI\e700\e600\fR, use 92 92 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if 93 93 the string is a collection of uninterpreted bytes.) 94 -.AP int length in 94 +.AP size_t length in 95 95 The number of bytes to copy from \fIbytes\fR when 96 96 initializing, setting, or appending to a string value. 97 -If negative, all bytes up to the first null are used. 97 +If TCL_AUTO_LENGTH, all bytes up to the first null are used. 98 98 .AP "const Tcl_UniChar" *unicode in 99 99 Points to the first byte of an array of Unicode characters 100 100 used to set or append to a string value. 101 101 This byte array may contain embedded null characters 102 102 unless \fInumChars\fR is negative. 103 -.AP int numChars in 103 +.AP size_t numChars in 104 104 The number of Unicode characters to copy from \fIunicode\fR when 105 105 initializing, setting, or appending to a string value. 106 -If negative, all characters up to the first null character are used. 107 -.AP int index in 106 +If TCL_AUTO_LENGTH, all characters up to the first null character are used. 107 +.AP size_t index in 108 108 The index of the Unicode character to return. 109 -.AP int first in 109 +.AP size_t first in 110 110 The index of the first Unicode character in the Unicode range to be 111 111 returned as a new value. 112 -.AP int last in 112 +.AP size_t last in 113 113 The index of the last Unicode character in the Unicode range to be 114 114 returned as a new value. 115 115 .AP Tcl_Obj *objPtr in/out 116 116 Points to a value to manipulate. 117 117 .AP Tcl_Obj *appendObjPtr in 118 118 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. 119 119 .AP int *lengthPtr out ................................................................................ 120 120 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store 121 121 the length of a value's string representation. 122 122 .AP "const char" *string in 123 123 Null-terminated string value to append to \fIobjPtr\fR. 124 124 .AP va_list argList in 125 125 An argument list which must have been initialized using 126 126 \fBva_start\fR, and cleared using \fBva_end\fR. 127 -.AP int limit in 127 +.AP size_t limit in 128 128 Maximum number of bytes to be appended. 129 129 .AP "const char" *ellipsis in 130 130 Suffix to append when the limit leads to string truncation. 131 131 If NULL is passed then the suffix 132 132 .QW "..." 133 133 is used. 134 134 .AP "const char" *format in 135 135 Format control string including % conversion specifiers. 136 136 .AP int objc in 137 137 The number of elements to format or concatenate. 138 138 .AP Tcl_Obj *objv[] in 139 139 The array of values to format or concatenate. 140 -.AP int newLength in 140 +.AP size_t newLength in 141 141 New length for the string value of \fIobjPtr\fR, not including the 142 142 final null character. 143 143 .BE 144 144 .SH DESCRIPTION 145 145 .PP 146 146 The procedures described in this manual entry allow Tcl values to 147 147 be manipulated as string values. They use the internal representation ................................................................................ 197 197 \fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned 198 198 byte pointer is owned by the value manager and should not be modified by 199 199 the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case 200 200 where the caller does not need the length of the unicode string 201 201 representation. 202 202 .PP 203 203 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the 204 -value's Unicode representation. 204 +value's Unicode representation. If the index is out of range or 205 +it references a low surrogate preceded by a high surrogate, it returns -1; 205 206 .PP 206 207 \fBTcl_GetRange\fR returns a newly created value comprised of the 207 208 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the 208 209 value's Unicode representation. If the value's Unicode 209 210 representation is invalid, the Unicode representation is regenerated 210 211 from the value's string representation. 211 212 .PP
Changes to doc/TCL_MEM_DEBUG.3.
30 30 .PP 31 31 Once memory debugging support has been compiled into Tcl, the C 32 32 functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR, 33 33 and the Tcl \fBmemory\fR command can be used to validate and examine 34 34 memory usage. 35 35 .SH "GUARD ZONES" 36 36 .PP 37 -When memory debugging is enabled, whenever a call to \fBckalloc\fR is 37 +When memory debugging is enabled, whenever a call to \fBTcl_Alloc\fR is 38 38 made, slightly more memory than requested is allocated so the memory 39 39 debugging code can keep track of the allocated memory, and eight-byte 40 40 .QW "guard zones" 41 41 are placed in front of and behind the space that will be 42 42 returned to the caller. (The sizes of the guard zones are defined by the 43 43 C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR 44 44 in the file \fIgeneric/tclCkalloc.c\fR \(em it can 45 45 be extended if you suspect large overwrite problems, at some cost in 46 46 performance.) A known pattern is written into the guard zones and, on 47 -a call to \fBckfree\fR, the guard zones of the space being freed are 47 +a call to \fBTcl_Free\fR, the guard zones of the space being freed are 48 48 checked to see if either zone has been modified in any way. If one 49 49 has been, the guard bytes and their new contents are identified, and a 50 50 .QW "low guard failed" 51 51 or 52 52 .QW "high guard failed" 53 53 message is issued. The 54 54 .QW "guard failed" 55 55 message includes the address of the memory packet and 56 -the file name and line number of the code that called \fBckfree\fR. 56 +the file name and line number of the code that called \fBTcl_Free\fR. 57 57 This allows you to detect the common sorts of one-off problems, where 58 58 not enough space was allocated to contain the data written, for 59 59 example. 60 60 .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS" 61 61 .PP 62 62 Normally, Tcl compiled with memory debugging enabled will make it easy 63 63 to isolate a corruption problem. Turning on memory validation with 64 64 the memory command can help isolate difficult problems. If you 65 65 suspect (or know) that corruption is occurring before the Tcl 66 66 interpreter comes up far enough for you to issue commands, you can set 67 67 \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl. 68 68 This will enable memory validation from the first call to 69 -\fBckalloc\fR, again, at a large performance impact. 69 +\fBTcl_Alloc\fR, again, at a large performance impact. 70 70 .PP 71 71 If you are desperate and validating memory on every call to 72 -\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call 72 +\fBTcl_Alloc\fR and \fBTcl_Free\fR is not enough, you can explicitly call 73 73 \fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar 74 74 *\fR and an \fIint\fR which are normally the filename and line number 75 75 of the caller, but they can actually be anything you want. Remember 76 76 to remove the calls after you find the problem. 77 77 .SH "SEE ALSO" 78 -ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory 78 +Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory 79 79 .SH KEYWORDS 80 80 memory, debug
Changes to doc/Tcl.n.
24 24 (see below) unless quoted. 25 25 .IP "[2] \fBEvaluation.\fR" 26 26 A command is evaluated in two steps. 27 27 First, the Tcl interpreter breaks the command into \fIwords\fR 28 28 and performs substitutions as described below. 29 29 These substitutions are performed in the same way for all 30 30 commands. 31 -Secondly, the first word is used to locate a command procedure to 32 -carry out the command, then all of the words of the command are 33 -passed to the command procedure. 34 -The command procedure is free to interpret each of its words 31 +Secondly, the first word is used to locate a routine to 32 +carry out the command, and the remaining words of the command are 33 +passed to that routine. 34 +The routine is free to interpret each of its words 35 35 in any way it likes, such as an integer, variable name, list, 36 36 or Tcl script. 37 37 Different commands interpret their words differently. 38 38 .IP "[3] \fBWords.\fR" 39 39 Words of a command are separated by white space (except for 40 40 newlines, which are command separators). 41 41 .IP "[4] \fBDouble quotes.\fR"
Changes to doc/TclZlib.3.
84 84 section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this 85 85 dictionary. 86 86 .AP "unsigned int" initValue in 87 87 The initial value for the checksum algorithm. 88 88 .AP "unsigned char" *bytes in 89 89 An array of bytes to run the checksum algorithm over, or NULL to get the 90 90 recommended initial value for the checksum algorithm. 91 -.AP int length in 91 +.AP size_t length in 92 92 The number of bytes in the array. 93 93 .AP int mode in 94 94 What mode to operate the stream in. Should be either 95 95 \fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or 96 96 \fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream. 97 97 .AP Tcl_ZlibStream *zshandlePtr out 98 98 A pointer to a variable in which to write the abstract token for the stream ................................................................................ 103 103 Whether and how to flush the stream after writing the data to it. Must be one 104 104 of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR 105 105 if the currently compressed data must be made available for access using 106 106 \fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put 107 107 into a state where the decompressor can recover from on corruption, or 108 108 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any 109 109 trailer demanded by the format is written. 110 -.AP int count in 111 -The maximum number of bytes to get from the stream, or -1 to get all remaining 112 -bytes from the stream's buffers. 110 +.AP size_t count in 111 +The maximum number of bytes to get from the stream, or TCL_AUTO_LENGTH to get 112 +all remaining bytes from the stream's buffers. 113 113 .AP Tcl_Obj *compDict in 114 114 A byte array value that is the compression dictionary to use with the stream. 115 115 Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this 116 116 only ever be used with streams that were created with their \fIformat\fR set 117 117 to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to 118 118 indicate whether a compression dictionary was present other than to fail on 119 119 decompression.
Changes to doc/Tcl_Main.3.
185 185 evaluated. In interactive mode, if an EOF or channel error 186 186 is encountered on the standard input channel, then \fBTcl_Main\fR 187 187 itself will evaluate the \fBexit\fR command after the main loop 188 188 procedure (if any) returns. In non-interactive mode, after 189 189 \fBTcl_Main\fR evaluates the startup script, and the main loop 190 190 procedure (if any) returns, \fBTcl_Main\fR will also evaluate 191 191 the \fBexit\fR command. 192 +.PP 193 +This function can not be used in stub-enabled extensions. 192 194 .SH "SEE ALSO" 193 195 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), 194 196 exit(n), encoding(n) 195 197 .SH KEYWORDS 196 198 application-specific initialization, command-line arguments, main program
Changes to doc/Thread.3.
41 41 int 42 42 \fBTcl_JoinThread\fR(\fIid, result\fR) 43 43 .SH ARGUMENTS 44 44 .AS Tcl_CreateThreadProc proc out 45 45 .AP Tcl_Condition *condPtr in 46 46 A condition variable, which must be associated with a mutex lock. 47 47 .AP Tcl_Mutex *mutexPtr in 48 -A mutex lock. 48 +.VS TIP509 49 +A recursive mutex lock. 50 +.VE TIP509 49 51 .AP "const Tcl_Time" *timePtr in 50 52 A time limit on the condition wait. NULL to wait forever. 51 53 Note that a polling value of 0 seconds does not make much sense. 52 54 .AP Tcl_ThreadDataKey *keyPtr in 53 55 This identifies a block of thread local storage. The key should be 54 56 static and process-wide, yet each thread will end up associating 55 57 a different block of storage with this key. ................................................................................ 61 63 The referred storage will contain the id of the newly created thread as 62 64 returned by the operating system. 63 65 .AP Tcl_ThreadId id in 64 66 Id of the thread waited upon. 65 67 .AP Tcl_ThreadCreateProc *proc in 66 68 This procedure will act as the \fBmain()\fR of the newly created 67 69 thread. The specified \fIclientData\fR will be its sole argument. 68 -.AP ClientData clientData in 70 +.AP void *clientData in 69 71 Arbitrary information. Passed as sole argument to the \fIproc\fR. 70 72 .AP int stackSize in 71 73 The size of the stack given to the new thread. 72 74 .AP int flags in 73 75 Bitmask containing flags allowing the caller to modify behavior of 74 76 the new thread. 75 77 .AP int *result out ................................................................................ 136 138 the \fBNotifier\fR manual page for more information on these procedures. 137 139 .PP 138 140 A mutex is a lock that is used to serialize all threads through a piece 139 141 of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. 140 142 If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will 141 143 block until \fBTcl_MutexUnlock\fR is called. 142 144 A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. 143 -The result of locking a mutex twice from the same thread is undefined. 144 -On some platforms it will result in a deadlock. 145 +.VS TIP509 146 +Mutexes are reentrant: they can be locked several times from the same 147 +thread. However there must be exactly one call to 148 +\fBTcl_MutexUnlock\fR for each call to \fBTcl_MutexLock\fR in order 149 +for a thread to release a mutex completely. 150 +.VE TIP509 145 151 The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR 146 152 procedures are defined as empty macros if not compiling with threads enabled. 147 153 For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. 148 154 This macro assures correct mutex handling even when the core is compiled 149 155 without threads enabled. 150 156 .PP 151 157 A condition variable is used as a signaling mechanism: ................................................................................ 198 204 .PP 199 205 It should then be defined like this example, which just counts up to a given 200 206 value and then finishes. 201 207 .PP 202 208 .CS 203 209 static \fBTcl_ThreadCreateType\fR 204 210 MyThreadImplFunc( 205 - ClientData clientData) 211 + void *clientData) 206 212 { 207 213 int i, limit = (int) clientData; 208 214 for (i=0 ; i<limit ; i++) { 209 215 /* doing nothing at all here */ 210 216 } 211 217 \fBTCL_THREAD_CREATE_RETURN\fR; 212 218 } ................................................................................ 213 219 .CE 214 220 .PP 215 221 To create the above thread, make it execute, and wait for it to finish, we 216 222 would do this: 217 223 .PP 218 224 .CS 219 225 int limit = 1000000000; 220 -ClientData limitData = (void*)((intptr_t) limit); 226 +void *limitData = (void*)((intptr_t) limit); 221 227 Tcl_ThreadId id; \fI/* holds identity of thread created */\fR 222 228 int result; 223 229 224 230 if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData, 225 231 \fBTCL_THREAD_STACK_DEFAULT\fR, 226 232 \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) { 227 233 \fI/* Thread did not create correctly */\fR
Changes to doc/ToUpper.3.
9 9 .BS 10 10 .SH NAME 11 11 Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 -Tcl_UniChar 16 +int 17 17 \fBTcl_UniCharToUpper\fR(\fIch\fR) 18 18 .sp 19 -Tcl_UniChar 19 +int 20 20 \fBTcl_UniCharToLower\fR(\fIch\fR) 21 21 .sp 22 -Tcl_UniChar 22 +int 23 23 \fBTcl_UniCharToTitle\fR(\fIch\fR) 24 24 .sp 25 25 int 26 26 \fBTcl_UtfToUpper\fR(\fIstr\fR) 27 27 .sp 28 28 int 29 29 \fBTcl_UtfToLower\fR(\fIstr\fR) ................................................................................ 74 74 \fBTcl_UtfToLower\fR is the same as \fBTcl_UtfToUpper\fR except it 75 75 turns each character in the string into its lower-case equivalent. 76 76 .PP 77 77 \fBTcl_UtfToTitle\fR is the same as \fBTcl_UtfToUpper\fR except it 78 78 turns the first character in the string into its title-case equivalent 79 79 and all following characters into their lower-case equivalents. 80 80 81 -.SH BUGS 82 -.PP 83 -At this time, the case conversions are only defined for the ISO8859-1 84 -characters. Unicode characters above 0x00ff are not modified by these 85 -routines. 86 - 87 81 .SH KEYWORDS 88 82 utf, unicode, toupper, tolower, totitle, case
Changes to doc/TraceCmd.3.
9 9 .BS 10 10 .SH NAME 11 11 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command 12 12 .SH SYNOPSIS 13 13 .nf 14 14 \fB#include <tcl.h>\fR 15 15 .sp 16 -ClientData 16 +void * 17 17 \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR 18 18 .sp 19 19 int 20 20 \fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR 21 21 .sp 22 22 void 23 23 \fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR ................................................................................ 28 28 .AP "const char" *cmdName in 29 29 Name of command. 30 30 .AP int flags in 31 31 OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and 32 32 \fBTCL_TRACE_DELETE\fR. 33 33 .AP Tcl_CommandTraceProc *proc in 34 34 Procedure to call when specified operations occur to \fIcmdName\fR. 35 -.AP ClientData clientData in 35 +.AP void *clientData in 36 36 Arbitrary argument to pass to \fIproc\fR. 37 -.AP ClientData prevClientData in 37 +.AP void *prevClientData in 38 38 If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, 39 39 so this call will return information about next trace. If NULL, this 40 40 call will return information about first trace. 41 41 .BE 42 42 .SH DESCRIPTION 43 43 .PP 44 44 \fBTcl_TraceCommand\fR allows a C procedure to monitor operations ................................................................................ 61 61 .PP 62 62 Whenever one of the specified operations occurs to the command, 63 63 \fIproc\fR will be invoked. It should have arguments and result that 64 64 match the type \fBTcl_CommandTraceProc\fR: 65 65 .PP 66 66 .CS 67 67 typedef void \fBTcl_CommandTraceProc\fR( 68 - ClientData \fIclientData\fR, 68 + void *\fIclientData\fR, 69 69 Tcl_Interp *\fIinterp\fR, 70 70 const char *\fIoldName\fR, 71 71 const char *\fInewName\fR, 72 72 int \fIflags\fR); 73 73 .CE 74 74 .PP 75 75 The \fIclientData\fR and \fIinterp\fR parameters will have the same 76 76 values as those passed to \fBTcl_TraceCommand\fR when the trace was 77 -created. \fIClientData\fR typically points to an application-specific 77 +created. \fIclientData\fR typically points to an application-specific 78 78 data structure that describes what to do when \fIproc\fR is invoked. 79 79 \fIOldName\fR gives the name of the command being renamed, and 80 80 \fInewName\fR gives the name that the command is being renamed to (or 81 81 NULL when the command is being deleted.) 82 82 \fIFlags\fR is an OR'ed combination of bits potentially providing 83 83 several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and 84 84 \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
Changes to doc/TraceVar.3.
20 20 int 21 21 \fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR 22 22 .sp 23 23 \fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR 24 24 .sp 25 25 \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR 26 26 .sp 27 -ClientData 27 +void * 28 28 \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR 29 29 .sp 30 -ClientData 30 +void * 31 31 \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR 32 32 .SH ARGUMENTS 33 -.AS Tcl_VarTraceProc prevClientData 33 +.AS void *prevClientData 34 34 .AP Tcl_Interp *interp in 35 35 Interpreter containing variable. 36 36 .AP "const char" *varName in 37 37 Name of variable. May refer to a scalar variable, to 38 38 an array variable with no index, or to an array variable 39 39 with a parenthesized index. 40 40 .AP int flags in ................................................................................ 42 42 \fBTCL_TRACE_WRITES\fR, \fBTCL_TRACE_UNSETS\fR, \fBTCL_TRACE_ARRAY\fR, 43 43 \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR, 44 44 \fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR. 45 45 Not all flags are used by all 46 46 procedures. See below for more information. 47 47 .AP Tcl_VarTraceProc *proc in 48 48 Procedure to invoke whenever one of the traced operations occurs. 49 -.AP ClientData clientData in 49 +.AP void *clientData in 50 50 Arbitrary one-word value to pass to \fIproc\fR. 51 51 .AP "const char" *name1 in 52 52 Name of scalar or array variable (without array index). 53 53 .AP "const char" *name2 in 54 54 For a trace on an element of an array, gives the index of the 55 55 element. For traces on scalar variables or on whole arrays, 56 56 is NULL. 57 -.AP ClientData prevClientData in 57 +.AP void *prevClientData in 58 58 If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or 59 59 \fBTcl_VarTraceInfo2\fR, so this call will return information about 60 60 next trace. If NULL, this call will return information about first 61 61 trace. 62 62 .BE 63 63 .SH DESCRIPTION 64 64 .PP ................................................................................ 103 103 This gives the trace procedure a chance to update the array before 104 104 array names or array get is called. Note that this is called 105 105 before an array set, but that will trigger write traces. 106 106 .TP 107 107 \fBTCL_TRACE_RESULT_DYNAMIC\fR 108 108 The result of invoking the \fIproc\fR is a dynamically allocated 109 109 string that will be released by the Tcl library via a call to 110 -\fBckfree\fR. Must not be specified at the same time as 110 +\fBTcl_Free\fR. Must not be specified at the same time as 111 111 \fBTCL_TRACE_RESULT_OBJECT\fR. 112 112 .TP 113 113 \fBTCL_TRACE_RESULT_OBJECT\fR 114 114 The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*) 115 115 with a reference count of at least one. The ownership of that 116 116 reference will be transferred to the Tcl core for release (when the 117 117 core has finished with it) via a call to \fBTcl_DecrRefCount\fR. Must ................................................................................ 120 120 Whenever one of the specified operations occurs on the variable, 121 121 \fIproc\fR will be invoked. 122 122 It should have arguments and result that match the type 123 123 \fBTcl_VarTraceProc\fR: 124 124 .PP 125 125 .CS 126 126 typedef char *\fBTcl_VarTraceProc\fR( 127 - ClientData \fIclientData\fR, 127 + void *\fIclientData\fR, 128 128 Tcl_Interp *\fIinterp\fR, 129 129 char *\fIname1\fR, 130 130 char *\fIname2\fR, 131 131 int \fIflags\fR); 132 132 .CE 133 133 .PP 134 134 The \fIclientData\fR and \fIinterp\fR parameters will 135 135 have the same values as those passed to \fBTcl_TraceVar\fR when the 136 136 trace was created. 137 -\fIClientData\fR typically points to an application-specific 137 +\fIclientData\fR typically points to an application-specific 138 138 data structure that describes what to do when \fIproc\fR 139 139 is invoked. 140 140 \fIName1\fR and \fIname2\fR give the name of the traced variable 141 141 in the normal two-part form (see the description of \fBTcl_TraceVar2\fR 142 142 below for details). 143 143 \fIFlags\fR is an OR-ed combination of bits providing several 144 144 pieces of information. ................................................................................ 308 308 successful completion. 309 309 If \fIproc\fR returns a non-NULL value it signifies that an 310 310 error occurred. 311 311 The return value must be a pointer to a static character string 312 312 containing an error message, 313 313 unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and 314 314 \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is 315 -either a dynamic string (to be released with \fBckfree\fR) or a 315 +either a dynamic string (to be released with \fBTcl_Free\fR) or a 316 316 Tcl_Obj* (cast to char* and to be released with 317 317 \fBTcl_DecrRefCount\fR) containing the error message. 318 318 If a trace procedure returns an error, no further traces are 319 319 invoked for the access and the traced access aborts with the 320 320 given message. 321 321 Trace procedures can use this facility to make variables 322 322 read-only, for example (but note that the value of the variable ................................................................................ 327 327 The return value from \fIproc\fR is only used during read and 328 328 write tracing. 329 329 During unset traces, the return value is ignored and all relevant 330 330 trace procedures will always be invoked. 331 331 .SH "RESTRICTIONS" 332 332 .PP 333 333 A trace procedure can be called at any time, even when there 334 -is a partially formed result in the interpreter's result area. If 334 +are partially formed results stored in the interpreter. If 335 335 the trace procedure does anything that could damage this result (such 336 -as calling \fBTcl_Eval\fR) then it must save the original values of 337 -the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore 338 -them before it returns. 336 +as calling \fBTcl_Eval\fR) then it must use the \fBTcl_SaveInterpState\fR 337 +and related routines to save and restore the original state of 338 +the interpreter before it returns. 339 339 .SH "UNDEFINED VARIABLES" 340 340 .PP 341 341 It is legal to set a trace on an undefined variable. 342 342 The variable will still appear to be undefined until the 343 343 first time its value is set. 344 344 If an undefined variable is traced and then unset, the unset will fail 345 345 with an error
Changes to doc/Utf.3.
27 27 Tcl_UniChar * 28 28 \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR) 29 29 .sp 30 30 int 31 31 \fBTcl_UniCharLen\fR(\fIuniStr\fR) 32 32 .sp 33 33 int 34 -\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR) 34 +\fBTcl_UniCharNcmp\fR(\fIucs, uct, uniLength\fR) 35 35 .sp 36 36 int 37 -\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR) 37 +\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, uniLength\fR) 38 38 .sp 39 39 int 40 40 \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR) 41 41 .sp 42 42 int 43 -\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR) 43 +\fBTcl_UtfNcmp\fR(\fIcs, ct, length\fR) 44 44 .sp 45 45 int 46 -\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR) 46 +\fBTcl_UtfNcasecmp\fR(\fIcs, ct, length\fR) 47 47 .sp 48 48 int 49 49 \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR) 50 50 .sp 51 51 int 52 52 \fBTcl_NumUtfChars\fR(\fIsrc, length\fR) 53 53 .sp ................................................................................ 59 59 .sp 60 60 const char * 61 61 \fBTcl_UtfNext\fR(\fIsrc\fR) 62 62 .sp 63 63 const char * 64 64 \fBTcl_UtfPrev\fR(\fIsrc, start\fR) 65 65 .sp 66 -Tcl_UniChar 66 +int 67 67 \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR) 68 68 .sp 69 69 const char * 70 70 \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR) 71 71 .sp 72 -int 72 +size_t 73 73 \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR) 74 74 .SH ARGUMENTS 75 75 .AS "const Tcl_UniChar" *uniPattern in/out 76 76 .AP char *buf out 77 77 Buffer in which the UTF-8 representation of the Tcl_UniChar is stored. At most 78 78 \fBTCL_UTF_MAX\fR bytes are stored in the buffer. 79 79 .AP int ch in ................................................................................ 90 90 A null-terminated Unicode string. 91 91 .AP "const Tcl_UniChar" *ucs in 92 92 A null-terminated Unicode string. 93 93 .AP "const Tcl_UniChar" *uct in 94 94 A null-terminated Unicode string. 95 95 .AP "const Tcl_UniChar" *uniPattern in 96 96 A null-terminated Unicode string. 97 -.AP int length in 97 +.AP size_t length in 98 98 The length of the UTF-8 string in bytes (not UTF-8 characters). If 99 -negative, all bytes up to the first null byte are used. 100 -.AP int uniLength in 101 -The length of the Unicode string in characters. Must be greater than or 102 -equal to 0. 99 +TCL_AUTO_LENGTH, all bytes up to the first null byte are used. 100 +.AP size_t uniLength in 101 +The length of the Unicode string in characters. 103 102 .AP "Tcl_DString" *dsPtr in/out 104 103 A pointer to a previously initialized \fBTcl_DString\fR. 105 -.AP "unsigned long" numChars in 106 -The number of characters to compare. 107 104 .AP "const char" *start in 108 105 Pointer to the beginning of a UTF-8 string. 109 -.AP int index in 106 +.AP size_t index in 110 107 The index of a character (not byte) in the UTF-8 string. 111 108 .AP int *readPtr out 112 109 If non-NULL, filled with the number of bytes in the backslash sequence, 113 110 including the backslash character. 114 111 .AP char *dst out 115 112 Buffer in which the bytes represented by the backslash sequence are stored. 116 113 At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer. ................................................................................ 117 114 .AP int nocase in 118 115 Specifies whether the match should be done case-sensitive (0) or 119 116 case-insensitive (1). 120 117 .BE 121 118 122 119 .SH DESCRIPTION 123 120 .PP 124 -These routines convert between UTF-8 strings and Tcl_UniChars. A 125 -Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size 121 +These routines convert between UTF-8 strings and Unicode characters. An 122 +Unicode character represented as an unsigned, fixed-size 126 123 quantity. A UTF-8 character is a Unicode character represented as 127 124 a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes. A multibyte UTF-8 128 125 sequence consists of a lead byte followed by some number of trail bytes. 129 126 .PP 130 127 \fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to 131 128 represent one Unicode character in the UTF-8 representation. 132 129 .PP 133 -\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string 130 +\fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string 134 131 in starting at \fIbuf\fR. The return value is the number of bytes stored 135 -in \fIbuf\fR. 132 +in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then 133 +the return value will be 1 and a single byte in the range 0xF0 - 0xF4 134 +will be stored. If you still want to produce UTF-8 output for it (even 135 +though knowing it's an illegal code-point on its own), just call 136 +\fBTcl_UniCharToUtf\fR again specifying ch = -1. 136 137 .PP 137 138 \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR 138 139 and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the 139 140 number of bytes read from \fIsrc\fR. The caller must ensure that the 140 141 source buffer is long enough such that this routine does not run off the 141 142 end and dereference non-existent or random memory; if the source buffer 142 143 is known to be null-terminated, this will not happen. If the input is 144 +a byte in the range 0x80 - 0x9F, \fBTcl_UtfToUniChar\fR assumes the 145 +cp1252 encoding, stores the corresponding Tcl_UniChar in \fI*chPtr\fR 146 +and returns 1. If the input is otherwise 143 147 not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first 144 148 byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and 145 149 0x00ff and return 1. 146 150 .PP 147 151 \fBTcl_UniCharToUtfDString\fR converts the given Unicode string 148 152 to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR. 149 153 You must specify \fIuniLength\fR, the length of the given Unicode string. ................................................................................ 165 169 \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode 166 170 characters. It accepts a null-terminated Unicode string and returns 167 171 the number of Unicode characters (not bytes) in that string. 168 172 .PP 169 173 \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to 170 174 \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters. 171 175 They accept two null-terminated Unicode strings and the number of characters 172 -to compare. Both strings are assumed to be at least \fInumChars\fR characters 176 +to compare. Both strings are assumed to be at least \fIuniLength\fR characters 173 177 long. \fBTcl_UniCharNcmp\fR compares the two strings character-by-character 174 178 according to the Unicode character ordering. It returns an integer greater 175 179 than, equal to, or less than 0 if the first string is greater than, equal 176 180 to, or less than the second string respectively. \fBTcl_UniCharNcasecmp\fR 177 181 is the Unicode case insensitive version. 178 182 .PP 179 183 \fBTcl_UniCharCaseMatch\fR is the Unicode equivalent to 180 184 \fBTcl_StringCaseMatch\fR. It accepts a null-terminated Unicode string, 181 185 a Unicode pattern, and a boolean value specifying whether the match should 182 186 be case sensitive and returns whether the string matches the pattern. 183 187 .PP 184 188 \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It 185 189 accepts two null-terminated UTF-8 strings and the number of characters 186 -to compare. (Both strings are assumed to be at least \fInumChars\fR 190 +to compare. (Both strings are assumed to be at least \fIlength\fR 187 191 characters long.) \fBTcl_UtfNcmp\fR compares the two strings 188 192 character-by-character according to the Unicode character ordering. 189 193 It returns an integer greater than, equal to, or less than 0 if the 190 194 first string is greater than, equal to, or less than the second string 191 195 respectively. 192 196 .PP 193 197 \fBTcl_UtfNcasecmp\fR corresponds to \fBstrncasecmp\fR for UTF-8 ................................................................................ 196 200 characters. 197 201 .PP 198 202 \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR 199 203 of \fIlength\fR bytes is long enough to be decoded by 200 204 \fBTcl_UtfToUniChar\fR, or 0 otherwise. This function does not guarantee 201 205 that the UTF-8 string is properly formed. This routine is used by 202 206 procedures that are operating on a byte at a time and need to know if a 203 -full Tcl_UniChar has been seen. 207 +full Unicode character has been seen. 204 208 .PP 205 209 \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It 206 210 returns the number of Tcl_UniChars that are represented by the UTF-8 string 207 211 \fIsrc\fR. The length of the source string is \fIlength\fR bytes. If the 208 212 length is negative, all bytes up to the first null byte are used. 209 213 .PP 210 214 \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It 211 -returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR 215 +returns a pointer to the first occurrence of the Unicode character \fIch\fR 212 216 in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is 213 217 considered part of the UTF-8 string. 214 218 .PP 215 219 \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It 216 -returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR 220 +returns a pointer to the last occurrence of the Unicode character \fIch\fR 217 221 in the null-terminated UTF-8 string \fIsrc\fR. The null terminator is 218 222 considered part of the UTF-8 string. 219 223 .PP 220 224 Given \fIsrc\fR, a pointer to some location in a UTF-8 string, 221 225 \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the 222 226 string. The caller must not ask for the next character after the last 223 227 character in the string if the string is not terminated by a null ................................................................................ 231 235 the start of the UTF-8 string. If \fIsrc\fR was already at \fIstart\fR, the 232 236 return value will be \fIstart\fR. 233 237 .PP 234 238 \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the 235 239 Pascal Ord() function. It returns the Tcl_UniChar represented at the 236 240 specified character (not byte) \fIindex\fR in the UTF-8 string 237 241 \fIsrc\fR. The source string must contain at least \fIindex\fR 238 -characters. Behavior is undefined if a negative \fIindex\fR is given. 242 +characters. 239 243 .PP 240 244 \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not 241 245 byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must 242 246 contain at least \fIindex\fR characters. This is equivalent to calling 243 -\fBTcl_UtfNext\fR \fIindex\fR times. If a negative \fIindex\fR is given, 247 +\fBTcl_UtfNext\fR \fIindex\fR times. If \fIindex\fR is TCL_INDEX_NONE, 244 248 the return pointer points to the first character in the source string. 245 249 .PP 246 250 \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl 247 251 commands. It parses a backslash sequence and stores the properly formed 248 252 UTF-8 character represented by the backslash sequence in the output 249 253 buffer \fIdst\fR. At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer. 250 254 \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number
Added doc/abstract.n.
1 +'\" 2 +'\" Copyright (c) 2018 Donal K. Fellows 3 +'\" 4 +'\" See the file "license.terms" for information on usage and redistribution 5 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 +'\" 7 +.TH abstract n 0.3 TclOO "TclOO Commands" 8 +.so man.macros 9 +.BS 10 +'\" Note: do not modify the .SH NAME line immediately below! 11 +.SH NAME 12 +oo::abstract \- a class that does not allow direct instances of itself 13 +.SH SYNOPSIS 14 +.nf 15 +package require TclOO 16 + 17 +\fBoo::abstract\fI method \fR?\fIarg ...\fR? 18 +.fi 19 +.SH "CLASS HIERARCHY" 20 +.nf 21 +\fBoo::object\fR 22 + \(-> \fBoo::class\fR 23 + \(-> \fBoo::abstract\fR 24 +.fi 25 +.BE 26 +.SH DESCRIPTION 27 +Abstract classes are classes that can contain definitions, but which cannot be 28 +directly manufactured; they are intended to only ever be inherited from and 29 +instantiated indirectly. The characteristic methods of \fBoo::class\fR 30 +(\fBcreate\fR and \fBnew\fR) are not exported by an instance of 31 +\fBoo::abstract\fR. 32 +.PP 33 +Note that \fBoo::abstract\fR is not itself an instance of \fBoo::abstract\fR. 34 +.SS CONSTRUCTOR 35 +The \fBoo::abstract\fR class does not define an explicit constructor; this 36 +means that it is effectively the same as the constructor of the 37 +\fBoo::class\fR class. 38 +.SS DESTRUCTOR 39 +The \fBoo::abstract\fR class does not define an explicit destructor; 40 +destroying an instance of it is just like destroying an ordinary class (and 41 +will destroy all its subclasses). 42 +.SS "EXPORTED METHODS" 43 +The \fBoo::abstract\fR class defines no new exported methods. 44 +.SS "NON-EXPORTED METHODS" 45 +The \fBoo::abstract\fR class explicitly states that \fBcreate\fR, 46 +\fBcreateWithNamespace\fR, and \fBnew\fR are unexported. 47 +.SH EXAMPLES 48 +.PP 49 +This example defines a simple class hierarchy and creates a new instance of 50 +it. It then invokes a method of the object before destroying the hierarchy and 51 +showing that the destruction is transitive. 52 +.PP 53 +.CS 54 +\fBoo::abstract\fR create fruit { 55 + method eat {} { 56 + puts "yummy!" 57 + } 58 +} 59 +oo::class create banana { 60 + superclass fruit 61 + method peel {} { 62 + puts "skin now off" 63 + } 64 +} 65 +set b [banana \fBnew\fR] 66 +$b peel \fI\(-> prints 'skin now off'\fR 67 +$b eat \fI\(-> prints 'yummy!'\fR 68 +set f [fruit new] \fI\(-> error 'unknown method "new"...'\fR 69 +.CE 70 +.SH "SEE ALSO" 71 +oo::define(n), oo::object(n) 72 +.SH KEYWORDS 73 +abstract class, class, metaclass, object 74 +.\" Local variables: 75 +.\" mode: nroff 76 +.\" fill-column: 78 77 +.\" End:
Changes to doc/append.n.
16 16 .BE 17 17 .SH DESCRIPTION 18 18 .PP 19 19 Append all of the \fIvalue\fR arguments to the current value 20 20 of variable \fIvarName\fR. If \fIvarName\fR does not exist, 21 21 it is given a value equal to the concatenation of all the 22 22 \fIvalue\fR arguments. 23 +.VS TIP508 24 +If \fIvarName\fR indicate an element that does not exist of an array that has 25 +a default value set, the concatenation of the default value and all the 26 +\fIvalue\fR arguments will be stored in the array element. 27 +.VE TIP508 23 28 The result of this command is the new value stored in variable 24 29 \fIvarName\fR. 25 30 This command provides an efficient way to build up long 26 31 variables incrementally. 27 32 For example, 28 33 .QW "\fBappend a $b\fR" 29 34 is much more efficient than ................................................................................ 40 45 puts $var 41 46 # Prints 0,1,2,3,4,5,6,7,8,9,10 42 47 .CE 43 48 .SH "SEE ALSO" 44 49 concat(n), lappend(n) 45 50 .SH KEYWORDS 46 51 append, variable 47 -'\" Local Variables: 48 -'\" mode: nroff 49 -'\" End: 52 +.\" Local variables: 53 +.\" mode: nroff 54 +.\" fill-column: 78 55 +.\" End:
Changes to doc/array.n.
1 1 '\" 2 2 '\" Copyright (c) 1993-1994 The Regents of the University of California. 3 3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. 4 4 '\" 5 5 '\" See the file "license.terms" for information on usage and redistribution 6 6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 7 '\" 8 -.TH array n 8.3 Tcl "Tcl Built-In Commands" 8 +.TH array n 8.7 Tcl "Tcl Built-In Commands" 9 9 .so man.macros 10 10 .BS 11 11 '\" Note: do not modify the .SH NAME line immediately below! 12 12 .SH NAME 13 13 array \- Manipulate array variables 14 14 .SH SYNOPSIS 15 15 \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR? ................................................................................ 31 31 \fISearchId\fR indicates which search on \fIarrayName\fR to 32 32 check, and must have been the return value from a previous 33 33 invocation of \fBarray startsearch\fR. 34 34 This option is particularly useful if an array has an element 35 35 with an empty name, since the return value from 36 36 \fBarray nextelement\fR will not indicate whether the search 37 37 has been completed. 38 +.TP 39 +\fBarray default \fIsubcommand arrayName args...\fR 40 +.VS TIP508 41 +Manages the default value of the array. Arrays initially have no default 42 +value, but this command allows you to set one; the default value will be 43 +returned when reading from an element of the array \fIarrayName\fR if the read 44 +would otherwise result in an error. Note that this may cause the \fBappend\fR, 45 +\fBdict\fR, \fBincr\fR and \fBlappend\fR commands to change their behavior in 46 +relation to non-existing array elements. 47 +.RS 48 +.PP 49 +The \fIsubcommand\fR argument controls what exact operation will be performed 50 +on the default value of \fIarrayName\fR. Supported \fIsubcommand\fRs are: 51 +.VE TIP508 52 +.TP 53 +\fBarray default exists \fIarrayName\fR 54 +.VS TIP508 55 +This returns a boolean value indicating whether a default value has been set 56 +for the array \fIarrayName\fR. Returns a false value if \fIarrayName\fR does 57 +not exist. Raises an error if \fIarrayName\fR is an existing variable that is 58 +not an array. 59 +.VE TIP508 60 +.TP 61 +\fBarray default get \fIarrayName\fR 62 +.VS TIP508 63 +This returns the current default value for the array \fIarrayName\fR. Raises 64 +an error if \fIarrayName\fR is an existing variable that is not an array, or 65 +if \fIarrayName\fR is an array without a default value. 66 +.VE TIP508 67 +.TP 68 +\fBarray default set \fIarrayName value\fR 69 +.VS TIP508 70 +This sets the default value for the array \fIarrayName\fR to \fIvalue\fR. 71 +Returns the empty string. Raises an error if \fIarrayName\fR is an existing 72 +variable that is not an array, or if \fIarrayName\fR is an illegal name for an 73 +array. If \fIarrayName\fR does not currently exist, it is created as an empty 74 +array as well as having its default value set. 75 +.VE TIP508 76 +.TP 77 +\fBarray default unset \fIarrayName\fR 78 +.VS TIP508 79 +This removes the default value for the array \fIarrayName\fR and returns the 80 +empty string. Does nothing if \fIarrayName\fR does not have a default 81 +value. Raises an error if \fIarrayName\fR is an existing variable that is not 82 +an array. 83 +.VE TIP508 84 +.RE 38 85 .TP 39 86 \fBarray donesearch \fIarrayName searchId\fR 40 87 This command terminates an array search and destroys all the 41 88 state associated with that search. \fISearchId\fR indicates 42 89 which search on \fIarrayName\fR to destroy, and must have 43 90 been the return value from a previous invocation of 44 91 \fBarray startsearch\fR. Returns an empty string. 45 92 .TP 46 93 \fBarray exists \fIarrayName\fR 47 94 Returns 1 if \fIarrayName\fR is an array variable, 0 if there 48 95 is no variable by that name or if it is a scalar variable. 49 96 .TP 97 +\fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP 98 +The first argument is a two element list of variable names for the 99 +key and value of each entry in the array. The second argument is the 100 +array name to iterate over. The third argument is the body to execute 101 +for each key and value returned. 102 +The ordering of the returned keys is undefined. 103 +If an array element is deleted or a new array element is inserted during 104 +the \fIarray for\fP process, the command will terminate with an error. 105 +.TP 50 106 \fBarray get \fIarrayName\fR ?\fIpattern\fR? 51 107 Returns a list containing pairs of elements. The first 52 108 element in each pair is the name of an element in \fIarrayName\fR 53 109 and the second element of each pair is the value of the 54 110 array element. The order of the pairs is undefined. 55 111 If \fIpattern\fR is not specified, then all of the elements of the 56 112 array are included in the result. ................................................................................ 181 237 number of buckets with 10 or more entries: 0 182 238 average search distance for entry: 1.2 183 239 .CE 184 240 .SH "SEE ALSO" 185 241 list(n), string(n), variable(n), trace(n), foreach(n) 186 242 .SH KEYWORDS 187 243 array, element names, search 244 +.\" Local variables: 245 +.\" mode: nroff 246 +.\" fill-column: 78 247 +.\" End:
Added doc/callback.n.
1 +'\" 2 +'\" Copyright (c) 2018 Donal K. Fellows 3 +'\" 4 +'\" See the file "license.terms" for information on usage and redistribution 5 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 +'\" 7 +.TH callback n 0.3 TclOO "TclOO Commands" 8 +.so man.macros 9 +.BS 10 +'\" Note: do not modify the .SH NAME line immediately below! 11 +.SH NAME 12 +callback, mymethod \- generate callbacks to methods 13 +.SH SYNOPSIS 14 +.nf 15 +package require TclOO 16 + 17 +\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR? 18 +\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR? 19 +.fi 20 +.BE 21 +.SH DESCRIPTION 22 +The \fBcallback\fR command, 23 +'\" Based on notes in the tcllib docs, we know the provenance of mymethod 24 +also called \fBmymethod\fR for compatibility with the ooutil and snit packages 25 +of Tcllib, 26 +and which should only be used from within the context of a call to a method 27 +(i.e. inside a method, constructor or destructor body) is used to generate a 28 +script fragment that will invoke the method, \fImethodName\fR, on the current 29 +object (as reported by \fBself\fR) when executed. Any additional arguments 30 +provided will be provided as leading arguments to the callback. The resulting 31 +script fragment shall be a proper list. 32 +.PP 33 +Note that it is up to the caller to ensure that the current object is able to 34 +handle the call of \fImethodName\fR; this command does not check that. 35 +\fImethodName\fR may refer to any exported or unexported method, but may not 36 +refer to a private method as those can only be invoked directly from within 37 +methods. If there is no such method present at the point when the callback is 38 +invoked, the standard \fBunknown\fR method handler will be called. 39 +.SH EXAMPLE 40 +This is a simple echo server class. The \fBcallback\fR command is used in two 41 +places, to arrange for the incoming socket connections to be handled by the 42 +\fIAccept\fR method, and to arrange for the incoming bytes on those 43 +connections to be handled by the \fIReceive\fR method. 44 +.PP 45 +.CS 46 +oo::class create EchoServer { 47 + variable server clients 48 + constructor {port} { 49 + set server [socket -server [\fBcallback\fR Accept] $port] 50 + set clients {} 51 + } 52 + destructor { 53 + chan close $server 54 + foreach client [dict keys $clients] { 55 + chan close $client 56 + } 57 + } 58 + 59 + method Accept {channel clientAddress clientPort} { 60 + dict set clients $channel [dict create \e 61 + address $clientAddress port $clientPort] 62 + chan event $channel readable [\fBcallback\fR Receive $channel] 63 + } 64 + method Receive {channel} { 65 + if {[chan gets $channel line] >= 0} { 66 + my echo $channel $line 67 + } else { 68 + chan close $channel 69 + dict unset clients $channel 70 + } 71 + } 72 + 73 + method echo {channel line} { 74 + dict with clients $channel { 75 + chan puts $channel \e 76 + [format {[%s:%d] %s} $address $port $line] 77 + } 78 + } 79 +} 80 +.CE 81 +.SH "SEE ALSO" 82 +chan(n), fileevent(n), my(n), self(n), socket(n), trace(n) 83 +.SH KEYWORDS 84 +callback, object 85 +.\" Local Variables: 86 +.\" mode: nroff 87 +.\" fill-column: 78 88 +.\" End:
Changes to doc/cd.n.
37 37 .CS 38 38 \fBcd\fR ../lib 39 39 .CE 40 40 .SH "SEE ALSO" 41 41 filename(n), glob(n), pwd(n) 42 42 .SH KEYWORDS 43 43 working directory 44 +'\" Local Variables: 45 +'\" mode: nroff 46 +'\" fill-column: 78 47 +'\" End:
Added doc/classvariable.n.
1 +'\" 2 +'\" Copyright (c) 2011-2015 Andreas Kupries 3 +'\" Copyright (c) 2018 Donal K. Fellows 4 +'\" 5 +'\" See the file "license.terms" for information on usage and redistribution 6 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 +'\" 8 +.TH classvariable n 0.3 TclOO "TclOO Commands" 9 +.so man.macros 10 +.BS 11 +'\" Note: do not modify the .SH NAME line immediately below! 12 +.SH NAME 13 +classvariable \- create link from local variable to variable in class 14 +.SH SYNOPSIS 15 +.nf 16 +package require TclOO 17 + 18 +\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR? 19 +.fi 20 +.BE 21 +.SH DESCRIPTION 22 +The \fBclassvariable\fR command is available within methods. It takes a series 23 +of one or more variable names and makes them available in the method's scope; 24 +those variable names must not be qualified and must not refer to array 25 +elements. The originating scope for the variables is the namespace of the 26 +class that the method was defined by. In other words, the referenced variables 27 +are shared between all instances of that class. 28 +.PP 29 +Note: This command is equivalent to the command \fBtypevariable\fR provided by 30 +the snit package in tcllib for approximately the same purpose. If used in a 31 +method defined directly on a class instance (e.g., through the 32 +\fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just 33 +using: 34 +.PP 35 +.CS 36 +namespace upvar [namespace current] $var $var 37 +.CE 38 +.PP 39 +for each variable listed to \fBclassvariable\fR. 40 +.SH EXAMPLE 41 +This class counts how many instances of it have been made. 42 +.PP 43 +.CS 44 +oo::class create Counted { 45 + initialise { 46 + variable count 0 47 + } 48 + 49 + variable number 50 + constructor {} { 51 + \fBclassvariable\fR count 52 + set number [incr count] 53 + } 54 + 55 + method report {} { 56 + \fBclassvariable\fR count 57 + puts "This is instance $number of $count" 58 + } 59 +} 60 + 61 +set a [Counted new] 62 +set b [Counted new] 63 +$a report 64 + \fI\(-> This is instance 1 of 2\fR 65 +set c [Counted new] 66 +$b report 67 + \fI\(-> This is instance 2 of 3\fR 68 +$c report 69 + \fI\(-> This is instance 3 of 3\fR 70 +.CE 71 +.SH "SEE ALSO" 72 +global(n), namespace(n), oo::class(n), oo::define(n), upvar(n), variable(n) 73 +.SH KEYWORDS 74 +class, class variable, variable 75 +.\" Local Variables: 76 +.\" mode: nroff 77 +.\" fill-column: 78 78 +.\" End:
Changes to doc/clock.n.
448 448 If a format string lacks a \fB%z\fR or \fB%Z\fR format group, 449 449 it is possible for the time to be ambiguous because it appears twice 450 450 in the same day, once without and once with Daylight Saving Time. 451 451 If this situation occurs, the first occurrence of the time is chosen. 452 452 (For this reason, it is wise to have the input string contain the 453 453 time zone when converting local times. This caveat does not apply to 454 454 UTC times.) 455 +.PP 456 +If the interpretation of the groups yields an impossible time because 457 +a field is out of range, enough of that field's unit will be added to 458 +or subtracted from the time to bring it in range. Thus, if attempting to 459 +scan or format day 0 of the month, one day will be subtracted from day 460 +1 of the month, yielding the last day of the previous month. 461 +.PP 462 +If the interpretation of the groups yields an impossible time because 463 +a Daylight Saving Time change skips over that time, or an ambiguous 464 +time because a Daylight Saving Time change skips back so that the clock 465 +observes the given time twice, and no time zone specifier (\fB%z\fR 466 +or \fB%Z\fR) is present in the format, the time is interpreted as 467 +if the clock had not changed. 455 468 .SH "FORMAT GROUPS" 456 469 .PP 457 470 The following format groups are recognized by the \fBclock scan\fR and 458 471 \fBclock format\fR commands. 459 472 .TP 460 473 \fB%a\fR 461 474 On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day ................................................................................ 869 882 time. This is useful for determining the time on a specific day or 870 883 doing other date-relative conversions. 871 884 .PP 872 885 The \fIinputString\fR argument consists of zero or more specifications of the 873 886 following form: 874 887 .TP 875 888 \fItime\fR 876 -A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR 877 -or \fBhhmm ?meridian? ?zone?\fR 878 -If no meridian is specified, \fBhh\fR is interpreted on 889 +. 890 +A time of day, which is of the form: 891 +.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?" 892 +or 893 +.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" . 894 +If no \fImeridian\fR is specified, \fIhh\fR is interpreted on 879 895 a 24-hour clock. 880 896 .TP 881 897 \fIdate\fR 898 +. 882 899 A specific month and day with optional year. The 883 900 acceptable formats are 884 -.QW "\fBmm/dd\fR?\fB/yy\fR?" , 885 -.QW "\fBmonthname dd\fR?\fB, yy\fR?" , 886 -.QW "\fBday, dd monthname \fR?\fByy\fR?" , 887 -.QW "\fBdd monthname yy\fR" , 888 -.QW "?\fBCC\fR?\fByymmdd\fR" , 901 +.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" , 902 +.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" , 903 +.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" , 904 +.QW "\fIdd monthname yy\fR" , 905 +.QW "?\fICC\fR?\fIyymmdd\fR" , 889 906 and 890 -.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" . 907 +.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" . 891 908 The default year is the current year. If the year is less 892 909 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 893 910 as 1969-1999. Not all platforms can represent the years 38-70, so 894 911 an error may result if these years are used. 895 912 .TP 896 913 \fIISO 8601 point-in-time\fR 914 +. 897 915 An ISO 8601 point-in-time specification, such as 898 916 .QW \fICCyymmdd\fBT\fIhhmmss\fR, 899 917 where \fBT\fR is the literal 900 918 .QW T , 901 919 .QW "\fICCyymmdd hhmmss\fR" , 902 920 or 903 -.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR . 921 +.QW \fICCyymmdd\fBT\fIhh\fB:\fImm\fB:\fIss\fR . 904 922 Note that only these three formats are accepted. 905 923 The command does \fInot\fR accept the full range of point-in-time 906 924 specifications specified in ISO8601. Other formats can be recognized by 907 925 giving an explicit \fB\-format\fR option to the \fBclock scan\fR command. 908 926 .TP 909 927 \fIrelative time\fR 928 +. 910 929 A specification relative to the current time. The format is \fBnumber 911 930 unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, 912 931 \fBmonth\fR, \fBweek\fR, \fBday\fR, 913 932 \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The 914 933 unit can be specified as a singular or plural, as in \fB3 weeks\fR. 915 934 These modifiers may also be specified: 916 935 \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
Added doc/cookiejar.n.
1 +'\" 2 +'\" Copyright (c) 2014-2018 Donal K. Fellows. 3 +'\" 4 +'\" See the file "license.terms" for information on usage and redistribution 5 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 +'\" 7 +.TH "cookiejar" n 0.1 http "Tcl Bundled Packages" 8 +.so man.macros 9 +.BS 10 +'\" Note: do not modify the .SH NAME line immediately below! 11 +.SH NAME 12 +cookiejar \- Implementation of the Tcl http package cookie jar protocol 13 +.SH SYNOPSIS 14 +.nf 15 +\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? 16 + 17 +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? 18 +\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? 19 +\fB::http::cookiejar new\fR ?\fIfilename\fR? 20 + 21 +\fIcookiejar\fR \fBdestroy\fR 22 +\fIcookiejar\fR \fBforceLoadDomainData\fR 23 +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR 24 +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR 25 +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? 26 +.fi 27 +.SH DESCRIPTION 28 +.PP 29 +The cookiejar package provides an implementation of the http package's cookie 30 +jar protocol using an SQLite database. It provides one main command, 31 +\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to 32 +create a cookie jar that manages a particular HTTP session. 33 +.PP 34 +The database management policy can be controlled at the package level by the 35 +\fBconfigure\fR method on the \fB::http::cookiejar\fR class object: 36 +.TP 37 +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? 38 +. 39 +If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a 40 +copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is 41 +supplied, just the value of the named option is returned. If both 42 +\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed 43 +to be the given value. 44 +.RS 45 +.PP 46 +Supported options are: 47 +.TP 48 +\fB\-domainfile \fIfilename\fR 49 +. 50 +A file (defaulting to within the cookiejar package) with a description of the 51 +list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains 52 +\fImust not\fR accept cookies set upon them. Note that the list of such 53 +domains is both security-sensitive and \fInot\fR constant and should be 54 +periodically refetched. Cookie jars maintain their own cache of the domain 55 +list. 56 +.TP 57 +\fB\-domainlist \fIurl\fR 58 +. 59 +A URL to fetch the list of top-level domains (e.g., \fB.com\fR or 60 +\fB.co.jp\fR) from. Such domains \fImust not\fR accept cookies set upon 61 +them. Note that the list of such domains is both security-sensitive and 62 +\fInot\fR constant and should be periodically refetched. Cookie jars maintain 63 +their own cache of the domain list. 64 +.TP 65 +\fB\-domainrefresh \fIintervalMilliseconds\fR 66 +. 67 +The number of milliseconds between checks of the \fI\-domainlist\fR for new 68 +domains. 69 +.TP 70 +\fB\-loglevel \fIlevel\fR 71 +. 72 +The logging level of this package. The logging level must be (in order of 73 +decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or 74 +\fBerror\fR. 75 +.TP 76 +\fB\-offline \fIflag\fR 77 +. 78 +Allows the cookie managment engine to be placed into offline mode. In offline 79 +mode, the list of domains is read immediately from the file configured in the 80 +\fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it 81 +also makes the \fB\-domainrefresh\fR option be effectively ignored. 82 +.TP 83 +\fB\-purgeold \fIintervalMilliseconds\fR 84 +. 85 +The number of milliseconds between checks of the database for expired 86 +cookies; expired cookies are deleted. 87 +.TP 88 +\fB\-retain \fIcookieCount\fR 89 +. 90 +The maximum number of cookies to retain in the database. 91 +.TP 92 +\fB\-vacuumtrigger \fIdeletionCount\fR 93 +. 94 +A count of the number of persistent cookie deletions to go between vacuuming 95 +the database. 96 +.RE 97 +.PP 98 +Cookie jar instances may be made with any of the standard TclOO instance 99 +creation methods (\fBcreate\fR or \fBnew\fR). 100 +.TP 101 +\fB::http::cookiejar new\fR ?\fIfilename\fR? 102 +. 103 +If a \fIfilename\fR argument is provided, it is the name of a file containing 104 +an SQLite database that will contain the persistent cookies maintained by the 105 +cookie jar; the database will be created if the file does not already 106 +exist. If \fIfilename\fR is not supplied, the database will be held entirely within 107 +memory, which effectively forces all cookies within it to be session cookies. 108 +.SS "INSTANCE METHODS" 109 +.PP 110 +The following methods are supported on the instances: 111 +.TP 112 +\fIcookiejar\fR \fBdestroy\fR 113 +. 114 +This is the standard TclOO destruction method. It does \fInot\fR delete the 115 +SQLite database if it is written to disk. Callers are responsible for ensuring 116 +that the cookie jar is not in use by the http package at the time of 117 +destruction. 118 +.TP 119 +\fIcookiejar\fR \fBforceLoadDomainData\fR 120 +. 121 +This method causes the cookie jar to immediately load (and cache) the domain 122 +list data. The domain list will be loaded from the \fB\-domainlist\fR 123 +configured a the package level if that is enabled, and otherwise will be 124 +obtained from the \fB\-domainfile\fR configured at the package level. 125 +.TP 126 +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR 127 +. 128 +This method obtains the cookies for a particular HTTP request. \fIThis 129 +implements the http cookie jar protocol.\fR 130 +.TP 131 +\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR 132 +. 133 +This method is called by the \fBstoreCookie\fR method to get a decision on 134 +whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and 135 +\fIpath\fR. This is checked immediately before the database is updated but 136 +after the built-in security checks are done, and should return a boolean 137 +value; if the value is false, the operation is rejected and the database is 138 +not modified. The supported \fIoperation\fRs are: 139 +.RS 140 +.TP 141 +\fBdelete\fR 142 +. 143 +The \fIdomain\fR is seeking to delete a cookie. 144 +.TP 145 +\fBsession\fR 146 +. 147 +The \fIdomain\fR is seeking to create or update a session cookie. 148 +.TP 149 +\fBset\fR 150 +. 151 +The \fIdomain\fR is seeking to create or update a persistent cookie (with a 152 +defined lifetime). 153 +.PP 154 +The default implementation of this method just returns true, but subclasses of 155 +this class may impose their own rules. 156 +.RE 157 +.TP 158 +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR 159 +. 160 +This method stores a single cookie from a particular HTTP response. Cookies 161 +that fail security checks are ignored. \fIThis implements the http cookie jar 162 +protocol.\fR 163 +.TP 164 +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? 165 +. 166 +This method looks a cookie by exact host (or domain) matching. If neither 167 +\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is 168 +stored is returned. If just \fIhost\fR (which may be a hostname or a domain 169 +name) is supplied, the list of cookie keys stored for that host is returned. 170 +If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is 171 +returned; it is an error if no such host or key match exactly. 172 +.SH "EXAMPLES" 173 +.PP 174 +The simplest way of using a cookie jar is to just permanently configure it at 175 +the start of the application. 176 +.PP 177 +.CS 178 +package require http 179 +\fBpackage require cookiejar\fR 180 + 181 +set cookiedb ~/.tclcookies.db 182 +http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] 183 + 184 +# No further explicit steps are required to use cookies 185 +set tok [http::geturl http://core.tcl.tk/] 186 +.CE 187 +.PP 188 +To only allow a particular domain to use cookies, perhaps because you only 189 +want to enable a particular host to create and manipulate sessions, create a 190 +subclass that imposes that policy. 191 +.PP 192 +.CS 193 +package require http 194 +\fBpackage require cookiejar\fR 195 + 196 +oo::class create MyCookieJar { 197 + superclass \fBhttp::cookiejar\fR 198 + 199 + method \fBpolicyAllow\fR {operation domain path} { 200 + return [expr {$domain eq "my.example.com"}] 201 + } 202 +} 203 + 204 +set cookiedb ~/.tclcookies.db 205 +http::configure -cookiejar [MyCookieJar new $cookiedb] 206 + 207 +# No further explicit steps are required to use cookies 208 +set tok [http::geturl http://core.tcl.tk/] 209 +.CE 210 +.SH "SEE ALSO" 211 +http(n), oo::class(n), sqlite3(n) 212 +.SH KEYWORDS 213 +cookie, internet, security policy, www 214 +'\" Local Variables: 215 +'\" mode: nroff 216 +'\" fill-column: 78 217 +'\" End:
Changes to doc/coroutine.n.
10 10 '\" Note: do not modify the .SH NAME line immediately below! 11 11 .SH NAME 12 12 coroutine, yield, yieldto \- Create and produce values from coroutines 13 13 .SH SYNOPSIS 14 14 .nf 15 15 \fBcoroutine \fIname command\fR ?\fIarg...\fR? 16 16 \fByield\fR ?\fIvalue\fR? 17 -.VS TIP396 18 17 \fByieldto\fR \fIcommand\fR ?\fIarg...\fR? 19 18 \fIname\fR ?\fIvalue...\fR? 20 -.VE TIP396 19 +.sp 20 +.VS "8.7, TIP383" 21 +\fBcoroinject \fIcoroName command\fR ?\fIarg...\fR? 22 +\fBcoroprobe \fIcoroName command\fR ?\fIarg...\fR? 23 +.VE "8.7, TIP383" 21 24 .fi 22 25 .BE 23 26 .SH DESCRIPTION 24 27 .PP 25 28 The \fBcoroutine\fR command creates a new coroutine context (with associated 26 29 command) named \fIname\fR and executes that context by calling \fIcommand\fR, 27 30 passing in the other remaining arguments without further interpretation. Once ................................................................................ 35 38 of the context can then be resumed by calling the context command, optionally 36 39 passing in the \fIsingle\fR value to use as the result of the \fByield\fR call 37 40 that caused 38 41 the context to be suspended. If the coroutine context never yields and instead 39 42 returns conventionally, the result of the \fBcoroutine\fR command will be the 40 43 result of the evaluation of the context. 41 44 .PP 42 -.VS TIP396 43 45 The coroutine may also suspend its execution by use of the \fByieldto\fR 44 46 command, which instead of returning, cedes execution to some command called 45 47 \fIcommand\fR (resolved in the context of the coroutine) and to which \fIany 46 48 number\fR of arguments may be passed. Since every coroutine has a context 47 49 command, \fByieldto\fR can be used to transfer control directly from one 48 50 coroutine to another (this is only advisable if the two coroutines are 49 51 expecting this to happen) but \fIany\fR command may be the target. If a ................................................................................ 54 56 decide what to do with those values. 55 57 .PP 56 58 The recommended way of writing a version of \fByield\fR that allows resumption 57 59 with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR 58 60 command, like this: 59 61 .PP 60 62 .CS 61 -proc yieldm {value} { 62 - \fByieldto\fR return -level 0 $value 63 +proc yieldMultiple {value} { 64 + tailcall \fByieldto\fR string cat $value 63 65 } 64 66 .CE 65 -.VE TIP396 66 67 .PP 67 68 The coroutine can also be deleted by destroying the command \fIname\fR, and 68 69 the name of the current coroutine can be retrieved by using 69 70 \fBinfo coroutine\fR. 70 71 If there are deletion traces on variables in the coroutine's 71 72 implementation, they will fire at the point when the coroutine is explicitly 72 73 deleted (or, naturally, if the command returns conventionally). 73 74 .PP 74 75 At the point when \fIcommand\fR is called, the current namespace will be the 75 76 global namespace and there will be no stack frames above it (in the sense of 76 77 \fBupvar\fR and \fBuplevel\fR). However, which command to call will be 77 78 determined in the namespace that the \fBcoroutine\fR command was called from. 79 +.PP 80 +.VS "8.7, TIP383" 81 +A suspended coroutine (i.e., one that has \fByield\fRed or \fByieldto\fR-d) 82 +may have its state inspected (or modified) at that point by using 83 +\fBcoroprobe\fR to run a command at the point where the coroutine is at. The 84 +command takes the name of the coroutine to run the command in, \fIcoroName\fR, 85 +and the name of a command (any any arguments it requires) to immediately run 86 +at that point. The result of that command is the result of the \fBcoroprobe\fR 87 +command, and the gross state of the coroutine remains the same afterwards 88 +(i.e., the coroutine is still expecting the results of a \fByield\fR or 89 +\fByieldto\fR as before) though variables may have been changed. 90 +.PP 91 +Similarly, the \fBcoroinject\fR command may be used to place a command to be 92 +run inside a suspended coroutine (when it is resumed) to process arguments, 93 +with quite a bit of similarity to \fBcoroprobe\fR. However, with 94 +\fBcoroinject\fR there are several key differences: 95 +.VE "8.7, TIP383" 96 +.IP \(bu 97 +.VS "8.7, TIP383" 98 +The coroutine is not immediately resumed after the injection has been done. A 99 +consequence of this is that multiple injections may be done before the 100 +coroutine is resumed. There injected commands are performed in \fIreverse 101 +order of definition\fR (that is, they are internally stored on a stack). 102 +.VE "8.7, TIP383" 103 +.IP \(bu 104 +.VS "8.7, TIP383" 105 +An additional two arguments are appended to the list of arguments to be run 106 +(that is, the \fIcommand\fR and its \fIargs\fR are extended by two elements). 107 +The first is the name of the command that suspended the coroutine (\fByield\fR 108 +or \fByieldto\fR), and the second is the argument (or list of arguments, in 109 +the case of \fByieldto\fR) that is the current resumption value. 110 +.VE "8.7, TIP383" 111 +.IP \(bu 112 +.VS "8.7, TIP383" 113 +The result of the injected command is used as the result of the \fByield\fR or 114 +\fByieldto\fR that caused the coroutine to become suspended. Where there are 115 +multiple injected commands, the result of one becomes the resumption value 116 +processed by the next. 117 +.PP 118 +The injection is a one-off. It is not retained once it has been executed. It 119 +may \fByield\fR or \fByieldto\fR as part of its execution. 120 +.PP 121 +Note that running coroutines may be neither probed nor injected; the 122 +operations may only be applied to 123 +.VE "8.7, TIP383" 78 124 .SH EXAMPLES 79 125 .PP 80 126 This example shows a coroutine that will produce an infinite sequence of 81 127 even values, and a loop that consumes the first ten of them. 82 128 .PP 83 129 .CS 84 130 proc allNumbers {} { ................................................................................ 134 180 } 135 181 }} allNumbers 136 182 for {set i 1} {$i <= 20} {incr i} { 137 183 puts "prime#$i = [\fIeratosthenes\fR]" 138 184 } 139 185 .CE 140 186 .PP 141 -.VS TIP396 142 187 This example shows how a value can be passed around a group of three 143 188 coroutines that yield to each other: 144 189 .PP 145 190 .CS 146 191 proc juggler {name target {value ""}} { 147 192 if {$value eq ""} { 148 193 set value [\fByield\fR [info coroutine]] 149 194 } 150 195 while {$value ne ""} { 151 196 puts "$name : $value" 152 197 set value [string range $value 0 end-1] 153 - lassign [\fByieldto\fR $target $value] value 198 + lassign [\fByieldto\fR \fI$target\fR $value] value 154 199 } 155 200 } 156 201 \fBcoroutine\fR j1 juggler Larry [ 157 202 \fBcoroutine\fR j2 juggler Curly [ 158 203 \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!" 159 204 .CE 160 -.VE TIP396 205 +.PP 206 +.VS "8.7, TIP383" 207 +This example shows a simple coroutine that collects non-empty values and 208 +returns a list of them when not given an argument. It also shows how we can 209 +look inside the coroutine to find out what it is doing, and how we can modify 210 +the input on a one-off basis. 211 +.PP 212 +.CS 213 +proc collectorImpl {} { 214 + set me [info coroutine] 215 + set accumulator {} 216 + for {set val [\fByield\fR $me]} {$val ne ""} {set val [\fByield\fR]} { 217 + lappend accumulator $val 218 + } 219 + return $accumulator 220 +} 221 + 222 +\fBcoroutine\fR collect collectorImpl 223 +\fIcollect\fR 123 224 +\fIcollect\fR "abc def" 225 +\fIcollect\fR 456 226 + 227 +puts [\fBcoroprobe \fIcollect\fR set accumulator] 228 +# ==> 123 {abc def} 456 229 + 230 +\fIcollect\fR "pqr" 231 + 232 +\fBcoroinject \fIcollect\fR apply {{type value} { 233 + puts "Received '$value' at a $type in [info coroutine]" 234 + return [string toupper $value] 235 +}} 236 + 237 +\fIcollect\fR rst 238 +# ==> Received 'rst' at a yield in ::collect 239 +\fIcollect\fR xyz 240 + 241 +puts [\fIcollect\fR] 242 +# ==> 123 {abc def} 456 pqr RST xyz 243 +.CE 244 +.PP 245 +This example shows a simple coroutine that collects non-empty values and 246 +returns a list of them when not given an argument. It also shows how we can 247 +look inside the coroutine to find out what it is doing. 248 +.VE "8.7, TIP383" 161 249 .SS "DETAILED SEMANTICS" 162 250 .PP 163 251 This example demonstrates that coroutines start from the global namespace, and 164 252 that \fIcommand\fR resolution happens before the coroutine stack is created. 165 253 .PP 166 254 .CS 167 255 proc report {where level} {
Changes to doc/define.n.
1 1 '\" 2 -'\" Copyright (c) 2007 Donal K. Fellows 2 +'\" Copyright (c) 2007-2018 Donal K. Fellows 3 3 '\" 4 4 '\" See the file "license.terms" for information on usage and redistribution 5 5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 6 '\" 7 7 .TH define n 0.3 TclOO "TclOO Commands" 8 8 .so man.macros 9 9 .BS ................................................................................ 30 30 configuration of all subclasses of the class and all objects that are 31 31 instances of that class or which mix it in (as modified by any per-instance 32 32 configuration). The way in which the configuration is done is controlled by 33 33 either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following 34 34 \fIarg\fR arguments; when the second is present, it is exactly as if all the 35 35 arguments from \fIsubcommand\fR onwards are made into a list and that list is 36 36 used as the \fIdefScript\fR argument. 37 -.SS "CONFIGURING CLASSES" 37 +.PP 38 +Note that the constructor for \fBoo::class\fR will call \fBoo::define\fR on 39 +the script argument that it is provided. This is a convenient way to create 40 +and define a class in one step. 41 +.SH "CONFIGURING CLASSES" 38 42 .PP 39 43 The following commands are supported in the \fIdefScript\fR for 40 44 \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form: 45 +.TP 46 +\fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR? 47 +.VS TIP478 48 +This creates a class method, or (if \fIargList\fR and \fIbodyScript\fR are 49 +omitted) promotes an existing method on the class object to be a class 50 +method. The \fIname\fR, \fIargList\fR and \fIbodyScript\fR arguments are as in 51 +the \fBmethod\fR definition, below. 52 +.RS 53 +.PP 54 +Class methods can be called on either the class itself or on the instances of 55 +that class. When they are called, the current object (see the \fBsel\fR and 56 +\fBmy\fR commands) is the class on which they are called or the class of the 57 +instance on which they are called, depending on whether they are called on the 58 +class or an instance of the class, respectively. If called on a subclass or 59 +instance of the subclass, the current object is the subclass. 60 +.PP 61 +In a private definition context, the methods as invoked on classes are 62 +\fInot\fR private, but the methods as invoked on instances of classes are 63 +private. 64 +.RE 65 +.VE TIP478 41 66 .TP 42 67 \fBconstructor\fI argList bodyScript\fR 43 68 . 44 69 This creates or updates the constructor for a class. The formal arguments to 45 70 the constructor (defined using the same format as for the Tcl \fBproc\fR 46 71 command) will be \fIargList\fR, and the body of the constructor will be 47 72 \fIbodyScript\fR. When the body of the constructor is evaluated, the current 48 73 namespace of the constructor will be a namespace that is unique to the object 49 74 being constructed. Within the constructor, the \fBnext\fR command should be 50 75 used to call the superclasses' constructors. If \fIbodyScript\fR is the empty 51 76 string, the constructor will be deleted. 52 -.TP 53 -\fBdeletemethod\fI name\fR ?\fIname ...\fR 54 -. 55 -This deletes each of the methods called \fIname\fR from a class. The methods 56 -must have previously existed in that class. Does not affect the superclasses 57 -of the class, nor does it affect the subclasses or instances of the class 58 -(except when they have a call chain through the class being modified). 77 +.RS 78 +.PP 79 +Classes do not need to have a constructor defined. If none is specified, the 80 +superclass's constructor will be used instead. 81 +.RE 59 82 .TP 60 83 \fBdestructor\fI bodyScript\fR 61 84 . 62 85 This creates or updates the destructor for a class. Destructors take no 63 86 arguments, and the body of the destructor will be \fIbodyScript\fR. The 64 87 destructor is called when objects of the class are deleted, and when called 65 88 will have the object's unique namespace as the current namespace. Destructors ................................................................................ 76 99 \fBexport\fI name \fR?\fIname ...\fR? 77 100 . 78 101 This arranges for each of the named methods, \fIname\fR, to be exported 79 102 (i.e. usable outside an instance through the instance object's command) by the 80 103 class being defined. Note that the methods themselves may be actually defined 81 104 by a superclass; subclass exports override superclass visibility, and may in 82 105 turn be overridden by instances. 83 -.TP 84 -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? 85 -.VS 86 -This slot (see \fBSLOTTED DEFINITIONS\fR below) 87 -.VE 88 -sets or updates the list of method names that are used to guard whether 89 -method call to instances of the class may be called and what the method's 90 -results are. Each \fImethodName\fR names a single filtering method (which may 91 -be exposed or not exposed); it is not an error for a non-existent method to be 92 -named since they may be defined by subclasses. 93 -.VS 94 -By default, this slot works by appending. 95 -.VE 96 106 .TP 97 107 \fBforward\fI name cmdName \fR?\fIarg ...\fR? 98 108 . 99 109 This creates or updates a forwarded method called \fIname\fR. The method is 100 110 defined be forwarded to the command called \fIcmdName\fR, with additional 101 111 arguments, \fIarg\fR etc., added before those arguments specified by the 102 112 caller of the method. The \fIcmdName\fR will always be resolved using the 103 113 rules of the invoking objects' namespaces, i.e., when \fIcmdName\fR is not 104 114 fully-qualified, the command will be searched for in each object's namespace, 105 115 using the instances' namespace's path, or by looking in the global namespace. 106 116 The method will be exported if \fIname\fR starts with a lower-case letter, and 107 117 non-exported otherwise. 118 +.RS 119 +.PP 120 +.VS TIP500 121 +If in a private definition context (see the \fBprivate\fR definition command, 122 +below), this command creates private forwarded methods. 123 +.VE TIP500 124 +.RE 108 125 .TP 109 -\fBmethod\fI name argList bodyScript\fR 126 +\fBinitialise\fI script\fR 127 +.TP 128 +\fBinitialize\fI script\fR 129 +.VS TIP478 130 +This evaluates \fIscript\fR in a context which supports local variables and 131 +where the current namespace is the instance namespace of the class object 132 +itself. This is useful for setting up, e.g., class-scoped variables. 133 +.VE TIP478 134 +.TP 135 +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR 110 136 . 111 137 This creates or updates a method that is implemented as a procedure-like 112 138 script. The name of the method is \fIname\fR, the formal arguments to the 113 139 method (defined using the same format as for the Tcl \fBproc\fR command) will 114 140 be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When 115 141 the body of the method is evaluated, the current namespace of the method will 116 142 be a namespace that is unique to the current object. The method will be 117 143 exported if \fIname\fR starts with a lower-case letter, and non-exported 118 144 otherwise; this behavior can be overridden via \fBexport\fR and 119 -\fBunexport\fR. 120 -.TP 121 -\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? 122 -.VS 123 -This slot (see \fBSLOTTED DEFINITIONS\fR below) 124 -.VE 125 -sets or updates the list of additional classes that are to be mixed into 126 -all the instances of the class being defined. Each \fIclassName\fR argument 127 -names a single class that is to be mixed in. 128 -.VS 129 -By default, this slot works by replacement. 130 -.VE 131 -.TP 132 -\fBrenamemethod\fI fromName toName\fR 133 -. 134 -This renames the method called \fIfromName\fR in a class to \fItoName\fR. The 135 -method must have previously existed in the class, and \fItoName\fR must not 136 -previously refer to a method in that class. Does not affect the superclasses 137 -of the class, nor does it affect the subclasses or instances of the class 138 -(except when they have a call chain through the class being modified). Does 139 -not change the export status of the method; if it was exported before, it will 140 -be afterwards. 145 +\fBunexport\fR 146 +.VS TIP519 147 +or by specifying \fB\-export\fR, \fB\-private\fR or \fB\-unexport\fR in the 148 +optional parameter \fIoption\fR. 149 +.VE TIP519 150 +.RS 151 +.PP 152 +.VS TIP500 153 +If in a private definition context (see the \fBprivate\fR definition command, 154 +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command 155 +creates private procedure-like methods. 156 +.VE TIP500 157 +.RE 158 +.TP 159 +\fBprivate \fIcmd arg...\fR 160 +.TP 161 +\fBprivate \fIscript\fR 162 +. 163 +.VS TIP500 164 +This evaluates the \fIscript\fR (or the list of command and arguments given by 165 +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the 166 +current class will be private definitions. 167 +.RS 168 +.PP 169 +The following class definition commands are affected by \fBprivate\fR: 170 +\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting 171 +\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost 172 +definition context is just a private definition context. All other definition 173 +commands have no difference in behavior when used in a private definition 174 +context. 175 +.RE 176 +.VE TIP500 141 177 .TP 142 178 \fBself\fI subcommand arg ...\fR 143 179 .TP 144 180 \fBself\fI script\fR 145 181 .TP 146 182 \fBself\fR 147 183 . ................................................................................ 155 191 .QW "\fBoo::objdefine \fIcls subcommand ...\fR" . 156 192 .RS 157 193 .PP 158 194 .VS TIP470 159 195 If no arguments at all are used, this gives the name of the class currently 160 196 being configured. 161 197 .VE TIP470 198 +.VS TIP500 199 +If in a private definition context (see the \fBprivate\fR definition command, 200 +below), the definitions on the class object will also be made in a private 201 +definition context. 202 +.VE TIP500 162 203 .RE 163 204 .TP 164 205 \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? 165 -.VS 206 +. 166 207 This slot (see \fBSLOTTED DEFINITIONS\fR below) 167 -.VE 168 208 allows the alteration of the superclasses of the class being defined. 169 209 Each \fIclassName\fR argument names one class that is to be a superclass of 170 210 the defined class. Note that objects must not be changed from being classes to 171 211 being non-classes or vice-versa, that an empty parent class is equivalent to 172 212 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and 173 213 \fBoo::class\fR may not be modified. 174 -.VS 175 214 By default, this slot works by replacement. 176 -.VE 177 215 .TP 178 216 \fBunexport\fI name \fR?\fIname ...\fR? 179 217 . 180 218 This arranges for each of the named methods, \fIname\fR, to be not exported 181 219 (i.e. not usable outside the instance through the instance object's command, 182 220 but instead just through the \fBmy\fR command visible in each object's 183 221 context) by the class being defined. Note that the methods themselves may be 184 222 actually defined by a superclass; subclass unexports override superclass 185 223 visibility, and may be overridden by instance unexports. 186 224 .TP 187 225 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? 188 -.VS 226 +. 189 227 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named 190 228 variables to be automatically made 191 229 available in the methods, constructor and destructor declared by the class 192 230 being defined. Each variable name must not have any namespace 193 231 separators and must not look like an array access. All variables will be 194 -actually present in the instance object on which the method is executed. Note 232 +actually present in the namespace of the instance object on which the method 233 +is executed. Note 195 234 that the variable lists declared by a superclass or subclass are completely 196 235 disjoint, as are variable lists declared by instances; the list of variable 197 236 names is just for methods (and constructors and destructors) declared by this 198 237 class. By default, this slot works by appending. 199 -.VE 200 -.SS "CONFIGURING OBJECTS" 238 +.RS 239 +.PP 240 +.VS TIP500 241 +If in a private definition context (see the \fBprivate\fR definition command, 242 +below), this slot manipulates the list of private variable bindings for this 243 +class. In a private variable binding, the name of the variable within the 244 +instance object is different to the name given in the definition; the name 245 +used in the definition is the name that you use to access the variable within 246 +the methods of this class, and the name of the variable in the instance 247 +namespace has a unique prefix that makes accidental use from other classes 248 +extremely unlikely. 249 +.VE TIP500 250 +.RE 251 +.SS "ADVANCED CLASS CONFIGURATION OPTIONS" 252 +.PP 253 +The following definitions are also supported, but are not required in simple 254 +programs: 255 +.TP 256 +\fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR 257 +.VS TIP524 258 +This allows control over what namespace will be used by the \fBoo::define\fR 259 +and \fBoo::objdefine\fR commands to look up the definition commands they 260 +use. When any object has a definition operation applied to it, \fIthe class that 261 +it is an instance of\fR (and its superclasses and mixins) is consulted for 262 +what definition namespace to use. \fBoo::define\fR gets the class definition 263 +namespace, and \fB::oo::objdefine\fR gets the instance definition namespace, 264 +but both otherwise use the identical lookup operation. 265 +.RS 266 +.PP 267 +This sets the definition namespace of kind \fIkind\fR provided by the current 268 +class to \fInamespaceName\fR. The \fInamespaceName\fR must refer to a 269 +currently existing namespace, or must be the empty string (to stop the current 270 +class from having such a namespace connected). The \fIkind\fR, if supplied, 271 +must be either \fB\-class\fR (the default) or \fB\-instance\fR to specify the 272 +whether the namespace for use with \fBoo::define\fR or \fBoo::objdefine\fR 273 +respectively is being set. 274 +.PP 275 +The class \fBoo::object\fR has its instance namespace locked to 276 +\fB::oo::objdefine\fR, and the class \fBoo::class\fR has its class namespace 277 +locked to \fB::oo::define\fR. A consequence of this is that effective use of 278 +this feature for classes requires the definition of a metaclass. 279 +.RE 280 +.VE TIP524 281 +.TP 282 +\fBdeletemethod\fI name\fR ?\fIname ...\fR? 283 +. 284 +This deletes each of the methods called \fIname\fR from a class. The methods 285 +must have previously existed in that class. Does not affect the superclasses 286 +of the class, nor does it affect the subclasses or instances of the class 287 +(except when they have a call chain through the class being modified) or the 288 +class object itself. 289 +.TP 290 +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? 291 +. 292 +This slot (see \fBSLOTTED DEFINITIONS\fR below) 293 +sets or updates the list of method names that are used to guard whether 294 +method call to instances of the class may be called and what the method's 295 +results are. Each \fImethodName\fR names a single filtering method (which may 296 +be exposed or not exposed); it is not an error for a non-existent method to be 297 +named since they may be defined by subclasses. 298 +By default, this slot works by appending. 299 +.TP 300 +\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? 301 +. 302 +This slot (see \fBSLOTTED DEFINITIONS\fR below) 303 +sets or updates the list of additional classes that are to be mixed into 304 +all the instances of the class being defined. Each \fIclassName\fR argument 305 +names a single class that is to be mixed in. 306 +By default, this slot works by replacement. 307 +.TP 308 +\fBrenamemethod\fI fromName toName\fR 309 +. 310 +This renames the method called \fIfromName\fR in a class to \fItoName\fR. The 311 +method must have previously existed in the class, and \fItoName\fR must not 312 +previously refer to a method in that class. Does not affect the superclasses 313 +of the class, nor does it affect the subclasses or instances of the class 314 +(except when they have a call chain through the class being modified), or the 315 +class object itself. Does 316 +not change the export status of the method; if it was exported before, it will 317 +be afterwards. 318 +.SH "CONFIGURING OBJECTS" 201 319 .PP 202 320 The following commands are supported in the \fIdefScript\fR for 203 321 \fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR 204 322 form: 205 323 .TP 206 -\fBclass\fI className\fR 207 -. 208 -This allows the class of an object to be changed after creation. Note that the 209 -class's constructors are not called when this is done, and so the object may 210 -well be in an inconsistent state unless additional configuration work is done. 211 -.TP 212 -\fBdeletemethod\fI name\fR ?\fIname ...\fR 213 -. 214 -This deletes each of the methods called \fIname\fR from an object. The methods 215 -must have previously existed in that object. Does not affect the classes that 216 -the object is an instance of. 217 -.TP 218 324 \fBexport\fI name \fR?\fIname ...\fR? 219 325 . 220 326 This arranges for each of the named methods, \fIname\fR, to be exported 221 327 (i.e. usable outside the object through the object's command) by the object 222 328 being defined. Note that the methods themselves may be actually defined by a 223 329 class or superclass; object exports override class visibility. 224 -.TP 225 -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? 226 -.VS 227 -This slot (see \fBSLOTTED DEFINITIONS\fR below) 228 -.VE 229 -sets or updates the list of method names that are used to guard whether a 230 -method call to the object may be called and what the method's results are. 231 -Each \fImethodName\fR names a single filtering method (which may be exposed or 232 -not exposed); it is not an error for a non-existent method to be named. Note 233 -that the actual list of filters also depends on the filters set upon any 234 -classes that the object is an instance of. 235 -.VS 236 -By default, this slot works by appending. 237 -.VE 238 330 .TP 239 331 \fBforward\fI name cmdName \fR?\fIarg ...\fR? 240 332 . 241 333 This creates or updates a forwarded object method called \fIname\fR. The 242 334 method is defined be forwarded to the command called \fIcmdName\fR, with 243 335 additional arguments, \fIarg\fR etc., added before those arguments specified 244 336 by the caller of the method. Forwarded methods should be deleted using the 245 337 \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with 246 338 a lower-case letter, and non-exported otherwise. 339 +.RS 340 +.PP 341 +.VS TIP500 342 +If in a private definition context (see the \fBprivate\fR definition command, 343 +below), this command creates private forwarded methods. 344 +.VE TIP500 345 +.RE 247 346 .TP 248 -\fBmethod\fI name argList bodyScript\fR 347 +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR 249 348 . 250 349 This creates, updates or deletes an object method. The name of the method is 251 350 \fIname\fR, the formal arguments to the method (defined using the same format 252 351 as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the 253 352 method will be \fIbodyScript\fR. When the body of the method is evaluated, the 254 353 current namespace of the method will be a namespace that is unique to the 255 354 object. The method will be exported if \fIname\fR starts with a lower-case 256 -letter, and non-exported otherwise. 355 +letter, and non-exported otherwise; 356 +.VS TIP519 357 +this can be overridden by specifying \fB\-export\fR, \fB\-private\fR or 358 +\fB\-unexport\fR in the optional parameter \fIoption\fR, or via the 359 +\fBexport\fR and \fBunexport\fR definitions. 360 +.VE TIP519 361 +.RS 362 +.PP 363 +.VS TIP500 364 +If in a private definition context (see the \fBprivate\fR definition command, 365 +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command 366 +creates private procedure-like methods. 367 +.VE TIP500 368 +.RE 257 369 .TP 258 370 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR? 259 -.VS 371 +. 260 372 This slot (see \fBSLOTTED DEFINITIONS\fR below) 261 -.VE 262 373 sets or updates a per-object list of additional classes that are to be 263 374 mixed into the object. Each argument, \fIclassName\fR, names a single class 264 375 that is to be mixed in. 265 -.VS 266 376 By default, this slot works by replacement. 267 -.VE 268 377 .TP 269 -\fBrenamemethod\fI fromName toName\fR 270 -. 271 -This renames the method called \fIfromName\fR in an object to \fItoName\fR. 272 -The method must have previously existed in the object, and \fItoName\fR must 273 -not previously refer to a method in that object. Does not affect the classes 274 -that the object is an instance of. Does not change the export status of the 275 -method; if it was exported before, it will be afterwards. 378 +\fBprivate \fIcmd arg...\fR 276 379 .TP 277 -\fBself \fR 278 -. 279 -.VS TIP470 280 -This gives the name of the object currently being configured. 281 -.VE TIP470 380 +\fBprivate \fIscript\fR 381 +.VS TIP500 382 +This evaluates the \fIscript\fR (or the list of command and arguments given by 383 +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the 384 +current object will be private definitions. 385 +.RS 386 +.PP 387 +The following class definition commands are affected by \fBprivate\fR: 388 +\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside 389 +\fBprivate\fR has no cumulative effect; the innermost definition context is 390 +just a private definition context. All other definition commands have no 391 +difference in behavior when used in a private definition context. 392 +.RE 393 +.VE TIP500 282 394 .TP 283 395 \fBunexport\fI name \fR?\fIname ...\fR? 284 396 . 285 397 This arranges for each of the named methods, \fIname\fR, to be not exported 286 398 (i.e. not usable outside the object through the object's command, but instead 287 399 just through the \fBmy\fR command visible in the object's context) by the 288 400 object being defined. Note that the methods themselves may be actually defined 289 401 by a class; instance unexports override class visibility. 290 402 .TP 291 403 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR? 292 -.VS 404 +. 293 405 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named 294 406 variables to be automatically made available in the methods declared by the 295 407 object being defined. Each variable name must not have any namespace 296 408 separators and must not look like an array access. All variables will be 297 -actually present in the object on which the method is executed. Note that the 409 +actually present in the namespace of the object on which the method is 410 +executed. Note that the 298 411 variable lists declared by the classes and mixins of which the object is an 299 412 instance are completely disjoint; the list of variable names is just for 300 413 methods declared by this object. By default, this slot works by appending. 414 +.RS 415 +.PP 416 +.VS TIP500 417 +If in a private definition context (see the \fBprivate\fR definition command, 418 +below), this slot manipulates the list of private variable bindings for this 419 +object. In a private variable binding, the name of the variable within the 420 +instance object is different to the name given in the definition; the name 421 +used in the definition is the name that you use to access the variable within 422 +the methods of this instance object, and the name of the variable in the 423 +instance namespace has a unique prefix that makes accidental use from 424 +superclass methods extremely unlikely. 425 +.VE TIP500 426 +.RE 427 +.SS "ADVANCED OBJECT CONFIGURATION OPTIONS" 428 +.PP 429 +The following definitions are also supported, but are not required in simple 430 +programs: 431 +.TP 432 +\fBclass\fI className\fR 433 +. 434 +This allows the class of an object to be changed after creation. Note that the 435 +class's constructors are not called when this is done, and so the object may 436 +well be in an inconsistent state unless additional configuration work is done. 437 +.TP 438 +\fBdeletemethod\fI name\fR ?\fIname ...\fR 439 +. 440 +This deletes each of the methods called \fIname\fR from an object. The methods 441 +must have previously existed in that object (e.g., because it was created 442 +through \fBoo::objdefine method\fR). Does not affect the classes that the 443 +object is an instance of, or remove the exposure of those class-provided 444 +methods in the instance of that class. 445 +.TP 446 +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR? 447 +. 448 +This slot (see \fBSLOTTED DEFINITIONS\fR below) 449 +sets or updates the list of method names that are used to guard whether a 450 +method call to the object may be called and what the method's results are. 451 +Each \fImethodName\fR names a single filtering method (which may be exposed or 452 +not exposed); it is not an error for a non-existent method to be named. Note 453 +that the actual list of filters also depends on the filters set upon any 454 +classes that the object is an instance of. 455 +By default, this slot works by appending. 456 +.TP 457 +\fBrenamemethod\fI fromName toName\fR 458 +. 459 +This renames the method called \fIfromName\fR in an object to \fItoName\fR. 460 +The method must have previously existed in the object, and \fItoName\fR must 461 +not previously refer to a method in that object. Does not affect the classes 462 +that the object is an instance of and cannot rename in an instance object the 463 +methods provided by those classes (though a \fBoo::objdefine forward\fRed 464 +method may provide an equivalent capability). Does not change the export 465 +status of the method; if it was exported before, it will be afterwards. 466 +.TP 467 +\fBself \fR 468 +.VS TIP470 469 +This gives the name of the object currently being configured. 470 +.VE TIP470 471 +.SH "PRIVATE METHODS" 472 +.VS TIP500 473 +When a class or instance has a private method, that private method can only be 474 +invoked from within methods of that class or instance. Other callers of the 475 +object's methods \fIcannot\fR invoke private methods, it is as if the private 476 +methods do not exist. However, a private method of a class \fIcan\fR be 477 +invoked from the class's methods when those methods are being used on another 478 +instance object; this means that a class can use them to coordinate behaviour 479 +between several instances of itself without interfering with how other 480 +classes (especially either subclasses or superclasses) interact. Private 481 +methods precede all mixed in classes in the method call order (as reported by 482 +\fBself call\fR). 483 +.VE TIP500 301 484 .SH "SLOTTED DEFINITIONS" 302 485 Some of the configurable definitions of a class or object are \fIslotted 303 486 definitions\fR. This means that the configuration is implemented by a slot 304 487 object, that is an instance of the class \fBoo::Slot\fR, which manages a list 305 488 of values (class names, variable names, etc.) that comprises the contents of 306 -the slot. The class defines three operations (as methods) that may be done on 489 +the slot. The class defines five operations (as methods) that may be done on 307 490 the slot: 308 -.VE 309 491 .TP 310 492 \fIslot\fR \fB\-append\fR ?\fImember ...\fR? 311 -.VS 493 +. 312 494 This appends the given \fImember\fR elements to the slot definition. 313 -.VE 314 495 .TP 315 496 \fIslot\fR \fB\-clear\fR 316 -.VS 497 +. 317 498 This sets the slot definition to the empty list. 318 -.VE 499 +.TP 500 +\fIslot\fR \fB\-prepend\fR ?\fImember ...\fR? 501 +.VS TIP516 502 +This prepends the given \fImember\fR elements to the slot definition. 503 +.VE TIP516 504 +.TP 505 +\fIslot\fR \fB\-remove\fR ?\fImember ...\fR? 506 +.VS TIP516 507 +This removes the given \fImember\fR elements from the slot definition. 508 +.VE TIP516 319 509 .TP 320 510 \fIslot\fR \fB\-set\fR ?\fImember ...\fR? 321 -.VS 511 +. 322 512 This replaces the slot definition with the given \fImember\fR elements. 323 513 .PP 324 514 A consequence of this is that any use of a slot's default operation where the 325 515 first member argument begins with a hyphen will be an error. One of the above 326 516 operations should be used explicitly in those circumstances. 327 517 .SS "SLOT IMPLEMENTATION" 328 518 Internally, slot objects also define a method \fB\-\-default\-operation\fR 329 519 which is forwarded to the default operation of the slot (thus, for the class 330 520 .QW \fBvariable\fR 331 521 slot, this is forwarded to 332 522 .QW "\fBmy \-append\fR" ), 333 523 and these methods which provide the implementation interface: 334 -.VE 335 524 .TP 336 525 \fIslot\fR \fBGet\fR 337 -.VS 338 -Returns a list that is the current contents of the slot. This method must 339 -always be called from a stack frame created by a call to \fBoo::define\fR or 340 -\fBoo::objdefine\fR. 341 -.VE 526 +. 527 +Returns a list that is the current contents of the slot, but does not modify 528 +the slot. This method must always be called from a stack frame created by a 529 +call to \fBoo::define\fR or \fBoo::objdefine\fR. This method \fIshould not\fR 530 +return an error unless it is called from outside a definition context or with 531 +the wrong number of arguments. 532 +.RS 533 +.PP 534 +.VS TIP516 535 +The elements of the list should be fully resolved, if that is a meaningful 536 +concept to the slot. 537 +.VE TIP516 538 +.RE 539 +.TP 540 +\fIslot\fR \fBResolve\fR \fIslotElement\fR 541 +.VS TIP516 542 +Returns \fIslotElement\fR with a resolution operation applied to it, but does 543 +not modify the slot. For slots of simple strings, this is an operation that 544 +does nothing, whereas for slots of classes, this maps a class name to its 545 +fully-qualified class name. This method must always be called from a stack 546 +frame created by a call to \fBoo::define\fR or \fBoo::objdefine\fR. This 547 +method \fIshould not\fR return an error unless it is called from outside a 548 +definition context or with the wrong number of arguments; unresolvable 549 +arguments should be returned as is (as not all slot operations strictly 550 +require that values are resolvable to work). 551 +.RS 552 +.PP 553 +Implementations \fIshould not\fR enforce uniqueness and ordering constraints 554 +in this method; that is the responsibility of the \fBSet\fR method. 555 +.RE 556 +.VE TIP516 342 557 .TP 343 558 \fIslot\fR \fBSet \fIelementList\fR 344 -.VS 559 +. 345 560 Sets the contents of the slot to the list \fIelementList\fR and returns the 346 561 empty string. This method must always be called from a stack frame created by 347 -a call to \fBoo::define\fR or \fBoo::objdefine\fR. 562 +a call to \fBoo::define\fR or \fBoo::objdefine\fR. This method may return an 563 +error if it rejects the change to the slot contents (e.g., because of invalid 564 +values) as well as if it is called from outside a definition context or with 565 +the wrong number of arguments. 566 +.RS 567 +.PP 568 +This method \fImay\fR reorder and filter the elements if this is necessary in 569 +order to satisfy the underlying constraints of the slot. (For example, slots 570 +of classes enforce a uniqueness constraint that places each element in the 571 +earliest location in the slot that it can.) 572 +.RE 348 573 .PP 349 574 The implementation of these methods is slot-dependent (and responsible for 350 575 accessing the correct part of the class or object definition). Slots also have 351 576 an unknown method handler to tie all these pieces together, and they hide 352 577 their \fBdestroy\fR method so that it is not invoked inadvertently. It is 353 578 \fIrecommended\fR that any user changes to the slot mechanism be restricted to 354 579 defining new operations whose names start with a hyphen. 355 -.VE 580 +.PP 581 +.VS TIP516 582 +Most slot operations will initially \fBResolve\fR their argument list, combine 583 +it with the results of the \fBGet\fR method, and then \fBSet\fR the result. 584 +Some operations omit one or both of the first two steps; omitting the third 585 +would result in an idempotent read-only operation (but the standard mechanism 586 +for reading from slots is via \fBinfo class\fR and \fBinfo object\fR). 587 +.VE TIP516 356 588 .SH EXAMPLES 357 589 This example demonstrates how to use both forms of the \fBoo::define\fR and 358 590 \fBoo::objdefine\fR commands (they work in the same way), as well as 359 -illustrating four of the subcommands of them. 591 +illustrating four of their subcommands. 360 592 .PP 361 593 .CS 362 594 oo::class create c 363 595 c create o 364 596 \fBoo::define\fR c \fBmethod\fR foo {} { 365 597 puts "world" 366 598 } ................................................................................ 405 637 } 406 638 \fBoo::objdefine\fR inst { 407 639 \fBmixin -append\fR B 408 640 } 409 641 inst m1 \fI\(-> prints "red brick"\fR 410 642 inst m2 \fI\(-> prints "blue brick"\fR 411 643 .CE 644 +.PP 645 +.VS TIP478 646 +This example shows how to create and use class variables. It is a class that 647 +counts how many instances of itself have been made. 648 +.PP 649 +.CS 650 +oo::class create Counted 651 +\fBoo::define\fR Counted { 652 + \fBinitialise\fR { 653 + variable count 0 654 + } 655 + 656 + \fBvariable\fR number 657 + \fBconstructor\fR {} { 658 + classvariable count 659 + set number [incr count] 660 + } 661 + 662 + \fBmethod\fR report {} { 663 + classvariable count 664 + puts "This is instance $number of $count" 665 + } 666 +} 667 + 668 +set a [Counted new] 669 +set b [Counted new] 670 +$a report 671 + \fI\(-> This is instance 1 of 2\fR 672 +set c [Counted new] 673 +$b report 674 + \fI\(-> This is instance 2 of 3\fR 675 +$c report 676 + \fI\(-> This is instance 3 of 3\fR 677 +.CE 678 +.PP 679 +This example demonstrates how to use class methods. (Note that the constructor 680 +for \fBoo::class\fR calls \fBoo::define\fR on the class.) 681 +.PP 682 +.CS 683 +oo::class create DBTable { 684 + \fBclassmethod\fR find {description} { 685 + puts "DB: locate row from [self] matching $description" 686 + return [my new] 687 + } 688 + \fBclassmethod\fR insert {description} { 689 + puts "DB: create row in [self] matching $description" 690 + return [my new] 691 + } 692 + \fBmethod\fR update {description} { 693 + puts "DB: update row [self] with $description" 694 + } 695 + \fBmethod\fR delete {} { 696 + puts "DB: delete row [self]" 697 + my destroy; # Just delete the object, not the DB row 698 + } 699 +} 700 + 701 +oo::class create Users { 702 + \fBsuperclass\fR DBTable 703 +} 704 +oo::class create Groups { 705 + \fBsuperclass\fR DBTable 706 +} 707 + 708 +set u1 [Users insert "username=abc"] 709 + \fI\(-> DB: create row from ::Users matching username=abc\fR 710 +set u2 [Users insert "username=def"] 711 + \fI\(-> DB: create row from ::Users matching username=def\fR 712 +$u2 update "group=NULL" 713 + \fI\(-> DB: update row ::oo::Obj124 with group=NULL\fR 714 +$u1 delete 715 + \fI\(-> DB: delete row ::oo::Obj123\fR 716 +set g [Group find "groupname=webadmins"] 717 + \fI\(-> DB: locate row ::Group with groupname=webadmins\fR 718 +$g update "emailaddress=admins" 719 + \fI\(-> DB: update row ::oo::Obj125 with emailaddress=admins\fR 720 +.CE 721 +.VE TIP478 722 +.PP 723 +.VS TIP524 724 +This example shows how to make a custom definition for a class. Note that it 725 +explicitly includes delegation to the existing definition commands via 726 +\fBnamespace path\fR. 727 +.PP 728 +.CS 729 +namespace eval myDefinitions { 730 + # Delegate to existing definitions where not overridden 731 + namespace path \fB::oo::define\fR 732 + 733 + # A custom type of method 734 + proc exprmethod {name arguments body} { 735 + tailcall \fBmethod\fR $name $arguments [list expr $body] 736 + } 737 + 738 + # A custom way of building a constructor 739 + proc parameters args { 740 + uplevel 1 [list \fBvariable\fR {*}$args] 741 + set body [join [lmap a $args { 742 + string map [list VAR $a] { 743 + set [my varname VAR] [expr {double($VAR)}] 744 + } 745 + }] ";"] 746 + tailcall \fBconstructor\fR $args $body 747 + } 748 +} 749 + 750 +# Bind the namespace into a (very simple) metaclass for use 751 +oo::class create exprclass { 752 + \fBsuperclass\fR oo::class 753 + \fBdefinitionnamespace\fR myDefinitions 754 +} 755 + 756 +# Use the custom definitions 757 +exprclass create quadratic { 758 + parameters a b c 759 + exprmethod evaluate {x} { 760 + ($a * $x**2) + ($b * $x) + $c 761 + } 762 +} 763 + 764 +# Showing the resulting class and object in action 765 +quadratic create quad 1 2 3 766 +for {set x 0} {$x <= 4} {incr x} { 767 + puts [format "quad(%d) = %.2f" $x [quad evaluate $x]] 768 +} 769 + \fI\(-> quad(0) = 3.00\fR 770 + \fI\(-> quad(1) = 6.00\fR 771 + \fI\(-> quad(2) = 11.00\fR 772 + \fI\(-> quad(3) = 18.00\fR 773 + \fI\(-> quad(4) = 27.00\fR 774 +.CE 775 +.VE TIP524 412 776 .SH "SEE ALSO" 413 777 next(n), oo::class(n), oo::object(n) 414 778 .SH KEYWORDS 415 779 class, definition, method, object, slot 416 780 .\" Local variables: 417 781 .\" mode: nroff 418 782 .\" fill-column: 78 419 783 .\" End:
Changes to doc/dict.n.
23 23 \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR? 24 24 . 25 25 This appends the given string (or strings) to the value that the given 26 26 key maps to in the dictionary value contained in the given variable, 27 27 writing the resulting dictionary value back to that variable. 28 28 Non-existent keys are treated as if they map to an empty string. The 29 29 updated dictionary value is returned. 30 +.VS TIP508 31 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 32 +array that has a default value set, the default value and will be used as the 33 +value of the dictionary prior to the appending operation. 34 +.VE TIP508 30 35 .TP 31 36 \fBdict create \fR?\fIkey value ...\fR? 32 37 . 33 38 Return a new dictionary that contains each of the key/value mappings 34 39 listed as arguments (keys and values alternating, with each key being 35 40 followed by its associated value.) 36 41 .TP ................................................................................ 110 115 elements in a manner similar to \fBarray get\fR. That is, the first 111 116 element of each pair would be the key and the second element would be 112 117 the value for that key. 113 118 .PP 114 119 It is an error to attempt to retrieve a value for a key that is not 115 120 present in the dictionary. 116 121 .RE 122 +.TP 123 +\fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR 124 +.TP 125 +\fBdict getwithdefault \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR 126 +.VS "8.7, TIP342" 127 +This behaves the same as \fBdict get\fR (with at least one \fIkey\fR 128 +argument), returning the value that the key path maps to in the 129 +dictionary \fIdictionaryValue\fR, except that instead of producing an 130 +error because the \fIkey\fR (or one of the \fIkey\fRs on the key path) 131 +is absent, it returns the \fIdefault\fR argument instead. 132 +.RS 133 +.PP 134 +Note that there must always be at least one \fIkey\fR provided, and that 135 +\fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other. 136 +.RE 137 +.VE "8.7, TIP342" 117 138 .TP 118 139 \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? 119 140 . 120 141 This adds the given increment value (an integer that defaults to 1 if 121 142 not specified) to the value that the given key maps to in the 122 143 dictionary value contained in the given variable, writing the 123 144 resulting dictionary value back to that variable. Non-existent keys 124 145 are treated as if they map to 0. It is an error to increment a value 125 146 for an existing key if that value is not an integer. The updated 126 147 dictionary value is returned. 148 +.VS TIP508 149 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 150 +array that has a default value set, the default value and will be used as the 151 +value of the dictionary prior to the incrementing operation. 152 +.VE TIP508 127 153 .TP 128 154 \fBdict info \fIdictionaryValue\fR 129 155 . 130 156 This returns information (intended for display to people) about the 131 157 given dictionary though the format of this data is dependent on the 132 158 implementation of the dictionary. For dictionaries that are 133 159 implemented by hash tables, it is expected that this will return the ................................................................................ 145 171 This appends the given items to the list value that the given key maps 146 172 to in the dictionary value contained in the given variable, writing 147 173 the resulting dictionary value back to that variable. Non-existent 148 174 keys are treated as if they map to an empty list, and it is legal for 149 175 there to be no items to append to the list. It is an error for the 150 176 value that the key maps to to not be representable as a list. The 151 177 updated dictionary value is returned. 178 +.VS TIP508 179 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 180 +array that has a default value set, the default value and will be used as the 181 +value of the dictionary prior to the list-appending operation. 182 +.VE TIP508 152 183 .TP 153 184 \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR 154 185 . 155 186 This command applies a transformation to each element of a dictionary, 156 187 returning a new dictionary. It takes three arguments: the first is a 157 188 two-element list of variable names (for the key and value respectively of each 158 189 mapping in the dictionary), the second the dictionary value to iterate across, ................................................................................ 202 233 \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR 203 234 . 204 235 This operation takes the name of a variable containing a dictionary 205 236 value and places an updated dictionary value in that variable 206 237 containing a mapping from the given key to the given value. When 207 238 multiple keys are present, this operation creates or updates a chain 208 239 of nested dictionaries. The updated dictionary value is returned. 240 +.VS TIP508 241 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 242 +array that has a default value set, the default value and will be used as the 243 +value of the dictionary prior to the value insert/update operation. 244 +.VE TIP508 209 245 .TP 210 246 \fBdict size \fIdictionaryValue\fR 211 247 . 212 248 Return the number of key/value mappings in the given dictionary value. 213 249 .TP 214 250 \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR? 215 251 . ................................................................................ 217 253 variable containing a dictionary value and places an updated 218 254 dictionary value in that variable that does not contain a mapping for 219 255 the given key. Where multiple keys are present, this describes a path 220 256 through nested dictionaries to the mapping to remove. At least one key 221 257 must be specified, but the last key on the key-path need not exist. 222 258 All other components on the path must exist. The updated dictionary 223 259 value is returned. 260 +.VS TIP508 261 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 262 +array that has a default value set, the default value and will be used as the 263 +value of the dictionary prior to the value remove operation. 264 +.VE TIP508 224 265 .TP 225 266 \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR 226 267 . 227 268 Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR 228 269 (as found by reading the dictionary value in \fIdictionaryVariable\fR) 229 270 mapped to the variable \fIvarName\fR. There may be multiple 230 271 \fIkey\fR/\fIvarName\fR pairs. If a \fIkey\fR does not have a mapping, ................................................................................ 232 273 terminates, any changes made to the \fIvarName\fRs is reflected back 233 274 to the dictionary within \fIdictionaryVariable\fR (unless 234 275 \fIdictionaryVariable\fR itself becomes unreadable, when all updates 235 276 are silently discarded), even if the result of \fIbody\fR is an error 236 277 or some other kind of exceptional exit. The result of \fBdict 237 278 update\fR is (unless some kind of error occurs) the result of the 238 279 evaluation of \fIbody\fR. 280 +.VS TIP508 281 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 282 +array that has a default value set, the default value and will be used as the 283 +value of the dictionary prior to the update operation. 284 +.VE TIP508 239 285 .RS 240 286 .PP 241 287 Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR; 242 288 it is recommended that this command only be used in a local scope 243 289 (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of 244 290 this, the variables set by \fBdict update\fR will continue to 245 291 exist after the command finishes (unless explicitly \fBunset\fR). ................................................................................ 266 312 for the execution of \fIbody\fR. As with \fBdict update\fR, making 267 313 \fIdictionaryVariable\fR unreadable will make the updates to the 268 314 dictionary be discarded, and this also happens if the contents of 269 315 \fIdictionaryVariable\fR are adjusted so that the chain of 270 316 dictionaries no longer exists. The result of \fBdict with\fR is 271 317 (unless some kind of error occurs) the result of the evaluation of 272 318 \fIbody\fR. 319 +.VS TIP508 320 +If \fIdictionaryVarable\fR indicates an element that does not exist of an 321 +array that has a default value set, the default value and will be used as the 322 +value of the dictionary prior to the updating operation. 323 +.VE TIP508 273 324 .RS 274 325 .PP 275 326 The variables are mapped in the scope enclosing the \fBdict with\fR; 276 327 it is recommended that this command only be used in a local scope 277 328 (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of 278 329 this, the variables set by \fBdict with\fR will continue to 279 330 exist after the command finishes (unless explicitly \fBunset\fR).
Changes to doc/eof.n.
55 55 puts "Read record: $record" 56 56 } 57 57 .CE 58 58 .SH "SEE ALSO" 59 59 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3) 60 60 .SH KEYWORDS 61 61 channel, end of file 62 +'\" Local Variables: 63 +'\" mode: nroff 64 +'\" fill-column: 78 65 +'\" End:
Changes to doc/exec.n.
212 212 .QW \[email protected]\0\fIfileId\fR 213 213 notation, does not work. When reading from a socket, a 16-bit DOS 214 214 application will hang and a 32-bit application will return immediately with 215 215 end-of-file. When either type of application writes to a socket, the 216 216 information is instead sent to the console, if one is present, or is 217 217 discarded. 218 218 .RS 219 +.PP 220 +Note that the current escape resp. quoting of arguments for windows works only 221 +with executables using CommandLineToArgv, CRT-library or similar, as well as 222 +with the windows batch files (excepting the newline, see below). 223 +Although it is the common escape algorithm, but, in fact, the way how the 224 +executable parses the command-line (resp. splits it into single arguments) 225 +is decisive. 226 +.PP 227 +Unfortunately, there is currently no way to supply newline character within 228 +an argument to the batch files (\fB.cmd\fR or \fB.bat\fR) or to the command 229 +processor (\fBcmd.exe /c\fR), because this causes truncation of command-line 230 +(also the argument chain) on the first newline character. 231 +But it works properly with an executable (using CommandLineToArgv, etc). 219 232 .PP 220 233 The Tk console text widget does not provide real standard IO capabilities. 221 234 Under Tk, when redirecting from standard input, all applications will see an 222 235 immediate end-of-file; information redirected to standard output or standard 223 236 error will be discarded. 224 237 .PP 225 238 Either forward or backward slashes are accepted as path separators for ................................................................................ 405 418 .CS 406 419 \fBexec\fR cmp.bat somefile.c -o somefile 407 420 .CE 408 421 .PP 409 422 With the file \fIcmp.bat\fR looking something like: 410 423 .PP 411 424 .CS 425 +@gcc %* 426 +.CE 427 +or like another variant using single parameters: 428 +.CS 412 429 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 413 430 .CE 414 431 .SS "WORKING WITH COMMAND BUILT-INS" 415 432 .PP 416 433 Sometimes you need to be careful, as different programs may have the 417 434 same name and be in the path. It can then happen that typing a command 418 435 at the DOS prompt finds \fIa different program\fR than the same
Changes to doc/exit.n.
45 45 \fBexit\fR 2 46 46 } 47 47 .CE 48 48 .SH "SEE ALSO" 49 49 exec(n) 50 50 .SH KEYWORDS 51 51 abort, exit, process 52 +'\" Local Variables: 53 +'\" mode: nroff 54 +'\" fill-column: 78 55 +'\" End:
Changes to doc/expr.n.
91 91 \fBTcl\fR. 92 92 .PP 93 93 Below are some examples of simple expressions where the value of \fBa\fR is 3 94 94 and the value of \fBb\fR is 6. The command on the left side of each line 95 95 produces the value on the right side. 96 96 .PP 97 97 .CS 98 -.ta 6c 98 +.ta 9c 99 99 \fBexpr\fR 3.1 + $a \fI6.1\fR 100 100 \fBexpr\fR 2 + "$a.$b" \fI5.6\fR 101 101 \fBexpr\fR 4*[llength "6 2"] \fI8\fR 102 102 \fBexpr\fR {{word one} < "word $a"} \fI0\fR 103 103 .CE 104 104 .SS OPERATORS 105 105 .PP ................................................................................ 120 120 . 121 121 Unary minus, unary plus, bit-wise NOT, logical NOT. These operators 122 122 may only be applied to numeric operands, and bit-wise NOT may only be 123 123 applied to integers. 124 124 .TP 20 125 125 \fB**\fR 126 126 . 127 -Exponentiation. Valid for numeric operands. 127 +Exponentiation. Valid for numeric operands. The maximum exponent value 128 +that Tcl can handle if the first number is an integer > 1 is 268435455. 128 129 .TP 20 129 130 \fB*\0\0/\0\0%\fR 130 131 . 131 132 Multiply and divide, which are valid for numeric operands, and remainder, which 132 133 is valid for integers. The remainder, an absolute value smaller than the 133 134 absolute value of the divisor, has the same sign as the divisor. 134 135 .RS ................................................................................ 183 184 \fB|\fR 184 185 . 185 186 Bit-wise OR. Valid for integer operands. 186 187 .TP 20 187 188 \fB&&\fR 188 189 . 189 190 Logical AND. If both operands are true, the result is 1, or 0 otherwise. 190 - 191 +This operator evaluates lazily; it only evaluates its second operand if it 192 +must in order to determine its result. 193 +This operator evaluates lazily; it only evaluates its second operand if it 194 +must in order to determine its result. 191 195 .TP 20 192 196 \fB||\fR 193 197 . 194 198 Logical OR. If both operands are false, the result is 0, or 1 otherwise. 199 +This operator evaluates lazily; it only evaluates its second operand if it 200 +must in order to determine its result. 195 201 .TP 20 196 -\fIx\fB?\fIy\fB:\fIz\fR 202 +\fIx \fB?\fI y \fB:\fI z\fR 197 203 . 198 204 If-then-else, as in C. If \fIx\fR is false , the result is the value of 199 205 \fIy\fR. Otherwise the result is the value of \fIz\fR. 206 +This operator evaluates lazily; it evaluates only one of \fIy\fR or \fIz\fR. 200 207 .PP 201 208 The exponentiation operator promotes types in the same way that the multiply 202 209 and divide operators do, and the result is is the same as the result of 203 210 \fBpow\fR. 204 211 Exponentiation groups right-to-left within a precedence level. Other binary 205 212 operators group left-to-right. For example, the value of 213 +.PP 206 214 .PP 207 215 .CS 208 216 \fBexpr\fR {4*2 < 7} 209 217 .CE 210 218 .PP 211 219 is 0, while the value of 212 220 .PP ................................................................................ 330 338 substitutions on, enclosing an expression in braces or otherwise quoting it 331 339 so that it's a static value allows the Tcl compiler to generate bytecode for 332 340 the expression, resulting in better speed and smaller storage requirements. 333 341 This also avoids issues that can arise if Tcl is allowed to perform 334 342 substitution on the value before \fBexpr\fR is called. 335 343 .PP 336 344 In the following example, the value of the expression is 11 because the Tcl parser first 337 -substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR. Enclosing the 338 -expression in braces would result in a syntax error. 345 +substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR as part 346 +of evaluating the expression 347 +.QW "$a + 2*4" . 348 +Enclosing the 349 +expression in braces would result in a syntax error as \fB$b\fR does 350 +not evaluate to a numeric value. 351 +.PP 339 352 .CS 340 353 set a 3 341 354 set b {$a + 2} 342 355 \fBexpr\fR $b*4 343 356 .CE 344 357 .PP 345 - 346 -When an expression is generated at runtime, like the one above is, the bytcode 358 +When an expression is generated at runtime, like the one above is, the bytecode 347 359 compiler must ensure that new code is generated each time the expression 348 360 is evaluated. This is the most costly kind of expression from a performance 349 361 perspective. In such cases, consider directly using the commands described in 350 362 the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR. 351 - 363 +.PP 352 364 Most expressions are not formed at runtime, but are literal strings or contain 353 365 substitutions that don't introduce other substitutions. To allow the bytecode 354 366 compiler to work with an expression as a string literal at compilation time, 355 367 ensure that it contains no substitutions or that it is enclosed in braces or 356 368 otherwise quoted to prevent Tcl from performing substitutions, allowing 357 369 \fBexpr\fR to perform them instead. 370 +.PP 371 +If it is necessary to include a non-constant expression string within the 372 +wider context of an otherwise-constant expression, the most efficient 373 +technique is to put the varying part inside a recursive \fBexpr\fR, as this at 374 +least allows for the compilation of the outer part, though it does mean that 375 +the varying part must itself be evaluated as a separate expression. Thus, in 376 +this example the result is 20 and the outer expression benefits from fully 377 +cached bytecode compilation. 378 +.PP 379 +.CS 380 +set a 3 381 +set b {$a + 2} 382 +\fBexpr\fR {[\fBexpr\fR $b] * 4} 383 +.CE 384 +.PP 385 +In general, you should enclose your expression in braces wherever possible, 386 +and where not possible, the argument to \fBexpr\fR should be an expression 387 +defined elsewhere as simply as possible. It is usually more efficient and 388 +safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR 389 +namespace) than it is to do complex expression generation. 358 390 .SH EXAMPLES 359 391 .PP 360 392 A numeric comparison whose result is 1: 393 +.PP 361 394 .CS 362 395 \fBexpr\fR {"0x03" > "2"} 363 396 .CE 364 397 .PP 365 398 A string comparison whose result is 1: 399 +.PP 366 400 .CS 367 401 \fBexpr\fR {"0y" > "0x12"} 368 402 .CE 369 403 .PP 370 404 Define a procedure that computes an 371 405 .QW interesting 372 406 mathematical function:
Changes to doc/fblocked.n.
61 61 socket -server connect 12345 62 62 vwait forever 63 63 .CE 64 64 .SH "SEE ALSO" 65 65 gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3) 66 66 .SH KEYWORDS 67 67 blocking, nonblocking 68 +'\" Local Variables: 69 +'\" mode: nroff 70 +'\" fill-column: 78 71 +'\" End:
Changes to doc/file.n.
428 428 \fBfile tail \fIname\fR 429 429 . 430 430 Returns all of the characters in the last filesystem component of 431 431 \fIname\fR. Any trailing directory separator in \fIname\fR is ignored. 432 432 If \fIname\fR contains no separators then returns \fIname\fR. So, 433 433 \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all 434 434 return \fBb\fR. 435 +.TP 436 +\fBfile tempdir\fR ?\fItemplate\fR? 437 +.VS "8.7, TIP 431" 438 +Creates a temporary directory (guaranteed to be newly created and writable by 439 +the current script) and returns its name. If \fItemplate\fR is given, it 440 +specifies one of or both of the existing directory (on a filesystem controlled 441 +by the operating system) to contain the temporary directory, and the base part 442 +of the directory name; it is considered to have the location of the directory 443 +if there is a directory separator in the name, and the base part is everything 444 +after the last directory separator (if non-empty). The default containing 445 +directory is determined by system-specific operations, and the default base 446 +name prefix is 447 +.QW \fBtcl\fR . 448 +.RS 449 +.PP 450 +The following output is typical and illustrative; the actual output will vary 451 +between platforms: 452 +.PP 453 +.CS 454 +% \fBfile tempdir\fR 455 +/var/tmp/tcl_u0kuy5 456 + % \fBfile tempdir\fR /tmp/myapp 457 +/tmp/myapp_8o7r9L 458 +% \fBfile tempdir\fR /tmp/ 459 +/tmp/tcl_1mOJHD 460 +% \fBfile tempdir\fR myapp 461 +/var/tmp/myapp_0ihS0n 462 +.CE 463 +.RE 464 +.VE "8.7, TIP 431" 435 465 .TP 436 466 \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? 437 467 '\" TIP #210 438 468 .VS 8.6 439 469 Creates a temporary file and returns a read-write channel opened on that file. 440 470 If the \fInameVar\fR is given, it specifies a variable that the name of the 441 471 temporary file will be written into; if absent, Tcl will attempt to arrange
Changes to doc/fileevent.n.
150 150 \fBfileevent\fR is based on the \fBaddinput\fR command created 151 151 by Mark Diekhans. 152 152 .SH "SEE ALSO" 153 153 fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3) 154 154 .SH KEYWORDS 155 155 asynchronous I/O, blocking, channel, event handler, nonblocking, readable, 156 156 script, writable. 157 +'\" Local Variables: 158 +'\" mode: nroff 159 +'\" fill-column: 78 160 +'\" End:
Changes to doc/filename.n.
172 172 .QW .....abc 173 173 is illegal. 174 174 .SH "SEE ALSO" 175 175 file(n), glob(n) 176 176 .SH KEYWORDS 177 177 current directory, absolute file name, relative file name, 178 178 volume-relative file name, portability 179 +'\" Local Variables: 180 +'\" mode: nroff 181 +'\" fill-column: 78 182 +'\" End:
Changes to doc/flush.n.
39 39 gets stdin name 40 40 puts "Hello there, $name!" 41 41 .CE 42 42 .SH "SEE ALSO" 43 43 file(n), open(n), socket(n), Tcl_StandardChannels(3) 44 44 .SH KEYWORDS 45 45 blocking, buffer, channel, flush, nonblocking, output 46 +'\" Local Variables: 47 +'\" mode: nroff 48 +'\" fill-column: 78 49 +'\" End:
Changes to doc/foreach.n.
98 98 .CE 99 99 100 100 .SH "SEE ALSO" 101 101 for(n), while(n), break(n), continue(n) 102 102 103 103 .SH KEYWORDS 104 104 foreach, iteration, list, loop 105 +'\" Local Variables: 106 +'\" mode: nroff 107 +'\" fill-column: 78 108 +'\" End:
Changes to doc/global.n.
52 52 append accumulator $string \en 53 53 } 54 54 .CE 55 55 .SH "SEE ALSO" 56 56 namespace(n), upvar(n), variable(n) 57 57 .SH KEYWORDS 58 58 global, namespace, procedure, variable 59 +'\" Local Variables: 60 +'\" mode: nroff 61 +'\" fill-column: 78 62 +'\" End:
Changes to doc/history.n.
96 96 is modified to eliminate the history command and replace it with 97 97 the result of the history command. 98 98 If you want to redo an event without modifying history, then use 99 99 the \fBevent\fR operation to retrieve some event, 100 100 and the \fBadd\fR operation to add it to history and execute it. 101 101 .SH KEYWORDS 102 102 event, history, record 103 +'\" Local Variables: 104 +'\" mode: nroff 105 +'\" fill-column: 78 106 +'\" End:
Changes to doc/http.n.
2 2 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. 3 3 '\" Copyright (c) 1998-2000 by Ajuba Solutions. 4 4 '\" Copyright (c) 2004 ActiveState Corporation. 5 5 '\" 6 6 '\" See the file "license.terms" for information on usage and redistribution 7 7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 8 8 '\" 9 -.TH "http" n 2.7 http "Tcl Bundled Packages" 9 +.TH "http" n 2.9 http "Tcl Bundled Packages" 10 10 .so man.macros 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 http \- Client-side implementation of the HTTP/1.1 protocol 15 15 .SH SYNOPSIS 16 -\fBpackage require http ?2.7?\fR 16 +\fBpackage require http\fI ?\fB2.8\fR? 17 17 .\" See Also -useragent option documentation in body! 18 18 .sp 19 -\fB::http::config ?\fI\-option value\fR ...? 19 +\fB::http::config\fR ?\fI\-option value\fR ...? 20 20 .sp 21 21 \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? 22 22 .sp 23 23 \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? 24 +.sp 25 +\fB::http::quoteString\fR \fIvalue\fR 24 26 .sp 25 27 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? 26 28 .sp 27 29 \fB::http::wait \fItoken\fR 28 30 .sp 29 31 \fB::http::status \fItoken\fR 30 32 .sp ................................................................................ 40 42 .sp 41 43 \fB::http::error \fItoken\fR 42 44 .sp 43 45 \fB::http::cleanup \fItoken\fR 44 46 .sp 45 47 \fB::http::register \fIproto port command\fR 46 48 .sp 49 +\fB::http::registerError \fIport\fR ?\fImessage\fR? 50 +.sp 47 51 \fB::http::unregister \fIproto\fR 48 52 .BE 49 53 .SH DESCRIPTION 50 54 .PP 51 55 The \fBhttp\fR package provides the client side of the HTTP/1.1 52 -protocol, as defined in RFC 2616. 56 +protocol, as defined in RFC 7230 to RFC 7235, which supersede RFC 2616. 53 57 The package implements the GET, POST, and HEAD operations 54 58 of HTTP/1.1. It allows configuration of a proxy host to get through 55 59 firewalls. The package is compatible with the \fBSafesock\fR security 56 60 policy, so it can be used by untrusted applets to do URL fetching from 57 61 a restricted set of hosts. This package can be extended to support 58 62 additional HTTP transport protocols, such as HTTPS, by providing 59 63 a custom \fBsocket\fR command, via \fB::http::register\fR. ................................................................................ 90 94 \fB\-accept\fR \fImimetypes\fR 91 95 . 92 96 The Accept header of the request. The default is */*, which means that 93 97 all types of documents are accepted. Otherwise you can supply a 94 98 comma-separated list of mime type patterns that you are 95 99 willing to receive. For example, 96 100 .QW "image/gif, image/jpeg, text/*" . 101 +.TP 102 +\fB\-cookiejar\fR \fIcommand\fR 103 +.VS TIP406 104 +The cookie store for the package to use to manage HTTP cookies. 105 +\fIcommand\fR is a command prefix list; if the empty list (the 106 +default value) is used, no cookies will be sent by requests or stored 107 +from responses. The command indicated by \fIcommand\fR, if supplied, 108 +must obey the \fBCOOKIE JAR PROTOCOL\fR described below. 109 +.VE TIP406 110 +.TP 111 +\fB\-pipeline\fR \fIboolean\fR 112 +. 113 +Specifies whether HTTP/1.1 transactions on a persistent socket will be 114 +pipelined. See the \fBPERSISTENT SOCKETS\fR section for details. The default 115 +is 1. 116 +.TP 117 +\fB\-postfresh\fR \fIboolean\fR 118 +. 119 +Specifies whether requests that use the \fBPOST\fR method will always use a 120 +fresh socket, overriding the \fB-keepalive\fR option of 121 +command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. 122 +The default is 0. 97 123 .TP 98 124 \fB\-proxyhost\fR \fIhostname\fR 99 125 . 100 126 The name of the proxy host, if any. If this value is the 101 127 empty string, the URL host is contacted directly. 102 128 .TP 103 129 \fB\-proxyport\fR \fInumber\fR ................................................................................ 111 137 to determine if a proxy is required for a given host. One argument, a 112 138 host name, is added to \fIcommand\fR when it is invoked. If a proxy 113 139 is required, the callback should return a two-element list containing 114 140 the proxy server and proxy port. Otherwise the filter should return 115 141 an empty list. The default filter returns the values of the 116 142 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are 117 143 non-empty. 144 +.TP 145 +\fB\-repost\fR \fIboolean\fR 146 +. 147 +Specifies what to do if a POST request over a persistent connection fails 148 +because the server has half-closed the connection. If boolean \fBtrue\fR, the 149 +request 150 +will be automatically retried; if boolean \fBfalse\fR it will not, and the 151 +application 152 +that uses \fBhttp::geturl\fR is expected to seek user confirmation before 153 +retrying the POST. The value \fBtrue\fR should be used only under certain 154 +conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The 155 +default is 0. 118 156 .TP 119 157 \fB\-urlencoding\fR \fIencoding\fR 120 158 . 121 159 The \fIencoding\fR used for creating the x-url-encoded URLs with 122 -\fB::http::formatQuery\fR. The default is \fButf-8\fR, as specified by RFC 160 +\fB::http::formatQuery\fR and \fB::http::quoteString\fR. 161 +The default is \fButf-8\fR, as specified by RFC 123 162 2718. Prior to http 2.5 this was unspecified, and that behavior can be 124 163 returned by specifying the empty string (\fB{}\fR), although 125 164 \fIiso8859-1\fR is recommended to restore similar behavior but without the 126 -\fB::http::formatQuery\fR throwing an error processing non-latin-1 127 -characters. 165 +\fB::http::formatQuery\fR or \fB::http::quoteString\fR 166 +throwing an error processing non-latin-1 characters. 128 167 .TP 129 168 \fB\-useragent\fR \fIstring\fR 130 169 . 131 -The value of the User-Agent header in the HTTP request. The default is 132 -.QW "\fBTcl http client package 2.7\fR" . 170 +The value of the User-Agent header in the HTTP request. In an unsafe 171 +interpreter, the default value depends upon the operating system, and 172 +the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example) 173 +.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.8.12 Tcl/8.6.8\fR" . 174 +A safe interpreter cannot determine its operating system, and so the default 175 +in a safe interpreter is to use a Windows 10 value with the current version 176 +numbers of \fBhttp\fR and \fBTcl\fR. 177 +.TP 178 +\fB\-zip\fR \fIboolean\fR 179 +. 180 +If the value is boolean \fBtrue\fR, then by default requests will send a header 181 +.QW "\fBAccept-Encoding: gzip,deflate,compress\fR" . 182 +If the value is boolean \fBfalse\fR, then by default this header will not be sent. 183 +In either case the default can be overridden for an individual request by 184 +supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option 185 +of \fBhttp::geturl\fR. The default is 1. 133 186 .RE 134 187 .TP 135 188 \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? 136 189 . 137 190 The \fB::http::geturl\fR command is the main procedure in the package. 138 191 The \fB\-query\fR option causes a POST operation and 139 192 the \fB\-validate\fR option causes a HEAD operation; ................................................................................ 223 276 .CS 224 277 Pragma: no-cache 225 278 .CE 226 279 .RE 227 280 .TP 228 281 \fB\-keepalive\fR \fIboolean\fR 229 282 . 230 -If true, attempt to keep the connection open for servicing 283 +If boolean \fBtrue\fR, attempt to keep the connection open for servicing 231 284 multiple requests. Default is 0. 232 285 .TP 233 286 \fB\-method\fR \fItype\fR 234 287 . 235 288 Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will 236 289 auto-select GET, POST or HEAD based on other options, but this option 237 290 enables choices like PUT and DELETE for webdav support. ................................................................................ 329 382 \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? 330 383 . 331 384 This procedure does x-url-encoding of query data. It takes an even 332 385 number of arguments that are the keys and values of the query. It 333 386 encodes the keys and values, and generates one string that has the 334 387 proper & and = separators. The result is suitable for the 335 388 \fB\-query\fR value passed to \fB::http::geturl\fR. 389 +.TP 390 +\fB::http::quoteString\fR \fIvalue\fR 391 +. 392 +This procedure does x-url-encoding of string. It takes a single argument and 393 +encodes it. 336 394 .TP 337 395 \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? 338 396 . 339 397 This command resets the HTTP transaction identified by \fItoken\fR, if any. 340 398 This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to 341 399 \fBreset\fR, and then calls the registered \fB\-command\fR callback. 342 400 .TP ................................................................................ 410 468 package require tls 411 469 412 470 ::http::register https 443 ::tls::socket 413 471 414 472 set token [::http::geturl https://my.secure.site/] 415 473 .CE 416 474 .RE 475 +.TP 476 +\fB::http::registerError\fR \fIport\fR ?\fImessage\fR? 477 +. 478 +This procedure allows a registered protocol handler to deliver an error 479 +message for use by \fBhttp\fR. Calling this command does not raise an 480 +error. The command is useful when a registered protocol detects an problem 481 +(for example, an invalid TLS certificate) that will cause an error to 482 +propagate to \fBhttp\fR. The command allows \fBhttp\fR to provide a 483 +precise error message rather than a general one. The command returns the 484 +value provided by the last call with argument \fImessage\fR, or the empty 485 +string if no such call has been made. 417 486 .TP 418 487 \fB::http::unregister\fR \fIproto\fR 419 488 . 420 489 This procedure unregisters a protocol handler that was previously 421 490 registered via \fB::http::register\fR, returning a two-item list of 422 491 the default port and handler command that was previously installed 423 492 (via \fB::http::register\fR) if there was such a handler, and an error if ................................................................................ 500 569 Once the data associated with the URL is no longer needed, the state 501 570 array should be unset to free up storage. 502 571 The \fB::http::cleanup\fR procedure is provided for that purpose. 503 572 The following elements of 504 573 the array are supported: 505 574 .RS 506 575 .TP 576 +\fBbinary\fR 577 +. 578 +This is boolean \fBtrue\fR if (after decoding any compression specified 579 +by the 580 +.QW "Content-Encoding" 581 +response header) the HTTP response is binary. It is boolean \fBfalse\fR 582 +if the HTTP response is text. 583 +.TP 507 584 \fBbody\fR 508 585 . 509 586 The contents of the URL. This will be empty if the \fB\-channel\fR 510 587 option has been specified. This value is returned by the \fB::http::data\fR command. 511 588 .TP 512 589 \fBcharset\fR 513 590 . ................................................................................ 598 675 . 599 676 A copy of the \fBContent-Type\fR meta-data value. 600 677 .TP 601 678 \fBurl\fR 602 679 . 603 680 The requested URL. 604 681 .RE 682 +.SH "PERSISTENT CONNECTIONS" 683 +.PP 684 +.SS "BASICS" 685 +.PP 686 +See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1. 687 +.PP 688 +A persistent connection allows multiple HTTP/1.1 transactions to be 689 +carried over the same TCP connection. Pipelining allows a 690 +client to make multiple requests over a persistent connection without 691 +waiting for each response. The server sends responses in the same order 692 +that the requests were received. 693 +.PP 694 +If a POST request fails to complete, typically user confirmation is 695 +needed before sending the request again. The user may wish to verify 696 +whether the server was modified by the failed POST request, before 697 +sending the same request again. 698 +.PP 699 +A HTTP request will use a persistent socket if the call to 700 +\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use 701 +pipelining where permitted if the \fBhttp::config\fR option 702 +\fB-pipeline\fR is boolean \fBtrue\fR (its default value). 703 +.PP 704 +The http package maintains no more than one persistent connection to each 705 +server (i.e. each value of 706 +.QW "domain:port" ). 707 +If \fBhttp::geturl\fR is called to make a request over a persistent 708 +connection while the connection is busy with another request, the new 709 +request will be held in a queue until the connection is free. 710 +.PP 711 +The http package does not support HTTP/1.0 persistent connections 712 +controlled by the \fBKeep-Alive\fR header. 713 +.SS "SPECIAL CASES" 714 +.PP 715 +This subsection discusses issues related to closure of the 716 +persistent connection by the server, automatic retry of failed requests, 717 +the special treatment necessary for POST requests, and the options for 718 +dealing with these cases. 719 +.PP 720 +In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline 721 +requests that use the POST method. If a POST uses a persistent 722 +connection and is not the first request on that connection, 723 +\fBhttp::geturl\fR waits until it has received the response for the previous 724 +request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it 725 +uses a new connection for each POST. 726 +.PP 727 +If the server is processing a number of pipelined requests, and sends a 728 +response header 729 +.QW "\fBConnection: close\fR" 730 +with one of the responses (other than the last), then subsequent responses 731 +are unfulfilled. \fBhttp::geturl\fR will send the unfulfilled requests again 732 +over a new connection. 733 +.PP 734 +A difficulty arises when a HTTP client sends a request over a persistent 735 +connection that has been idle for a while. The HTTP server may 736 +half-close an apparently idle connection while the client is sending a 737 +request, but before the request arrives at the server: in this case (an 738 +.QW "asynchronous close event" ) 739 +the request will fail. The difficulty arises because the client cannot 740 +be certain whether the POST modified the state of the server. For HEAD or 741 +GET requests, \fBhttp::geturl\fR opens another connection and retransmits 742 +the failed request. However, if the request was a POST, RFC 7230 forbids 743 +automatic retry by default, suggesting either user confirmation, or 744 +confirmation by user-agent software that has semantic understanding of 745 +the application. The \fBhttp::config\fR option \fB-repost\fR allows for 746 +either possibility. 747 +.PP 748 +Asynchronous close events can occur only in a short interval of time. The 749 +\fBhttp\fR package monitors each persistent connection for closure by the 750 +server. Upon detection, the connection is also closed at the client end, 751 +and subsequent requests will use a fresh connection. 752 +.PP 753 +If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR, 754 +then it will both try to use an existing persistent connection 755 +(if one is available), and it will send the server a 756 +.QW "\fBConnection: keep-alive\fR" 757 +request header asking to keep the connection open for future requests. 758 +.PP 759 +The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and 760 +\fB-repost\fR relate to persistent connections. 761 +.PP 762 +Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests 763 +made 764 +over a persistent connection. POST requests will not be pipelined - if the 765 +POST is not the first transaction on the connection, its request will not 766 +be sent until the previous response has finished. GET and HEAD requests 767 +made after a POST will not be sent until the POST response has been 768 +delivered, and will not be sent if the POST fails. 769 +.PP 770 +Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option 771 +\fB-keepalive\fR, and always open a fresh connection for a POST request. 772 +.PP 773 +Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request 774 +that fails because it uses a persistent connection that the server has 775 +half-closed (an 776 +.QW "asynchronous close event" ). 777 +Subsequent GET and HEAD requests in a failed pipeline will also be retried. 778 +\fIThe -repost option should be used only if the application understands 779 +that the retry is appropriate\fR - specifically, the application must know 780 +that if the failed POST successfully modified the state of the server, a repeat POST 781 +would have no adverse effect. 782 +.VS TIP406 783 +.SH "COOKIE JAR PROTOCOL" 784 +.PP 785 +Cookies are short key-value pairs used to implement sessions within the 786 +otherwise-stateless HTTP protocol. (See RFC 6265 for details; Tcl does not 787 +implement the Cookie2 protocol as that is rarely seen in the wild.) 788 +.PP 789 +Cookie storage managment commands \(em 790 +.QW "cookie jars" 791 +\(em must support these subcommands which form the HTTP cookie storage 792 +management protocol. Note that \fIcookieJar\fR below does not have to be a 793 +command name; it is properly a command prefix (a Tcl list of words that will 794 +be expanded in place) and admits many possible implementations. 795 +.PP 796 +Though not formally part of the protocol, it is expected that particular 797 +values of \fIcookieJar\fR will correspond to sessions; it is up to the caller 798 +of \fB::http::config\fR to decide what session applies and to manage the 799 +deletion of said sessions when they are no longer desired (which should be 800 +when they not configured as the current cookie jar). 801 +.TP 802 +\fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR 803 +. 804 +This command asks the cookie jar what cookies should be supplied for a 805 +particular request. It should take the \fIprotocol\fR (typically \fBhttp\fR or 806 +\fBhttps\fR), \fIhost\fR name and \fIrequestPath\fR (parsed from the \fIurl\fR 807 +argument to \fB::http::geturl\fR) and return a list of cookie keys and values 808 +that describe the cookies to supply to the remote host. The list must have an 809 +even number of elements. 810 +.RS 811 +.PP 812 +There should only ever be at most one cookie with a particular key for any 813 +request (typically the one with the most specific \fIhost\fR/domain match and 814 +most specific \fIrequestPath\fR/path match), but there may be many cookies 815 +with different names in any request. 816 +.RE 817 +.TP 818 +\fIcookieJar \fBstoreCookie \fIcookieDictionary\fR 819 +. 820 +This command asks the cookie jar to store a particular cookie that was 821 +returned by a request; the result of this command is ignored. The cookie 822 +(which will have been parsed by the http package) is described by a 823 +dictionary, \fIcookieDictionary\fR, that may have the following keys: 824 +.RS 825 +.TP 826 +\fBdomain\fR 827 +. 828 +This is always present. Its value describes the domain hostname \fIor 829 +prefix\fR that the cookie should be returned for. The checking of the domain 830 +against the origin (below) should be careful since sites that issue cookies 831 +should only do so for domains related to themselves. Cookies that do not obey 832 +a relevant origin matching rule should be ignored. 833 +.TP 834 +\fBexpires\fR 835 +. 836 +This is optional. If present, the cookie is intended to be a persistent cookie 837 +and the value of the option is the Tcl timestamp (in seconds from the same 838 +base as \fBclock seconds\fR) of when the cookie expires (which may be in the 839 +past, which should result in the cookie being deleted immediately). If absent, 840 +the cookie is intended to be a session cookie that should be not persisted 841 +beyond the lifetime of the cookie jar. 842 +.TP 843 +\fBhostonly\fR 844 +. 845 +This is always present. Its value is a boolean that describes whether the 846 +cookie is a single host cookie (true) or a domain-level cookie (false). 847 +.TP 848 +\fBhttponly\fR 849 +. 850 +This is always present. Its value is a boolean that is true when the site 851 +wishes the cookie to only ever be used with HTTP (or HTTPS) traffic. 852 +.TP 853 +\fBkey\fR 854 +. 855 +This is always present. Its value is the \fIkey\fR of the cookie, which is 856 +part of the information that must be return when sending this cookie back in a 857 +future request. 858 +.TP 859 +\fBorigin\fR 860 +. 861 +This is always present. Its value describes where the http package believes it 862 +received the cookie from, which may be useful for checking whether the 863 +cookie's domain is valid. 864 +.TP 865 +\fBpath\fR 866 +. 867 +This is always present. Its value describes the path prefix of requests to the 868 +cookie domain where the cookie should be returned. 869 +.TP 870 +\fBsecure\fR 871 +. 872 +This is always present. Its value is a boolean that is true when the cookie 873 +should only used on requests sent over secure channels (typically HTTPS). 874 +.TP 875 +\fBvalue\fR 876 +. 877 +This is always present. Its value is the value of the cookie, which is part of 878 +the information that must be return when sending this cookie back in a future 879 +request. 880 +.PP 881 +Other keys may always be ignored; they have no meaning in this protocol. 882 +.RE 883 +.VE TIP406 605 884 .SH EXAMPLE 606 885 .PP 607 886 This example creates a procedure to copy a URL to a file while printing a 608 887 progress meter, and prints the meta-data associated with the URL. 609 888 .PP 610 889 .CS 611 890 proc httpcopy { url file {chunk 4096} } {
Added doc/idna.n.
1 +'\" 2 +'\" Copyright (c) 2014-2018 Donal K. Fellows. 3 +'\" 4 +'\" See the file "license.terms" for information on usage and redistribution 5 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 6 +'\" 7 +.TH "idna" n 0.1 http "Tcl Bundled Packages" 8 +.so man.macros 9 +.BS 10 +'\" Note: do not modify the .SH NAME line immediately below! 11 +.SH NAME 12 +tcl::idna \- Support for normalization of Internationalized Domain Names 13 +.SH SYNOPSIS 14 +.nf 15 +package require tcl::idna 1.0 16 + 17 +\fBtcl::idna decode\fR \fIhostname\fR 18 +\fBtcl::idna encode\fR \fIhostname\fR 19 +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? 20 +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? 21 +\fBtcl::idna version\fR 22 +.fi 23 +.SH DESCRIPTION 24 +This package provides an implementation of the punycode scheme used in 25 +Internationalised Domain Names, and some access commands. (See RFC 3492 for a 26 +description of punycode.) 27 +.TP 28 +\fBtcl::idna decode\fR \fIhostname\fR 29 +. 30 +This command takes the name of a host that potentially contains 31 +punycode-encoded character sequences, \fIhostname\fR, and returns the hostname 32 +as might be displayed to the user. Note that there are often UNICODE 33 +characters that have extremely similar glyphs, so care should be taken with 34 +displaying hostnames to users. 35 +.TP 36 +\fBtcl::idna encode\fR \fIhostname\fR 37 +. 38 +This command takes the name of a host as might be displayed to the user, 39 +\fIhostname\fR, and returns the version of the hostname with characters not 40 +permitted in basic hostnames encoded with punycode. 41 +.TP 42 +\fBtcl::idna puny\fR \fIsubcommand ...\fR 43 +. 44 +This command provides direct access to the basic punycode encoder and 45 +decoder. It supports two \fIsubcommand\fRs: 46 +.RS 47 +.TP 48 +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? 49 +. 50 +This command decodes the punycode-encoded string, \fIstring\fR, and returns 51 +the result. If \fIcase\fR is provided, it is a boolean to make the case be 52 +folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is 53 +false) during the decoding process; if omitted, no case transformation is 54 +applied. 55 +.TP 56 +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? 57 +. 58 +This command encodes the string, \fIstring\fR, and returns the 59 +punycode-encoded version of the string. If \fIcase\fR is provided, it is a 60 +boolean to make the case be folded to upper case (if \fIcase\fR is true) or 61 +lower case (if \fIcase\fR is false) during the encoding process; if omitted, 62 +no case transformation is applied. 63 +.RE 64 +.TP 65 +\fBtcl::idna version\fR 66 +. 67 +This returns the version of the \fBtcl::idna\fR package. 68 +.SH "EXAMPLE" 69 +.PP 70 +This is an example of how punycoding of a string works: 71 +.PP 72 +.CS 73 +package require tcl::idna 74 + 75 +puts [\fBtcl::idna puny encode\fR "abc\(->def"] 76 +# prints: \fIabcdef-kn2c\fR 77 +puts [\fBtcl::idna puny decode\fR "abcdef-kn2c"] 78 +# prints: \fIabc\(->def\fR 79 +.CE 80 +'\" TODO: show how it handles a real domain name 81 +.SH "SEE ALSO" 82 +http(n), cookiejar(n) 83 +.SH KEYWORDS 84 +internet, www 85 +'\" Local Variables: 86 +'\" mode: nroff 87 +'\" fill-column: 78 88 +'\" End:
Changes to doc/incr.n.
23 23 1 is added to \fIvarName\fR. 24 24 The new value is stored as a decimal string in variable \fIvarName\fR 25 25 and also returned as result. 26 26 .PP 27 27 Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed 28 28 to \fBincr\fR may be unset, and in that case, it will be set to 29 29 the value \fIincrement\fR or to the default increment value of \fB1\fR. 30 +.VS TIP508 31 +If \fIvarName\fR indicate an element that does not exist of an array that has 32 +a default value set, the sum of the default value and the \fIincrement\fR (or 33 +1) will be stored in the array element. 34 +.VE TIP508 30 35 .SH EXAMPLES 31 36 .PP 32 37 Add one to the contents of the variable \fIx\fR: 33 38 .PP 34 39 .CS 35 40 \fBincr\fR x 36 41 .CE ................................................................................ 55 60 .CS 56 61 \fBincr\fR x 0 57 62 .CE 58 63 .SH "SEE ALSO" 59 64 expr(n), set(n) 60 65 .SH KEYWORDS 61 66 add, increment, variable, value 67 +.\" Local variables: 68 +.\" mode: nroff 69 +.\" fill-column: 78 70 +.\" End:
Changes to doc/info.n.
9 9 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 10 10 '\" 11 11 .TH info n 8.4 Tcl "Tcl Built-In Commands" 12 12 .so man.macros 13 13 .BS 14 14 '\" Note: do not modify the .SH NAME line immediately below! 15 15 .SH NAME 16 -info \- Return information about the state of the Tcl interpreter 16 +info \- Information about the state of the Tcl interpreter 17 17 .SH SYNOPSIS 18 18 \fBinfo \fIoption \fR?\fIarg arg ...\fR? 19 19 .BE 20 20 .SH DESCRIPTION 21 21 .PP 22 -This command provides information about various internals of the Tcl 23 -interpreter. 24 -The legal \fIoption\fRs (which may be abbreviated) are: 22 +Available commands: 25 23 .TP 26 24 \fBinfo args \fIprocname\fR 27 25 . 28 -Returns a list containing the names of the arguments to procedure 29 -\fIprocname\fR, in order. \fIProcname\fR must be the name of a 30 -Tcl command procedure. 26 +Returns the names of the parameters to the procedure named \fIprocname\fR. 31 27 .TP 32 28 \fBinfo body \fIprocname\fR 33 29 . 34 -Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be 35 -the name of a Tcl command procedure. 30 +Returns the body of the procedure named \fIprocname\fR. 36 31 .TP 37 32 \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR 38 -.VS 8.6 39 -Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are 40 -described in \fBCLASS INTROSPECTION\fR below. 41 -.VE 8.6 33 +. 34 +Returns information about the class named \fIclass\fR. 35 +See \fBCLASS INTROSPECTION\fR below. 42 36 .TP 43 37 \fBinfo cmdcount\fR 44 38 . 45 -Returns a count of the total number of commands that have been invoked 46 -in this interpreter. 39 +Returns the total number of commands evaluated in this interpreter. 40 +.TP 41 +\fBinfo cmdtype \fIcommandName\fR 42 +.VS TIP426 43 +Returns a the type of the command named \fIcommandName\fR. 44 +Built-in types are: 45 +.RS 46 +.IP \fBalias\fR 47 +\fIcommandName\fR was created by \fBinterp alias\fR. 48 +In a safe interpreter an alias is only visible if both the alias and the 49 +target are visible. 50 +.IP \fBcoroutine\fR 51 +\fIcommandName\fR was created by \fBcoroutine\fR. 52 +.IP \fBensemble\fR 53 +\fIcommandName\fR was created by \fBnamespace ensemble\fR. 54 +.IP \fBimport\fR 55 +\fIcommandName\fR was created by \fBnamespace import\fR. 56 +.IP \fBnative\fR 57 +\fIcommandName\fR was created by the \fBTcl_CreateObjProc\fR 58 +interface directly without further registration of the type of command. 59 +.IP \fBobject\fR 60 +\fIcommandName\fR is the public command that represents an 61 +instance of \fBoo::object\fR or one of its subclasses. 62 +.IP \fBprivateObject\fR 63 +\fIcommandName\fR is the private command, \fBmy\fR by default, 64 +that represents an instance of \fBoo::object\fR or one of its subclasses. 65 +.IP \fBproc\fR 66 +\fIcommandName\fR was created by \fBproc\fR. 67 +.IP \fBslave\fR 68 +\fIcommandName\fR was created by \fBinterp create\fR. 69 +.IP \fBzlibStream\fR 70 +\fIcommandName\fR was created by \fBzlib stream\fR. 71 +.PP 72 +Other types may be also registered as well. See \fBTcl_RegisterCommandTypeName\fR. 73 +.RE 74 +.VE TIP426 47 75 .TP 48 76 \fBinfo commands \fR?\fIpattern\fR? 49 77 . 50 -If \fIpattern\fR is not specified, 51 -returns a list of names of all the Tcl commands visible 52 -(i.e. executable without using a qualified name) to the current namespace, 53 -including both the built-in commands written in C and 54 -the command procedures defined using the \fBproc\fR command. 55 -If \fIpattern\fR is specified, 56 -only those names matching \fIpattern\fR are returned. 57 -Matching is determined using the same rules as for \fBstring match\fR. 58 -\fIpattern\fR can be a qualified name like \fBFoo::print*\fR. 59 -That is, it may specify a particular namespace 60 -using a sequence of namespace names separated by double colons (\fB::\fR), 61 -and may have pattern matching special characters 62 -at the end to specify a set of commands in that namespace. 63 -If \fIpattern\fR is a qualified name, 64 -the resulting list of command names has each one qualified with the name 65 -of the specified namespace, and only the commands defined in the named 66 -namespace are returned. 67 -.\" Technically, most of this hasn't changed; that's mostly just the 68 -.\" way it always worked. Hardly anyone knew that though. 78 +Returns the names of all commands visible in the current namespace. If 79 +\fIpattern\fR is given, returns only those names that match according to 80 +\fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. 81 +Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the 82 +\fBnamespace\fR(n) documentation. 69 83 .TP 70 84 \fBinfo complete \fIcommand\fR 71 85 . 72 -Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of 73 -having no unclosed quotes, braces, brackets or array element names. 74 -If the command does not appear to be complete then 0 is returned. 75 -This command is typically used in line-oriented input environments 76 -to allow users to type in commands that span multiple lines; if the 77 -command is not complete, the script can delay evaluating it until additional 78 -lines have been typed to complete the command. 86 +Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise. 87 +Typically used in line-oriented input environments 88 +to allow users to type in commands that span multiple lines. 79 89 .TP 80 90 \fBinfo coroutine\fR 81 -.VS 8.6 82 -Returns the name of the currently executing \fBcoroutine\fR, or the empty 83 -string if either no coroutine is currently executing, or the current coroutine 84 -has been deleted (but has not yet returned or yielded since deletion). 85 -.VE 8.6 91 +. 92 +Returns the name of the current \fBcoroutine\fR, or the empty 93 +string if there is no current coroutine or the current coroutine 94 +has been deleted. 86 95 .TP 87 -\fBinfo default \fIprocname arg varname\fR 96 +\fBinfo default \fIprocname parameter varname\fR 88 97 . 89 -\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR 90 -must be the name of an argument to that procedure. If \fIarg\fR 91 -does not have a default value then the command returns \fB0\fR. 92 -Otherwise it returns \fB1\fR and places the default value of \fIarg\fR 93 -into variable \fIvarname\fR. 98 +If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a 99 +default value, stores that value in \fIvarname\fR and returns \fB1\fR. 100 +Otherwise, returns \fB0\fR. 94 101 .TP 95 102 \fBinfo errorstack \fR?\fIinterp\fR? 96 -.VS 8.6 97 -Returns, in a form that is programmatically easy to parse, the function names 98 -and arguments at each level from the call stack of the last error in the given 99 -\fIinterp\fR, or in the current one if not specified. 103 +. 104 +Returns a description of the active command at each level for the 105 +last error in the current interpreter, or in the interpreter named 106 +\fIinterp\fR if given. 100 107 .RS 101 108 .PP 102 -This form is an even-sized list alternating tokens and parameters. Tokens are 109 +The description is a dictionary of tokens and parameters. Tokens are 103 110 currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be 104 -introduced in the future. \fBCALL\fR indicates a procedure call, and its 111 +introduced in the future. \fBCALL\fR indicates a command call, and its 105 112 parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a 106 113 shift in variable frames generated by \fBuplevel\fR or similar, and applies to 107 114 the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR 108 115 identifies the 109 116 .QW "inner context" , 110 117 which is the innermost atomic command or bytecode instruction that raised the 111 118 error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR 112 -allow to follow complex call paths, \fBINNER\fR homes in on the offending 113 -operation in the innermost procedure call, even going to sub-expression 119 +provide a trail of the call path, \fBINNER\fR provides details of the offending 120 +operation in the innermost procedure call, even to sub-expression 114 121 granularity. 115 122 .PP 116 123 This information is also present in the \fB\-errorstack\fR entry of the 117 124 options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR 118 125 is a convenient way of retrieving it for uncaught errors at top-level in an 119 -interactive \fBtclsh\fR. 126 +interactive \fBinterpreter\fR. 120 127 .RE 121 -.VE 8.6 122 128 .TP 123 129 \fBinfo exists \fIvarName\fR 124 130 . 125 -Returns \fB1\fR if the variable named \fIvarName\fR exists in the 126 -current context (either as a global or local variable) and has been 127 -defined by being given a value, returns \fB0\fR otherwise. 131 +Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been 132 +defined, and \fB0\fR otherwise. 128 133 .TP 129 -\fBinfo frame\fR ?\fInumber\fR? 134 +\fBinfo frame\fR ?\fIdepth\fR? 130 135 . 131 -This command provides access to all frames on the stack, even those 132 -hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this 133 -command returns a number giving the frame level of the command. This 134 -is 1 if the command is invoked at top-level. If \fInumber\fR is 135 -specified, then the result is a dictionary containing the location 136 -information for the command at the \fInumber\fRed level on the stack. 136 +Returns the depth of the call to \fBinfo frame\fR itself. Otherwise, returns a 137 +dictionary describing the active command at the \fIdepth\fR, which counts all 138 +commands visible to \fBinfo level\fR, plus commands that don't create a new 139 +level, such as \fBeval\fR, \fBsource\fR, or \fIuplevel\fR. The frame depth is 140 +always greater than the current level. 137 141 .RS 138 142 .PP 139 -If \fInumber\fR is positive (> 0) then it selects a particular stack 140 -level (1 refers to the outer-most active command, 2 to the command it 141 -called, and so on, up to the current frame level which refers to 142 -\fBinfo frame\fR itself); otherwise it gives a level relative to the 143 -current command (0 refers to the current command, i.e., \fBinfo 144 -frame\fR itself, -1 to its caller, and so on). 143 +If \fIdepth\fR is greater than \fB0\fR it is the frame at that depth. Otherwise 144 +it is the number of frames up from the current frame. 145 145 .PP 146 -This is similar to how \fBinfo level\fR works, except that this 147 -subcommand reports all frames, like \fBsource\fRd scripts, 148 -\fBeval\fRs, \fBuplevel\fRs, etc. 149 -.PP 150 -Note that for nested commands, like 146 +As with \fBinfo level\fR and error traces, for nested commands like 151 147 .QW "foo [bar [x]]" , 152 148 only 153 149 .QW x 154 -will be seen by an \fBinfo frame\fR invoked within 150 +is seen by \fBinfo frame\fR invoked within 155 151 .QW x . 156 -This is the same as for \fBinfo level\fR and error stack traces. 157 152 .PP 158 -The result dictionary may contain the keys listed below, with the 159 -specified meanings for their values: 153 +The dictionary may contain the following keys: 160 154 .TP 161 155 \fBtype\fR 162 156 . 163 -This entry is always present and describes the nature of the location 164 -for the command. The recognized values are \fBsource\fR, \fBproc\fR, 157 +Always present. Possible values are \fBsource\fR, \fBproc\fR, 165 158 \fBeval\fR, and \fBprecompiled\fR. 166 159 .RS 167 160 .TP 168 161 \fBsource\fR\0\0\0\0\0\0\0\0 169 162 . 170 -means that the command is found in a script loaded by the \fBsource\fR 163 +A script loaded via the \fBsource\fR 171 164 command. 172 165 .TP 173 166 \fBproc\fR\0\0\0\0\0\0\0\0 174 167 . 175 -means that the command is found in dynamically created procedure body. 168 +The body of a procedure that could not be traced back to a 169 +line in a particular script. 176 170 .TP 177 171 \fBeval\fR\0\0\0\0\0\0\0\0 178 172 . 179 -means that the command is executed by \fBeval\fR or \fBuplevel\fR. 173 +The body of a script provided to \fBeval\fR or \fBuplevel\fR. 180 174 .TP 181 175 \fBprecompiled\fR\0\0\0\0\0\0\0\0 182 176 . 183 -means that the command is found in a pre-compiled script (loadable by 184 -the package \fBtbcload\fR), and no further information will be 185 -available. 177 +A pre-compiled script (loadable by the package 178 +\fBtbcload\fR), and no further information is available. 186 179 .RE 187 180 .TP 188 181 \fBline\fR 189 182 . 190 -This entry provides the number of the line the command is at inside of 191 -the script it is a part of. This information is not present for type 192 -\fBprecompiled\fR. For type \fBsource\fR this information is counted 193 -relative to the beginning of the file, whereas for the last two types 194 -the line is counted relative to the start of the script. 183 +The line number of of the command inside its script. Not available for 184 +\fBprecompiled\fR commands. When the type is \fBsource\fR, the line number is 185 +relative to the beginning of the file, whereas for the last two types it is 186 +relative to the start of the script. 195 187 .TP 196 188 \fBfile\fR 197 189 . 198 -This entry is present only for type \fBsource\fR. It provides the 199 -normalized path of the file the command is in. 190 +For type \fBsource\fR, provides the normalized path of the file that contains 191 +the command. 200 192 .TP 201 193 \fBcmd\fR 202 194 . 203 -This entry provides the string representation of the command. This is 204 -usually the unsubstituted form, however for commands which are a 205 -canonically-constructed list (e.g., as produced by the \fBlist\fR command) 206 -executed by \fBeval\fR it is the substituted form as they have no other 207 -string representation. Care is taken that the canonicality property of 208 -the latter is not spoiled. 195 +The command before substitutions were performed. 209 196 .TP 210 197 \fBproc\fR 211 198 . 212 -This entry is present only if the command is found in the body of a 213 -regular Tcl procedure. It then provides the name of that procedure. 199 +For type \fBprod\fR, the name of the procedure containing the command. 214 200 .TP 215 201 \fBlambda\fR 216 202 . 217 -This entry is present only if the command is found in the body of an 218 -anonymous Tcl procedure, i.e. a lambda. It then provides the entire 219 -definition of the lambda in question. 203 +For a command in a script evaluated as the body of an unnamed routine via the 204 +\fBapply\fR command, the definition of that routine. 220 205 .TP 221 206 \fBlevel\fR 222 207 . 223 -This entry is present only if the queried frame has a corresponding 224 -frame returned by \fBinfo level\fR. It provides the index of this 225 -frame, relative to the current level (0 and negative numbers). 208 +For a frame that corresponds to a level, (to be determined). 226 209 .PP 227 -A thing of note is that for procedures statically defined in files the 228 -locations of commands in their bodies will be reported with type 229 -\fBsource\fR and absolute line numbers, and not as type 230 -\fBproc\fR. The same is true for procedures nested in statically 231 -defined procedures, and literal eval scripts in files or statically 232 -defined procedures. 210 +When a command can be traced to its literal definition in some script, e.g. 211 +procedures nested in statically defined procedures, and literal eval scripts in 212 +files or statically defined procedures, its type is \fBsource\fR and its 213 +location is the absolute line number in the script. Otherwise, its type is 214 +\fBproc\fR and its location is its line number within the body of the 215 +procedure. 233 216 .PP 234 217 In contrast, procedure definitions and \fBeval\fR within a dynamically 235 218 \fBeval\fRuated environment count line numbers relative to the start of 236 219 their script, even if they would be able to count relative to the 237 220 start of the outer dynamic script. That type of number usually makes 238 221 more sense. 239 222 .PP 240 -A different way of describing this behaviour is that file based 223 +A different way of describing this behaviour is that file-based 241 224 locations are tracked as deeply as possible, and where this is not 242 225 possible the lines are counted based on the smallest possible 243 226 \fBeval\fR or procedure body, as that scope is usually easier to find 244 227 than any dynamic outer scope. 245 228 .PP 246 229 The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it 247 230 is given a literal list argument the system tracks the line number 248 231 within the list words as well, and otherwise all line numbers are 249 232 counted relative to the start of each word (smallest scope) 250 233 .RE 251 234 .TP 252 235 \fBinfo functions \fR?\fIpattern\fR? 253 236 . 254 -If \fIpattern\fR is not specified, returns a list of all the math 237 +If \fIpattern\fR is not given, returns a list of all the math 255 238 functions currently defined. 256 -If \fIpattern\fR is specified, only those functions whose name matches 257 -\fIpattern\fR are returned. Matching is determined using the same 258 -rules as for \fBstring match\fR. 239 +If \fIpattern\fR is given, returns only those names that match 240 +\fIpattern\fR according to \fBstring match\fR. 259 241 .TP 260 242 \fBinfo globals \fR?\fIpattern\fR? 261 243 . 262 -If \fIpattern\fR is not specified, returns a list of all the names 244 +If \fIpattern\fR is not given, returns a list of all the names 263 245 of currently-defined global variables. 264 246 Global variables are variables in the global namespace. 265 -If \fIpattern\fR is specified, only those names matching \fIpattern\fR 247 +If \fIpattern\fR is given, only those names matching \fIpattern\fR 266 248 are returned. Matching is determined using the same rules as for 267 249 \fBstring match\fR. 268 250 .TP 269 251 \fBinfo hostname\fR 270 252 . 271 -Returns the name of the computer on which this invocation is being 272 -executed. 273 -Note that this name is not guaranteed to be the fully qualified domain 274 -name of the host. Where machines have several different names (as is 253 +Returns the name of the current host. 254 + 255 +This name is not guaranteed to be the fully-qualified domain 256 +name of the host. Where machines have several different names, as is 275 257 common on systems with both TCP/IP (DNS) and NetBIOS-based networking 276 -installed,) it is the name that is suitable for TCP/IP networking that 258 +installed, it is the name that is suitable for TCP/IP networking that 277 259 is returned. 278 260 .TP 279 -\fBinfo level\fR ?\fInumber\fR? 261 +\fBinfo level\fR ?\fIlevel\fR? 280 262 . 281 -If \fInumber\fR is not specified, this command returns a number 282 -giving the stack level of the invoking procedure, or 0 if the 283 -command is invoked at top-level. If \fInumber\fR is specified, 284 -then the result is a list consisting of the name and arguments for the 285 -procedure call at level \fInumber\fR on the stack. If \fInumber\fR 286 -is positive then it selects a particular stack level (1 refers 287 -to the top-most active procedure, 2 to the procedure it called, and 288 -so on); otherwise it gives a level relative to the current level 289 -(0 refers to the current procedure, -1 to its caller, and so on). 290 -See the \fBuplevel\fR command for more information on what stack 291 -levels mean. 263 +If \fInumber\fR is not given, the level this routine was called from. 264 +Otherwise returns the complete command active at the given level. If 265 +\fInumber\fR is greater than \fB0\fR, it is the desired level. Otherwise, it 266 +is \fInumber\fR levels up from the current level. A complete command is the 267 +words in the command, with all subsitutions performed, meaning that it is a 268 +list. See \fBuplevel\fR for more information on levels. 292 269 .TP 293 270 \fBinfo library\fR 294 271 . 295 -Returns the name of the library directory in which standard Tcl 296 -scripts are stored. 297 -This is actually the value of the \fBtcl_library\fR 298 -variable and may be changed by setting \fBtcl_library\fR. 272 +Returns the value of \fBtcl_library\fR, which is the name of the library 273 +directory in which the scripts distributed with Tcl scripts are stored. 299 274 .TP 300 275 \fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR? 301 276 . 302 -Returns the filename loaded as part of \fIpackage\fR. If \fIpackage\fR 303 -is not specified, returns a list describing all of the packages 304 -that have been loaded into \fIinterp\fR with the \fBload\fR command. 305 -Each list element is a sub-list with two elements consisting of the 306 -name of the file from which the package was loaded and the name of 307 -the package. 308 -For statically-loaded packages the file name will be an empty string. 309 -If \fIinterp\fR is omitted then information is returned for all packages 310 -loaded in any interpreter in the process. 311 -To get a list of just the packages in the current interpreter, specify 312 -an empty string for the \fIinterp\fR argument. 277 +Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of 278 +\fIpackage\fR . If \fIpackage\fR is not given, returns a list where each item 279 +is the name of the loaded file and the name of the package for which the file 280 +was loaded. For a statically-loaded package the name of the file is the empty 281 +string. For \fInterp\fR, the empty string is the current interpreter. 313 282 .TP 314 283 \fBinfo locals \fR?\fIpattern\fR? 315 284 . 316 -If \fIpattern\fR is not specified, returns a list of all the names 317 -of currently-defined local variables, including arguments to the 318 -current procedure, if any. 319 -Variables defined with the \fBglobal\fR, \fBupvar\fR and 320 -\fBvariable\fR commands will not be returned. 321 -If \fIpattern\fR is specified, only those names matching \fIpattern\fR 322 -are returned. Matching is determined using the same rules as for 323 -\fBstring match\fR. 285 +If \fIpattern\fR is given, returns the name of each local variable matching 286 +\fIpattern\fR according to \fBstring match\fR. Otherwise, returns the name of 287 +each local variable. A variables defined with the \fBglobal\fR, \fBupvar\fR or 288 +\fBvariable\fR is not local. 289 + 324 290 .TP 325 291 \fBinfo nameofexecutable\fR 326 292 . 327 -Returns the full path name of the binary file from which the application 328 -was invoked. If Tcl was unable to identify the file, then an empty 329 -string is returned. 293 +Returns the absolute pathname of the program for the current interpreter. If 294 +such a file can not be identified an empty string is returned. 330 295 .TP 331 296 \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR 332 -.VS 8.6 333 -Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are 334 -described in \fBOBJECT INTROSPECTION\fR below. 335 -.VE 8.6 297 +. 298 +Returns information about the object named \fIobject\fR. \fIsubcommand\fR is 299 +described \fBOBJECT INTROSPECTION\fR below. 336 300 .TP 337 301 \fBinfo patchlevel\fR 338 302 . 339 -Returns the value of the global variable \fBtcl_patchLevel\fR, which holds 340 -the exact version of the Tcl library by default. 303 +Returns the value of the global variable \fBtcl_patchLevel\fR, in which the 304 +exact version of the Tcl library initially stored. 341 305 .TP 342 306 \fBinfo procs \fR?\fIpattern\fR? 343 307 . 344 -If \fIpattern\fR is not specified, returns a list of all the 345 -names of Tcl command procedures in the current namespace. 346 -If \fIpattern\fR is specified, 347 -only those procedure names in the current namespace 348 -matching \fIpattern\fR are returned. 349 -Matching is determined using the same rules as for 350 -\fBstring match\fR. 351 -If \fIpattern\fR contains any namespace separators, they are used to 352 -select a namespace relative to the current namespace (or relative to 353 -the global namespace if \fIpattern\fR starts with \fB::\fR) to match 354 -within; the matching pattern is taken to be the part after the last 355 -namespace separator. 308 +Returns the names of all visible procedures. If \fIpattern\fR is given, returns 309 +only those names that match according to \fBstring match\fR. Only the final 310 +component in \fIpattern\fR is actually considered a pattern. Any qualifying 311 +components simply select a namespace. See \fBNAMESPACE RESOLUTION\fR in the 312 +\fBnamespace\fR(n) documentation. 356 313 .TP 357 314 \fBinfo script\fR ?\fIfilename\fR? 358 315 . 359 -If a Tcl script file is currently being evaluated (i.e. there is a 360 -call to \fBTcl_EvalFile\fR active or there is an active invocation 361 -of the \fBsource\fR command), then this command returns the name 362 -of the innermost file being processed. If \fIfilename\fR is specified, 363 -then the return value of this command will be modified for the 364 -duration of the active invocation to return that name. This is 365 -useful in virtual file system applications. 366 -Otherwise the command returns an empty string. 316 +Returns the pathname of the innermost script currently being evaluated, or the 317 +empty string if no pathname can be determined. If \fIfilename\fR is given, 318 +sets the return value of any future calls to \fBinfo script\fR for the duration 319 +of the innermost active script. This is useful in virtual file system 320 +applications. 367 321 .TP 368 322 \fBinfo sharedlibextension\fR 369 323 . 370 -Returns the extension used on this platform for the names of files 371 -containing shared libraries (for example, \fB.so\fR under Solaris). 372 -If shared libraries are not supported on this platform then an empty 373 -string is returned. 324 +Returns the extension used on this platform for names of shared libraries, e.g. 325 +\fB.so\fR under Solaris. Returns the empty string if shared libraries are not 326 +supported on this platform. 374 327 .TP 375 328 \fBinfo tclversion\fR 376 329 . 377 -Returns the value of the global variable \fBtcl_version\fR, which holds the 378 -major and minor version of the Tcl library by default. 330 +Returns the value of the global variable \fBtcl_version\fR, in which the 331 +major and minor version of the Tcl library are stored. 379 332 .TP 380 333 \fBinfo vars\fR ?\fIpattern\fR? 381 334 . 382 -If \fIpattern\fR is not specified, 383 -returns a list of all the names of currently-visible variables. 384 -This includes locals and currently-visible globals. 385 -If \fIpattern\fR is specified, only those names matching \fIpattern\fR 386 -are returned. Matching is determined using the same rules as for 387 -\fBstring match\fR. 388 -\fIpattern\fR can be a qualified name like \fBFoo::option*\fR. 389 -That is, it may specify a particular namespace 390 -using a sequence of namespace names separated by double colons (\fB::\fR), 391 -and may have pattern matching special characters 392 -at the end to specify a set of variables in that namespace. 393 -If \fIpattern\fR is a qualified name, 394 -the resulting list of variable names 395 -has each matching namespace variable qualified with the name 396 -of its namespace. 397 -Note that a currently-visible variable may not yet 398 -.QW exist 399 -if it has not 400 -been set (e.g. a variable declared but not set by \fBvariable\fR). 335 +If \fIpattern\fR is not given, returns the names of all visible variables. If 336 +\fIpattern\fR is given, returns only those names that match according to 337 +\fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. 338 +Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the 339 +\fBnamespace\fR(n) documentation. When \fIpattern\fR is a qualified name, 340 +results are fully qualified. 341 + 342 +A variable that has declared but not yet defined is included in the results. 401 343 .SS "CLASS INTROSPECTION" 402 -.VS 8.6 403 344 .PP 404 345 The following \fIsubcommand\fR values are supported by \fBinfo class\fR: 405 -.VE 8.6 406 346 .TP 407 347 \fBinfo class call\fI class method\fR 408 -.VS 348 +. 409 349 Returns a description of the method implementations that are used to provide a 410 350 stereotypical instance of \fIclass\fR's implementation of \fImethod\fR 411 351 (stereotypical instances being objects instantiated by a class without having 412 352 any object-specific definitions added). This consists of a list of lists of 413 353 four elements, where each sublist consists of a word that describes the 414 354 general type of method implementation (being one of \fBmethod\fR for an 415 -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a 355 +ordinary method, \fBfilter\fR for an applied filter, 356 +.VS TIP500 357 +\fBprivate\fR for a private method, 358 +.VE TIP500 359 +and \fBunknown\fR for a 416 360 method that is invoked as part of unknown method handling), a word giving the 417 361 name of the particular method invoked (which is always the same as 418 362 \fImethod\fR for the \fBmethod\fR type, and 419 363 .QW \fBunknown\fR 420 364 for the \fBunknown\fR type), a word giving the fully qualified name of the 421 365 class that defined the method, and a word describing the type of method 422 366 implementation (see \fBinfo class methodtype\fR). 423 367 .RS 424 368 .PP 425 369 Note that there is no inspection of whether the method implementations 426 -actually use \fBnext\fR to transfer control along the call chain. 370 +actually use \fBnext\fR to transfer control along the call chain, 371 +.VS TIP500 372 +and the call chains that this command files do not actually contain private 373 +methods. 374 +.VE TIP500 427 375 .RE 428 -.VE 8.6 429 376 .TP 430 377 \fBinfo class constructor\fI class\fR 431 -.VS 8.6 378 +. 432 379 This subcommand returns a description of the definition of the constructor of 433 380 class \fIclass\fR. The definition is described as a two element list; the first 434 381 element is the list of arguments to the constructor in a form suitable for 435 382 passing to another call to \fBproc\fR or a method definition, and the second 436 383 element is the body of the constructor. If no constructor is present, this 437 384 returns the empty list. 438 -.VE 8.6 439 385 .TP 440 386 \fBinfo class definition\fI class method\fR 441 -.VS 8.6 387 +. 442 388 This subcommand returns a description of the definition of the method named 443 389 \fImethod\fR of class \fIclass\fR. The definition is described as a two element 444 390 list; the first element is the list of arguments to the method in a form 445 391 suitable for passing to another call to \fBproc\fR or a method definition, and 446 392 the second element is the body of the method. 447 -.VE 8.6 393 +.TP 394 +\fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR? 395 +.VS TIP524 396 +This subcommand returns the definition namespace for \fIkind\fR definitions of 397 +the class \fIclass\fR; the definition namespace only affects the instances of 398 +\fIclass\fR, not \fIclass\fR itself. The \fIkind\fR can be either 399 +\fB\-class\fR to return the definition namespace used for \fBoo::define\fR, or 400 +\fB\-instance\fR to return the definition namespace used for 401 +\fBoo::objdefine\fR; the \fB\-class\fR kind is default (though this is only 402 +actually useful on classes that are subclasses of \fBoo::class\fR). 403 +.RS 404 +.PP 405 +If \fIclass\fR does not provide a definition namespace of the given kind, 406 +this command returns the empty string. In those circumstances, the 407 +\fBoo::define\fR and \fBoo::objdefine\fR commands look up which definition 408 +namespace to use using the class inheritance hierarchy. 409 +.RE 410 +.VE TIP524 448 411 .TP 449 412 \fBinfo class destructor\fI class\fR 450 -.VS 8.6 413 +. 451 414 This subcommand returns the body of the destructor of class \fIclass\fR. If no 452 415 destructor is present, this returns the empty string. 453 -.VE 8.6 454 416 .TP 455 417 \fBinfo class filters\fI class\fR 456 -.VS 8.6 418 +. 457 419 This subcommand returns the list of filter methods set on the class. 458 -.VE 8.6 459 420 .TP 460 421 \fBinfo class forward\fI class method\fR 461 -.VS 8.6 422 +. 462 423 This subcommand returns the argument list for the method forwarding called 463 424 \fImethod\fR that is set on the class called \fIclass\fR. 464 -.VE 8.6 465 425 .TP 466 426 \fBinfo class instances\fI class\fR ?\fIpattern\fR? 467 -.VS 8.6 427 +. 468 428 This subcommand returns a list of instances of class \fIclass\fR. If the 469 429 optional \fIpattern\fR argument is present, it constrains the list of returned 470 430 instances to those that match it according to the rules of \fBstring match\fR. 471 -.VE 8.6 472 431 .TP 473 432 \fBinfo class methods\fI class\fR ?\fIoptions...\fR? 474 -.VS 8.6 433 +. 475 434 This subcommand returns a list of all public (i.e. exported) methods of the 476 435 class called \fIclass\fR. Any of the following \fIoption\fRs may be 477 -specified, controlling exactly which method names are returned: 436 +given, controlling exactly which method names are returned: 478 437 .RS 479 -.VE 8.6 480 438 .TP 481 439 \fB\-all\fR 482 -.VS 8.6 483 -If the \fB\-all\fR flag is given, the list of methods will include those 440 +. 441 +If the \fB\-all\fR flag is given, 442 +.VS TIP500 443 +and the \fB\-scope\fR flag is not given, 444 +.VE TIP500 445 +the list of methods will include those 484 446 methods defined not just by the class, but also by the class's superclasses 485 447 and mixins. 486 -.VE 8.6 487 448 .TP 488 449 \fB\-private\fR 489 -.VS 8.6 490 -If the \fB\-private\fR flag is given, the list of methods will also include 491 -the private (i.e. non-exported) methods of the class (and superclasses and 450 +. 451 +If the \fB\-private\fR flag is given, 452 +.VS TIP500 453 +and the \fB\-scope\fR flag is not given, 454 +.VE TIP500 455 +the list of methods will also include 456 +the non-exported methods of the class (and superclasses and 492 457 mixins, if \fB\-all\fR is also given). 458 +.VS TIP500 459 +Note that this naming is an unfortunate clash with true private methods; this 460 +option name is retained for backward compatibility. 461 +.VE TIP500 462 +.TP 463 +\fB\-scope\fI scope\fR 464 +.VS TIP500 465 +Returns a list of all methods on \fIclass\fR that have the given visibility 466 +\fIscope\fR. When this option is supplied, both the \fB\-all\fR and 467 +\fB\-private\fR options are ignored. The valid values for \fIscope\fR are: 468 +.RS 469 +.IP \fBpublic\fR 3 470 +Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance 471 +of this class) are to be returned. 472 +.IP \fBunexported\fR 3 473 +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to 474 +be returned. 475 +.IP \fBprivate\fR 3 476 +Only methods with \fIprivate\fR scope (i.e., only callable from within this class's 477 +methods) are to be returned. 493 478 .RE 494 -.VE 8.6 479 +.VE TIP500 480 +.RE 495 481 .TP 496 482 \fBinfo class methodtype\fI class method\fR 497 -.VS 8.6 483 +. 498 484 This subcommand returns a description of the type of implementation used for 499 485 the method named \fImethod\fR of class \fIclass\fR. When the result is 500 486 \fBmethod\fR, further information can be discovered with \fBinfo class 501 487 definition\fR, and when the result is \fBforward\fR, further information can 502 488 be discovered with \fBinfo class forward\fR. 503 -.VE 8.6 504 489 .TP 505 490 \fBinfo class mixins\fI class\fR 506 -.VS 8.6 491 +. 507 492 This subcommand returns a list of all classes that have been mixed into the 508 493 class named \fIclass\fR. 509 -.VE 8.6 510 494 .TP 511 495 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR? 512 -.VS 8.6 496 +. 513 497 This subcommand returns a list of direct subclasses of class \fIclass\fR. If 514 498 the optional \fIpattern\fR argument is present, it constrains the list of 515 499 returned classes to those that match it according to the rules of 516 500 \fBstring match\fR. 517 -.VE 8.6 518 501 .TP 519 502 \fBinfo class superclasses\fI class\fR 520 -.VS 8.6 503 +. 521 504 This subcommand returns a list of direct superclasses of class \fIclass\fR in 522 505 inheritance precedence order. 523 -.VE 8.6 524 506 .TP 525 -\fBinfo class variables\fI class\fR 526 -.VS 8.6 507 +\fBinfo class variables\fI class\fR ?\fB\-private\fR? 508 +. 527 509 This subcommand returns a list of all variables that have been declared for 528 510 the class named \fIclass\fR (i.e. that are automatically present in the 529 511 class's methods, constructor and destructor). 512 +.VS TIP500 513 +If the \fB\-private\fR option is given, this lists the private variables 514 +declared instead. 515 +.VE TIP500 530 516 .SS "OBJECT INTROSPECTION" 531 517 .PP 532 518 The following \fIsubcommand\fR values are supported by \fBinfo object\fR: 533 -.VE 8.6 534 519 .TP 535 520 \fBinfo object call\fI object method\fR 536 -.VS 8.6 521 +. 537 522 Returns a description of the method implementations that are used to provide 538 523 \fIobject\fR's implementation of \fImethod\fR. This consists of a list of 539 524 lists of four elements, where each sublist consists of a word that describes 540 525 the general type of method implementation (being one of \fBmethod\fR for an 541 -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a 526 +ordinary method, \fBfilter\fR for an applied filter, 527 +.VS TIP500 528 +\fBprivate\fR for a private method, 529 +.VE TIP500 530 +and \fBunknown\fR for a 542 531 method that is invoked as part of unknown method handling), a word giving the 543 532 name of the particular method invoked (which is always the same as 544 533 \fImethod\fR for the \fBmethod\fR type, and 545 534 .QW \fBunknown\fR 546 535 for the \fBunknown\fR type), a word giving what defined the method (the fully 547 536 qualified name of the class, or the literal string \fBobject\fR if the method 548 537 implementation is on an instance), and a word describing the type of method 549 538 implementation (see \fBinfo object methodtype\fR). 550 539 .RS 551 540 .PP 552 541 Note that there is no inspection of whether the method implementations 553 -actually use \fBnext\fR to transfer control along the call chain. 542 +actually use \fBnext\fR to transfer control along the call chain, 543 +.VS TIP500 544 +and the call chains that this command files do not actually contain private 545 +methods. 546 +.VE TIP500 554 547 .RE 555 -.VE 8.6 556 548 .TP 557 549 \fBinfo object class\fI object\fR ?\fIclassName\fR? 558 -.VS 8.6 559 -If \fIclassName\fR is unspecified, this subcommand returns class of the 550 +. 551 +If \fIclassName\fR is not given, this subcommand returns class of the 560 552 \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a 561 553 boolean value indicating whether the \fIobject\fR is of that class. 562 -.VE 8.6 554 +.TP 555 +\fBinfo object creationid\fI object\fR 556 +.VS TIP500 557 +Returns the unique creation identifier for the \fIobject\fR object. This 558 +creation identifier is unique to the object (within a Tcl interpreter) and 559 +cannot be controlled at object creation time or altered afterwards. 560 +.RS 561 +.PP 562 +\fIImplementation note:\fR the creation identifier is used to generate unique 563 +identifiers associated with the object, especially for private variables. 564 +.RE 565 +.VE TIP500 563 566 .TP 564 567 \fBinfo object definition\fI object method\fR 565 -.VS 8.6 568 +. 566 569 This subcommand returns a description of the definition of the method named 567 570 \fImethod\fR of object \fIobject\fR. The definition is described as a two 568 571 element list; the first element is the list of arguments to the method in a 569 572 form suitable for passing to another call to \fBproc\fR or a method definition, 570 573 and the second element is the body of the method. 571 -.VE 8.6 572 574 .TP 573 575 \fBinfo object filters\fI object\fR 574 -.VS 8.6 576 +. 575 577 This subcommand returns the list of filter methods set on the object. 576 -.VE 8.6 577 578 .TP 578 579 \fBinfo object forward\fI object method\fR 579 -.VS 8.6 580 +. 580 581 This subcommand returns the argument list for the method forwarding called 581 582 \fImethod\fR that is set on the object called \fIobject\fR. 582 -.VE 8.6 583 583 .TP 584 584 \fBinfo object isa\fI category object\fR ?\fIarg\fR? 585 -.VS 8.6 585 +. 586 586 This subcommand tests whether an object belongs to a particular category, 587 587 returning a boolean value that indicates whether the \fIobject\fR argument 588 588 meets the criteria for the category. The supported categories are: 589 -.VE 8.6 590 589 .RS 591 590 .TP 592 591 \fBinfo object isa class\fI object\fR 593 -.VS 8.6 592 +. 594 593 This returns whether \fIobject\fR is a class (i.e. an instance of 595 594 \fBoo::class\fR or one of its subclasses). 596 -.VE 8.6 597 595 .TP 598 596 \fBinfo object isa metaclass\fI object\fR 599 -.VS 8.6 597 +. 600 598 This returns whether \fIobject\fR is a class that can manufacture classes 601 599 (i.e. is \fBoo::class\fR or a subclass of it). 602 -.VE 8.6 603 600 .TP 604 601 \fBinfo object isa mixin\fI object class\fR 605 -.VS 8.6 602 +. 606 603 This returns whether \fIclass\fR is directly mixed into \fIobject\fR. 607 -.VE 8.6 608 604 .TP 609 605 \fBinfo object isa object\fI object\fR 610 -.VS 8.6 606 +. 611 607 This returns whether \fIobject\fR really is an object. 612 -.VE 8.6 613 608 .TP 614 609 \fBinfo object isa typeof\fI object class\fR 615 -.VS 8.6 610 +. 616 611 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether 617 612 \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether 618 613 direct or indirect). 619 614 .RE 620 -.VE 8.6 621 615 .TP 622 616 \fBinfo object methods\fI object\fR ?\fIoption...\fR? 623 -.VS 8.6 617 +. 624 618 This subcommand returns a list of all public (i.e. exported) methods of the 625 619 object called \fIobject\fR. Any of the following \fIoption\fRs may be 626 -specified, controlling exactly which method names are returned: 620 +given, controlling exactly which method names are returned: 627 621 .RS 628 -.VE 8.6 629 622 .TP 630 623 \fB\-all\fR 631 -.VS 8.6 632 -If the \fB\-all\fR flag is given, the list of methods will include those 624 +. 625 +If the \fB\-all\fR flag is given, 626 +.VS TIP500 627 +and the \fB\-scope\fR flag is not given, 628 +.VE TIP500 629 +the list of methods will include those 633 630 methods defined not just by the object, but also by the object's class and 634 631 mixins, plus the superclasses of those classes. 635 -.VE 8.6 636 632 .TP 637 633 \fB\-private\fR 638 -.VS 8.6 639 -If the \fB\-private\fR flag is given, the list of methods will also include 640 -the private (i.e. non-exported) methods of the object (and classes, if 634 +. 635 +If the \fB\-private\fR flag is given, 636 +.VS TIP500 637 +and the \fB\-scope\fR flag is not given, 638 +.VE TIP500 639 +the list of methods will also include 640 +the non-exported methods of the object (and classes, if 641 641 \fB\-all\fR is also given). 642 +.VS TIP500 643 +Note that this naming is an unfortunate clash with true private methods; this 644 +option name is retained for backward compatibility. 645 +.VE TIP500 646 +.TP 647 +\fB\-scope\fI scope\fR 648 +.VS TIP500 649 +Returns a list of all methods on \fIobject\fR that have the given visibility 650 +\fIscope\fR. When this option is supplied, both the \fB\-all\fR and 651 +\fB\-private\fR options are ignored. The valid values for \fIscope\fR are: 652 +.RS 653 +.IP \fBpublic\fR 3 654 +Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be 655 +returned. 656 +.IP \fBunexported\fR 3 657 +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to 658 +be returned. 659 +.IP \fBprivate\fR 3 660 +Only methods with \fIprivate\fR scope (i.e., only callable from within this object's 661 +instance methods) are to be returned. 642 662 .RE 643 -.VE 8.6 663 +.VE TIP500 664 +.RE 644 665 .TP 645 666 \fBinfo object methodtype\fI object method\fR 646 -.VS 8.6 667 +. 647 668 This subcommand returns a description of the type of implementation used for 648 669 the method named \fImethod\fR of object \fIobject\fR. When the result is 649 670 \fBmethod\fR, further information can be discovered with \fBinfo object 650 671 definition\fR, and when the result is \fBforward\fR, further information can 651 672 be discovered with \fBinfo object forward\fR. 652 -.VE 8.6 653 673 .TP 654 674 \fBinfo object mixins\fI object\fR 655 -.VS 8.6 675 +. 656 676 This subcommand returns a list of all classes that have been mixed into the 657 677 object named \fIobject\fR. 658 -.VE 8.6 659 678 .TP 660 679 \fBinfo object namespace\fI object\fR 661 -.VS 8.6 680 +. 662 681 This subcommand returns the name of the internal namespace of the object named 663 682 \fIobject\fR. 664 -.VE 8.6 665 683 .TP 666 -\fBinfo object variables\fI object\fR 667 -.VS 8.6 684 +\fBinfo object variables\fI object\fRR ?\fB\-private\fR? 685 +. 668 686 This subcommand returns a list of all variables that have been declared for 669 687 the object named \fIobject\fR (i.e. that are automatically present in the 670 688 object's methods). 671 -.VE 8.6 689 +.VS TIP500 690 +If the \fB\-private\fR option is given, this lists the private variables 691 +declared instead. 692 +.VE TIP500 672 693 .TP 673 694 \fBinfo object vars\fI object\fR ?\fIpattern\fR? 674 -.VS 8.6 695 +. 675 696 This subcommand returns a list of all variables in the private namespace of 676 697 the object named \fIobject\fR. If the optional \fIpattern\fR argument is 677 698 given, it is a filter (in the syntax of a \fBstring match\fR glob pattern) 678 699 that constrains the list of variables returned. Note that this is different 679 700 from the list returned by \fBinfo object variables\fR; that can include 680 701 variables that are currently unset, whereas this can include variables that 681 702 are not automatically included by any of \fIobject\fR's methods (or those of 682 703 its class, superclasses or mixins). 683 -.VE 8.6 684 704 .SH EXAMPLES 685 705 .PP 686 706 This command prints out a procedure suitable for saving in a Tcl 687 707 script: 688 708 .PP 689 709 .CS 690 710 proc printProc {procName} { ................................................................................ 699 719 lappend formals [list $var] 700 720 } 701 721 } 702 722 puts [lappend result $formals [\fBinfo body\fR $procName]] 703 723 } 704 724 .CE 705 725 .SS "EXAMPLES WITH OBJECTS" 706 -.VS 8.6 707 726 .PP 708 727 Every object necessarily knows what its class is; this information is 709 728 trivially extractable through introspection: 710 729 .PP 711 730 .CS 712 731 oo::class create c 713 732 c create o ................................................................................ 720 739 The introspection capabilities can be used to discover what class implements a 721 740 method and get how it is defined. This procedure illustrates how: 722 741 .PP 723 742 .CS 724 743 proc getDef {obj method} { 725 744 foreach inf [\fBinfo object call\fR $obj $method] { 726 745 lassign $inf calltype name locus methodtype 746 + 727 747 # Assume no forwards or filters, and hence no $calltype 728 748 # or $methodtype checks... 749 + 729 750 if {$locus eq "object"} { 730 751 return [\fBinfo object definition\fR $obj $name] 731 752 } else { 732 753 return [\fBinfo class definition\fR $locus $name] 733 754 } 734 755 } 735 756 error "no definition for $method" ................................................................................ 744 765 .PP 745 766 .CS 746 767 proc getDef {obj method} { 747 768 if {$method in [\fBinfo object methods\fR $obj]} { 748 769 # Assume no forwards 749 770 return [\fBinfo object definition\fR $obj $method] 750 771 } 772 + 751 773 set cls [\fBinfo object class\fR $obj] 774 + 752 775 while {$method ni [\fBinfo class methods\fR $cls]} { 753 776 # Assume the simple case 754 777 set cls [lindex [\fBinfo class superclass\fR $cls] 0] 755 778 if {$cls eq ""} { 756 779 error "no definition for $method" 757 780 } 758 781 } 782 + 759 783 # Assume no forwards 760 784 return [\fBinfo class definition\fR $cls $method] 761 785 } 762 786 .CE 763 -.VE 8.6 764 787 .SH "SEE ALSO" 765 -.VS 8.6 766 788 global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n), 767 -.VE 8.6 768 789 tcl_library(n), tcl_patchLevel(n), tcl_version(n) 769 790 .SH KEYWORDS 770 791 command, information, interpreter, introspection, level, namespace, 771 -.VS 8.6 772 -object, 773 -.VE 8.6 774 -procedure, variable 792 +object, procedure, variable 775 793 '\" Local Variables: 776 794 '\" mode: nroff 777 795 '\" fill-column: 78 778 796 '\" End:
Changes to doc/interp.n.
197 197 \fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? 198 198 . 199 199 Controls whether frame-level stack information is captured in the 200 200 slave interpreter identified by \fIpath\fR. If no arguments are 201 201 given, option and current setting are returned. If \fB\-frame\fR 202 202 is given, the debug setting is set to the given boolean if provided 203 203 and the current setting is returned. 204 -This only effects the output of \fBinfo frame\fR, in that exact 204 +This only affects the output of \fBinfo frame\fR, in that exact 205 205 frame-level information for command invocation at the bytecode level 206 206 is only captured with this setting on. 207 207 .RS 208 208 .PP 209 209 For example, with code like 210 210 .PP 211 211 .CS ................................................................................ 232 232 execution of all commands. 233 233 .PP 234 234 Note that once it is on, this flag cannot be switched back off: such 235 235 attempts are silently ignored. This is needed to maintain the 236 236 consistency of the underlying interpreter's state. 237 237 .RE 238 238 .TP 239 -\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR 239 +\fBinterp\fR \fBdelete \fR?\fIpath ...\fR? 240 240 . 241 241 Deletes zero or more interpreters given by the optional \fIpath\fR 242 242 arguments, and for each interpreter, it also deletes its slaves. The 243 243 command also deletes the slave command for each interpreter deleted. 244 244 For each \fIpath\fR argument, if no interpreter by that name 245 245 exists, the command raises an error. 246 246 .TP
Changes to doc/join.n.
38 38 \fBjoin\fR $data 39 39 \fB\(-> 1 2 3 4 5 {6 7} 8\fR 40 40 .CE 41 41 .SH "SEE ALSO" 42 42 list(n), lappend(n), split(n) 43 43 .SH KEYWORDS 44 44 element, join, list, separator 45 +'\" Local Variables: 46 +'\" mode: nroff 47 +'\" fill-column: 78 48 +'\" End:
Changes to doc/lappend.n.
18 18 .SH DESCRIPTION 19 19 .PP 20 20 This command treats the variable given by \fIvarName\fR as a list 21 21 and appends each of the \fIvalue\fR arguments to that list as a separate 22 22 element, with spaces between elements. 23 23 If \fIvarName\fR does not exist, it is created as a list with elements 24 24 given by the \fIvalue\fR arguments. 25 +.VS TIP508 26 +If \fIvarName\fR indicate an element that does not exist of an array that has 27 +a default value set, list that is comprised of the default value with all the 28 +\fIvalue\fR arguments appended as elements will be stored in the array 29 +element. 30 +.VE TIP508 25 31 \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs 26 32 are appended as list elements rather than raw text. 27 33 This command provides a relatively efficient way to build up 28 34 large lists. For example, 29 35 .QW "\fBlappend a $b\fR" 30 36 is much more efficient than 31 37 .QW "\fBset a [concat $a [list $b]]\fR" ................................................................................ 43 49 1 2 3 4 5 44 50 .CE 45 51 .SH "SEE ALSO" 46 52 list(n), lindex(n), linsert(n), llength(n), lset(n), 47 53 lsort(n), lrange(n) 48 54 .SH KEYWORDS 49 55 append, element, list, variable 56 +.\" Local variables: 57 +.\" mode: nroff 58 +.\" fill-column: 78 59 +.\" End:
Changes to doc/lindex.n.
9 9 .TH lindex n 8.4 Tcl "Tcl Built-In Commands" 10 10 .so man.macros 11 11 .BS 12 12 '\" Note: do not modify the .SH NAME line immediately below! 13 13 .SH NAME 14 14 lindex \- Retrieve an element from a list 15 15 .SH SYNOPSIS 16 -\fBlindex \fIlist ?index ...?\fR 16 +\fBlindex \fIlist\fR ?\fIindex ...\fR? 17 17 .BE 18 18 .SH DESCRIPTION 19 19 .PP 20 20 The \fBlindex\fR command accepts a parameter, \fIlist\fR, which 21 21 it treats as a Tcl list. It also accepts zero or more \fIindices\fR into 22 22 the list. The indices may be presented either consecutively on the 23 23 command line, or grouped in a
Added doc/link.n.
1 +'\" 2 +'\" Copyright (c) 2011-2015 Andreas Kupries 3 +'\" Copyright (c) 2018 Donal K. Fellows 4 +'\" 5 +'\" See the file "license.terms" for information on usage and redistribution 6 +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. 7 +'\" 8 +.TH link n 0.3 TclOO "TclOO Commands" 9 +.so man.macros 10 +.BS 11 +'\" Note: do not modify the .SH NAME line immediately below! 12 +.SH NAME 13 +link \- create link from command to method of object 14 +.SH SYNOPSIS 15 +.nf 16 +package require TclOO 17 + 18 +\fBlink\fR \fImethodName\fR ?\fI...\fR? 19 +\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR? 20 +.fi 21 +.BE 22 +.SH DESCRIPTION 23 +The \fBlink\fR command is available within methods. It takes a series of one 24 +or more method names (\fImethodName ...\fR) and/or pairs of command- and 25 +method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods 26 +available as commands without requiring the explicit use of the name of the 27 +object or the \fBmy\fR command. The method does not need to exist at the time 28 +that the link is made; if the link command is invoked when the method does not 29 +exist, the standard \fBunknown\fR method handling system is used. 30 +.PP 31 +The command name under which the method becomes available defaults to the 32 +method name, except where explicitly specified through an alias/method pair. 33 +Formally, every argument must be a list; if the list has two elements, the 34 +first element is the name of the command to create and the second element is 35 +the name of the method of the current object to which the command links; 36 +otherwise, the name of the command and the name of the method are the same 37 +string (the first element of the list). 38 +.PP 39 +If the name of the command is not a fully-qualified command name, it will be 40 +resolved with respect to the current namespace (i.e., the object namespace). 41 +.SH EXAMPLES 42 +This demonstrates linking a single method in various ways. First it makes a 43 +simple link, then a renamed link, then an external link. Note that the method 44 +itself is unexported, but that it can still be called directly from outside 45 +the class. 46 +.PP 47 +.CS 48 +oo::class create ABC { 49 + method Foo {} { 50 + puts "This is Foo in [self]" 51 + } 52 + 53 + constructor {} { 54 + \fBlink\fR Foo 55 + # The method foo is now directly accessible as foo here 56 + \fBlink\fR {bar Foo} 57 + # The method foo is now directly accessible as bar 58 + \fBlink\fR {::ExternalCall Foo} 59 + # The method foo is now directly accessible in the global 60 + # namespace as ExternalCall 61 + } 62 + 63 + method grill {} { 64 + puts "Step 1:" 65 + Foo 66 + puts "Step 2:" 67 + bar 68 + } 69 +} 70 + 71 +ABC create abc 72 +abc grill 73 + \fI\(-> Step 1:\fR 74 + \fI\(-> This is foo in ::abc\fR 75 + \fI\(-> Step 2:\fR 76 + \fI\(-> This is foo in ::abc\fR 77 +# Direct access via the linked command 78 +puts "Step 3:"; ExternalCall 79 + \fI\(-> Step 3:\fR 80 + \fI\(-> This is foo in ::abc\fR 81 +.CE 82 +.PP 83 +This example shows that multiple linked commands can be made in a call to 84 +\fBlink\fR, and that they can handle arguments. 85 +.PP 86 +.CS 87 +oo::class create Ex { 88 + constructor {} { 89 + \fBlink\fR a b c 90 + # The methods a, b, and c (defined below) are all now 91 + # directly acessible within methods under their own names. 92 + } 93 + 94 + method a {} { 95 + puts "This is a" 96 + } 97 + method b {x} { 98 + puts "This is b($x)" 99 + } 100 + method c {y z} { 101 + puts "This is c($y,$z)" 102 + } 103 + 104 + method call {p q r} { 105 + a 106 + b $p 107 + c $q $r 108 + } 109 +} 110 + 111 +set o [Ex new] 112 +$o 3 5 7 113 + \fI\(-> This is a\fR 114 + \fI\(-> This is b(3)\fR 115 + \fI\(-> This is c(5,7)\fR 116 +.CE 117 +.SH "SEE ALSO" 118 +interp(n), my(n), oo::class(n), oo::define(n) 119 +.SH KEYWORDS 120 +command, method, object 121 +.\" Local Variables: 122 +.\" mode: nroff 123 +.\" fill-column: 78 124 +.\" End:
Changes to doc/llength.n.
49 49 1,0 50 50 .CE 51 51 .SH "SEE ALSO" 52 52 list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 53 53 lset(n), lsort(n), lrange(n), lreplace(n) 54