diff options
Diffstat (limited to 'jim_tcl.txt')
| -rw-r--r-- | jim_tcl.txt | 305 |
1 files changed, 240 insertions, 65 deletions
diff --git a/jim_tcl.txt b/jim_tcl.txt index 29d5505..adf68a1 100644 --- a/jim_tcl.txt +++ b/jim_tcl.txt @@ -34,7 +34,7 @@ available only in Jim Tcl. Some notable differences with Tcl 8.5/8.6/8.7 are: #. Object-based I/O (aio), but with a Tcl-compatibility layer -#. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6 +#. I/O: Support for sockets and pipes including TCP, UDP, UNIX-Domain sockets and IPv6 #. Integers are 64bit #. Support for references (`ref`/`getref`/`setref`) and garbage collection #. Builtin dictionary type (`dict`) with some limitations compared to Tcl 8.6 @@ -44,11 +44,10 @@ Some notable differences with Tcl 8.5/8.6/8.7 are: #. Support for "static" variables in procedures #. Threads and coroutines are not supported #. Command and variable traces are not supported -#. Built-in command line editing +#. Built-in command line editing in interactive mode with autocompletion and hints #. Expression shorthand syntax: +$(...)+ #. Modular build allows many features to be omitted or built as dynamic, loadable modules #. Highly suitable for use in an embedded environment -#. Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets #. Jim does not convert backslash-newline within braces (in order to preserve accurate line numbers) RECENT CHANGES @@ -58,6 +57,16 @@ Changes since 0.83 #. `aio` - support for configurable read and write buffering #. Add support for `package forget` #. Add `aio translation` support (and fconfigure -translation) +#. `exec` TIP 424 - support safer +'exec |'+ syntax (also +'open "|| pipeline..."'+) +#. New `lsubst` command to create lists using subst-style substitution +#. Add support for `regexp -expanded` and `regsub -expanded` +#. `vwait` now accepts a script argument +#. Add support for `os.umask` +#. Add `taint` support for improved data security +#. Improved API for creating C commands with +'Jim_RegisterCommand'+ for arg checking and usage +#. New `info usage` to return the usage for a proc or native command +#. New `info aliases` to list all aliases +#. `expr` supports new +'=*'+ and +'=~'+ matching operators (see <<_expressions,EXPRESSIONS>>) Changes between 0.82 and 0.83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -107,7 +116,7 @@ Changes between 0.79 and 0.80 #. dictionaries and arrays now preserve insertion order, matching Tcl and the documentation #. Add `dict getwithdefault` (and the alias `dict getdef`) per TIP 342 #. Add string comparison operators (lt, gt, le, ge) per TIP 461 -#. Implement 0d radix prefix for decimal per TIP 472 +#. Implement +0d+ radix prefix for decimal per TIP 472 Changes between 0.78 and 0.79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -324,7 +333,7 @@ has three fields: the first, `set`, is the name of a Tcl command, and the last two, 'a' and '22', will be passed as arguments to the `set` command. The command name may refer either to a built-in Tcl command, an application-specific command bound in with the library -procedure 'Jim_CreateCommand', or a command procedure defined with the +procedure 'Jim_RegisterCommand', or a command procedure defined with the `proc` built-in command. Arguments are passed literally as text strings. Individual commands may @@ -874,6 +883,14 @@ of precedence: String equal and not equal. Uses the string value directly without attempting to convert to a number first. ++=*+:: + String glob match. The left and side is the string to match and the right + and side is the pattern. See <<_string_matching,STRING MATCHING>>. + ++=~+:: + String regexp match. The left and side is the string to match and the right + and side is the regular expression. See <<_regular_expressions,REGULAR EXPRESSIONS>>. + +in ni+:: String in list and not in list. For 'in', result is 1 if the left operand (as a string) is contained in the right operand (as a list), or 0 otherwise. The result for @@ -1204,6 +1221,10 @@ defined in jim.h, and are: Indicates that the command called the `exit` command. The string contains the exit code. ++JIM_USAGE(-1)+:: + This is a special return code that is automatically translated into JIM_ERR with the command usage + (from Jim_RegisterCommand()) as the message. + Tcl programmers do not normally need to think about return codes, since +JIM_OK+ is almost always returned. If anything else is returned by a command, then the Tcl interpreter immediately stops processing @@ -2062,7 +2083,7 @@ curry Similar to `alias` except it creates an anonymous procedure (lambda) instead of a named procedure. -the following creates a local, unnamed alias for the command `info exists`. +The following creates a local, unnamed alias for the command `info exists`. ---- set e [local curry info exists] @@ -2101,6 +2122,11 @@ Performs one of several operations on dictionary values. The +'option'+ argument determines what action is carried out by the command. The legal +'options'+ are: ++*dict append* 'dictionaryName key ?string ...?'+:: + This appends the given string (or strings) to the value that + the given key maps to in +'dictionaryName'+. Non-existent keys + are treated as if they map to an empty string. + +*dict create* '?key value \...?'+:: Create and return a new dictionary value that contains each of the key/value mappings listed as arguments (keys and values @@ -2113,6 +2139,9 @@ command. The legal +'options'+ are: dictionary value. This returns a true value exactly when `dict get` on that path will succeed. ++*dict for* '{keyvar valuevar} dictionary script'+:: + *TBD* + +*dict get* 'dictionary ?key \...?'+:: Given a dictionary value (first argument) and a key (second argument), this will retrieve the value for that key. Where several keys are @@ -2133,12 +2162,28 @@ command. The legal +'options'+ are: Similar to `dict get` except if no value exists in the dictionary for the give key(s), returns +'default'+ instead. ++*dict incr* 'dictionaryName key ?increment?'+:: + This adds the given increment value (an integer that defaults + to 1 if not specified) to the value that the given key maps to + in +'dictionaryName'+. Non-existent keys are treated as if + they map to 0. It is an error to increment a value for an + existing key if that value is not an integer. + ++*dict info* 'dictionary'+:: + Returns some information about the utilisation of the data + within the hashtable that represents +'dictionary'+. + +*dict keys* 'dictionary ?pattern?'+:: Returns a list of the keys in the dictionary. If +'pattern'+ is specified, then only those keys whose names match +'pattern'+ (using <<_string_matching,STRING MATCHING>> rules) are included. ++*dict lappend* 'dictionaryName key ?value ...?'+:: + This appends the given items to the list value that the given + key maps to in +'dictionaryName'+. Non-existent keys are treated + as if they map to the empty list. + +*dict merge* ?'dictionary \...'?+:: Return a dictionary that contains the contents of each of the +'dictionary'+ arguments. Where two (or more) dictionaries @@ -2146,6 +2191,13 @@ command. The legal +'options'+ are: maps that key to the value according to the last dictionary on the command line containing a mapping for that key. ++*dict replace* 'dictionary ?key value ...?'+:: + Return a new dictionary that is a copy of +'dictionary'+ + except with some values different or some + extra key/value pairs added. It is legal for this command to + be called with no key/value pairs, but illegal for this command + to be called with a key but no value. + +*dict set* 'dictionaryName key ?key \...? value'+:: This operation takes the +'name'+ of a variable containing a dictionary value and places an updated dictionary value in that variable @@ -2165,6 +2217,16 @@ command. The legal +'options'+ are: least one key must be specified, but the last key on the key-path need not exist. All other components on the path must exist. ++*dict update* 'dictionaryName key varName ?key VarName ...? script'+:: + *TBD* + ++*dict values* 'dictionary ?globPattern?'+:: + Return a list of all values in +'dictionary'+. If a pattern is + supplied, only those values that match it (according to the + rules of `string match`) will be returned. The returned values + will be in the order of that the keys associated with those + values were inserted into the dictionary. + +*dict with* 'dictionaryName key ?key \...? script'+:: Execute the Tcl script in +'script'+ with the value for each key in +'dictionaryName'+ mapped to a variable with the same @@ -2184,8 +2246,6 @@ command. The legal +'options'+ are: explicitly unset). Note that changes to the contents of +'dictionaryName'+ only happen when +'script'+ terminates. -+*dict for, values, incr, append, lappend, update, info, replace*+ to be documented... - ensemble ~~~~~~~~ +*ensemble* 'name ?*-automap*? prefix'+ @@ -2195,15 +2255,15 @@ By default, the prefix is +'name'+ followed by a single space. For example, consider: +---- proc {test open} {name} { ... } proc {test close} {handle} { ... } proc {test show} {handle} { ... } ensemble test +---- Now the '+test+' command has been created that redirects based on the first argument. -e.g. - - test open $filename => {test open} $filename +e.g. +'test open $filename'+ => +'{test open} $filename'+ env ~~~ @@ -2282,6 +2342,8 @@ exec ~~~~ +*exec* 'arg ?arg\...?'+ ++*exec* | '{cmdlist \...} ?redirection \...?'+ + This command treats its arguments as the specification of one or more UNIX commands to execute as subprocesses. The commands take the form of a standard shell pipeline; @@ -2315,7 +2377,8 @@ is a newline then that character is deleted from the result or error message for consistency with normal Tcl return values. -An +'arg'+ may have one of the following special forms: +An +'arg'+ (or +'redirection'+ in the second form) may have one of the +following special forms: +>filename+:: The standard output of the last command in the pipeline @@ -2332,23 +2395,23 @@ An +'arg'+ may have one of the following special forms: will normally return an empty string. +2>filename+:: - The standard error of the last command in the pipeline + The standard error of all commands in the pipeline is redirected to the file. +2>>filename+:: As above, but append to the file. +2>@fileId+:: - The standard error of the last command in the pipeline is + The standard error of all commands in the pipeline is redirected to the given (writable) file descriptor. +2>@1+:: - The standard error of the last command in the pipeline is - redirected to the same file descriptor as the standard output. + The standard error of all commands in the pipeline is + redirected command output. +>&filename+:: - Both the standard output and standard error of the last command - in the pipeline is redirected to the file. + Both standard output from the last command and standard error from all commands + in the pipeline are redirected to the file. +>>&filename+:: As above, but append to the file. @@ -2365,24 +2428,29 @@ An +'arg'+ may have one of the following special forms: The standard input of the first command in the pipeline is taken from the given (readable) file descriptor. +Note that any of the forms that take an argument (filename, fileId or string) +their argument may be a separate word. e.g. +'<< $str'+. + If there is no redirection of standard input, standard error or standard output, these are connected to the corresponding input or output of the application. -If the last +'arg'+ is +&+ then the command will be -executed in background. -In this case the standard output from the last command -in the pipeline will -go to the application's standard output unless -redirected in the command, and error output from all -the commands in the pipeline will go to the application's -standard error file. The return value of exec in this case -is a list of process ids (pids) in the pipeline. +If the last +'arg'+ or +'redirection'+ is +&+ then the command will be +executed in background. In this case the standard output from the last +command in the pipeline will go to the application's standard output +unless redirected in the command, and error output from all the commands +in the pipeline will go to the application's standard error file. The +return value of exec in this case is a list of process ids (pids) in +the pipeline. Each +'arg'+ becomes one word for a command, except for +|+, +<+, +<<+, +>+, and +&+ arguments, and the arguments that follow +<+, +<<+, and +>+. +In the second form, +'cmdlist'+ is the command list, so there +is no ambiguity about whether an argument or a redirection. +Note that this second form is not currently supported by Tcl. + The first word in each command is taken as the command name; the directories in the PATH environment variable are searched for an executable by the given name. @@ -2424,12 +2492,12 @@ this variable is unset, in which case the original environment is used). exists ~~~~~~ -+*exists ?-var|-proc|-command|-alias?* 'name'+ ++*exists ?-var|-proc|-command|-alias|-channel?* 'name'+ -Checks the existence of the given variable, procedure, command -or alias respectively and returns 1 if it exists or 0 if not. This command +Checks the existence of the given variable, procedure, command, +alias or channel respectively and returns 1 if it exists or 0 if not. This command provides a more simplified/convenient version of `info exists`, -`info procs` and `info commands`. +`info procs`, `info commands`, `info aliases` and `info channels`. If the type is omitted, a type of '-var' is used. The type may be abbreviated. @@ -2870,19 +2938,27 @@ The legal +'option'+'s (which may be abbreviated) are: +'command'+ must be an alias created with `alias`. In which case the target command and arguments, as passed to `alias` are returned. See `exists -alias` ++*info aliases ?-all?* ?'pattern'?+:: + Returns a list of alias commands. + See `info commands` for the meaning of +*-all*+ and +'pattern'+. + +*info body* 'procname'+:: Returns the body of procedure +'procname'+. +'procname'+ must be the name of a Tcl command procedure. -+*info channels*+:: - Returns a list of all open file handles from `open` or `socket` ++*info channels ?-all?* ?'pattern'?+:: + Returns a list of open file handles from `open` or `socket`. + See `info commands` for the meaning of +*-all*+ and +'pattern'+. -+*info commands* ?'pattern'?+:: ++*info commands ?-all?* ?'pattern'?+:: If +'pattern'+ isn't specified, returns a list of names of all the Tcl commands, including both the built-in commands written in C and - the command procedures defined using the `proc` command. + the command procedures defined using the `proc` command (including aliases + and channels). If +'pattern'+ is specified, only those names matching +'pattern'+ (using <<_string_matching,STRING MATCHING>> rules) are returned. + Normally commands containing a space character are not returned. + If +*-all*+ is given, the result does include these commands. +*info complete* 'command' ?'missing'?+:: Returns 1 if +'command'+ is a complete Tcl command in the sense of @@ -2958,11 +3034,13 @@ The legal +'option'+'s (which may be abbreviated) are: was invoked. A full path will be returned, unless the path can't be determined, in which case the empty string will be returned. -+*info procs* ?'pattern'?+:: - If +'pattern'+ isn't specified, returns a list of all the - names of Tcl command procedures. - If +'pattern'+ is specified, only those names matching +'pattern'+ - (using <<_string_matching,STRING MATCHING>> rules) are returned. ++*info patchlevel*+:: + Returns the build (git) version if available. Otherwise + returns the same as `info version`. + ++*info procs ?-all?* ?'pattern'?+:: + Returns a list containing the names of Tcl command procedures. + See `info commands` for the meaning of +*-all*+ and +'pattern'+. +*info references*+:: Returns a list of all references which have not yet been garbage @@ -2997,6 +3075,14 @@ The legal +'option'+'s (which may be abbreviated) are: procedure. An empty dictionary is returned if the procedure has no static variables. ++*info tainted* 'str'+:: + Returns 1 if the value is tainted, or 0 if not. + ++*info usage* 'command'+:: + Returns the usage for the given command. For Tcl command procedures, this is based + on the arguments defined for the procedure. For a C command, this is the command usage + that was specificied when the command was registered. + +*info version*+:: Returns the version number for this version of Jim in the form +*x.yy*+. @@ -3091,6 +3177,63 @@ than variables, a list of unassigned elements is returned. a=1,b=2 ---- +lsubst +~~~~ ++*lsubst ?-line?* 'string'+ + +This command is similar to `list` in that it creates a list, but uses +the same rules as scripts when constructing the elements of the list. +It is somewhat similar to `subst` except it produces a list instead of a string. + +This means that variables are substituted, commands are evaluated, backslashes are +interpreted, the expansion operator is applied and comments are skipped. + +Consider the following example. + +--- + set x 1 + set y {2 3} + set z 3 + lsubst { + # This is a list with interpolation + $x; # The x variable + {*}$y; # The y variable expanded + [string cat a b c]; # A command + {*}[list 4 5]; # A list expanded into multiple elements + "$z$z"; # A string with interpolation + } +--- + +The result of `lsubst` is the following list with 7 elements. + +--- + 1 2 3 abc 4 5 33 +--- + +This is particularly useful when constructing a list (or dict) +as a data structure as it easily allows for comments and variable and command +substitution. + +Sometimes it is useful to return each "command" as a separate list rather than +simply running all the words together. This can be accomplished with `lsubst -line`. + +Consider the following example. + +--- + lsubst -line { + # two "lines" because of the semicolon + one a; two b + # one line with three elements + {*}{a b c} + } +--- + +The result of `lsubst -line` is the following list with 3 elements, one for each "command". + +--- +{one a} {two b} {a b c} +--- + local ~~~~~ +*local* 'cmd ?arg\...?'+ @@ -3122,16 +3265,13 @@ continues to have global scope while it is active. ---- In this example, the lambda is deleted at the end of the procedure rather -than waiting until garbage collection. +than waiting until garbage collection. Note that `local` returns the command name. ---- proc outer {} { - set x [lambda inner {args} { + set x [local lambda {args} { # will be deleted when 'outer' exits }] - # Use 'function' here which simply returns $x - local function $x - $x ... ... } @@ -3620,6 +3760,8 @@ by the command. If read-only access is used (e.g. +'access'+ is r), standard input for the pipeline is taken from the current standard input unless overridden by the command. +Note that this incudes new style exec syntax, e.g. +'open |[list | ls -l] r'+. + The `pid` command may be used to return the process ids of the commands forming the command pipeline. @@ -3627,38 +3769,34 @@ See also `socket`, `pid`, `exec` package ~~~~~~~ -+*package forget* '?name ...?'+ - ++*package forget* '?name ...?'+:: Removes the knowledge that the given packages were loaded. This allows new, replacement packages to be loaded. Note that it does not remove any effects of the previous packages being loaded. -+*package provide* 'name ?version?'+ - ++*package provide* 'name ?version?'+:: Indicates that the current script provides the package named +'name'+. *Note*: The supplied version is ignored. All packages are registered as version 1.0 (it is simply accepted for compatibility purposes). - + :: Any script that provides a package may include this statement as the first statement, although it is not required. -+*package require* 'name ?version?'+ - ++*package require* 'name ?version?'+:: Searches for the package with the given +'name'+ by examining each path in '$::auto_path' and trying to load '$path/$name.so' as a dynamic extension, or '$path/$name.tcl' as a script package. - + :: The first such file which is found is considered to provide the package. (The version number is ignored). - + :: If '$name.so' exists, it is loaded with the `load` command, otherwise if '$name.tcl' exists it is loaded with the `source` command. - + :: If `load` or `source` fails, `package require` will fail immediately. No further attempt will be made to locate the file. -+*package names*+ - ++*package names*+:: Returns a list of all known/loaded packages, including internal packages. pid @@ -3759,7 +3897,7 @@ Integer parameters may be any integer expression. read ~~~~ -+*read ?-nonewline? 'fileId ?length?'+ ++*read* ?-nonewline? 'fileId ?length?'+ Tcl-compatible alterative version of +'fileId' *read ?-nonewline?* '?length?'+ @@ -3767,7 +3905,7 @@ See `aio read` regexp ~~~~~~ -+*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar \...?'+ ++*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?-expanded? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar \...?'+ Determines whether the regular expression +'exp'+ matches part or all of +'string'+ and returns 1 if it does, 0 if it doesn't. @@ -3840,13 +3978,17 @@ The following switches modify the behaviour of +'regexp'+ data, plus one element for each subexpression in the regular expression. ++*-expanded*+:: + Enables use of the expanded regular expression syntax where whitespace + and comments are ignored. + +*--*+:: Marks the end of switches. The argument following this one will be treated as +'exp'+ even if it starts with a +-+. regsub ~~~~~~ -+*regsub ?-nocase? ?-all? ?-line? ?-command? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+ ++*regsub ?-nocase? ?-all? ?-line? ?-command? ?-expanded? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+ This command matches the regular expression +'exp'+ against +'string'+ using the rules described in REGULAR EXPRESSIONS @@ -3928,6 +4070,10 @@ The following switches modify the behaviour of +'regsub'+ start matching the regular expression. +'offset'+ will be constrained to the bounds of the input string. ++*-expanded*+:: + Enables use of the expanded regular expression syntax where whitespace + and comments are ignored. + +*--*+:: Marks the end of switches. The argument following this one will be treated as +'exp'+ even if it starts with a +-+. @@ -4418,6 +4564,9 @@ For example, if +-nocommands+ is specified, no command substitution is performed: open and close brackets are treated as ordinary characters with no special interpretation. +*Note*: `expr` shorthand +$(\...)+ is considered a variable substitution +and so is disabled by +-novariables+. + *Note*: when it performs its substitutions, subst does not give any special treatment to double quotes or curly braces. For example, the following script returns +xyz \{44\}+, not +xyz \{$a\}+. @@ -4543,6 +4692,12 @@ The following are identical except the first immediately replaces the current ca proc sub_cmd2 ... ---- +taint +~~~~~ ++*taint* 'varname'+ + +Set "taint" on the value contained in the given variable. + tell ~~~~ +*tell* 'fileId'+ @@ -4709,6 +4864,12 @@ An error occurs if any of the variables doesn't exist, unless '-nocomplain' is specified. The '--' argument may be specified to stop option processing in case the variable name may be '-nocomplain'. +untaint +~~~~~~~ ++*untaint* 'varname'+ + +Remove "taint" from the value contained in the given variable. + upcall ~~~~~~~ +*upcall* 'command ?args ...?'+ @@ -4889,8 +5050,8 @@ what options were selected when Jim Tcl was built. [[cmd_1]] -posix: os.fork, os.gethostname, os.getids, os.uptime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +posix: os.fork, os.gethostname, os.getids, os.uptime, os.umask +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +*os.fork*+:: Invokes 'fork(2)' and returns the result. @@ -4905,6 +5066,9 @@ posix: os.fork, os.gethostname, os.getids, os.uptime uid 1000 euid 1000 gid 100 egid 100 ---- ++*os.umask* ?newmask?+:: + Set or return the current process 'umask(2)'. Returns the previous umask. + +*os.uptime*+:: Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'. @@ -5122,6 +5286,15 @@ This command returns an empty string. will be returned instead. Although this is designed for normal files and those should be used in blocking mode. ++$handle *taint source|sink ?0:n?*+:: + Sets the taint characteristics of the channel. Data read from + the channel will have a taint value as set by +'source'+, while + a check will be made against data written to the channel against + the +'sink'+ value. If the taint of the data and the channel + match, the operation will fail. By default, channels created + by `open` are not tainted while channels created by `socket` + have both set to 1. + +$handle *tell*+:: Returns the current seek position or -1 if the channel is not seekable. @@ -5298,14 +5471,16 @@ Time-based execution is also available via the eventloop API. the type of the event. An error occurs if +'id'+ does not match an event. -+*vwait ?-signal?* 'variable'+:: ++*vwait ?-signal?* 'variable' ?script?+:: A call to `vwait` enters the eventloop. `vwait` processes events until the named (global) variable changes or all event handlers are removed. The variable need not exist beforehand. If there are no event handlers defined, `vwait` - returns immediately. If +'-signal'+ is specified, `vwait` will + returns immediately. If +*-signal*+ is specified, `vwait` will also quit if a handled signal occurs. In this case, `signal check -clear` - can be used to check for the signal that occurred. + can be used to check for the signal that occurred. If +'script'+ is given + it is evaluated after each event. If it returns break, `vwait` returns. + `vwait` also returns with an error if the script returns an error. +*update ?idletasks?*+:: A call to `update` enters the eventloop to process expired events, but |