Welcome to Ticol Tcl Interpreter (C) M Shaw 2010-2018
 _______          __         ___  ___  ____
/_  __(_)______  / / _  __  <  / |_  |/ __/
 / / / / __/ _ \/ / | |/ /  / / / __// _ \ 
/_/ /_/\__/\___/_/  |___/  /_(_)____/\___/
See any associated README.TXT for latest updates and amendments

 ---------------------------------------------------------------------------
  Ticol Copyright and Licence
 ---------------------------------------------------------------------------
  Copyright (C) to M Shaw 2010-2018
  All rights reserved.
  Portions Copyright (c) 2007-2016, Salvatore Sanfilippo
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:

  1 Redistributions of source code must retain the above copyright notice,
    this list of conditions and the following disclaimer.
  2 Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution
  3 This product and its associated documentation may not be sold or
    resold for profit
  4 This licence does not extend to the Ticol Tcl manual
    The Ticol Tcl manual, associated documentation and sample scripts
    are not included in this licence but are covered separately by the
    standard international author copyright for literary works
      Copyright (C) M Shaw (2015-2018)
      All rights are reserved
  
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Acknowledgements are made for the following code:

  ticol_zip plugin, portions
    Copyright (c) 1990-1999 Info-ZIP.  All rights reserved
    The plugin library is not supplied by Info-ZIP

  ticol_sqlite plugin, portions
    Copyright attributed to SQLite (Public Domain)

  MD5 Algorithm: RSA Data Security, Inc. MD5 Message-Digest Algorithm
    Copyright (C) 1991-2, RSA Data Security, Inc. 1991.
    All rights reserved

  Mersenne Twister Random Number Generator
    Copyright(C) 1997-2002, Makoto Matsumoto, Takuji Nishimura

  TCP/IP specific extensions in Windows Sockets 2
    Copyright(C) 1980,1983,1988,1993
    The Regents of the University of California
 

Ticol Manual Index

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | 

$ dereference
$$ double-dereference (multi-dereference)
$this
<< >> Bit shift (64-bit)
-> and => (struct or class dereference)
:: Double-colon (Scope symbol)
addressofb, strptr (Binary Buffer Address)
addslash
after, every (script)
alias
Alphabetic Index of Built-In Ticol Commands
ANSI (American National Standard for Information) - Unicode Support
append
apply
args  (proc variable or command)
Argument Expansion
argv and argc
arity
ARP Address Resolution Protocol and RARP (Reverse ARP) Plugin
array - Tcl Array Commands
array append
array create
array exists
array find (Reverse array lookup)
array foreach
array get
array is_set
array item
array list
array list
array names
array set
array size
array sort
array statistics
array trim
array unset
array walk
array_to_list
asc
assert
Associative arrays
at_exit
atof, ftoa
autoexec
autoexec.tcl
base64
baseconv, convbase
BEDMAS/BOMDAS (Math Operator Precedence)
beep
binary (Experimental binary command)
bintoint, inttobin
bit
bool (boolean value)
box
Braces {} (Grouping) and Brace Style
break
calc - Auto-optimising alternative to [expr]
call
calldll examples
calldllstr, calldllstr_cdecl
carray plugin
catch
ceil
CGI Application Back-End Configuration
CGI Script Debugging
Chaining Tcl Commands
charcount
chartok
chdir
chomp
chr
Class Example
clear
clearprocs
clipboard
clock
clock format
clock scan
Clock Scan Workaround
clock split
close, file close
cls
cmdcount (Command Count)
cmp (Compare)
Code Highlighting Plugin
Colour Constants
comma
Command Line Prompt String
commands
Comments
Comparing Ticol/Tcl With PHP
Complex Nested Dereferences
concat
Conditional Operator - ?:
console
Console Colours
const
continue
Control+C (break)
Conversion Routines - mkn, cvn
copyfile
cset
ctime (Unix time)
ctime_to_double, double_to_ctime
Data Structures
Data Type Ranges
date
date_to_ctime
dateserial
day_of_week
debug
Debugging Ticol
Decimal to Roman Conversion Plugin
decrypt
default
defined
dict (Dictionaries) (Incomplete feature)
dict exists
die
Differences between Ticol and Standard Tcl
dim
Disambiguity: sort
diskfree
disktype
dll_close
dll_close
dll_open
do while, do until (Flow Control)
doevents
Double Quotes
dump
dumpvariant
Easter Egg
echo
elevate
Embedded TCX Plugin
Embedding Ticol Tcl in C++ Programs
encrypt
enum
error
Error Codes
escape
eval
Examples
Exception Handling
exec
Executable-Only Code Obfuscation (ticol.exe filename /c)
exit
Experimental @> Command
explain
expr
Expression Functions
External DLL Link Plugin - calldll*, calldll*_cdecl
fib (Fibonacci)
file
file exists
file gets
file pathcount
file stat
filesize
find (Help)
Flow-control: for foreach array_foreach, if elseif else, switch while do
flush
for (Flow Control)
foreach (Flow Control)
Form Input
format
Format String (printf and format)
fpart
fraction and integral
funct
Function Arity
functions
get_fileopen, get_filesave
get_folder
get_win_error
getcwd, pwd
getenv
getkey
gets
getsid
Getting User Input
glob
global
Global Variables
gosub, sub
goto_block, goto
gotoxy
Handling filenames and paths
Hash Tables
hasp - Ticol Hasp HL Plugin
help topic
Hex Routines
html chomp_tag (Plugin)
html header_field (Plugin)
html remove_header (Plugin)
html strip (Plugin)
http
if..elseif..else (Flow Control)
in, ni
Include files
incr, decr, ++, --
index
info
info args
info cmdcount
info exists
info level
info vars
info winver
INI Handling Plugin
inkey
input
input_csv
inputbox
instr, rinstr, strstr, strstrr
int, double (Type Casting)
inttooct, octtoint
ip_to_long, long_to_ip
is_*
is_admin
is_array
is_command
is_const
is_date
is_dir
is_dst
is_elevated
is_empty
is_file
is_leapyear
is_list
is_mod
is_numeric
is_pointer
is_proc
is_set
item (array, stack or struct)
join
json_to_list (JSON Conversion Plugin)
K Combinator
key input routine
Known Bugs and Feature Anomalies
Lambda Example
lappend
lassign
lastchar
lcount
ldepth (proc)
left, string left
len
let (Assignment command)
lib (Ticol Plugin Module Extension Loader)
lib interface specifications
lindex
Line Continuation Character
Line Numbers
link_to_path
Linked List Plugin
list
List Processing Commands
list_to_array
Listing Files
llength
lmap
load
logo
loop (Flow Control)
lrand
lrange
lreverse
ls
lsearch
lset
lsort
Macro #if #exec #echo
Macro Constants
Macro Escape Sequences
makestr
malloc, free
man - Ticol Manual
map, string map
Math Expressions
Math Operators
max, min (Command form)
md5
MD5 Batch Example
MD5 Verification
md5_file
mean
mem_used
memcpy
memset
mid (Set String Middle)
mids (Return a String Midsection)
Miscellaneous Routines Plugin
mkdir
mkdirs
Modulo Sign (Discussion)
movefile
msgbox
Multi Line Commands
Multiple Commands
Namespaces and Scope
Networking Commands
new
newline
Non-Decimal Numbers
not (Bitwise and Logical)
now
Number Formats
ofaddress, addressof (Tcl Variable Address)
ofaddressb (Binary Buffer from Address)
open, file open
option  (Runtime Configuration Options)
option breakpoint, halt, resume
Passing Structs to a Procedure By Name
Passing Variables to Procedures by Name (by Reference)
Passing Variables to Procedures by Value
pause
Performance Example
Performance Graph
pid, tid  (Process and Thread ID)
play_wav, stop_wav
pointers
Preset Global Variables and Constants
Print Functions
printf
proc (Tcl Procedures)
proc args ($args) (See also args for the command)
procs (info procs) ?glob-pattern?
puts
qbf
randomstr
range
read
readfile
Recursion and Issues Arising
regex
rename
replacechar
reserved variables
return
Returning Struct Variables from Procedures
rewind
right, string right
rlm - An RLM Licence Query Plugin
rnd
round
rset
RTF Output Plugin
run - (Run a Ticol Tcl script)
Running Scripts
scan
screen
Security
seek
semi-colon
set
setat
setb, struct setb
setenv
setresult
sgn
Shortcut Math Operators
Single Line Commands
Single Quotes
sizeof
sleep
spawn
split
sql
stack
Stack Examples
static (static variables in Ticol)
stop
store
string
String Comparison Operators
string equal
String Functions
string index
string is_alpha, string is_alnum
string isempty
string match
string range
string replace
string slice
string to_wchar
string toarray
string tolower, string toupper, tolower, toupper
stripto
striptor
strsplit
strto, strtor
strtok
struct
struct clear
struct copy
struct create
struct dump
struct elements
struct elements
Struct Implementation Details
struct item
struct set
struct setb
struct size
struct unset
subst
swap
switch (Flow Control)
Syntax Checking (Static)
sysfree
Tcl Arrays
Tcl Callbacks
Tcl Commands
TCL History
Tcl Lists
Tcl Programming Idioms
Tcl Semantics
Tcl Strings
Tcl Syntax
TCP/IP and Networking Functionality
tell
textcolor
The Tcl Language
ticks
Ticol Big Integer Math Plugin
Ticol Bitmap Encoding Plugin
Ticol CGI Web Plugin
Ticol Command Line
Ticol Command Line Arguments
Ticol Command Line Interpreter (CLI)
Ticol Commands Grouped by Functionality
Ticol Compatibility with Standard Tcl
Ticol Copyright and Licensing
Ticol CPU Information Plugin
Ticol CRC32 Plugin
Ticol Design and Picol Design Changes
Ticol Design Goals
Ticol DHCP Plugin (Simple DHCP commands)
Ticol DNS Plugin (Simple DNS / Reverse DNS lookups)
Ticol Editor and Recommended IDE
Ticol Errors
Ticol FAQ - Frequently Asked Questions
Ticol FTP Plugin (Simple FTP Client)
Ticol Hints and Tips
Ticol HTML Plugin
Ticol ICMP Ping Plugin
Ticol Introspection and Reflection
Ticol is a Tcl interpreter, not a compiler!
Ticol line - Line Processing Plugin
Ticol Macro PreProcessor (MPP)
Ticol Macro PreProcessor (MPP)
Ticol Memory Allocation and Garbage-Collection
Ticol Network Drive Map Plugin
Ticol Performance and Efficiency
Ticol Plugins
Ticol Random File Database Plugin
Ticol Registry Plugin (ANSI)
Ticol Scientific Format Number Plugin
Ticol SMTP Mail Plugin
Ticol Tcl - Copyright (C) M Shaw 2010-2018
Ticol Tcl architecture
Ticol Tcl Interpreter for Windows
Ticol TCP Socket Ping Plugin
Ticol Variables
Ticol Variant - A Simple Variant Handling Plugin
Ticol Windows Event Log Handling Plugin
Ticol Windows Service Query Plugin
Ticol Wordcount Plugin
Ticol Workarounds
Ticol XBase - A Simple Dbase III/IV Plugin
Ticol ZIP Plugin
Ticol-Specific, Non Standard Tcl Commands
ticol.ini - Configuration file for Ticol.exe
time
timer
Tips for Writing Big Programs
tk Support
tohex, fromhex
Towers of Hanoi
trace
trim, trimleft, trimright, string trimleft - string trimright
trimprefix
trimsuffix
Troubleshooting and Common Mistakes
try ... catch (Flow Control)
type
UNC Path Handling
undef
undef command (Undefining Commands)
unescape
unknown (proc)
unlink
unset
unwrap (proc)
uplevel
upvar
urlencode, urldecode
Useful Commands
Useful Debug Routines
Using [upvar] with Structs
Using Logical and/or Within Flow-Control Statements
Using Ticol With Batch Files
variable
Variable Casting
Variant Array Functions (Plugin)
varray count (Plugin)
varray get (Plugin)
varray lbound (Plugin)
varray ubound (Plugin)
vars
VB (Visual BASIC) Time
vsplit (Plugin)
vwait (Requires threaded compile of Ticol)
walk
watch
wchar_length
wchar_to_string
while (Flow Control)
White Space
Why I Wrote Ticol Tcl?
win_error
Windows Dialogs
wrap
wrap example script
writefile


Ticol Tcl - Copyright (C) M Shaw 2010-2018  Top  
_______ __ ___ ___ ____ /_ __(_)______ / / _ __ < / |_ |/ __/ / / / / __/ _ \/ / | |/ / / / / __// _ \ /_/ /_/\__/\___/_/ |___/ /_(_)____/\___/ See any associated README.TXT for latest updates and amendments Type the following: help <command> for help on a particular command, e.g. help contents help commands help debugging help functions help flow control help macro help math help performance help ticol help variables autoexec on or off to enable automatic execution of unknown commands commands for a list of commands vars for a list of variables (vars -const for a list of consts) exec ticol /? for command-line help spawn run a program with redirected output <command> for a Windows command exit to exit the interpreter shell http://kerys.co.uk/ticol See also: ticol, tcl, autoexec, commands, exec, flow control, macro, math, vars, load, script, run, commands by function, faq
Alphabetic Index of Built-In Ticol Commands  Top  
Code used to generate this list: foreach x [commands] { puts $x } puts "[lcount [commands]] commands" Count the commands using: puts [lcount [commands]] Redirect to a file in Windows using: ticol.exe ; "foreach x [commands] {puts $x}" /na > cmdlist.txt $ ${} :: ! != % & && &= * ** *= + ++ += - -- -= / /= < << <= == > >= >> ? @ K ^ ^= add addressof addressofb addslash after alias append apply args arity array array_foreach array_set asc assert at_exit atof autoexec base64 baseconv beep binary bintoint bool box bit break calc call carray catch cd cd.. ceil cgi char charcount chdir chomp chr clear clearprocs clipboard clock close cls cmdcount cmp comma commands concat console const continue convbase copyfile cpu cset ctime_to_double cvn date date_to_ctime day_of_week debug dec decr decrypt defined dict die dim diskfree disktype div do while do until doevents double double_to_ctime dummy dump dumpvariant echo elevate encrypt enum eof eq eqi eqn error escape eval event exec exit expand explain expr false fib file filesize find float flush for foreach format fpart fraction fromhex funct functions ge gei get_folder get_win_error getcwd getenv get_fileopen get_filesave getkey gets getsid glob global gosub goto goto_block gotoxy gpf gt gti halt help hextoint highlight hostname html http if in incr index info inkey input input_csv inputbox instr int integral inttobin inttohex inttooct ip_to_long is_admin is_command is_const is_date is_dir is_dst is_elevated is_file is_leapyear is_list is_mod is_numeric is_pointer is_proc is_set join json_to_list lappend lassign lastchar lcount le left lei len let level lib lindex link_to_path linkedlist list list_to_array llength lmap load logo long long_to_ip loop lrand lrange ls lsearch lset lsort lt lti makestr man map max md md5 md5_file mean mem_used memset mid mids min mkdir mkdirs mkn mod movefile msgbox mul ne nei new newline ni normal_path now null octtoint ofaddress ofaddressb open option pause pid play_wav printf proc procs put puts pwd rainbow randomstr range read readfile ren rename replacechar resume return rewind right rinstr rnd rot13 round rset run scan sci screen set setat setb setenv setresult shell short signed sizeof sleep slice sockping source spawn split srand stack static stop stop_wav store string stripto striptor strptr strsplit strstr strstrr strto strtok strtor struct sub subst swap switch sysfree tell test textcolor textcolour ticks time timer tohex tokenise trace trimprefix trimsuffix true try type undef unescape unlink unset unsigned unwrap uplevel upvar urldecode urlencode username variable varray vars volume vsplit vwait walk wallpaper watch wchar_length wchar_to_string while wide win_error wordcount wrap writefile | |= || ~ See also: commands by function, Ticol, Tcl, faq
Ticol Commands Grouped by Functionality  Top  
Data Types and Type Manipulation Relational: > < >= <= == != array array_to_list array_foreach array_set base64 bit carray const convbase ctime_to_double cvf cvi dict dim enum eq eqi eqn escape fromhex ge gei global gt gti hextoint inttobin inttohex inttooct is_const is_mod is_numeric is_proc is_set json_to_list le lei let lei let list_to_array linkedlist (Linked list plugin) long long_to_ip le lt lti map mkf mki ne nei new null octtoint rtf (RTF plugin) set short signed sizeof stack static subst swap tohex type unset unsigned variable varray vsplit wchar_length wchar_to_string wide Database db (Ticol DB plugin) sql (SQLite plugin) xbase (DBase 3/4 plugin) Date and Time clock ctime_to_double date date_to_ctime day_of_week double_to_ctime is_date is_dst is_leapyear ticks time timer now Debugging assert catch debug dump dumpvariant halt resume time trace try vars walk watch DLL and Struct Interface -> Dereference a struct field => Set (assign) a struct field value =>> Dereference then evaluate addressof addressofb class new ofaddress ofaddressb setb strptr struct Encryption, Compression, Randomness and MD5 crc (CRC plugin) decrypt encrypt file_crc (CRC plugin) md5 md5_file randomstr rle (RLE plugin) rnd rot13 (Misc plugin) srand zip (ZIP plugin) File and Disk and I/O addslash cd cd.. chdir close copyfile diskfree disktype eof file filesize flush getcwd get_fileopen get_filesave glob ini (INI Plugin) input_csv is_dir is_file link_to_path ls md mkdir mkdirs movefile normal_path open pwd read readfile ren rename rewind tell unlink volume writefile Flow Control {*} after arity at_exit break call catch clear clearprocs continue defined die do while do until doevents error exit expand for foreach funct gosub goto goto_block halt if is_proc level loop proc procs resume return sleep stop sub switch try undef uplevel upvar vwait while Event Handling (Threaded compile of Ticol) after vwait every (script) at (script) HTML and Internet cgi (Plugin) html (Plugin) http urldecode urlencode Information and Environment cpu info is_admin is_command is_elevated is_pointer $tcl_date $tcl_config $tcl_cli $tcl_threaded $tcl_version $tcl_precision $env $argc $argv $win64 List Handling apply array_to_list in is_list lappend lassign lcount lindex linkedlist (Plugin) lappend lassign lcount list list_to_array llength lmap lrand lrange lsearch lset lsort unwrap ni Logic Logical and/or &&, || Bitwise and/or &, | Logical not ! Bitwise not ~ Combined: &=, |= bool false ($::false) true ($::true) xor Macro #echo #else #endif #exec #exit #if #ifdef #ifndef #undef Math Bitshift: << >> Increment: ++ Decrement: -- Combinational: +=, -=, *=, /=, ^= atof baseconv big (big number plugin) binary bintoint calc ceil dec decr div double eval explain expr fib float fpart fraction incr int integral Math operators: + - * / ** ^ % max mean min mod mul round sci unescape Memory free malloc memcpy memset store Network arp (ARP plugin) cidr_match (Misc plugin) dns (DNS plugin) ftp (FTP plugin) hostname ip_from_host (Ping plugin) ip_match (Misc plugin) ip_to_long is_mac (Misc plugin) ping (Ping plugin) rarp (ARP plugin) sendmail (SMTP mail plugin) sockping (Socket ping plugin) Program Execution alias args autoexec cmdcount commands dump functions lib load option run source String add append asc char chr chomp cmp comma concat cset index instr join lastchar left makestr memset mid mids range replacechar right rinstr rset scan setat slice split string stripto striptor strsplit strstr strstrr strto strtok strtor trimprefix trimsuffix wordcount wrap User interaction and Display beep box cls echo find format get_folder get_fileopen get_filesave getkey gets gotoxy help inkey input inputbox logo man msgbox newline pause printf puts rainbow screen textcolor textcolour Windows System Interaction clipboard console elevate event exec get_win_error getenv getsid info mem_used pid play_wav reg (registry plugin) setenv shell spawn stop_wav sysfree username wallpaper win_error See also: command list, Ticol, Tcl, faq
:: Double-colon (Scope symbol)  Top  
The double-colon symbol operates in a similar way to that found in C/C++ ::varname represents a variable in global (root) scope $::varname represents a dereferenced variable in global (root) scope Ticol Tcl does not support operational namespaces but can emulate them by allowing for the inclusion of pseudo-namespace prefixes such as... namespace::varname or $namespace::varname Example: In Tcl, unlike other programming languages, variables do not "inherit" into procedures from higher-scope. Globals are visible if addressed using a double colon prefix... set s "Hello world" proc foo {} { set s "Goodbye cruel" # Declare a conflicting variable 's' puts $::s # Reference the global variable 's' } Result: Hello world For partial/embedded substitution, a variable name prefix may be isolated and forced by wrapping in curly braces. So to replace a variable placeholder which references a pseudo-namespace you would use, for example (where q holds the pseudo-namespace value) ${q}::varname This causes $q to be evaluated in preference to $q::varname See also: variables, dereference, set, namespace, global
Ticol Tcl architecture  Top  
This is a simplified block diagram of the unthreaded Ticol Tcl architecture +--+----------------------------------------------------------+ | 9| Tcl Command Line Interpreter (CLI) | EXE Command Line | +--+---------------------------+------------------------------+ | 8| tcl script | tcx script | |--| |------------------------------+ | 7| | Obfuscation Decoder/Encoder | +--+---------------------------+------------------------------+ | 6| Macro Preprocessor (MPP) | +--+----------------------------------------------------------+ | 5| Registered commands, [proc] registration, [undef] | +--+---------------------------+------------------------------+ | 4| [proc] | Known Tcl commands | +--+---------------------------+------------------------------+ | 3| [eval] | +--+---------------------------+------------------------------+ | 2| Tcl Parser | Registered [lib] commands | | | | [lib calldlll] | +--+---------------------------+------------------------------+ | 1| ticol.exe binary | External DLLs | +--+---------------------------+------------------------------+ The CLI or ticol.exe command line load plaintext or obfuscated scripts These are processed before execution by the Macro Preprocessor (MPP). The resulting script content may register [proc] instances and interact with any registered command The Macro PreProcessor (MPP) performs a number of tasks, including stripping out comment lines, processing the macro language and optimising [calc] expressions as well as performing basic sanity checks on the script All commands are evaluated internally by the internal 'eval' function which may also be called directly using [eval]. Eval parses the script content and breaks it up into commands and arguments. The [lib] command can load exported Tcl commands into the root namespace where they may be called the same as any other command (See: lib interface) See also: Ticol, Tcl, lib, Ticol, lib interface
Argument Expansion  Top  
{*} - Argument Expansion Operator expand - Argument Expansion Command command {*}{word ?word...?} string [expand command string...] Translates a list into an argument array for a single command Makes each item in a list an individual argument of the current command. CAUTION: This is an experimental feature. Use with care! If a word is prefixed with {*} followed by a non-whitespace character then the leading {*} prefix is discarded and the rest of the word is parsed and substituted as for any normal Tcl word. (Word here is analogous to a parameter or argument). The substitution process is equivalent to calling [subst] After substitution is complete, the word is then parsed as a Tcl list without command or variable substitutions. Backslash substitutions are performed as is normal for a list and individual internal words may be surrounded by either braces or double-quote characters. Its words are then added as individual arguments to the command being substituted It is not possible to expand a variable as the expansion prefix is resolved before variables. However, you can use the [expand] command Note that [eval] will also be able to resolve the task in most cases {*} is typically required with chained commands where the outer command requires separate arguments but the inner one returns a string The [dummy] command is useful for tracing results of {*} set s "puts {Hello world}" # This is will not work as {*} is processed before $s {*}$s # This will work as expected. {*} is delayed till after $s expand $s Be extremely cautious not to accidentally use an unquoted "{*}" string within your code where you do not intend it to expand arguments. e.g. don't use... puts [unescape "[string repeat 80 {*}]\\highlight0\\cf0\\par "] as this will attempt to expand within the nested call to [string repeat] and will lead to impossible to debug errors Supplying a whitespace character (tab or space) after {*} is unlawful For instance: cmd a {*}{b [c]} d {*}{$e f {g h}} is equivalent to supplying: cmd a b {[c]} d {$e} f {g h} And results in the effective arguments: a b {[c]} d {$e} f g h being passed to a command Example: set a "puts {Hello world}" # Set var to a command with args $a # Error: Bad attempt to dereference {*}$a # Correct method of dereferencing eval $a # This works just as well, however eval {$a} # Results in an error Results puts' is not recognized as an internal or external command ... Hello world Hello world puts' is not recognized as an internal or external command ... Example: # Unset all variables 'a' to 'z' (supplying individual arguments) unset {*}[split [range a-z]] -nocomplain # This works just as well expand "unset [split [range a-z]] -nocomplain" # So does this eval "unset [split [range a-z]] -nocomplain" Example: # Lambda like call with argument passed via [lmap] set square {lmap {x {expr $x * $x}}} # {*} will break string into separate arguments puts [{*}$square 42] # This also works just as well puts [eval "$square 42"] Result: 1764 1764 Example: set e {info exists} # {*} will break string into separate arguments puts [{*}$e a] assert [{*}$e a] {== $_ 0} -v -line #__LINE__ set a Hello puts [{*}$e a] assert [{*}$e a] {== $_ 1} -v -line #__LINE__ # This also works just as well puts [expand "$e a"] Results: 0 1 1 Example: set args [list range foobar 2 4] puts [string {*}$args] # This works just as well puts [expand "string $args"] # And so does this... puts [eval "string $args"] Example: Set script literal via 'command list' [...list...] and execute variable contents set q "puts {1 2 3 4}" # Or set q {puts {1 2 3 4}} {*}$q Results: 1 2 3 4 See: http://wiki.tcl.tk/17158 http://wiki.tcl.tk/19707 See also: subst
semi-colon  Top  
A semi-colon is used as a punctuator between groups of statements It marks the absolute end of a command list and acts equivalent to a newline character. Example: set a 0;puts "hello";incr a;puts "a is $a" # Is equivalent to set a 0 puts "hello" incr a puts "a is $a" Result: hello a is 1 Statements which require to pass multiple commands as a single argument must be braced, thus: some-command {arg1; arg2; arg3} otherwise the command string will be interpreted as: some-command arg1 arg2 arg3 This should be particularly noted with commands which take a script element as an argument such as [after] Command Line Use: A semi-colon may also be used as the first argument to ticol.exe to specify a "dummy" script file which is never executed. If specified then any remaining arguments will be evaluated by the Ticol Command line Interpreter (CLI) within the same interpreter instance Example Command Line: ticol.exe ; "set a 0;puts hello;incr a;puts \"a is $a\"" Result: hello a is 1 Example: ticol.exe ; "puts \"Hello\tworld\"" Result: Hello world See also: syntax, Tcl
addslash  Top  
addslash varname -var string [addslash string] Conditionally append a path separation character (slash) to a path string The backslash character in the string will be escaped Examples: puts [addslash C:] puts [addslash .] puts [addslash \\path\\to\\file] Results: C:\\ .\\ \\path\\to\\file\\ See also: file, info
ofaddress, addressof (Tcl Variable Address)  Top  
integer [addressof variable] string [ofaddress pointer-variable|address-literal-value -string] [addressof] returns the address of a standard Tcl variable object (not the variable's data buffer) and stores it as a string record of that address. [ofaddress] performs the inverse operation. The two functions are provides for use in conjunction with calldll and calldll_cdecl Both commands are for use with [calldll*] only, and it is strongly advised that Ticol variables are not manipulated using these commands [addressof] [addressofb],[set],[$] # Get address | | v v +---------------------+ +---------------------+ | Tcl Variable Object | -> | Variable Data Block | +---------------------+ +---------------------+ | | v v [ofaddress] [ofaddressb] # Dereference Where a variable is passed to [ofaddress], the address stored in the internal buffer is dereferenced and the result is returned. Where an integer literal is passed to [ofaddress], the value is assumed to be an address and it is dereferenced back to a buffer address By comparison with C/C++, [addressofb] returns the equivalent of LPSTR* or LPPSTR (char**) If a string value is being dereferenced the '-string' argument is required, otherwise the string may be truncated. Note that you cannot evaluate [ofaddress "literal-string"] Such a value must be an integer pointer variable address value returned by [addressof] To return a string from pointer value set by [struct setb var] use: [ofaddress $var] To return string as char array use: [ofaddress var] When using [calldll*] the address of a Tcl variable buffer/string pointer by value may be passed by using [addressofb variable] to pass the literal string address (LPSTR). strptr is an alias for addressofb For Ticol structs, member values refer to an offset in the struct data block: struct s {a 5 b 10 c 20} Tcl var Address Struct byte offset ----------------------------------------------------- s => 32542464 (0x1f08f00) 0 s.a => 32542464 (0x1f08f00) 0 s.b => 32542469 (0x1f08f05) 5 s.c => 32542479 (0x1f08f0f) 15 In the above example, both $s and $s.a is 32542464, $s.b is 32542469 etc. [addressof] and [ofaddress] are useful for assigning values to structs where the size of the value to be stored is unknown. In such cases we can store the variable address provided the variable is not reassigned. See also: setb, ofaddressb, calldll, calldll_cdecl, struct
addressofb, strptr (Binary Buffer Address)  Top  
integer [addressofb variable] string [strptr variable] Inverse of [ofaddressb] [addressofb] and [ofaddressb] are 'unsafe' Returns the address of the binary string buffer of a variable/string [addressofb] (or [strptr]) returns the equivalent of LPSTR or (char*) The command performs a similar function to VarPtr() in Visual BASIC [addressofb] is for use with [calldll*] only, and it is strongly advised that Ticol variables are not manipulated using this command [addressof] [addressofb],[set],[$] | | v v +---------------------+ +-----------------------+ | Tcl Variable Object | -> | Variable's Data Block | +---------------------+ +-----------------------+ | | v v [ofaddress] [ofaddressb] The [addressof] command, unlike [addressofb], returns the address of a Ticol variable as a numeric string which can be dereferenced back using ofaddress However, this does not point to the variable's string buffer and is not, therefore suitable to pass via a [calldll*] to a DLL. Instead, [addressofb] should be used to return the true string buffer address Example: set a Hello [addressof] [addressofb],[set],[$] | 34602704 | 34600096 v v +---------------------+ +-----------------------+ | a | -> | Hello | +---------------------+ +-----------------------+ | | v v [ofaddress 34602704] [ofaddressb 34600096] Hello Hello [addressofb] may be used to pass the address of a Tcl variable's string buffer to an external DLL where the contents will be recovered and used in your program. Care should be taken to avoid buffer overflows. It is preferable to use a struct when passing data to external DLLs [strptr] is a friendly alias for [addressofb] Retrieve 2 byte short value: [ofaddressb var 2] Retrieve 4 byte long value: [ofaddressb var 4] Retrieve 8 byte int64 value: [ofaddressb var 8] Retrieve 256 byte struct 's': [ofaddressb s 256] Example: set timeout 0 set datalen 64 set buf [makestr 16] # Create 16 byte buffer as Tcl variable # Call ping32.dll, passing the binary address of the Tcl buffer # data block, which will receive the return data calldll ping32 PingAPI google.com [addressofb buf]:4 datalen:2\ timeout:4 1000 puts $buf Result: 173.194.78.105 See also ofaddressb See also: addressof, ofaddress, ofaddressb, set, setb, calldll
ofaddressb (Binary Buffer from Address)  Top  
string [ofaddressb struct-variable ?byte-width?] Inverse of [addressofb] [addressofb] and [ofaddressb] are 'unsafe' Return a binary interpretation of data pointed to in a struct field by the struct-variable. Normally a string interpretation of the memory location is returned [ofaddressb] is for use with [calldll*] only, and it is strongly advised that Ticol variables are not manipulated using this command [addressof] [addressofb],[set],[$] | | v v +---------------------+ +-----------------------+ | Tcl Variable Object | -> | Variable's Data Block | +---------------------+ +-----------------------+ | | v v [ofaddress] [ofaddressb] This will usually be unprintable without using [tohex]. What is often required is to retrieve a literal numeric value written to memory by [struct setb] which is the inverse function. [ofaddress] could be used but that will simply map 'n' bytes from the given memory location On Windows Intel platforms the data is stored in inverted 'little endian' format (byte order is reversed) A byte-width can be specified but this will be rounded to 1,2,4 or 8 bits You must correctly supply the bit-width interpretation of the data to match the struct storage field definition. The default bit-width is 4 (a DWORD or 32-bit long) Example: (where field2 is defined as 8 bytes width) struct s {field 8} # Single-field struct struct setb s.field 123 # Set member field to 123 binary (0x7b) puts [ofaddressb s.field 8] # Retrieve and display Dump: 008f3440 00 00 00 00 00 00 00 00 - 00 00 00 7B 00 00 00 00 ...........{.... -- -- -- -- 00 00 00 7B Result: 123 Note: Literal integer values greater than the range of DWORD must be retrieved back using [ofaddressb <varname> 8] Example: struct setb foo.a 1234567890123456789 -value puts [ofaddressb foo.a 8] # Byte width of 8 is required Result: 1234567890123456789 See also: addressof, ofaddress, struct, struct setb, setb, calldll, calldll_cdecl
after, every (script)  Top  
after milliseconds command ?arg? ?arg...? after milliseconds {script} after milliseconds {run scriptfile} after milliseconds {eval scriptfile} Threaded Ticol versions *: after info after count Run a command after a given number of milliseconds For unthreaded releases of Ticol, processing will halt until the specified time-interval has elapsed. [after] is implemented as a simple time-delay (see notes below) For experimental, threaded releases of Ticol; [after] is event-driven and will run asynchronously with main scripts with separate [after] scripts interleaved The threaded version of Ticol multitasks at script rather than command- level. [after] and [run] lock mutually so [after] cannot launch either [after] or [run] whilst a script is in progress from either of these commands Interaction with scripts launched using [after] should be controlled using [vwait]. A continuously running script will typically block an [after] script. Consider rewriting scripts which need to run continually as an [every] proc which can be polled at intervals rather than run in a main script loop (see below) Extreme care should be taken to avoid scripts clashing, particularly with respect to common variables or procedures. Pseudo namespace variables may be used outside procs. Procs will have their own temporary namespace A proc return value can be passed to any variable which may then be used as a [vwait] control flag, thus: after 2500 {set vret [draw_logo yellow $cursor_yloc]} vwait vret [vwait] will suspend the current script until the named variable changes [after] events do not interact with the CLI as these run under a separate thread Note: Be careful to brace [after] arguments and not use: after 4000 set vret [foo] as the unbraced [foo] proc will be called before [after] and thus polled immediately Threaded versions can be detected via the const '::tcl_threaded' e.g. if {$tcl_threaded} { # Call some [after] code } Arguments will be concatenated with a space. Formatting and grouping may be maintained by wrapping arguments in braces Multiple commands may be specified by using an intervening semi-colon (;) An [every] command may be defined using a simple 4-line script (see below) An [at] command can be defined using an 11-line procedure Unthreaded Compile Example: # Unthreaded version example # Instructions are executed sequentially after a simple delay after 1000 box 3 3 20 10 - blue after 1000 load demo.tcl after 1000 run after 1000 puts {"hello world"} after 1000 {puts "hello there...";} {puts "How are you?"} after 1000 goto 10 after 2000 ping 127.0.0.1 Threaded Version Example (requires threaded compile of Ticol): proc every {ms code} { eval $code after $ms every $ms $code # Respawn } set done 0 set i 0 proc tick {} { ++ ::i if {> $::i 4} {set ::done 1} } every 1000 tick # Tick once per second vwait done puts "Finished ticking at $i" Results: Finished ticking at 5 Threaded Version Example (A simple 'DOS TSR-like' clock) # When run from the CLI the CLI will remain interactive proc every {ms code} { eval $code after $ms every $ms $code # Respawn } every 1000 { set x [screen curx] set y [screen cury] gotoxy 72 1 textcolor white blue; puts [time] -nonewline textcolor gotoxy $x $y } Threaded Compile Example (A useful Tcl [at] scheduler) # Be careful to avoid calling the Windows 'at' command if {! [defined at]} { proc at {time args} { global at_flag if {[>= [date $time] [fraction [date now]]] } { set dt [int [* 86400000 [- [date $time] \ [fraction [date now]]]]] } else { set dt [int [* 86400000 [- [+ [date $time] 1] \ [fraction [date now]]]]] } after $dt $args return [/ $dt 1000] # Convert ms to seconds } } at 23:59 {puts "The witching hour is nigh!"} * Threaded Ticol is currently experimental and unlikely to reach final release quality See also: vwait, time
Using Logical and/or Within Flow-Control Statements  Top  
Using with: 'option expression off' (forcing non-expression syntax): && || Will perform logical operations on arguments Arguments will be evaluated as true or false & | Will perform bitwise operations on arguments 0b10 | 0b01 == 3 # i.e. true 0b10 & 0b01 == 0 # i.e. false Note that sub-expression which are to be tested using logical and/or MUST be bracketed, e.g. ((22/7==3) and (12>1)) Example: if {[expr ($k != 4) && ($k != 6) && ($k != 9) && ($k != 11)]} { ... Due to the structure of the Tcl language, compound expressions with [if] command which use 'and' or 'or' may become complicated. You can either pass to an [expr] statement or wrap multiple bracketed statements as follows: if { [&& [statement1] [statement2] } { ... if { [|| [statement1] [statement2] } { ... if { [expr [statement1] || [statement2]] } { ... if { [expr [statement1] && [statement2]] } { ... Or you can use [option expression on] which will enable expressions for flow control structures. Commands presented in [] format are evaluated before the outer expression statement... if { [statement1] || [statement2] } { ... if { [statement1] && [statement2] } { ... option expression off for {set i 0} {< $i $adapter_count} {incr i} { set addr [info ip_address $i] if { [&& [ne $addr "0.0.0.0"] [ne $addr "127.0,0.1"]] } { set adapter $i break } } Example: # if $op is * and (a xor b) is -ve then option a else option b ... if {[eq $op *] && [^ [eq $a "-"] [eq $b "-"]] } { You may also nest 'if' statements to achieve the same effect as 'and' option expression off for {set i 0} {< $i $adapter_count} {incr i} { if { ne [info ip_address $i] "0.0.0.0"} { if { ne [info ip_address $i] "127.0,0.1"} { set adapter $i break } } } [if.. else] statements may be used to replicate 'or' constructs -- Using with: 'option expression on' or with [expr] Logical operators &&, || (and, or) are evaluated left-to-right Complex expressions using logical combination operators should be properly bracketed. e.g. 'if {(22/7)==3 && (12>1)} {puts yes} else {puts no}' Expressions may combine individual values, bitwise to yield a testable result: expr "1 || 2 || 4" You may still use bracketed 'eval' type expressions See also: if
ANSI (American National Standard for Information) - Unicode Support  Top  
Ticol is an ANSI only language. That is, extended/international characters, often called "Unicode", "Wide" or "Multi-byte" characters are not supported Non-Roman languages such as Chinese are not directly supported but data might be handled via external DLLs and using the [calldll] plugin Only the standard 8-bit ANSI character set from 0..255, including many international accented characters, is supported This is by design. Ticol is a personal hobby project with no requirement for non-Roman character sets Many other applications similarly lack Unicode/MBCS support e.g. Unix du.exe for Windows cannot handle Unicode path names See also: Ticol, why
alias  Top  
alias alias-name existing-command alias alias-name existing-proc Create an alias of a proc or command. The command or proc being aliased must exist and the alias must not exist An alias can be undefined using [undef] Example: alias fred puts fred "Hello world" Results: Hello world See also: undef, proc, commands
append  Top  
append variable value ?value? ... string [append variable value ?value? ... -return] Append a value or series of values to a variable. If the variable does not exist it will be created and any arguments appended to it Append provides an efficient means of concatenating values into variables However, [store add] is much faster [append] will append to any simple variable or array element only To concatenate strings without passing to a variable see: [concat] As the string size expands and to aid speed and efficiency, [append] returns no string unless the -return argument is used Example: option expression off set var 0 for {set i 1} {<= $i 10} {incr i} { append var "," $i } puts $var Result: 0,1,2,3,4,5,6,7,8,9,10 See also: concat, set, string
apply  Top  
string [apply funct ?arg1 arg2 ...?] Apply an anonymous function The command [apply] applies the function 'func' to the arguments arg1 arg2 ... and returns the result. In mathematics apply is a function that applies functions to arguments. It is key to programming languages derived from lambda calculus, such as LISP and also in functional languages The function 'func' is a two element list {args body} or a three element list {args body namespace} (as if the list command had been used). Note that namespaces are only emulated in Ticol The first element args specifies the formal arguments to func. The invocation of apply adds a call frame to Ticol's evaluation stack and acts in equivalent manner to [proc]. So the [info level] value will be +1 higher than the calling frame Empty function args and an empty arglist as {} are acceptable The specification of the formal arguments args is shared with the proc command. See: proc Example: This shows how to make a simple general command that applies a transformation to each element of a list proc lmap {lambda list} { set result {} foreach item $list { lappend result [apply $lambda $item] } return $result } lmap {x {return [string length $x]:$x}} {a bb ccc dddd} lmap {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} Results: 1:a 2:bb 3:ccc 4:dddd 2 -2 -4 -4 -2 2 8 16 26 Example: puts [apply {{x y} {expr hypot($x,$y)}} 3 4] Result: 5.0 Example: puts [apply {{} {return [info level]}} {}] # Show callframe level Result: 1 See: http://wiki.tcl.tk/4884 http://wiki.tcl.tk/5892 https://en.wikipedia.org/wiki/Apply https://www.tcl.tk/man/tcl/TclCmd/apply.htm See also: proc, lassign, K, uplevel, lmap, map, lambda
argv and argc  Top  
::argc is always defined. ::argv will be defined only if there are arguments If a script is launched via ticol.exe's command-line then argc will always be at least 1 and argv(0) will contain the full path and name of the script file. This applies to both TCL and TCX filetypes. If there are no command-line arguments then argv will not be set and argc will be 0. Use [is_set] or ::argc to check if argv exists before processing Example: Command: ticol.exe argv.tcl 1 2 3 argv.tcl: array walk argv Result: -------------------------------------------- hash_table object:0x3c4088 size:250 -------------------------------------------- Bucket(1) Node: 0x20a3f10 chained nodes:1 1: 0x20a3f10 key:'0' => 'argv.tcl' Bucket(69) Node: 0x20a3fd0 chained nodes:1 1: 0x20a3fd0 key:'3' => '3' Bucket(94) Node: 0x20a3f50 chained nodes:1 1: 0x20a3f50 key:'1' => '1' Bucket(135) Node: 0x20a3f90 chained nodes:1 1: 0x20a3f90 key:'2' => '2' Caution! -------- If a Ticol filetype (tcl/tcx) is associated with the Windows shell then this behaviour will differ unless the association definition has been modified to include command line arguments. Simply associating TCL or TCX files with Ticol.exe is insufficient to pass command line arguments. For this reason, take extreme care in launching Ticol scripts via Windows file associations Example: Command: argv.tcx 1 2 3 argv.tcx: array walk argv Result: (argv higher than 0 is not passed via the command-line) --------------------------------------------------------------- hash_table object:0x5c4088 size:250 --------------------------------------------------------------- Bucket(1) Node: 0x2113f40 chained nodes:1 1: 0x2113f40 key:'0' => 'C:\\VC5\\MyProjects\\picol\\Re...' Example: if {is_set argv} { array foreach argv val ss { puts "argv($ss)='$val'" } } See also: globals, array item
args (proc variable or command)  Top  
proc <name> {args} {... # Variable args argument-list... # Command $args proc variable ------------------ $args is a procedure variable which acts analogously to the C++ elipsis pseudo variable placeholder. Where specified,'args' will contain all subsequent arguments similar to the "C" elipsis (...) Example: proc foo {args} { puts "\$args=='$args'" } foo 1 2 3 4 Result: $args=='1 2 3 4' [args] command -------------- See: proc args for additional information The [args] command is a dummy debugging command which simply echoes its argument list. This is useful for debugging procedure or command arguments Example: (Using the {*} expand operator) args a {*}{b [c]} d {*}{$e f {g h}} Result: 0 'args' 1 'a' 2 'b' 3 '{[c]}' 4 'd' 5 '{$e}' 6 'f' 7 'g h' See also: debugging
proc args ($args) (See also args for the command)  Top  
proc {argument-list ... args} { ... The special variable 'args' may be defined as the last argument of a procedure. When defined this variable will receive a list of zero or more arguments which are supplied when the proc is called. It is similar in function to the C/C++ elipsis function argument "..." If the special argument, 'args', is not specified as the final argument of a proc then any excess arguments supplied when the proc is called will be discarded and ignored When including several scripts it is recommended to ensure procs from other scripts are cleaned-up before defining using [undef], e.g. undef foo -nocomplain Example: proc foo {a args} { # Will include unlimited trailing args puts "foo a is '$a'" puts "foo args is '$args'" } proc bar {a} { # Will allow only one arg puts "bar a is '$a'" } foo Hello foo Hello World foo Hello World How {Are You} Today newline bar Hello bar Hello World bar Hello World How {Are You} Today newline Results: foo a is 'Hello' foo args is '' foo a is 'Hello' foo args is 'World' foo a is 'Hello' foo args is 'World How {Are You} Today' bar a is 'Hello' bar a is 'Hello' bar a is 'Hello' Example: proc foo {x y} { ... Example: proc demo {first {second "two"} args} { ... Results: See: proc for more information Procs can also be called in many ways, directly by name or via [call], [gosub], [@>] or [$] Example: proc foo {} {puts Hello} foo call foo gosub foo @> foo set p foo $foo Results: Hello Hello Hello Hello Hello See also: proc, args
Function Arity  Top  
Arity is the number of arguments presented to a given function. There are a variety of functions available either within expr or funct as follows: The command [arity] will return the arity of a built-in function Function Arity 0 ---------------- srand Initialise the random number generator rand Return double random value from 0 to 1 The rand() and srand() functions are not cryptographically secure, and should not be used to generate one-time passwords or session keys Link to the Windows API using [calldll] instead Function Arity 1 ---------------- abs value Return the absolute value of a number acos value Return the arc cosine of value (arccos) asin value Return the arc sin of value (arcsin) atan value Return the arc tangent of value (arctan) bool value Evaluates a string and returns 1 or 0 ceil value Round to the next-highest integer value cos/cosh value Return the cosine of value decr value Decrement value degrees value Convert radians to degrees double value Cast value to double exp value Return the exponent of value fib value Return the fibonacci of value fix value Return integer value rounded up floor value Round to the next-lowest integer value fraction value Return the fraction part of a real/double incr value Increment value int value Cast value to integer integral value Return the integer part of a real/double log value Return the logarithm of value log10 value Return the log10 of value round value (0 places) Round value to 0 places using standard rounding sgn value Return the sign as an integer (1, 0, -1) sin/sinh value Return the sine of value sqr value Return the square of value sqrt value Return the square-root of value srand seed Seed the random number generator tan/tanh value Return the tangent of value wide value Force a value to 64 bit signed integer Function Arity 2 ---------------- div a b Functional division of a / b fmod a b Return the remainder of a / b hypot a b Return the hypotenuse of a and b max a b Return the maximum of a and b min a b Return the minimum of a and b mul a b Functional multiplication of a * b pow a b Return a to the power of b rnd a b Return a random number between a and b inclusive round a b (b places) Round a to b decimal places You can use the [functions] command to get a list of supported [expr] functions You can use the [funct] command to export and access an expression function See also: expression functions, arity, functions, funct, expr, eval
arity  Top  
integer [arity functname] Return the arity count of an inbuilt function as an integer value If the function is not found then -1 is returned Example: puts [arity rand] # No arguments puts [arity abs] # One argument puts [arity max] # Two arguments (funct) puts [arity fred] # No such command Results 0 1 2 -1 For an arity list of each available function. See: function arity See also: function arity, expression functions, functions, funct, expr, eval
ARP Address Resolution Protocol and RARP (Reverse ARP) Plugin  Top  
Load using: lib ticol_arp?.dll? arp ipv4-address ?-list? # ARP lookup of IPV4 address arp table # Return the ARP table as a Tcl list rarp mac-address ?-list? # Reverse ARP lookup. Look up in ARP table Address Resolution Protocol (ARP queries will query the local Arp table. Results will depend on the content of the Arp table [arp] returns a string value and may return an empty string for interfaces which return no MAC address. No mac address is returned for addresses which cross NAT firewalls or for loopback/dummy interfaces. Such addresses must be on the same LAN [arp table] returns a Tcl list with one {ip-address mac-address status} list per interface found [rarp] can only return results for "known" IPV4 addresses which have been discovered and placed in the local ARP table cache. Your workstation must have been in conversation with these addresses, (e.g. via ping) Lookups which return empty {} string are not fatal errors. The return should be tested to see if the return value is empty, which indicates the IP or MAC address was not found For exceptions such as malformed IP or MAC addresses an error exception is raised with an internal ARP library error code or a Windows system error code The -list option will return a list which includes the error code as the 2nd item. [arp] Error Codes ----------------------------------------------------------------- 0 Success 1 Success but empty MAC address returned 2 Failed to load iphlpapil.dll 3 Failed to link to lib function SendARP 4 MakeMacAddress failed 5 Bad PMAC buffer 6 Bad IP address 7 Unhandled error * SendArp API error code 31 ERROR_GEN_FAILURE (Network error/disconnected interface) 50 ERROR_NOT_SUPPORTED 67 ERROR_BAD_NET_NAME 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW 1168 ERROR_NOT_FOUND 1784 ERROR_INVALID_USER_BUFFER [rarp] Error Codes ----------------------------------------------------------------- 0 Success (match found) 1 Failure (no match) 2 Bad MAC address 3 Bad MAC format 4 Unknown/unhandled error Example: puts [arp table] Result: {224.0.0.2 00-00-00-00-00-00 Static} {224.0.0.22 00-00-00-00-00-00 St atic} {224.0.0.252 00-00-00-00-00-00 Static} Example: set t [arp table] foreach l $t { # foreach list item foreach {i m s} $l { # IP, MAC, Status puts "$i\t$m\t$s" } } Result: 224.0.0.2 00-00-00-00-00-00 Static 224.0.0.22 00-00-00-00-00-00 Static 224.0.0.252 00-00-00-00-00-00 Static Examples: arp 127.0.0.1 # Loopback adapter arp 8.8.8.8 # Google DNS arp 192.168.1.1 # Class C local IPV4 address rarp 3c46d8cc5cce # Must be in the ARP table (ping first) rarp beefdeadbeef # Must be in the ARP table (ping first) Results: {} # Empty string as loopback adapter not in cache {} # Empty string as 8.8,8.8 is an internet address 3c46d8cc5cce # MAC address of workstation on local LAN 192.168.1.1 # Reverse lookup from MAC to IP {} # No such MAC address in the ARP table Examples: arp 1.2.3.4 -list # No such address? rarp pqrs -list # Bad MAC address Result: {} 31 # Empty return + network error See also: ping, dns, dhcp, plugins
array - Tcl Array Commands  Top  
Various commands for manipulating standard Tcl arrays. Arrays are also addressed and dereferenced using the dollar ($) sign in the same way as for languages such as PHP arrays Information about standard Tcl arrays array append a b ?n? Append array b to array a for ?n? rows array create arrayVar ?n? Create an empty array array exists arrayVar Return boolean true if array exists array find arrayVar string Return index/subscript or empty string array foreach arrayVar v s code Alias for [array_foreach] array get arrayVar Return an array as a key + value list array is_set arrayVar Boolean 1 if an array exists else 0 array item arrayVar subscript Array indexing with default option array list arrayVar Exports an array to an unsorted list array names arrayVar Returns a list of subscript values array set arrayVar list Set array using a list of parameters array size arrayVar Return the size of array if it exists array sort arrayVar Exports the array to a sorted Tcl list array statistics arrayVar Show statistics for a given array array trim arrayVar ?mask? Trim L/H and R/H end of array values array unset arrayVar Delete array & all allocated elements array walk arrayVar Walk the array hash-table Example: set a(0) Hello puts $a(0) Example: set a(0) Hello puts [array item a 0] Example: set a(0) Hello puts [array get a 0] Example: set a(0) Hello puts [set a(0)] See: help array <subcommand> e.g.: help array list See also: arrays, variant arrays, array_foreach, passing variables by name
array append  Top  
integer [array append array1 array2 ?count?] Append one integer-indexed array onto the end of another. Optionally, this can be restricted to one or more elements of the 2nd array. The returned integer is the new count of the appended-to array Integer-indexed arrays are returned by a number of Ticol command such as [split] Example: split $qbf " " -array a # Splits into an integer-indexed array split "Now is the time for all men to come to the party" " " -array b set r [array append a b] # Append 2nd array on to the 1st assert [array size a] {== $_ 22} -v -line #__LINE__ puts "New size is $r" Result: New size is 22 This is an equivalent [proc] solution option expression off proc array_append {_a _q} { upvar $_a a upvar $_q b set q [array size a] set r [array size b] for {set i 0} {< $i $r} {++ i} { set a([+ $q $i]) $b($i) } return $_a } See also: arrays, array foreach, array size
array foreach  Top  
array foreach arrayName valueVar ?subscriptVar? {code} array_foreach arrayName valueVar ?subscriptVar? {code} Iterate an array, applying a block of code with each element's value passed into valVar and, optionally, the array's subscript value passed into subscriptVar. The array element value precedes subscript due to subscript being an optional parameter [array foreach] is functionally equivalent to a combination of [foreach] and [array get] but is more efficient # Emulate [array foreach] using [array get] and [foreach] foreach {x y} [array get env] { printf "%-20.20s\t=%-45.45s\r\n" $x $y } One common alternative is to get the names and then order them Tcl arrays are associative and intrinsically unordered. Values cannot be retrieved from an array in the same order that they were set. Arrays will be retrieved in random (unsorted) order. Integer-indexed arrays should be used where a sorted order is required [array foreach] may also be called as [array_foreach] Example: set i 0 array foreach env val ss { printf "$i:\t%-20.20s=%-45.45s\n" $ss $val incr i } Result: (prints out environment table) 1: ProgramFiles =C:\Program Files (x86) 2: USERPROFILE =C:\Users\Admin Example: ticol.exe ; "set i 0; array_foreach env x {puts $i:$x;[incr i]}" Result: Prints out environment See also: foreach, arrays, array
array create  Top  
array create arrayName ?size? Alias for [dim arrayName size] Creates a Tcl associative array with the default pre-allocation of 1 If 'size' is specified then the array will have memory preallocated to that size. This will prevent a need to reorganise the storage table on the fly It is not mandatory to use [array create]. Arrays will be created on first use as with standard variables, for example, the statement: set a(0) Hello will create array 'a' and array element '0' [array set] will be the most common means of creating arrays with pre- determined contents, e.g. array set colours { red 1 green 2 blue 3 white 4 } will create array 'colours' with 4 elements Example: array create names 10 array walk names Results: ----------------------------------------------------------------- hash_table object:0x35ec650 size:10 ----------------------------------------------------------------- Hash Table Statistics: Root size:10 Occupation:0 (0.00%) Max depth:0 Nodes:0 ----------------------------------------------------------------- See also: array, arrays, dim
array_to_list  Top  
array_to_list arrayvar ?listvar? ?-values? Converts an array to a well-formed but unsorted Tcl list containing pairs of keys (subscripts) and matching values. Optionally this list can be passed into an output variable. Both the array and optional list variables must be passed by name If the -values argument is used then only values are returned Use [lsort] to sort the resulting list Example: set q [lsort [array_to_list env]] puts "Returned [lcount q] item(s)" newline set i 1 foreach pair $q { foreach {l r} $pair { puts "$i\t$l\t=$r" } ++ i } Result: 1 ALLUSERSPROFILE =C:\ProgramData 2 APPDATA =C:\Users\Admin\AppData\Roaming 3 COMPUTERNAME =FIDO 4 ComSpec =C:\Windows\system32\cmd.exe 5 CommonProgramFiles =C:\Program Files (x86)\Common Files 6 CommonProgramFiles(x86) =C:\Program Files (x86)\Common Files 7 CommonProgramW6432 =C:\Program Files\Common Files ... See also: list_to_array, lsort, array, list
array is_set  Top  
array is_set arrayVar Returns boolean 1 ($true) if an array exists, otherwise 0 ($false) Example: set a(0) Hello puts [bool [array is_set foo]] puts [bool [array is_set a]] Result: false true See also: is_set
array exists  Top  
Return a boolean indicating if an array exists array exists arrayName array exists arrayName(element) When used with the name of an array variable this tests only if the array variable name has been set. This does not guarantee any elements in the array are assigned. To check the size of an array use [array size arrayName] An array element represents a single variable bound to an array and should be tested using [array exists arrayName(element)] You may also use [info exists varname] to test for an array element In all cases the variable to be tested must NOT be prefixed by a dollar $ sign Case will be ignored when searching for the special system arrays 'env' and 'argv' Examples: array exists argv array exists env array exists argv(0) array exists env(TEMP) info exists argv(0) info exists env(TEMP) See also: is_set, is_empty, arrays, array, array size, info exists
array find (Reverse array lookup)  Top  
array find arrayName valuestring ?-nocase? ?-length N? Searches an array by looking up a value to return the index/subscript of the first matching item with full string match, or an empty string if the item does not exist. The match is case-sensitive and will match the entire string. It will not match a substring [array find] is not a standard Tcl command and is much less efficient than subscript indexing, but should be adequate for small arrays of less than a few thousand elements Example: split $qbf " " -array a # Split into integer-indexed array set i [array find a "fox"] puts "fox is in element '$i'" Results: fox is in element '3' The '-length' argument allows comparison on a given number of characters Example: puts [array find env "x86" -nocase -length 3] Result: PROCESSOR_ARCHITECTURE Example: array set fruits { # Subscript/key # Value blue berry green apple orange orange red cherry yellow lemon } set i [array find fruits cherry] puts "cherry is in element '$i'" Results: cherry is in element 'red' See also: arrays
array get  Top  
list [array get arrayname] string [array get arrayName ?mode? ?pattern?] string [array get arrayName ?pattern? ?mode?] Return an array as a key + value list. [array get arrayName] will return the entire array as a list of pairs of keys+values Where ?mode? is any of: -glob Wildcard string matching (the default) -exact Exact string matching (-glob is the default) -all Return all items and optionally: -pair Return array subscript+value pairs -nocase Ignore case when making comparisons Note that [array get] is less efficient than direct array addressing as Tcl associative arrays are hashed and meant to be indexed efficiently by the precise key value (subscript) Case will be ignored automatically for arrays set using -nocase or for the special global arrays env() and argv() Example: array get env u* Result: USERPROFILE C:\Users\Admin USERNAME Admin USERDOMAIN SNOOPY Example: (Prints out the environment table) foreach {x y} [array get env] {puts $x=$y} Result: ProgramFiles=C:\Program Files (x86) USERPROFILE=C:\Users\Admin OS=Windows_NT ComSpec=C:\Windows\system32\cmd.exe PROCESSOR_ARCHITEW6432=AMD64 SystemDrive=C: Example: foreach x [lsort [array get env -nocase -pair]] { puts [lindex $x 0]=[lindex $x 1] } Result: ALLUSERSPROFILE=C:\ProgramData APPDATA=C:\Users\Admin\AppData\Roaming HOMEDRIVE=C: HOMEPATH=\Users\Admin LOCALAPPDATA=C:\Users\Admin\AppData\Local USERNAME=Admin WINDIR=C:\Windows Example: foreach {x y} [array get env proc* -nocase] {puts $x=$y} Result: PROCESSOR_ARCHITEW6432=AMD64 PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 37 Stepping 5, GenuineIntel PROCESSOR_REVISION=2505 PROCESSOR_LEVEL=6 PROCESSOR_ARCHITECTURE=x86 Example: puts [wrap [array get env -glob c*] 60] Results: ComSpec C:\\Windows\\system32\\cmd.exe COMPUTERNAME LENOVO C ommonProgramFiles(x86) {C:\\Program Files (x86)\\Common File s} CommonProgramFiles {C:\\Program Files (x86)\\Common Files } CommonProgramW6432 {C:\\Program Files\\Common Files} COMMP ath {C:\\Program Files\\Lenovo\\Communications Utility} See also: array names, arrays, array, info exists
array list  Top  
array list arrayName Exports the array values to an unsorted Tcl list Note that this does not include the array subscripts. Ticol lists are slow and inefficient, particularly when used to store large numbers of items (> 1000 or more). For small lists the difference in performance is insignificant Example: # Export and iterate each list value item foreach {x} [array list env] { puts $x } Result: C:\Program Files C:\Users\Admin\AppData\Local C:\Users\Public C:\Users\Admin\AppData\Roaming C:\ProgramData $P$G See also: arrays, array names, array item
array item  Top  
array item arrayName subScript ?default value? ?-nocase? Resolve an array index with optional default return value. This is helpful since associative arrays may be 'sparse' and there may therefore be no guarantee that any element exists at all [array item] is not a standard Tcl command and it offers a safe lookup of arrays. The standard, 'inline' method of referencing arrays will return a fatal error where the array element does not exist. [array item] will instead return an empty string where the array element does not exist The referenced array variable must exist [array item] may be combined with [array exists array subscript -nocase] to safely handle ambiguous/case-insensitive array lookups If the element is not found and a default value given then the default value will be returned. This permits safe/simple array lookups with defaults A fatal error is raised only where the referenced array does not exist The variable name argument must not be dereferenced using the $ symbol Correct: puts [array item env temp -nocase] Wrong: puts [array item $env temp -nocase] # $env returns the tag "<array>" Example: array set smtp_code { # Array of SMTP error codes 221 "Server ready" 250 "Send success" 252 "Cannot verify user, but it will deliver" } puts [array item smtp_code 250 "Unknown error"] puts [array item smtp_code 251 "Unknown error"] Result: Server ready Unknown error See also: array, arrays
array names  Top  
array names arrayName ?mode? ?pattern? Where ?mode? is any of: -glob Wildcard string matching (the default) -exact Exact string matching (-glob is the default) -nocase Ignore case when making comparisons -all Return all items Returns a list of array subscript values (array element name identifiers) Case will be ignored automatically for arrays set using -nocase or for the special global arrays env and argv Example: puts [array names env u*] Result: USERPROFILE USERNAME USERDOMAIN Example: foreach {x} [array names env t* -nocase] {puts "$x\t$env($x)"} Result: TEMP C:\Users\Admin\AppData\Local\Temp TMP C:\Users\Admin\AppData\Local\Temp Example: foreach {x} [array names env -exact windir] {puts "$x=$env($x)"} Result: windir=C:\Windows See: array get for similar examples See also: arrays
array set  Top  
integer [array set arrayName list ?-const? ?-nocase?] Set and initialise an array using a list of parameters. This may be a single Tcl list or series of arguments. [array set] cannot be used to append items to an existing array. The array must not already exist The standard Tcl command is extended to add constant (-const) and case- significance lookup attributes (-nocase). Arrays which are constant cannot be reassigned but can be unset Arrays which are set using -nocase will be much less efficient but can be indexed by subscript values in a case-insensitive manner. Scripts should be designed to use large arrays in a case-sensitive manner. For small arrays the performance impact will be negligible A subst is performed on array pairs before assignment. Variables are substituted and escaped characters are translated. Commands are not executed Use: [set array(subscript) value] - to set individual array elements [array create] can be used to create an array without assigning any elements and [array create size] can be used to pre-allocate an array of a fixed size to avoid time-consuming dynamic reallocation [array set] returns an integer count of the number of array elements created Example: array set colours { red 1 green 2 blue 3 white 4 } array set colours {red 1 green 2 blue 3 white 4} array walk colours array_foreach colours a b { printf "%s\t%s\n" $b $a} Result: --------------------------------------------- hash_table::walk() Object:0x1df43f0 size:250 --------------------------------------------- Bucket(138) Node: 0x1e08840 chained nodes:1 1: 0x1e08840 key:'green' value:'2' Bucket(140) Node: 0x1e08870 chained nodes:1 1: 0x1e08870 key:'blue' value:'3' Bucket(181) Node: 0x1e088a0 chained nodes:1 1: 0x1e088a0 key:'white' value:'4' Bucket(238) Node: 0x1e08810 chained nodes:1 1: 0x1e08810 key:'red' value:'1' green 2 blue 3 white 4 red 1 Example: (Calling commands and passing the result into [array set] set p [expr 4*atan(1)] set bp [expr 22/7.0] array set mathstuff { pie $p badpie $bp } array foreach mathstuff v ss { puts "Item: $ss\tValue '$v'" } Result: Item: badpie Value '3.142857142857143' Item: pie Value '3.141592653589792' See also: set, array, arrays
array size  Top  
array size arrayName # Return the size of an array if it exists If the array is not assigned (does not exist) then a null string is returned If the array exists (has been declared) but with no elements assigned then zero is returned Example: # a # Not declared set b {} # Not an array dim c 1 # Create empty array using [dim] set d(1) 0 # Assigned array and element array set e {1 one 2 two 3 three} # Multi-element set puts "Undeclared a '[array size a]'" puts "Non-array b '[array size b]'" puts "Empty-array c '[array size c]'" puts "Declared d '[array size d]'" puts "Declared e '[array size e]'" Results: Undeclared a '' Non-array b '' Empty-array c '0' Declared d '1' Declared e '3' See also: array, array unset
array list  Top  
array list arrayName # Exports the array to an unsorted Tcl list Note that the list contents will be in random, not original, order Example: foreach x $qbf { set q($x) $x } Result: the brown jumps lazy fox quick over The dog Example: foreach x [array list env] { puts $x } Result: D:\WINDOWS D:\WINDOWS\system32\cmd.exe See also: arrays, array sort, array
array sort  Top  
list [array sort arrayname ?newvar? ?-reverse? ?-names?] integer [array sort arrayname ?newvar? ?-reverse? ?-array name? ?-names?] Creates a sorted Tcl list of array values. Note that the subscript (key) values are not returned and the internal array hashtable structure cannot actually be sorted, only the returned output By default a sorted Tcl list is returned. Alternately, another integer- indexed array can be created, in which case the new array element count is returned. The default sort order is normal (A-Z) Sorting in Integer Sequence --------------------------- [array sort] can also output an integer sorted array indexed at base 0 by specifying the '-array' argument Example: option expression on for {set i 0} {$i < 2000} {incr i} { set a($i) [randomstr 20] } puts [llength [array sort a]] Result: 2000 Example: option expression on for {set i 0} {$i < 2000} {incr i} { set a($i) [randomstr 20] } puts [array sort a b] Result: 2000 Example: option expression off array sort env -array out set s [array size out] for {set i 0} {[< $i $s]} {incr i} { printf "%4i:\t%-40.40s\r\n" $i $out($i) } Results Outputs values in the ENV table Example: # Using a temporary and [swap] to swap between sorted and unsorted arrays # [swap] moves no data, it simply renames the two variables option expression off array sort foo -array out swap out foo # Swap $foo and $out set s [array size foo] for {set i 0} {[< $i $s]} {incr i} { printf "%4i:\t%-40.40s\r\n" $i $foo($i) } Sort by Array Names (Subscripts/Keys) ------------------------------------- If -names is specified together with -array and an array value then the array will contain an exported, integer-indexed list of array names (subscript keys) rather than array values. The resulting integer-indexed array can then be used to index the original array in that sorted order Example: array set unsorted { The orange quick yellow brown blue fox black jumps magenta over white the cyan lazy green dog red } array sort unsorted -array sorted -names # Output to array 'sorted' set size [array size sorted] # Grab the array size option expression off for {set i 0} {[< $i $size]} {incr i} { # Iterate numerically printf "%4i:\tref: %s =>\t%-40.40s\r\n" $i $sorted($i) \ $unsorted($sorted($i)) } Results: 0: ref: brown => blue 1: ref: dog => red 2: ref: fox => black 3: ref: jumps => magenta 4: ref: lazy => green 5: ref: over => white 6: ref: quick => yellow 7: ref: The => orange 8: ref: the => cyan [array sort] is not a standard Tcl command See also: arrays, array list, array, swap, Tcl lists
array statistics  Top  
array statistics arrayname Show statistics for a given array. This shows the total number of root entries in the array's hash-table as well as the total number of buckets (nodes) including the root entries. Additionally, a summary is shown of the first 10 most relevant top-level bucket allocation counts. Ideally the average search depth for a given root entry should not be much more than about 2 or 3 but as the allocation is largely random and this is therefore impossible to achieve completely. Ticol enhances the usual Tcl statistics table by showing the total bucket count per-category in brackets. Example: option expression on for {set i 0} {$i < 2000} {incr i} { set a($i) [randomstr 20] } array statistics a Result: 2000 entries in table, 1000 buckets number of buckets with 0 entries: 0 (0) number of buckets with 1 entries: 270 (270) number of buckets with 2 entries: 269 (538) number of buckets with 3 entries: 173 (519) number of buckets with 4 entries: 94 (376) number of buckets with 5 entries: 36 (180) number of buckets with 6 entries: 16 (96) number of buckets with 7 entries: 3 (21) number of buckets with 8 entries: 0 (0) number of buckets with 9 entries: 0 (0) number of buckets with 10 or more entries: 0 (0) average search distance per entry: 2.32 Array hash-table performance can be configured using ticol.ini settings but it is strongly recommended to keep to the defaults See: ticol.ini See also: arrays, array, array walk
array trim  Top  
array trim arrayVar ?maskchars? ?-left|-right? Trims the left and/or right hand ends of all array values Example: # Create a ragged, CRLF-delimited string with leading/trailing spaces option expression off set s " The quick brown fox jumped over the lazy dog" puts $s puts [string repeat - 30] split $s "\r\n" -array a array trim a for {set i 0} {< $i 4} {++ i} { # Print in array order puts '$a($i)' } Result: The quick brown fox jumped over the lazy dog ------------------------------ 'The quick brown' 'fox jumped' 'over the' 'lazy dog' See also: array, trim, string repeat
array unset  Top  
array unset ?::?arrayName array unset ?::?arrayElement(X) Delete a single array and all elements. Individual array elements may also be deleted using [unset] array unset arrayName If the array is in global scope then use the '::' prefix (omitting the $) as: array unset ::arrayName It is an error to attempt to unset a non-existent or const array variable See also: unset, arrays, array, clear, vars
array walk  Top  
array walk arrayName Walk (iterate) the array hash-table (not a standard Tcl command) -------------------------------------------------- hash_table::walk() Object:0x973290 size:500 -------------------------------------------------- Table(1) Node: 0x9d8500 chained nodes:1 0x9d8500 depth:1 key:'75' value:'WdqUPVnSLNLTMfeeEqTO' Table(5) Node: 0x9d8a80 chained nodes:1 0x9d8a80 depth:1 key:'50' value:'gPkhMdxxowGitxhibQgd' Table(10) Node: 0x9d8d90 chained nodes:1 0x9d8d90 depth:1 key:'76' value:'KMtJygZvZouAvRBUPVqg' Root size:500 Root occupation:89 (17.80%) Max depth:2 Occupied nodes:100 -------------------------------------------------- An optional 'glob' filter pattern may be given to filter on key values [array walk] is not a standard Tcl command See also: arrays, array, array statistics
Tcl Arrays  Top  
Ticol supports subscripted, associative Tcl arrays. This offers arrays with either traditional numeric subscripts or subscripts indexed by a case- sensitive string. This subscript may be a string-literal or a Tcl variable name prefixed by a dollar $ sign or $:: global scope indicator to access global variables within procedures. Numeric subscripts are still supported but the subscript will simply be a string value which may be intermixed with non-integer subscript values See: array Multi-Dimensional Arrays ------------------------ There are no multi-dimensional arrays in standard Tcl but they may be emulated by various means. This usually involves compound subscript values using embedded commas which, when combined, form a unique hash key e.g. 'arrayvar(x,y)' where the key value is "x,y" See the Tcl websites for a discussion Example: set a(0,1) "Item one" set a(0,2) "Item two" set a(1,1) "Item three" set a(1,2) "Item four" Case Sensitive Subscripts ------------------------- Array subscripts are case-sensitive with the exception of the $argv and $env system arrays. Subscripts are referenced case-insensitively so that $env(TEMP) and $env(temp) will both return the correct array element. Large arrays cannot be efficiently traversed when addressed case- insensitively. The internal hash table has to be traversed in a linear fashion in such cases (See: array index) Some Tcl commands have been extended to include case-insensitive lookups. These lookups are far less efficient than case sensitive ones An array can be defined as case-insensitive using [array set] with the -nocase argument Example: array set a {q Hello} -nocase puts $a(q) # Reference using lower case puts $a(Q) # Reference using upper case Result: Hello # Same result for upper or lower case Hello Spaces in Subscripts -------------------- Whitespace is allowed in a subscript value but should be wrapped in double quotes Example: set foo("a b c") zzz set bar("d e f") "Hello world" Declaration and Use ------------------- Arrays can be declared using set only one level at a time. Multiple, simultaneous, nested arrays may not be declared (e.g. set a(b(c(1))) hello) You can use [array set] to initialise multiple array elements set a(1) Hello # A traditional literal numeric subscript puts $a(1) # Example dereference Hello # Result set a(one) Hello # An associative array with literal subscript puts $a(one) # Example dereference Hello # Result set i 0 # Create an index variable set a($i) Hello # An associative array with variable subscript puts $a($i) # Example dereference Hello # Result array set days { # Create a const array of 7 elements 1 Monday 2 Tuesday 3 Wednesday 4 Thursday 5 Friday 6 Saturday 7 Sunday } -const Arrays are referenced by dollar prefix, the same as any other Tcl variable Note that the array syntax prohibits any whitespace between the variable name and the open parenthesis: Correct: "$varname($index)" Incorrect: "$varname ($index)" (looks for non-array variable '$varname') Arrays as Command Arguments --------------------------- Not all Ticol commands accept arrays as output arguments. Some do, such as [setat].Check with the section for each command Most commands won't accept nested/complex array expressions as output arguments (i.e. as the name of target variables to be written). Most will accept arrays and complex array expressions as input arguments as long as the array is resolved before the call Sorting ------- Associative arrays cannot be sorted internally, they are, however, rapidly accessible by the hashed key (subscript) value so sorted indexes are typically unnecessary.. See [array sort] for sorting workarounds Storage and Efficiency ---------------------- All arrays are stored in a dynamic hash-table as associative arrays. Due to this internal storage method, arrays are not contiguous in memory and thus cannot be natively sorted. To sort an array, output it to a sorted list You can create an array with a fixed table allocation and avoid the performance costs of resizing by declaring to a high enough initial size. Use array create arrayName size, e.g. array create big 10000 Arrays indexed by numeric value can be indexed in pseudo-sorted order by use of a numeric subscript index value and a for loop or returned as a list Array storage is expanded dynamically from a minimum reserve allocation of 1 element Any valid object which can be stored in a standard Tcl variable may be stored in an array element Storing Types ------------- The empty string "" is stored in an array element as an empty Tcl list {} Arrays of lists and other types are possible but it should be understood that a Tcl array is not a contiguous binary array and is unsuitable for passing forward to an external C/C++ DLL Arrays of Lists --------------- Since Tcl lists are strings, Tcl arrays may have a list as the array value array set economists { 1 {HH002 "Henry Hazlitt" 002 87} 2 {WB001 "Walter Block" 072 77} 3 {PB001 "Phillip Bagus" 033 22} 4 {MR001 "Murray Rothbard" 023 19} } -const And this would be equally valid since the subscript key is unique array set economists { HH002 {1 "Henry Hazlitt" 002 87} WB001 {2 "Walter Block" 072 77} PB001 {3 "Phillip Bagus" 033 22} MR001 {4 "Murray Rothbard" 023 19} } -const Passing Arrays to Procedures ---------------------------- Arrays can only be passed via a proc body by reference (by name) and using a subsequent upvar command. To pass an array by value you must convert to a list This is by design. Arrays are intended to be passed by reference (by name) [array item] is the most convenient way to handle the double-dereference of unknown array names passed to a proc Example: array set colours { 1 red 2 green 3 blue } -const proc list_by_key {arrayName} { upvar $arrayName foreach key [lsort [array names $arrayName]] { puts "Key: '$key [array item $arrayName $key]'" } } list_by_key colours Nested Array References ----------------------- Nested array references are permissible. The outer variable must follow Tcl syntax and NOT include a dollar prefix when calling [set] set c 1 # Create a subscript variable set b($c) hi # Create an array variable set a($b($c)) Hello # Set a nested associative array puts $a($b($c)) # Example nested dereference Hello # Result Each nested level must first be declared either using set or the [array] command. Attempting to set an un-dereferenced intermediate array (i.e. missing the $ symbol) will trigger an invalid argument error. (e.g. set a(b(c))) hello) -> error in 'b(c)') Advanced Arrays --------------- Ticol cannot create complex arrays such as arrays of struct, arrays of stack etc. The array variable, can however, point to the name of a complex variable type or a standard Tcl variable which holds a list Array Debugging --------------- The statistics for an array are inspected using: [array statistics arrayname] and the array can be inspected in detail using [array walk] See also: array, array create, array exists, array list, array size, array sort, array statistics, array unset, array walk
asc  Top  
integer [asc character|string] integer [asc "character"|"string"] The inverse of chr. Returns the ASCII (ANSI) numeric value of a string Examples: puts [asc "A"] # Double-quoted argument puts [asc {A}] # Braced argument puts [asc A] # Raw argument Result: 65 65 65 See also: chr, string, left, right, mid, index
assert  Top  
assert value {expression} ?-line line? ?-v? ?-var name? Asserts an expression using a substitution variable in the expression This expression is in the current scope context A temporary variable is created in the current scope which receives the result of the first argument. The default name is $_ . You can change this to any name using the ?-var name? option as long as the variable does not already exist in the current scope. The substitution variable represents the evaluated expression and may be used in the test expression If you supply a line number this will be displayed in the output No output is issued if the assertion is true unless the '-v' (verbose) argument is specified. Thus, [assert] statements may be left within active code. The expression argument must be supplied in braced format After debugging is complete all [assert] statements can be disabled globally using the following Macro definition. #define NDEBUG #undef NDEBUG Once the macro variable NDEBUG is defined [assert] statements are skipped and have minimal execution overhead within a script Resetting NDEBUG with #undef NDEBUG may have no effect on the rest of the script. The entire script will be affected by the first instance of #define NDEBUG which is found since this has effect only at macro preprocess time and these events are out-of-order with sequential Tcl command processing For more information, see: macro preprocessor Examples -------- Example: assert 1 {eq $_ 1} Result: # PASS - Program continues without interruption # No output Example: assert 1 {eq $_ 1} -line 10 -v Result: # Program continues without interruption and displays confirmation assert: PASS 'eq $_ 1' Example: assert 0 {eq $_ 1} -v -line #__LINE__ # Default internal variable Result: assert: Line 10: Assertion failed: '0' != 'eq $_ 1' # Program execution halts Example: assert 1 {eq $x 1} -var x Result: # Test passes OK. No output Example: assert 1 {eq $x 1} -v -var x -line #__LINE__ assert 0 {eq $x 1} -v -var x -line #__LINE__ Result: assert: Line 1: PASS 'eq $x 1' assert: Line 2: Assertion failed: '0' != 'eq $x 1' # Program execution halts Example: #define ndebug # The following statement would normally fail but is now ignored assert 1 {eq $_ 0} Result: # Assertion is ignored. Execution continues without assert See also: debugging
Associative arrays  Top  
Older languages like C, C++, BASIC, and Java support arrays in which the array subscript index value is an integer and where that subscript index represents some offset into a single memory block. Tcl, in common with many modern scripting languages such as Perl, Python or PHP supports 'associative' arrays in which the index value is an arbitrary string value or string representation of a number. In associative arrays there is no counted binary offset from one location in a block of memory to the next. The underlying data structure in the case of Ticol is the "hash table" Associative arrays held in a hash-table are inherently unordered Associative array syntax places the subscript within parentheses as with other languages. There is no need to declare an array before assigning. You can assign any valid variable name as an array a long as it is not already assigned and in use If you intend to assign a very large array you can use [dim] to pre- allocate the underlying hash-table to speed-up assignment later on Example: set name(first) "Gordon" # 'first' is a string literal set name(last) "Bennett" # 'last' is a string literal puts "Full name: $name(first) $name(last)" Result: Full name: Gordon Bennett As with all Tcl variables, you dereference a variable by prefixing with a dollar symbol $ but cases which refer to a variable name without dereferencing do not require a dollar prefix e.g. puts $name(first) Some functions, such as [unset] require the literal name of the array, e.g. [unset name], [unset name(first)] The system environment is provided via a pre-allocated const array 'env' e.g. puts $env("PATH") Ticol command line arguments are provided via the const array 'argv' with integer 'argc' representing the argument count. e.g. puts $argv(0) Double-dereferencing such as $$array(subscript) can be handled For detailed information, see: arrays See also: array, arrays, array find, env, argv, dim, dump, array unset double dereference
autoexec  Top  
autoexec ?on|off? This option interacts with 'proc unknown'. It controls the passing of unrecognised/unknown commands to the underlying operating system or the calling of a special procedure. Autoexec is ON by default, allowing Ticol to be used as a Windows command-shell If autoexec is 'on' then unknown commands are passed to Windows IF and only IF a proc called "unknown" isn't defined. C/C++ style escape characters such as \r or \n are also disabled at the console to ensure correct operation with Windows If autoexec is 'off' and a proc called "unknown" is not defined, then the command will return an error. Turning the option 'off' will re-read any INI configuration settings for BackslashEscape for the CLI (see: help ini) The command 'autoexec' with no arguments will return the current status as 'on' or 'off' This is also configured in ticol.ini [config] as Autoexec=<boolean> The autoexec option is Ticol specific and not standard Tcl. The autoexec option does not relate to the use of an autoexec.tcl file For more information, see: unknown See also: autoexec.tcl, ini, commands, exec, spawn, cli, debugging, macro
autoexec.tcl  Top  
autoexec.tcl - The Ticol startup script If a file called autoexec.tcl is found in the same folder as TICOL.EXE at startup then this will be executed automatically unless configured otherwise or set to do so via the command line. This is the Ticol equivalent to the DOS/Win AUTOEXEC.BAT file. Due to inherent risks in running a script automatically, the autoexec.tcl file may NOT be obfuscated, thus preventing potentially damaging commands from being hidden. Any obfuscated autoexec.tcl file will not be processed You may disable the execution of autoexec.tcl using either the command line option /NA or via the ticol.ini file setting: [config] AutoExecScript=FALSE An autoexec.tcl file may be used to initialise common variables or define a set of common procedures before an interactive CLI session or running another script If autoexec.tcl ran successfully and returned code ok then variable $::autoexec_ran will be set to $::true (1), otherwise $::false (0) autoexec.tcl is never run in CGI mode. Programmers must rely on ticol.ini or the active script for configuration Note that autoexec.tcl may NOT be encrypted/obfuscated. This is by design autoexec.tcl has nothing to do with the [option autoexec] setting for the Ticol Command Line Interpreter (CLI) See also: configuration, obfuscation, autoexec, at_exit
at_exit  Top  
proc at_exit {} {<script>} [at_exit] is an optional user-defined procedure which is called when a Tcl script exits by exiting Ticol. Proc at_exit takes no arguments. Any arguments to [at_exit] will be ignored [at_exit] is called only via running scripts, never from the CLI and is not called unless the script exits the Ticol binary The [upvar] command is required to access variables defined elsewhere in the [at_exit] procedure [at_exit] is intended for use as a cleanup routine, to close DLL and open file handles safely, avoid memory leaks, file or database corruption etc. [at_exit] is not called when Ticol is exited abruptly using CTRL+BREAK Where a [stop] command is encountered within [at_exit], execution will be returned to the CLI. Where an exit command is met within [at_exit], Ticol will exit Where neither is given the default behaviour will apply (exit if run from Windows or stop and return to the CLI if run from the CLI) Unlike C++, multiple [at_exit] routines are not provided for. There is no need to register multiple [at_exit] routines. One routine can call all desired shutdown code, including other procedures Example: proc at_exit {} { puts "Inside proc 'at_exit'" upvar handle upvar pointer puts "Handle is $handle" puts "Pointer is $pointer" puts "Exiting Ticol" return 0 } puts "In main()" set handle 10 set pointer 2 puts "Exiting script" stop Result: In main() Exiting script Inside proc 'at_exit' Handle is 10 Pointer is 2 Exiting Ticol Example: proc at_exit {} { # If undefined then has no effect on the program exit textcolor lightred puts "* Stopped *" textcolor # exit # Exit to O/S if desired # stop # Return to CLI if desired return 23 # Return ERRORLEVEL value to the O/S # Else exit to original start environment } Example: ticol.exe "proc at_exit {} {puts Done}"; test.tcl See also: upvar, run, cli, exit, stop, return, autoexec.tcl
atof, ftoa  Top  
double [atof <scientific-number-format-string>] string [ftoa value] Converts a string containing a number in "scientific notation" format e.g. "2e+10" into a double value. This will convert only within the range of an 8 byte double representation Scientific notation numbers are not implemented within [expr] in order to increase efficiency of the interpreter and since their use is likely to be quite low. This is a temporary/intermediate fix for the lack of "scientific" number handling within Ticol. [atof] may be embedded within [expr] expressions The inverse of [atof] is [ftoa] which will convert a floating point number in non "scientific" notation back to such. [format %e] may also be used to convert from standard to "scientific notation" format Examples: puts [atof 2e10] puts [atof 2e-5] puts [atof 32e+4] puts [ftoa 320000.000000] puts [atof 32.345e-4] puts [atof 0.001234e+6] set q "0.001234e+6" puts [expr [atof $q]*$pi] puts [ftoa [expr [atof $q]*$pi]] # Division and cast using scientific notation set a 2.2e1 set b 7 puts [/ [double [atof $a]] $b] Results: 20000000000.000000 0.000020 320000.000000 3.200000e+005 0.003235 1234.000000 3876.725334529804500 3.876725e+003 3.142857142857143 https://en.wikipedia.org/wiki/Scientific_notation See also: math
base64  Top  
string [base64 string | varName -encode | -decode ?-format width?] Base64 encode or decode a string or variable according to the argument parameter given. Where a -format value is given this will control line- wrapping on the returned base64 code. The default is no line-wrapping (0) The minimum -format width is 4 characters Example: set a [base64 "Hello world!" -encode] puts $a puts [base64 $a -decode] Result: SGVsbG8gd29ybGQh Hello world! Example: puts [base64 $qbf -encode] newline puts [base64 $qbf -encode -format 10] Result: VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZw== VGhlIHF1aWNr IGJyb3duIGZv eCBqdW1wcyBv dmVyIHRoZSBs YXp5IGRvZw== See also: encrypt, decrypt, mkn, cvn
Tips for Writing Big Programs  Top  
Ticol Tcl is intended for small scripts relating to administrative use. It was written by the author to be used for general housekeeping tasks as a simple alternative to PowerShell and batch script Here are some tips for developing larger programs: Make full use of [proc] Divide large scripts into many small procedures except where performance is critical and inline code required Use file-level modularity Break big scripts into smaller files and call using [eval scriptname] Be aware that each call to [eval scriptname] will evoke the macro preprocessor (MPP) which has a time cost Arguments to external files are permissible via [eval scriptname] Use the Macro Pre Processor For conditional execution, where appropriate Make full use of plugin libraries with [lib] A range of functionality is available via Ticol plugin DLLs See also: performance, faq, eval
bit  Top  
Currently, only one subcommand implemented [bit invert] integer [bit invert value ?-8|16|32|64?] Bitwise invert a value, optionally according to a given mask width The inversion mirrors or flips the bit pattern left-to-right 0x0001 -> 0x1000 The inversion is performed against the specified mask-width with a mask of 64 being the default Example: puts [inttobin [bit invert 1]] puts [inttobin [bit invert 1 -8]] puts [bit invert 0x0180 -16] puts [inttobin [bit invert 0x0180 -16]] puts [inttobin [bit invert 0b1100000000 -16]] Result: 0b1000000000000000000000000000000000000000000000000000000000000000 0b10000000 384 0b110000000 # 384 decimal 0b110000000 # 384 decimal See also: << >> ~
calc - Auto-optimising alternative to [expr]  Top  
calc <expression> ?-explain? calc {<expression>} ?-explain? calc "<expression>" ?-explain? calc <arg> <arg...> ?-explain? Inline Tcl commands are faster and more efficient than using [expr]. The Macro PreProcessor will expand [calc] natural 'infix' expressions into native Tcl commands using Polish 'prefix'-style notation [calc] is identical to [expr] and may be used in place of [expr]. It accepts the same expression format argument(s). However, unless the command-line argument /NEO (No Expression Optimisation) or the [option preprocessor off] directive is used, then the expression will be expanded and rewritten by the Macro PreProcessor (MPP) into native Tcl format commands before running. If /NEO is used then [calc] will be interpreted exactly as for [expr] The '-explain' argument is should be used only at the Ticol CLI rather than load/macro-preprocess runtime. It must also be the last argument in any test expression Example: # Example using -explain from the CLI option echo on calc 1+2/3.0-4*4 -explain puts [calc 1+2/3.0-4*4] Result: [- [+ 1 [/ 2 3.0]] [* 4 4]] -14.333333333333332 [calc] supports the same range of math operators as [expr] (excludes ++ and --) [calc] requires a bracketed declaration - Use [calc ...] not calc ... The translated command strings are typically around 50% faster than [expr] as [expr] has an error and syntax-checking overhead as well finally calling [eval] with the results. [calc] hugely speeds up performance by pre-processing this task before run time Ticol expressions are BEDMAS-optimised unless brackets are used to enforce ordering. Function calls are resolved to the [funct] command. If the command-line argument /NEO is used then [calc] will behave in exactly the same way as [expr]; This makes [calc] much more flexible as well as significantly improving perform performance on math tasks. In addition, this enables the '-explain' argument. If problems are encountered then use /NEO to disable [calc] translation and it will be interpreted as [expr] If the result of [calc] is a string value and if [option expression] is set to OFF and this value is passed to [eval] then the result may be misinterpreted as a command. The fix is to ensure that you use [option expression on] when handling string returns when chaining the result to [eval] You may examine the translated result using the /ECHO command line argument if manual checks are required on the translated expression Example: set f 3 puts [calc {$f+2-($f==2)}] Translation (requires ticol.exe /ECHO to output): puts [- [+ $f 2] [== $f 2]] Result: 5 Example: option PreProcessor off # Turn off MPP for the command line set s [calc 1/2.0+3*4 -explain] # Get the translated Tcl code puts $s # Display the Tcl code puts [eval $s] # Evaluate it and get the result option PreProcessor on # Turn the MPP back on again Result: (Expanded Tcl commands) [+ [/ 1 2.0] [* 3 4]] 12.5 [calc] will also attempt to simplify constant-only expressions by evaluation and then substitution. Disable using the /NEO command argument Example: puts [calc {[rnd 2 4] > 3 ? {return Higher} : {return "Same/lower"}}] Interpreted as: puts [? [> [rnd 2 4] 3] {return Higher} {return "Same or Lower"}] Result: Either Higher or lower Example: (save as script.tcl) # script.tcl set s [calc "1 / 2.0 + 3 * 4"] puts $s Run as: ticol.exe script.tcl /echo /neo set s [calc "1 / 2.0 + 3 * 4"] puts $s Run as: ticol.exe script.tcl /echo set s [12.5] puts $s ticol.exe script.tcl Note: (/NEO command-line argument) The /NEO (No Expression Optimisation) argument also applies when creating protected TCX files. Any TCX sub-file which needs to be run using the /NEO argument must be obfuscated using /NEO Note: (Excess {} braces) Do not wrap the entire expression to be passed to [calc] in braces or [calc] will be unable to interpret it. Braces prevent evaluation. Spurious error messages will result. Example: (WRONG - expression is 'masked' by braces) puts "a and b are: '[calc {{$a eq $b} ? {return equal}\ : {return different}}]" Example: (CORRECT) puts "a and b are: '[calc {$a eq $b} ? {return equal}\ : {return different}]" Note: (/NES argument) The /NES (No Expression Simplification) will disable automatic simplification and optimisation of expressions generated by [calc] Note that where [calc] const expressions are pre-evaluated and generate an error then this error will always be fatal and the preprocessing phase will halt. This feature can be disabled using /NES on the command-line Note also, that constants or variables with embedded # characters must be enclosed in double-quotes Example: puts [calc acos(10)] # Will evaluate to -1.#IND00000000000 (invalid) Note that the literal hash (#) comment character can be used safely within a quoted string See also: explain, expr, Macro PreProcessor, /NEO
Tcl Callbacks  Top  
Ticol Tcl procs can perform 'callbacks' to other Tcl procs where the name of a callback proc is passes via the initial command reference Example: option expression off proc test_callback {cbf} { puts "Enter test_callback -> '$cbf'" for {set j 0} {[< $j 10000]} {++ j} { if {[&& [> $j 0] [is_mod $j 1000]]} { [$cbf $j] # Call the callback proc } sleep 1 } } proc callback {x} { puts "In callback $x" } test_callback callback Results: Enter test_callback -> 'callback' In callback 1000 In callback 2000 In callback 3000 In callback 4000 ... See also: proc
Variable Casting  Top  
unsigned char [char value] # 8 bit unsigned signed short [short value] # 16 bit signed signed long [long value] # 32 bit signed signed integer [int value] # 64 bit signed unsigned integer [unsigned value] # 64 bit unsigned double [double value] # 8 byte FP Tcl is effectively a typeless language. It handles all variables internally as string values and, in most cases these are converted by Ticol to 64-bit integers or 8-byte floating-point doubles when necessary for arithmetic purposes All Ticol integers are stored as 64-bit signed integers, internally (See: data type ranges) Conversion and type detection is automatic. There may be cases, such as marshalling data for DLL interfaces, where you wish to coerce the type manually. Built-in Ticol casts are more efficient than casts written in Tcl script Non-decimal constants such as 0x1234 or 0o1234 are usually translated into decimal format before execution by the Macro PreProcessor (MPP). If the MPP is disabled using the /NP command-line option then translation is done on-the-fly. The work of unnecessary runtime conversion is therefore avoided by the MPP, but this might cause unexpected side-effects if a script relies on the original notation. If in any doubt, wrap such values in double-quotes, this will prevent MPP translation You may use the functions above to cast the string values to an appropriate type. This may involve the truncation of the value with loss of precision. [char] differs from [chr] in that [char] truncates any value to a valid char integer range whereas [chr] accepts only a fixed range of argument values (0..255) [signed] and [unsigned] will be coerced from 64-bit signed or unsigned integers with consequent 'wrap around' Appending ".0" to an integer will have the same math effect as a [double] cast Example: # Same effect from both concatenation of ".0" and [double] cast [12345].0 -> 12345.0 [double 12345] -> 12345.000000000000000 Numeric type conversions are built-in to Ticol. A cast will accept any kind of numeric input, decimal integer, decimal real, hexadecimal, octal or binary You will still have to specify byte widths when marshalling data for export via a DLL interface via [calldll*] Note again, that non-decimal number types such as hex (0xNN) which are not protected within quoted strings will be converted to decimal by the Macro Pre-Processor (MPP) before any script is run. This is designed to speed up execution Example: Result Comments -------------------------------------------------------------------------- puts [int $pi] 3 Cast a constant puts [char 12345] 9 Cast an integer puts [chr 12345] Overflow Invalid for [chr] puts [char 0b1111000] x Cast binary (0bX) puts [double 0b111100011011] 3867.000000000000000 Cast binary (0bX) puts [short 0o123] 83 Cast octal (0oX) puts [short 0x123ffff] -1 Truncated as short puts [int 0x123ffff] 19136511 Valid integer puts [double 0x123ffff] 19136511.000000000000 Valid double puts -1 -1 64-bit integer puts [unsigned -1] 18446744073709551615 64-bit integer puts [signed 18446744073709551615] -1 64-bit integer puts [signed 0xFFFFFFFFFFFFFFFF] -1 64-bit integer Code Example: option expression off for {set i 0} {< $i 64} {incr i} { puts "1 << $i == [unsigned [<< 1 $i]]" } See also: data type ranges, fpart, integral, asc, calldll, chr, error
catch  Top  
# With option expression off errorcode [catch {sourcecode} resultVariable] # With option expression on errorcode {[sourcecode]} resultVariable [catch] intercepts error returns from the source code expression which is passed to it and prevents the script from halting, instead returning a boolean value. If there is an error condition then 'variable' is set to the error message. [catch] returns a success code and the intercepted error code as a return value. The [catch] command operates at the level of Tcl error return values and does not provide any additional O/S CPU exception handling. [catch] returns 0 on SUCCESS and a non-zero value on error The non-zero value is a Tcl error code. See: error code The [catch] expression must be wrapped in braces and, if a command, the command must not be wrapped in square brackets or catch will evaluate the command return rather than the command itself and may fail. This behaviour is dependent on the [option expression] setting If the expression is successful then 'resultVariable' is set to the return value of the expression. It is important that the catch expression is wrapped in curved braces not square brackets as square bracketed expressions will be evaluated before the catch test Don't wrap an assignment within a [catch] statement unless you want to test the assignment itself. For example... # Where 'nosuchvar' does not exist, s is not set set s Hello catch {set s [string left $nosuchvar 1]} assert $s {ne $_ Hello} -v # This will fail to clear s # Use instead... option expression off catch {string left $nosuchvar 1} s Effective use of [catch] requires 'option echo off' as [catch] will handle the display of error messages rather than direct console output Within flow-control statements with: [option expression on] catch must be wrapped in square brackets to be evaluated otherwise it will be treated as an expression. Catch is most useful when combined with [if] (see below) See: error values for a list of returned error codes Example: option expression off if {[catch {set h1 [xbase open user.dbf]}]} { die "Failed to open database address.dbf" } Example: option echo off set file "nosuchfile.txt" # Note [catch] is wrapped in square brackets for [if] if { [catch { open $file r } err] } { # Any value > 0 puts stderr "Could not open $file for reading\n$err" exit 1 } Result: Could not open nosuch.txt for reading Exception raised from catch. Error code 1 Example: option echo off stack create s 1000 stack unset s catch {puts "Stack empty? [bool [stack is_empty s]]" } err puts stderr "Stack error\n$err" exit 1 Result: Stack error stack is_empty: Stack 's' not initialised Example: set line #__LINE__ if {[! [catch {puts 'pwd: [pwd]'} # Must be wrapped in braces ]]} { die "Failed to trap bad puts command at line: $line" } Result: # No error occurs Global variables are also set by internal error-handlers as follows: errorCode Tcl error code returned to the CLI errorLine May be set by the script using #__LINE__ errorMsg Console message generated by an internal error-handler See also: try, cmdcount, trace, error, run, time, debugging, flow control stop, exit, errorCode, errorLine, errorMsg, errorInfo, error values
ceil  Top  
integer [ceil double-value] Returns a double, rounded up to the nearest integer value Example: puts [ceil 7.6] puts [ceil 3.2] Results: 8 4 See also: floor, math, integer, double
clear  Top  
integer [clear ?-list?] Clear (unset) all user-level variables and consts System-level consts such as $env are unaffected. Although consts cannot be changed during the life of a script, the entire variable table may be cleared before running a new script. This prevents conflicts where scripts are loaded from the CLI. By default, [clear] returns the count of cleared variables Note that certain variables such as error* are recreated each time the Command Line Interface reloads Adding the '-list' argument will return a list of cleared variables instead of a count of variables cleared Ticol also maintains a small number of reserved system variables which are protected from deletion by [clear] or [run] The [run] command will also clear the user-level variable table The loaded script may be cleared using the command [load -clear] Example: puts [clear -list] Result: errorMsg errorLine errorInfo errorCode See also: clearprocs, reserved variables, load, unset, set, vars
charcount  Top  
integer [charcount string mask-chars ?-nocase?] Count the number of instances of each character in the mask in the input string. Case may be ignored using the -nocase argument Where $qbf is a standard test variable: "The quick brown fox jumps over the lazy dog" ... Each successive mask character is counted only once. i.e. the string is iterated against the mask and each string char is matched only once Thus [charcount $qbf Tt] and [charcount $qbf TTtt] both return 2 This applies also to -nocase where both [charcount $qbf Tt -nocase] and [charcount $qbf t -nocase] return 2 [charcount] is useful for checking the number of backslash escapes and estimating a shrinkage factor when a string is unescaped Escaped backslash characters - "\\" are counted as one character, otherwise each backslash is counted as one character and any non-backslash mask character which follows is counted as one character Example Result puts [charcount $qbf a] # 1 puts [charcount $qbf r] # 2 puts [charcount $qbf t] # 1 puts [charcount $qbf tT] # 2 puts [charcount $qbf t -nocase] # 2 puts [charcount $qbf tT -nocase] # 2 puts [charcount $qbf aeiou] # 11 puts [charcount $qbf fox] # 6 x o and f puts [charcount "\[puts \"hello\"\]" "\\"] # 4 \\ puts [charcount "c:\\windows\\system32\\" "\\"] # 3 \\ puts [charcount "c:\\windows\\system32\\" "ws\\"] # 8 w, s and \\ See also: chartok, char, string
chartok  Top  
integer [chartok string charmask array] [chartok] 'tokenises' (breaks apart) a string as delimited by characters specified in the 'charmask' argument and returns the individual components in a base 0 integer-indexed array. A count of the number of tokenised items in the array is returned The mask argument may comprise of one or more characters by which the string will be broken-up The mask characters are not included in the output. Typically a string will be split by spaces, tabs or CRLF pairs If the 'array' argument exists it will be overwritten without warning Example: option expression off set count [chartok $qbf " " a] for {set i 0} {< $i $count} {++ i} {puts $a($i)} Result: The quick brown fox jumps over the lazy dog Example: set s "Live-long and+prosper" set count [chartok $s "+- " a] for {set i 0} {< $i $count} {++ i} {puts $a($i)} Result: Live long and prosper See also: array, arrays, charcount, split, strto, strtor
clearprocs  Top  
integer [clearprocs ?filter? ?-nocomplain?] Clear all user-defined procedures from the current workspace If a 'glob' name filter is not given then * assumed (all procs) User procedures are all defined at scope level 0 (root/global) [clearprocs] returns a count of the number of procs which have been successfully erased. This may be used to cross-check with a list produced by [procs] [clearprocs] will terminate any [after] script which is proc dependent Example: option echo on procs puts [clearprocs] Result: cube rainbow square testmean 4 See also: clear, glob
Ticol Command Line Arguments  Top  
Syntax: ticol.exe <scriptname>?.tcl? ?/argument...? Syntax: ticol.exe ; "tcl script commands" The following command line switch options are accepted: /ECHO Echo preprocessed source code and exit Invalid for encrypted files /EXPR:<expression> Evaluate a Tcl expression (calls [expr expression]) Expression results can be piped back to scripts etc /ST Enable Stack Trace only. Will be displayed only if an exception occurs. Not valid for plugin DLL libs /CRLF Issue a CRLF after /EXPR (default is OFF) /LIB:libname?.dll? Load a Ticol plugin library DLL at startup /C[:OPT][outfile] Protect (encrypt) a Ticol source file Where OPT is one of the following options: <No option> Automatic encryption/decryption USER Lock to a Windows user name VERSION Lock to a Ticol version MAC Lock to a network card address WINVER Lock to a Windows version x.xx HOST Lock to a Windows host name PASSWORD Require a user-specified password Decryption is automatic except for /C:password If <outfile> is omitted then infile.tcx is created /64 Base64 encode the resulting TCX output produced with /C /PW:<password> A password phrase relevant to the above /C cases which will be used to encrypt the script The MD5 value is displayed on successful encryption /I Info. Show encryption information for a TCX file /G Show performance analysis graph at end of run /MD5 filename Display the MD5 value of a file (or: /MD5:filename) /NA No autoexec.tcl Don't load/execute autoexec.tcl /NOESC No MPP processing of escape sequences /NEO No Expression Optimisation of [calc] during preproc /NES No Expression Simplification of [calc] during preproc /NB No console I/O buffering /NP No Macro PreProcessor /NX No CLI autoexecute unknown commands (autoexec off) /NE Disable the exit command, disable CTRL+BREAK /SC Enforce Tcl standard comments /BP Enable breakpoints and single-step debugging This also enables the [halt] debugging command and stack trace /PAUSE Pause after execution (keep console window open) /Q Quiet mode. Don't show load/run/PreProcessor errors Use: ticol.exe /? to get details of command line arguments for the current version of Ticol Expressions are accepted if the first argument is specified as a semi- colon. Where this format is used, the entire expression must be wrapped at the command-line level, in double-quotes otherwise the following error may be encountered: Error: 1 too many [ brackets found Braces may be used within Windows CMD line arguments to delineate Tcl strings Examples: ticol.exe ; "puts [{hello world}]" ticol.exe ; "puts [cd {\\\\server\\share\\path}]" See also: argc, argv, command line interpreter, CLI
Ticol Command Line Interpreter (CLI)  Top  
This is an interactive shell within which Tcl commands may be directly executed. From here you can also run programs or interact with the O/S shell. The CLI is a single-line editor with a maximum line length of 4096 characters. Multi-line freeform editing is not supported. Command history is retrieved using the up/down cursor keys control the command history both at the CLI and within most text input routines Macro-preprocessing such as #ifdef...#endif won't apply to commands entered directly within the CLI. The [at_exit] command also not enabled from the CLI Scripts may be run using: run script?.tcl? or evaluated using: eval script The CLI returns the status error code in square brackets, followed by any applicable return value if 'option echo' is set to ON [x:status] <return-value> The primary Ticol status codes are: 0 OK/Success 1 Error condition. The 'error' command may give more information 2 Return statement encountered 3 Break statement encountered 4 Continue statement encountered 5 Exit condition encountered 6 Stop or abort condition (stop command, wrong arguments etc.) 7 goto operation encountered 8 Value already defined Commands are not echoed by default. To enable command console echo use the command: option echo on - or configure the ticol.ini file and add an entry: [Config] ConsoleEcho=TRUE Example: set a "Hello" set $a Result (at the CLI): [0:ok] Hello See also: command line arguments, Ticol, exec, autoexec, debugging, macro, ticol.ini
clipboard  Top  
clipboard get clipboard set string ?-append? clipboard clear clipboard isempty clipboard printscreen clipboard gettext Copy text to or from the clipboard. Optionally, clear the clipboard or check to see if it is empty. clipboard printscreen will capture the current window to the clipboard as an image [clipboard get] will retrieve ANSI text from a selected area in the console window. You can append to the clipboard using the -append argument [clipboard set] will place ANSI text into the clipboard [clipboard clear] empty the clipboard. It is recommended that you test for a non-empty clipboard and clear it prior to copying text to it. Note that the clipboard supports multiple data formats [clipboard printscreen] will grab the current visible console window as a graphic image equivalent to a PrtScrn operation [clipboard gettext] will retrieve 80 x 25 characters of ANSI text from cursor location 1,1 onwards in the current console. If the screen is scrolled after a [cls] command then only the first 2,000 ANSI characters will be returned. Select-zones are not supported by this command Other than clipboard printscreen, only text mode operations are supported See also: Single line commands, Ticol
Command Line Prompt String  Top  
The command line prompt can be configured via the TICOL.INI file using a subset of the DOS/Windows PROMPT characters as follows [Config] Prompt=<string> Where the default internal value is Prompt=$u@$h$g Which will return: user@host> Example: [Config] Prompt=$u@$h$s$k$g Result: Admin@Snoopy 132> Where: the string contains literal text and any of the following tokens: $c An opening curved parenthesis ( $g A greater-than symbol > $h The current hostname (if any) $f A closing curved parenthesis ) $k Command count (See: info cmdcount) $l A less-than symbol < $p The current path $n The current drive letter only, e.g. C $s A single space character $u The current username (if any) $_ A newline See also: cli, ini file, info cmdcount
Colour Constants  Top  
The following colour constants are defined. You may also use numeric values: 0 0x00 black 1 0x01 darkblue 2 0x02 darkgreen 3 0x03 darkcyan 4 0x04 darkred 5 0x05 darkmagenta 6 0x06 darkyellow 7 0x07 grey (gray) 8 0x08 darkgrey (darkgray) 9 0x09 blue 10 0x0a green 11 0x0b cyan 12 0x0c red 13 0x0d magenta 14 0x0e yellow 15 0x0f white Both 'grey' (UK) and 'gray' (US) spellings are accepted See the example file: colors.tcl Most modern versions of Windows will display "darkyellow" as a brown/khaki colour where orange would be more useful. You can change darkyellow to orange using the following REG file. Save as "console-orange.reg" and merge into the current session then log out and back in again to enable More recent versions of Windows will reset this colour at each boot --------------------------------------------------------------------- Windows Registry Editor Version 5.00 ; Colour table with DarkYellow == Orange 0x00c0c0c0 (BGR) [HKEY_CURRENT_USER\Console] "ColorTable06"=dword:00508dfc --------------------------------------------------------------------- See also: textcolor, textbackground
Conditional Operator - ?:  Top  
Command syntax: ? {test-expression} {true-expression} ?:? {false-expression} or: (using expr syntax): ( test-expression ? true-expression : false-expression ) Ternary (3 argument) or 'functional' if The first operand is evaluated and all side effects such as expression calls are completed before continuing to evaluate If the first operand evaluates to true (a nonzero value), the second operand is evaluated. If the first operand evaluates to false (0), the third operand is evaluated. The result of the conditional operator is the result of whichever operand is evaluated the second or the third. Whichever of the operand expressions applies will be evaluated using 'expr' and this may include other Tcl commands. To return literal strings use 'return string' Only one of the last two operands is evaluated in a conditional expression Note: Nested functional if commands should be avoided as these can lead to difficult-to-debug problems, bracket parity issues and possible stack overflow conditions in recursive code. Where a nested functional if must be used it is strongly recommended that each level is bracketed Arguments for the command version should be properly braced, particularly if the expressions contain commands wrapped in square brackets The functional if may be faster than an if command for simple expressions To return a string or other literal from the command form [?], use the [return] command. This is not necessary in the expression form Example: puts [expr "rnd(1,2) ==1 ? One : Two"] Example: set i 0; while {[< $i 5]} {puts [? [rnd 0 1] {return true}\ {return false}]; incr i} Result: false true true false true Example: # Command form [?] requires [] puts "[? [rnd 0 1] {return true} {return false}]" Result: (true or false) Infix functional [?] if expressions may be rewritten using the command version proc factorial {n} {? $n<2 1 : {? $n>=20 0 : {expr $n * [factorial [-- n]]}}} See also: flow control, if, else, while, for, foreach
Conversion Routines - mkn, cvn  Top  
string [mkn <numeric-value>] # Make a compressed number integer [cvn <mki-string>] # Convert a compressed number These commands are similar to Visual BASIC's Mki/Cvi, Mkf, Cvf functions They convert a decimal numeric string of any length into a compressed 4-bit encoding format which is universal to all decimal-based number types Large amounts of numeric data may be compressed or numeric data may be efficiently compressed for storage in say a database field This format does not embed nulls within the string and encodes a precise string representation rather than a binary translation. It encodes to precisely half the original string length The size of the numeric string is limited only by available memory The encoded character ranges is: "0-9 + - . <space>" Encoding pattern is as follows: ------------------------------------------------------------------ ASCII Value Input Encoding Symbol Comment ------------------------------------------------------------------ 48..57 0x1..0xa '0..9' Decimal digit 43 0xb 11 '+' Positive sign 44 0xc 12 ',' Comma (non-UK thousands separator) 45 0xd 13 '-' Negative sign 46 0xe 14 '.' Decimal point 32 0xf 15 ' ' Space 0 0x0 '\0' Reserved for C/C++ NULL terminator ------------------------------------------------------------------ Examples: puts [mkn 616] puts [mkn $pi] puts [mkn +3.14159] puts [cvn [mkn 3452345]] puts [cvn [mkn +3.14159]] Results (may include extended characters not reproducible here): rp N%&vFC@ Rj 3452345 +3.14159 Using [mkn], [cvn] to store float/double values in struct fields ---------------------------------------------------------------- Since [struct setb] stores integers only you must either store floats in string format or, if space is at a premium, you can encode them using [mkf] to create a compressed floating point number representation which can be stored and then retrieved using [cvn] Example: struct s {a 16 b 16} struct setb s.a 1234.5678] # Will truncate and store integer struct set s.b [mkn 1234.5678] # Will store full float value puts "s.a is: '[ofaddressb s.a]'" puts "s.b is: '$s.b' -> '[cvn $s.b]'" Results: 1234 1234.5678 Struct dump: struct 's' level 0 (0x1f389f0) data @32737744 (0x1f389d0) | 32 byte(s), 2 member(s) + 1:'->s.a' => 32737744 (0x1f389d0) 16 byte(s) + 2:'->s.b' => 32737760 (0x1f389e0) 16 byte(s) Address 0 1 2 3 4 5 6 7 8 9 A B C D E F ASCII -------- ----------------------- ----------------------- ---------------- 01f389d0 D2 04 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 01f389e0 23 45 E6 78 90 00 00 00 00 00 00 00 00 00 00 00 #E.x............ See also: base64, fromhex, tohex, inttohex, md5, crc, encrypt, decrypt
baseconv, convbase  Top  
integer [convbase number base] integer [baseconv number base] convbase can convert from an arbitrary base (2..16) to base 10 baseconv can convert from base 10 to any base (2..16) CAUTION: Do not prefix convbase inputs with a number-type prefix such as 0x or the Macro PreProcessor will preconvert to decimal before it is seen by the command Results are not prefixed with a type flag such as 0x Example: convbase 499602D2 16 convbase 1010 2 Result 1234567890 (Base 10) 10 (Base 10) Example: baseconv 10 2 Result 1010 The resulting numeric values are not prefixed by a type flag e.g. 0x, 0o or 0b See also: inttobin, inttohex, inttooct
beep  Top  
beep ?frequency? ?duration? Play a note. The default frequency is 700Hz and the default duration is 200ms Example: option expression off for {set i 100} {< $i 900} {incr i 100} {beep $i 100} Examples: beep 600 beep - 2000 Note that best performance is on systems which support the 8254 timer chip. This is emulated on Windows 7 via the sound card, and not at all on some versions of Windows. Performance may be very poor with emulated sound output Support for the Beep API was dropped in Windows Vista and Windows XP 64-Bit See: https://msdn.microsoft.com/en-gb/library/windows/desktop/ms679277%28v=vs.85%29.aspx See also: playwav
Using Ticol With Batch Files  Top  
It is possible to emulate the Linux 'shebang' system and create a batch- script which can automatically execute Ticol Tcl code within the same file The following batch script can be used as a stub-wrapper for Tcl code ::set - { @echo off rem ################################################################## rem Name: magic.bat rem Purpose: Command-line chaining test for Ticol Tcl rem Notes: Run as: magic.bat rem The initial enclosing [set] command is ignored by Tcl rem ################################################################## rem Check filetype using BATCH script if "%~x0" equ "" ( set SCRIPT=%0.bat ) if "%~x0" neq "" ( set SCRIPT=%0%~x0 ) ticol.exe %SCRIPT% %1 %2 %3 %4 %5 %6 %7 %8 %9 /na exit /b } # Start Tcl Code #################################################### textcolor magenta puts "Hello from Ticol Tcl" textcolor newline See also: Ticol, md5 batch example, autoexec.tcl, autoexec
in, ni  Top  
bool [in list value ?-glob|-nocase?] bool [ni list value ?-glob|-nocase?] Return a boolean indicating whether an element is in or not in a well- formed single-level Tcl list. Multi-level lists are unsupported. [lsearch] is more suited to complex list-searching A 'glob' style wildcard or case-insensitive search may be used. These options cannot be combined and -glob is case-significant Example Result # qbf: The quick brown fox jumps over the lazy dog puts [in $qbf fox] # 1 puts [in $qbf FOX -nocase] # 1 puts [in $qbf f?x -glob] # 1 puts [in $qbf f*x -glob] # 1 puts [in $qbf fred] # 0 puts [ni $qbf fox] # 0 puts [ni $qbf fred] # 1 See also: list, lsearch, lindex, llength
Ticol is a Tcl interpreter, not a compiler!  Top  
Ticol is a Tcl interpreter. This means that Tcl scripts are evaluated on-the-fly and are not translated into machine instructions for the CPU Interpreters are necessarily slower in terms of execution than any compiled language. Some other languages compile to an intermediate form (p-code) which is designed to run on a virtual machine (virtual CPU) and these can perform very fast and in some cases out-perform native compiled object code. However these languages are not interpreters in the truest sense. This means Ticol will be relatively slow and should not be used for tasks where performance is required For this reason it is vital to optimise Tcl scripts. One of the ways this is achieved is to use a Macro PreProcessor (MPP) to pre-process scripts and perform any necessary static translations, e.g. on non-decimal const numbers such as 0x123 and convert these to decimal values. C-like escape sequences such as \r or \n are also converted to literal characters. Ticol includes a number of non-standard Tcl commands which are designed to facilitate optimal performance. See: performance The command [calc] is an optimisable alternative to [expr]. This command will be optimised into simpler Tcl commands by the Macro PreProcessor unless disabled. If disabled it will be interpreted identically to [expr] See: Macro PreProcessor for more information See: https://en.wikipedia.org/wiki/Tcl See also: calc, Tcl, Ticol
binary (Experimental binary command)  Top  
binary set tcl-var escapedString ?-length x? binary set tcl-var binary tohex varname binary fromhex string varname binary base64 varname ?-encode? | ?-decode varname? binary length varname binary memcpy tcl-var source-address length Ticol uses uncounted ASCIIZ string which limits flexibility for use with binary strings which contain embedded NULL characters Ticol supports a few rudimentary binary operations. Note that where 'varname' is specified as an argument this should NOT be dereferenced as dereferenced strings are not handled as binary and will be truncated at the first NULL character. Binary strings cannot be returned from commands directly, so binary commands which return binary strings cannot be chained together (nested) If an argument variable does not exist then it will be created. If it exists and has content it will be overwitten. Useful for handling binary registry values. [binary] is not a full implementation of the Tcl [binary] command [binary] commands can not be used on non-binary variables binary set varname escapedString ?-length x? Set a standard Tcl variable with binary content binary tohex varname Return a hex interpretation of a binary variable binary fromhex string varname Convert a hex string to a Ticol binary variable binary base64 varname ?-encode ?varname?? | ?-decode varname? Returns the contents of a binary variable, base64-encoded or decoded. -encode is the default mode for this command If -decode is specified then the argument must be followed by the name of a new output variable. The output from -decode will/may be a binary string with embedded NULLs Where a variable name is specified the return value is a boolean Otherwise (for -encode with no varname), the return value is the encoded ASCIIZ string in base64 format binary length ticolVar Return an integer value representing the stored length binary memcpy varname sourceAddress length Copies data from memory address to a Tcl variable The Tcl variable will have memory allocated to hold the source The variable is marked as 'binary' and will have a length value The resulting binary string is "safe" and is null-terminated It may safely be printed using [puts] Notes: The Ticol Macro PreProcessor (MPP) will not allow \x00 or \x22 entries but these are correctly handled by [binary]. Remaining values are unescaped by the MPP before the script is loaded Example: binary set a \xfe\xffhello\x21\x00\x22world\x02\xff\xfe -length 18 puts "'$a!'" puts "binary length=[binary length a]" puts "tohex: '[binary tohex a]'" puts "base64: '[binary base64 a]'" Results: '.Hello' binary length=18 tohex: 'feff68656c6c6f210022776f726c6402fffe' base64: '/v9oZWxsbyEAIndvcmxkAv/+' Example: set a 23 binary memcpy b [addressofb a] 2 puts "\$b=='$b'" puts "binary length=[binary length b]" puts "string length=[string length b]" Result: $b=='23' binary length=2 string length=2 See also: set, tohex, encrypt, base64, tohex, fromhex
bintoint, inttobin  Top  
integer [bintoint binary-value] string [inttobin value ?-full? ?-noprefix?] [bintoint] converts a binary value to a decimal [inttobin] converts a decimal value to a binary string with the prefix "0b". Conversion of binary to decimal integer is automatic in Ticol Values are calculated as 64-bit integers Values given to intobin may be decimal integers, hexadecimal, octal or binary The optional ?-full? arg includes leading left-hand zeroes CAUTION ------- The Macro PreProcessor (MPP) will automatically convert octal values in the form 0bNN into decimal. Be cautious when passing unquoted binary values with "0b" prefix to [bintoint] Examples: option echo on inttobin 9223372036854775808 -full inttobin 666 -full inttobin 666 -noprefix inttobin 666 Results: 0b1000000000000000000000000000000000000000000000000000000000000000 0b0000000000000000000000000000000000000000000000000000001010011010 0000000000000000000000000000000000000000000000000000001010011010 0b1010011010 See also: big number, inttohex, inttoct
bool (boolean value)  Top  
string [bool value] Returns the string "true" or "false" depending on the input numeric value A non-zero value returns true, a zero value, false If the string "true" or "false" is given then 1 or 0 respectively is returned with the string being evaluated for a match Mappings: Input Result ---------------- 1 True 3 True -3 True 0 False x False True 1 TRUE 1 False 0 FALSE 0 true and false are defined as constants 1 and 0 respectively Examples: puts [bool 1] puts [bool true] puts [bool false] puts [bool [> [funct rnd 1 10] 5]] Results: true 1 0 true or false depending on [rnd] See also: math, string
box  Top  
Draw a graphic box box x y w h ?forecolour | -? ?backcolour? ?-solid? ?-nofill? Color may be a symbolic name such as 'blue' or a numeric value which corresponds with standard Windows console values (e.g. blue, cyan and these may optionally be prefixed with 'light', e.g. 'lightred') Both 'grey' and 'gray' are accepted. -solid will remove the border pattern and draw a solid box of 'backcolour' -nofill will draw only the box outline in 'forecolour' 'backcolour' is the box 'fill' colour 'forecolour' may be ignored when specifying 'backcolour' by using a - Displaying the box will change the cursor position. Use gotoxy to reset. gotoxy may also be used to draw within the box area Screen colours are reset back to defaults after a call to [box] If width w or height h is zero then a vertical bar or horizontal line will be drawn Examples: box 3 4 30 10 - lightcyan -solid box [rnd 1 20] [rnd 1 20] [rnd 5 30] [rnd 1 20] - lightcyan See also: msgbox, cls, gotoxy
Braces {} (Grouping) and Brace Style  Top  
Braces group Tcl commands including string characters. Braces may be nested Typically each call to a Tcl command unwraps one level of braces In some cases, double-quotes may be used to group words together. Note that single-quotes do not group, so ... puts 'Hello world' is not valid, whereas ... puts "Hello world" or ... puts {Hello world} is valid as braces may also delimit a string and can be useful where there would otherwise be nested double-quotes Braces delay evaluation and may be used strategically to prevent evaluation at a specific level. Evaluation may be forced using [subst] Each command-call removes one set of braces and evaluates the result Because braces delay evaluation for one level they will prevent variables from being replaced. Thus later evaluations which are dependent on such variables will fail Nested levels of braces, used outside of quoted strings may be used to prevent interpretation within the current context, i.e. to delay interpretation to a later evaluation in a sequence Braces may also be used to isolate concurrent variables within strings and to prevent misinterpretation of variables adjacent to literal string content e.g. in "$variablestring" -> "${variable}string" we want to isolate 'variable' from 'string' and dereference $variable but not 'string'. This is easier in languages which have a dollar suffix but Tcl has a dollar prefix which requires a more complex solution to strings 'buffering up' against each other Braces which fully-enclose variables name within strings do not delay evaluation and may also be used to distinguish variable names from string content which follows immediately-after e.g. set will_be_evluated_ok "Hello " puts ${will_be_evluated_ok}string Result: Hello string Braces may be used within lists to delineate groupings Example: set a "Goodbye " set b "cruel " puts "$a${b}world" Result: Goodbye cruel world Brace Style ----------- Tcl requires K&R style brace placement as the line end forms part of the command syntax. Failure to adhere to this style will cause fatal errors proc foo x { # Correct K&R Tcl style ... } proc foo x # Incorrect Allman/BSD C/C++ style { ... } See: https://en.wikipedia.org/wiki/Indent_style http://wiki.tcl.tk/708 See also: Tcl commands, double dereference, dereference, flow control, subst, eval, math, Tcl
call  Top  
call proc ?argument...? call command ?argument...? call "<tcl script>" Allows the calling of a procedure, Ticol command or scriptlet Similar to the function of CALL in legacy Visual BASIC. Call allows a proc to be called directly bypassing expression-evaluation, [trace] and /G graph statistics. [call] may also call procs which have been defined with numeric names A command can be called. In this case the normal evaluation chain is followed including [trace] and /G graphing Finally, a text script containing Ticol Tcl commands may be called Proc Example: proc 123 {} {puts "I am in bad proc 123"} [123] # Not called as [123] is evaluated as a number call 123 # Called successfully Result: I am in bad proc 123 Command Examples: option echo on call expr "sqrt(99)" Result: (Submitted via the CLI prompt) [0] 9.949874371066199 Script Example: call "textcolor magenta; puts {Hello } -nonewline ;\ textcolor red; puts world; textcolor" Result: (Submitted via the CLI prompt) Hello world See also: puts, eval, expr, foreach, sub, gosub, goto
External DLL Link Plugin - calldll*, calldll*_cdecl  Top  
To load, use: lib ticol_calldll ?-verbose? ?-nocomplain? Syntax: calldll* dllname?.dll? function-name|@ordinal arg arg... Safely call an external ANSI DLL routine. Both __stdcall and __cdecl DLLs are supported thus offering connectivity with a wide range of other applications including the Microsoft Visual C++ runtime (msvcrt40.dll), SQLite3, AutoIT and other DLLs which use standard interface methods Calling DLLs is not a trivial task an the marshalling of variables both outward and return can be quite complex and difficult to debug. The correct call-type (standard __stdcall or __Cdecl) must be used to match the DLL The DLL may be called either by name or by a handle returned from dll_open Additionally, an exported DLL function may be called by ordinal number by prefixing the ordinal with a @ symbol. e.g. puts "Is user an admin?: "[bool [calldll "Shell32" "@680"]] All arguments must be supplied, even if optional for the DLL interface Pass default NULL arguments as 0. Failure to supply sufficient arguments, even if defaults exist, will result in a [calldll] exception e.g. for C++ export prototype in foo.dll void __stdcall bar(LPSTR, long* = NULL); Pass: calldll foo.dll bar "Hello" 0 # Equivalent to passing NULL set r "000000000000000000000" # Ensure buffer is sufficient calldll foo.dll bar "Hello" r # And pass 'r; by reference struct r {s 21} # Create a small struct calldll foo.dll bar "Hello" r # And pass by reference Quotes around the dll and function name are optional, as is the DLL suffix It is usually recommended that calldll calls be wrapped inside a procedure Byte widths may be specified in arguments as 'var:<width>' e.g. 'data:4' If a variable or string contains a ":" character (e.g. in a Windows path), a byte-width MUST be specified. This feature is not ideal and will be improved in a future version Variables are passed by reference if a variable name is used and the variable exists, if prefixed by a $ then they are passed by value. If you pass a value which could be interpreted as a variable name then ensure you [unset] that name before calling [calldll] as detection is automatic. Passing a Tcl variable by reference does not guarantee sufficient allocated memory space to hold any return. Either the called DLL must allocate using malloc() or you should allocate a sufficient buffer by using [makestr] or asssigning a suitably large value using [set] Alternatively, you may pass the address of a single-member struct which has sufficient static buffer space in the member field. Literals, e.g. "Hello" or 23, are passed by value.for example Variant returns,including 1D and 2D string arrays are handled Passing the binary address of a variable buffer/string pointer by value may be forced by using [addressofb variable] to pass the literal buffer address (LPSTR in C++). [strptr] is an alias for [addressofb]. This is most useful for struct field address offsets. To pass the address of a Ticol string buffer within a variable (LPSTR* in C++) use [addressof]. Note that the string buffer is a field within a Ticol variable not the address of the variable in memory # Where 'funct()' is an exported __stdcall function in 'dllname.dll' set var 10 calldll dllname funct $var # Pass a variable by value calldll dllname funct var # Pass a variable by reference calldll dllname funct [addressofb var] # Pass a variable by reference calldll dllname funct [strptr var] # Pass a variable by reference Note: The Microsoft Visual C++ runtime (msvcrt40.dll) is compiled as a __cdecl DLL and calldll*_cdecl must be used to call it. Return types and calls ---------------------- Type Use ---------------------------------------------------------------------- long, short, void: calldll dllname|handle funct ?var...? You may also recast a long value to string pointer <type*> You may also cast any accessible type double, float: calldlldbl dllname|handle funct ?var...? string, bstr: calldllstr dllname|handle funct ?var...? variant calldllvariant dllname|handle funct ?var...? long, short, void: calldll_cdecl dllname|handle funct ?var...? double, float: calldlldbl_cdecl dllname|handle funct ?var...? string, bstr: calldllstr_cdecl dllname|handle funct ?var...? variant calldllvariant_cdecl dllname|handle funct ?var...? Return Error Codes ------------------- 0 No error 1 Invalid parameter passed 2 Failed to get handle to DLLNAME (poss. doesn't exist) 3 Can't get proc address to given function in existing DLL 4 Unhandled data type was passed via the VARIANT to CallDLL* Examples -------- Example: calldll_cdecl msvcrt40.dll printf "Hi from printf %i %f\n" 123 4.567 Result: Hi from printf 123 4.567000 Example: puts "Shell32 is user an admin: [bool [calldll shell32 @680]]" Result: true Example: puts "AutoIt is_admin: [bool [calldll AutoItX3.dll AU3_is_admin]]" Result: true Data Structures --------------- External API routines can often use structs. Ticol provides binary- compatible structs which can interface with both Ticol and external DLLs See: structs See also: calldllstr, calldll examples, dll_open, dll_close, struct, addressof, addressofb, strptr, ofaddress
calldll examples  Top  
Note: All examples require the statement: lib ticol_calldll -- set t 1470404087 # Fri Aug 05 14:34:47 2016 set ret [calldllstr_cdecl msvcrt40.dll ctime t] # Convert time_t to string puts "Result is ctime(FIXED-DATE): -"[string trim ret [chr 10]]- -- calldll user32 SetWindowTextA [calldll Kernel32 GetConsoleWindow] \ "Ticol Tcl" -- puts "Is user an admin?: [calldll Shell32 @680]" -- puts "is_admin: [bool [calldll AutoItX3.dll AU3_is_admin]]" true -- calldll_cdecl msvcrt40.dll printf "Hi from printf %i %f\n" 123 4.567 Hi from printf 123 4.567000 -- calldll mslib145 MapNetworkDrive "\\srv01\c[chr 36]" "q:" "" "" errcode 1 0 -- puts "proc mem: "[comma [calldll "mslib145.dll" "GetProcessMemoryUsed" \ [pid]]] -- proc ipfromhost {hostname} { return [calldllstr ping32 GetIPFromHostName $hostname] } -- puts "calldlldbl_cdecl->"[calldlldbl_cdecl msvcrt40.dll sqrt $pi] -- Example passing the address of a buffer by value to call a DLL: set timeout 0 set datalen 64 set buf [makestr 16] calldll ping32 PingAPI google.com [addressofb buf]:4 datalen:2 timeout:4\ 1000 Returns the string: 173.194.78.105 in variable 'buf' -- Example querying Windows OS version struct OsVersionInfo { {OSVSize 4} # long {dwVerMajor 4} # long {dwVerMinor 4} # long {dwBuildNumber 4} # long {PlatformID 4} # long {szCSDVersion 128} # char* x 128 bytes } setb OSVSize [struct size OsVersionInfo] 4 -value puts "GetVersionEx=[calldll kernel32 GetVersionExA OsVersionInfo]" puts "OSVSize: [ofaddressb OSVSize 4]" puts "dwVerMajor: [ofaddressb dwVerMajor 4]" puts "dwVerMinor: [ofaddressb dwVerMinor 4]" puts "dwBuildNumber: [ofaddressb dwBuildNumber 4]" puts "PlatformID: [ofaddressb PlatformID 4]" puts "szCSDVersion: [ofaddress szCSDVersion]" dump OsVersionInfo -- # Requires the author's vbsqlite3.dll port set QueryString "SELECT t1.ArtistName,CDs.Title,CDs.date, CDs.CDID\ FROM Artists t1, CDs\ Where t1.ArtistID = CDs.ArtistID\ ORDER BY ArtistName, CDs.Date ASC " set dbfile ".\\test.db" set handle [dll_open "vbsqlite3.dll"] set r [calldll $handle sqlite3_open [strptr dbfile] db] set vr [calldllvariant $handle sqlite_get_table_basic $db:4 $QueryString] set rows [varray count $vr] set cols [varray count $vr 2] set dims [calldll $handle "GetArrayDimensions" $vr] puts "Table has $rows rows and $cols columns and $dims dimensions" calldll $handle sqlite3_close $db dll_close handle -- # Requires the author's VB Toolbox DLL set handle [dll_open mslib145.dll] calldll $handle LoadIPHLPAPI set adapters [calldll $handle GetAdapterCount] puts "Querying $adapters adapter(s)..." option expression off # No reason other than as a demo for {set i 0} {< $i $adapters} {++ i} { # uses eval not expr set addr [ofaddressb [calldllstr $handle GetIPAddress $i]] set name [ofaddressb [calldllstr $handle GetAdapterDescription $i]] puts "$i: [left $name 40] -> $addr" } dll_close handle -- See also: calldllstr, calldll, calldll_cdecl, single line commands
calldllstr, calldllstr_cdecl  Top  
To load, use: lib ticol_calldll ?-verbose? ?-nocomplain? Syntax: calldllstr dllname?.dll? function-name|@ordinal arg arg... calldllstr_cdecl dllname?.dll? function-name|@ordinal arg arg... Call a DLL which returns a string result, exported as a Tcl string If there is a need to dereference or address a returned pointer, e.g. to release memory allocated by the DLL call then you must use [calldll] instead and use the returned integer pointer address value. When a Tcl string is returned then the original address will be lost Static references to strings returned via [calldll] will return a reference to some part of an external variable. When [calldllstr] is used the original string (pointer address) reference is lost. No attempt should be made therefore, to release values returned by [calldllstr] other than using standard Tcl methods such as [unset] [calldllstr_cdecl] is used to call DLLs compiled with the __cdecl DLL calling convention. Use [calldll_cdecl] to return an address value If memory wasn't allocated by the DLL call then any return address returned by [calldll] when returning a string may be discarded. A null address will return 0 Example: # Uses shell32 StrChrA to locate a substring by character match # Shows differences between addressof and addressofb # and use of ofaddressb to dereference set s "Hello World" puts "addressof s [addressof s]" # Note how these addresses differ puts "addressofb s [addressofb s]" # This is the var string address puts "calldll: H is '[calldllstr shell32 StrChrA [addressofb s] [asc H]]'" set ptr [calldllstr shell32 StrChrA [addressofb s] [asc W]] puts "StrChrA($s,W) offset should be 'World' -> '[ofaddressb $ptr']" See also: calldll
carray plugin  Top  
To load, use: lib ticol_carray ?-verbose? ?-nocomplain? Syntax: handle [carray create ?size?] bool [carray add handle lval ?rval?] carray delete handle index integer [carray count handle] string [carray item handle index ?-rval? ?-list?] carray foreach handle lvalue ?rvalue? {code} carray sort handle ?-reverse? carray walk handle bool [carray unset handle ?-nocomplain?] Emulates "C"-like fixed arrays rather than associative arrays. Fixed arrays are indexed using 'base zero' integer index values and may be sorted, [carray] can optionally store an "Rvalue" string as well as the required "Lvalue". Multi-dimensional arrays are not supported create # Can pre-allocate memory to a given number of elements add # Adds an lvalue and, optionally, a corresponding rvalue # An Rvalue only may be added by specifying the Lvalue as {} delete # Removes an item by index (both Lvalue and any Rvalue) count # Returns a count of items in the array sort # Can sort the array in normal or reverse order. Note that fixed # arrays are not as efficient at sorting as associative arrays # and it may be impractical and slow to sort very large arrays item # Index the array by integer subscript foreach # Offers a means of iterating each element of the array in # ascending integer storage order. [foreach] is affected by # the internally-sorted order of the array walk # Is useful for debugging. It will iterate the array elements unset # Destroys the array and renders the handle unusable. Using # the handle after a call to [unset] will result in an error Example: set h [carray create] carray add $h Quick Brown carray add $h Fox Jumps carray add $h Lazy Dog carray add $h LValue carray add $h {} RValue carray sort $h carray foreach $h lv rv { # foreach iterator example puts "Lvalue:'$lv'\tRvalue:'$rv'" } carray sort $h -reverse set count [carray count $h] puts "We have $count item(s)" for {set i 0} {[< $i $count]} {++ i} { # Loop example puts "Item $i: '[carray item $h $i]'\t'\ [carray item $h $i -rvalue]'" } Results: Lvalue:'' Rvalue:'RVonly' Lvalue:'Fox' Rvalue:'Jumps' Lvalue:'Hello' Rvalue:'World' Lvalue:'LVonly' Rvalue:'' Lvalue:'Lazy' Rvalue:'Dog' Lvalue:'Quick' Rvalue:'Brown' Item 0: 'Quick' 'Brown' Item 1: 'Lazy' 'Dog' Item 2: 'LVonly' '' Item 3: 'Hello' 'World' Item 4: 'Fox' 'Jumps' Item 5: '' 'RVonly' Advantages and Disadvantages ---------------------------- Unlike associative arrays, "C" arrays can have an inherently ordered (sorted) state. They are, on average, slower to insert/add new records and sorting a large array may take a long time and searching a record on an unsorted array will usually be much longer than a hashtable- based associative array. Deleting All Nodes ------------------ As the count will change after each call to [carray delete] the following method should be used to iterate through and delete all nodes: set i 0 while {[> [carray count $h] 0]} { carray delete $h 0 # Delete the first record } A naive [for] loop which iterates the count with a fixed index won't work # Won't work as [carray count] changes after each [carray delete] for {set i 0} {[< $i [carray count $h]]} {++ i} { carray delete $h $i } See also: plugins, arrays
Ticol CGI Web Plugin  Top  
To load, use: lib ticol_cgi ?varname? A rudimentary command to process CGI server POST input as a CGI (Common Gateway Interface) application and splits into an array variable The default variable name is _POST but this can be changed by passing an alternate name as an argument Ticol can be used to generate a modest CGI 'back-end' system including database using SQLite or XBase. The language is not, however, recommended for commercial or industrial CGI use Syntax: integer [cgi get ?-var name?] string [cgi arg name ?-nocase?] # Match QUERY_STRING bool [cgi argfound name ?-nocase?] # Match QUERY_STRING string [cgi post name ?-nocase?] # Match POST value bool [cgi postfound name ?-nocase?] # Match POST value Where 'varname' is an optional alternative to the default var, '_POST' Errors: To avoid fatal errors within a CGI script, all errors other than a fatal exception are non-fatal and will return code 'OK' an error code as follows >0 SUCCESS Count of items returned 0 No items returned from POST -1 Failed to initialise library -2 Incorrect argument count -3 CONTENT_LENGTH was not set -4 CONTENT_LENGTH <= 0 -5 CONTENT_TYPE was not set -6 REQUEST_METHOD not set to POST -7 Unknown/unhandled error Example: Front-end form <!- Web form --> <html> <head> <title>Test Form</title> </head> <body><pre> <form name="A" method="POST" action="/cgi-bin/ticol.exe?cgi_post.tcl" enctype="multipart/form-data" encoding="multipart/form-data"><p> Enter your name: <input type="text" name="name" size="30"><p> Enter some text: <input type="text" name="text" size="40"><p> <input type="submit" value="Submit" name="button1"; <input type="reset" value="Reset" name="button2"><p> </form></pre></body> </html> Tcl back-end script option expression off puts "Content-type: text/html\r\n\r\n" # Be sure to send this first lib ticol_cgi -nocomplain set s [cgi] # Call to set $_POST if {> $s 0} { # Test for -ve error return puts "<font color=\"blue\"><strong>" array foreach _POST val subscript { puts "<br>Result \$_POST($subscript)='$val'<br>" } puts "</strong></font>" } Result: <Depends on data typed into the input form> See also: plugins
Ticol CPU Information Plugin  Top  
To load, use: lib ticol_cpu ?-verbose? ?-nocomplain? Shows various low-level CPU information by directly accessing the CPU Syntax: string [cpu name] # The full, descriptive name of the CPU string [cpu vendor] # The CPU vendor, e.g. "GenuineIntel" integer [cpu bitness] # The underlying O/S bitness, (32 or 64) integer [cpu cores] # Estimate the number of available cores bool [cpu hyperthreading] # Hyperthreading supported. Returns 1 or 0 bool [cpu hypervisor] # Running on hypervisor. Returns 1 or 0 integer [cpu eax] # eax register return as integer integer [cpu ebx] # ebx register return as integer integer [cpu ecx] # ecx register return as integer integer [cpu edx] # edx register return as integer Not all VMs will show hypervisor enabled. Some VMs will emulate the CPU entirely, others will use the underlying CPU but may disable some features The number of cores is an estimate and may be incorrect. The operating system may disable cores as it wishes Examples: lib ticol_cpu puts [cpu name] puts [cpu vendor] puts [cpu bitness] puts [cpu cores] puts [cpu hypervisor] puts "Virtual Machine Extensions " -nonewline if {& [cpu edx] 0x2} { # Test edx bit 2 puts "present" } else { puts "not present" } Results: Intel(R) Core(TM) i5 CPU M 540 @ 2.53GHz GenuineIntel 64 4 FALSE Virtual Machine Extensions present See also: plugins
concat  Top  
string [concat string ?string ...?] Efficiently concatenate one or more strings and return the result [concat] treats each argument as a list and concatenates them into a single list. It permits any number of arguments. The arguments are unchanged [concat] is much faster at accumulating strings than using chained [set] operations as the original source string is not repeatedly passed via the Ticol interpreter and parsed To concatenate items to a variable see [append] or [store] Example: puts [concat The quick brown fox jumps over the lazy dog] Result The quick brown fox jumps over the lazy dog Example: concat a b {c d e} {f {g h}} Result: a b c d e f {g h} See also: append, store, setat, cmp, set, variable, performance
cset  Top  
integer [cset varName string ?length?] Insert a source string into a variable's contents, centrally padded, optionally for 'length' characters. The target variable is not truncated Any value for 'length' < 0 will be ignored. Any value for 'length' greater than the source string length or variable length will be ignored The number of characters copied from the source string will be returned If varName is empty then the request will be ignored and 0 will be returned Use [lset] and [rset] to align left and right Example: set s [makestr 30] set r [cset s Hello] puts '$s' puts $r Result: ' Hello ' 5 Example: set s "" set r [cset s Hello] puts '$s' puts $r Result: '' 0 See also: lset, rset, string
chdir  Top  
cd path chdir path Change the current directory. Does not support wildcard * chdir prefix Both forward and backslash characters are accepted Where cd is called from the command-line as a script expression, remember to escape all backslash characters and any reserved Tcl character such as the dollar ($) sign UNC paths are accepted but can have no action relative to a current, fixed drive-letter: Examples: cd.. cd .. cd \\rootdir cd \\rootdir\\subdir cd \\\\server\\share\\path # Will have no action relative to path cd \\\\server\\c\$\\path # Note that $ must be escaped cd /rootdir cd /rootdir/subdir cd //server/share/path # Will have no action relative to path cd //server/c\$/path # Note that $ must be escaped See also: mkdir, mkdirs, getcwd, file, pwd
chr  Top  
string [chr n ?added-offset-value?] The inverse of asc. Returns character number 'n' as a string The argument 'n' must be an integer value, not a character [chr] also permits a value to be added. This is useful where an integer is converted into an ASCII letter e.g. 0 -> 'a', 1 -> 'b' and avoids an additional and time-consuming call to [+] to calculate the ASCII value Example: puts [chr 65] Result: A Example: set i 2 puts [chr $i 97] # Add offset: character 2 + 97 Result: c See also: asc, string, left, right, mid, index
chomp  Top  
string [chomp var ?-leave?] string [chomp var N ?-leave?] [chomp] takes only a variable name as its argument and is a non-standard command to efficiently slice-up large strings. If an argument length is not specified, then [chomp] removes and returns characters up to and excluding the next whitespace character as one of "\r\n\t ". If an argument length, 'N' is specified, [chomp] removes and returns 'N' characters from the left-hand side of a string. The remainder of the characters not removed are left in the variable The source variable will have the returned characters removed and they are thus 'eaten' or 'chomped' away unless the '-leave' argument is used [chomp] is faster and more memory-efficient with very large strings than compounding [set] and [mids] or [set] and [string left] etc. If argument N is larger than the string length then an whole string is returned. If the source variable is empty then an empty string is returned chomp var N # Removing N characters is equivalent to mids $var [+ N 1] # this command Example: set s $qbf chomp s 1 # Removes 1 character and saves 2nd char onwards puts $s set s $qbf puts [mids $s 2] # Returns 2nd character onwards Results: he quick brown fox jumps over the lazy dog he quick brown fox jumps over the lazy dog See also: mids, left, string, string left
clock  Top  
Standard Tcl time/date routines Returns dates or times in the Unix epoch (01/01/1970) integer [clock clicks|seconds|milliseconds] string [clock format seconds|now ?-format "%Y-%m-%dT%H:%M:%S"?] Where seconds must be a positive integer See also: clock scan, clock split The -format option controls what format the return will be in The contents of the string argument to format has similar contents as the format statement Additionally, there are several more %* descriptors which can be used to describe the output. %a Abbreviated weekday name (Mon, Tue, etc.) %A Full weekday name (Monday, Tuesday, etc.) %b Abbreviated month name (Jan, Feb, etc.) %B Full month name (January, February, etc.) %d Day of month %j Julian day of year %m Month number (01-12) %y Year in century %Y Year with 4 digits %H Hour (00-23) %I Hour (00-12) %M Minutes (00-59) %S Seconds(00-59) %p PM or AM %D Date as %m/%d/%y %r Time as %I:%M:%S %p %R Time as %H:%M %T Time as %H:%M:%S %Z Time Zone Name The default -format mask is "%a %b %d %H:%M:%S %Y" Examples: Command: Result clock clicks # 80579 clock seconds # 1425214130 clock format now -format "%Y %m %d" # 2015 03 01 clock format 9999 -format "%Y %m %d %H:%M:%S" # 1970 01 01 02:46:39 Example: puts [clock format [double_to_ctime [now]] -format "%Y/%m/%d %H:%M:%S" Result: 2015/04/08 12:15:41 Example: puts "[clock milliseconds] v's [clock seconds]" Result: 1512702231579 v's 1512702231 See: clock, clock scan, clock scan workaround See also: clock format, clock scan, clock scan workaround, clock split, time, date, ticks, double_to_ctime, ctime_to_double, date_to_ctime, now, vars, is_dst
clock format  Top  
string [clock format seconds|now ?-format "%Y-%m-%dT%H:%M:%S"?] Format codes for the clock -format string are as follows. These are standard C/C++ formatting codes with a couple of extra Tcl codes %a Abbreviated weekday name %A Full weekday name %b Abbreviated month name %B Full month name %c Date and time representation appropriate for locale %D Day of month as a decimal number with no 0 prefix (1..31) %d Day of month as decimal number (01..31) %H Hour in 24-hour format (00 .. 23) %I Hour in 12-hour format (01 .. 12) %j Day of year as decimal number (001..366) %m Month as decimal number (01 .. 12) %M Minute as decimal number (00 .. 59) %N Month of the year as a 1 or 2 digit number (1..12) %p Current locale's A.M./P.M. indicator for 12-hour clock %o Day of month ordinal. E.g. "st", "nd", "rd", "th" %S Second as decimal number (00 .. 59) %U Week of year as decimal number, Sunday as first day of week (00..51) %w Weekday as decimal number (0 .. 6; Sunday is 0) %W Week of year as decimal number, Monday as first day of week (00..51) %x Date representation for current locale %X Time representation for current locale %y Year without century, as decimal number (00 .. 99) %Y Year with century, as decimal number %z Time-zone name or abbreviation; no characters if time zone is unknown %Z Ditto %% Percent sign Example: puts [clock format 0 -format "%A, %D%o %B %Y"] Result: Thursday, 1st January 1970 Example: puts [clock format now -format "%A, %D%o %B %Y %H:%I:%S"] Result Wednesday, 4th October 2017 20:04:37 Example: puts [clock format [date_to_ctime 1972 04 04] -format %D%N%y] Result: 4472 See also: clock, clock split, clock scan, clock scan workaround, time, date
clock scan  Top  
clock scan <date> [clock scan] accepts input in the following common formats US date format - 'MMM DD ?HH:MM:SS?' US date format - 'MMM DD YY ?HH:MM:SS?' US date format - 'MMM DD YYYY ?HH:MM:SS?' US date format - 'MMM DD, YY ?HH:MM:SS?' US date format - 'MMM DD, YYYY ?HH:MM:SS?' US date format - 'MMMM DD ?HH:MM:SS?' US date format - 'MMMM DD YY ?HH:MM:SS?' US date format - 'MMMM DD YYYY ?HH:MM:SS?' US date format - 'MMMM DD, YY ?HH:MM:SS?' US date format - 'MMMM DD, YYYY ?HH:MM:SS?' US date format - 'DD MMM ?HH:MM:SS?' US date format - 'DD MMM YY?HH:MM:SS?' US date format - 'DD MMM YYYY?HH:MM:SS?' US date format - 'DD MMMM ?HH:MM:SS?' US date format - 'DD MMMM YY ?HH:MM:SS?' US date format - 'DD MMMM YYYY ?HH:MM:SS?' US date format - 'MM/DD ?HH:MM:SS?' US date format - 'MM/DD/YY ?HH:MM:SS?' US date format - 'MM/DD/YYYY ?HH:MM:SS?' US date format - 'DD/MM ?HH:MM:SS?' US date format - 'DD/MM/YY ?HH:MM:SS?' US date format - 'DD/MM/YYYY ?HH:MM:SS?' Where: MM is a 2-digit month value MMM is a 3 character month name MMMM is a full month name DD is a 1 or 2 digit day YY is a 2 digit year > 100 AD, where > 50 -> 19xx and <= 50 -> 20xx YYYY is a 4 digit year The output is always limited to the start of the Unix time epoch - 1970/Jan/01 00:00:00 (0) [clock scan] can be emulated for various date formats using [scan] and [date], Example: # Scan an ISO date into [date] format scan 20161122 %4i%2i%2i y m d puts "$y/$m/$d" Result: 2016/11/22 Checks are made only on each individual parameter. No check is made for the validity of the entire date string. See: clock scan workaround Example: set a [clock scan "Jan 12, 1992"] set b [clock scan "Jan 12, 1997"] puts $a puts $b puts "Difference is [- $b $a]" Results: 695174400 853027200 Difference is 157852800 second(s) The result of [clock scan] can be converted from a "C" integer time value to double using [ctime_to_double]. This value can then be manipulated as an ISO date string using [date] Example: set b [clock scan "Jan 12, 1997, 23:59:12"] puts [date [ctime_to_double $b]] Result: 1997/01/12 23:59:12 Error Codes ----------- 1 Bad slash separator count 2 Day value < 1 || > 31 3 Month value < 1 || > 12 4 Missing value field 5 Resulting date is invalid 6 Unhandled error See also: clock scan workaround, clock, clock_split, date, time, scan, is_dst
Clock Scan Workaround  Top  
[clock scan] is not fully-implemented as the date inputs are too widely varying to be practical. Using the popular Tcl example code we can demonstrate an easy workaround using [scan] and [date] # We replace: set bookSeconds [clock scan $halBirthBook] set h 00 set i 00 set s 00 set halBirthBook "Jan 12, 1997 01:02:03" set count [scan $halBirthBook "%s %s %s %02d:%02d:%02d" m d y h i s] puts "Scanned $count item(s)" set d [string trim d ,] puts "date string $y/$m/$d $h:$i:$s" set bookSeconds [date $y/$m/$d $h:$i:$s -ctime] puts "bookSeconds=$bookSeconds" newline # We replace: set movieSeconds [clock scan $halBirthMovie] set h 00 set i 00 set s 00 set halBirthMovie "Jan 12, 1992 23:59:01" set count [scan $halBirthMovie "%3s %s %s %02d:%02d:%02d" m d y h i s] puts "Scanned $count item(s)" set d [string trim d ,] puts "date string $y/$m/$d $h:$i:$s" set movieSeconds [date $y/$m/$d $h:$i:$s -ctime] puts "movieSeconds=$movieSeconds" newline set diffseconds [expr $bookSeconds - $movieSeconds] puts "The book and movie versions of '2001, A Space Odyssey' had a" puts "discrepancy of $diffseconds second(s) [/ $diffseconds 86400] day(s)\ in how" puts "soon we would have sentient computers like the HAL 9000" Based on example from: https://www.tcl.tk/man/tcl8.5/tutorial/Tcl41.html See also: clock, clock scan, clock split, date, time, scan
clock split  Top  
[clock split seconds ?days|-? ?hours|-? ?minutes|-? ?seconds|-?] Splits a number of seconds into variables containing an absolute number of days, hours, minutes or seconds Each variable argument is optional but at least one variable argument must be present. Arguments must be in order of days, hours, minutes and seconds. Arguments may be skipped by using a "-" placeholder Variable arguments must not exist Example: puts [clock split 3601 d h m s] puts "$d day(s) $h hour(s) $m minute(s) $s second(s)" Result: 4 0 day(s) 1 hour(s) 0 minute(s) 1 second(s) Example: puts [clock split 3601 d h m s] puts "$d day(s) $h hour(s) $m minute(s) $s second(s)" Result: 4 Example: puts [clock split 86461 d h m s] puts "$d day(s) $h hour(s) $m minute(s) $s second(s)" Result: 4 1 day(s) 0 hour(s) 1 minute(s) 1 second(s) Example: puts [clock split [now -ctime] d h m s] puts "$d day(s) $h hour(s) $m minute(s) $s second(s)" Result: 4 17522 day(s) 12 hour(s) 42 minute(s) 49 second(s) See also: clock, clock scan, time, date
close, file close  Top  
close handle file close handle Close a file-handle previously returned from the open command Handle must be > 0 and a valid stream handle [puts] may be used to write to the file Example: set fp [open "input.txt" w+] puts $fp "test" close $fp See also: open, gets, file
cls  Top  
cls Clears the console window See also: console
cmdcount (Command Count)  Top  
integer [cmdcount] integer [cmdcount script|command ?var?] Similar to [catch], dcount will either show the current count of commands executed or will execute a command or script and return a count of the number of commands which were executed. Along with the [time] command this may be useful for profiling and optimising Tcl scripts Example: puts [cmdcount] # Show the current command count Result: 1 Example: puts [cmdcount {puts "Hello"}] # Command cost of running this command Result: 1 Example: puts [cmdcount {run test.tcl}] Result: 2786 See also: debugging, time, trace, catch
cmp (Compare)  Top  
bool [cmp var|string1 string2 start-pos ?len? ?-ignorecase?] Efficient compare function. Avoids the need to extract string segments for comparison by comparing directly within the string. Either a variable or a string-literal may be given. The start position is indexed at a base 1 offset. You may also perform a case-insensitive comparison using -ignorecase Example: (Detect C style opening comment) option expression off for {set i 1} {< $i $count} {incr i} { if { cmp data "/*" $i 2 } { incr i 2 set in_comment $true } } See also: cat, eq, ne, efficiency
comma  Top  
string [comma string ?separator-char?] Comma-formats a numeric value. Optionally, the separator character may be customised Example: puts [comma 1234567890] Result: 1,234,567,890 Example: puts [comma 1234567890 " "] Result: 1 234 567 890 Example: puts "[comma [/ [filesize "ticol.exe"] 1024]] Kb" Result: 214 Kb See also: format
commands  Top  
list [commands ?filter?] Returns a list of all known/registered commands and procs A filter may be used to select by filter prefix match Example: commands sc Result: scan screen [is_command] may be used to test for the presence of a defined command or proc A count of commands registered may be obtained using: puts [lcount [commands]] Use: option echo on to display directly to the console See also: Tcl commands, commands by function, info, is_command, vars, help, exit
Ticol Command Line  Top  
ticol.exe filename[.tcl] [arg ...] [/switches] ticol.exe ; [statement ...] [/switches] Running Tcl scripts from the Windows command-line: If the first argument to ticol.exe is a Tcl script then this will be loaded and executed after running any autoexec.tcl file (unless /NA is specified) Any subsequent arguments can be accessed from the argv() array See: argv Using Ticol as a command-line expression-evaluator from Windows: You can call Ticol with Tcl commands if you prefix them with a semi-colon character as the first command-line argument and quote the remainder when necessary. This avoids Ticol attempting to run a Tcl script file ticol.exe ; "puts [+ 1 1]" ; Embedded double quotes may be escaped in Windows using \" e.g. ticol.exe ; "puts [expr \"22/7.0\"]" ; or you may use the /EXPR command-line argument. This will evaluate and return the result by calling [expr] ticol.exe ; "/expr:22/7.0" The semi-colon variant can handle multiple arguments in the same interpreter context: Example: ticol.exe ; "set a 4" "printf \"Pi is %3.2f\r\n\" \ [calc round(4*atan(1),2)]" "puts [expr $a*3]" /na Result: Pi is 3.14 12 Example: ticol ; "load test.tcl; run" ticol.exe ; "puts [expr \"22/7.0\"]" ; "puts \"hello world\"" ; "for \ {set i 0} {< $i 3} {++ i} {puts $i}" Result: <runs script test.tcl and then returns to the O/S> 3.142857142857143 hello world 0 1 2 Expressions with embedded spaces, commands etc. must be wrapped in double-quotes. Embedded double-quotes may be escaped ticol "/expr:[cube 3]" /debug # works OK ticol /expr:[cube 3] /debug # does not ticol "/expr:\"Hello world\"" /na # puts not required Calling from Windows Batch Script FOR Command --------------------------------------------- The Windows FOR command will require usebackq and backtick wrappers to use double-quotes around any Tcl /EXPR command which contains spaces for /F "tokens=* usebackq" %%i in (`ticol.exe "/expr:round(22/7.0,4)"`) do ( set RESULT=%%i ) echo Ticol expression result for 22/7.0 is %RESULT% for /F "tokens=* usebackq" %%i in (`ticol.exe "/expr:4*atan(1)"`) do ( set RESULT=%%i ) echo Ticol expression result for 4*atan(1) is %RESULT% /EXPR may also be used to call external __stdcall or __cdecl DLLs ... for /F "tokens=* usebackq" %%i in (`ticol /expr:"[calldlldbl_cdecl \ msvcrt40.dll sqrt 10.0]" /na`) do ( set RESULT=%%i ) echo Result for [calldlldbl_cdecl msvcrt40.dll sqrt 10.0] is %RESULT% The Windows FOR command requires no CRLF to be issued. You can add a CRLF to the output by adding the /CRLF argument See also: command line, command line arguments, Ticol, commands
Tcl Commands  Top  
string [command ?arg...?] A Tcl command is some alpha string which is most often contained within square brackets If a known/registered command string is met outside of a quoted string it will be executed without the need to be wrapped in square brackets. Thus, in puts "Hello world" the command, [puts] does not need to be wrapped in [] Unless evaluation is delayed by wrapping in braces, commands are evaluated recursively within strings before the string or command- sequence is evaluated Thus... puts "Hello [chr [+ 80 7]][chr 111][chr 114][chr 108][chr 100]" will display Hello world The innermost [+ 80 7] command is resolved first, then the result, [chr 87], followed by [chr 111] ... The command may have optional arguments. Most Tcl commands take arguments, whereas a few do not. Thus [stop] takes no arguments whereas [puts] does. Arguments act as modifiers of a command similar to 'attributes' in certain languages such as C# Tcl commands use "Polish" type prefix notation where an operator or command appears first, followed by any arguments. Flow-control commands may accept either Tcl command or natural expression syntax. This behaviour can be controlled using the [option expression] command. Explicitly called commands which are wrapped in [] do not require the use of [option expression off] The command name can be supplied via a variable which will be resolved before the command is executed (if braces are not used to delay evaluation) set p puts set q Hello set r world $p "$q $r" Result: Hello world Example: set p puts set q randomstr set r 10 $p [$q $r] Result: UaMLNJYcxl See also: braces, option expression
Comments  Top  
Standard Tcl Comments are prefixed by the # character Example: # This is a comment End of line comments are supported and are enhanced since they may start at any position on a line, not just as the first character. A semi-colon is not required before a # comment as these are implemented by the macro preprocesor A comment start # symbol is valid only outside of quoted strings. Hash symbols within quoted strings are not treated as comment start markers and may be used as literal characters A literal has character can be represented using [asc] and [chr] as follows: puts [asc "#"] puts [chr 35] Result: 35 # It is strongly-recommended that, as a matter of style, a comment character is followed by a space. This will avoid accidental and difficult to trace clashes with the Ticol macro commands (e.g. #exec, #if, #exit) The Tcl semi-colon+hash end of line syntax is supported but not required # This is a comment puts "Hello World" # This is a valid Ticol comment puts "Goodbye" ;# This also a valid comment puts "Quoted # char" ;# This is a valid Tcl comment too Any information after a comment character is completely removed by the Ticol Macro PreProcessor. To disable this use the /NP (no preprocesor) command-line argument. Note that this also disables #ifdef etc. macros and these must therefore be removed from the source file A # comment should not appear after a line continuation character '\' Example: "The quick brown\ # This comment is illegal because of \ fox jumps over\ # line-continuation. So is this ... the lazy dog" Long comments are supported via the Macro PreProcessor #ifdef... #endif statements and also by C/C++ style /* ... */ comment markers. C/C++ style comments are the most efficient and both styles are processed by the Macro PreProcessor (MPP) both from the command-line or CLI during [load] or [run] Example Tcl comments using macro variables and #ifdef commands #ifdef comment set a 22 set b 7.0 puts [/ $a $b] #endif To revert a long macro comment either delete or prefix again with a 2nd # character ... ##ifdef comment # This ifdef statement is commented-out #ifdef comment # This ifdef statement is active And (perhaps heinously, for some Tcl enthusiasts) C/C++ style comments are supported ... /* This is a comment, this code is ignored So is this invalid expression [expr 1/0] Some may not like this, but it is convenient and useful */ C/C++ long comments are not valid inside quoted strings and are treated as string literals within them. Thus... set a "Brave /* new */ world" will result in the string ... Brave /* new */ world C/C++ long comments may be ignored by prefixing with a standard Tcl # comment ... # /* puts "This code will be executed as it is not commented" # */ Selective enabling of comment blocks during debugging can be facilitated as in C++ /* puts "This code will not be executed" # */ C++ single-line style comments may be defined using this dummy proc: proc // args { # C++ style comment - do nothing. Discard all args on this line } but this is not particularly recommended. Be careful of Unix-style wildcard filename/path values within unquoted strings. It is good practise to always wrap strings in double quotes puts [ftp $hostname ls /tools/ * -u admin -p xxxxx] Should be: puts "[ftp $hostname ls /tools/*.zip -u admin -p xxxxx]" Since the unquoted '/*' in '/*.zip' will be interpreted as a long comment start. Quoting will prevent this. These are examples of a dangerous comments because '#if' and '#else' are reserved Macro Preprocessor keywords. Commenting out a Tcl [if] or [else] statement will create a valid Macro directive #if This line is present the MPP will execute the '#if' clause #else This comment is also dangerous #exit This comment will cause the MPP to exit See also: command line, cli, Ticol
Ticol Compatibility with Standard Tcl  Top  
Ticol Tcl was designed to be flexible and have a reasonable degree of compatibility with standard Tcl. Standard Tcl has changed over time and has incorporated many new features. Ticol was written for personal use by the author and incorporates a number of changes which were desired by the author Some of these changes reduce compatibility with standard Tcl. One of the main design issues was a desire to improve performance by use of a Macro PreProcessor (MPP) to optimise source code before execution. It was decided that the # character would be an absolute comment delimiter and therefore cannot be uses in commands such as [uplevel]. C/C++ like comments are also available as these suited the author's preference The Macro PreProcessor is non-Tcl-standard and is more C-like. Although basic it can offer some advantages when developing Tcl code Tests showed that standard Tcl command such as [+] or [-] were much faster than the expression-handler. Perhaps because Ticol doesn't make use of any compiler-like optimisations when interpreting the script and it leans on the basic Picol kernel interpreter design. For this reason, a new command [calc] was added which enables the MPP to expand expressions into inline Tcl code. If the MPP is disabled then [calc] will be interpreted as [expr] Some advanced Tcl features are not implemented either fully or at all. Arrays are preferred by the author to lists and dictionaries and have been implemented as hashtables. Performance of arrays is quite fast with Ticol being able to handle a million array items with no particular problems and with excellent access speed Ticol has its own (DLL) plugin library support which is not supported by standard Tcl. One of these plugins offers the ability to interface into external DLL libraries (either __stdcall or __Cdecl). To support this interface Ticol also offers a simple binary struct which enables API/external DLL calls and struct returns. Variants are also supported The plugin interface C++ API code is available on request so you can extend Ticol by adding new commands Ticol also offers many non-standard commands which can be used to improve performance and flexibility, e.g. [funct] will allow you to call any [expr] function directly. [funct] is used by the MPP when it expands [calc] expressions Other commands include: [at_exit], [base64], [cat], [chr]. [encrypt], [ctime_to_double], [decimal_to_roman], [dump], [elevate], [inputbox] [json_to_list], [msgbox], [shell], [spawn], [win_error], [write] Standard Tcl may require some modifications before it will run on Ticol Tk is not supported See also: Non Standard Tcl Commands, Ticol, FAQ, Performance, Plugins, Tcl
console  Top  
console close # Closes the console and exits Ticol console hide # Hides the console console show # Shows the console console hidecursor # Hide the console cursor console hidden # Returns a boolean 1 if hidden, 0 if not console get_title # Return the console title as a string console move x y ?w? ?h? # Move the console window (resize) console scroll x y w h ?lines? # Scroll a console area console setfocus # Set focus on the console window console showcursor # Show the console cursor console title string # Set the console title Show or hide the console window or check if the console is already hidden. Note: if you hide the console window you will lose control of the Ticol CLI The command 'console hide' should be run only from a running script or you may lose control of the console. Hiding the console may be useful for CGI web scripts Setfocus has limited use and may be blocked by recent versions of Windows [console scroll] accepts an optional lines argument. Currently 1 (default) scrolls the contents of the area up and -1 scrolls the window content downwards Usage: console hide console show console setfocus Example: console title "Ticol Demo" puts "Hiding the console..." console hide puts "Console hidden? [bool [console hidden]]" # Not visible until show sleep 3000 console show puts "I should be back now" Result: The console window will disappear for 3 seconds then reappear Example: # Smooth scroll an area down by 1 line, 5 times for {set i 0} {< $i 5} {++ i} { console scroll 26 3 50 4 sleep 80 } # Smooth scroll an area up by 1 line, 5 times for {set i 0} {< $i 5} {++ i} { console scroll 26 3 50 4 -1 sleep 80 } See also: screen, CLI, box, gotoxy, console colours
Console Colours  Top  
The standard console colours can be customised. This may be necessary as some colours in the standard Windows console palette are not represented well. These also may not match those interpretations on very old PC system For example, orange appears as khaki brown for some reason on some versions of Windows. Example: (Set console "DarkYellow" to be orange) Save the following file as: console-orange.reg To load it, double click and accept the prompts --------------------------------------------------------------- Windows Registry Editor Version 5.00 ; Colour table with DarkYellow == Orange 0x00c0c0c0 (BGR format) [HKEY_CURRENT_USER\Console] "ColorTable06"=dword:00508dfc --------------------------------------------------------------- Note that the file may only be valid for the current session and unless the defaults are changed the colours will revert after the next reboot Colour changes made via the registry have no effect until a new console window is opened See also: console, big graph
const  Top  
const varName value Define a simple constant variable. You cannot assign to a constant The use of [const] is preferable to macro #define Const values will typically be created in global scope and can be accessed from within procedures using the $::constname scope prefix. Or they may be declared using upvar to create a local const instance Constants can be deleted using [unset] Const arrays can be set using [array set arrayname -const] Example: const ONE_GIGABYTE 1073741824.0 puts $ONE_GIGABYTE puts [bool [is_const ONE_GIGABYTE]] proc foo {} { puts "foo thinks 1Gb is: $::ONE_GIGABYTE" # :: scope operator used } foo unset ONE_GIGABYTE -const puts [bool [is_set ONE_GIGABYTE]] Results: 1073741824.0 True foo thinks 1Gb is: 1073741824.0 False See also: enum, set, array set
copyfile  Top  
integer [copyfile sourcespec target ?-y?] Copy a file from sourcefile to targetfile. Wildcards are supported Path targets or specified filename targets are supported Paths accept \ or / separators. Where a trailing -y is used from the CLI then a trailing / separator must be used to signify a path as the backslash will be interpreted as a line-continuation escape character (\). Where backslashes are used then take note that the Macro PreProcessor (MPP) will require these to be escaped as double backslashes (\\) e.g. "c:\\path" The count of successful copies is returned else 0 on failure Example: copyfile ticol.exe c:\temp\ticol.exe -y copyfile ticol.exe c:/temp/new Copy to target file /temp/new copyfile c:\\tcl\\*.tcl c:\\temp Existing directory copyfile c:\\tcl\\*.tcl c:/temp/new Will fail as '/new' is a file copyfile c:\\tcl\\*.tcl c:/temp/new/ Force create '/new/' directory See also: movefile, file
Ticol Copyright and Licensing  Top  
--------------------------------------------------------------------------- Ticol Copyright and Licence --------------------------------------------------------------------------- Copyright (C) to M Shaw 2010-2018 All rights reserved. Portions Copyright (c) 2007-2016, Salvatore Sanfilippo All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1 Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2 Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution 3 This product and its associated documentation may not be sold or resold for profit 4 This licence does not extend to the Ticol Tcl manual The Ticol Tcl manual, associated documentation and sample scripts are not included in this licence but are covered separately by the standard international author copyright for literary works Copyright (C) M Shaw (2015-2018) All rights are reserved THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --------------------------------------------------------------------------- Licence Summary --------------- As with the Info-ZIP licence, this modified BSD licence has additional clauses added to protect the author: Clause 3 to avoid the author having to encounter the downstresam cost of commercial support Clause 4 to ensure that the literary rights to the documentation are fully protected to ensure that it is is not edited, repackaged and sold by a 3rd party A modified licence may be issues on request and by agreement with the author This project was initially derived from a small project called "Picol", by Salvatore Antirez Sanfilippo, which implemented a Tcl interpreter in 500 lines. This project is closed source and the source code is not distributed There is no obligation under the BSD licence to distribute source code The original 500-line Picol source is freely available from http://oldblog.antirez.com/post/picol.html This documentation (manual), in whatever format distributed, is an original creative work by the author, It is licenced separately from the program binaries and protected by standard international literary copyright. It may be distributed with the program free of charge, but may not be sold, resold, modified or incorporated into other works Copyright (C) to M Shaw (2015-2018) All rights reserved To the best of the author's knowledge, no GPL code is used in this project Portions of certain plugin code may contain code attributable to other authors includeing but not limited to the following: For more information, see any accompanying readme.txt for a full list ticol_zip plugin, portions Copyright (c) 1990-1999 Info-ZIP. All rights reserved The plugin library is not supplied by Info-ZIP ticol_sqlite plugin, portions Copyright attributed to SQLite (Public Domain) Acknowledgements are made for the following code MD5 Algorithm: RSA Data Security, Inc. MD5 Message-Digest Algorithm Copyright (C) 1991-2, RSA Data Security, Inc. 1991. All rights reserved Mersenne Twister Random Number Generator Copyright(C) 1997-2002, Makoto Matsumoto, Takuji Nishimura TCP/IP specific extensions in Windows Sockets 2 Portions Copyright(C) 1980,1983,1988,1993 The Regents of the University of California The Picol project source code has been replaced with around 100,000 lines of C++ code. This source code is not available but the program binaries will be made available for both private and commercial use as freeware. Should any disputes arise the author reserves the right to withdraw the Ticol program from further public distribution Please read the LICENCE.TXT or README.TXT file for full licence terms In summary: No warranty of fitness for use or any other type of warranty is offered. By using Ticol you agree to use it at your own risk and indemnify the author against all liabilities arising as per the licence agreement. Ticol must not be used in a commercial environment without adequate and thorough testing You may freely use Ticol whether for private or commercial use You may give individual copies of Ticol to friends or colleagues You may not sell Ticol or any accompanying documentation You have no right to technical support whatsoever You agree to satisfy yourself of any fitness for use regarding Ticol You accept this as software offered free of charge and in good faith You agree that this software is not warrantied in terms of fitness for any purpose whatsoever You accept that this is a personal/hobby/educational project and you hold no commercial or professional expectations of it either in terms of reliability, fitness for use, performance or levels of support You agree to use Ticol entirely at your own risk and indemnify the author from any and all liabilities arising from its use You should not use this product in any mission critical systems where life or financial loss is at risk You must include the BSD copyright notice/licence terms with any copies you pass on to a 3rd party See: Ticol, why, frequently asked questions
ctime (Unix time)  Top  
C or "Unix" time is defined as a signed integer representing the number of seconds elapsed since 00:00:00 hours on January the 1st 1970 Dates prior to this cannot be represented Dates after 03:14:07 UTC on 19 January 2038 cannot be represented The Visual BASIC method is to use a double value to represent time Example: puts [clock seconds] Result: 1449684929 See: https://en.wikipedia.org/wiki/Year_2038_problem Convert to a string format using the [clock format] command See also: vbtime, date_to_ctime, double_to_ctime, ctime_to_double, clock, time, now
ctime_to_double, double_to_ctime  Top  
double [ctime_to_double seconds] integer [double_to_ctime double] [ctime_to_double] converts the standard internal Tcl "C" time format from seconds in the Unix epoch of 01/Jan/1970 to an industry-standard or Visual BASIC double value. [double_to_ctime] performs the inverse operation Example: puts [clock format [double_to_ctime [now]] -format "%Y/%m/%d %H:%M:" Example: puts [double_to_ctime [now]] puts [clock seconds] Result: 1449684929 1449684930 See also: date, time, is_date ,date_to_ctime, clock, clock format, now, ctime
VB (Visual BASIC) Time  Top  
Visual BASIC stores Date values as an IEEE 64-bit (8-byte) floating point number, identical to a VB Double. Digits to the left of the decimal point, when converted to decimal, are interpreted as a date between 1 January 100 and 31 December 9999. Values to the right of the decimal indicate a time between 0:00:00 and 23:59:59 The date section of the Date data type, is a count of the number of days that have passed since 1 Jan 100, offset by 657434. That is, 1 Jan 100 is denoted by a value of -657434; 2 Jan 100 is denoted -657433; 31 Dec 1899 is 1; 1 Jan 2000 is 36526 etc. The time section of the date (after the decimal point) is the fraction of a day, expressed as a time. For example, 1.5 indicates the date 31 Dec 1899 and half a day, i.e. 12:00:00. So, an hour is denoted by an additional 4.16666666666667E-02, a minute by 6.94444444444444E-04, and a second by 1.15740740740741E-05 The Ticol [date], [dateserial] and [time] commands understand Visual BASIC format doubles representing date values See also: date, dateserial, time, ctime, now, date_to_ctime
is_*  Top  
See: is_admin # Test if user has administrative rights is_array # Test if a variable name is an array is_command string # Is a string a registered command is_const string # Is a string a constant variable is_date string # Is a string a valid formatted date or time is_dir path # Is a string a valid directory is_dst # Test if we are in Daylight Savings Time is_elevated # Test if we are running with elevated rights is_empty var # Test if a variable is both set and empty is_file name # Test a file is_leapyear string # Is a date value a leap year is_list string # Test if a string is a valid Tcl list is_mod x # Optimised modular division test is_numeric x # Is a string a valid number is_pointer x # Is a variable a pointer variable is_proc name # Test if a string is a defined proc is_set var # Test for a valid/existing variable array exists a # Tests if an array exists array is_set a # Tests if an array element is set All the above commands return type "bool" (0 | 1) See also: array exists, array is_set
is_array  Top  
bool [is_array varname] Test if a variable name is an array variable dim a 10 # Empty array set b Hello # Simple variable array c {a 10} # Array struct set d {a 10} # Struct puts [is_array a] puts [is_array b] puts [is_array c] puts [is_array d] puts [is_array e] # e does not exist Results: 1 0 1 0 0 See also: is_*, is_set, array exists
is_dst  Top  
bool [is_dst ?-bias? ?-offset? ?-standardname? ?-daylightname?] [is_dst] returns a boolean (1 or 0) indicating whether we are currently in Daylight Savings Time. The actual time offset is not returned The '-bias' argument will return the local geographic time zone bias from UTC (GMT) in minutes. The '-offset' argument will return the local Daylight-Savings-Time (DST) offset in minutes The '-name' argument will return the name of the time zone Example: # US Central time (-6hrs) will return -360 (minutes) puts [is_dst -offset] Result: -360 Example: # UK summer time (+1hr) will return 60 (minutes) puts [is_dst -offset] Result: 60 Example: puts [is_dst -standardname] Result: GMT Standard Time Example: puts [is_dst -daylightname] Result: GMT Daylight Time See also: is_*, time, date, clock, ctime_to_double, double_to_ctime
is_date  Top  
bool [is_date double] bool [is_date date|time] bool [is_date date] bool [is_date time] bool [is_date "date time"] bool [is_date "time date"] Performs basic sanity checks in a date-interpreted double value or string(s) Examples: puts [is_date 0] # True puts [is_date -1] # True puts [is_date 42657.0430902778] # True puts [is_date 2016/Oct/14] # True puts [is_date 2016/10/14] # True puts [is_date 00:00:59] # True puts [is_date 2016/10/14 01:02:03] # True puts [is_date 01:02:03 2016/10/14] # True puts [is_date "2016/10/14 01:02:03"] # True puts [is_date {2016/10/14 01:02:03}] # True puts [is_date 9999999.0430902778] # False (out of range) puts [is_date "00:00:59 2016/oct/39"] # False (invalid day) See also: is_*, date, dateserial, vbtime
is_file  Top  
bool [is_file filename] Currently checks for the existence of a file and returns a boolean value indicating whether the file exists or not Examples: puts [is_file ticol.exe] puts [is_file nosuch.txt] Results: 1 0 See also: file, is_*
is_leapyear  Top  
bool [is_leapyear year] Confirms whether a year value is a leapyear or not. Valid from 1 AD to 9999 AD Returns a boolean (integer) 1 or 0 The date of the 1582 Pope Gregory declaration is used as the calculation threshold Common algorithms which use leap years to calculate are not valid for years in the Julian calendar before 1752 in the British Empire and US. The year 1700 was a leap year in the Julian calendar, but not in the Gregorian calendar. Example: puts [is_leapyear 0001] puts [is_leapyear 0004] # Is a leap year puts [is_leapyear 4] # Is a leap year puts [is_leapyear 1896] # Is a leap year puts [is_leapyear 2001] puts [is_leapyear 2012] # Is a leap year puts [is_leapyear 9996] # Is a leap year puts [is_leapyear 9999] Results: 0 1 1 1 0 1 1 0 See also: is_date, is_*
is_list  Top  
bool [is_list string] Test if a string is a valid Tcl list Example: puts [is_list {}] puts [is_list ""] puts [is_list a] puts [is_list {a b] Results: 0 0 1 1 See also: is_*, list, lindex, lcount
date  Top  
date ?-separator char? # Return the current date as YYYY-MM-DD # Use [date -separator {}] for YYYYMMDD date -year # Return the current year as YYYY date -month # Return the current month as M date -day # Return the current day as D date -yday # Return the current day of the year as D date double ?-separator char? # Returns YYYY-MM-DD with optional separator date double ?-list? # Return each field as a Tcl list date double ?-notime? # Suppress display of time value time double # Use [time] to suppress date value date double ?-longmonth? # Display 3-character month names e.g. "Jan" date now # Returns the current date as a double value date YYYY/MM/DD ?hh:mm??:ss? # Returns a double representing the date date YYYY-MM-DD ?hh:mm??:ss? # Do date YYYY/MMM/DD ?hh:mm??:ss? # Do date YYYY-MMM-DD ?hh:mm??:ss? # Do date DD/MM/YYYY ?hh:mm??:ss? # Do date DD-MM-YYYY ?hh:mm??:ss? # Do date DD-MMM-YYYY ?hh:mm??:ss? # Do date DD-MMM-YYYY ?hh:mm??:ss? # Do date <date-string> -ctime # Return the time as a C-long integer dateserial YYYY MM DD hh mm ss # Use [dateserial] for dates as Tcl lists Shows the current system date in ISO YYYY-MM-DD format ISO date format is preferred Returns a VB6-compatible date value as double Or, returns a formatted date/time string Date Ranges Numeric inputs range from -693958.000000 (0000/01/01 AD) to 2958465.000000 (9999/12/31 AD). Units are in days and fractions of a day as per Visual BASIC 6.0 US Date Formats The US date formats of MM-DD-YYYY and MM-DDD-YYYY are not supported Comma Date Formats The date format Jan, 1, 2016 and similar formats are not supported Input Locales Automatic/Windows system input locales are not supported The epoch starts the same as for VB6 at 30/Dec/1899 as value 0.0 Negative values extend as far back as January, 1st 0 AD 1/1/70 00:00:00 (Unix epoch in VB) is 25569.0 as a double February 5, 2036 (Unix epoch end) is 49711.00001157407 (00:00:01 6th Feb 2036) Valid Range Dates are valid in the range from 0 AD to 9999/12/31 AD Dates older than the positive VB6 date epoch are negative Year values must be 4-digit. Leading zeroes are required if a date is < 4 digits. e.g. 325 AD will be year "0325" not "325" Values outside the of range 0/00/00 to 9999/12/31 (-693959.0 to 2958465.0) will raise an error Similarly: puts [date [time [date now] -ctime]] is invalid because [date] cannot take a C time value as an argument. In such cases we would use [ctime_to_double] to convert the result from [time]: puts [date [ctime_to_double [time [date now] -ctime]]] Short Year Values Short year values such as 99 for 1999 are not supported 4-digit years are mandatory otherwise 0.0 will be returned Date Arithmetic Since date values are "real" (floating point double) values they may be added, subtracted, multiplied or divided with caution and providing the number range is adhered to when reconverting back to date format using [date] Year/month/day values can be compared with now by using [int] to strip off the fractional (time) part of the number Example: if {[eq [int [date now]] [date $year-$month-$day]]} {...} Exercise caution when adding dates on or before the zero epoch date of 30/dec/1899 as time values will wrap-around. You may need to use [fpart] or [fraction] to split-off the fractional part of a date, save it and then re-add after arithmetic. This is because dates < 30/dec/1899 are represented negative floating point and changing the sign may invert the fractional part When manipulating for whole days you will usually need to strip off the fraction parts of double values to avoid rounding up with 1 day error You may use [fpart] to strip-off and save the decimal fraction part Example: # Increment year from 325 AD to 1776 AD, keeping the time # An alternate method is to return a list and increment item 0 set d [date 0325/jan/01 09:30:00] # Save full date set t [fpart $d] # Split off and save time set i [integral $d] # Split and save the date puts "Stored: $d [date $d] and time as $t" # Display saved values set r [+ [* 1452 365] $i] # Add 1452 365 day years puts "Result: '${r}.$t' -> [date ${r}.$t]" # Concatenate and display Result: Stored: -575255.3958333334 0325/01/01 09:30:00 and time as 3958333333 Result: '-45275.3958333333' -> 1776/01/01 09:30:00 Example: # Date subtraction in epoch range > 0.0 (30/Dec/1899) # Days to 2019/01/10 puts "[int [- [date 2019/01/10] [date now]]] days" # Days to Xmas 2016 puts "[int [- [date 2016/12/25] [date now]]] days" Results: 813 days 67 days Time Arithmetic --------- Time values should be first converted using [date]. Next, any arithmetic should be performed, and the result converted back using [time] puts [date 11:58] puts [date 5:30] # Add 5.5 hours to 11:58 puts [time [+ [date 11:58] [date 5:30]]] # Same action using [now] puts [time [+ [now] [date 5:30]]] # Same action, giving a full date puts [date [+ [now] [date 5:30]]] Results: 0.4986111111 0.2291666667 17:28:00 17:29:58 2017/04/14 17:30:58 Exception Errors Accessing a date value outside the valid range will trigger an exception error. Other date errors will return 0.0 Notes - Converting from 1 second interval cdates to decimal day fractions Multiply each second by 0.000011574074074 or [/ 1 86400.0] Example: # 1 second past the Unix epoch end puts [+ 49711 [/ 1 86400.0]] # 1 second past the Unix epoch end puts [date [+ 49711 [/ 1 86400.0]]] Result: 49711.000011574077 2036/02/08 00:00:01 Visual BASIC Anomalies In order to accommodate two digit year values, VB5 interprets cdbl(fix(cdate("0000/jan/1"))) as 36892.0; which is 01/01/2000 Dates with a year of < 100 AD are interpreted as being in the year 2000 Ticol does no such 2-digit year interpretation adjustment. Post Y2K there is now no valid reason to use two-digit year dates within scripts. 4-digit years are mandatory in Ticol for all dates after 999 AD More Examples Result puts [date] 2016-10-18 # ISO date puts [date -year] 2016 # Current year puts [date -month] 10 # Current month puts [date -day] 18 # Current day puts [date -yday] ? # Day of year puts [date now] 42661.785891 # "now" keyword puts [date [date now]] 2016/10/18 18:51:41 puts [date 0] 1899/12/30 # Same as VB6 puts [date 1] 1899/12/31 # Same as VB6 puts [date 2] 1900/01/01 # Same as VB6 puts [date 0000/1/1] -693958 # VB6=01/01/2000 puts [date -693958.000000] 0000/01/01 # Jan, 1st 0 AD puts [date 0001/1/1] -693593 # VB6=01/01/2001 puts [date -693593.000000] 0001/01/01 # Jan, 1st 1 AD puts [date 42661.785891] 2016/10/18 18:51:40 puts [date 42661.785891 -separator -] 2016-10-18 18:51:40 puts [date 42661.785891 -separator " "] 2016 10 18 18:51:40 puts [date 42661.785891 -separator _] 2016_10_18 18:51:40 puts [date 42661.785891 -longmonth] 2016/Oct/18 18:51:41 puts [date 2016-10-18] 42661 # YYYY-MM-DD puts [date 2016/10/18] 42661 # YYYY/MM/DD puts [date 18-10-2016] 42661 # DD-MM-YYYY puts [date 18/10/2016] 42661 # DD/MM/YYYY puts [date 0325/01/01] -575255 # -ve (325 AD) puts [date 1400/01/10] -182610 # Same as VB6 puts [date 1700/01/10] -73037 # Same as VB6 puts [date 1970/01/01] 25569 # Unix epoch puts [date 2036/02/06] 49712 # Unix epoch end puts [date 9999/02/06] 2958101 # Same as VB6 puts [date 2016-10/18] 0.000000 # ERROR puts [dateserial 2016 10 18 18 51 40] 42661.785880 # For lists puts [date 2016/10/18 18:51:40] 42661.785880 # 2 arguments puts [date 18:51:40 2016/10/18] 42661.785880 # Reverse is OK puts [date "2016/10/18 18:51:40"] 42661.785880 # Quoted is OK puts [date {2016/10/18 18:51:40}] 42661.785880 # Braced is OK puts [date {18:51:40 2016/10/18}] 42661.785880 # Reverse is OK See also: time, dateserial, is_date, ticks, clock, ctime, vbtime, date_to_ctime, fpart, clock scan workaround, clock scan, day_of_week
dateserial  Top  
double [dateserial ?year|-? ?month|-? ?day|-? ?hour|-? ?minute|-?\ ?second|-?] double [dateserial ?tcl-list?] Calculates a date value and returns a double from individual arguments Each arguments is optional with the defaults being 1 1 1 0 0 0 (1st January, 1 AD 00:00:00). Optional arguments are omitted by specifying a hyphen character '-', using empty "" or {} arguments [dateserial] may also be called with these items as a space-separated Tcl list, as produced by [date double -list] All arguments must be integer values. Values must be given in order but may be omitted with a '-' used as a placeholder Example: puts [dateserial - - - 00 05 36] puts [dateserial "" "" "" 00 05 36] puts [dateserial {} {} {} 00 05 36] puts [date [dateserial - - - 00 05 36]] Result: -693958.00388888887 -693958.00388888887 -693958.00388888887 0000/01/01 00:05:36 Example: puts [dateserial 1899 12 30 0 0 0] puts [date [dateserial 1899 12 30 0 0 0]] Result: 0.000000000000000 1899/12/30 00:00:00 Example: puts [date now] # Returns a double puts [date [date now] -list] # Returns date as list puts [dateserial [date [date now] -list]] # Returns a double puts [date [dateserial [date [date now] -list]]] # Returns full date Result: 42663.971261574072 2016 10 20 23 18 37 42663.971261574072 2016/10/20 23:18:37 Example: puts [fraction [dateserial - - - 2 4 6]] # Extracts .nnnn puts [time [fraction [dateserial - - - 2 4 6]]] # Extracts .nnnn Result: -0.086180555517785 02:04:06 See also: date, time, vbtime
date_to_ctime  Top  
integer [date_to_ctime year ?month? ?day? ?hour? ?minute? ?second?] Convert string-formatted date values into a C/Unix time value as a number of seconds since January 1st 1970. Passing a date value earlier than this will raise an error. The inverse command is [ctime_to_double] Example: puts [date_to_ctime 1972 apr 04] # Flying Scotsman Day Result: 71193600 Example: puts [date [ctime_to_double [date_to_ctime 1972 04 04]]] puts [clock format [date_to_ctime 1972 04 04] -format %D%N%y] Result: 1972/04/04 00:00:00 4472 See also: ctime_to_double, ctime, time, date, dateserial, vbtime
Data Type Ranges  Top  
The following data type ranges may be coerced using data type casts The internal storage format for numbers is string. Calculations are performed on integers by converting to 64-bit values and real numbers by converting to 64-bit (8 byte) doubles By default, signed values are used internally. Some commands such as bitwise operations [bit] may use unsigned values. See the documentation for each command Type casts may be forced using various cast commands (See: variable casting) Type Bits Sign Example Comma-Range -------------------------------------------------------------------------- char 8 signed -128 to 127 char 8 unsigned 0 to 255 short 16 signed -32,768 to 32,767 short 16 unsigned 0 to 65535 long 32 signed -2,147,483,648 to 2,147,483,647 long 32 unsigned 0 to 4294967295 int 64 signed -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 int 64 unsigned 0 to 18,446,744,073,709,551,615 double 64 signed 1.7E +/- 308 (15 digits of precision) Example Integer Range ------------------------------------------------------- char -128 to 127 unsigned char 0 to 255 short -32768 to 32767 unsigned short 0 to 65535 long -2147483648 to 2147483647 unsigned long 0 to 4294967295 int -9223372036854775808 to 9223372036854775807 int unsigned 0 to 18446744073709551615 double 1.7E +/- 308 (15 digits of precision) Note that [scan] with %d, %ld etc. will not truncate excess range values down to handled ranges Useful Definitions ------------------ # Refer within source without a $ prefix e.g. CHAR_MIN # The MPP will detect within substrings e.g. MYCHAR_MIN #define CHAR_MIN -128 #define CHAR_MAX 127 #define UCHAR_MIN 0 #define UCHAR_MAX 255 #define WORD_MIN -32768 #define WORD_MAX 32767 #define UWORD_MIN 0 #define UWORD_MAX 65535 #define LONG_MIN -2147483648 #define LONG_MAX 2147483647 #define ULONG_MIN 0 #define ULONG_MAX 4294967295 #define INT_MIN -9223372036854775808 #define INT_MAX 9223372036854775807 #define UNSIGNED_MIN 0 #define UNSIGNED_MAX 18446744073709551615 or # Refer within source code using a $ prefix e.g. $CHAR_MIN # Detection and parsing is more precise but slower const CHAR_MIN -128 const CHAR_MAX 127 const UCHAR_MIN 0 const UCHAR_MAX 255 const WORD_MIN -32768 const WORD_MAX 32767 const UWORD_MIN 0 const UWORD_MAX 65535 const LONG_MIN -2147483648 const LONG_MAX 2147483647 const ULONG_MIN 0 const ULONG_MAX 4294967295 const INT_MIN -9223372036854775808 const INT_MAX 9223372036854775807 const UNSIGNED_MIN 0 const UNSIGNED_MAX 18446744073709551615 Within the C language these values are defined within file "limits.h" See also: variable casting, cast, numeric types, vbtime
Data Structures  Top  
Ticol offers the following data structures and ADTs integers as string double/floats as string binary values as string hexadecimal values as string big integers plugin strings natively lists as string stacks natively associative arrays natively binary lists plugin structs natively date/time natively dynamic memory blocks natively dictionaries unfinished xbase/dbase databases plugin sqlite databases plugin Variant array plugin Ticol does not offer classes objects/inheritance counted/binary strings (other than in a very limited way) See also: data types
day_of_week  Top  
integer [day_of_week day month year] Returns the day of the week for a given day in a given month and for a given year. All arguments are required. Valid for range 1000 AD to 9999 AD The values are all 'base 1' e.g. day 1..31, month 1..12, year 1..2017+ The return value ia 'base 0' index where 0==Sunday, 1==Monday etc... [day_of_week] can be used to construct a Gregorian calendar Calculations are based on the introduction of the Gregorian calendar in 1582 not 1752 Common algorithms which use leap years to calculate are not valid for years in the Julian calendar before 1752 in the British Empire and US. The year 1700 was a leap year in the Julian calendar, but not in the Gregorian calendar. Example: # 23rd December 2017 is a Saturday (day 6) puts [day_of_week 23 12 2017] puts [day_of_week 4 4 1972] puts [day_of_week 21 2 1804] Result: 6 # Saturday 2 # Flying Scotsman Day was a Tuesday 2 # The first steam locomotive ran on a Tuesday [day_of_week] can be used to create an extended-range Gregorian calendar. See calendar.tcl example file Example: JANUARY 1172 Sun Mon Tue Wed Thu Fri Sat 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 # 1st January is a Saturday (Gregorian) # Validation Reference: # https://moodle.lse.ac.uk/calendar/view.php? view=month&course=1&time=-25182489600 JANUARY 14001 Sun Mon Tue Wed Thu Fri Sat 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 # Validation reference: # http://elearning2.msbm-uwi.org/calendar/view.php? view=month&course=1&time=379661749200 References: https://calendar.zoznam.sk/nameday-enathor.php See also: date, time, clock
debug  Top  
debug ?on|off|print? ?-quiet? Turn on/off debug tracing or view the current setting or print to the console. Internal debugging output applies only to debug build releases of Ticol See the /DEBUG command line argument. This is distinct from [debug print] [debug] with no arguments issues a verbose status unless -quiet is used. In all cases a boolean 1 or 0 is returned indicating the current debug status [debug -quiet] can be used to programmatically detect debugging status and act accordingly if { [debug -quiet] } { debug off } [debug print] or [debug print string] is a command which prints to the console unless a ... #define ndebug statement is issued. In which case all [debug print] statements are disabled in the script, regardless of where the #define occurs Because this is an interpreter, not a compiler and because the MPP runs before runtime interpretation the '#define ndebug' statement can appear anywhere and will have an effect on the whole file If selective output is required then do not define 'ndebug', instead define a different macro variable and wrap statements in #ifdef Example: debug print "Hello from debug" Result: Hello from debug Example: debug print "This statement will not appear" #define ndebug debug.print "Nor will this" Result: <no output> Example: #define debug_print #ifdef debug_print debug print "I will appear" #else debug print "I won't appear" #endif Result: I will appear See also: trace, debugging, breakpoints, halt, time, debugging, commands
Useful Debug Routines  Top  
Two useful routines are offered to aid testing and debugging, [check] and [checkex]. [checkex] is an extended form of [check] which allows for more complex expressions in the test rather than just simple equivalence [assert] offers a built in alternative if {! [defined checkex] } { proc checkex {x expr} { upvar i upvar line set NAN "-1.[calc [chr 35]]IND00000000000" set q {$x} puts "Line $line: " -nonewline puts "'$q'=='$x': '$expr'" if { [eval $expr] } { # puts "Pass" } else { textcolor red puts "checkex assertion failed: '$q' -> '$x' at line $line" textcolor stop } } } if {! [defined check] } { proc check {x y} { if {!= $x $y} { puts "Error in test at after line $::line" puts "'$x' != '$y'" stop } } } Examples: check [calc "ceil(2.8)"] 3 checkex [comma 1234567890] {eq $x "1,234,567,890"} Results: line 3348: x:[3.000000000000000] == y:[3] Line 3348: '$x'=='1,234,567,890': 'eq $x "1,234,567,890"' See also: assert, debug, faq, debugging
decrypt  Top  
string [decrypt string|var password] Decrypt a string or variable from a base64 string which was encoded using [encrypt]. Decoding will result in a string size reduction Example: puts [encrypt "Hello world!" secret] Result: N4w8n7XnePSvob9G Example: decrypt [encrypt "Hello world!" secret] secret Result: Hello world! See also: encrypt, base64
default  Top  
See: proc for default proc arguments See: switch for default switch clause
defined  Top  
bool [defined command|function] Returns a boolean 1 or 0 indicating whether the given command or procedure is defined. The defined command is useful in allowing scripts to be re-run on a stop event without encountering a 'procedure already defined' error. Example: if {! [defined ipfromhost]} { proc ipfromhost {hostname} { return [calldllstr ping32 GetIPFromHostName $hostname] } } Example: puts [bool [defined foo]] puts [bool [defined puts]] Result: false See also: commands, is_set
dict (Dictionaries) (Incomplete feature)  Top  
Simplified Tcl dictionaries. Dictionaries are implemented as efficient hashtables Nested dictionaries are minimally-supported dict create var ?key value?... Create dictionary, put reference in var dict get var key ?key...? Get a dictionary item(s) dict info Show dictionary information dict keys var Return a list of dictionary keys dict set var key ?key...? value Add/update a dictionary item by key value dict size Return the number of element pairs Example: dict create mydic 4470 "Great Northern" 4471 "Sir Frederic Banbury" dict set mydic 4472 "Flying Scotsman" dict set mydic 4473 "Solario" dict set mydic 4474 "Victor Wild" dict set mydic 4475 "Flying Fox" dict set mydic 4476 "Royal Lancer" dict set mydic 4477 "Gay Crusader" set l [dict keys mydic] foreach item $l { puts [format "%-10s\t%s" $item [string trim [dict get mydic $item] \ [chr 34]]] } See also: list
dict exists  Top  
bool [dict exists dictionaryValue key ?key ...?] [dict exists] returns a boolean value (1 or 0) indicating whether the key or series of keys within a set of nested dictionaries) exists in the given dictionary value. This returns a true (1) value if a [dict get] on that series will succeed. Example: dict set a the quick brown fox jumps over the lazy dog bool [dict exists $a the] bool [dict exists $a The] bool [dict exists $a the quick] bool [dict exists $a the quick brown fox jumps over the lazy] bool [dict exists $a the quick brown fox jumps over the lazy dog] Results true false true true false See also: dict
Windows Dialogs  Top  
The following Windows dialogs are available: inputbox Accept user input, optionally with password masking get_fileopen Browse for a file to open get_filesave Browse for a file to save get_folder Browse for a folder name msgbox Get user input or display a message from a popup dialog There is no Tk GUI support in Ticol, unless an external DLL is called or the Win32 API called via the calldll* plugin See also: inputbox, get_fileopen, get_filesave, get_folder, msgbox, gets
die  Top  
die ?message? ?-code return-code? A PHP-like command to exit the current program, optionally displaying a message or return code. If running in the CLI, control is returned to the CLI, otherwise the program will exit to the operating system. Example: die "Something went wrong" die "Exiting to system" -code 10 See also: exit, stop, at_exit, return
Differences between Ticol and Standard Tcl  Top  
Ticol is intended to be a subset of standard Tcl with a few differences The following aspects differ from ActiveState Tcl: $this Ticol offers $this in [switch] $env $env (and other) consts are provided. $env has case- insensitive subscript reference binary Binary values are handled as 0bNNNNN... with options arrays Variant arrays are available for use with calldll autoexec.tcl A startup, autoexec.tcl file is supported big math Big number integer support available as a plugin calc [calc] interacts with the Macro Preprocesor (MPP) which will transform [calc] commands to more-efficient raw Tcl. If the MPP is disabled then [calc] will be interpreted as [expr] calldll An external plugin lib which offers DLL interfacing similar to Visual BASIC, dotNet etc. commands Many additional commands which are implemented at binary level for speed. This includes some useful BASIC-like commands. To facilitate [calc] macro optimisation a command will accept a reduced calc expression as [number]. e.g. [10] comments Comments require no ; prefix as ;# Comments are extended to include "C" style long-comments console echo To make the CLI more useful, Ticol turns console echo off by default. This may be enabled using: option echo on Debugger A single-step debugger and error stack trace do Ticol implements a do..while loop as well as [loop] encryption Source code obfuscation with various locking schemes are available in Ticol Tcl eval External scripts are linked and evaluated using [eval] expr Expressions can sometimes be handled differently, due to less flexibility in the Ticol expression handler e.g. Spaces required between commands when evaluating strings in [expr] ActiveState Tcl: if {""==""} {puts PASS} Ticol Tcl: option expression on if {"" == ""} {puts PASS} Sometimes Ticol is more flexible: ActiveState Tcl: set op == set foo 1 if "$foo $op 1" {puts YES} # can't read "foo": no such var Ticol Tcl: option expression on set op == set foo 1 if "$foo $op 1" {puts YES} # Passes (echoes YES) if {"$foo$op 1"} {puts YES} # Passes (echoes YES) if {"$foo${op}1"} {puts YES}# Passes (echoes YES) global Global is an alias for upvar goto Limited-scope gotos (purely for entertainment purposes) lib External plugin modules (as DLLs) are loaded using [lib] The standard Tcl plugin method is different and incompatible loop A simple and efficient equivalent to [for] namespaces Real namespaces are not supported. They are emulated using name-scope prefixes such as 'fake_scope::var' Macros A full "C"-like Macro PreProcessor with load-time optimisation and extended command set math All integer math is calculated using 64-bit integers Hex, octal and binary consts are handled transparently in math.:e.g. expr 0b1010*3 => 30, expr 0x0f*10 => 150 The new Tcl 9.x 0oNN octal format specifier is supported Math expressions are optimised by the Macro PreProcessor unless /NEO and /NES command line arguments are used memory Memory allocation and free for use with [calldll] obfuscation Script encryption (obfuscation). Ticol scripts may be obfuscated using symmetric encryption and may also be execution-locked by various means option Certain functionality is controlled via the [option] command particularly, the 'option expression' option Performance Performance analysis, profiling and graphing proc Ticol procs may not be integers or real numbers A proc name may, however, contain numeric digits ActiveState Tcl allows numeric values as proc names A proc name may also consist of only one or more spaces Procs defined with numeric prefixes can be called only directly using [call procname] Proc default args cannot contain math or other symbols unless wrapped in double-quotes. It is good practice to wrap strings within double-quotes in any case speed Ticol Tcl is purely an interpreter. Even though the MPP will do some optimisation it will always be slower than ActiveState Tcl or compiled code stacks Stacks are built-in static Ticol offers native static variables for procs, and this can be extended to include structs structs Ticol provides for binary struct emulation in order to interface with external DLLs. Structs may also be used with care with native Tcl code time Optionally returns the current time as [time] Ticol also has an extensive [date] command uplevel The absolute level parameter is specified by a @ symbol not # as # is reserved by the MPP for comments e.g. uplevel @1 command # Executes at absolute level 0 upvar The absolute level parameter is specified by a @ symbol not # as # is reserved by the MPP for comments [upvar] also assumes the local variable name (optional) e.g. upvar @1 s # Executes at absolute level 0 Also, [upvar] optionally assumes the alias, which makes far more sense than making it mandatory e.g. upvar s # Not upvar s s variants Some variant handling for interfacing with external DLLs These are not recommended for use with native Tcl code variable [variable] is implemented an alias for [set] because Ticol does not support real namespaces Variable names allow underscores, dots and colon characters Variable names can embed "::" as a pseudo namespace e.g. variable foo::bar Windows Basic Windows dialogs including file open, file save, folder-browse, input box and message box xbase/dbase xbase database support as a plugin as well as an extended database support which offers large fields/records The Macro-PreProcessor (MPP) extends the standard Tcl comment character. This adds trailing comments but reserves the # symbol. The MPP s designed to optimise and speed up interpretive scripts but can be disabled using the /NP command argument (not recommended). The MPP consumes no run-time resources as pre-processing is performed at load time Macro #__LINE__ , #__DATE__ and #__TIME__ debugging constants are available Macro PreProcessor #define, #ifdef, #ifndef, #undef controls Ticol has no Tk/GUI support unless you call an external dll via the calldll plugin to facilitate graphics output via the Windows API See also: ticol, gui, arrays, calc, calldll, do, encryption, global, goto, lib, math, option, struct, time, uplevel, upvar, variant
dim  Top  
dim arrayname size Dimensions an array according to size. The underlying hash table is created and required memory is allocated. No array elements are assigned and the element count is set to zero. See also [array create] A size value of 0 is acceptable [is_set] will return $true (1) [array exists] will return $true (1) [dim] is not necessary as array allocation is dynamic, but it may save time when allocating a very large number of elements within a loop as the array hash table is expanded dynamically and geometrically as elements are added. This introduces a (diminishing) time cost overhead to critical loops Example: array create names 10 array walk names Results: ----------------------------------------------------------------- hash_table object:0x35ec650 size:10 ----------------------------------------------------------------- Hash Table Statistics: Root size:10 Occupation:0 (0.00%) Max depth:0 Nodes:0 ----------------------------------------------------------------- See also: array, arrays, array set
disktype  Top  
integer [disktype x:] Returns a numeric value indicating the disk type as follows: 0 DRIVE_UNKNOWN 1 DRIVE_NO_ROOT_DIR 2 DRIVE_REMOVABLE 3 DRIVE_FIXED 4 DRIVE_REMOTE 5 DRIVE_CDROM 6 DRIVE_RAMDISK Example: array set status { 0 "Unknown" 1 "No root directory" 2 "Removable" 3 "Fixed" 4 "Remote" 5 "CDROM" 6 "RAMDisk" } -const puts "[array item status [disktype c:] Unknown" Result: (where c: is a hard drive) Fixed Note that a trailing path is allowed. e.g. [disktype "c:\\temp"] See also: diskfree
dll_close  Top  
dll_close dllname handle Release a DLL previously opened by [dll_open]. Accepts either a literal or a variable. Returns a boolean success flag. Example: set handle [dll_open "vbsqlite3.dll"] dll_close $handle Result: 1 See also: dll_open, calldll
dll_open  Top  
integer [dll_open dllname] Load a DLL into persistent memory. This may be necessary to process DLL calls where there is a need for a persistent handle such as SQLite queries [calldll] will accept a handle to an open DLL in place of a DLL name Example: set handle [dll_open "vbsqlite3.dll"] Result: 13631488 See also: dll_close, calldll
incr, decr, ++, --  Top  
integer [incr value|variable ?increment?] integer [decr value|variable ?increment?] integer [++ value|variable ?increment?] integer [-- value|variable ?increment?] Increases or decreases a value by 1 unless increment is specified. If specified the increment may be +ve or -ve and greater than 1 The optional increment argument may be any signed 64-bit integer Real numbers (1.2345) will be rounded to integer before applying the operator so: [++ -1.23] gives 0, and [++ 1.23] gives 2 Example: set line #__LINE__ ++ line 2 puts "Line is $line" Unary increment/decrement is not implemented within [expr]. Embed [++] or [--] command within the expression as follows... Example: set a 1;puts [expr "[++ $a]*2"] # Result 4 Example: set a 1;puts [expr "[++ $a 5]*2"] # Result 12 Where the incrementing operator is used in an expression as an infix operator it should be wrapped in parentheses if an increment value is given Example: set a 1;puts [expr "($a++ 10)*2"] # Result 22 See also: math, expr, eval
diskfree  Top  
integer [diskfree x:] Shows the free disk space for a given drive/path. [diskfree] works with UNC path. You can use comma to format the result Example: puts "[comma [diskfree d:]] byte(s)" Result: 135,071,793,152 byte(s) Example: Show free space on UNC path for workstation, "snoopy" C: puts "[format %.3f [/ [diskfree \\snoopy\c$] [* [* 1024.0 1024] 1024]]] Gb" Result: 7.89 Gb See also: disktype, file, comma
do while, do until (Flow Control)  Top  
do while {condition-statement} {code-block} do {code-block} while {condition-statement} do {code-block} {condition-statement} do until {condition-statement} {code-block} do {code-block} until {condition-statement} A flexible-syntax [do] loop The following additional commands interact with [do] break # Is passed back to any enclosing structure stop # Halt operation, return to the CLI if loaded exit # Exit the script and return to Windows goto # Where used with an enclosing [goto_block] continue # Resume execution at the head of the loop Ticol offers both standard Tcl while loops as well as do...while loops Well-formed single statements need not be braced but where braces are present and over more than one line the open brace must be at the end of the line not the start of a line (see flow control). Statements may be combined on a line using the semi-colon separator Examples: do {puts [rnd 1 10] } while 1 do {puts [rnd 1 10] } while { 1 } do {puts [rnd 1 10] } while { 1 } set i 0 do { # Correct brace layout (Tcl) puts "i is $i" if {$i == 2} { return } incr i } while { $i < 10} do while {1} {puts [rnd 1 10] } do {puts [rnd 1 10] } {1} set i 0 ; do {puts "i is $i"; if {== $i 2} { return } ; incr i } \ while { $i < 10} do while {[< $i 10]} { puts "do-while i is $i" ++ i } set i 0 do { puts "do {} i is $i" ++ i } {[< $i 10]} set i 0 do { puts "do-while i is $i" ++ i } while {[< $i 10]} See also: flow control, while, for, loop, if, switch, goto, time
$ dereference  Top  
$varname [set varname] Dereferences a variable to return the contents (see: double dereference) Very early versions of Tcl lacked the '$' syntax and, instead, used the [set] command to dereference variables. In some cases [set] may still be useful. Variable names may be braced as ${var} to isolate from strings Because braces delay evaluation, the use of braces to isolate variable names can be problematic, especially with nested sub-variables: e.g. ${name_$var}. Such cases will require the use of intermediate variables since translation would require the order of nested brace evaluation to be reversed for a $ operation. Nested, braced dereferences are allowed (e.g. ${var1${var2}} ) Strings which contain non-variable embedded dollars must be escaped. If it is not possible to manually escape then such strings may be escaped using the [escape] command Example: set var {"\\path\\to\\badfile.$$$"} # Simulate read from [ls] puts [escape $var] # Prevent problems Unlike standard Tcl, Ticol supports multi-level dereferences ($$var) Note that you cannot dereference a struct member using $ or [set] as this merely returns the member offset address within the struct Example: set s 23 puts "a is '$s'" puts "a is '[set s]'" Result: s is 23 s is 23 Example: set a(1) 23 puts "a(1) is '$a(1)'" puts "a(1) is '[set a(1)]'" Result: a(1) is '23' a(1) is '23' Example: set a "Hello " puts ${a}world Result: Hello world Double-Dereferencing -------------------- Double/multiple level dereferences are allowed in Ticol Tcl using either nested [set] or multiple $ prefix statements. (See: double dereference) Examples: set a 23 set b a set c b set d c puts $$$$d # 4 levels of dereference puts [set $$$d] # 4 levels of dereference puts [set [set $$d]] # 4 levels of dereference puts [set [set [set $d]]] # 4 levels of dereference puts [set [set [set [set d]]]] # 4 levels of dereference Result: 23 23 23 23 23 See also: set, double dereference, nested dereference, variables, arrays
Double Quotes  Top  
In common with most programming languages, double quotes in Tcl are used to delineate and group words together into strings. They are not mandatory unless an intended string value contains whitespace. They are, however, strongly recommended to be used in all cases where a string is intended Braces may also be used to perform this task since braces can group characters into a single argument for a command. Since nested double- quotes as not permitted, braces may be used to group string sequences within double-quoted strings Example: set "I am a {string within} a string" Example: puts "Hello world" puts {Hello world} It should also be noted that while unescaped double-quotes are not allowed within a string, adjacent strings will concatenate, thus in the following example \\r\\n isn't embedded but is, instead, concatenated Example: store add s "[unescape "\\r\\n"]\r\n" Single-quote characters (') do not group and therefore cannot be used to group characters into a string argument The empty string or empty list may be represented by pairs of double quotes or braces Example: set s "" set s {} Numeric hex or other literals for which it is desired that the MPP not translate into decimal should be quoted. This will affect the interaction with string comparison commands such as eq, ne. Numeric comparison commands will perform automatic decimal conversion Examples: set a 0xABCDEF set b "0xABCDEF" set c 0o12345 set d "0o12345" set e 0b1010101 set f "0b1010101" puts $a puts $b puts [int $b] puts $c puts $d puts [int $d] puts $e puts $f puts [int $f] Result: 11259375 0xABCDEF 11259375 5349 0o12345 5349 85 0b1010101 85 It is not allowed to embed unescaped double-quotes within a quoted-string even if quote parity is maintained. In standard Tcl this is an error Example: option echo on set q Hello"world" # This is actually two adjacent strings Result Hello"world # But the embedded quote is visible However, a workaround is to wrap the unescaped string in spaces or to escape the string and then use [unescape]. For example, when addressing an array with a subscript which has spaces... set q {a("with spaces")} vars q* assert $q {eq $_ {a("with spaces")}} -v assert $q {eq $_ [unescape "a(\"with spaces\")"]} -v See also: braces, single quotes, dereference
$$ double-dereference (multi-dereference)  Top  
$$var set $var Ticol allows for a non-standard double-dereference similar to PERL on simple variables and arrays elements. This avoids the need for clumsy [set] statements and is much faster, avoiding a slow command-call Multiple levels of double-dereferencing are supported e.g. $$$$var Deeply-nested levels can also be handled using [set] in the approved manner for example: set [set [set [set $var]]] but this is quite cumbersome Complex, braced variable expressions such as '${var}::name' are not supported by multiple dereferences. Instead use [set] to handle these (e.g. [set ${var}::name]) [set] can be combined with the use of one or more dollar $ dereferences Note that struct member fields must be dereferenced using [struct item] and not the dereference dollar prefix $ Example: set a 23 set myvar a puts "Double dereference using \$\$ is: '$$myvar'" puts "Double dereference using \[set\] is: '[set $myvar]'" Result: Double dereference using $$ is: '23' Double dereference using [set] is: '23' Example: set a 23; set b a; set c b; set d c puts $$$$d # x4 levels of dereference puts [set $$$d] # x4 levels of dereference puts [set [set $$d]] # x4 levels of dereference puts [set [set [set $d]]] # x4 levels of dereference puts [set [set [set [set d]]]] # x4 levels of dereference Result: 23 23 23 23 23 Example: set a(1) one set b a(1) set c(1) b set d c(1) puts "\$\$\$\$d resolves to '$$$$d'" puts "\$\$\$\$d resolves to '[set [set [set [set d]]]]'" Results: $$$$d resolves to 'one' $$$$d resolves to 'one' Array double-dereferences, where the array name prefix is contained in a variable must be resolved as follows. This method is useful when addressing array names returned from procedures etc. set a(0) "Hello" set q a set i 0 puts "Array element $i: '${${q}($i)}'" # Correct syntax # ^ # Resolve first ${q} # Resolve second ${____($i)} Result: Hello This breaks down as follows... a) ${${q}($i)} b) Resolve innermost reference: ${q} -> which gives 'a' c) Resolve outermost array: ${a($i)} -> Hello Complex array elements containing whitespace can be referenced using quoted-escaped strings and the [unescape] command as follows: Whilst variables can be declared which have complex whitespace, literal strings require escaping. Example: set a("with spaces") "Hello world!" # ^ Array definition (escapes not required) set b [unescape "a(\"with spaces\")"] # Escaped string # ^ Literal string (must be escaped) set c b puts "Triple dereference: '$$$c'" Result: Triple dereference: Hello world! Useful resources: http://phaseit.net/claird/comp.lang.tcl/tcl_deref.html See also: dereference, nested dereference, set, variables
Complex Nested Dereferences  Top  
Complex nested dereferences are supported for arrays and standard variables These may also be braced to isolate variable names from strings. This is an enhancement on standard Tcl Braces are resolved within variable expressions in the opposite order to braces within standard Tcl expressions. That is, they are evaluated recursively, from the innermost set of braces outwards. Where braces are used within a variable expression they must follow immediately after the dollar sign. Braces must wrap the whole variable expression Examples: $s # A simple variable dereference $a(text) # Array with subscript literal value 'text' $a($ss) # Array with subscript variable '$ss' ${s}text # Variable 's' isolated from remainder of text ${${s}text} # Double dereference of 's' including 'text' ${a($ss)}text # Array 'a' with subscript '$ss', isolated from text abc${a(1)}def # Array 'a(1)' embedded within the string "abcdef" $a(${i}wo) # Where $i == 't', this references subscript 'two' $$$c # Treble dereference (c->b->a->result) $$${c} # Ditto (equivalent) $${${c}} # Ditto (equivalent) ${${${c}}} # Ditto (equivalent) ${$p$q$r} # Where p, q, r == v, a, r and var == "x" then "x" ${${p}${q}${r}} # Ditto (equivalent) ${q}(${i}wo) # Where q == a and i == t "a(two)" ${${q}(${i}wo)} # Where q == a and i == t and a(two) == "x" then x ${::{$x}.a} # Where x == s; refer to global struct member s.a ${::foo::{$x}.a} # Where x == s; refer to namespace struct ::foo::s.a Invalid Expressions: ${q}(text) # Where q == a. For array 'a' will return "<array>text" # Should be ${${q}(text)} {$a(1)} # Will not resolve due to protective braces # Should be ${$a(1)} {$p$q$r} # Will not resolve due to protective braces # Should be ${$p$q$r} Dereferencing [struct] Inside [proc] ------------------------------------ Dereferencing an [upvar] struct inside [proc] can be problematic due to indirection in the struct name which requires a complex, nested dereference. If desired, [set] or [->] can be used as an alternative to resolve the final dereference where ${${argvar}.field} would be required Example: struct s {a 10} proc foo {x} { upvar $x # Dereferencing, x gives the struct name 's' puts "-> ${x}.a" # This requires x.a to be braced puts "-> ${${x}.a}" # This requires $s.a to be braced } struct set s.a Hello foo s Results: s.a Hello See also: dereference, double dereference
dump  Top  
Dump loaded source-code or known variables dump ?-echo? ?-crlf? # Display syntax-highlighted source code dump variable # Analyse a variable Dump with no arguments will display any preprocessed source code loaded within the CLI by either [run] or [load] as long as it is not encrypted. Code which has been encrypted (obfuscated) using ticol.exe /C cannot be listed Source code is highlighted using the following convention blue Inbuilt Tcl commands magenta Procs defined within the script yellow Strings (embedded commands not highlighted) green Dereferenced variables darkyellow Numeric values grey Variables, arguments and lib commands white Square, curved and curly braces - Comments are removed by the MPP You can return the source code as a single string to be captured by a Tcl variable by using the -echo argument. Unless the Macro PreProcessor has been disabled the returned code will be preprocessed and will have had empty lines removed with comments and macro #ifdef..#else..#endif blocks stripped Line numbers will no longer match the original source-code but #__LINE__ tags will correctly reference the original source. Trailing whitespace is removed but indenting is preserved. See: load Example: load msgbox # Load msgbox.tcl to the CLI set a [dump -echo] puts $a Result: Loaded msgbox.tcl OK 105 byte(s) set r [msgbox [join [split $qbf " "] "\n" 768] "Choose" 36] msgbox "You chose [map {6 Yes 7 No} $r]" -- dump ?variable? dump with a variable name displays an analysis of a variable. When used with structs full member details will be shown, this includes the offset into the struct and the member (field) size in bytes struct 's' - at 9384672 (0x8f32e0), 146 byte(s), 5 member(s) + member 1: 's->s_a' => 0x8f32e0, 4 byte(s) + member 2: 's->s_b' => 0x8f32e4, 30 byte(s) + member 3: 's->s_c' => 0x8f3302, 100 byte(s) + member 4: 's->s_d' => 0x8f3366, 4 byte(s) + member 5: 's->s_e' => 0x8f336a, 8 byte(s) -------- ----------------------- ----------------------- -- ASCII ------- 008f32e0 48 65 6C 6C F0 FF 00 00 - 6F 00 33 32 31 41 42 43 Hell....o.321ABC 008f32f0 44 45 46 47 48 49 4A 4B - 4C 4D 4E 4F 50 51 52 53 DEFGHIJKLMNOPQRS 008f3300 54 55 54 68 65 20 71 75 - 69 63 6B 20 62 72 6F 77 TUThe quick brow 008f3310 6E 20 66 6F 78 20 6A 75 - 6D 70 73 20 6F 76 65 72 n fox jumps over 008f3320 20 74 68 65 20 6C 61 7A - 79 20 64 6F 67 00 00 00 the lazy dog... 008f3330 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00 ................ dump, when used with upvar arrays or standard variables will also show the parent linked-list chain. This may be useful to understand how variables work array 'b' level 3 (0x200bde0) data @33603120 (0x200be30) 7 byte(s) (Array data not shown. Use array walk arrayname) Address 0 1 2 3 4 5 6 7 8 9 A B C D E F ASCII -------- ----------------------- ----------------------- ---------------- 020cbe30 3C 61 72 72 61 79 3E 00 20 27 00 78 69 74 20 6C <array>. '.xit l + Parents of 3::'b' (0x20cbde0 / 34389472): + Value: '<array>' | | Lvl::Variable Name This -> Parent Type Const | ------------------------------------------------------------------ + 2::b 0x020cbe40 -> 0x020cb890 array False + Value: '<array>' + 1::b 0x020cb890 -> 0x020c9540 array False + Value: '<array>' + 0::b 0x020c9540 -> 0x00000000 array False + Value: '<array>' See also: vars, struct, calldll, dumpvariant, array walk, load, run
dumpvariant  Top  
dumpvariant address Defined in lib plugin: ticol_variant Displays information relating to a variant object which has been returned from a calldll*variant operation. This operation requires a valid variant address Example: set v [vsplit $qbf] # Split to Variant (SAFEARRAY) array dumpvariant v varray unset v Result: DUMP: Variant 'v' at 36012656 (0x2258270) Type is 8204 (0x200c) BYVAL Variant is an array of type 0xc Type is 12 byte Variant VT_VARIANT See also: dump, walk, vars, varray get, array walk
Easter Egg  Top  
There are no Easter eggs in Ticol. Such things would be impossible for man or machine See also: topic
Ticol Editor and Recommended IDE  Top  
Notepad++ is the recommended editor: https://notepad-plus-plus.org You can add the TCL syntax by copying the output of: puts [commands] Next, open Notepad++ and go to: Settings->Style Configuration->Tcl (from list) ->Instruction Word (from list) and then paste the list of functions into the "User defined keywords" area Executing Ticol Scripts from Notepad++ -------------------------------------- Click the "Run" menu option on the Notepad++ main menu Select "Run..." Click the elipsis button (...) to browse to the location of ticol.exe and select it Add a space to the resulting command line and append the following, wrapped in double-quotes: "$(FULL_CURRENT_PATH)" You should now have a command something like C:\path\to\ticol.exe "$(FULL_CURRENT_PATH)" Click "Save..." Enter an appropriate name, e.g. "Ticol Tcl" If desired select a shortcut such as CTRL+F1 Click "OK" to save You should now be able to run the current script using your shortcut or the menu You may need to add /NA to the command string to prevent autoexec.tcl from running, e.g. C:\path\to\ticol.exe "$(FULL_CURRENT_PATH)" /na You may also need to add /PAUSE to halt the screen before closing C:\path\to\ticol.exe "$(FULL_CURRENT_PATH)" /na /pause Note that command-line editing is non-existent via the menus, if you wish to change the command line you will need to delete the shortcut and recreate from scratch See also: Ticol, ticol.ini
echo  Top  
echo value|varname ?-var? Print a string without backslash escape translation other than performed by the Macro PreProcessor when the script is loaded. Echo is marginally more efficient than either [puts] or [printf] Additionally, [echo] with -var can output a string which contains Tcl code without the $ dereference causing the contained code to be executed. [echo] is equivalent to: puts [set value] except that a string value, not a variable is required as the only argument [echo] returns the untranslated string intact, and also does not append an additional carriage return/linefeed pair at the end. Use [newline] or puts "" after a call to [echo] if you wish to generate a new line Examples: echo $env(programfiles) puts [set env(programfiles)] puts $env(programfiles) Results: C:\Program Files (x86) C:\Program Files (x86) See also: puts, printf
elevate  Top  
elevate ?scriptname? ?command-line-arg...? Raise the current elevation level if running on Windows XP, 7 or higher by spawning a new instance of the Ticol interpreter You will be prompted for UAC if necessary. If the console or launching process is already elevated then the [elevate] command will be ignored Examples: # With no script loaded ######################## # Elevate the current session elevate # Elevate session and does not run autoexec.tcl elevate /na # With script loaded ########################### # Elevate the loaded script and run it elevate # Elevate and run the loaded script, doesn't run autoexec elevate /na # Elevate the script 'foo.tcl' elevate foo.tcl # Elevate the script 'foo.tcl' (filetype is optional) elevate foo # Elevate the script 'foo.tcl' with no autoexec.tcl elevate foo /na # Elevate the script 'foo.tcl' with 3 arguments elevate foo arg1 arg2 arg3 # Elevate the script 'foo.tcl' with 3 arguments, no autoexec elevate foo arg1 arg2 arg3 /na [elevate] can elevate any script which has been pre-loaded using [load] or will elevate specified scripts together with their optional arguments. [elevate] can also be used to run a script in elevated mode from the Ticol CLI Prompts depend on the current UAC setting to determine wither or not user-interaction may be required to grant elevated permission. Ticol cannot override this, [elevate] returns a boolean indicating whether the session is/was elevated successfully To exit an elevated Ticol CLI with no active script: type exit and press ENTER Elevation will work differently between Windows XP and 7 and this also depends on the service pack level for Windows XP. To kill an elevated instance of Ticol you will need to run pskill.exe from an elevated command prompt Use [is_elevated] to test whether or not a script is elevated As the spawned, elevated instance of Ticol will close automatically on exit you may wish to use this snippet to prevent the script from closing option expression off if {is_elevated} { pause } Example: puts [elevate] Result: 1 Example: if( ! [is_elevated] } { elevate } else { puts "[escape [info script] is running elevated" # ... pause } Result: # If UAC is accepted then will display <path-to-script> is running elevated Example: load test # Contains [elevate] command as shown above run Result: # The script is run in elevated mode Example: load tests # No [elevate] command present elevate # Elevate and run Result: # The script is run in elevated mode Chaining $argv to an elevated script ------------------------------------ The expansion operator can be used to pass a concatenated $argv() array if {! [is_elevated] } { set cmdline "" if { [array is_set argv] } { for {set i 0} {< $i $argc} {++ i} { append cmdline "$argv($i) " } } elevate {*}$cmdline } else { newline textcolor green puts "* [escape [info script]] is now elevated!\r\n" textcolor # ... further commands ... } See also: is_elevated, is_admin, spawn, exec, shell
Executable-Only Code Obfuscation (ticol.exe filename /c)  Top  
* For the ticol_tcx.dll plugin see: tcx plugin Code obfuscation/encryption or code-protection is available. This encrypts a Ticol source file to prevent inspection and tampering. You should only run protected and unprotected Ticol scripts from a source you trust. This option can apply only to a single Ticol file module. TCX files can be run either from the command-line or from the Ticol CLI console Where an output isn't specified when encoding, the filename will be used with the filetype-suffix ".tcx". When running .tcx files the filetype must be given The code is obfuscated and randomised. e.g. 000000 2C 15 72 09 1F 46 1B 40 - 78 77 66 0C 0F 7F 7F 0A ,.r..F.@xwf..+ 000010 29 7A 3F 4E 62 6A 2A 33 - 7B 05 6E 0F 41 77 16 3A )z?Nbj*3{.n.Aw.: 000020 7C 2D 6E 13 68 6F 4C 15 - 7B 77 5F 40 58 28 13 7D |-n.hoL.{w_@X(.} 000030 29 21 47 60 72 22 76 71 - 1A 1E 75 2A 39 34 47 4A )!G`r"vq..u*94GJ Advantages of Obfuscation ------------------------- Scripts may be emailed or transmitted securely. The contents are tamper- proofed which means their safety can be verified if the source is known and trusted and if checked using MD5 signatures. Source code and IP is not divulged to third-parties. MD5 signatures should always be used to check Macro Preprocessing, other than processing backslash escape sequences is performed in advance. These are not processed as the MPP will be run a 2nd time on the TCX file and strings with resolved \n sequences would be invalid. Advanced processing enables advance checking of basic syntax before runtime. Disadvantages of Obfuscation ---------------------------- Encrypted scripts could hide malicious code if run from untrusted sources You should never run a tcx script from an untrusted source nor if the MD5 is not verified. Preferably reserve protected code for internal use only. Treat protected Ticol scripts the same as unverified EXE files Use the sample MD5 check BAT file as a specimen for checking against a list of known scripts Note that the macro, "#exec" can cause scripts to be executed not only when scripts are run but when they are "compiled" using /C since the Macro PreProcessor will be invoke when compiling unless /NP is used You should only run (including obfuscate) scripts you trust and preferably only ones you generate and lock-down yourself Caveats on Code Protection -------------------------- Although the encryption type can be divulged, protected scripts cannot be decrypted back to the original source. The /ECHO command is disabled This is by design. You MUST retain unencrypted copied of any encrypted source code When running in breakpoint/debug mode the individual commands are shown at each breakpoint but the script summary is unavailable for TCX files. Likewise, the commands [commands], [functions] and [procs] will reveal the names of loaded code but not the code itself As the command [info body] may be necessary for scripts to run it is not blocked and will reveal code snippets for procedures only, but the main code and its structure are not revealed Security Verification --------------------- Use an external MD5 checking application or Ticol's /MD5 argument to generate a checkable MD5 signature Example: ticol.exe /md5 test.tcx Result: AC6960741A575B1C0928EEE817D72272 See TESTMD5.BAT for a specimen script to automatically check a TCX file before executing Encryption Syntax ----------------- ticol.exe tclfile.tcl ?output-file? /C?:<option>? ?/PW:<password>? The command-line option /C takes the following arguments Case is ignored for all options other than /C:PASSWORD /C:PASSWORD Requires /PW:<password> to be successfully encrypted /PW Values are optional for the remainder and if omitted, Local workstation/user details, Tcl version will be used /C Automatic encryption. No run restrictions. Can be run on any workstation and by any user. Source cannot be viewed or edited /C:VERSION Encrypt to be run only with a specific version of Ticol /C:PASSWORD Uses a password specified using /PW:<password> Will not execute unless password is specified /C:MAC Encrypt on the basis of a MAC address which must be present on the executing system /C:IP Lock to the first current (active) IP address /C:USER Encrypt to be run by a current Windows username /C:HOST Encrypt to be run on a specific workstation name /C:WINVER Encrypt to be run on a specific windows version (x.xx) Controlling WinVer execution is better done in real time /I Will display the encryption mode info for a protected file /MD5:<filename> Produce an MD5 string for any file. This may be used by an external script to verify a Ticol file which is about to be executed Operation Syntax ---------------- No arguments are required to run a protected file except /C:password ticol.exe filename.tcx # Run a default-encrypted file ticol.exe filename.tcx /pw:secret # Run a password protected file ticol.exe filename.tcx /i # Show obfuscation info ticol.exe /md5:filename.tcx # Show a tcx file's MD5 The encryption type is automatically detected. The only mode for which a password can be specified is that encrypted using /C:PASSWORD mode tcx files may be associated with ticol.exe to run as executable files. e.g. C:\>hello.tcx Hello World in such cases command-line arguments my not be passed properly Code Protection Examples ------------------------ ticol.exe foo.tcl /c # Obfuscated but no restrictions ticol.exe foo.tcl /c:mac /pw:01020365A690 # Run only on MAC 01020365A690 ticol.exe foo.tcl /c:user /pw:admin # Run only for user 'admin' ticol.exe foo.tcl /c:host /pw:server1 # Run only on host PC server1 ticol.exe foo.tcl /c:version /pw:1.23 # Run only on Ticol v1.23+ ticol.exe foo.tcl /c:password /pw:secret # Run only with this password Result: Creates 'foo.tcx' which can be run using the command: ticol.exe foo.tcx The MD5 signature of the new file will be displayed if successful. This should be stored if necessary for use with script validation CGI Mode -------- TCX scripts may be used as web-server CGI applications Security -------- Cryptographic features in this program are not cryptographically secure See also: run, load, Ticol, md5, md5_file
Embedding Ticol Tcl in C++ Programs  Top  
There are 4 methods of embedding/linking, neither of which have been made publicly available yet. 1) The use of a C++ LIB and DLL file for C++ projects 2) Direct inclusion of the main Ticol source code for C++ projects, with compilation macro variable flags set 3) Wrap and export ticol.exe as a DLL exposing all functions 4) Wrap and export ticol.exe as a DLL exposing [eval] only At some future point a mechanism for producing C++ programs with embedded Ticol Tcl may be released As there is no speed advantage to embedding Tcl within EXE files, this is a very low priority Example Calling ticol.dll ------------------------- An alternative to embedding Ticol Tcl within binary code is to call ticol.dll (an experimental DLL version of the Ticol interpreter), from C++ code ... // Example C++ calling ticol.dll (__stdcall DLL) // Ensure stack is sufficient #pragma comment(linker, "/stack:0x300000") #include <windows.h> #include <stdio.h> int main(int argc, char** argv) { LPSTR ptr=NULL; long breakpoint=0; long errnum=0; // Don't indent multi-line literal // Some compilers may restrict the size of string literals LPSTR script="\ textcolor magenta\r\n\ puts \"Hello world\"\r\n\ textcolor\r\n\ "; LPSTR (__stdcall* ticol_command)(LPSTR s, long, long*); HINSTANCE hAPI=LoadLibraryA("ticol.dll"); if(hAPI) { ticol_command=(LPSTR (__stdcall*)(LPSTR, long, long*)) \ GetProcAddress(hAPI,"ticol_command"); if(ticol_command) { printf("test: Loaded DLL ticol.dll->ticol_command()\r\n"); ptr=ticol_command(script,breakpoint,&errnum); printf("test: ticol_command: Returned result:'%s' errorcode:%li\r\n"\ ,(ptr?ptr:"NULL"),errnum); } else { printf("test: Failed to ticol_command in ticol.dll\r\n"); return 1; } } else { printf("test: Failed to load ticol.dll\r\n"); return 2; } return 0; } See also: plugins, Ticol
encrypt  Top  
string [encrypt string|var password] Encrypt a string or variable to a base64 string using moderate-strength symmetric encryption. Encryption will result in string size increase due to base64 encoding [encrypt] should not be used to store highly-vulnerable information such as credit cards, personal or bank details etc. For high-strength secure encryption call an external DLL or API which offers AES or similar asymmetric encryption If you require stronger encryption use [calldll*] to call an external encryption library Example: puts [encrypt "Hello world!" secret] puts [decrypt [encrypt "Hello world!" secret] secret] Result N4w8n7XnePSvob9G Hello world! Security -------- Cryptographic features in this program are not cryptographically secure External routines should be called for security cryptography See also: decrypt, base64, mkn, cvn
Embedded TCX Plugin  Top  
Load using: lib ticol_tcx?.dll? result [tcx "base64-block" ?-password password? ?-run?] string [tcx "base64-block" ?-password password?] The ticol_tcx plugin allows blocks of obfuscated Ticol Tcl code to be embedded within windows batch or other Ticol Tcl scripts Extreme caution should be used when executing such code from unknown or untrusted sources. The use of [md5] is recommended to check the code has not been modified. (See: md5) If the ?-run? argument is used, the result of the script will be returned after being submitted to [eval], otherwise, if omitted the script text will be returned. Arguments are not directly currently supported via [tcx] but you can set argc and argv consts as follows: # Example setting argc and argv to pass to a [tcx] block # This example is for Towers of Hanoi (hanoi.tcl) with 15 hoops unset argc -const -nocomplain unset argv -const -nocomplain set argc 2 # 2 arguments to be passed set argv(0) "" # 1st argument will be the script name (not required) set argv(1) 15 # 2nd argument will be the ring count Decrypt failure will return an error code (2) and should be handled using [try] or [catch] A companion utility called base64.exe can be used to convert TCX code into base 64 format text for use with [tcx] or the /64 argument can be used with the /C argument. Base64 encoded TCX code can only be executed by the [tcx] command, not by ticol.exe directly Example: # Uses default encryption # Encode using ticol.exe filename.tcl /c /64 # Or using base64.exe filename.tcx to encode set code "ibuhXiuUJYyD6Uubn7G4L/wRkK/BtOkaHi5IFuULSaPU/3YskM139se IuesC7KEhQjprZY83PyZAqzgwFmlfnIkpMMmSMvs=" # Load the plugin lib ticol_tcx # Execute the code (call [eval] internally) tcx $code -run Decoded script: textcolor yellow puts "Hello World" textcolor ; Results: Hello world Note that Ticol's string processor doesn't care how the quoted base64 string is formatted. Line-endings are ignored and this would work just as well. set code "ibuhXiuUJ YyD6Uubn 7G4L/wRkK/BtOkaHi5IFuULSaPU/3Y skM139se Iues C7KEhQjprZY83PyZAqzgw FmlfnIkpMMmSMvs=" Code validation can be performed using [md5] Example: # Encode using ticol.exe filename.tcl /c which will also generate the # MD5 value, and then: base64.exe filename.tcx set code "<some-block-of-tcx-code-generated-via-the-above-method>" if {ne [md5 $code] 2e65ca46a5e2e605e5e675d935033c1a} { textcolor red die "Error: MD5 validation failed at line "#__LINE__ textcolor } # Otherwise, continue and evaluate tcx $code -run See also: tcx, base64
enum  Top  
enum var ?var? ... enum var = integer ?var = integer? ... enum {var|var = integer ?var|var = integer? ...} A simple implementation of enumerated integer constants. You cannot assign to an enum. Enums will have visibility scope at the level where they are defined and each member will be treated as a separate const variable Enums are assigned values in sequence starting at zero to guarantee they are unique. Names may not have already been assigned to a const or variable Member names must be unique Assignment is optionally permitted in any number format which resolves to a signed integer. The enum increment sequence will continue to increment by +1 from that number in the next constant. The assignment operator '=' must be separated by a space or tab character [enum] avoids more convoluted methods of declaring a unique series of variables [enum] const values will typically be created in global scope and can be accessed from within procedures using the $::constname scope prefix Enumerated values cannot be assigned but they can be [unset] and re- declared. You must call as [unset varname -const] Example: enum zero one two three Result: integer three 3 integer two 2 integer one 1 integer zero 0 Example: enum zero one six = 6 seven Result: integer seven 7 integer six 6 integer one 1 integer zero 0 Example: enum {quick brown = 3 fox} Result: integer quick 0 integer brown 3 integer fox 4 Example: (For Windows MessageBox API) enum { MB_OK MB_OKCANCEL MB_ABORTRETRYIGNORE MB_YESNOCANCEL MB_YESNO MB_RETRYCANCEL MB_CANCELTRYCONTINUE MB_ICONSTOP = 0x10 MB_ICONERROR = 0x10 MB_ICONHAND = 0x10 MB_ICONQUESTION = 0x20 MB_ICONWARNING = 0x30 MB_ICONINFORMATION = 0x40 MB_ICONASTERISK = 0x40 MB_DEFBUTTON1 = 0 MB_DEFBUTTON2 = 0x100 MB_DEFBUTTON3 = 0x200 MB_DEFBUTTON4 = 0x300 MB_APPLMODAL = 0 MB_SYSTEMMODAL = 0x1000 MB_TASKMODAL = 0x2000 MB_HELP = 0x4000 } Example: enum zero one two unset zero -const unset one -const unset tw* -const -nocomplain See also: const, set, unset, vars, walk
error  Top  
error message ?info? ?returnCode? ?line? Raises an error condition The [error] command may be used in conjunction with catch to display/set error strings message is an informative error message. info gives more information about the error. code is intended to be a numeric error code. Line is optional and non-standard and may report the line number by using the #__LINE__ macro together with a variable Example: option expression off proc Div {a b} { set line #__LINE__ if {== $b 0} { error "Error generated" "Info for error" 1 [- $line 1] } else { return [/ $a $b] } } Div 3 0 See also: catch, return
Ticol Errors  Top  
Some common Tcl/Ticol errors; Example: my_proc [[string left [getenv PROMPT] 4]] Result: eval: No such command or procedure '$P$G' Fix: Remove an outer layer of square brackets from an evaluation checkex [string left [getenv PROMPT] 4] Reason: The outer brackets will try to evaluate the string which is returned and it will be executed as a Ticol or Windows command See also: error, debugging
Error Codes  Top  
Ticol error code return values are as follows These are returned by [catch] but may be passed as option arguments to other commands such as [return] 0 Success 1 Error 2 return statement met 3 break statement met 4 continue statement met 5 exit statement met 6 stop statement met 7 goto statement met 8 value already defined See also: error, catch, return
Chaining Tcl Commands  Top  
Many commands are able to be chained together to form command sequences Example: set r [msgbox [join [split $qbf " "] "\n" 768] "Choose" 36] msgbox "You chose [map {6 Yes 7 No} $r]" See also: K combinator
eval  Top  
string [eval expression] eval filename.tcl|filename.tcx ?arg ...? Evaluate a Tcl expression, a Ticol tcl or obfuscated tcx script file For simple commands it is more efficient to call directly than via [eval] (e.g. [+ $x $y] [min $x $y] v's [eval "+ $x $y"] [eval "min $x $y]) Standard Tcl expressions are in 'prefix' format whereas expr expressions are in 'infix' format. If the filetype ".tcl" is included a script file will be searched-for. Unlike [run], [eval] requires that the ".tcl" extension must be given for Tcl scripts [eval script] will run the named script. If this script is intended to contain only [proc] or other definitions then these must be kept in a separate include script Note: [eval script] will perform a time-consuming Macro PreProcess on the script each time it loads. Do not load repeatedly in loops TCX files which do not require a password may be passed Example: puts [eval "> 10 2"] Result: true Example: eval hanoi.tcx 17 Result Loads, decrypts and executes hanoi.tcx setting argv(1) to 17 Tcl script files may be called/chained from a script by using eval, with execution returning to the original script. Note that variables for a chained script exist in the same namespace (true namespaces are not supported) so care should be taken to avoid clashes in variable names in the chained script. Arguments cannot be given [eval filename] will not reset the interpreter command count Example puts "Calling child script" eval child.tcl puts "Parent script is still here" Freeform/unquoted number formats understood by eval are as follows: decimal values NNNN hexadecimal prefixed by 0xNNNN octal prefixed by 0oNNNN binary prefixed by 0bNNNN Note that where a script which calls other TCL files is encrypted as a TCX file, this does not alter those TCL links to TCX format. If you wish to "chain" to TCX files you must write the script to call TCX versions of a file before encoding Note that chaining scripts may accumulate uncleared variables. A script should clean-up its own global variables before exit if it is likely to be called by another script. Local proc variables are cleared autormatically. (See: clear, unset) See also: expr, bool, math, ticol, clear, unset, tcx
Ticol Windows Event Log Handling Plugin  Top  
To load, use: lib ticol_event ?-verbose? ?-nocomplain? bool [event is_source name] bool [event add name ?0..4?] bool [event remove name] bool [event log name string type ?postscript?] [event] offers basic Windows event logging commands. [event add] requires Windows UAC elevation and adds an SZ_EXPAND registry event entry under: "SYSTEM\\CurrentControlSet\\Services\\EventLog\\Application\\%s" and this registers ticol_event.dll as the string table source for event messages. Only 4 basic message types are supported The following Macro defines are useful. Note that these can only be used outside quoted strings #define EVENTLOG_SUCCESS 0 #define EVENTLOG_ERROR_TYPE 1 #define EVENTLOG_WARNING_TYPE 2 #define EVENTLOG_INFORMATION_TYPE 4 Note ---- If an event source is removed then the Windows Event Log application will no longer be able to query the string table of the linked Ticol plugin DLL. You will see an error: The description for Event ID N from source XXXX cannot be found. The event source should be left registered as long as ticol_event.dll is installed on the system and you need to query related events Example: #define EVENTLOG_INFORMATION_TYPE 4 lib ticol_event if {[is_elevated]} { if {event add ticol EVENTLOG_INFORMATION_TYPE} { puts "Added an event to the event log" } else { puts "Failed to add an event" } puts [bool [event is_source ticol] } Results: (If elevated) True See also: is_elevated, elevate, plugins
Exception Handling  Top  
The following commands are useful in handling exceptions: catch try / catch error The following variables are pre-defined and set on an error condition arising Name Type Comments ::errorCode Var Tcl error code sent to a the console ::errorLine Var May be preset using the #__LINE__ macro ::errorMsg Var Error message generated by a Ticol error Fatal exceptions generate no errorMsg variable ::errorInfo Var Additional information See also; try, catch, error
exec  Top  
exec program ?arg? ?arg...? @program ?arg? ?arg...? @ program ?arg? ?arg...? shell Run an external program from the Ticol shell. Ticol can be used as a Windows command shell. If autoexec is "on" then unrecognised commands will be shell-executed Prefixing a command with '@' can be useful to override conflicts with built-in commands. [shell] launches an instance of CMD.EXE. Type exit to exit and return to Ticol To grab the output text from a spawned application, see the [spawn] command CTRL+C is available for external applications, if quit using CTRL+C then execution will be returned to the Ticol CLI shell Examples: @type ticol.man # Call the Windows command shell exec dir *.tcl /s # Use [exec] to spawn the command ftp localhost # Call the program directly xcopy *.* \\server\share\folder # Call xcopy with arguments See also: autoexec, spawn, exit
Examples  Top  
Various example scripts are included with the standard Ticol distribution This includes a series of test files See also: Tcl, Ticol, faq
exit  Top  
exit ?errorlevel-value? Exits a Ticol Tcl program. If the program was launched from a Windows console then execution will return to the console. If launched from the Ticol CLI then execution will return to the CLI The errorlevel value will be returned to the operating system CTRL+C is disabled in Ticol. If you wish to quit the CLI prompt, either press CTRL+BREAK or type 'exit' at the CLI prompt See also: stop, at_exit, return
explain  Top  
string [explain expression] Explain the Polish Notation (PN) interpretation of an expression as used with [calc]. The expression handler, [expr] does not translate into Polish notation The result of [explain] may be evaluated using [eval] Example: puts [explain 2+2*0+2] puts [eval [explain 2+2*0+2]] Result: [+ [+ 2 [* 2 0]] 2] 4 See also: calc, expr
expr  Top  
string [expr expression items] string [expr {expression-group}] string [expr "expression-string"] string [expr arg arg...] Evaluates a mathematical expression held in a Tcl string or variable Expressions within 'expr' allow 'infix' format whereas native Tcl 'eval' commands are in 'prefix' notation as [operator var1 ?var2?], Individual [expr] arguments may be grouped by double-quotes or braces but will otherwise be concatenated into a single argument. It is strongly recommended that the argument to [expr] be wrapped in braces or double- quotes or complex expressions, (particularly multi-line) will be mis- evaluated [calc] is recommended as an alternative to expr for expressions not generated at run-time. [calc] will reduce the natural-expression to 'Polish notation' format which runs faster than iterating over the expression interpreter Examples: option echo on expr 2*3+2 # Internal precedence expr 2*(3+2) # Natural expression with brackets expr 2*[+ 3 2] # Infix sub-command expr "2*[+ 3 2]" # Infix sub-command (quoted) expr {2*[+ 3 2]} # Infix sub-command (braced) Result: 10 10 10 10 10 Expression operators include: + - * / & | ^ &= |= ^= > < >= <= == != == += -= *= /= %= >> << && || ** ? () Note that: ++ and -- are not supported other than as embedded [++] commands You may intermingle expression functions, procedures, bracketed commands, constants, variable names etc. within the expression string. Standard BEDMAS operator precedence applies unless curved parentheses are used to group A wide range of arithmetic functions are supported. See "functions" for more information. Curved brackets may be used to prioritise sub-expressions Parity checks are made on bracket pairing Number evaluation follows Tcl rules. All numbers are evaluated as integer unless a decimal point is specified. Division will therefore be truncated to integer unless a decimal point is given for the divisor Freeform expressions are also permitted but it is recommended that expression-strings are braced or enclosed in double-quotes Performance ----------- Because it is a generalised expression-handler with significant syntax- checking overheads and which calls the underlying Tcl routines, [expr] may be far slower than decomposing an expression into component operations with Tcl 'prefix' syntax. See [calc] for an optimised equivalent to [expr] Example: set src [expr ($x & $y) % 3] # Freeform expression syntax set src [expr {22/7.0}] # Braced expression syntax set src [expr "22/7.0"] # Quoted expression syntax set src [% [& $x $y] 3] # Decomposed commands (~50% faster) The Macro PreProcessor (MPP) may be used to optimise expressions into native Tcl commands (see [calc] which is a substitute command which will auto- optimise expressions into simpler Tcl commands) Embedded Commands ------------------ Tcl commands may be embedded within expressions. These will be evaluated first but do not affect overall operator precedence - e.g. Use: puts [expr 22/7.0+[incr 2]] -> 6.142857142857142 Not: puts [expr 22/7.0+incr 2] Use: puts [expr [incr 10]] Not: puts [expr "incr 10"] Whitespace ---------- Whitespace is handled between bracketed expression calls but the expression should ideally be wrapped in double quotes or curly braces to ensure safe grouping Examples: expr 22 / 7.0 expr 22/7.0 expr "22/7.0" Returns: 3.142857 Whitespace is permitted it is recommended that it is avoided Number Formats -------------- The following 64-bit encoded number formats are understood by [expr]: decimal any base 10 number 12345 hexadecimal prefixed by 0xNNNN 0x3039 octal prefixed by 0oNNNN 0o30071 binary prefixed by 0bNNNN 0b11000000111001 Transiting Array Brackets ------------------------- An [expr] statement does not transit expression array () brackets. While array indices may contain expressions those expressions are not resolved unless they are in Tcl "command" format e.g. [* 2 3] or if the [expr] command is used Thus: [expr $a(22/7*2)] would be one of: [expr $a([expr (22/7)*2])] [expr $a([* [22/7] 2])] Note that [calc] will attempt to resolve all sub-expressions, including array parentheses expressions Incorrect Use ------------- Tcl commands which are not part of the [expr] syntax cannot be embedded without square brackets. Commands [++] and [--] are not allowed as these conflict with arithmetic addition/subtraction followed by sign value Example: set a 1;puts [expr "set b; ++ $a"] # ;separators are not valid set a 1;set b [expr "[++ $a]"]; puts '$b' # Valid Caution ------- Because Tcl does not distinguish between data types you should avoid passing unchecked string data into [expr], particularly string data which may contain valid Tcl commands. This is because the arguments will be evaluated Example: set s "@format c: /y" expr "$s == {}" # This could be bad! instead, embed string comparison commands such as [eq] or [string equal] as follows... set s "@format c: /y" expr [eq $s {}] https://en.wikipedia.org/wiki/Polish_notation See also: calc, eval, bool, functions, math, arrays, inttohex, inttooct, inttobin
fib (Fibonacci)  Top  
integer [fib n] Compute Fibonacci series value from 0 to 93 Accessing a value over 93 will return an overflow error [fib] uses a rapid, iterative method of calculation internally Example: option expression on for {set j 0} {$j < 81} {incr j} {puts "$j [fib $j]"} Result: 0 0 1 1 2 1 3 2 4 3 5 5 6 8 7 13 8 21 9 34 10 55 11 89 12 144 13 233 14 377 . . . See also: math, big
file  Top  
Enhanced Tcl 'file' command Offers a variety of stream-based file manipulation commands as well as O/S-like commands. These are similar to those offered by the "C" language Many of the sub-commands can be used independently without the 'file' prefix file attributes filename # Return a Tcl list of common attributes file close fp # Close an open file file delete filename # Delete a file (alias for unlink) file dirname name # Return the directory name of a filename/path file eof fp # Tests file-read for end of file condition file executable filename # Tests if a file is executable, return 1 or 0 file exepath # Return the path of the Ticol executable file exists filename # Test if a file exists file extension filename # Get the filename-extension file flush fp # Flush file output to a stream file gets fp ?var? ?bytes? # Read a line of text data from an open file # Returns string or count of bytes if var given file isdirectory filename # Test if filename is a directory file isfile filename # Test if filename is a file file isroot path # Test if an unescaped path is root, X:\ or \ file md5 filename # Generate an MD5 value for a file file mkdir filename # Create a directory file name filename # Return the filename+ext only (non standard) # "C:\path\to\my.txt" gives "my.txt" file normalize filename # Get the full, normalised path of a filename # e.g. win.ini in c:\windows\system32 gives # c:\windows\system32\win.ini file open filename # Open a file for reading or writing # Returns a file handle file pathcount filename # Return count of path segments (\\ or /) file readable filename # Check a file for read access & return 1 or 0 file rename oldname newname # Rename a file file rewind fp # Rewind the file pointer of an open-file file runtype filename ?-v? # Tests executable run type # Returns code: Optional -v verbose flag # -1 unknown Unknown type/non-executable # 0 32bit 32-bit Windows exe # 1 dos DOS executable # 2 wow Windows on Windows64 exe (wow) # 3 pif PIF file # 4 posix Posix binary # 5 os216 OS/2 16-bit exe # 6 64bit 64-bit Windows exe file seek fp offset # Set/place the file pointer of an open-file file size filename # Get the size of a filename (64-bit) file split filename # Split a path into components in list format # {drive: path filename} file stat filename var # Retrieve 'stat' data. See: file stat file tell fp # Get the file-pointer location of an open-file file type filename # Return file, directory, link or unknown file unlink filename # Delete a file (alias for delete) file volumes # Return a Tcl list of valid volumes file writeable filename # Check file/dir for write access. Returns bool Examples: -------- All examples are with: option echo on Example: file attributes autoexec.tcl Result: -archive 1 -hidden 0 -system 0 -readonly 0 -longname autoexec.tcl \ -shortname {} Example: file readable autoexec.tcl Result: 1 Example: file type autoexec.tcl Result: file Example: file volumes Result: C:/ D:/ E:/ F:/ G:/ I:/ J:/ See also: info, exists, filesize, mkdir, mkdirs, unlink, dir, input, normal_path, unc paths
file exists  Top  
bool [file exists filename] Check if a file exists or not Example: puts [file exists ticol.exe] Result: 1 See also: file
file pathcount  Top  
integer [file pathcount filename] Returns a count of the individual path segments (including any filename) [pathcount] accepts backslash or Unix-style forward slash characters If using backslash characters then [pathcount] requires an 'escaped' path Use [escape] to escape a path string delimited by single backslash characters Examples: puts [file pathcount c:\\] puts [file pathcount c:/] puts [file pathcount c:\\file.txt] puts [file pathcount c:/file.txt] puts [file pathcount c:\\path\\to\\some\\file.txt] puts [file pathcount [escape c:\path\to\some\file.txt]] puts [file pathcount c:/path/to/some/file.txt] Results: 1 1 2 2 5 5 5 See also: file
file stat  Top  
bool [file stat filename arrayvar] Fills an array with _stat information using the C++ '_stat()' function The array variable referenced in the argument must not exist. A boolean True (1) is returned if the file exists, False (0) if it doesn't Example: file stat ticol.exe a array foreach a val ss { puts "\$a($ss)\t$val" } Results: $a(mode) 33279 # Protection $a(ino) 0 # inode number (always 0) $a(dev) 2 # ID of device containing file (A==0) $a(atime) 1481501018 # C time of last access $a(mtime) 1481501108 # C time of last modification $a(gid) 0 # Group ID of owner (always 0) $a(size) 190976 # Total size, in bytes $a(nlink) 1 # Number of links (always 1) $a(rdev) 2l # device ID (if special file) $a(ctime) 1481501018 # time of last status change $a(drive) C # Drive letter of 'dev' (upper case) $a(uid) 0 # User ID of owner (always 0) References: https://msdn.microsoft.com/en-us/library/14h5k7ff.aspx https://stackoverflow.com/questions/6094665/how-does-stat-under-windows-exactly-works See also: file
file gets  Top  
string [file gets fp ?var? ?bytes?] Read a line of text data from an open file Returns a string value if no variable specified, else returns the count of bytes successfully read if a var argument was given. If an EOL byte sequence is encountered before 'bytes' have been read then a short count will be returned. If 'var' does not exist it will be created in the current scope [file gets var] will always clear var to {} if it exists Example: set fp [file open [unescape $argv(1)]] set r [file gets $fp s 100] puts "s is '$s" file close $fp Result: <Text from input file up to 100 chars or first CRLF sequence> See also: readfile, file
filesize  Top  
integer [filesize filename] Returns the size of a given file in bytes as a 64-bit value See also: file, unlink
find (Help)  Top  
find string find "string with spaces" Search the Ticol manual for topics which contain a given search string Since the macro preprocessor (MPP) processes all Ticol command-line arguments including both 'help' and 'find', this will affect the ability to search for the # character (which is interpreted as a comment) See: help option PreProcessor Example: user@host> find upvar Result: Help topics containing keyword 'upvar' arrays subsequent upvar command. To pass an array by value at_exit The upvar command is required to access variables d combinatory logic upvar 1 $_stack stack comparing ticol with php Standard (downwards) variable inheritance No (upva const declared using upvar to create a local const instan contents upvar Reference a variable in a higher differences global Global is an alias for upvar dump dump, when used with upvar arrays or standard varia find user@host> find upvar See also: help
for (Flow Control)  Top  
Provides a for iterator similar to that of C/C++ With: option expression on (Standard Tcl): Default: for {init-eval} {condition-expr} {post-eval} {eval-code} With INI ForInitAllowsExpression=TRUE for {init-expr} {condition-expr} {post-eval} {eval-code} for {[init-eval]} {condition-expr} {post-eval} {eval-code} This uses an [expr] statement as the 3rd (condition) argument and if configured, can optionally use an [expr] statement for the 2nd (init) argument With: option expression off (Non-standard): for {init-eval} {condition-eval} {post-eval} {eval-code} This uses an [eval] statement for the 3rd (condition) argument The following additional commands are available for use with [for] return # Will exit the script when used in root-level [if] break # Will be passed back to any enclosing structure stop # Halt operation, return to the CLI if loaded exit # Exit the script and return to Windows goto # Where used with an enclosing [goto_block] continue # Resume execution at the head of the [for] loop Flow-control for loop Example with single loop variable option expression off for {set i 0} {< $i 10} {incr i} { puts "i is $i" ++ j } option expression on for {[set i 0]} {$i < 10} {incr i} { puts "i is $i" ++ j } Example - Handling multiple loop variables: option expression on for {[set i 0]; [set j 0]} {($i < 10) && ($j < 10)} {incr i; incr j} { puts "i is $i, j is $j" ++ j } option expression on for {[set i 0; set j 0]} {$i < 6} { ++ i; ++ j 2} { puts "i=$i; j=$j" } option expression off for {[set i 0]; [set j 0]} {[expr ($i < 10) && ($j < 10)]} {[incr i]; \ [incr j]} { puts "i is $i, j is $j" ++ j } See also: loop, while, do, time, flow control
Control+C (break)  Top  
The standard interrupt handler CTRL+C is disabled to prevent accidental or undesired exit from a Ticol script. Script execution can be terminated using CTRL+Break instead See also: break, exit, stop
Flow-control: for foreach array_foreach, if elseif else, switch while do  Top  
The following construct flow-control constructs are supported: array foreach # Iterator carray foreach # Iterator catch # Error handler do # Iterator for # Iterator foreach # Iterator if # Branching linkedlist foreach # Iterator loop # Iterator stack foreach # Iterator switch # Branching time # Iterator try/catch # Error handler varray foreach # Iterator while # Iterator Details ------- array_foreach array element ?subscript? {code-body} carray foreach handle lvalue ?rvalue? {code-body} catch {code-body} do {code-body} while {...} for {initiator} {condition-test} {post-action} {code-body} foreach variable list {code-body} foreach varlist1 list1 ?varlistN listN ...? {code-body} if {condition-test} else {...} if {condition-test} elseif {...} ... else {...} linkedlist foreach handle lvalue ?rvalue? {code-body} loop variable start limit ?increment? {code-body} stack foreach varName indexVar {code-body} ?-r? switch ?options? {arg} {{case script} ... | {default script}} time ?expression? ?iterations? ?-info | -quiet? try {code-body} catch {code-body} varray foreach handle variable {code-body} while {condition-test} {code-body} Additionally: the following keywords are available: break # Exit the loop continue # Continue execution from the loop head default # (For use with [switch] only) die # Exit to windows with message exit # Halt processing and exit to Windows goto # Only valid within a [goto_block] return # Return from the loop with optional code etc. stop # Halt processing and return to the CLI Behaviour is modified by: option expression on|off if/else/elseif keywords must be separated by whitespace. The Tcl syntax requires that the opening brace following if, else, elseif, be on the same line as the command. e.g. (See: brace style) if { condition } { # Correct layout (K&R/Tcl) statement } elseif { condition } { statement } else { statement } if { condition } # Incorrect layout (Allman/BSD) { statement } else if { condition } { statement } else { statement } while { condition } { # Correct layout (Tcl) statement } while condition { statement } # Correct layout (Tcl) do { # Correct layout (Tcl) statement } ?while? {condition} do {statement} {condition} # Correct layout (Tcl) set i 0 do { # Correct layout (Tcl) puts "i is $i" if {== $i 2} { return } incr i } while { $i < 10} while 1 {puts [rnd 1 10] } do {puts [rnd 1 10] } while 1 All of the above cases support the break or continue keywords break exits the block loop structure such as while, for, foreach continue jumps to the start of any block structure and repeats Return values set using 'return' can be passed from while or do-while by chaining from 'set' - e.g. set r [do { ... if { $i == 2 } {return string} set r [while { ... if { $i == 2 } {return string} If 'option expression' is set to ON then expr with infix notation will be used for tests instead of the default of eval with prefix notation A limited-scope form of goto is supported within a goto_block (see goto_block) See also: for, foreach, array_foreach, if, elseif, else, switch, while, do, loop See also: option expression, foreach, array foreach, if, proc, return, at_exit, linkedlist, carray, stack, loop, try, catch
break  Top  
break Halt execution within a flow-control block such as [for], [while], [do] or [goto_block] If executed outside a flow control block and at level 0 (root) [break] will exit the current script and have the same effect as [exit] [break] is not valid within other flow-control structures Example: option expression off for {set i 0} {< $i 10} {incr i} { if {== $i 5} {break} } Example: break Result # Script exits See also: flow control, continue, stop, exit, return
continue  Top  
continue Continue execution of a loop structure from the head of the loop [continue] skips any body code and executes the increment argument of a [for] loop. Relevant to [for] [foreach] [while] [do] Example: # print a line for each of the integers from 0 to 10 except 5: option expression on for {set x 0} {$x < 10} {incr x} { if {$x == 5} { continue } puts "x is $x" } Result: x is 0 x is 1 x is 2 x is 3 x is 4 x is 6 x is 7 x is 8 x is 9 Example: option expression off set sum 0 set x 0 while {< $x 10} { incr x # Pre-increment before [continue] if {== $x 5} { continue } puts "x is $x" += sum $x } Result: x is 1 x is 2 x is 3 x is 4 x is 6 x is 7 x is 8 x is 9 x is 10 See also: flow control, break, stop, exit, return
Handling filenames and paths  Top  
Ticol handles both / and \ path separators in filenames. Within complex strings and expressions it may be preferable to use / as this does not need to be escaped and avoids problems with 'double unescaping' Literal strings must have the \ character 'escaped' as \\ Example: set filename "c:/path/to/file.txt" # Correct set filename "c:\\path\\to\\file.txt" # Correct set filename "c:\path\to\file.txt" # Incorrect (\t is a TAB) Command Line Use ---------------- When using filenames from the CLI this behaviour is modified to allow unescaped paths. See: option escape for more information See also: escape sequences, escape, unescape, option escape
fpart  Top  
integer [fpart double-value ?precision?] Return the fractional part of a double value as an integer The precision part must be >= 1 and <= 10 [fpart] preserves any zeroes after the decimal, stripping the sign, leading zero (if any) before the decimal point and the decimal point itself Example: puts [fpart $pi] puts [fpart $pi 2] puts [fpart $pi 6] Results: 1415926535 14 141592 Example: puts [fpart 0.12] Result: 1200000000 Example: # Splitting a double value for processing with reassembly puts "[integral $pi].[fpart $pi 7]" # Recommended puts "[integral $pi].[fraction $pi]" # Bad idea! Result: 3.1415926 3.0.141592653589793 Example: puts [fpart [dateserial - - - 2 4 6]] puts [time .[fpart [dateserial - - - 2 4 6]]] Results: 0861805555 02:04:06 See also: fraction, integral
fraction and integral  Top  
double [fraction realValue] double [integral realValue] Returns either the fractional or integer part of a real number (float) Example: fraction [expr atan(1)*4] Result: 0.141593 Example: integral [expr atan(1)*4] Result: 3.00000 Note: Use [fpart] to retrieve the decimal fraction as an integer value See also: fpart, math
Ticol Introspection and Reflection  Top  
Ticol has modest commands for type reflection and introspection, as follows: array walk # Dump a variable's contents cmdcount # Count of the # of executed commands dump # Dump details of a standard variable or struct dump # Show syntax-highlighted source code dumpvariant # Dump the contents of a variant info # Various introspective commands mem_used # Returns the current memory used by Ticol trace # Display calls and shows results type # Display variable type names walk # Dump the variable table at any callframe level watch # Set a variable watch for use with breakpoints /echo # Show Macro PreProcessed source code /bp # Breakpoint execution stacktrace /g # Performance graph Variables also exist which reveal information about the system These can be inspected using the command [vars -const] string exe_name string tcl_date integer tcl_cli string tcl_config integer tcl_threaded float tcl_version integer tcl_precision array env empty argv0 integer argc See also: debugging
doevents  Top  
doevents ?count? ?-sleep? This is analogous to Visual BASIC's DoEvents command. [doevents] yields thread control to Windows and allows processing of the Windows message queue. doevents may be combined with sleep to minimise CPU use during tight loops. [doevents] will poll the Windows message queue An optional count argument may be added which will cause [doevents] to poll a given number of times. Additionally, a 'sleep' of 10ms may be performed during each loop. You can use [sleep 0] to achieve a similar effect Example: set i 0 while {$i < 1000000 } { # A tight, CPU-intensive loop doevents incr i sleep 0 } See also: sleep
flush  Top  
flush ?stream? Flushes output to an open file stream. This may include the symbolic strings stdout and stderr as well as open file handles See also: open, close, file
foreach (Flow Control)  Top  
foreach var list ?var list...? {script} foreach {varlist} list ?{varlist} list...? {script} foreach var|{var...} list|{vars...} {script} Iterates the RValue (right hand value) list using LValue (left hand value) variable(s) as placeholder(s) for the list item(s) Can be considered equivalent to the pseudocode ('in' is not supported): foreach variable in list {script} If a literal list of items is given then it should not be wrapped in braces to ensure grouping. If a braced list of variables is given then don't enclose in quotes or braces. Rvalue variables should not be braced as this will prevent evaluation. LValue variables may be braced The opening brace of the body statement should be on the same line as foreach. See the rules about grouping in Tcl in the Tcl documentation If a break statement is encountered before the list is exhausted, the tail of the list will be returned. foreach f [ls "c:\\windows\\*.*" -af -list] { puts "File: $f" foreach {f g} {one {two three} four five six {seven eight} nine ten} { puts "Items f g: $f, $g" } ls *.* a -la -list foreach {i j k l} $a { # Lvalue vars may be braced to group puts "$i, $j, $k, $l" } foreach f {one two three} {puts "$f,"} set args {one two three four} set arg [foreach {a b c} $args break] foreach s [commands] {puts $s} set l [array list argv] foreach s $l {puts $s} Example: set a "1 2" set b "3 4" foreach x $a y $b {puts "$x $y"} Results: 1 3 2 4 When using with arrays take care to wrap multiple Lvalue variable arguments in braces WRONG: foreach x y [array get env] {puts $x=$y} RIGHT: foreach {x y} [array get env] {puts $x=$y} foreach may also be used to split lists into variables using an empty body set s "123 456" foreach {p q} $s {} Admin@Lenovo 134> vars Defined variables at level 0 ---------------------------------------- integer p 123 integer q 456 See also: for, while, time, switch, array_foreach, list, ls, ticol
Form Input  Top  
The [input] and [gotoxy] commands can be used to create simple form-based input screens to capture user-input. There is no support for Tk and Windows GUI based forms Example: # Prompt for 3 basic input fields cls textcolor white darkmagenta puts " * Ticol Demo Form Input * " textcolor if {< $tcl_version 1.26} { puts "Error: Requires Tcl v1.26 or higher. Found v$tcl_version" die } proc at_exit {} { gotoxy 1 15 } box 4 4 74 7 gotoxy 6 6 puts "Enter your name: ________________________________________" gotoxy 6 7 puts "Enter your age: ___" gotoxy 6 8 puts "Enter your address: __________________________________________________" gotoxy 6 6 puts "Enter your name: " -nonewline gotoxy 26 6 set name [input 40 -f white -b red] textcolor if {eq $name ""} return gotoxy 6 7 puts "Enter your age: " -nonewline gotoxy 26 7 set age [input 3 -f white -b blue -password] textcolor if {eq $age ""} return gotoxy 6 8 puts "Enter your address: " -nonewline gotoxy 26 8 set address [input 50 -f black -b yellow] textcolor if {eq $address ""} return # Display our results ... box 4 11 74 5 gotoxy 6 12 puts "Your name is: $name" gotoxy 6 13 puts "Your age is: $age" gotoxy 6 14 puts "Your address is: $address" gotoxy 1 17 Result: +--------------------------------------------------------------------+ | Your name is: Me | | Your age is: 23 | | Your address is: me@23skidoo.com | +--------------------------------------------------------------------+ See also: input, inputwin, msgbox, getkey
format  Top  
string [format format-string|literal ?arg? ...] Standard Tcl format command. The syntax is similar to the C printf command. format prints no output. You must call puts or printf to display the result. Note that format and printf do not automatically issue a newline character Examples: format %x 123456 puts [format "%.10f" [/ $euler $pi]] puts [format "%.0i" [expr 1/20.0*100]]% Results: 1e240 0.8652559794 5 format and printf both include 64-bit number formatting as %I64i and %I64u (case-sensitive). Overflows occur at about 19 digits. Format field numeric specifiers may be passed using a * token Example: (interprets as '%-20.2s') Result: printf "'%-*.*s'\n" 20 2 Hello => 'He ' See also: format string, set, puts, printf, comma
Format String (printf and format)  Top  
The [format] and [printf] commands generate a formatted string in a fashion similar to the ANSI C sprintf function. A format string indicates how to format the result, using % conversion specifiers as in C sprintf, and the additional arguments, if any, provide values to be substituted into the result. The return value from format is a formatted string The following formatting tokens may be used with [format] and [printf] Positional Specifier -------------------- In standard Tcl the first position is an optional positional specifier This is unsupported in Ticol Tcl Optional Flags -------------- The section portion of a format string consists of an optional flag character - Left-justify the converted argument + Print number with a sign, even if positive. space A space should be added to the beginning of the number if the first character is not a sign 0 Specifies that the number should be padded on the left with zeroes instead of spaces Optional Field Width -------------------- The third portion of a conversion specifier is a decimal number giving a minimum field width for this conversion. It is typically used to make columns line up in tabular printouts. If the converted argument contains fewer characters than the minimum field width then it will be padded so that it is as wide as the minimum field width. Padding normally occurs by adding extra spaces on the left of the converted argument, but the 0 and - flags may be used to specify padding with zeroes on the left or with spaces on the right, respectively. If the minimum field width is specified as * rather than a number, then the next argument to the format command determines the minimum field width; it must be an integer value printf "'%*s'\n" 20 Hello => ' Hello' printf "'%-*s'\n" 20 Hello => 'Hello ' Optional Precision Specifier ---------------------------- The fourth portion of a conversion specifier is a precision, which consists of a period followed by a number If the precision is specified with * rather than a number then the next argument to the format command determines the precision; it must be a numeric string. Example: (interpreted as '%-20.2s') printf "'%-*.*s'\n" 20 2 Hello => 'He ' Optional Size Modifier ---------------------- The fifth part of a conversion specifier is a size modifier, which must be ll, h, or l. If it is ll or I64 then the value will be cast to 'wide' format lli 64-bit signed integer llu 64-bit unsigned integer I64i 64-bit signed integer I64u 64-bit unsigned integer Mandatory Conversion Types -------------------------- The sixth part of a format string is a mandatory conversion type specifier d Decimal u Unsigned integer i Signed integer o Octal x or X Hexadecimal (lower, upper case) b Binary integer c Character type (Non-Tcl standard. Tcl converts to Unicode) s String f Floating point/double e or E Scientific notation g or G General format % Literal % symbol (%%) Differences from ANSI printf ---------------------------- p Unsupported Differences from Standard Tcl ----------------------------- %N$ Prefix unsupported See also: format, printf, puts
Ticol Memory Allocation and Garbage-Collection  Top  
Ticol allocates and frees memory for variables automatically. There is no need to perform any 'garbage collection' operations Exceptions would be memory returned by external DLL calls or assigned by [malloc] for an external DLL call. These should be carefully managed Uncontrolled recursion can cause a 'stack overflow' memory error where the application will generate a fatal exception error. Recursive procedures should be carefully-designed to avoid such situations arising See also: set, proc, malloc, free
get_win_error  Top  
integer [get_win_error] Retrieve the last registered Windows error. This should be retrieved as soon as possible before a new event resets the error value to zero Use [win_error] to format the error message See also: win_error
glob  Top  
list [glob ?-file d|f? ?-directory name? ?-nocase? pattern] A very limited implementation of the Tcl [glob] command. The [ls] command offers more flexibility but [glob] is useful for generating lists of files/folders or taking file counts The glob pattern MUST be wrapped in double-quotes if it contains /* [glob] performs a case-sensitive comparison on search results, this can be overridden using -nocase The search pattern may specify only * and ?; character matches [chars], \x and {a,b,...} are unsupported. Only one search pattern is supported The options currently support only -type d (directory) or -type f (file) arguments b,c,l,p,s are unsupported. (df is the default) The -directory name may be either a path name or a filespec The types may be combined using multiple -type arguments A Tcl list is returned with the path separator format will always be in Unix style "/" Examples: puts [glob -type f] # Find all files puts [glob -type fd] # Find all files and dirs puts [glob -type f -type d] # Find all files and dirs puts [glob -type f d*] # Find all files matching d* puts [glob -directory c:\tools -type f a*] # Find files a* in c:\tools puts [glob "/windows/*.dll"] # Dquotes required for /* puts [lcount [glob -nocase "/windows/system32/r*"]] Example: puts [glob -type d "\windows\system32\r*"] # From the CLI Result: /windows/system32/ras /windows/system32/Recovery /windows/system32/restore /windows/system32/ro-RO /windows/system32/RTCOM /windows/system32/ru-RU Example: foreach x [glob -type f "/tools/*"] {puts [file normalize $x] Result: C:/tools/ask.exe C:/tools/md5.exe C:/tools/printf.exe C:/tools/ticol.exe Glob is also a term which refers to wildcard string matching in the following array get array names lsearch string match switch unset vars See also: ls
get_folder  Top  
string [get_folder ?-initdir initdir? ?-flags flags? ?-title string?] Creates a browse dialog with a user-input edit box Uses the Windows shell GUI to browse for a folder, and, if required create a new foldername. If the interface is cancelled then an empty string is returned. Unicode is not supported. No error codes are returned [get_folder] requires an unescaped string for '-initdir'. Use [unescape] Some useful flag values: #define BIF_RETURNONLYFSDIRS 0x00000001 #define BIF_EDITBOX 0x00000010 #define BIF_NEWDIALOGSTYLE 0x00000040 See the Windows API guide for full details of folder browse flags Examples: #define BIF_RETURNONLYFSDIRS 0x00000001 set s [get_folder -flags BIF_RETURNONLYFSDIRS] set s [get-folder -initdir [unescape "c:\\temp"] set s [get-folder -initdir [unescape "c:\\"] -title "Select txt files" See also: get_fileopen, get_filesave
getkey  Top  
string [getkey ?-integer? ?-lower? ?-upper?] Wait for a keypress and return the character. If the -integer argument is given then an integer value representing the key input is returned Upper or lower case can be forced using -lower or -upper Note that PC extended key handling for keys such as F1 will return a sequence of two integer values. For more information, Google PC keyboard handling Use [inkey] to handle keyboard polling loops Example: A useful Yes/No/Quit key-input procedure if {! [defined get_key_input]} { proc get_key_input {} { while {1} { set k [getkey -lower] # Returns a lower-case keypress if {eq $k "y"} { puts $k return "-r" } elseif {eq $k "n"} { puts $k return {} } elseif {eq $k "q"} { puts $k return q } sleep 20 } } } Example: Prompt user to copy text to clipboard textcolor yellow puts "Copy screen to the clipboard ? Y/N" -nonewline set k [getkey -lower] if {eq $k "y"} { clipboard gettext # Grab the screen as text puts "\\nCaptured screen to clipboard" } else { newline } textcolor See also: key input, inkey, gets, input, inputbox
getsid  Top  
integer [getsid <username>] integer [getsid <domain\\username>] Retrieve a Windows SID string for a given username. The domain prefix is optional. If omitted the current workstation/workgroup will be used Example: puts [getsid administrator] puts [getsid snoopy\\administrator] puts [getsid [username]] Result: S-1-5-21-460261754-543217201-1416368962-500 S-1-5-21-460261754-543217201-1416368962-500 S-1-5-21-460261754-123456789-9876543210-500 See also: pid, tid, username
global  Top  
global varName ?varName? ... ?-value value? Link to an existing variable in global scope or, if this does not exist, create a new, simple variable (non struct/array) in global scope with an alias of the same name in the local scope [global] is valid only within procedures This is used within procedures to create a global in the root (::global) namespace and a local (upvar) copy of the same variable. The value argument is optional and if omitted the new variable will be set to empty "" When the local copy of the global variable is updated the global copy will also be updated. The local copy is destroyed on exit of the procedure but the global copy will remain with values set by the procedure Ticol global differs from standard Tcl in supporting a 'value' argument in preference to multiple variables. This is because the need to use global with multiple variables is less likely than the need to set a variable in the var Example: proc create_global {} { # Create a global var with local upvar copy, set it then change it puts "Calling \[global global_var -value 12345\]" # Creates var in global scope global global_var -value 12345 puts "Local: \[bool \[is_set global_var\]\]=\ [bool [is_set global_var]]" puts "Global:\[bool \[is_set ::global_var\]\]=\ [bool [is_set ::global_var]]" puts "Check: \$::global_var=$::global_var" # Update the local copy set global_var 11111 # Then check the global copy puts "Recheck:\$::global_var=$::global_var" } create_global vars gl* Result: Calling [global global_var -value 12345] Local: [bool [is_set global_var]]=true Global:[bool [is_set ::global_var]]=true Check: $::global_var=12345 Recheck:$::global_var=11111 Defined variables matching 'gl' at level 0 ------------------------------------------ integer global_var 11111 See also: global variables, preset globals
Global Variables  Top  
Variables in global scope, including arrays, may be accessed by the global scope prefix '::'. This must appear immediately after any dollar sign, e.g. $::globalVar Global constants, when accessed within procedures, must be either referred to using $:: or declared using upvar which will create a local const instance See: preset globals - for a discussion of pre-set Ticol global variables Nested scope levels exist within procedures. This is referred to as the given 'level'. This value increases from 0 at the top (global) level to higher values as procedure call-frames are added. Variable scope within flow-control structures is the same as at the current procedure level Example: proc getvar {} { set a "I am here" puts "proc local a is: '$a'" puts "proc global a is: '$::a'" puts "proc const b is $::b" } set a "Hello" const b 1234 puts "a in global scope is $::a" getvar Result: a in global scope is Hello proc local a is: 'I am here' proc global a is: 'Hello' proc const b is 1234 Example of declaring a global variable and setting as an array/element set a "" proc set_global_array {} { # Set (cast) global non-array variable as array with one element set ::a(1) "One" } set_global_array # Call the proc puts "\$a(1) set by proc is '$a(1)'" # Print the results Result: $a(1) set by proc is 'One' See also: preset globals, global, set, let
goto_block, goto  Top  
goto_block, goto, gosub goto_block { goto local_label gosub local_label | public_label label {statement} ... } [goto] is implemented purely for the entertainment of the author [goto] statements are valid only within a [goto_block] statement The [goto] paradigm is unpopular and can lead to messy and difficult to debug source code but may be of interest to computer science students A [goto_block] is a simple set of locally-constrained labels and matched, braced script pairs. If a label's script argument consists of only a single-command there is no need for braces. In addition to pairs of labels and scripts, a [goto label] or [gosub label] entry with matching label argument is allowed No freeform Tcl code is allowed in the [goto_block]. All Tcl script code must be declared under a valid label - e.g. goto_block { puts "Hello" # Wrong } goto_block { init {puts "Hello"} # Correct } [goto_block] labels may be any string (including keywords) but they must be unique within the context of a [goto_block] Unless a [goto] or [gosub] command is encountered, a [goto_block] will sequentially evaluate each label's script argument in turn, one after the other. A label's script is executed immediately when encountered with execution starting at the first valid label in the block. Each successive label will be evaluated unless otherwise directed by a [goto] or [gosub] statement A [break] or [return] within a label's script will exit the [goto_block] and ignore any remaining labels and code within that block. e.g. goto_block { # Sequential statements label1 { puts Hello } label2 {} # Empty arguments are permitted label3 { break } # Will cause the goto_block to exit label4 { puts world } # Never executed } Result: Hello Each label entry within a [goto_block] must consist of a label followed by a code block. The code block must be wrapped in braces if there is more than one command present. Labels need not be all-numeric and can be any valid string. Empty label script argument parentheses are allowed Any required block initialisation code for the [goto_block] MUST appear within a dummy label entry and not 'inline'. It is suggested that an 'init' label is used as the first label entry and any setup code executed within the 'init' code-block. Label statements are executed sequentially until a [goto] statement is encountered or after one or more goto statements has been executed [goto_blocks] may be nested. Another [goto_block] may appear within a label's script argument. However, labels are unique and local to the [goto_block] at each level Example: goto_block { label1 { puts "In parent goto_block label1" goto_block { label1 { puts "In child goto_block label1" goto_block { label1 { puts "In grandchild goto_block label1" goto label2 } label2 { puts "In grandchild goto_block label2" } } } label2 { puts "In child goto_block label2" } } } } Result: In parent goto_block label1 In child goto_block label1 In grandchild goto_block label1 In grandchild goto_block label2 In child goto_block label2 [gosub] may be used to call a local label and resume execution at the next statement after that original [gosub] [gosub], when used within a label's argument script, behaves normally and will only call a registered [sub]. This [sub] may be declared within the [goto_block] or externally Example: sub external { puts "In external sub" } goto_block { gosub label_two # Call local block gosub label_one # Call local block label_one { puts "In yr label1" gosub external # Call external [sub] } label_two { puts "In yr label2" } } Results: In yr label2 # [gosub] calls directly In yr label1 # [gosub] calls directly In external sub # Called by non-[goto_block] [gosub] In yr label1 # 'Fall-through' to label1 In external sub # Called by non-[goto_block] [gosub] In yr label2 # 'Fall-through' to label2 A [return] within a label's script argument will behave as follows: * If called from a [gosub] - will return to resume execution * If called from [goto] or sequential execution, will exit the [goto_block] goto_block { gosub label_one label_one { puts "Hello user" return } label_two { puts "I am never executed" } } If a [break] statement is encountered this will cause the [goto_block] to exit. A [goto_block] cannot be exited using return, other than using [return -code break] Example: goto_block { 10 { puts "Going to 30" goto 30 } 20 { puts "Going to end" goto end } 30 { puts "Going to 20" goto 20 } end { puts "Exiting" } } Example: set a 1; goto_block { 10 {;} 11 {;} 12 {puts $a} 12 {incr a; goto 10} } Example: goto_block { # goto_block used to comment out a block of code goto end puts "This statement won't be executed" end } A BASIC-like ON GOTO can be simulated using the following. This behaves the same as C++ switch() goto_block { init { # Initialisation must be within a dummy block set var [rnd 1 3] goto $var # Jump to a [goto] entry } 1 { puts "One" break } 2 { puts "Two" break } 3 { puts "Three" break } } Braces are required for the rvalue of each goto sub-block when more than one command is present and items are separated by whitespace. The following [goto_block] will jump to the selected label similar to ON GOTO and will then execute all subsequent blocks below Example: proc one {} { puts "One" } proc two {} { puts "Two" } proc three {} { puts "Three" } proc four {} { puts "Four" } goto_block { init { # Initialisation is in a dummy block set var [rnd 1 4] goto $var # Jump to a [goto] entry } 1 one 2 two 3 three 4 four } Example emulated loop with conditional exit: option expression off set s 0 goto_block { start { # Loop start ++ s # Increment if {> $s 9} { # Test goto end # Exit } goto start # Loop end } end { textcolor magenta puts "Puts exited OK at label: end" textcolor } } Example: Flip-flops are memory-stable and can be run infinitely set sleep_delay 2000 goto_block { 10 {puts "in 10";sleep $sleep_delay;goto 20} 20 {puts "in 20";sleep $sleep_delay;goto 10} } Used outside of a [goto_block], [goto] will echo its first argument See also: gosub, sub, do, while, for, foreach, flow control
gosub, sub  Top  
The [sub] and [gosub] commands are probably useless and has been implemented for entertainment value only. [proc] should be used instead sub label {code} gosub label gosub proc A [sub] subroutine is a procedure ([proc]) which takes no arguments and returns no value. [return] commands are ignored and return values are discarded. Any arguments given to a [gosub] command are ignored. The [gosub] command is 'syntactic-sugar' and is an optional part of the Ticol language [gosub] may be combined with [goto] within a [goto_block] For use of [gosub] within a [goto_block], see goto_block [sub] labels are case-sensitive. [gosub] may also call any proc but will pass no arguments The commands [static], [upvar], [uplevel] etc. may be used within a subroutine exactly as in [proc]. Local variables in [sub] work in exactly the same way as in [proc] [gosub] when used within a [goto_block] two different behaviours. In a [goto_block] root is will [gosub] a block label, within a script argument it will [gosub] a defined subroutine. See [goto_block] Example: sub label1 { static counter ++ counter puts "In label1. Counter is $counter" } gosub label1 gosub label1 Result: In label1. Counter is 1 In label1. Counter is 2 Example: sub label1 { static counter1 ++ counter1 puts "I am label 1. counter1 is $counter1" return # return is optional and values discarded } sub label2 { static counter2 ++ counter2 puts "I am label 2. counter2 is $counter2" gosub label1 # Call another sub. Scope prefix required return # return is optional and values discarded } gosub label1 gosub label2 gosub label1 vars Result: I am label 1. counter1 is 1 I am label 2. counter2 is 1 I am label 1. counter1 is 2 I am label 1. counter1 is 3 Defined variables at level 0 -------------------------------- integer label2::counter 1 integer label1::counter 3 CAUTION: [gosub] subroutines may not call each other or call themselves recursively or a stack-overflow error will result. Example: Stack overflow conditions can be triggered by the following abuses... sub label1 { gosub label1 # Recursion will cause a stack-overflow } sub label2 { gosub label3 # Mutual calls will cause a stack-overflow } sub label3 { gosub label2 } gosub label1 gosub label2 The [gosub] command is optional. A defined subroutine may be called directly by referencing its name Example: sub label1 { puts "In label1" } label1 # Call the subroutine without [gosub] Result: In label1 See also: goto, goto_block, proc, static, upvar, uplevel
hasp - Ticol Hasp HL Plugin  Top  
A HASP HL plugin to query local and remote network HASP licence servers To load, use: lib ticol_hasp ?-verbose? ?-nocomplain? Prerequisite: The HASP HL driver must be installed and running on the target host Command and Syntax: list-of-dongle-ids [hasp keys hostname|ip ?-port value?] list-of-fids [hasp modules hostname|ip keyid ?-port value?] date-string [hasp expiry hostnam|ipe keyid fid ?-port value?] string [hasp product hostname|ip keyid fid ?-port value?] string [hasp type hostname|ip keyid ?-port value?] list [hasp data hostname|ip ?-port value?] list [hasp keydata hostname|ip ?-port value?] Note that the HASP HL series driver must be installed to run this plugin Note also that 'fid' is Feature ID code, 'keyid' must be a single key ID, not a list of key IDs Non netwoked (HASP HL Time) can only be discovered on the local machine [hasp keys] Returns a list of discovered HASP key IDs [hasp keydata] Returns a list of basic information on a unique HASP key basis for all known keys. 5 fields are returned per key Key#, IP, Hostname, Type, Module FID, Module Expiry [hasp modules] Returns a list of known module FIDs by key ID [hasp expiry] Returns the expiry of a given module [hasp product] Returns the product name for a given FID [hasp type] Returns they key type of a given HASP key ID [hasp data] Returns all of the known HASP key data from a host Example: # List basic key information (per key) set i 1 foreach x [hasp keydata localhost] { puts "$i '[lindex $x 0]' '[lindex $x 1]' '[lindex $x 2]'" ++ i } Example: # Do not use puts [hasp modules localhost [hasp keys localhost]] Examples: lib ticol_hasp.dll # Show all connected+known keys on server foo puts [hasp keys foo] # List known module FIDs on the first known key lib ticol_hasp.dll puts [hasp modules localhost [lindex [hasp keys localhost] 0]] Useful references ----------------- https://sentinel.gemalto.com/software-monetization/sentinel-hasp-hl/ See also: plugins, ticol_rlm
Include files  Top  
eval filename There is no #include macro for Ticol. Includes are processed in real-time by using the [eval] command. As the 'included' file will undergo Macro Preprocessing it should be arranged to include the file only once near the start of any script. Avoid using [eval filename] inside loops Example: eval defs.tcl puts $LONG_MAX You can use [eval] to include data to set arrays etc. which has been defined in a separate file Example: # File. include_data.tcl return { 1 {foo} 2 {bar} 3 {baz} 4 {quux} } # Main file which will include the data file puts "Including include_data.tcl" array set data [eval include_data.tcl] for {set i 1} {<= $i [array size data]} {++ i} { puts "$data($i)" } Results: foo bar baz quux See also: Macro, eval
index  Top  
string [index string N] Rapid indexing of strings to return a single character. [index] uses base 0 indexing values where 0 represents the first character of a string. Out of bounds index values will return the null string {} Example: puts -[index $qbf 0]- puts -[index $qbf 1]- puts -[index $qbf 2]- puts -[index $qbf 42]- Result -T- -h- -e- -g- See also: strstr, instr, string
Tcl Programming Idioms  Top  
Idioms are code fragments with a common theme and frequent usage "A programming idiom expresses a recurring construct in one or more programming languages. Developers recognize programming idioms by associating and giving meaning to one or more code fragments" (Wikipedia) Idioms are often implemented 'longhand' and inefficiently using a number of separate commands (words). Such idioms may be compressed into a single command. In the case of Ticol, which is implemented more efficiently as a distinct command In essence, they represent one or more ways of doing a common task Some non-standard idiomatic commands have been included with Ticol. These can be written by combining several other commands but these inbuilt idioms improve speed and efficiency by compressing into a single command Removing a matching sequence of characters from the start of a string See [chomp], [html chomp_tag] Extract complete HTML tags from a text string See [html chomp_tag] Align one string into another See [lset], [cset], [rset] Wrap text into a fixed width boundary See [wrap] Convert JSON data to a Tcl list See [json_to_list] Efficiently concatenate strings See [concat], [append], [store] Match one of a series of characters to a location in a string See:[instr], [strstr] Create a repeated list/string sequence See [string repeat], [range] Return the last character of a string See [lastchar], [mids] Split a string along fixed width boundaries See [slice] Return a single character within a string See [index], [mids] Return part of a string See [mids] Return all of a string after a given index position See [mids] Format a number as a comma-separated sequence See [comma] Replace part of a string with a sequence of characters See [setat], [mid] Declare and initialise See [static], [let], [dim] Show Disk Free Space (UNC or local) See [diskfree] References: https://en.wikipedia.org/wiki/Idiom
if..elseif..else (Flow Control)  Top  
if {condition} then {statement} else {statement} The if statement controls conditional branching The body of an if statement is executed if the value of the expression is evaluated as nonzero. The number of elseif statements is unlimited but execution will slow down as more cases are added The opening brace for the statement following if or else MUST be on the same line as the if or else verb. The standard Tcl keyword "then" is not supported in order to speed-up execution It is recommended that the 'then' argument is not used 'condition' may be an expression, numeric literal or eval return For and/or compound syntax see and, or if {condition} { statements... } if {condition} { statements... } elseif { condition } { statements... } else { statements... } Compact if..elseif Form ----------------------- Line-continuation characters may be used to produce a compact elseif ladder Note that the \ backslash is not required on the last elseif line set failed $false if {eqi $tag area} {set failed $true}\ elseif {eqi $tag base} {set failed $true}\ elseif {eqi $tag br} {set failed $true}\ elseif {eqi $tag col} {set failed $true} # No backslash on last clause if {$failed} { ... } Subcommands ----------- The following additional commands are available with [if-elseif-else] return # Will exit the script when used in root-level [if] break # Will be passed back to any enclosing structure stop # Halt operation, return to the CLI if loaded exit # Exit the script and return to Windows goto # Where used with an enclosing [goto_block] Expression v's Eval ------------------- Flow control structures use the settings of 'option expression' to decide whether to test statements using [expr] or [eval]. When using expression on bear in mind that the argument must be a valid math expression and NOT a command If 'option expression' is ON then you MUST use valid math expressions. Math expressions must use direct or implied logical tests on command results. Command calls require square brackets with expression ON in order to return a boolean value to test Caution: Don't do this ... option expression on if {[$argc > 1]} { ... # [] transforms into a command call As Ticol will try to dereference argc first and then try to run a command with that name. Use this form... option expression on if {$argc > 1} { ... # A braced expression is required here Example Expression: option expression on if {is_set w} {puts yes} else {puts no} # Not a math expression if {[is_set w]!=0} {puts yes} else {puts no} # Correct math expression if {[is_set w]} {puts yes} else {puts no} # Correct math expression Example Eval: option expression on if {[is_set w]!=0} {puts yes} else {puts no} # Wrong for use with eval if {[is_set w]} {puts yes} else {puts no} # OK for eval if {is_set w} {puts yes} else {puts no} # OK for eval, [] optional More complex, combined conditional expressions may be formed using [expr] Example: option expression off if {expr [ne $var_1 ""] && [ne $var_2 ""]} { ... option expression on if {[ne $var_1 ""] && [ne $var_2 ""]} { ... If Tests for Non-Zero Results ----------------------------- [if] tests for a non-zero expression or command result so expressions may sometimes return unusual or unexpected results option expression on set i 9 if {$i - 10} {puts yes} else {puts no} if {$i - 9} {puts yes} else {puts no} if {$i - 8} {puts yes} else {puts no} Results yes no yes See also: else, elseif, and, or, while, foreach, switch, flow control
info  Top  
* Note that adapter and TCP/IP information is unsupported in Windows NT info adapter_count # Return the count of known network adapters info adapter_id n # Return adapter GUID info adapter_name n # Return the adapter name info adapter_type n # Return the adapter type value info args procname # Return the argument list of a procedure # Cannot be blocked by TCX encryption info body procname # Return the script body of a procedure # Cannot be blocked by TCX encryption info cmdcount # Return a count of total command calls info commands ?pattern? # List available commands info domain ?n? # Show the DNS domain name bound to adapter info dhcp_enabled n # Return boolean 1 if DHCP is enabled else 0 info dhcp_end n # Show the DHCP lease expiry date info dhcp_server n # Show any currently configured DHCP server info dhcp_start n # Show the DHCP lease start date info disks # Return a Tcl list containing active disks info disktype x: # Show the disk type for a given drive/path # 0 Unknown type # 1 No root directory/Unavailable/Error # 2 Removable # 3 Fixed # 4 Remote # 5 CDROM/DVD # 6 RAMDISK info encrypted # Returns 1 if script was obfuscated else 0 info executablename # Returns the command line EXE filename info exists varname # Check if a variable exists, returns 1 or 0 info fmac_address n # Return a formatted adapter MAC address info frame ?number? # Show the frame number info functions # Return a list of functions info gateway n # Return the configured IP gateway address info globals ?filter? # Returns a Tcl list of variables at level 0 info guid # Return a new, unique GUID string info hostname # Return the configured PC host name info ip_address n # Return the IP address for an adapter info is_elevated # Show whether running elevated (Win7+) info is_networked # Show whether networked or not info level ?n? # Show the call frame level (top level is 0) info lib # The library path name info locals ?filter? # Tcl list of variables at the current level info mac_address n # The adapter's MAC address info memtotal # The total physical memory in bytes info memavail # The available physical memory in bytes info memtotalpage # The total swapfile memory in bytes info memavailpage # The available swapfile memory in bytes info memtotalvirtual # The total virtual memory in bytes info memavailvirtual # The available virtual memory in bytes info mempercentfree # Show the % free to 2 decimal places info monitorcount # Show the number of connected monitors info nameofexecutable # Ticol's EXE name and path info netmask n # The adapter's IP subnet mask info primary_dns n # The adapter's primary DNS server info primary_wins n # The adapter's primary WINS server info procname # The currently active proc else "" info procs ?filter? # A list of user-defined procedures info script # The name of the active script (if any) info secondary_dns n # The adapter's secondary DNS server info secondary_wins n # The adapter's secondary WINS server info tclversion # The Ticol version. Same as $::tcl_version info username # Return the currently logged-on user # List variables. See also: info vars info vars ?pattern? ?-const? ?-nocase? info winver ?-list? # Windows version information (as a list) # See: info winver Where a network adapter is given this is a base 0 value Multiple network information calls are necessarily slow as an API call has to be repeatedly made to retrieve each attribute. # Example Result Comment # ---------------------------------------------------------------------------- puts [info args square] # x List procedure arguments puts [info body square] # * $x $x List procedure body puts [bool [info exists pi]] # true Check if var pi exists puts [info exists commands c] # call calldll... List all starting with 'c' puts [info exeutablename] # c:\tcl\ticol.exe Shows the EXE name and path puts [info ip_address 0] # 0.0.0.0 Show IP for adapter #1 puts [info ip_address 2] # 192.168.1.23 Show IP for adapter #3 puts [info hostname] # WORKSTATION23 Show the host name puts [info tclversion] # 1.06 Ticol-specific version no puts [info vars pi -const] # pi 3.141592... List vars starting with pi puts [info procs f*] # foo List procs starting with f puts [info script] # test.tcl Must be loaded puts [info level -1] # foo 10 Where called from proc foo Example: option expression on for {set i 0} {$i < [info adapter_count]} {incr i} { puts "Adapter $i: [info ip_address $i]" } Example: # This script file extension set filetype [file extension [info script]] puts "File ext is: $filetype" See also: commands, dump, set, vars
info args  Top  
string [info args procname] Returns the argument parameter of a defined proc. The proc must exist Example: proc foo {x {y NULL}} { puts "In proc [info procname] [info args [info procname]]" } foo Result: In proc foo x {y NULL} See: info
info cmdcount  Top  
integer [info cmdcount] Return a count of total Ticol command calls as an integer Example: proc factorial {val} { puts "Current level: [info level] - val: $val" set lvl [info level] if {$lvl == $val} { return $val } return [expr {($val-$lvl) * [factorial $val]}] } puts "This is how many commands have been executed: [info cmdcount]" puts "Now this is how many commands have been executed: [info cmdcount]" puts "\nThis interpreter is revision level: [info tclversion]" puts "The process id for this program is [pid]" set count1 [info cmdcount] set fact [factorial 3] set count2 [info cmdcount] puts "The factorial of 3 is $fact" puts "Before calling the factorial proc, $count1 commands executed" puts "After calling the factorial proc, $count2 commands executed" puts "It took [expr $count2-$count1] commands to calculate a factorial" Results: This is how many commands have been executed: 133 Now this is how many commands have been executed: 135 This interpreter is revision level: 1.14 The process id for this program is 4352 Current level: 1 - val: 3 Current level: 2 - val: 3 Current level: 3 - val: 3 The factorial of 3 is 18,3,3 Before calling the factorial proc, 142 commands executed After calling the factorial proc, 176 commands executed It took 34 commands to calculate a factorial See also: info
info exists  Top  
bool [info exists variableName|arrayName] The argument for variable or array name must be a name-literal. i.e. it cannot be prefixed with a dollar sign as this will cause automatic dereference to the variable value. Dollar-subscript values may be required for arrays. Note that the array syntax prohibits whitespace between the variable name and the open parenthesis: Correct: "$varname($index)" Incorrect: "$varname ($index)" (looks for non-array variable $varname) Use [array exists arrayname] to test for the presence of an array by name info exists argv0 info exists argv(0) set i 0 info exists argv($i) info exists env(TEMP) array exists argv array exists env See also: info, array exists
info level  Top  
info level ?number? Displays information about the calling frame at a given level. Level 1 in a proc will be the current level, level 0 the calling frame for that proc. If 'number' is not specified, info level returns a number indicating the current calling level, i.e. the level from which info level was called with 0 being the top level, and each subsequent level incremented by 1 If 'number' is specified, info levels returns a Tcl list containing words of the command for the level indicated by number. A number value greater than 0 indicates the level identified by that number. 0 indicates the current level, -1 indicates one level prior to the current level, -2 indicates the level prior to that one etc. Example: proc foo {bar {baz NULL}} { puts "info level 0 is \[[info level 0]\]" } foo foo abc foo abc def Results: info level 0 is [foo] info level 0 is [foo abc] info level 0 is [foo abc def] See: http://wiki.tcl.tk/1720 See also: info
info vars  Top  
list [info vars ?pattern? ?-const? ?-nocase?] Return a Tcl list of matching variables. A glob pattern may be supplied and the search will be case-sensitive unless the -nocase argument is included. A list of constants may be returned by using the -const argument set foo 1 const Example 1 puts [info vars] # All variables regardless of case puts [info vars e*] # All variables precisely matching e* puts [info vars f??] # All variables precisely matching e* puts [info vars F?? -nocase] # All variables matching f?? or F?? puts [info vars N* -nocase] # All variables matching n* or N* puts [info vars -const] # All constants puts [info vars e* -const] # All constants matching e* puts [info vars e* -const -nocase] # All constants matching e* or E* Results: argc argv argv0 env eof errorCode errorInfo errorLine errorMsg euler exe _name false logo NAN pi qbf tcl_cli tcl_config tcl_date tcl_precision tc l_threaded tcl_version true win64 env eof errorCode errorInfo errorLine errorMsg euler exe_name foo foo NAN argc argv argv0 env eof euler exe_name false logo NAN pi qbf tcl_cli tcl _config tcl_date tcl_precision tcl_threaded tcl_version true win64 env eof euler exe_name env eof euler Example exe_name The [vars] command gives a diagnostic snapshot of current variables and an abridged view of their type and contents. See: vars See also: vars, info
info winver  Top  
info winver ?-list? ?-vernum? ?-truever? Show information about the current Windows version Argument -list will return full Windows information in Tcl list format as {Version name} major.minor.build {Service pack} bitness Argument -vernum will return the full version number as a double value Argument -truever will show the true version number on later Windows builds Example: puts [info winver -list] Result: {Windows XP} 5.01.2600 {Service Pack 3} 32 Example: puts [info winver] Result: Windows XP [Version 5.01.2600] (Service Pack 3) 32 bit Example: # Show whether Windows is 64 or 32 bit lindex [info winver -list] 3 Result: 64 Example: puts [info winver -vernum] Result 5.1 See also: info
input  Top  
string [input ?length? ?-f forecolour? ?-b backcolour? ?-password? ?-crlf?] Input a fixed length string from the console The default input length is 30 characters Optionally, the input area foreground and background colour can be set and input characters can be masked with '*' if the -password argument is used. Backspace editing/deleting is supported. Insert mode is not supported. The input length cannot be exceeded or a bell alert will sound Input is confirmed by pressing the RETURN, ENTER or TAB keys If ESC is pressed then any input text is discarded and input exits Example: # Input 20 characters using white on blue text puts "Enter 20 chars: " set s [input 20 -f white -b blue] newline puts "You input '$s'" Example: # Input a password, hiding the input puts "Enter password of 20 chars: " set s [input 20 -password] newline puts "You input '$s'" See also: inkey, getkey, gets, input, input_csv, gotoxy, box, inputbox
inkey  Top  
integer [inkey] Check if there is a key input event pending and retrieve the keypress code If a key-event is pending the key values is returned, otherwise 0 is returned Use [getkey] to wait for keyboard input Example: puts "Press ESC to halt" while {1} { puts "Looping" sleep 1000 if {== [inkey] 27} { # ESC is 27 stop } } See also: key input, getkey, gets, input, input_csv, gotoxy, box
input_csv  Top  
input-csv filename ?varname | -? ?items-max? ?-crlf? ?-array name? ?-r? Read lines from a standard-format CSV file and translate to a properly- formatted Tcl list. The CSV input-file may be contain double-quote wrapped strings but all fields must be comma separated If no variable name is given then [input_csv] returns the list. If a variable name is passed then the variable is assigned (even if this is an empty list) and a count of the number of list elements is returned The new variable name is optional but if lines-max is specified and varname is omitted then supply a hyphen (-) character instead The optional '-crlf' argument will retain newline pairs in the resulting output 'items-max' is the maximum number of array items to read from the file CSV read and conversion may become slow for files over about 5Mb and excessively so for files above 10 or 20Mb+. Consider sequential. line-based input into smaller Tcl lists instead Each line (row) of the file can be read to a Tcl array using the -array argument with a non-existent variable name. Subscript->value assignment can be reversed or 'inverted' using the -r argument No unicode/wide character conversion is performed Example: CSV file: "Hello world",1234,"ABC",5.678 "The quick brown fox",0123,"CDE",23.23 puts [input_csv csvfile.csv - 4] Result: {Hello world} 1234 Tcl 5.678 See also: json_to_list, file read
Getting User Input  Top  
[input] offers console line-input with text input length limits, backspace editing and text input area colourisation as well as password character hiding [inkey] provides polled single key input to enable you to build your own keyboard-interaction routines [gets stdin] is a stream-based method of retrieving user input from stdin It offers limited line-editing facilities and no option to fix the length of the user-input or prevent line-wrap. It is not recommended for general user interaction. Use [input] instead Example: puts "Enter 20 chars: " set s [input 20 -f white -b blue] newline puts "You input '$s'" Example: puts -nonewline "Throw a die. What value did you get? " flush stdout set top [gets stdin] switch -- $top { 1 {set end "st"} 2 {set end "nd"} 3 {set end "rd"} default {set end "th"} } puts "You selected the $top$end face" See also: gets, flush, switch
inttooct, octtoint  Top  
string [inttooct integer-value] integer [octtoint octal-value ?-unsigned?] Converts to and from from decimal integer and octal format Conversion from octal to decimal is automatic in all routines Octal format is defined by an "0o" prefix. e.g. "0o12" Values given to [inttooct] may be decimal integers, hexadecimal, octal or binary values Tcl v9 octal number identifiers are implemented, which require 0oNN format CAUTION ------- The Macro PreProcessor (MPP) will automatically convert octal values in the form 0oNN into decimal. Be cautious when passing unquoted octal values with "0o" prefix to [octtoint] Examples: puts [inttooct [expr "0o123+1"]] puts [inttooct 0b1101001] puts [inttooct 0x68] puts [octtoint 0o124] # Unquoted octal will be converted by MPP puts [octtoint "0o124"] # Quoted octal will be retained Results: 0o124 0o151 0o150 0 84 See: http://wiki.tcl.tk/498 See also: intotohex, inttobin, tohex, fromhex, cast
instr, rinstr, strstr, strstrr  Top  
integer [instr haystack needle ?startpos? ?-nocase? ?-var?] integer [instr haystack needle ?startpos? ?-nocase? ?-var?] integer [strstr haystack needle ?startpos? ?-nocase? ?-var?] integer [strstrr haystack needle ?startpos? ?-nocase? ?-var?] VB and C++ - like string search commands. Use either the VB or C++ alias [instr] and [strstr] search forward from the start of a string [rinstr] and [strstrr] search backward from the end of the string Where 'haystack' may be a variable or literal string and where 'needle' may also be a variable or literal string The 'startpos' argument is an index base 1 value indicating which character to start the comparison from. e.g. 1 is the 1st character in the string Returns a 'base 1' index value of 'needle' into 'haystack' If 'needle' is not found in 'haystack' then 0 will be returned. If 'needle' is a null string then 0 is returned The result may be treated as a boolean - not found being 0 and found non-zero Example: puts [instr $qbf "fox"] puts [instr $qbf "QUICK" -nocase] if {[instr $qbf "lazy"]} { puts "True" } Results: 17 5 True Example: puts [strstr "quick brown fox" "brown"] puts [strstr "quick brown fox" "BROWN" -nocase] Result: 7 7 Example: option expression on if {instr $qbf fox} { puts "I found the fox!" } Result: I found the fox! See also: lset, rset, mid, string
inputbox  Top  
inputbox ?prompt? ?title? ?default? ?-password? ?-x X? ?-y Y?\ ?-w W? ?-h H? Creates a windows which can receive user input, optionally with input masked by a password-masking character. Inputs are confirmed by ENTER/OK click or cancelled using ESC/CANCEL click Options ------- -password Mask input characters with an asterisk (*) -x X Locate at cursor X -x Y Locate at cursor Y -w W Make dialog W wide -h H Make dialog H high If -x and -y are omitted the dialogue will centre on the screen Examples: puts [inputbox "Enter your name:"] puts [inputbox "Enter password:" "Password" -password] puts -[inputbox "Enter your name" "info" -w 500 -password]- puts [inputbox "Enter your name:" -x 200 -y 300 -w 500] See also: msgbox, get_filesave, get_filesave, get_folder, input, gets
ip_to_long, long_to_ip  Top  
integer [ip_to_long value] string [long_to_ip value] Convert an IPV4 dotted-quad address to an unsigned long value or convert a long value to an IPV4 dotted-quad address. The address can be partial, in which case it will be evaluated from left to right (e.g. "192.168.0") Example: puts [inttohex [ip_to_long 255.255.255.255]] Result: 0xffffffff Example: # Partial address puts [inttohex [ip_to_long 192.168.0]] puts [ip_to_long 192.168.0] Result: 0xc0a80000 3232235520 Example: puts [long_to_ip 0xffffffff] Result: 255.255.255.255 See also: info
item (array, stack or struct)  Top  
string [array item arrayName subScript ?default? ?-nocase?] string [stack item stackName index ?default?] string [struct item structName fieldname ?default?] The item argument returns a value if it exists. If the referenced object does not exist then either "" or a default value is returned See also: array, stack, struct
tohex, fromhex  Top  
string [tohex string] string [fromhex string] Converts a string to and from a hex-encoded version Examples: tohex "hello" fromhex 68656C6C6F puts [fromhex [tohex "Hello world"]] Result: 68656C6C6F hello Hello world See also: inttohex, inttooct, cast
funct  Top  
number [funct function-name arg ?arg? ...] Call an [expr] function directly and separate from the [expr] command [funct] is more efficient than calling expr where access to a single function is required. Complex expressions are not supported within the arguments unless returned by [expr] Examples: puts [funct log10 2] puts [funct round $pi 2] puts [funct rnd 1 10] puts [* [funct atan 1] 4] Result: 0.301029995663981 3.140000 6 3.141592653589792 See: 'functions' and 'expression functions' for the full list of functions exported from [expr] See also: functions, expr, eval, function arity
functions  Top  
list [functions ?glob-pattern?] Return a Tcl list of math functions defined for use with the expr command The search may be constrained by a glob search value. The list may be iterated with [foreach]. The search case is not relevant as all functions are pre-defined internally as lower-case. See: 'function arity' and 'expression functions' for more details about particular functions and their arguments Example: # Full list of all [expr] and [funct] functions in this version puts [functions] Result: abs acos asin atan bool ceil decr div cos cosh degrees double exp fib fix floor fmod fraction hypot incr int integral log log10 max min mul pow rand rnd round sgn sin sinh sqr sqrt srand tan tanh wide Example: # List all functions starting with the letter 'm' puts [functions m*] Result: max min mul Use: option echo on to display directly to the console See also: expression, procs, funct
BEDMAS/BOMDAS (Math Operator Precedence)  Top  
Ticol implements BEDMAS to automatically prioritise math expressions: BEDMAS: Brackets, Exponent, Division, Multiplication, Addition, Subtraction This is also known by other acronyms such as PEDMAS, BOMDAS etc. The order of operations used throughout mathematics, science, technology and many computer programming languages is expressed as: Exponents and roots Multiplication and division (of equal preference, thus left-to-right) Addition and subtraction (of equal preference, thus left-to-right) Where an operator has equal precedence, (e.g. + and -) then a left to right evaluation is performed This aspect of mathematics appears to date from well before the 17th century and rrequent internet postings suggest that this comes as a surprise to many See: http://en.wikipedia.org/wiki/Order_of_operations See also: math operators, math expressions, expression functions
Math Expressions  Top  
Tcl does not natively understand math, although individual commands are able to process math commands and expressions The built-in [expr] command can handle complex expressions and applies standard BEDMAS rules by reprioritising expressions before evaluation. During the checking phase any non-decimal consts such as 0xFF or 0o777 are automatically converted to their decimal equivalents. Multiplication and division are given priority over addition and subtraction Main flow-control commands may take either an [expr] or [eval] argument which is controlled by the 'option expression' setting. With 'option expression on' commands such as [if] and [while] will take an [expr] argument. With 'option expression off' you will need to pass eval results of individual Tcl commands e.g. option expression on if {30 / 10 == 3} { ... option expression on if {== [/ 30 10]} { ... Exponentiation is supported via the operator '**' and pow() expression function Example: puts [expr 2**8] puts [expr pow(2,8)] Results: 256 256.000000000000000 The contents of pre-bracketed expressions and function brackets are also evaluated for correct ordering and precedence. Value interpretation follows Tcl rules. Integers are subjected to integer division. If you wish float division then specify a decimal point. e.g. - 22/7 will return 3, 22/7.0 will return 3.142857142857143 For a full list of supported math functions see Expression Functions Note that commas ',' are undefined within math expressions other than as function parameter separators and their inclusion elsewhere may cause unpredictable results. You may also apply your own expression parentheses. Example: # Call [expr] then external BAT file which calls cscript->eval # abs(1+11*2-1/7.0)/sqrt(2/1.6) is reinterpreted as: # abs(1+(11*2)-(1/7.0))/sqrt(2/1.6) puts [expr abs(1+11*2-1/7.0)/sqrt(2/1.6)] 20.444050079998078 puts [eval.bat abs(1+11*2-1/7.0)/sqr(2/1.6)] 20.44405007999810 Note: The big math plugin module can be used to extend the number range See also: math operators, BEDMAS, expression functions
Math Operators  Top  
The following math operators are supported. Operations are treated as discrete integer or float unless mixed types are encountered, in which case float is used. Take care with division; if you want a float result then one of the operands must be a float value or your result will be truncated to an integer value: e.g. Use: expr "22/7.0" not expr "22/7" + Addition - Subtraction * Multiplication / Division % Modular division ** Power. Returns x raised to the power of y (See: pow) Integer overflow is fatal Double overflow returns 1.#INF00000000000 Combination Operators += Combination add and assign -= Combination sub and assign *= Combination mul and assign /= Combination div and assign Integer Only: ^ Bitwise xor << Bitwise shift left (64-bit) >> Bitwise shift right (64-bit) | Bitwise or || Logical or & Bitwise and && Logical and The above may be applied as combined operator= symbols, e.g. ^=, &= Relational Operators: == Equivalence != Inequality > Greater than >= Greater than or equal to < Less than <= Less than or equal to mod Modular division is_mod Safe modular division test () Precedence bracketing Division by zero will return an error as either: Integer division by zero (10 / 0) Float division by zero (10 / 0) When used as a command, the math operators such as [add] [sub] etc. can be used with a variable name as the following method of shortcut assignment... set a 1 add a [expr 3*3] add a [* 3 3] Result: 10 19 Note: The big math plugin module can be used to extend the number range See also: big math, incr, decr, ++, --, is_div, shortcut operators, BEDMAS, math expressions, is_mod
Shortcut Math Operators  Top  
Syntax: <operator> <variable> <value> Operator Mnemonic Domain ------------------------------------------ += Add Integer, float -= Sub Integer, float *= Mul Integer, float /= Div Integer, float &= BitAnd Integer |= BitOr Integer ^= BitXor Integer The shortcut math operators help simplify and speed up math expressions. For example, the longhand: set a [* a 3] may be condensed to: *= a 3 Examples: Set a 1 # 1 += a 10 # 11 -= a 2 # 9 *= a 3 # 27 /= a 9 # 3 |= a 4 # 7 &= a 6 # 6 ^= a 2 # 4 ^= a 2 # 6 See also: math operators
<< >> Bit shift (64-bit)  Top  
integer [<< value bits ?bit-width?] # Bitwise shift left integer [>> value bits ?bit-width?] # Bitwise shift right Either left or right-shifts a value by N bits. This is a valid operation for integers only. Negative shift values will raise a catch exception The expression forms of << and >> do not accept bit-width arguments. If you need to specify a bit width then insert the command in either expression or eval pass as [<< value shift bits] [>> value shift bits] Examples: puts [expr [<< [expr 20+3] [expr 2^4] 32] - 472] puts [expr 1*[<< 1 1]*3/4.0*5] Result: 1000 7.5 Note that all Ticol integers are 64-bit and by default these bit operations work on 64-bit integers. This can be modified by adding an output bit-width argument of either 8,16 or 32. Any other values will evaluate as 64-bit Shift does not wrap or suffer from an underlying 32-bit bias for other bit-widths. All shifts equal-to or in excess of the specified bit width will return 0 Wrapping does not occur (32-bit wrapping is blocked) Shift [<<] and [>>] fills vacated bits with 0. All values are unsigned. Sign-bits do not therefore, cause 'backfill' with [>>] Examples: puts [inttohex [<< 0xff 32]] puts [inttohex [<< 0xff 63]] puts [inttohex [<< 0xff 64]] loop i 0 40 8 { printf "\[inttohex \[<< 0xff %2i 32\]\]='%20s'\r\n" $i\ [inttohex [<< 0xff $i 32]] } Result: 0xff00000000 0x8000000000000000 0x0 Examples: puts [inttohex [<< 0xff 0 32]]=' 0xff' puts [inttohex [<< 0xff 8 32]]=' 0xff00' puts [inttohex [<< 0xff 16 32]]=' 0xff0000' puts [inttohex [<< 0xff 24 32]]=' 0xff000000' puts [inttohex [<< 0xff 32 32]]=' 0x0' See also: math operators, functions
Expression Functions  Top  
The following standard C/C++ compatible functions are available within Tcl expressions using the [expr] command. See: function arity for a more detailed list of arguments abs(x) acos(x) asin(x) atan(x) bool(x) ceil(x) decr(x) div(x,y) cos(x) cosh(x) degrees(x) double(x) exp(x) fib(x) fix(x) floor(x) fmod(x,y) fraction(x) hypot(x,y) incr(x) int(x) integral(x) log(x) log10(x) max(x,y) min(x,y) mul(x,y) pow(x,y) rand() rnd(x,y) round(x,y) sgn(x) sin(x) sinh(x) sqr(x) sqrt(x) srand() tan(x) tanh(x) wide(x) ?x:y Available functions may be listed using the 'functions' command See: function arity for more details about functionality The functional int differs from the int conversion command. int(x) will round to the lowest integer whereas [int x] will simply cast and convert Int returns the first -ve integer less than or equal to value, whereas Fix returns the first -ve integer greater than or equal to value. Functions may be nested within expressions passed to the 'expr' command and may also be called using the [funct] command The 'sgn' function returns: Greater than zero 1 Equal to zero 0 Less than zero -1 Example: expr "int(22/7.0)+int(5.2)" Result: 8 Example: expr "round(exp(log(10)),0)" Result: 10 Example: expr ([rnd 0 1]?yes:no) Result: Randomly yes or no Example: puts [funct max 2 10] Result: 10 See also: function arity, Math Expressions, arity, expr, eval, math, funct, functions, funct
getcwd, pwd  Top  
getcwd pwd Returns the current working directory [getcwd] will return the path as a backslash-escaped string for Tcl processing [pwd] will print out the current working directory for display purposes Example: pwd getcwd Results: C:\windows\system32 C:\\windows\\system32 See also: mkdir, mkdirs, file, dir
get_fileopen, get_filesave  Top  
get_fileopen filter title initdir ?flags? get_filesave filter title initdir ?flags? ?defaultname? Launches a Windows file select (open) dialogue or a file select (save) dialogue For get_filesave a default filename may be specified after the flag value. Unwanted flag values should be specified as 0 Example: set f [get_filesave *.txt "Save Txt File" "d:\temp"] set f [get_filesave *.txt "Open Txt File" "d:\temp" 0 fred.txt] See also: msgbox, inputbox, get_folder
getenv  Top  
string [getenv] Return an environment variable from Windows Example: puts [getenv ProgramFiles] Result: C:\Program Files (x86) See also: setenv
gets  Top  
string [gets ?stdin|filenum? ?var? ?count?] string [gets] string [gets length] string [gets var] string [gets var length] string [gets stdin var] string [gets stdin length] string [gets stdin var length] Read data from an open file-stream. This may either have been opened by the open command or the stdin read stream may be used. Optionally, a variable may be specified to receive the data. This need not be declared in advance. The default file-stream is 'stdin'. A numeric value is assumed to represent a length value Additionally an optional number of bytes to read from the stream may be specified If 'count' is specified then CTRL+Z (^Z or EOF) terminates input before the required number of characters has been read. If count is not specified then input terminates when ENTER is met When using [gets] to read from the stdin console it supports up/down cursor history, home/end and full inset-mode line editing Example: puts "Enter your name: " -nonewline set a [gets] newline Example: puts "Enter your name: " -nonewline gets a newline Example: puts "Enter your name up to 20 characters: " -nonewline gets a 20 newline Example: puts "Enter your name up to 20 characters: " -nonewline gets stdin a 20 newline Example: set fp [open "input.txt" r] gets $fp a 100 # Read 100 chars close $fp See also: inputbox, file, open, close
gotoxy  Top  
gotoxy x y Locate the screen cursor at an x/y location. The values are base 1 If using [puts] with absolute screen coordinates via [gotoxy] you should use the -nonewline argument if possible to avoid screen scrolling issues Example: option expression off for {set i 0} {< $i 10} {++ i} { gotoxy 5 5 puts "I am at 5,5" -nonewline } See also: cls, box
Towers of Hanoi  Top  
The Towers of Hanoi script is a useful benchmark for speed. A compiled C++ version of the Tcl algorithm is a couple of orders of magnitude faster, but this is to be expected as Ticol Tcl is interpreted and outside the plugin module level, is not intended to be coded for performance The following example code, 'hanoi 17' runs in around 4 seconds on a low-powered i5 under Windows 7. option expression off cls set n 0 set yloc 1 if {! [defined draw_status]} { proc draw_status {} { upvar yloc gotoxy 1 $yloc upvar a upvar b upvar c upvar n upvar moves upvar x textcolor white puts "Towers of Hanoi ($n) - Pole Status ([comma $x] moves)\n" textcolor red printf "Pole A(%2i) %-67s\r\n" [stack count a] [stack list a] textcolor yellow printf "Pole B(%2i) %-67s\r\n" [stack count b] [stack list b] textcolor green printf "Pole C(%2i) %-67s\r\n" [stack count c] [stack list c] textcolor } } halt textcolor white blue puts " Towers of Hanoi " textcolor newline if {[< $argc 2]} { puts "How many rings (2..25)? " -nonewline gets stdin n if {|| [== $n ""] [== $n 0]} {stop} } else { set n $argv(1) } set n [min $n 25] stack create a $n # Init 3 stacks to given size stack create b $n stack create c $n for {set x 0} {[< $x $n ]} {++ x} { # Create initial stack of hoops stack push a [+ $x 1] # 0..n-1 } set x 1 set shln [<< 1 $n] # Precalc (1 << $n), << for n draw_status set start_secs [clock seconds] set start [timer] while {< $x $shln} { set xminus1 [- $x 1] stack push [chr [calc ((($x|$xminus1) + 1) % 3 )] 97] \ [stack pop [chr [calc ($x & $xminus1) % 3] 97]] is_mod $x 50000 draw_status ++ x } set end [timer] set end_secs [clock seconds] draw_status newline puts "Took [- $end $start] millisecond(s) and [comma $x] move(s)" puts "Took [- $end_secs $start_secs] second(s) and [comma $x] move(s)" newline puts "Done." stack unset a stack unset b stack unset c Results: Took 3884 millisecond(s) and 131,072 move(s) Took 4 second(s) and 131,072 move(s) For comparison. The compiled C++ hanoi.exe 17 gives the following and can run 'hanoi 23' in about the same time with 8,388,607 moves Took 47 ms and 131071 move(s)
Hex Routines  Top  
string [tohex string] string [fromhex value] string [inttohex decimal-variable ?-noprefix? ?-full?] integer [hextoint string] Conversion routines to convert from text and integers, to and from hexadecimal Note that because the Macro PreProcessor will translate hex values if prefixed with '0x', you should wrap any such values in double quotes before calling [hextoint], or you should strip any prefixing '0x', otherwise inaccurate results will be returned due to double, interpretation of the hex value [tohex] Converts a string into hex-encoding, the inverse is [fromhex] [inttohex] converts a decimal value to base 16, the inverse is [hextoint] Conversion from hex to decimal integer is automatic in Ticol The -full argument presents all prefixing zero values. Normally these leading zeroes are omitted If the -noprefix argument is given then the 0x... prefix will be omitted Example: puts [inttohex 12345] Result: 0x3039 Examples: puts [inttohex 12345] puts [inttohex 12345 -noprefix] puts [hextoint "0x3039"] puts [tohex "Hello world"] puts [fromhex 48656C6C6F20776F726C64] Results: 0x3039 3039 48656C6C6F20776F726C64 Hello world See also: int, double, data types
Code Highlighting Plugin  Top  
Load using: lib ticol_highlight?.dll? string [highlight string ?-bat? ?-rtf?] string [highlight {} -reset] [highlight] was created purely to output the Ticol man file as both HTML and RTF format files It can create a HTML-highlighted block of text from Tcl or Windows Batch script code using the Ticol man file markup syntax. Use the '-bat' argument for batch scripts Rich Text (RTF) output can also be generated using a custom {colortbl} entry Call as [highlight {} -reset] to reset multi-line string text highlighting if necessary Example files are supplied, man_to_rtf.tcl and man_to_html.tcl See also: Plugins, lib, rtf
Ticol HTML Plugin  Top  
Various HTML manipulation commands To load, use: lib ticol_html ?-verbose? ?-nocomplain? See separate topics for: html chomp_tag Parse an HTML file html header_field Return an HTTP/HTML header html remove_header Strip off an HTTP/HTML header html strip Remove all HTML tags from a string See also: plugins, http
html chomp_tag (Plugin)  Top  
To load, use: lib ticol_html ?-verbose? ?-nocomplain? string [html chomp_tag varName ?varOut ?-nobrackets?] Remove the next HTML tag from a variable, return it and remove that part of the string (including <> brackets) An optional array or simple variable (varOut) can receive any pre-tag prefix text, thus enabling combined HTML and plaintext to be parsed. Optionally the enclosing brackets can be omitted from any return Example: lib ticol_html set s [http http://localhost:8800] puts [html chomp_tag s] puts [html chomp_tag s] puts [html chomp_tag s] Result: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <html> <head> Example: lib ticol_html set s " <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\ <html><head><title>Hello world</title></head><body>\ Hello World </body></html>" puts [html chomp_tag s] # Tag:doctype html chomp_tag s # Tag:html html chomp_tag s # Tag:head html chomp_tag s # Tag:title html chomp_tag s t # Tag:/title. Return the title text value in 't' puts $t Example: lib ticol_html option expression off set s [http http://localhost:8800] do { set t [html chomp_tag s] puts $t } while {ne $t ""} Results: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <html> <head> <title> </title> </head> <body> ... See also: plugins, html strip, html header_field, html remove_header
html header_field (Plugin)  Top  
To load, use: lib ticol_html ?-verbose? ?-nocomplain? string [html header_field string field-name] string [html header_field varName field-name -var] Return a header field from an HTTP 1.1 block of HTML code. Case is ignored during comparison and trailing colons may be omitted for the field name. Whitespace is trimmed from the return string The -var argument allows a variable name to be passed instead of a string literal If either the string argument or field-name is null then an empty string is returned Example: # Emulate an HTTP header set x "HTTP/1.1 200 OK\r\n\ Date: Fri, 12 Jun 2017 13:26:15 GMT\r\n\ Server: Apache/2.4.10 (Ubuntu)\r\n\ X-Powered-By: PHP/5.5.12-2ubuntu4.3\r\n\ Redirect: http://localhost.com/index.php\r\n\r\n" puts "Date: \[[html header_field $x Date:]\]" puts "Redirect: \[[html header_field $x rEdIrEcT:]\]" puts "Server: \[[html header_field x server -var]\]" puts "Foo: \[[html header_field $x foo]\]" Result: Date: [Fri, 12 Jun 2017 13:26:15 GMT] Redirect: [http://localhost.com] Server: [Apache/2.4.10 (Ubuntu)] Foo [] See also: plugins, html strip, html header_field, html remove_header
html remove_header (Plugin)  Top  
To load, use: lib ticol_html ?-verbose? ?-nocomplain? string [html remove_header string] Servers may return a 'header' section as an HTML page prefix. This command offers an easy way to remove this [html remove_header] strips off and removes the HTTP header from an HTML body return string stripto may be used to remove other junk up to the first "<" bracket This command is also useful for removing any HTML prefix from JSON data which is prefixed by a header. See: json_to_list See also: plugins, http, html strip, html header_field, html chomp_tag
html strip (Plugin)  Top  
To load, use: lib ticol_html ?-verbose? ?-nocomplain? string [html strip string] Removes all HTML tags from a string   tags are replaced with a single space Example: set s "<b><em>Hello world</em></b>" puts [html strip s] Result Hello world See also: plugins, html remove_header, html header_field, html chomp_tag
http  Top  
http ?http://?domain?:port??url? ?port | -? ?var? ?-u user? ?-p pass? ?-1? ?-nocomplain? ?-head? Load a page of HTML text from a remote website via a HTTP 1.1 request HTTP is supported on any port but HTTPS and FTP etc. are unsupported For FTP, see ticol_ftp This is currently a minimal HTTP 1.1 implementation with automatic chunked download support which should be sufficient for rudimentary data download from a server. HTTP 1.0 using the ?-1? argument is available Binary downloads are currently unsupported but you can easily [spawn] external programs such as wget.exe for binary content The default port value is 80. This may be specified either in the URL or via the port argument. Extra headers cannot be specified. A URL which contains whitespace must be enclosed in braces or double- quotes Optional Arguments: -1 Use HTTP 1.0 instead of HTTP 1.1 -head Issue an HTTP HEAD command instead of HTTP GET -nocomplain Don't issue verbose output on errors -u Specify a username for BASIC Authentication -p Specify a password for BASIC Authentication Positional Arguments: Example: http "http://en.wikipedia.org/wiki/Main_Page" - x Result: puts "HTML is: $x" Example: puts [http http://localhost:8800/cgi-bin/ticol.exe?cgi.tcl] Result: <displays Tcl script page contents> See also: urlencode, urldecode, html remove_header, html header_field
int, double (Type Casting)  Top  
Type-casting operators: integer [int variable|number] double [double variable|number] Converts a numeric character to the requested type, by truncation of necessary. Input can either be a number or a variable name Bear in mind that Tcl is a "typeless" language where "everything is a string" However strings still have an apparent type, for example the string: 3.141592653589792 has "real" number characteristics, whereas ... 3 does not. Consequently one can transpose real numbers to integers. Also, Ticol assumes type and will assume integer values in some cases where this is undesired. This may affect certain math operations such as division forcing a truncated integer result. You can ensure a real number (double) operation by casting integer values to double Example: expr 22/7 Result: 3 Examples: puts [expr 22/double(7)] # Expression syntax puts [/ 22 [funct double 7]] # Using [funct] to call puts [/ 22 [double 7]] # [double] direct command puts [/ 22 7.0] # Command syntax with double value Result: 3.142857142857143 [int] and [double] are available as both expression functions and Ticol commands See also: vars, type
is_admin  Top  
bool [is_admin] Return $::true (1) if the current Windows user is an administrator See also: true, false, elevate, is_elevated, is_*
is_command  Top  
bool [is_command command|procname] Returns either $::true (1) or $::false (0) indicating whether a command or procedure is defined. [is_defined] may also be used to test for definition Example Result is_command puts 1 is_command put 1 is_command putt 0 See also: is_defined, commands, if, while. for. foreach, flow control, is_* true, false
is_const  Top  
bool [is_const varName] Returns a boolean $::true (1) or $::false (0) indicating whether a variable is a constant Example: set sid Hello enum { fred } puts "Is sid const? [bool [is_const sid]]" puts "Is fred const? [bool [is_const fred]]" Results: False True See also: bool, true, false, is_pointer, const, set, is_*
is_elevated  Top  
bool [is_elevated] Returns $::true (1) if Ticol is running with elevated privileges (Windows 7+) or $::false (0) if not [elevate] will self-call, passing the original command-line arguments Example: if {! [is_elevated]} { elevate } else { # Run the script } See also: true, false, elevate, is_admin, is_*
is_empty  Top  
bool [is_empty varname] Test if a variable is both set and empty. If a variable of either array or simple type is both set and empty it returns 1, otherwise it returns 0. Be careful to pass the name of the variable rather than its value Empty Not-empty ---------------------- unset 0 0 set 1 0 Example: set s {} if {is_empty s} { puts "Empty" } else { puts "Not empty" } Result: Empty See also: is_set, is_*
is_dir  Top  
bool [is_dir path] Tests if the given path string is a path or not, returning a boolean $::true (1) or $::false (0) See also: true, false, mkdir, mkdirs, unlink, file, is_*
is_pointer  Top  
bool [is_pointer varName] Returns a boolean $::true (1) or $::false (0) indicating whether a variable is a constant or not See also: true, false, is_const, setb, addressofb, ofaddressb, struct, is_*
is_proc  Top  
bool [is_proc name] Test if a command is a user-defined procedure. Returns a boolean $::true (1) or $::false (0) Example: if {is_proc foo} { undef foo } See also: true, false, proc, undef, is_*
is_mod  Top  
bool [is_mod value divisor ?{command}?] Fast, division-safe modular division check. If the divisor is zero then $false (0) is returned. This avoids extra Tcl code to prevent division by zero In loops this can lead to improved performance. A boolean $::true (1) or $::false (0) is returned. Performance may be enhanced by avoiding [if] and executing an optional command to evaluate if [is_mod] is true [is_mod] replaces the longhand expression: if {[== [% $x 1000] 0]} {call_proc} with: if {[is_mod $x 5000]} {call_proc} Calculations are performed on 64-bit integer values Example: [is_mod $x 5000 call_proc] Avoid using this... if {is_mod $i 1000} { printf "\r %2.f %% " [* [/ ${i}.0 $size] 100.0] } Use this instead, as it is more efficient is_mod $i 1000 { printf "\r %2.f %% " [* [/ ${i}.0 $size] 100.0] } See also: is_, is_number, math, is_*
is_numeric  Top  
bool [is_numeric string] Tests if a string is composed entirely of the following characters and returns boolean 1 if so, otherwise 0 +-0123456789,. This includes comma-formatted numbers Examples: puts [is_numeric hello] puts [is_numeric 10/01/2017] puts [is_numeric 23:59] puts [is_numeric 12345] puts [is_numeric +123.45] puts [is_numeric -12,345.67] Results: 0 0 0 1 1 1 See also: is_*
is_set  Top  
bool [is_set variableName ?-nocase?] Tests to see if a variable exists (is set). Similar to php's 'isset' This command is useful for testing potentially unset variables with [if] You cannot do the following with an array variable because the variable is resolved before [if] is called ... if {$_array(nosuch_element)} { # Will raise an unset variable error Instead use [is_set]: if {is_set _array(nosuch_element)} { You should pass a variable name not the dereferenced contents of a variable [is_set] returns a boolean value (1 or 0) [is_set] may be used on standard Tcl variables such as string variables, arrays, lists, stacks, structs. For arrays you may also use [array is_set] If using option expression on then the 1st argument will not be interpreted as a command. Thus care should be taken with flow-control statement arguments Correct use of [is_set]: option expression on if { [is_set argv] } {...} option expression off if { is_set argv } {...} Incorrect: if { is_set $argv } {...} if { [is_set $argv] } {...} Array existence should be tested using [array exists] See also: is_empty, array exists, is_admin, is_dir, is_elevated, set, vars, is_*
join  Top  
string [join list ?separator?] Join elements within a space-separated Tcl list and return a string. The spaces are removed during the process. The list elements may be separated by an optional separator character Example: set s "The quick brown fox" set r [join $s "-"] puts $r Result: The-quick-brown-fox [join] can also be used to 'flatten' a list by one level. The outer- braces are always removed when an argument is passed to a command but an additional +1 level of braces is removed Example: set data {1 {2 3} 4 {5 {6 7} 8}} puts [join $data] Result: 1 2 3 4 5 {6 7} 8 See also: split, list
json_to_list (JSON Conversion Plugin)  Top  
This is a very simple JSON conversion command To load, use: lib ticol_json?.dll? ?-verbose? ?-nocomplain? list [json_to_list json_string|variable-in ?-var? ?variable-out?] Convert a sequence of JSON format data into Tcl list format Converting JSON using native Tcl code can be quite slow. This function speeds up conversion significantly compared to a Tcl code implementation The command was written for a specific data-processing task and may not, therefore, be feature-complete as far as the JSON specification is concerned. It contains a subset of the JSON feature set If -var argument is passed then the main input argument is interpreted as a variable name. An optional output variable is suppoted. This may be either a simple variable or an array element Example: lib ticol_json -verbose set json { "name":"John", "age":30, "car":null } set l [json_to_list $json] puts "Name: [lindex $l 0 1]" puts "Age: [lindex $l 1 1]" puts "Car: [lindex $l 2 1]" Results: Name: John Age: 30 Car: null See also: Plugins, list, list_to_array, unwrap
Ticol line - Line Processing Plugin  Top  
Efficiently process lines from CRLF-delimited text. Allows a block of CRLF-delimited text to be addressed as conveniently as if it was an array To load, use: lib ticol_line?.dll? ?-verbose? ?-nocomplain? integer [line count string|?varname -var?] string [line <number> string|?varname -var?] integer [line <number> string|?varname -var? -array name] [line count] will return a count of CRLF-delimited lines in a string [line <number>] will return a particular line number from a CRLF- delimited string If the -var qualifier argument is appended then the passed string argument will be assumed to be the name of a variable. This avoids having to make copies of large strings internally and should improve performance in loops If '-array name' is appended then an array will be returned containing the requested lines of text. The command will return the count of lines returned Example: lib ticol_line set s [readfile foo.txt] puts [line count $s] Example: lib ticol_line set s [readfile foo.txt] puts [line 237 $s] Example: lib ticol_line set s [readfile ovid.txt] puts [line 237 $s 4 -arrray a] Result: # Returns 4 lines from 237 on in array 'a' See also: plugins
K Combinator  Top  
string [K x ?y? ...] Functional programming K-combinator. Allows chaining of Tcl expressions Functionally equivalent to: proc K {a b} {return $a} It can be used in all situations where you want to deliver a result that is not the last. i.e. the first item is returned but the last discarded The K is a capital letter K (not lower-case k) For instance, reading a file in one go: proc readfile filename { set f [open $filename] set data [read $f] close $f return $data } can be simplified, without need for the data variable, to: proc readfile filename { K [read [set f [open $filename]]] [close $f] } Swap two variables, say a and b, without any temporary variables: set a [K $b [set b $a]] Another example, popping a stack: proc pop _stack { upvar 1 $_stack stack K [lindex $stack end] [set stack [lrange $stack 0 end-1]] } We can also achieve an efficient implementation of lambda expressions in Tcl using K: proc lambda {arg body} { K [set n [info $body 0]] [proc $n $arg1 $body] } For more information see: http://wiki.tcl.tk/1923/ See also: list functions
key input routine  Top  
Here is an example input procedure for single key input with echo This could also be implemented as a [sub] if {! [defined get_key_input]} { option expression off proc get_key_input {} { # Returns a lower-case keypress while {1} { set k [getkey -lower] if {eq $k "y"} { puts $k return "-r" } elseif {eq $k "n"} { puts $k return {} } elseif {eq $k "q"} { puts $k return q } sleep 20 } } } Example usage option expression off set r [get_key_input] if {eq $r "q"} { textcolor red puts "\n * Quit *" textcolor stop } See also: getkey, input, proc, sub
Lambda Example  Top  
Here is an example Lambda function from the http://tcl.tk website When called from a script the lambda function can be called using puts [$inv x]. This script cannot handle lists of arguments When called from the Ticol CLI you can use just $inv x - e.g. $inv 5 proc lambda {args body} { puts "in lambda args:$args body:$body" set name [info level 0] # Should return lambda x {expr 1./$x} puts "Name:$name" commands $name proc $name $args $body set name } set inv [lambda x {expr 1./$x}] # Calls proc lambda puts [$inv 5] # Call with $inv 5 from the Ticol CLI Result: 0.2 The [lmap] command can also be used to construct lambda expressions such as: puts [lmap {x {expr {$x * $x}}} {1 2 3 4 5}] For more on lambda expressions see: lmap and apply See: http://wiki.tcl.tk/519 See also: K, apply, lassign, lmap, map
lappend  Top  
list [lappend listVar string ?string?...] Append list elements onto a variable or creates a list from a series of strings. Strings with spaces are wrapped in double quotes. The variable referenced in the argument will be created if it does not exist Where the string to be appended contains reserved Tcl characters such as {}{}$\ these will be escaped in order to print safely Creating Nested Lists --------------------- Don't use [lappend] to add enclosing { and } braces to create sub lists as this will add superfluous spaces and break parsing. Either append sub items to a sub-list and [lappend] that or use string routines to wrap in {} Examples -------- Example: puts [lappend var [list one two] three] puts $var Result: {one two} three Example: set s "" echo [lappend s "{escaped"] # [echo] is required to see the escapes Result: \{escaped Example: # Will create a new variable lappend nosuchvar 1 2 3 # Variable 'nosuchvar' does not exit puts $nosuchvar Result: 1 2 3 See also: lindex, list
lassign  Top  
list [lassign list ?varName ...?] This command treats the value list as a list and assigns successive elements from that list to the variables given by the varName arguments in order. If there are more variable names than list elements, the remaining variables are set to the empty string. If there are more list elements than variables, a list of unassigned elements is returned, otherwise an empty list {} is returned Example: lassign {a b c} x y z Result: $x =>'a' $y =>'b' $z =>'c' Example: lassign {a b c} v w x y z Result: $v =>'a' $w =>'b' $x =>'c' $y =>'{}' $z =>'{}' Example: lassign {a b c "The quick" "brown fox" "jumps"} x y z Result $x =>'a' $y =>'b' $z =>'c' {The quick} {brown fox} jumps See also: lappend, list, apply, lmap, map, apply, lambda
lcount  Top  
integer [lcount list] integer [lcount varname -var] Returns an integer count of the number of items in a list Using -var and a variable name avoids a time-consuming variable copy which may improve performance in tight loops or with very large lists The argumment list must be either a variable or, if a literal string, enclosed in braces or double-quotes Example: puts [lcount $qbf] # Count the number of words puts [lcount qbf -var] # Count the number of words puts [lcount {{a b} c}] Result: 9 9 2 Example: See also: list, lindex, lappend, lassign
ldepth (proc)  Top  
integer [ldepth list] Returns the depth of a list or 0 for an empty or flat list Procedure definition: proc ldepth {list} { if {! [is_list $list]} { return 0 } set flatList [join $list] if {[string equal $flatList $list]} { return 1 } return [expr {[ldepth $flatList] + 1}] } Example: set l {} puts [ldepth $l] set l a puts [ldepth $l] set l {a b} puts [ldepth $l] set l {a {b {c d}}} puts [ldepth $l] Results: 0 1 1 3 See also: unwrap, list, lappend, lassign, lcount, ldepth, lindex, list, list_to_array, llength, lmap, lrand, lrange, lreverse, .lsearch lset, lsort
lastchar  Top  
string [lastchar string] Returns the last character of a string (or list interpreted as a string) If the string is empty then an empty string "" is returned [lastchar] is more efficient than convoluted combined commands such as: puts [mids $qbf [string length $qbf] 1] Examples: puts [mids $qbf [string length $qbf] 1] puts [lastchar $qbf] puts [lastchar Hello] puts [lastchar ""] Results: g g o "" See also: string, left, right, mids, mid
left, string left  Top  
string [left string n] string [string left string n] string [left string varName -var] string [string left varName n -var] Return the leftmost n characters of a string A common task is to look at the first character of a string. The most effective way to do this is to use [index] rather than [string left] Example: puts [string left $qbf 1] puts [index $qbf 1] Results: T T See also: index, right, mid, lastchar, cset, lset, rset, strto, strtor
len  Top  
integer [len string] Return the length of a string This is a convenient alias for [string length] Example: puts [len $qbf] Result 43 See also: string, string length, lastchar
let (Assignment command)  Top  
let Lvalue = Rvalue Evaluate Rvalue(s) as an expression then assign let Lvalue := Rvalue Assign rvalue(s) without evaluating (assignment) The MPP may simplify/evaluate expressions Rvalue of [expr] or [command] will still evaluate If Rvalue is a string then a well-formed Tcl list will be returned (this may be brace-wrapped) let Lvalue ++ Increment lvalue(s) - equivalent to [++ var] let Lvalue -- Increment lvalue(s) - equivalent to [-- var] let Lvalue += Rvalue Assign to existing value. Rvalue may be expression Will cast to double before addition let Lvalue -= Rvalue Assign to existing value. Rvalue may be expression Will cast to double before subtraction let variable|array = expression|variable|array|[command] # Eval with expr let variable|array := list|variable|array|[command] # Assignment only let variable|array = {variable|array} # Evaluate contents with [expr] let variable|array := {variable|array} # Assignment of values only [let] implements a proposed extension to the Tcl language. It acts similarly to [set] except that it accepts a Tcl expression as the Rvalue The expression may be another Tcl variable or a complex statement [let] returns the resulting Lvalue variable's contents if there is only one lvalue. If several variables are [let] then the last variable's contents is returned Whitespace is allowed between individual Rvalue expression arguments where '=' is used to separate. This will be removed before the result is evaluated using [expr] To assign a literal string rather than evaluate it, use the ':=' operator instead of '='. This also allows the result of a bracketed [eval] operation or commands to be assigned. For numeric expressions there will be no difference between the two methods since the numeric result will be correctly checked by [expr] Example: let x y z := "06/Jun/2015" # Note: just assign, don't [eval] Note that expressions contained within square [] brackets will have already been evaluated before being presented to [let]. Therefore the result will be re-evaluated again when using '='. Where this is not desired use direct assignment ':=' For example let a b c = [info commands] return an invalid result since the resulting command string will be re-evaluated as an expression. The correct command would be: let a b c := [info commands] Example: set x "Hello world" let a b c := $x puts "$a, $b, $c" Result: Hello world, Hello world, Hello world, Example: let x := [/ 22 7.0] # Call assign instead of expr Result: 3.142857142857143 # [] are always resolved Example let x := [/ 22 7.0]*2 # Call assign instead of expr Result: 3.142857142857143*2 # [] are always resolved Example let x = [/ 22 7.0]*2 # Call expr and assign the result Result: 6.285714285714286 Example: let x := "Hello world" # Will return a Tcl list Result: {Hello world} Example: let x := one "two three" four # Will return a well-formed Tcl list Result: one {two three} four Example: set q 0;let q += [rnd 1 10]; puts $q Result (some value between 1 and 10): 2.000000 Let is an efficient way of setting variables to a complex expression which avoids intermediate steps but will be slower and less-efficient for simple assignments of const values When using the '=' operator, variables, including array variables will be evaluated before the call to let, and the contents of the variable will then be evaluated by let as an expression, thus if you wish to assign the value of a variable without interpretation you must wrap the rvalue variable in braces thus: Example: let path = {$env(TEMP)} # Prevent [expr] evaluation, pass as a literal let path := $env(TEMP) # Alternate method, direct assignment Result: x is correctly set to 'c:\temp' Example: let path = $env(TEMP) Result: x is incorrectly set to 'temp' after evaluation of c:\temp Expression examples: Example: let q = 4 * atan(1) puts "q is $q" Result: q is 3.141592653589792 Example: let q = [fib 12] puts "q is $q" Result: q is 233 Example: let x = {rnd(1,5)>2?return Hi:return Lo} # rvalue must be wrapped in {} Result: Lo See: Tcl language extension proposal: http://wiki.tcl.tk/3880 See also: set, unset, vars
lib (Ticol Plugin Module Extension Loader)  Top  
Load or reference a library using the following syntax: result [lib <libraryname>?.dll? ?-option?] integer [lib dllname ?filter|modulename? ?-list? ?-nocomplain? \ ?-verbose? ?-replace?] # Load a library plugin string [lib dllname -info] # Show lib information integer [lib dllname -unload] # Unload a module string [lib -modules] # List loaded modules bool [lib -loaded module_name] # Test if a module is loaded bool [lib module_name -loaded] # Test if a module is loaded ticol.exe /lib:dllname ?/lib:dllname...? # Load at startup (For a list of available plugins see: help plugins) Load a Ticol plugin extension DLL. The DLL must have been written for Ticol using the Ticol interface standards/ It must provide query interfaces according to the supplied API definitions. (See the accompanying API documentation) If no path is given, [lib] will attempt to load the plugin library from the current ticol.exe path location. The command returns a count of the number of modules loaded or unloaded [lib] will load commands into the current interpreter instance. Once loaded these cannot be reloaded by [lib] until they have been undefined using [undef]. [lib -nocomplain] may be used to ignore any reload errors. No load status will be printed to the console unless the -verbose arg is used Conflicting commands can be automatically unregistered using the -replace arg Once loaded, plugin library functions may be used the same as any other internal Ticol command and variable memory assigned is automatically garbage-collected [lib -info] Calling separately with the -info arg will return the version number as x.xx and the build date in ISO format as a Tcl list. This command does not load the library To unload a plugin and remove all registered commands use the -unload argument. -unload will return a count of modules successful de-registered A library may be loaded at startup using: ticol.exe /lib:dllname Any number of modules may be loaded at startup [lib -modules] will return a Tcl list of all registered Ticol module DLLs Examples: lib ticol_zip # Load in silent mode lib ticol_mail.dll -verbose # Load in verbose mode lib ticol.dll d* -list # Load and return modules as a list lib ticol.dll -unload # Unload ticol.dll lib ticol_bignum.dll -replace # Reload puts [lib ticol_ping -info] # Returns "1.02 20160331" puts [lib -modules] # "ticol_bignum ticol_zip ticol_reg" To unload all loaded plugins use the following code snippet foreach x [lib -modules] {lib $x -unload} An audit of all modules can be performed using the following code set file [escape [ls "ticol_*.dll" -list]] set l "" foreach x $file { set cmds [lib $x -list] # Load with command list set info [lib $x -info] # Module info textcolor yellow puts $x # Lib filename textcolor puts "\t$info" puts "\t$cmds" lib $x -unload } newline puts "[lcount $file] module(s)" See: plugins for a list of available Ticol plugin modules See also: plugins, lib interface, undef, commands
lib interface specifications  Top  
Plug-in DLLs can be produced for Ticol which adhere to the following specifications: All functions must be exported as __cdecl The following exports must be offered: long __cdecl _get_dll_version() { return _DLL_VER // C++ macro definition } LPCSTR __cdecl _get_dll_date() { return _DLL_DATE; // C++ macro definition } LPCSTR* __cdecl _get_function_list() { return _dll_function; // C++ array } LPCSTR* __cdecl _get_command_list() { return _dll_command; // C++ array } long __cdecl _get_export_count() { return _export_count; // Defined from arrays } Interface functions (as defined above) must be exported by name as __cdecl with the following Ticol command signature: int (__cdecl* CmdFunc)(struct Interp* i, int argc, char** argv, void* pd) Your functions will use i as the interpreter instance and use the argc/argv arguments to receive arguments. These arguments may be altered but not deleted or reassigned. Full details of available library functions are given in the plugin documentation. For more information see the example C++ source code ticol_init(); should be called before calling any Ticol library functions Only locally-allocated memory may be freed. The C++ lib header has prototypes for a number of functions exported back from Ticol to the DLL for memory housekeeping etc. Commands are specified as case-sensitive strings which must not contain spaces Example stub code: int __cdecl CommandTest(struct Interp *i, int argc, char **argv, void *pd) { print_error("%s: Command not implemented\n",argv[0]); _ticol_set_result(i,"0"); return TICOL_OK; } See also: plugins, commands
lindex  Top  
string [lindex list index ?index|end-N?...] Index an item from a list. Multiple index selectors may be given, in which case, each will be selected in turn from left to right. Brace binding is honoured and quoted strings are treated as distinct objects outside of braces. Index values are array base indexed at zero Indexing very large lists (megabytes and above) can be quite slow. Arrays should be used in preference For single indices, the mnemonic, "end" may be used either with or without an adjustment value, e.g. end-4 To return a range of elements from a list, see [lrange] Example: set l [list colour "icon cornflower blue"] puts $l Result: colour {icon cornflower blue} Example: puts [lindex $l 0] Result: icon Example: puts [lindex $l 1 0] Result: icon Example: puts [lindex $l 1 1] Result: cornflower See also: list, lrange, llength, lappend
Line Continuation Character  Top  
A backslash character can be appended to the end of a Tcl source file line This will cause the line to continue onto the next and the backslash to be ignored. A space will be appended to data from the next line. Any whitespace before the \ character will be left in-situ Care should be taken to include formatting spaces when breaking up a string The next line should start at the beginning of the line and not be indented by source-code formatting unless you want this to be included in the resulting string The line-continuation character must not be followed by any other character or comment such as # on that line or it will be interpreted as a literal backslash rather than end of line marker Ticol also handles multi-line strings in a source file. Example: (First char of each next line is will become a space) .........1.........2.........3... puts "The quick brown\ fox jumps over\ the lazy dog" Result: The quick brown fox jumps over the lazy dog Example: (Multi-line string. The text format is retained) .........1.........2.........3... puts "The quick brown fox jumps over the lazy dog" Result: .........1.........2.........3... The quick brown fox jumps over the lazy dog Example: (Results in extra spaces) .........1.........2.........3... puts "The quick brown \ fox jumped over \ the lazy dog" Result: The quick brown fox jumps over the lazy dog Example: .........1.........2.........3... puts \ "Hello world" Result: Hello world Where if statements are used with [option expression on] and the expression is on multiple lines then line break continuation characters must be used, e.g. set r [rnd 1 10] if { $r \ > \ 5 } { puts Yes } else { puts No } Numbers may be declared using line-continuation providing they are wrapped in double quotes, thus: set n "12345\ 6789" See also: escape sequences, macro, #ifdef, #define
Line Numbers  Top  
Absolute line numbers exist only in an original Ticol source script. In Tcl there is no concept of absolute line numbers within operational code since code may be broken up into many separate fragments (e.g. procs) The Macro PreProcessor (MPP) will completely remove comment lines and thus the original line numbers cannot be traced. Also, procedures use copied segments of code which have no absolute line numbering. Line numbers referring back to the original source code can be matched during debugging by the use of a variable set within the source code at strategic points using the #__LINE__ macro Example: set line #__LINE__ if {! [defined check] } { # [assert] is the native alternative proc check {x y} { if {!= $x $y} { puts "Error in test at after line $::line" puts "$x != $y" stop } } } set line #__LINE__ check [expr "abs(-100)"] 100 # Should pass set line #__LINE__ check [expr "abs(-100)"] 101 # Should fail Result: Error in test at after line 15 See also: assert, line continuation character, debugging, performance
llength  Top  
integer [llength literal-list] Return the count of items in a Tcl list or 0 if the list is empty llength takes a dereferenced list literal as argument, not a variable name Example: set a [list one two three] puts [llength $a] Result: 3 See also: list, lappend
link_to_path  Top  
string [link_to_path filename] Resolve a Windows LNK shortcut file to the target path for that link file The result is an unescaped string. [escape] may be required to use the return with other commands Example: (This uses an external app: makelink.exe to create the LNK file) makelink.exe ticol.exe . puts [link_to_path ticol.exe.lnk] Result: C:\Tcl\ticol.exe See also: info file, escape
Linked List Plugin  Top  
To load use: lib ticol_list ?-verbose? ?-nocomplain? handle [linkedlist create] bool [linkedlist add handle lvalue ?rvalue?] string [linkedlist get handle lvalue] string [linkedlist item handle integer] code [linkedlist foreach $handle lvalue ?rvalue? {command}] bool [linkedlist in_list handle key] bool [linkedlist insert handle key lvalue ?rvalue?] long [linkedlist count handle] void [linkedlist walk handle] bool [linkedlist unset handle key] bool [linkedlist unset handle] [linkedlist] offers standard low-level, linked lists. These are not the same as Ticol built-in Tcl lists (which are represented as ordered strings) [linkedlist] enables a programmer to create rapid, robust linked lists in the same manner as offered by many other high-level programming languages External data structures such as [linkedlist] require a valid handle variable to access A list has a start (often called a 'head') and an end (often called a 'tail'). Items are usually added to the start of the list and the 'tail' value represents the most recently added item. Lists are iterated by starting at the 'start' node and reading each successive node in the chain until the 'tail' or last node is met the quick brown +------+ +------+ +------+ +-----------+ | head |->|node 1|->|node 2|->|tail (NULL)| +------+ +------+ +------+ +-----------+ |lvalue| |lvalue| |lvalue| | N/A | +------+ +------+ +------+ +-----------+ |rvalue| |rvalue| |rvalue| | N/A | +------+ +------+ +------+ +-----------+ Each node in the linked list can store two variables. Each will store an lvalue (left hand value) and may optionally store an rvalue (right hand value) [linkedlist create] Creates a new list and returns a handle to the created list. A list is identified and manipulated by its handle. It is a fatal error to issue a list command with an invalid, freed or absent handle [linkedlist add] will add a new item to the linked list. Each successive new item is added at the head of the list. An "rvalue" is optional Example: linkedlist add $handle hello linkedlist add $handle pi 3.14159265358979323 [linkedlist get] retrieves an 'rvalue' (if any) from a list item. A list item may either simply be present in the list (as an lvalue) or the lvalue may have an associated rvalue. (lvalue and rvalue stand for left hand value and right-hand value respectively) Example: # The lvalue is 'pi', the rvalue is '3.14159265358979323' linkedlist add $handle pi 3.14159265358979323 puts [linkedlist get $handle pi] [linkedlist item] Allows for random access of the linked list by integer value. The first item in the list will be '1' (i.e. a base 1 index) [linkedlist count] should be used to obtain a count of list items Example: option expression off set handle [linkedlist create] set i 1 foreach {x} $qbf { linkedlist insert $handle {} $x $i ++ i } for {set i 1} {< $i [linkedlist count $handle]} {++ i} { set lv [linkedlist item $handle $i] # LValue set rv [linkedlist item $handle $i -rvalue] # RValue puts "$i:\t$lv\t$rv" } Result: 1: lazy 8 2: the 7 3: over 6 4: jumps 5 5: fox 4 6: brown 3 7: quick 2 8: The 1 [linkedlist foreach] allows iteration over the list from start to head, calling some body of code. An lvalue variable must be supplied. An rvalue variable is optional. Standard flow-control commands such as [break], [return] and [stop] are supported and these will return an appropriate error code (See: error codes, stop, break, return) Example: set handle [linkedlist create] set i 1 foreach {x} $qbf { linkedlist add $handle $x $i ++ i } linkedlist foreach $handle lv rv { puts "foreach is:\t'$lv'\t'$rv'" if {[eq $lv fox]} { puts "* Break *" break } } Results: foreach is: 'The' '1' foreach is: 'quick' '2' foreach is: 'brown' '3' foreach is: 'fox' '4' * Break * [linkedlist in_list] can be used to test if a given lvalue (key) is present in a given linked-list structure Example: set handle [linkedlist create] set i 1 foreach {x} $qbf { linkedlist insert $handle {} $x $i ++ i } puts "dog present?: [bool [linkedlist in_list $handle dog]]" puts "cat present?: [bool [linkedlist in_list $handle cat]]" Results: true false [linkedlist insert] inserts a new entry AFTER any key value which is found or at the start of the list if the key value was not found or was supplied as an empty/null value Example: linkedlist insert $handle quick blue linkedlist unset $handle fox Repeated calls to [linkedlist insert handle {}] can be used to create a list in reversed-order from the default. Each successive call will add the new value to the beginning of the list Example: set handle [linkedlist create] set i 1 foreach {x} $qbf { linkedlist insert $handle {} $x $i ++ i } linkedlist walk $handle Results: List 0x2d60cb0 0 item(s) List::walk 0x2d60f70 VT_001e [dog]=>'9' List::walk 0x2d60f20 VT_001e [lazy]=>'8' List::walk 0x2d60ed0 VT_001e [the]=>'7' List::walk 0x2d60e80 VT_001e [over]=>'6' List::walk 0x2d60e30 VT_001e [jumps]=>'5' List::walk 0x2d60de0 VT_001e [fox]=>'4' List::walk 0x2d60d90 VT_001e [brown]=>'3' List::walk 0x2d60d40 VT_001e [quick]=>'2' List::walk 0x2d60cf0 VT_001e [The]=>'1' [linkedlist count] will return a count of the number of items in a list [linkedlist walk] will perform a debug 'walk' of the linked list, starting at the beginning and iterating all nodes until the head is met Cleanup ------- It is not recommended to [return] from a linked script with ticol_list loaded and objects created unless you first clean-up using [lib ticol_list -unload] and/or specifically call [linkedlist unset] [linkedlist unset $handle] Destroys the linked list and renders the handle invalid. Attempts to use a handle after a call to unset will raise an exception. [linkedlist] objects are not subject to automatic garbage- collection on proc-exit [lib unload] destroys all created lists and reclaims their memory Example: set handle [linkedlist create] puts "Handle to list is $handle" set i 0 foreach {x} $qbf { linkedlist add $handle $x $i ++ i } linkedlist insert $handle jumps "rapidly" # Insert after jumps linkedlist insert $handle {} *start* # Insert at start linkedlist insert $handle fox dog # Add dog after fox linkedlist unset $handle fox # Remove fox linkedlist walk $handle linkedlist unset $handle Results: List 0x2d20fe0 10 item(s) List::walk 0x2d20cd0 VT_001e [The]=>'0' List::walk 0x2d20d20 VT_001e [quick]=>'1' List::walk 0x2d20d70 VT_001e [brown]=>'2' List::walk 0x2d21150 VT_001e [dog]=>'10' List::walk 0x2d20e10 VT_001e [jumps]=>'4' List::walk 0x2d21100 VT_001e [rapidly]=>'9' List::walk 0x2d20e60 VT_001e [over]=>'5' List::walk 0x2d20eb0 VT_001e [the]=>'6' List::walk 0x2d20f00 VT_001e [lazy]=>'7' List::walk 0x2d20f50 VT_001e [dog]=>'8' See also: list, array, stack, struct, error codes
list  Top  
list {vars...} Return a Tcl list from a series of variables. List creates an atomic parameter which can be supplied/chained into other parameters Example: call [dict create d colours [list orange red blue green purple]] Ticol supports a range of standard Tcl list commands Note that a plugin also offers standard linked lists: (See: linked list) See: list commands See also: lappend, lreverse, lcount, lindex, llength, lassign, list_to_array, array_to_list, string, linked list, apply
List Processing Commands  Top  
Ticol lists are simple formatted strings, and are quite inefficient. List processing operations should be kept to relatively short lists For greater efficiency, use arrays or stacks See the following separate help topics: array_to_list Convert an array to a list in Test if an item is in a list lappend Append an item to a list lassign Anonymous functions. Apply a command to a list lcount Return the count of elements in a list ldepth Test the depth of a list (proc) lindex Return an item from a list by integer index list Return a well-formed Tcl list list_to_array Convert a list to an array llength Return the length of a list lmap Iteratively assign elements of lists to variables lrand Return a random element from a list lrange Return a range of items from a list lreverse Reverse the order of a list lsearch Search a list for an item lset Set a list (deprecated) lsort Sort a list ni Test if an item is not in a list See also: Tcl lists
list_to_array  Top  
integer [list_to_array <tcl-list> arrayname] Converts a well-formed Tcl list into an array indexed by integer from element base 0. Example: set r [list_to_array $qbf out] puts "list_to_array returned $r item(s)" set s [array size out] for {set i 0} {[< $i $s]} {incr i} { printf "%i:\t%-40.40s\r\n" $i $out($i) } Result: list_to_array returned 9 item(s) 0: The 1: quick 2: brown 3: fox 4: jumps 5: over 6: the 7: lazy 8: dog See also: list
lrand  Top  
string [lrand <list>] Returns a random element from a list Example: puts [lrand $qbf] Result: fox # (probably) See also: list
lrange  Top  
list [lrange <list> start finish|end|end-N] [lrange] returns a range of list elements from the given list. The index values are 'base 0' values where 0 is the first element The end value may be specified using either 'end' for the last item or 'end-N' for the Nth item before the last To select single elements from a list or sub-list see [lindex] Example: puts [lrange $qbf 1 3] # 2nd to 4th items Results: quick brown fox See also: list, lindex, list commands
lreverse  Top  
lreverse tcl-list Reverse a Tcl list. The list must be a well-formed Tcl list or simple space/tab-separated string Example: puts [lreverse $qbf] Result: dog lazy the over jumps fox brown quick The Example: set q "Now is the {time for all good men} to come to the aid of \ {the party}" puts [lreverse $q] Result: {the party} of aid the to come to {time for all good men} the is the is Now See also: list
Tcl Lists  Top  
A Tcl list is a sequence of characters, optionally separated by whitespace and grouped, where necessary by braces. To all intents and purposes a Tcl list is a human-readable string. Lists get complex when there are nested lists and nesting where braces protect space-separated lists. Sub-lists are likewise braced "This is a list" Placing this as a sub-list we get: "This is a list {This is a list}" As with Lisp, complex "tree-like" hierarchies can be represented using lists See also: list, lindex, lassign
load  Top  
# Unencrypted file load filename?.tcl? ?targetVarName? ?-password password? # Encrypted file load filename.tcx ?-password password? # Clear a loaded file load -clear Load to the Console and Run --------------------------- Loads a Tcl file from the interpreter shell [load] with no arguments will display information about a loaded script Use [run] to run the file once loaded Use [dump] to display non-encrypted (obfuscated) loaded source code to the console and optionally to a Tcl variable Use [load -clear] to erase the script buffer (See also: clear) The [load] command does not clear the user-level variable table or non- system level consts (See: run, clear) [load] with a .tcx file and, if necessary a password via -password will load and decrypt a protected file. Load to a Variable ------------------ Optionally, a file may be loaded to a variable instead of the CLI. In this case any loaded program will be cleared and the preprocessed source loaded to the given variable. If the variable exists it will be overwritten. You can then run this source using [eval $varname]. The source is not returned or echoed by the [load] command Example: load test.tcl code # Load 'test.tcl to variable 'code' > Loaded test.tcl OK 1420 byte(s) # CLI acknowledgement eval $code # Runs the script at the CLI See also: run, dump, exit, clear
logo  Top  
logo fore ?back? ?x? ?y? Draw the Ticol logo See also: console, screen, puts
lmap  Top  
lmap {lambda-expression} list Iteratively assigns elements of one or more lists to variables, executes the lambda-expression argument, and collects the results into a new list by callin [apply]. The lambda-expression will be an expression such as: {x {expr {$x * $x}}} # Given x return x * x [lmap] applied to an empty list will return an empty list [lmap] is defined as a native command in Ticol. This can also be emulated using the following Tcl code and using [apply]. The native command is more efficient, performance-wise proc lmap {lambda list} { set result {} foreach item $list { lappend result [apply $lambda $item] } return $result } Example: puts [lmap {x {expr {$x * $x}}} {1 2 3 4 5}] Result: 1 4 9 16 25 Example: puts [lmap {x {return [string length $x]:$x}} {a bb ccc dddd}] Result: 1:a 2:bb 3:ccc 4:dddd See: https://wiki.tcl-lang.org/13920 http://www.tcl.tk/man/tcl/TclCmd/lmap.htm See also: lambda, list, apply
loop (Flow Control)  Top  
loop variable start limit ?increment? {code} A simple and efficient [for] loop. [loop] performs around 50% faster than [for] (excluding the code payload). loop i 0 10 2 {puts "Hello $i"} is equivalent to: for {set i 0} {< $i 10} {incr i 2} { puts "Hello $i" } [loop] takes 5 argument with an optional 6th argument to specify an increment. There is no need to brace all but the last argument [loop] takes a loop variable name as its 2nd argument, which will be initiated to the value of the 3rd argument. The final 'code' argument will be evaluated, incrementing the loop variable by 1 unless an increment value is specified as the optional 5th argument The increment argument may be positive or negative but not zero. If argument 3 is higher than argument 4 and no increment argument is given then an increment of -1 will be used The [loop] variable will always be the same as the limit variable on exit but the loop will execute for 'limit-start' times. So 'loop i 0 10' will execute 10 times, looping from 0 to 9 inclusive the same as [for] if 'start' is equal to 'limit' then the loop code body is never executed and 'limit' is returned in the loop variable [loop] supports [continue], [break] and [return] [loop] uses signed 64-bit integers as its loop arguments Example: # Automatic use of +1 increment loop i 0 5 { puts "i is $i" } puts "Final i is $i" # Automatic use of -1 increment loop i 5 0 { puts "i is $i" } puts "Final i is $i" Results: i is 0 i is 1 i is 2 i is 3 i is 4 Final i is 5 and i is 5 i is 4 i is 3 i is 2 i is 1 Final i is 0 Example: option expression off set i 0 proc foo {} { upvar i loop i 0 10 1 { puts "i is $i" if {== $i 5} {return $i} } } foo puts "i is $i" Result: i is 5 Example: option expression off loop i 0 10 1 { if {== $i 5} { # Skip 5 and increment past 6 ++ i continue } } puts "i is $i" Result: i is 10 See also: for, while, do, flow control
Listing Files  Top  
See: ls See also: file
ls  Top  
ls <filespec> ?-r? ?-ad | -af | -all? ?-la? ?-list ?var?? ?-array var? List files This is not a complete implementation -r Recursive search (includes subfolders) -ad | -af Attributes: directory or file -all List all files -la List all file details -list ?var? Return in list format (variable not mandatory) -array var Return the list as an array (variable is mandatory) var Storage variable is optional (for either -array or -list) If var is given then a filespec must also be given Ordering/sorting is not supported. You can sort the result from -list Perform a Windows-compatible directory listing. The result can optionally be fed into a variable and optionally in Tcl list format using the -list arg If [option echo] is set to OFF then [puts] or [printf] must be used to display the results Forward-slash and backslash path separators are supported CAUTION: The default is not to return a Tcl list. Use -list to return one Example: option echo off ls *.txt -la -list a # Return list in var 'a' foreach {q} [lsort $a] { # For each file row entry foreach {i j k l} $q { puts "'$i' '$j' '$k' '$l'" } } Example: option echo on ls c:/temp/newdir ls "c:/temp/newdir/*.tcl" Note: where the external Windows DIR command is used this requires backslash syntax and does not support Unix/Tcl style forward slash path separators See also: unlink, mkdir, mkdirs, chdir, getcwd
lsearch  Top  
integer [lsearch ?option ...? list pattern] Where ?options? are implemented as follows: -glob Default. Use a glob style match v's -exact (see: glob) -exact Make an exact match (case-sensitive) v's -glob matching -nocase Make a case-insensitive comparison -inline Return the value rather than the list index position -start N Start processing at list index item offset N An array base 0 value corresponding to [string index] where 0 is the first item in the list, 1 the 2nd etc... This offset will apply to the pre-sorted input list Values <0 are ignored and 0 assumed -not Invert the search. Return items which don't match 'list' Typically this will return a well-formed Tcl list -all Return a list of all items matching the search pattern of the first item. Output may be modified by -inline -sort Sort the input list before comparing (non-standard) -sorted Ignored. Ticol does not optimise sorted list searches -increasing Ignored. Used with -sort only - otherwise ignored -decreasing Ignored. Used with sort only - otherwise ignored -ascii Ignored. Ticol is ANSI-only [lsearch] matches the pattern argument to the list to find a match. If no match is found then -1 is returned. Nested lists are not supported. If all matching style options are omitted then the default matching style is -glob. If more than one matching style is specified, the last matching style given takes precedence Sub-list matching is not yet supported Examples: lsearch {ba ze fi eo cu pa le ri} fred # => -1 lsearch {ba ze fi eo cu pa le ri} * # => ba lsearch -inline {ba ze fi eo cu pa le ri} * # => 0 lsearch -not {ba ze fi eo cu pa le ri} * # => -1 lsearch -all -not {ba ze fi eo cu pa le ri} * # => {} lsearch -inline -all -not {ba ze fi eo cu pa le ri} * # => {} lsearch {ba ze fi eo cu pa le ri} ?o # => 3 lsearch -inline {ba ze fi eo cu pa le ri} ?o # => eo lsearch -inline -all {ba ze fi eo cu pa le ri} ?e # => ze le lsearch -inline -glob -all {ba ze fi eo cu pa le ri} ?e # => ze le lsearch -inline -all -not {ba ze fi eo cu pa le ri} ?e # => ba fi eo cu pa ri lsearch -all -not {ba ze fi eo cu pa le ri} ?e # => 0 2 3 4 5 7 lsearch -glob -all -not {ba ze fi eo cu pa le ri} ?e # => 0 2 3 4 5 7 lsearch -exact -nocase {{a b c} {d e f}} {D E F} # => 1 lsearch -exact -nocase {{a b c} {d e f}} {p q r} # => -1 # Not found/-1 lsearch -exact -sorted -inline -start 4 {b z f e c p l r} {p} # => p lsearch -exact -sorted -start 4 {b z f e c p l r} {p} # => 2 lsearch -inline -list -exact\ -not -start 0 {a "Hello there" x y z} {x} # => "a {Hello there} y z" lsearch -exact -inline -all -not {a c b c a b c} c # => a b a b lsearch -exact -all -not {a c b c a b c} c # => 0 2 4 5 lsearch -exact -inline -all {a c b c a b c} c # => c c c lsearch -exact -all {a c b c a b c} c # => 1 3 6 lsearch -exact -all -start 2 {a c b c a b c} c # => 3 6 Note that [lsearch] does not 'eval' it's arguments... lsearch -all -inline {$qbf} * # => $qbf (correct) lsearch -all -inline {list $qbf} * # => list $qbf (correct) lsearch -all -inline "$qbf" * # => quick brown ... lsearch -all -nocase -inline $qbf t* # => The the See also: list, lappend, lindex
lset  Top  
string [lset target-variable source-variable|source-string] A Procrustean command. Inserts a source string or variable into the target, left-aligned. [lset] is based on the common BASIC command Any excess length in the source is stripped to fit. The standard Tcl [lset list] is not yet implemented Example: set s [makestr 20 *] lset s "hello" puts $s Result: hello*************** Example: (Blank out part of a string) set s "0849 666 616" lset s " " puts "'$s'" Result: ' 666 616' See also: cset, rset, mid, strstr, string
lsort  Top  
list [lsort list ?-ascending | -descending? ?-nocase? ?-integer? ?-real?] Sorts a Tcl list in ascending or descending order, optionally ignoring case, comparing as integer, or comparing as a double value lsort does not support -step. -index, -stride etc. Braced list sub-items are supported lsort will perform a simple sort on a list. e.g. foreach x [lsort [array get env]] {puts $x} Example: set ls [lsort { {{d e m o} 34512} {{c o d e} 54321} {{v e r y} 13254} {{b i g} 12345} {} } ] puts "=$ls=" Result: ={{b i g} 12345} {{c o d e} 54321} {{d e m o} 34512} {{v e r y} 13254}= See also: list
makestr  Top  
string [makestr length ?char? ?var?] string [makestr length] string [makestr length char] string [makestr length char var] string [makestr length -- var] Creates and allocated a string of given length, optionally filled with a specified character. If more than one fill character is passed then only the first character of the fill-string will be used. The default fill character is a space. Don't mix [makestr] with [malloc] for standard Tcl variables. Variables created with [makestr] are standard Ticol variables and will be automatically released Literal numeric fill characters will be used if passed: e.g. [makestr 5 0] => "00000" Low and high order ASCII characters may be passed using [chr N] Examples: makestr 5 [chr 0x21] # => "!!!!!" makestr 5 [chr 42] # => "*****" makestr 5 [char 0b101011] # => "+++++" [makestr] does not accept the value [chr 0] Ticol Tcl does not like null (0x0) characters within strings. Use [memset] to zeroise the contents of a Tcl string buffer. If variable is specified and a filler-character omitted then a dummy argument then '--' should be used to skip this argument Example: set buf [makestr 10] puts "-'$buf'-" Result: -' '- Example: makestr 10 -- buf puts "-'$buf'-" Result: -' '- Example: set buf [makestr 1024] # Allocate a string buffer of 1024 spaces memset buf [chr 0] 1024 # Set all characters to [chr 0] See also: chr, asc, memset, calldll
malloc, free  Top  
address [malloc byte-count] free address|variable [malloc] is provides for integration with external DLLs using [calldll] [malloc] allocates memory using the C malloc() function from the heap memory manager. An address to a heap-allocated block of memory is returned This address is freed by a call to [free] using the same address. The address argument or variable value must be > 0 [malloc] and [free] should be used with extreme care and are intended for use only with Ticol structs and for interfacing with [calldll] Don't use [malloc] for standard Tcl variables. Used correctly, [malloc] will be stable and not leak memory. Memory blocks allocated with [malloc] are not automatically freed. You must call [free] on the address returned by [malloc] If [free] is passed the name of a variable then the variable will be reset to "0" on successful free, otherwise you must take care to reset any variables to avoid pointer re-use. Example: set ptr [malloc 10] puts "malloc ptr is $ptr" set source Hello # MUST copy length of string + 1 to copy the NULL char memcpy $ptr [addressofb source] 6 puts "ofaddressb ptr =='[ofaddressb $ptr]'" free $ptr Result: malloc ptr is 33394064 ofaddressb ptr =='Hello' See also: memcpy, memset, calldll
man - Ticol Manual  Top  
The Ticol manual is a simple text file which is formatted using a method which can break the file into easily-accessible sections. Topic markers are phrases which must be prefixed by a dot character and the dot must be the first character on a line The format is as follows --------------------------------------------- .. comment and end of section marker .topic key .another optional topic key .yet another optional key topic title Manual text... ..code <some Tcl code> ..end ..colour <some text ..end ..end (of topic section) --------------------------------------------- Any text following ".." will be ignored See also: ticol
map, string map  Top  
string [map {token-pair-list} variable|string-literal ?-nocase?] string [string map {token-pair-list} variable|string-literal ?-nocase?] Remaps strings using a paired list. The list-pair must have even parity. If a variable is given for the last argument then the variable contents will be reassigned. In either case the remapped string is returned. If there are no valid mappings then the original input string is returned Mapping is expensive on long strings where no multi-char remaps are found and where a large input-map is given Also implemented as [string map] Examples: puts "Result is: [string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc]" puts "Should be: 01321221" puts "Result is: [string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc]" puts "Should be: 02c322c222c" puts "Result is: [string map {1 0 ab 2 a 3 abc 1} frederick]" puts "Should be: frederick" # No valid mapping returns original string set s "1<2 2>1 2≥2 2≤2" puts "Result is: "[string map -nocase { "<" "<" ">" ">" "≤" "<=" "≥" ">=" } $s] puts "Should be: 1<2 2>1 2>=2 2<=2" See also: map, apply, string
max, min (Command form)  Top  
number [max x y ...] number [min x y ...] Return the maxima or minima of two numeric values, either double or integer. String arguments are not accepted. Either a double or integer value is returned, depending on the inputs max() and min() are also available as expression functions. You can also access these in command-style using [funct max x y] and [funct min x y] Example: puts [max 3 7] puts [max 3.0 7.0] puts [max foo bar] # Invalid string literals puts [max $pi $euler] Results: 7 7.000000000000000 0 3.141592653589793 See also: max function, min function, functions, math
mid (Set String Middle)  Top  
integer [mid varName string|variable startpos ?length?] Set the middle of a variable to a portion of a 2nd variable or string literal If the length parameter is omitted then the entire source string will be copied to the target (or as much as will fit) [mid] is not a standard Tcl command Example: set q $qbf puts [mid q cat 17 3] puts $q Results: 3 The quick brown cat jumps over the lazy dog See also: mids, left, right, rset, lset, strstr, string
mids (Return a String Midsection)  Top  
string [mids string start ?length?] string [mids varName start ?length? -var] Return a mid-section of a string 'start' is a base 1 index value. The length argument is optional. If omitted then the entire string from 'start' will be returned If -var is passed as the last argument then the value will be interpreted as a variable name. The variable must exist Use [index <string> n] instead of [mids <string> n 1] [mids] is not a standard Tcl command Example: if {eq [mids $data $i 2] "/*" } { incr i 2 set in_comment $true } Example: puts [mids "hello world" 7] Result: world Example: puts [mids "hello world" 2 4] Result: ello Example: set s "Hello" puts [mids $s 3 2] Result: ll See also: mid, left, right, cset, rset, lset, strstr, string, index, lastchar, strto, strtor
mkdir  Top  
bool [mkdir path] bool [md path] Create a single directory (folder) Example: mkdir foldername See: [mkdirs] to create a series of folder names in one command See also: unlink, file, ls
mkdirs  Top  
bool [mkdirs path] Create a series of directories (folders) [mkdirs] is not a standard Tcl command Example: mkdirs \\one\two\\three See: [mkdir] to create a single folder See also: unlink, file, ls
md5  Top  
string [md5 string|var ?-var?] Return the 32-character MD5 value of a string [md5] is not a standard Tcl command The -var option is binary-compatible Example: puts [md5 $qbf] puts [md5 qbf -var] Result: 9e107d9d372bb6826bd81d3542a419d6 9e107d9d372bb6826bd81d3542a419d6 Example: MD5 hash-based random number generator set seed $pi # Could instead use [clock] set counter 0 # Global/static counter option expression on # Use [expr] for flow-control proc hashrnd {lo hi} { # Hash-generated random number upvar seed # Not recursive. No level given upvar counter incr counter set r [md5 [+ $counter $seed]] # Get an MD5 value set q "0x" # Literal 0x prefix append q [mids r [% $counter 24] 8] # Slice a section of the MD5 return [expr "$q % (($hi-$lo)+1)+$lo"] # Evaluate as hexadecimal } option expression on for {set i 0} { $i < 10000} {incr i} { puts "hashrnd 10..10000:\t[hashrnd 10 10000]" } See also: md5 batch example, md5_file, protection, MD5 Verification, upvar, append
MD5 Batch Example  Top  
This is a simple batch file which will run a Ticol script depending on a successful MD5 check. You will need to know the MD5 signature in advance and if the signature changed then you would need to update the script @echo OFF set FILE=hello.tcx set MD5=C7A37A87B4E6B7D311C0BF430844B94A for /F "tokens=*" %%i in ('ticol.exe /md5 %FILE%') do ( set RESULT=%%i ) rem echo DEBUG: MD5 result is: %RESULT% if /I %MD5% equ %RESULT% ( hello.tcx ) else ( echo MD5 failure. Cannot execute %FILE% echo MD5 is: ticol.exe /md5:%FILE% /crlf echo Should be: echo %MD5% ) See also: md5
md5_file  Top  
string [md5_file filename] Return a 32-bit MD5 hex-value for a given filename. Performance is reasonable even on large ISO images. This should match the MD5 of any external MD5 EXE program Example: puts [md5_file ticol.exe] Result: 82bef32153657dc25dc439a3b500a614 See also: md5, protection, MD5 Verification
MD5 Verification  Top  
The following skeleton batch file may be used to generate a mechanism to test encrypted Ticol TCX files before execution. This method requires that the MD5 value be entered into the batch script ---------------------------------------------------------- @ECHO OFF SET FILE=hello.tcx FOR /F "tokens=*" %%i in ('ticol.exe /md5 %FILE%') DO ( SET RESULT=%%i ) REM ECHO DEBUG: MD5 result is: %RESULT% IF /I 314ebb9f13a413ab4419fc9d5691011d EQU %RESULT% ( ticol.exe hello.tcx ) ELSE ( ECHO MD5 failure. Cannot execute %FILE% ) ---------------------------------------------------------- See also: md5, md5_file, security issues
mean  Top  
double [mean value ?value? ...] Calculate the arithmetic mean of a series of values and return the result as a floating point value. Individual values and the total are evaluated as floating point doubles with a double return (double 64 bit signed 1.7E +/- 308 (15 digits of precision)) Example: puts [mean 1.2 19.8 22.7 4343 40.5 19.4 222] Result: 666.942857142857060 [mean] is not a standard Tcl command See also: math functions, big mean
mem_used  Top  
integer [mem_used ?pid?] Show the memory used by the current Ticol process or any other process in bytes This will be the same amount of memory as displayed in Task manager for "mem usage". This can be used to track application memory use for fault- finding etc. There should be initial memory allocation as routines are set-up, but this should not continually increase. The underlying memory- manager may also fluctuate but the usage trend should remain broadly stable Error returns: On error mem_used returns a negative value indicating one of the following: -1 Can't load PSPAPI.DLL -2 Can't get procaddress for "GetProcessMemoryInfo" -3 Can't open given Process ID (usually insufficient permissions) Example: set memstart [mem_used] set last 0 set this 0 set iters 0 while {1} { # command to check ######################## some-valid-tcl-function ########################################### set this [mem_used] if {!= $last $this} { # Next line ends with a line-continuation character... puts "Leaked [/ [- $this $memstart] 1024] Kb\tTotal used: \ [comma [/ $this 1024]] Kb\t$iters iteration(s)" } set last $this incr iters } [mem_used] is not a standard Tcl command See also: Ticol, debugging
memcpy  Top  
memcpy target-address source-address byte-count ?-t? [memcpy] calls the standard "C" memcpy() routine to copy a block of memory from one location to another. [memcpy] can take a dereferenced struct member name as the target, or an address of a block of memory allocated by [malloc]. The copied block may not be null-terminated and therefore may not be safely printable. [memcpy], [malloc] and [free] should be used with extreme care and are intended for use only with Ticol structs and for interfacing with [calldll] [addressofb] can be used to return the binary/byte address of the allocated buffer in a Ticol variable (similar to StrPtr() in Visual BASIC) [ofaddresb] is used to dereference a Ticol variable which stores a memory address Example: set ptr [malloc 10] puts "malloc ptr is $ptr" set source Hello memcpy $ptr [addressofb source] 6 # MUST copy length of string + 1 to copy the NULL char puts "ofaddressb ptr =='[ofaddressb $ptr]'" free $ptr Result: malloc ptr is 33394064 ofaddressb ptr =='Hello' If the -t argument is used then a null terminator will be substituted for the last byte copied. Thus x1 byte of the source is discarded Example: set a [malloc 256] # Allocate a large buffer set s "hello" # Set a standard Tcl variable memcpy $a [addressofb s] 5 -t # Copy 5 bytes. Make the last byte NULL puts "a is '[ofaddressb $a]'" # Print the binary data at address a Result: a is 'hell' [memcpy] is not a standard Tcl command and should be used with extreme care See also: malloc, free, memset
memset  Top  
memset varName characterNumber length [memset] may be used to format or zeroise buffers such as those created using [makestr] when interfacing with external DLLs using calldll* [set] will copy only the usable part of a string, not the full, allocated buffer size. Thus using [set] with [makestr] and [chr 0] could create an under-sized target buffer string and cause instability with [calldll] [memset] will clear memory only up to the allocated length of the string it will not clear/set the internal/terminating null character of any string It is allowable to call memset with a calculated address offset Avoid using memset with Tcl variables other than those used via calldll* Example: set buf [makestr 1024 " "] # Creates a buffer of 1024 spaces memset buf 0 1024 puts "'$buf'" Result '' # Buffer has been allocated to 1024 chars but set to [chr 0] Example: set ptr [malloc 200] # [malloc] returns an address memset $ptr x 10 # Write 10 char "x" memset [+ $ptr 5] "q" 2 # Write "qq" to offset ptr + 5 puts "Address is: $ptr" puts "Contents: '[ofaddressb $ptr]'" Result: Address is: 34791712 Contents: 'xxxxxqqxxx' [memset] is not a standard Tcl command and should be used with extreme care See also: calldll, malloc, free, memcpy, makestr
Troubleshooting and Common Mistakes  Top  
Here are some of the most common mistakes when first using Tcl. Particularly when coming from a C/C++ background: Very Long Strings in Notepad++ ------------------------------ It has been noticed that NPP may automatically wrap and insert CRLFs into very long strings, e.g. very large numbers of say 1000+ digits The solution to this is to break the string into smaller pieces, wrap in double quotes and use line-continuation backslash characters at the end of each intermediate line Example: assert [big fact 200] {== $_ "7886578673647905035523632139321850622951\ 3597768717326329474253324435944996340334292030428401198462390417721213\ 8919638830257642790242637105061926624952829931113462857270763317237396\ 9889439224456214516642402540332918641312274282948532775242424075739032\ 4032125740557956866022603190417032406235170085879617892222278962370389\ 7374720000000000000000000000000000000000000000000000000"} -v Using [unset] instead of [undef] -------------------------------- Intending to clear a proc (e.g. foo) but using 'unset foo' where 'undef foo' is required, or indending to clear var foo using 'undef foo' where 'unset foo' is required Failure to Use [option expression off] -------------------------------------- When using non-expression (Tcl command format) arguments to flow-control The preference can be set up in ticol.ini Using 'VB' Style Variable Syntax -------------------------------- Using var$ instead of $var. Tcl requires the latter Example: set i 0 for {[> i$ 10]} { ... # Wrong set i 0 for {[> $i 10]} { ... # Correct Failure to Use [upvar] for [proc] Arguments ------------------------------------------- When passing by name (by reference) rather than by value, you must use [upvar] to create a reference to the variable. If a [proc] is called by another [proc] then [upvar] giving no level reference is sufficient as each [proc] call is one level higher than the next. Example: proc foo x { # Wrong. Variable x won't be referenced return [* $x 1] } proc foo x { # Correct upvar x # [upvar] creates a linkage to the source var return [* $x 1] } proc foo x { # Correct (using an alternate local variable) upvar x y # $y is an alias for $x return [* $y 1] } Variable Name Clash Within Procedures when Using [upvar] -------------------------------------------------------- Consider the following proc which will pass its argument by name (reference) proc foo {a} { # Variable 'a' is created in [proc] scope upvar $a # Attempts to declare a second local var 'a' puts $a } set a Hello foo a # Calling with 'a' means [proc]->'a' resolves to 'a' An error will result, pointing out that variable 'a' already exists in the current scope This occurs because we passed the name 'a' via argument 'a' which then resolves to 'a' when dereferenced upvar: 'a' already exists at level 1 (check proc args) which it does, since it was passed via the proc body. Because you can't be sure what variable name will be passed into the proc later on you must avoid such clashes where the inbound name is the same as the local one You must either explicitly declare the local variable in the [upvar] statement, e.g. in this case: upvar $a b or 'mangle' the names using underscores e.g. proc foo {_a} { upvar $_a a # Declares a local var 'a' puts $a } Alternatively, just ensure the variable names for the local reference are different from the arguments when calling by name proc foo {a} { upvar $a b # Declares a local var 'b' puts $b } Failure to clear/delete variables or procs ------------------------------------------ A conflicting proc or variable exists somewhere else in the code, possibly within an external file. It is good practise to clear procs and variables as soon as you have finished within them, particularly when working in the global (root) scope. This can be done safely using: undef procname -nocomplain unset variablename -nocomplain [clear] will clear all locally created variables A useful shortcut scriptlet is as follows: This will remove all single letter variables 'a' to 'z'. The {*} will cause each list element to be passed to [unset] as a separate argument: unset {*}[split [range a-z]] -nocomplain Failure to Evaluate [proc] Returns ---------------------------------- Example: return * $i $i Should be: return [* $i $i] Reason: [*] is a command which must be evaluated. The first example, instead, supplied 3 invalid arguments to the [return] command. i.e. [return * $i $i]. Square brackets cause an advance recursive evaluation, thus, if i was set to 3 then [return [* $i $i]] would be interpreted as [return 9] Using [static] where [set] is required ---------------------------------------- # In root-level scope static foo 23 assert $foo {== $_ 23} -v # PASS static foo 11 assert $foo {== $_ 11} -v # FAIL set foo 11 assert $foo {== $_ 11} -v # PASS Incorrect Options Setting with [for] etc. ---------------------------------------- Example: variable not found after [for] loop initiation Should be: for {[set i 0]} ... or option expression off for {set i 0} ... or: TICOL.INI -> ForInitAllowsExpression=FALSE for {set i 0} ... Reason: Standard Tcl forces the first (initiator) statement of a [for] loop to be a Tcl command (via [eval]). Ticol Tcl allows the first command to be an expression if configured in TICOL.INI using: ForInitAllowsExpression=<boolean> Incorrect [option expression] Setting ------------------------------------- Example: option expression on if {file exists test.tcl} { ... } Should be: if {[file exists test_enum.tcx]} { or option expression off if {file exists test.tcl} { ... } Reason: If option expression is on, either by command or INI config file, then the arguments to flow-control commands such as [if], [for] etc. will be interpreted as math expressions. If this is the case any command must be evaluate (called) by wrapping in square brackets. -- Example: option expression off for {set i 0} {$i < 10} {incr i} { ...} Should be: option expression off for {set i 0} {< $i 10} {incr i} { ...} or: option expression on for {[set i 0]} {< $i 10} {incr i} { ...} Reason: With option expression off, arguments to flow-control commands such as [for], [while] etc. will not be evaluated in "expression format" but in [eval] format. The command expression in the first argument will have no effect With 'option expression on' '{set i 0}' is not a valid expression Misplaced End of Line Brace Characters -------------------------------------- C/C++ and C# programmers may inadvertently assume that the following brace style can be used with Tcl. It cannot. Opening braces mark delayed expansion wrappers for commands. CRLFs are valid within delayed brace wrappers but not within argument tails outside curly braces Example: (wrong - opening brace must be on same line) if {== $i 10} { puts "i is 10" } else { puts "i is not 10" } Should be: (correct - opening brace on same line) if {== $i 10} { puts "i is 10" } else { puts "i is not 10" } or if {== $i 10} {puts "i is 10"} else {puts "i is not 10"} Reason. The first expression is "C++"-like but illegal. The CRLF marks the termination of the command [for] and it is prematurely truncated Failure to Separate Commands by Whitespace ------------------------------------------ Example: option expression on for{set i 0}{$i < 10}{incr i}{ ...} Should be: option expression on for {set i 0} {$i < 10} {incr i} { ...} Reason: Tcl is a discrete, command-based language. Spaces are required between commands and grouped arguments (those wrapped in braces) Failure to Protect Strings With Double Quotes --------------------------------------------- Strings need not be wrapped in double-quotes but failure to do so leaves a path open for frustrating errors. e.g. puts [ftp $hostname ls /tools/* -u admin -p xxxxx] Should be: puts "[ftp $hostname ls /tools/*.zip -u admin -p xxxxx]" Since the unquoted '/*' in '/*.zip' will be interpreted as a long comment start. Quoting will prevent this. Misplaced Double Quotes ----------------------- If an extra, unescaped double quote is embedded in a properly quoted string then this error may be issued: "Premature end preprocessing source file" Possibly with a preprocessor line number. Work backwards from the line number to check for strings with embedded/unescaped double quotes Incorrect Delimiting of Command Arguments ----------------------------------------- Bad example: puts The quick brown fox jumps over the lazy dog Should be: puts "The quick brown fox jumps over the lazy dog" or: puts {The quick brown fox jumps over the lazy dog} or: puts Thequickbrownfoxjumpsoverthelazydog Reason: Arguments to Tcl commands such as [puts] must be either wrapped in double- quotes (where appropriate) or grouped using curly-braces. The first example instead supplies 9 independent and invalid arguments to [puts]. Arguments are also implicitly grouped if there is no intervening whitespace, thus an argument which contains no whitespace need neither be braced or quoted Using [else if] Instead of [elseif] ----------------------------------- Example: (wrong) if {[rnd 0 1]} { puts "True" } else if {[==