2e0d49537d
git-svn-id: file:///root/webif/svn/humax/pkg/src/webif/trunk@686 2a923420-c742-0410-a762-8d5b09965624
8071 lines
325 KiB
HTML
8071 lines
325 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
|
|
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
|
|
<meta name="generator" content="AsciiDoc 8.6.5" />
|
|
<title>Jim Tcl(n)</title>
|
|
<style type="text/css">
|
|
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
|
|
|
|
/* Default font. */
|
|
body {
|
|
font-family: Georgia,serif;
|
|
}
|
|
|
|
/* Title font. */
|
|
h1, h2, h3, h4, h5, h6,
|
|
div.title, caption.title,
|
|
thead, p.table.header,
|
|
#toctitle,
|
|
#author, #revnumber, #revdate, #revremark,
|
|
#footer {
|
|
font-family: Arial,Helvetica,sans-serif;
|
|
}
|
|
|
|
body {
|
|
margin: 1em 5% 1em 5%;
|
|
}
|
|
|
|
a {
|
|
color: blue;
|
|
text-decoration: underline;
|
|
}
|
|
a:visited {
|
|
color: fuchsia;
|
|
}
|
|
|
|
em {
|
|
font-style: italic;
|
|
color: navy;
|
|
}
|
|
|
|
strong {
|
|
font-weight: bold;
|
|
color: #083194;
|
|
}
|
|
|
|
h1, h2, h3, h4, h5, h6 {
|
|
color: #527bbd;
|
|
margin-top: 1.2em;
|
|
margin-bottom: 0.5em;
|
|
line-height: 1.3;
|
|
}
|
|
|
|
h1, h2, h3 {
|
|
border-bottom: 2px solid silver;
|
|
}
|
|
h2 {
|
|
padding-top: 0.5em;
|
|
}
|
|
h3 {
|
|
float: left;
|
|
}
|
|
h3 + * {
|
|
clear: left;
|
|
}
|
|
h5 {
|
|
font-size: 1.0em;
|
|
}
|
|
|
|
div.sectionbody {
|
|
margin-left: 0;
|
|
}
|
|
|
|
hr {
|
|
border: 1px solid silver;
|
|
}
|
|
|
|
p {
|
|
margin-top: 0.5em;
|
|
margin-bottom: 0.5em;
|
|
}
|
|
|
|
ul, ol, li > p {
|
|
margin-top: 0;
|
|
}
|
|
ul > li { color: #aaa; }
|
|
ul > li > * { color: black; }
|
|
|
|
pre {
|
|
padding: 0;
|
|
margin: 0;
|
|
}
|
|
|
|
#author {
|
|
color: #527bbd;
|
|
font-weight: bold;
|
|
font-size: 1.1em;
|
|
}
|
|
#email {
|
|
}
|
|
#revnumber, #revdate, #revremark {
|
|
}
|
|
|
|
#footer {
|
|
font-size: small;
|
|
border-top: 2px solid silver;
|
|
padding-top: 0.5em;
|
|
margin-top: 4.0em;
|
|
}
|
|
#footer-text {
|
|
float: left;
|
|
padding-bottom: 0.5em;
|
|
}
|
|
#footer-badges {
|
|
float: right;
|
|
padding-bottom: 0.5em;
|
|
}
|
|
|
|
#preamble {
|
|
margin-top: 1.5em;
|
|
margin-bottom: 1.5em;
|
|
}
|
|
div.imageblock, div.exampleblock, div.verseblock,
|
|
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
|
|
div.admonitionblock {
|
|
margin-top: 1.0em;
|
|
margin-bottom: 1.5em;
|
|
}
|
|
div.admonitionblock {
|
|
margin-top: 2.0em;
|
|
margin-bottom: 2.0em;
|
|
margin-right: 10%;
|
|
color: #606060;
|
|
}
|
|
|
|
div.content { /* Block element content. */
|
|
padding: 0;
|
|
}
|
|
|
|
/* Block element titles. */
|
|
div.title, caption.title {
|
|
color: #527bbd;
|
|
font-weight: bold;
|
|
text-align: left;
|
|
margin-top: 1.0em;
|
|
margin-bottom: 0.5em;
|
|
}
|
|
div.title + * {
|
|
margin-top: 0;
|
|
}
|
|
|
|
td div.title:first-child {
|
|
margin-top: 0.0em;
|
|
}
|
|
div.content div.title:first-child {
|
|
margin-top: 0.0em;
|
|
}
|
|
div.content + div.title {
|
|
margin-top: 0.0em;
|
|
}
|
|
|
|
div.sidebarblock > div.content {
|
|
background: #ffffee;
|
|
border: 1px solid #dddddd;
|
|
border-left: 4px solid #f0f0f0;
|
|
padding: 0.5em;
|
|
}
|
|
|
|
div.listingblock > div.content {
|
|
border: 1px solid #dddddd;
|
|
border-left: 5px solid #f0f0f0;
|
|
background: #f8f8f8;
|
|
padding: 0.5em;
|
|
}
|
|
|
|
div.quoteblock, div.verseblock {
|
|
padding-left: 1.0em;
|
|
margin-left: 1.0em;
|
|
margin-right: 10%;
|
|
border-left: 5px solid #f0f0f0;
|
|
color: #777777;
|
|
}
|
|
|
|
div.quoteblock > div.attribution {
|
|
padding-top: 0.5em;
|
|
text-align: right;
|
|
}
|
|
|
|
div.verseblock > pre.content {
|
|
font-family: inherit;
|
|
font-size: inherit;
|
|
}
|
|
div.verseblock > div.attribution {
|
|
padding-top: 0.75em;
|
|
text-align: left;
|
|
}
|
|
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
|
|
div.verseblock + div.attribution {
|
|
text-align: left;
|
|
}
|
|
|
|
div.admonitionblock .icon {
|
|
vertical-align: top;
|
|
font-size: 1.1em;
|
|
font-weight: bold;
|
|
text-decoration: underline;
|
|
color: #527bbd;
|
|
padding-right: 0.5em;
|
|
}
|
|
div.admonitionblock td.content {
|
|
padding-left: 0.5em;
|
|
border-left: 3px solid #dddddd;
|
|
}
|
|
|
|
div.exampleblock > div.content {
|
|
border-left: 3px solid #dddddd;
|
|
padding-left: 0.5em;
|
|
}
|
|
|
|
div.imageblock div.content { padding-left: 0; }
|
|
span.image img { border-style: none; }
|
|
a.image:visited { color: white; }
|
|
|
|
dl {
|
|
margin-top: 0.8em;
|
|
margin-bottom: 0.8em;
|
|
}
|
|
dt {
|
|
margin-top: 0.5em;
|
|
margin-bottom: 0;
|
|
font-style: normal;
|
|
color: navy;
|
|
}
|
|
dd > *:first-child {
|
|
margin-top: 0.1em;
|
|
}
|
|
|
|
ul, ol {
|
|
list-style-position: outside;
|
|
}
|
|
ol.arabic {
|
|
list-style-type: decimal;
|
|
}
|
|
ol.loweralpha {
|
|
list-style-type: lower-alpha;
|
|
}
|
|
ol.upperalpha {
|
|
list-style-type: upper-alpha;
|
|
}
|
|
ol.lowerroman {
|
|
list-style-type: lower-roman;
|
|
}
|
|
ol.upperroman {
|
|
list-style-type: upper-roman;
|
|
}
|
|
|
|
div.compact ul, div.compact ol,
|
|
div.compact p, div.compact p,
|
|
div.compact div, div.compact div {
|
|
margin-top: 0.1em;
|
|
margin-bottom: 0.1em;
|
|
}
|
|
|
|
tfoot {
|
|
font-weight: bold;
|
|
}
|
|
td > div.verse {
|
|
white-space: pre;
|
|
}
|
|
|
|
div.hdlist {
|
|
margin-top: 0.8em;
|
|
margin-bottom: 0.8em;
|
|
}
|
|
div.hdlist tr {
|
|
padding-bottom: 15px;
|
|
}
|
|
dt.hdlist1.strong, td.hdlist1.strong {
|
|
font-weight: bold;
|
|
}
|
|
td.hdlist1 {
|
|
vertical-align: top;
|
|
font-style: normal;
|
|
padding-right: 0.8em;
|
|
color: navy;
|
|
}
|
|
td.hdlist2 {
|
|
vertical-align: top;
|
|
}
|
|
div.hdlist.compact tr {
|
|
margin: 0;
|
|
padding-bottom: 0;
|
|
}
|
|
|
|
.comment {
|
|
background: yellow;
|
|
}
|
|
|
|
.footnote, .footnoteref {
|
|
font-size: 0.8em;
|
|
}
|
|
|
|
span.footnote, span.footnoteref {
|
|
vertical-align: super;
|
|
}
|
|
|
|
#footnotes {
|
|
margin: 20px 0 20px 0;
|
|
padding: 7px 0 0 0;
|
|
}
|
|
|
|
#footnotes div.footnote {
|
|
margin: 0 0 5px 0;
|
|
}
|
|
|
|
#footnotes hr {
|
|
border: none;
|
|
border-top: 1px solid silver;
|
|
height: 1px;
|
|
text-align: left;
|
|
margin-left: 0;
|
|
width: 20%;
|
|
min-width: 100px;
|
|
}
|
|
|
|
div.colist td {
|
|
padding-right: 0.5em;
|
|
padding-bottom: 0.3em;
|
|
vertical-align: top;
|
|
}
|
|
div.colist td img {
|
|
margin-top: 0.3em;
|
|
}
|
|
|
|
@media print {
|
|
#footer-badges { display: none; }
|
|
}
|
|
|
|
#toc {
|
|
margin-bottom: 2.5em;
|
|
}
|
|
|
|
#toctitle {
|
|
color: #527bbd;
|
|
font-size: 1.1em;
|
|
font-weight: bold;
|
|
margin-top: 1.0em;
|
|
margin-bottom: 0.1em;
|
|
}
|
|
|
|
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
|
|
margin-top: 0;
|
|
margin-bottom: 0;
|
|
}
|
|
div.toclevel2 {
|
|
margin-left: 2em;
|
|
font-size: 0.9em;
|
|
}
|
|
div.toclevel3 {
|
|
margin-left: 4em;
|
|
font-size: 0.9em;
|
|
}
|
|
div.toclevel4 {
|
|
margin-left: 6em;
|
|
font-size: 0.9em;
|
|
}
|
|
|
|
span.aqua { color: aqua; }
|
|
span.black { color: black; }
|
|
span.blue { color: blue; }
|
|
span.fuchsia { color: fuchsia; }
|
|
span.gray { color: gray; }
|
|
span.green { color: green; }
|
|
span.lime { color: lime; }
|
|
span.maroon { color: maroon; }
|
|
span.navy { color: navy; }
|
|
span.olive { color: olive; }
|
|
span.purple { color: purple; }
|
|
span.red { color: red; }
|
|
span.silver { color: silver; }
|
|
span.teal { color: teal; }
|
|
span.white { color: white; }
|
|
span.yellow { color: yellow; }
|
|
|
|
span.aqua-background { background: aqua; }
|
|
span.black-background { background: black; }
|
|
span.blue-background { background: blue; }
|
|
span.fuchsia-background { background: fuchsia; }
|
|
span.gray-background { background: gray; }
|
|
span.green-background { background: green; }
|
|
span.lime-background { background: lime; }
|
|
span.maroon-background { background: maroon; }
|
|
span.navy-background { background: navy; }
|
|
span.olive-background { background: olive; }
|
|
span.purple-background { background: purple; }
|
|
span.red-background { background: red; }
|
|
span.silver-background { background: silver; }
|
|
span.teal-background { background: teal; }
|
|
span.white-background { background: white; }
|
|
span.yellow-background { background: yellow; }
|
|
|
|
span.big { font-size: 2em; }
|
|
span.small { font-size: 0.6em; }
|
|
|
|
span.underline { text-decoration: underline; }
|
|
span.overline { text-decoration: overline; }
|
|
span.line-through { text-decoration: line-through; }
|
|
|
|
|
|
/*
|
|
* xhtml11 specific
|
|
*
|
|
* */
|
|
|
|
tt {
|
|
font-family: monospace;
|
|
font-size: inherit;
|
|
color: navy;
|
|
}
|
|
|
|
div.tableblock {
|
|
margin-top: 1.0em;
|
|
margin-bottom: 1.5em;
|
|
}
|
|
div.tableblock > table {
|
|
border: 3px solid #527bbd;
|
|
}
|
|
thead, p.table.header {
|
|
font-weight: bold;
|
|
color: #527bbd;
|
|
}
|
|
p.table {
|
|
margin-top: 0;
|
|
}
|
|
/* Because the table frame attribute is overriden by CSS in most browsers. */
|
|
div.tableblock > table[frame="void"] {
|
|
border-style: none;
|
|
}
|
|
div.tableblock > table[frame="hsides"] {
|
|
border-left-style: none;
|
|
border-right-style: none;
|
|
}
|
|
div.tableblock > table[frame="vsides"] {
|
|
border-top-style: none;
|
|
border-bottom-style: none;
|
|
}
|
|
|
|
|
|
/*
|
|
* html5 specific
|
|
*
|
|
* */
|
|
|
|
.monospaced {
|
|
font-family: monospace;
|
|
font-size: inherit;
|
|
color: navy;
|
|
}
|
|
|
|
table.tableblock {
|
|
margin-top: 1.0em;
|
|
margin-bottom: 1.5em;
|
|
}
|
|
thead, p.tableblock.header {
|
|
font-weight: bold;
|
|
color: #527bbd;
|
|
}
|
|
p.tableblock {
|
|
margin-top: 0;
|
|
}
|
|
table.tableblock {
|
|
border-width: 3px;
|
|
border-spacing: 0px;
|
|
border-style: solid;
|
|
border-color: #527bbd;
|
|
border-collapse: collapse;
|
|
}
|
|
th.tableblock, td.tableblock {
|
|
border-width: 1px;
|
|
padding: 4px;
|
|
border-style: solid;
|
|
border-color: #527bbd;
|
|
}
|
|
|
|
table.tableblock.frame-topbot {
|
|
border-left-style: hidden;
|
|
border-right-style: hidden;
|
|
}
|
|
table.tableblock.frame-sides {
|
|
border-top-style: hidden;
|
|
border-bottom-style: hidden;
|
|
}
|
|
table.tableblock.frame-none {
|
|
border-style: hidden;
|
|
}
|
|
|
|
th.tableblock.halign-left, td.tableblock.halign-left {
|
|
text-align: left;
|
|
}
|
|
th.tableblock.halign-center, td.tableblock.halign-center {
|
|
text-align: center;
|
|
}
|
|
th.tableblock.halign-right, td.tableblock.halign-right {
|
|
text-align: right;
|
|
}
|
|
|
|
th.tableblock.valign-top, td.tableblock.valign-top {
|
|
vertical-align: top;
|
|
}
|
|
th.tableblock.valign-middle, td.tableblock.valign-middle {
|
|
vertical-align: middle;
|
|
}
|
|
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
|
|
vertical-align: bottom;
|
|
}
|
|
/* Overrides for manpage documents */
|
|
h1 {
|
|
padding-top: 0.5em;
|
|
padding-bottom: 0.5em;
|
|
border-top: 2px solid silver;
|
|
border-bottom: 2px solid silver;
|
|
}
|
|
h2 {
|
|
border-style: none;
|
|
}
|
|
div.sectionbody {
|
|
margin-left: 3em;
|
|
}
|
|
|
|
@media print {
|
|
div#toc { display: none; }
|
|
}
|
|
|
|
</style>
|
|
<script type="text/javascript">
|
|
/*<+'])');
|
|
// Function that scans the DOM tree for header elements (the DOM2
|
|
// nodeIterator API would be a better technique but not supported by all
|
|
// browsers).
|
|
var iterate = function (el) {
|
|
for (var i = el.firstChild; i != null; i = i.nextSibling) {
|
|
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
|
|
var mo = re.exec(i.tagName);
|
|
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
|
|
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
|
|
}
|
|
iterate(i);
|
|
}
|
|
}
|
|
}
|
|
iterate(el);
|
|
return result;
|
|
}
|
|
|
|
var toc = document.getElementById("toc");
|
|
if (!toc) {
|
|
return;
|
|
}
|
|
|
|
// Delete existing TOC entries in case we're reloading the TOC.
|
|
var tocEntriesToRemove = [];
|
|
var i;
|
|
for (i = 0; i < toc.childNodes.length; i++) {
|
|
var entry = toc.childNodes[i];
|
|
if (entry.nodeName == 'DIV'
|
|
&& entry.getAttribute("class")
|
|
&& entry.getAttribute("class").match(/^toclevel/))
|
|
tocEntriesToRemove.push(entry);
|
|
}
|
|
for (i = 0; i < tocEntriesToRemove.length; i++) {
|
|
toc.removeChild(tocEntriesToRemove[i]);
|
|
}
|
|
|
|
// Rebuild TOC entries.
|
|
var entries = tocEntries(document.getElementById("content"), toclevels);
|
|
for (var i = 0; i < entries.length; ++i) {
|
|
var entry = entries[i];
|
|
if (entry.element.id == "")
|
|
entry.element.id = "_toc_" + i;
|
|
var a = document.createElement("a");
|
|
a.href = "#" + entry.element.id;
|
|
a.appendChild(document.createTextNode(entry.text));
|
|
var div = document.createElement("div");
|
|
div.appendChild(a);
|
|
div.className = "toclevel" + entry.toclevel;
|
|
toc.appendChild(div);
|
|
}
|
|
if (entries.length == 0)
|
|
toc.parentNode.removeChild(toc);
|
|
},
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
// Footnotes generator
|
|
/////////////////////////////////////////////////////////////////////
|
|
|
|
/* Based on footnote generation code from:
|
|
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
|
|
*/
|
|
|
|
footnotes: function () {
|
|
// Delete existing footnote entries in case we're reloading the footnodes.
|
|
var i;
|
|
var noteholder = document.getElementById("footnotes");
|
|
if (!noteholder) {
|
|
return;
|
|
}
|
|
var entriesToRemove = [];
|
|
for (i = 0; i < noteholder.childNodes.length; i++) {
|
|
var entry = noteholder.childNodes[i];
|
|
if (entry.nodeName == 'DIV' && entry.getAttribute("class") == "footnote")
|
|
entriesToRemove.push(entry);
|
|
}
|
|
for (i = 0; i < entriesToRemove.length; i++) {
|
|
noteholder.removeChild(entriesToRemove[i]);
|
|
}
|
|
|
|
// Rebuild footnote entries.
|
|
var cont = document.getElementById("content");
|
|
var spans = cont.getElementsByTagName("span");
|
|
var refs = {};
|
|
var n = 0;
|
|
for (i=0; i<spans.length; i++) {
|
|
if (spans[i].className == "footnote") {
|
|
n++;
|
|
var note = spans[i].getAttribute("data-note");
|
|
if (!note) {
|
|
// Use [\s\S] in place of . so multi-line matches work.
|
|
// Because JavaScript has no s (dotall) regex flag.
|
|
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
|
|
spans[i].innerHTML =
|
|
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
|
|
"' title='View footnote' class='footnote'>" + n + "</a>]";
|
|
spans[i].setAttribute("data-note", note);
|
|
}
|
|
noteholder.innerHTML +=
|
|
"<div class='footnote' id='_footnote_" + n + "'>" +
|
|
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
|
|
n + "</a>. " + note + "</div>";
|
|
var id =spans[i].getAttribute("id");
|
|
if (id != null) refs["#"+id] = n;
|
|
}
|
|
}
|
|
if (n == 0)
|
|
noteholder.parentNode.removeChild(noteholder);
|
|
else {
|
|
// Process footnoterefs.
|
|
for (i=0; i<spans.length; i++) {
|
|
if (spans[i].className == "footnoteref") {
|
|
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
|
|
href = href.match(/#.*/)[0]; // Because IE return full URL.
|
|
n = refs[href];
|
|
spans[i].innerHTML =
|
|
"[<a href='#_footnote_" + n +
|
|
"' title='View footnote' class='footnote'>" + n + "</a>]";
|
|
}
|
|
}
|
|
}
|
|
},
|
|
|
|
install: function(toclevels) {
|
|
var timerId;
|
|
|
|
function reinstall() {
|
|
asciidoc.footnotes();
|
|
if (toclevels) {
|
|
asciidoc.toc(toclevels);
|
|
}
|
|
}
|
|
|
|
function reinstallAndRemoveTimer() {
|
|
clearInterval(timerId);
|
|
reinstall();
|
|
}
|
|
|
|
timerId = setInterval(reinstall, 500);
|
|
if (document.addEventListener)
|
|
document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
|
|
else
|
|
window.onload = reinstallAndRemoveTimer;
|
|
}
|
|
|
|
}
|
|
asciidoc.install();
|
|
/*]]>*/
|
|
</script>
|
|
</head>
|
|
<body class="manpage">
|
|
<div id="header">
|
|
<h1>
|
|
Jim Tcl(n) Manual Page
|
|
</h1>
|
|
<h2>NAME</h2>
|
|
<div class="sectionbody">
|
|
<p>Jim Tcl v0.73 -
|
|
reference manual for the Jim Tcl scripting language
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="content">
|
|
<div class="sect1">
|
|
<h2 id="_synopsis">SYNOPSIS</h2>
|
|
<div class="sectionbody">
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>cc <source> -ljim</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>or</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jimsh [<scriptfile>]
|
|
jimsh -e '<immediate-script>'
|
|
jimsh --version</tt></pre>
|
|
</div></div>
|
|
<div class="ulist"><div class="title">Quick Index</div><ul>
|
|
<li>
|
|
<p>
|
|
<a href="#CommandIndex">Command Reference</a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#OperatorPrecedence">Operator Precedence</a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#BuiltinVariables">Builtin Variables</a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#BackslashSequences">Backslash Sequences</a>
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_introduction">INTRODUCTION</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Jim Tcl is a small footprint reimplementation of the Tcl scripting language.
|
|
The core language engine is compatible with Tcl 8.5+, while implementing
|
|
a significant subset of the Tcl 8.6 command set, plus additional features
|
|
available only in Jim Tcl.</p></div>
|
|
<div class="paragraph"><p>Some notable differences with Tcl 8.5/8.6 are:</p></div>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Object-based I/O (aio), but with a Tcl-compatibility layer
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Integers are 64bit
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for references (<a href="#_ref"><strong><tt>ref</tt></strong></a>/<a href="#_getref"><strong><tt>getref</tt></strong></a>/<a href="#_setref"><strong><tt>setref</tt></strong></a>) and garbage collection
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Builtin dictionary type (<a href="#_dict"><strong><tt>dict</tt></strong></a>) with some limitations compared to Tcl 8.6
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_env"><strong><tt>env</tt></strong></a> command to access environment variables
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Operating system features: <a href="#cmd_1"><strong><tt>os.fork</tt></strong></a>, <a href="#cmd_1"><strong><tt>os.wait</tt></strong></a>, <a href="#cmd_1"><strong><tt>os.uptime</tt></strong></a>, <a href="#_signal"><strong><tt>signal</tt></strong></a>, <a href="#_alarm"><strong><tt>alarm</tt></strong></a>, <a href="#_sleep"><strong><tt>sleep</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Much better error reporting. <a href="#_info"><strong><tt>info</tt></strong></a> <tt>stacktrace</tt> as a replacement for <em>$errorInfo</em>, <em>$errorCode</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for "static" variables in procedures
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Threads and coroutines are not supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Command and variable traces are not supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Built-in command line editing
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Expression shorthand syntax: <tt>$(…)</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Modular build allows many features to be omitted or built as dynamic, loadable modules
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Highly suitable for use in an embedded environment
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_recent_changes">RECENT CHANGES</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_72_and_0_73">Changes between 0.72 and 0.73</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Built-in regexp now support non-capturing parentheses: (?:…)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_string"><strong><tt>string</tt></strong></a> <tt>replace</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_string"><strong><tt>string</tt></strong></a> <tt>totitle</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><tt>info</tt></strong></a> <tt>statics</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <tt>build-jim-ext</tt> for easy separate building of loadable modules (extensions)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><tt>local</tt></strong></a> now works with any command, not just procs
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><tt>info</tt></strong></a> <tt>alias</tt> to access the target of an alias
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
UTF-8 encoding past the basic multilingual plane (BMP) is supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_tcl_prefix"><strong><tt>tcl::prefix</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_history"><strong><tt>history</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Most extensions are now enabled by default
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for namespaces and the <a href="#_namespace"><strong><tt>namespace</tt></strong></a> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_apply"><strong><tt>apply</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_71_and_0_72">Changes between 0.71 and 0.72</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
procs now allow <em>args</em> and optional parameters in any position
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add Tcl-compatible expr functions, <tt>rand()</tt>, <tt>srand()</tt> and <tt>pow()</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for the <em>-force</em> option to <a href="#_file"><strong><tt>file</tt></strong></a> <tt>delete</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Better diagnostics when <a href="#_source"><strong><tt>source</tt></strong></a> fails to load a script with a missing quote or bracket
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
New <tt>tcl_platform(pathSeparator)</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support settings the modification time with <a href="#_file"><strong><tt>file</tt></strong></a> <tt>mtime</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_exec"><strong><tt>exec</tt></strong></a> is now fully supported on win32 (mingw32)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_file"><strong><tt>file</tt></strong></a> <tt>join</tt>, <a href="#_pwd"><strong><tt>pwd</tt></strong></a>, <a href="#_glob"><strong><tt>glob</tt></strong></a> etc. now work for mingw32
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Line editing is now supported for the win32 console (mingw32)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_aio"><strong><tt>aio</tt></strong></a> <tt>listen</tt> command
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_70_and_0_71">Changes between 0.70 and 0.71</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Allow <em>args</em> to be renamed in procs
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <tt>$(…)</tt> shorthand syntax for expressions
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add automatic reference variables in procs with <tt>&var</tt> syntax
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support <tt>jimsh --version</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Additional variables in <tt>tcl_platform()</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><tt>local</tt></strong></a> procs now push existing commands and <a href="#_upcall"><strong><tt>upcall</tt></strong></a> can call them
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_loop"><strong><tt>loop</tt></strong></a> command (TclX compatible)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_aio"><strong><tt>aio</tt></strong></a> <tt>buffering</tt> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_info"><strong><tt>info</tt></strong></a> <tt>complete</tt> can now return the missing character
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_binary"><strong><tt>binary</tt></strong></a> <tt>format</tt> and <a href="#_binary"><strong><tt>binary</tt></strong></a> <tt>scan</tt> are now (optionally) supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_string"><strong><tt>string</tt></strong></a> <tt>byterange</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Built-in regexp now support non-greedy repetition (*?, +?, ??)
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_63_and_0_70">Changes between 0.63 and 0.70</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<tt>platform_tcl()</tt> settings are now automatically determined
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add aio <tt>$handle filename</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><tt>info</tt></strong></a> <tt>channels</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <em>bio</em> extension is gone. Now <a href="#_aio"><strong><tt>aio</tt></strong></a> supports <em>copyto</em>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_exists"><strong><tt>exists</tt></strong></a> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add the pure-Tcl <em>oo</em> extension
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <a href="#_exec"><strong><tt>exec</tt></strong></a> command now only uses vfork(), not fork()
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Unit test framework is less verbose and more Tcl-compatible
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Optional UTF-8 support
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Optional built-in regexp engine for better Tcl compatibility and UTF-8 support
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Command line editing in interactive mode, e.g. <em>jimsh</em>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_tcl_introduction">TCL INTRODUCTION</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl stands for <em>tool command language</em> and is pronounced <em>tickle.</em>
|
|
It is actually two things: a language and a library.</p></div>
|
|
<div class="paragraph"><p>First, Tcl is a simple textual language, intended primarily for
|
|
issuing commands to interactive programs such as text editors,
|
|
debuggers, illustrators, and shells. It has a simple syntax and is also
|
|
programmable, so Tcl users can write command procedures to provide more
|
|
powerful commands than those in the built-in set.</p></div>
|
|
<div class="paragraph"><p>Second, Tcl is a library package that can be embedded in application
|
|
programs. The Tcl library consists of a parser for the Tcl language,
|
|
routines to implement the Tcl built-in commands, and procedures that
|
|
allow each application to extend Tcl with additional commands specific
|
|
to that application. The application program generates Tcl commands and
|
|
passes them to the Tcl parser for execution. Commands may be generated
|
|
by reading characters from an input source, or by associating command
|
|
strings with elements of the application’s user interface, such as menu
|
|
entries, buttons, or keystrokes.</p></div>
|
|
<div class="paragraph"><p>When the Tcl library receives commands it parses them into component
|
|
fields and executes built-in commands directly. For commands implemented
|
|
by the application, Tcl calls back to the application to execute the
|
|
commands. In many cases commands will invoke recursive invocations of the
|
|
Tcl interpreter by passing in additional strings to execute (procedures,
|
|
looping commands, and conditional commands all work in this way).</p></div>
|
|
<div class="paragraph"><p>An application program gains three advantages by using Tcl for its command
|
|
language. First, Tcl provides a standard syntax: once users know Tcl,
|
|
they will be able to issue commands easily to any Tcl-based application.
|
|
Second, Tcl provides programmability. All a Tcl application needs
|
|
to do is to implement a few application-specific low-level commands.
|
|
Tcl provides many utility commands plus a general programming interface
|
|
for building up complex command procedures. By using Tcl, applications
|
|
need not re-implement these features.</p></div>
|
|
<div class="paragraph"><p>Third, Tcl can be used as a common language for communicating between
|
|
applications. Inter-application communication is not built into the
|
|
Tcl core described here, but various add-on libraries, such as the Tk
|
|
toolkit, allow applications to issue commands to each other. This makes
|
|
it possible for applications to work together in much more powerful ways
|
|
than was previously possible.</p></div>
|
|
<div class="paragraph"><p>Fourth, Jim Tcl includes a command processor, <tt>jimsh</tt>, which can be
|
|
used to run standalone Tcl scripts, or to run Tcl commands interactively.</p></div>
|
|
<div class="paragraph"><p>This manual page focuses primarily on the Tcl language. It describes
|
|
the language syntax and the built-in commands that will be available
|
|
in any application based on Tcl. The individual library procedures are
|
|
described in more detail in separate manual pages, one per procedure.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_jimsh_command_interpreter">JIMSH COMMAND INTERPRETER</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>A simple, but powerful command processor, <tt>jimsh</tt>, is part of Jim Tcl.
|
|
It may be invoked in interactive mode as:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jimsh</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>or to process the Tcl script in a file with:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jimsh filename</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>It may also be invoked to execute an immediate script with:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jimsh -e "script"</tt></pre>
|
|
</div></div>
|
|
<div class="sect2">
|
|
<h3 id="_interactive_mode">Interactive Mode</h3>
|
|
<div class="paragraph"><p>Interactive mode reads Tcl commands from standard input, evaluates
|
|
those commands and prints the results.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>$ jimsh
|
|
Welcome to Jim version 0.73, Copyright (c) 2005-8 Salvatore Sanfilippo
|
|
. info version
|
|
0.73
|
|
. lsort [info commands p*]
|
|
package parray pid popen proc puts pwd
|
|
. foreach i {a b c} {
|
|
{> puts $i
|
|
{> }
|
|
a
|
|
b
|
|
c
|
|
. bad
|
|
invalid command name "bad"
|
|
[error] . exit
|
|
$</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If <tt>jimsh</tt> is configured with line editing (it is by default) and a VT-100-compatible
|
|
terminal is detected, Emacs-style line editing commands are available, including:
|
|
arrow keys, <tt>^W</tt> to erase a word, <tt>^U</tt> to erase the line, <tt>^R</tt> for reverse incremental search
|
|
in history. Additionally, the <tt>h</tt> command may be used to display the command history.</p></div>
|
|
<div class="paragraph"><p>Command line history is automatically saved and loaded from <tt>~/.jim_history</tt></p></div>
|
|
<div class="paragraph"><p>In interactive mode, <tt>jimsh</tt> automatically runs the script <tt>~/.jimrc</tt> at startup
|
|
if it exists.</p></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_interpreters">INTERPRETERS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The central data structure in Tcl is an interpreter (C type <em>Jim_Interp</em>).
|
|
An interpreter consists of a set of command bindings, a set of variable
|
|
values, and a few other miscellaneous pieces of state. Each Tcl command
|
|
is interpreted in the context of a particular interpreter.</p></div>
|
|
<div class="paragraph"><p>Some Tcl-based applications will maintain multiple interpreters
|
|
simultaneously, each associated with a different widget or portion of
|
|
the application. Interpreters are relatively lightweight structures.
|
|
They can be created and deleted quickly, so application programmers should
|
|
feel free to use multiple interpreters if that simplifies the application.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_data_types">DATA TYPES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl supports only one type of data: strings. All commands, all arguments
|
|
to commands, all command results, and all variable values are strings.</p></div>
|
|
<div class="paragraph"><p>Where commands require numeric arguments or return numeric results,
|
|
the arguments and results are passed as strings. Many commands expect
|
|
their string arguments to have certain formats, but this interpretation
|
|
is up to the individual commands. For example, arguments often contain
|
|
Tcl command strings, which may get executed as part of the commands.
|
|
The easiest way to understand the Tcl interpreter is to remember that
|
|
everything is just an operation on a string. In many cases Tcl constructs
|
|
will look similar to more structured constructs from other languages.
|
|
However, the Tcl constructs are not structured at all; they are just
|
|
strings of characters, and this gives them a different behaviour than
|
|
the structures they may look like.</p></div>
|
|
<div class="paragraph"><p>Although the exact interpretation of a Tcl string depends on who is doing
|
|
the interpretation, there are three common forms that strings take:
|
|
commands, expressions, and lists. The major sections below discuss
|
|
these three forms in more detail.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_basic_command_syntax">BASIC COMMAND SYNTAX</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The Tcl language has syntactic similarities to both the Unix shells
|
|
and Lisp. However, the interpretation of commands is different
|
|
in Tcl than in either of those other two systems.
|
|
A Tcl command string consists of one or more commands separated
|
|
by newline characters or semi-colons.
|
|
Each command consists of a collection of fields separated by
|
|
white space (spaces or tabs).
|
|
The first field must be the name of a command, and the
|
|
additional fields, if any, are arguments that will be passed to
|
|
that command. For example, the command:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a 22</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>has three fields: the first, <a href="#_set"><strong><tt>set</tt></strong></a>, is the name of a Tcl command, and
|
|
the last two, <em>a</em> and <em>22</em>, will be passed as arguments to
|
|
the <a href="#_set"><strong><tt>set</tt></strong></a> command. The command name may refer either to a built-in
|
|
Tcl command, an application-specific command bound in with the library
|
|
procedure <em>Jim_CreateCommand</em>, or a command procedure defined with the
|
|
<a href="#_proc"><strong><tt>proc</tt></strong></a> built-in command.</p></div>
|
|
<div class="paragraph"><p>Arguments are passed literally as text strings. Individual commands may
|
|
interpret those strings in any fashion they wish. The <a href="#_set"><strong><tt>set</tt></strong></a> command,
|
|
for example, will treat its first argument as the name of a variable
|
|
and its second argument as a string value to assign to that variable.
|
|
For other commands arguments may be interpreted as integers, lists,
|
|
file names, or Tcl commands.</p></div>
|
|
<div class="paragraph"><p>Command names should normally be typed completely (e.g. no abbreviations).
|
|
However, if the Tcl interpreter cannot locate a command it invokes a
|
|
special command named <a href="#_unknown"><strong><tt>unknown</tt></strong></a> which attempts to find or create the
|
|
command.</p></div>
|
|
<div class="paragraph"><p>For example, at many sites <a href="#_unknown"><strong><tt>unknown</tt></strong></a> will search through library
|
|
directories for the desired command and create it as a Tcl procedure if
|
|
it is found. The <a href="#_unknown"><strong><tt>unknown</tt></strong></a> command often provides automatic completion
|
|
of abbreviated commands, but usually only for commands that were typed
|
|
interactively.</p></div>
|
|
<div class="paragraph"><p>It’s probably a bad idea to use abbreviations in command scripts and
|
|
other forms that will be re-used over time: changes to the command set
|
|
may cause abbreviations to become ambiguous, resulting in scripts that
|
|
no longer work.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_comments">COMMENTS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>If the first non-blank character in a command is <tt>#</tt>, then everything
|
|
from the <tt>#</tt> up through the next newline character is treated as
|
|
a comment and ignored. When comments are embedded inside nested
|
|
commands (e.g. fields enclosed in braces) they must have properly-matched
|
|
braces (this is necessary because when Tcl parses the top-level command
|
|
it doesn’t yet know that the nested field will be used as a command so
|
|
it cannot process the nested comment character as a comment).</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_grouping_arguments_with_double_quotes">GROUPING ARGUMENTS WITH DOUBLE-QUOTES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Normally each argument field ends at the next white space, but
|
|
double-quotes may be used to create arguments with embedded space.</p></div>
|
|
<div class="paragraph"><p>If an argument field begins with a double-quote, then the argument isn’t
|
|
terminated by white space (including newlines) or a semi-colon (see below
|
|
for information on semi-colons); instead it ends at the next double-quote
|
|
character. The double-quotes are not included in the resulting argument.
|
|
For example, the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a "This is a single argument"</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will pass two arguments to <a href="#_set"><strong><tt>set</tt></strong></a>: <em>a</em> and <em>This is a single argument</em>.</p></div>
|
|
<div class="paragraph"><p>Within double-quotes, command substitutions, variable substitutions,
|
|
and backslash substitutions still occur, as described below. If the
|
|
first character of a command field is not a quote, then quotes receive
|
|
no special interpretation in the parsing of that field.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_grouping_arguments_with_braces">GROUPING ARGUMENTS WITH BRACES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Curly braces may also be used for grouping arguments. They are similar
|
|
to quotes except for two differences. First, they nest; this makes them
|
|
easier to use for complicated arguments like nested Tcl command strings.
|
|
Second, the substitutions described below for commands, variables, and
|
|
backslashes do <strong>not</strong> occur in arguments enclosed in braces, so braces
|
|
can be used to prevent substitutions where they are undesirable.</p></div>
|
|
<div class="paragraph"><p>If an argument field begins with a left brace, then the argument ends
|
|
at the matching right brace. Tcl will strip off the outermost layer
|
|
of braces and pass the information between the braces to the command
|
|
without any further modification. For example, in the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a {xyz a {b c d}}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the <a href="#_set"><strong><tt>set</tt></strong></a> command will receive two arguments: <em>a</em>
|
|
and <em>xyz a {b c d}</em>.</p></div>
|
|
<div class="paragraph"><p>When braces or quotes are in effect, the matching brace or quote need
|
|
not be on the same line as the starting quote or brace; in this case
|
|
the newline will be included in the argument field along with any other
|
|
characters up to the matching brace or quote. For example, the <a href="#_eval"><strong><tt>eval</tt></strong></a>
|
|
command takes one argument, which is a command string; <a href="#_eval"><strong><tt>eval</tt></strong></a> invokes
|
|
the Tcl interpreter to execute the command string. The command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>eval {
|
|
set a 22
|
|
set b 33
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will assign the value <em>22</em> to <em>a</em> and <em>33</em> to <em>b</em>.</p></div>
|
|
<div class="paragraph"><p>If the first character of a command field is not a left
|
|
brace, then neither left nor right
|
|
braces in the field will be treated specially (except as part of
|
|
variable substitution; see below).</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_command_substitution_with_brackets">COMMAND SUBSTITUTION WITH BRACKETS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>If an open bracket occurs in a field of a command, then command
|
|
substitution occurs (except for fields enclosed in braces). All of the
|
|
text up to the matching close bracket is treated as a Tcl command and
|
|
executed immediately. Then the result of that command is substituted
|
|
for the bracketed text. For example, consider the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a [set b]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>When the <a href="#_set"><strong><tt>set</tt></strong></a> command has only a single argument, it is the name of a
|
|
variable and <a href="#_set"><strong><tt>set</tt></strong></a> returns the contents of that variable. In this case,
|
|
if variable <em>b</em> has the value <em>foo</em>, then the command above is equivalent
|
|
to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a foo</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Brackets can be used in more complex ways. For example, if the variable
|
|
<em>b</em> has the value <em>foo</em> and the variable <em>c</em> has the value <em>gorp</em>,
|
|
then the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyz[set b].[set c]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyzfoo.gorp</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>A bracketed command may contain multiple commands separated by newlines
|
|
or semi-colons in the usual fashion. In this case the value of the last
|
|
command is used for substitution. For example, the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a x[set b 22
|
|
expr $b+2]x</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a x24x</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If a field is enclosed in braces then the brackets and the characters
|
|
between them are not interpreted specially; they are passed through to
|
|
the argument verbatim.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_variable_substitution_with">VARIABLE SUBSTITUTION WITH $</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The dollar sign (<tt>$</tt>) may be used as a special shorthand form for
|
|
substituting variable values. If <tt>$</tt> appears in an argument that isn’t
|
|
enclosed in braces then variable substitution will occur. The characters
|
|
after the <tt>$</tt>, up to the first character that isn’t a number, letter,
|
|
or underscore, are taken as a variable name and the string value of that
|
|
variable is substituted for the name.</p></div>
|
|
<div class="paragraph"><p>For example, if variable <em>foo</em> has the value <em>test</em>, then the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a $foo.c</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a test.c</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>There are two special forms for variable substitution. If the next
|
|
character after the name of the variable is an open parenthesis, then
|
|
the variable is assumed to be an array name, and all of the characters
|
|
between the open parenthesis and the next close parenthesis are taken as
|
|
an index into the array. Command substitutions and variable substitutions
|
|
are performed on the information between the parentheses before it is
|
|
used as an index.</p></div>
|
|
<div class="paragraph"><p>For example, if the variable <em>x</em> is an array with one element named
|
|
<em>first</em> and value <em>87</em> and another element named <em>14</em> and value <em>more</em>,
|
|
then the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyz$x(first)zyx</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyz87zyx</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If the variable <em>index</em> has the value <em>14</em>, then the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyz$x($index)zyx</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a xyzmorezyx</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>For more information on arrays, see VARIABLES AND ARRAYS below.</p></div>
|
|
<div class="paragraph"><p>The second special form for variables occurs when the dollar sign is
|
|
followed by an open curly brace. In this case the variable name consists
|
|
of all the characters up to the next curly brace.</p></div>
|
|
<div class="paragraph"><p>Array references are not possible in this form: the name between braces
|
|
is assumed to refer to a scalar variable. For example, if variable
|
|
<em>foo</em> has the value <em>test</em>, then the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a abc${foo}bar</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a abctestbar</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Variable substitution does not occur in arguments that are enclosed in
|
|
braces: the dollar sign and variable name are passed through to the
|
|
argument verbatim.</p></div>
|
|
<div class="paragraph"><p>The dollar sign abbreviation is simply a shorthand form. <tt>$a</tt> is
|
|
completely equivalent to <tt>[set a]</tt>; it is provided as a convenience
|
|
to reduce typing.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_separating_commands_with_semi_colons">SEPARATING COMMANDS WITH SEMI-COLONS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Normally, each command occupies one line (the command is terminated by a
|
|
newline character). However, semi-colon (<tt>;</tt>) is treated as a command
|
|
separator character; multiple commands may be placed on one line by
|
|
separating them with a semi-colon. Semi-colons are not treated as
|
|
command separators if they appear within curly braces or double-quotes.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_backslash_substitution">BACKSLASH SUBSTITUTION</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Backslashes may be used to insert non-printing characters into command
|
|
fields and also to insert special characters like braces and brackets
|
|
into fields without them being interpreted specially as described above.</p></div>
|
|
<div class="paragraph"><p>The backslash sequences understood by the Tcl interpreter are
|
|
listed below. In each case, the backslash
|
|
sequence is replaced by the given character:</p></div>
|
|
<div class="dlist" id="BackslashSequences"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>\b</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Backspace (0x8)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\f</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Form feed (0xc)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\n</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Newline (0xa)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\r</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Carriage-return (0xd).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\t</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Tab (0x9).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\v</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Vertical tab (0xb).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\{</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Left brace ({).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\}</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Right brace (}).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\[</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open bracket ([).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\]</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Close bracket (]).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\$</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Dollar sign ($).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\<space></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Space ( ): doesn’t terminate argument.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\;</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Semi-colon: doesn’t terminate command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\"</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Double-quote.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\<newline></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Nothing: this joins two lines together
|
|
into a single line. This backslash feature is unique in that
|
|
it will be applied even when the sequence occurs within braces.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\\</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Backslash (<em>\</em>).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\ddd</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The digits <tt><em>ddd</em></tt> (one, two, or three of them) give the octal value of
|
|
the character. Note that Jim supports null characters in strings.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\unnnn</tt>
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<tt>\u{nnn}</tt>
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<tt>\Unnnnnnnn</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The UTF-8 encoding of the unicode codepoint represented by the hex digits, <tt><em>nnnn</em></tt>, is inserted.
|
|
The <em>u</em> form allows for one to four hex digits.
|
|
The <em>U</em> form allows for one to eight hex digits.
|
|
The <em>u{nnn}</em> form allows for one to eight hex digits, but makes it easier to insert
|
|
characters UTF-8 characters which are followed by a hex digit.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>For example, in the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a \{x\[\ yz\141</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the second argument to <a href="#_set"><strong><tt>set</tt></strong></a> will be <tt>{x[ yza</tt>.</p></div>
|
|
<div class="paragraph"><p>If a backslash is followed by something other than one of the options
|
|
described above, then the backslash is transmitted to the argument
|
|
field without any special processing, and the Tcl scanner continues
|
|
normal processing with the next character. For example, in the
|
|
command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set \*a \\\{foo</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The first argument to <a href="#_set"><strong><tt>set</tt></strong></a> will be <tt>\*a</tt> and the second
|
|
argument will be <tt>\{foo</tt>.</p></div>
|
|
<div class="paragraph"><p>If an argument is enclosed in braces, then backslash sequences inside
|
|
the argument are parsed but no substitution occurs (except for
|
|
backslash-newline): the backslash
|
|
sequence is passed through to the argument as is, without making
|
|
any special interpretation of the characters in the backslash sequence.
|
|
In particular, backslashed braces are not counted in locating the
|
|
matching right brace that terminates the argument.
|
|
For example, in the
|
|
command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a {\{abc}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the second argument to <a href="#_set"><strong><tt>set</tt></strong></a> will be <tt>\{abc</tt>.</p></div>
|
|
<div class="paragraph"><p>This backslash mechanism is not sufficient to generate absolutely
|
|
any argument structure; it only covers the
|
|
most common cases. To produce particularly complicated arguments
|
|
it is probably easiest to use the <a href="#_format"><strong><tt>format</tt></strong></a> command along with
|
|
command substitution.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Many string and list commands take one or more <em>index</em> parameters which
|
|
specify a position in the string relative to the start or end of the string/list.</p></div>
|
|
<div class="paragraph"><p>The index may be one of the following forms:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>integer</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A simple integer, where <em>0</em> refers to the first element of the string
|
|
or list.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>integer+integer</tt> or
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<tt>integer-integer</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The sum or difference of the two integers. e.g. <tt>2+3</tt> refers to the 5th element.
|
|
This is useful when used with (e.g.) <tt>$i+1</tt> rather than the more verbose
|
|
<tt>[expr {$i+1}]</tt>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>end</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The last element of the string or list.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>end-integer</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The <em>nth-from-last</em> element of the string or list.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_command_summary">COMMAND SUMMARY</h2>
|
|
<div class="sectionbody">
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
A command is just a string.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Within a string commands are separated by newlines or semi-colons
|
|
(unless the newline or semi-colon is within braces or brackets
|
|
or is backslashed).
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
A command consists of fields. The first field is the name of the command.
|
|
The other fields are strings that are passed to that command as arguments.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fields are normally separated by white space.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Double-quotes allow white space and semi-colons to appear within
|
|
a single argument.
|
|
Command substitution, variable substitution, and backslash substitution
|
|
still occur inside quotes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Braces defer interpretation of special characters.
|
|
If a field begins with a left brace, then it consists of everything
|
|
between the left brace and the matching right brace. The
|
|
braces themselves are not included in the argument.
|
|
No further processing is done on the information between the braces
|
|
except that backslash-newline sequences are eliminated.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
If a field doesn’t begin with a brace then backslash,
|
|
variable, and command substitution are done on the field. Only a
|
|
single level of processing is done: the results of one substitution
|
|
are not scanned again for further substitutions or any other
|
|
special treatment. Substitution can
|
|
occur on any field of a command, including the command name
|
|
as well as the arguments.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
If the first non-blank character of a command is a <tt>#</tt>, everything
|
|
from the <tt>#</tt> up through the next newline is treated as a comment
|
|
and ignored.
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_expressions">EXPRESSIONS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The second major interpretation applied to strings in Tcl is
|
|
as expressions. Several commands, such as <a href="#_expr"><strong><tt>expr</tt></strong></a>, <a href="#_for"><strong><tt>for</tt></strong></a>,
|
|
and <a href="#_if"><strong><tt>if</tt></strong></a>, treat one or more of their arguments as expressions
|
|
and call the Tcl expression processors (<em>Jim_ExprLong</em>,
|
|
<em>Jim_ExprBoolean</em>, etc.) to evaluate them.</p></div>
|
|
<div class="paragraph"><p>The operators permitted in Tcl expressions are a subset of
|
|
the operators permitted in C expressions, and they have the
|
|
same meaning and precedence as the corresponding C operators.
|
|
Expressions almost always yield numeric results
|
|
(integer or floating-point values).
|
|
For example, the expression</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>8.2 + 6</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>evaluates to 14.2.</p></div>
|
|
<div class="paragraph"><p>Tcl expressions differ from C expressions in the way that
|
|
operands are specified, and in that Tcl expressions support
|
|
non-numeric operands and string comparisons.</p></div>
|
|
<div class="paragraph"><p>A Tcl expression consists of a combination of operands, operators,
|
|
and parentheses.</p></div>
|
|
<div class="paragraph"><p>White space may be used between the operands and operators and
|
|
parentheses; it is ignored by the expression processor.
|
|
Where possible, operands are interpreted as integer values.</p></div>
|
|
<div class="paragraph"><p>Integer values may be specified in decimal (the normal case), in octal (if the
|
|
first character of the operand is <em>0</em>), or in hexadecimal (if the first
|
|
two characters of the operand are <em>0x</em>).</p></div>
|
|
<div class="paragraph"><p>If an operand does not have one of the integer formats given
|
|
above, then it is treated as a floating-point number if that is
|
|
possible. Floating-point numbers may be specified in any of the
|
|
ways accepted by an ANSI-compliant C compiler (except that the
|
|
<em>f</em>, <em>F</em>, <em>l</em>, and <em>L</em> suffixes will not be permitted in
|
|
most installations). For example, all of the
|
|
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.</p></div>
|
|
<div class="paragraph"><p>If no numeric interpretation is possible, then an operand is left
|
|
as a string (and only a limited set of operators may be applied to
|
|
it).</p></div>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Operands may be specified in any of the following ways:
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
As a numeric value, either integer or floating-point.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
As a Tcl variable, using standard <em>$</em> notation.
|
|
The variable’s value will be used as the operand.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
As a string enclosed in double-quotes.
|
|
The expression parser will perform backslash, variable, and
|
|
command substitutions on the information between the quotes,
|
|
and use the resulting value as the operand
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
As a string enclosed in braces.
|
|
The characters between the open brace and matching close brace
|
|
will be used as the operand without any substitutions.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
As a Tcl command enclosed in brackets.
|
|
The command will be executed and its result will be used as
|
|
the operand.
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
<div class="paragraph"><p>Where substitutions occur above (e.g. inside quoted strings), they
|
|
are performed by the expression processor.
|
|
However, an additional layer of substitution may already have
|
|
been performed by the command parser before the expression
|
|
processor was called.</p></div>
|
|
<div class="paragraph"><p>As discussed below, it is usually best to enclose expressions
|
|
in braces to prevent the command parser from performing substitutions
|
|
on the contents.</p></div>
|
|
<div class="paragraph"><p>For some examples of simple expressions, suppose the variable <em>a</em> has
|
|
the value 3 and the variable <em>b</em> has the value 6. Then the expression
|
|
on the left side of each of the lines below will evaluate to the value
|
|
on the right side of the line:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>$a + 3.1 6.1
|
|
2 + "$a.$b" 5.6
|
|
4*[llength "6 2"] 8
|
|
{word one} < "word $a" 0</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The valid operators are listed below, grouped in decreasing order
|
|
of precedence:</p></div>
|
|
<div class="dlist" id="OperatorPrecedence"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>int() double() round() abs(), rand(), srand()</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unary functions (except rand() which takes no arguments)
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<tt><em>int()</em></tt> converts the numeric argument to an integer by truncating down.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>double()</em></tt> converts the numeric argument to floating point.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>round()</em></tt> converts the numeric argument to the closest integer value.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>abs()</em></tt> takes the absolute value of the numeric argument.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>rand()</em></tt> takes the absolute value of the numeric argument.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>rand()</em></tt> returns a pseudo-random floating-point value in the range (0,1).
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt><em>srand()</em></tt> takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed.
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unary math functions.
|
|
If Jim is compiled with math support, these functions are available.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>- + ~ !</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
|
|
may be applied to string operands, and bit-wise NOT may be
|
|
applied only to integers.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>** pow(x,y)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Power. e.g. <em>x<sup>y</sup></em>. If Jim is compiled with math support, supports doubles and
|
|
integers. Otherwise supports integers only. (Note that the math-function form
|
|
has the same highest precedence)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>* / %</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Multiply, divide, remainder. None of these operands may be
|
|
applied to string operands, and remainder may be applied only
|
|
to integers.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>+ -</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Add and subtract. Valid for any numeric operands.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><< >> <<< >>></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Left and right shift, left and right rotate. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>< > <= >=</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Boolean less, greater, less than or equal, and greater than or equal.
|
|
Each operator produces 1 if the condition is true, 0 otherwise.
|
|
These operators may be applied to strings as well as numeric operands,
|
|
in which case string comparison is used.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>== !=</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Boolean equal and not equal. Each operator produces a zero/one result.
|
|
Valid for all operand types. <strong>Note</strong> that values will be converted to integers
|
|
if possible, then floating point types, and finally strings will be compared.
|
|
It is recommended that <em>eq</em> and <em>ne</em> should be used for string comparison.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>eq ne</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
String equal and not equal. Uses the string value directly without
|
|
attempting to convert to a number first.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>in ni</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
String in list and not in list. For <em>in</em>, result is 1 if the left operand (as a string)
|
|
is contained in the right operand (as a list), or 0 otherwise. The result for
|
|
<tt>{$a ni $list}</tt> is equivalent to <tt>{!($a in $list)}</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>&</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise AND. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>|</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise OR. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>^</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise exclusive OR. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>&&</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
|
|
Valid for numeric operands only (integers or floating-point).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>||</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
|
|
Valid for numeric operands only (integers or floating-point).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>x ? y : z</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If-then-else, as in C. If <tt><em>x</em></tt>
|
|
evaluates to non-zero, then the result is the value of <tt><em>y</em></tt>.
|
|
Otherwise the result is the value of <tt><em>z</em></tt>.
|
|
The <tt><em>x</em></tt> operand must have a numeric value, while <tt><em>y</em></tt> and <tt><em>z</em></tt> can
|
|
be of any type.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>See the C manual for more details on the results
|
|
produced by each operator.
|
|
All of the binary operators group left-to-right within the same
|
|
precedence level. For example, the expression</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>4*2 < 7</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>evaluates to 0.</p></div>
|
|
<div class="paragraph"><p>The <tt>&&</tt>, <tt>||</tt>, and <tt>?:</tt> operators have <em>lazy evaluation</em>, just as
|
|
in C, which means that operands are not evaluated if they are not
|
|
needed to determine the outcome. For example, in</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>$v ? [a] : [b]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>only one of <tt>[a]</tt> or <tt>[b]</tt> will actually be evaluated,
|
|
depending on the value of <tt>$v</tt>.</p></div>
|
|
<div class="paragraph"><p>All internal computations involving integers are done with the C
|
|
type <em>long long</em> if available, or <em>long</em> otherwise, and all internal
|
|
computations involving floating-point are done with the C type
|
|
<em>double</em>.</p></div>
|
|
<div class="paragraph"><p>When converting a string to floating-point, exponent overflow is
|
|
detected and results in a Tcl error.
|
|
For conversion to integer from string, detection of overflow depends
|
|
on the behaviour of some routines in the local C library, so it should
|
|
be regarded as unreliable.
|
|
In any case, overflow and underflow are generally not detected
|
|
reliably for intermediate results.</p></div>
|
|
<div class="paragraph"><p>Conversion among internal representations for integer, floating-point,
|
|
and string operands is done automatically as needed.
|
|
For arithmetic computations, integers are used until some
|
|
floating-point number is introduced, after which floating-point is used.
|
|
For example,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>5 / 4</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>yields the result 1, while</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>5 / 4.0
|
|
5 / ( [string length "abcd"] + 0.0 )</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>both yield the result 1.25.</p></div>
|
|
<div class="paragraph"><p>String values may be used as operands of the comparison operators,
|
|
although the expression evaluator tries to do comparisons as integer
|
|
or floating-point when it can.
|
|
If one of the operands of a comparison is a string and the other
|
|
has a numeric value, the numeric operand is converted back to
|
|
a string using the C <em>sprintf</em> format specifier
|
|
<em>%d</em> for integers and <em>%g</em> for floating-point values.
|
|
For example, the expressions</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>"0x03" > "2"
|
|
"0y" < "0x12"</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>both evaluate to 1. The first comparison is done using integer
|
|
comparison, and the second is done using string comparison after
|
|
the second operand is converted to the string <em>18</em>.</p></div>
|
|
<div class="paragraph"><p>In general it is safest to enclose an expression in braces when
|
|
entering it in a command: otherwise, if the expression contains
|
|
any white space then the Tcl interpreter will split it
|
|
among several arguments. For example, the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>expr $a + $b</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>results in three arguments being passed to <a href="#_expr"><strong><tt>expr</tt></strong></a>: <tt>$a</tt>,
|
|
+, and <tt>$b</tt>. In addition, if the expression isn’t in braces
|
|
then the Tcl interpreter will perform variable and command substitution
|
|
immediately (it will happen in the command parser rather than in
|
|
the expression parser). In many cases the expression is being
|
|
passed to a command that will evaluate the expression later (or
|
|
even many times if, for example, the expression is to be used to
|
|
decide when to exit a loop). Usually the desired goal is to re-do
|
|
the variable or command substitutions each time the expression is
|
|
evaluated, rather than once and for all at the beginning. For example,
|
|
the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>for {set i 1} $i<=10 {incr i} {...} ** WRONG **</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is probably intended to iterate over all values of <tt>i</tt> from 1 to 10.
|
|
After each iteration of the body of the loop, <a href="#_for"><strong><tt>for</tt></strong></a> will pass
|
|
its second argument to the expression evaluator to see whether or not
|
|
to continue processing. Unfortunately, in this case the value of <tt>i</tt>
|
|
in the second argument will be substituted once and for all when the
|
|
<a href="#_for"><strong><tt>for</tt></strong></a> command is parsed. If <tt>i</tt> was 0 before the <a href="#_for"><strong><tt>for</tt></strong></a>
|
|
command was invoked then the second argument of <a href="#_for"><strong><tt>for</tt></strong></a> will be <tt>0<=10</tt>
|
|
which will always evaluate to 1, even though <tt>i</tt> eventually
|
|
becomes greater than 10. In the above case the loop will never
|
|
terminate. Instead, the expression should be placed in braces:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>for {set i 1} {$i<=10} {incr i} {...} ** RIGHT **</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This causes the substitution of <em>i</em>
|
|
to be delayed; it will be re-done each time the expression is
|
|
evaluated, which is the desired result.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_lists">LISTS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The third major way that strings are interpreted in Tcl is as lists.
|
|
A list is just a string with a list-like structure
|
|
consisting of fields separated by white space. For example, the
|
|
string</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>Al Sue Anne John</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is a list with four elements or fields.
|
|
Lists have the same basic structure as command strings, except
|
|
that a newline character in a list is treated as a field separator
|
|
just like space or tab. Conventions for braces and quotes
|
|
and backslashes are the same for lists as for commands. For example,
|
|
the string</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>a b\ c {d e {f g h}}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is a list with three elements: <tt>a</tt>, <tt>b c</tt>, and <tt>d e {f g h}</tt>.</p></div>
|
|
<div class="paragraph"><p>Whenever an element is extracted from a list, the same rules about
|
|
braces and quotes and backslashes are applied as for commands. Thus in
|
|
the example above when the third element is extracted from the list,
|
|
the result is</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>d e {f g h}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>(when the field was extracted, all that happened was to strip off
|
|
the outermost layer of braces). Command substitution and
|
|
variable substitution are never
|
|
made on a list (at least, not by the list-processing commands; the
|
|
list can always be passed to the Tcl interpreter for evaluation).</p></div>
|
|
<div class="paragraph"><p>The Tcl commands <a href="#_concat"><strong><tt>concat</tt></strong></a>, <a href="#_foreach"><strong><tt>foreach</tt></strong></a>, <a href="#_lappend"><strong><tt>lappend</tt></strong></a>, <a href="#_lindex"><strong><tt>lindex</tt></strong></a>, <a href="#_linsert"><strong><tt>linsert</tt></strong></a>,
|
|
<a href="#_list"><strong><tt>list</tt></strong></a>, <a href="#_llength"><strong><tt>llength</tt></strong></a>, <a href="#_lrange"><strong><tt>lrange</tt></strong></a>, <a href="#_lreplace"><strong><tt>lreplace</tt></strong></a>, <a href="#_lsearch"><strong><tt>lsearch</tt></strong></a>, and <a href="#_lsort"><strong><tt>lsort</tt></strong></a> allow
|
|
you to build lists, extract elements from them, search them, and perform
|
|
other list-related functions.</p></div>
|
|
<div class="paragraph"><p>Advanced list commands include <a href="#_lrepeat"><strong><tt>lrepeat</tt></strong></a>, <a href="#_lreverse"><strong><tt>lreverse</tt></strong></a>, <a href="#_lmap"><strong><tt>lmap</tt></strong></a>, <a href="#_lassign"><strong><tt>lassign</tt></strong></a>, <a href="#_lset"><strong><tt>lset</tt></strong></a>.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_list_expansion">LIST EXPANSION</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>A new addition to Tcl 8.5 is the ability to expand a list into separate
|
|
arguments. Support for this feature is also available in Jim.</p></div>
|
|
<div class="paragraph"><p>Consider the following attempt to exec a list:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set cmd {ls -l}
|
|
exec $cmd</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This will attempt to exec the a command named "ls -l", which will clearly not
|
|
work. Typically eval and concat are required to solve this problem, however
|
|
it can be solved much more easily with <tt>{*}</tt>.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>exec {*}$cmd</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This will expand the following argument into individual elements and then evaluate
|
|
the resulting command.</p></div>
|
|
<div class="paragraph"><p>Note that the official Tcl syntax is <tt>{*}</tt>, however <tt>{expand}</tt> is retained
|
|
for backward compatibility with experimental versions of this feature.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_regular_expressions">REGULAR EXPRESSIONS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl provides two commands that support string matching using regular
|
|
expressions, <a href="#_regexp"><strong><tt>regexp</tt></strong></a> and <a href="#_regsub"><strong><tt>regsub</tt></strong></a>, as well as <a href="#_switch"><strong><tt>switch</tt></strong></a> <tt>-regexp</tt> and
|
|
<a href="#_lsearch"><strong><tt>lsearch</tt></strong></a> <tt>-regexp</tt>.</p></div>
|
|
<div class="paragraph"><p>Regular expressions may be implemented one of two ways. Either using the system’s C library
|
|
POSIX regular expression support, or using the built-in regular expression engine.
|
|
The differences between these are described below.</p></div>
|
|
<div class="paragraph"><p><strong>NOTE</strong> Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (<tt>ARE</tt>).</p></div>
|
|
<div class="sect2">
|
|
<h3 id="_posix_regular_expressions">POSIX Regular Expressions</h3>
|
|
<div class="paragraph"><p>If the system supports POSIX regular expressions, and UTF-8 support is not enabled,
|
|
this support will be used by default. The type of regular expressions supported are
|
|
Extended Regular Expressions (<tt>ERE</tt>) rather than Basic Regular Expressions (<tt>BRE</tt>).
|
|
See REG_EXTENDED in the documentation.</p></div>
|
|
<div class="paragraph"><p>Using the system-supported POSIX regular expressions will typically
|
|
make for the smallest code size, but some features such as UTF-8
|
|
and <tt>\w</tt>, <tt>\d</tt>, <tt>\s</tt> are not supported.</p></div>
|
|
<div class="paragraph"><p>See regex(3) and regex(7) for full details.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_jim_built_in_regular_expressions">Jim built-in Regular Expressions</h3>
|
|
<div class="paragraph"><p>The Jim built-in regulare expression engine may be selected with <tt>./configure --with-jim-regexp</tt>
|
|
or it will be selected automatically if UTF-8 support is enabled.</p></div>
|
|
<div class="paragraph"><p>This engine supports UTF-8 as well as some <tt>ARE</tt> features. The differences with both Tcl 7.x/8.x
|
|
and POSIX are highlighted below.</p></div>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
UTF-8 strings and patterns are both supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Supported character classes: <tt>[:alnum:]</tt>, <tt>[:digit:]</tt> and <tt>[:space:]</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Supported shorthand character classes: <tt>\w</tt> = <tt>[:alnum:]</tt>, <tt>\d</tt> = <tt>[:digit:],</tt> <tt>\s</tt> = <tt>[:space:]</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Character classes apply to ASCII characters only
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Supported constraint escapes: <tt>\m</tt> = <tt>\<</tt> = start of word, <tt>\M</tt> = <tt>\></tt> = end of word
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Backslash escapes may be used within regular expressions, such as <tt>\n</tt> = newline, <tt>\uNNNN</tt> = unicode
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for the <tt>?</tt> non-greedy quantifier. e.g. <tt>*?</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for non-capuring parentheses <tt>(?:…)</tt>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_command_results">COMMAND RESULTS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Each command produces two results: a code and a string. The
|
|
code indicates whether the command completed successfully or not,
|
|
and the string gives additional information. The valid codes are
|
|
defined in jim.h, and are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_OK(0)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This is the normal return code, and indicates that the command completed
|
|
successfully. The string gives the command’s return value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_ERR(1)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that an error occurred; the string gives a message describing
|
|
the error.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_RETURN(2)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_return"><strong><tt>return</tt></strong></a> command has been invoked, and that the
|
|
current procedure (or top-level command or <a href="#_source"><strong><tt>source</tt></strong></a> command)
|
|
should return immediately. The
|
|
string gives the return value for the procedure or command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_BREAK(3)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_break"><strong><tt>break</tt></strong></a> command has been invoked, so the
|
|
innermost loop should abort immediately. The string should always
|
|
be empty.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_CONTINUE(4)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_continue"><strong><tt>continue</tt></strong></a> command has been invoked, so the
|
|
innermost loop should go on to the next iteration. The string
|
|
should always be empty.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_SIGNAL(5)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that a signal was caught while executing a commands.
|
|
The string contains the name of the signal caught.
|
|
See the <a href="#_signal"><strong><tt>signal</tt></strong></a> and <a href="#_catch"><strong><tt>catch</tt></strong></a> commands.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>JIM_EXIT(6)</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the command called the <a href="#_exit"><strong><tt>exit</tt></strong></a> command.
|
|
The string contains the exit code.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>Tcl programmers do not normally need to think about return codes,
|
|
since <tt>JIM_OK</tt> is almost always returned. If anything else is returned
|
|
by a command, then the Tcl interpreter immediately stops processing
|
|
commands and returns to its caller. If there are several nested
|
|
invocations of the Tcl interpreter in progress, then each nested
|
|
command will usually return the error to its caller, until eventually
|
|
the error is reported to the top-level application code. The
|
|
application will then display the error message for the user.</p></div>
|
|
<div class="paragraph"><p>In a few cases, some commands will handle certain <a href="#_error"><strong><tt>error</tt></strong></a> conditions
|
|
themselves and not return them upwards. For example, the <a href="#_for"><strong><tt>for</tt></strong></a>
|
|
command checks for the <tt>JIM_BREAK</tt> code; if it occurs, then <a href="#_for"><strong><tt>for</tt></strong></a>
|
|
stops executing the body of the loop and returns <tt>JIM_OK</tt> to its
|
|
caller. The <a href="#_for"><strong><tt>for</tt></strong></a> command also handles <tt>JIM_CONTINUE</tt> codes and the
|
|
procedure interpreter handles <tt>JIM_RETURN</tt> codes. The <a href="#_catch"><strong><tt>catch</tt></strong></a>
|
|
command allows Tcl programs to catch errors and handle them without
|
|
aborting command interpretation any further.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_info"><strong><tt>info</tt></strong></a> <tt>returncodes</tt> command may be used to programmatically map between
|
|
return codes and names.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_procedures">PROCEDURES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl allows you to extend the command interface by defining
|
|
procedures. A Tcl procedure can be invoked just like any other Tcl
|
|
command (it has a name and it receives one or more arguments).
|
|
The only difference is that its body isn’t a piece of C code linked
|
|
into the program; it is a string containing one or more other
|
|
Tcl commands.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_proc"><strong><tt>proc</tt></strong></a> command is used to create a new Tcl command procedure:</p></div>
|
|
<div class="paragraph"><p><tt><strong>proc</strong> <em>name arglist ?statics? body</em></tt></p></div>
|
|
<div class="paragraph"><p>The new command is named <tt><em>name</em></tt>, and it replaces any existing command
|
|
there may have been by that name. Whenever the new command is
|
|
invoked, the contents of <tt><em>body</em></tt> will be executed by the Tcl
|
|
interpreter.</p></div>
|
|
<div class="paragraph"><p><tt><em>arglist</em></tt> specifies the formal arguments to the procedure.
|
|
It consists of a list, possibly empty, of the following
|
|
argument specifiers:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>name</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Required Argument - A simple argument name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>name default</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Optional Argument - A two-element list consisting of the
|
|
argument name, followed by the default value, which will
|
|
be used if the corresponding argument is not supplied.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>&name</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Reference Argument - The caller is expected to pass the name of
|
|
an existing variable. An implicit <a href="#_upvar"><strong><tt>upvar</tt></strong></a> <tt>1 'origname' 'name'</tt> is done
|
|
to make the variable available in the proc scope.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>args</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Variable Argument - The special name <tt><em>args</em></tt>, which is
|
|
assigned all remaining arguments (including none) as a list. The
|
|
variable argument may only be specified once. Note that
|
|
the syntax <tt>args newname</tt> may be used to retain the special
|
|
behaviour of <tt><em>args</em></tt> with a different local name. In this case,
|
|
the variable is named <tt><em>newname</em></tt> rather than <tt><em>args</em></tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>When the command is invoked, a local variable will be created for each of
|
|
the formal arguments to the procedure; its value will be the value
|
|
of corresponding argument in the invoking command or the argument’s
|
|
default value.</p></div>
|
|
<div class="paragraph"><p>Arguments with default values need not be specified in a procedure
|
|
invocation. However, there must be enough actual arguments for all
|
|
required arguments, and there must not be any extra actual arguments
|
|
(unless the Variable Argument is specified).</p></div>
|
|
<div class="paragraph"><p>Actual arguments are assigned to formal arguments as in left-to-right
|
|
order with the following precedence.</p></div>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Required Arguments (including Reference Arguments)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Optional Arguments
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Variable Argument
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
<div class="paragraph"><p>The following example illustrates precedence. Assume a procedure declaration:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>proc p {{a A} args b {c C} d} {...}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This procedure requires at least two arguments, but can accept an unlimited number.
|
|
The following table shows how various numbers of arguments are assigned.
|
|
Values marked as <tt>-</tt> are assigned the default value.</p></div>
|
|
<div class="tableblock">
|
|
<table rules="all"
|
|
width="40%"
|
|
frame="hsides"
|
|
cellspacing="0" cellpadding="4">
|
|
<col width="16%" />
|
|
<col width="16%" />
|
|
<col width="16%" />
|
|
<col width="16%" />
|
|
<col width="16%" />
|
|
<col width="16%" />
|
|
<thead>
|
|
<tr>
|
|
<th align="left" valign="top">Number of arguments</th>
|
|
<th align="left" valign="top">a</th>
|
|
<th align="left" valign="top">args</th>
|
|
<th align="left" valign="top">b</th>
|
|
<th align="left" valign="top">c</th>
|
|
<th align="left" valign="top">d</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table">2</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">1</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">2</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table">3</p></td>
|
|
<td align="left" valign="top"><p class="table">1</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">2</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">3</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table">4</p></td>
|
|
<td align="left" valign="top"><p class="table">1</p></td>
|
|
<td align="left" valign="top"><p class="table">-</p></td>
|
|
<td align="left" valign="top"><p class="table">2</p></td>
|
|
<td align="left" valign="top"><p class="table">3</p></td>
|
|
<td align="left" valign="top"><p class="table">4</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table">5</p></td>
|
|
<td align="left" valign="top"><p class="table">1</p></td>
|
|
<td align="left" valign="top"><p class="table">2</p></td>
|
|
<td align="left" valign="top"><p class="table">3</p></td>
|
|
<td align="left" valign="top"><p class="table">4</p></td>
|
|
<td align="left" valign="top"><p class="table">5</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table">6</p></td>
|
|
<td align="left" valign="top"><p class="table">1</p></td>
|
|
<td align="left" valign="top"><p class="table">2,3</p></td>
|
|
<td align="left" valign="top"><p class="table">4</p></td>
|
|
<td align="left" valign="top"><p class="table">5</p></td>
|
|
<td align="left" valign="top"><p class="table">6</p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph"><p>When <tt><em>body</em></tt> is being executed, variable names normally refer to local
|
|
variables, which are created automatically when referenced and deleted
|
|
when the procedure returns. One local variable is automatically created
|
|
for each of the procedure’s arguments. Global variables can be
|
|
accessed by invoking the <a href="#_global"><strong><tt>global</tt></strong></a> command or via the <tt>::</tt> prefix.</p></div>
|
|
<div class="sect2">
|
|
<h3 id="_new_in_jim">New in Jim</h3>
|
|
<div class="paragraph"><p>In addition to procedure arguments, Jim procedures may declare static variables.
|
|
These variables scoped to the procedure and initialised at procedure definition.
|
|
Either from the static variable definition, or from the enclosing scope.</p></div>
|
|
<div class="paragraph"><p>Consider the following example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> set a 1
|
|
jim> proc a {} {a {b 2}} {
|
|
set c 1
|
|
puts "$a $b $c"
|
|
incr a
|
|
incr b
|
|
incr c
|
|
}
|
|
jim> a
|
|
1 2 1
|
|
jim> a
|
|
2 3 1</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The static variable <tt><em>a</em></tt> has no initialiser, so it is initialised from
|
|
the enclosing scope with the value 1. (Note that it is an error if there
|
|
is no variable with the same name in the enclosing scope). However <tt><em>b</em></tt>
|
|
has an initialiser, so it is initialised to 2.</p></div>
|
|
<div class="paragraph"><p>Unlike a local variable, the value of a static variable is retained across
|
|
invocations of the procedure.</p></div>
|
|
<div class="paragraph"><p>See the <a href="#_proc"><strong><tt>proc</tt></strong></a> command for information on how to define procedures
|
|
and what happens when they are invoked. See also NAMESPACES.</p></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_variables_scalars_and_arrays">VARIABLES - SCALARS AND ARRAYS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl allows the definition of variables and the use of their values
|
|
either through <em>$</em>-style variable substitution, the <a href="#_set"><strong><tt>set</tt></strong></a>
|
|
command, or a few other mechanisms.</p></div>
|
|
<div class="paragraph"><p>Variables need not be declared: a new variable will automatically
|
|
be created each time a new variable name is used.</p></div>
|
|
<div class="paragraph"><p>Tcl supports two types of variables: scalars and arrays.
|
|
A scalar variable has a single value, whereas an array variable
|
|
can have any number of elements, each with a name (called
|
|
its <em>index</em>) and a value.</p></div>
|
|
<div class="paragraph"><p>Array indexes may be arbitrary strings; they need not be numeric.
|
|
Parentheses are used refer to array elements in Tcl commands.
|
|
For example, the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set x(first) 44</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will modify the element of <em>x</em> whose index is <em>first</em>
|
|
so that its new value is <em>44</em>.</p></div>
|
|
<div class="paragraph"><p>Two-dimensional arrays can be simulated in Tcl by using indexes
|
|
that contain multiple concatenated values.
|
|
For example, the commands</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a(2,3) 1
|
|
set a(3,6) 2</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>set the elements of <em>a</em> whose indexes are <em>2,3</em> and <em>3,6</em>.</p></div>
|
|
<div class="paragraph"><p>In general, array elements may be used anywhere in Tcl that scalar
|
|
variables may be used.</p></div>
|
|
<div class="paragraph"><p>If an array is defined with a particular name, then there may
|
|
not be a scalar variable with the same name.</p></div>
|
|
<div class="paragraph"><p>Similarly, if there is a scalar variable with a particular
|
|
name then it is not possible to make array references to the
|
|
variable.</p></div>
|
|
<div class="paragraph"><p>To convert a scalar variable to an array or vice versa, remove
|
|
the existing variable with the <a href="#_unset"><strong><tt>unset</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_array"><strong><tt>array</tt></strong></a> command provides several features for dealing
|
|
with arrays, such as querying the names of all the elements of
|
|
the array and converting between an array and a list.</p></div>
|
|
<div class="paragraph"><p>Variables may be either global or local. If a variable
|
|
name is used when a procedure isn’t being executed, then it
|
|
automatically refers to a global variable. Variable names used
|
|
within a procedure normally refer to local variables associated with that
|
|
invocation of the procedure. Local variables are deleted whenever
|
|
a procedure exits. Either <a href="#_global"><strong><tt>global</tt></strong></a> command may be used to request
|
|
that a name refer to a global variable for the duration of the current
|
|
procedure (this is somewhat analogous to <em>extern</em> in C), or the variable
|
|
may be explicitly scoped with the <tt>::</tt> prefix. For example</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a 1
|
|
set b 2
|
|
proc p {} {
|
|
set c 3
|
|
global a</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt> puts "$a $::b $c"
|
|
}
|
|
p</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>1 2 3</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_arrays_as_lists_in_jim">ARRAYS AS LISTS IN JIM</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Unlike Tcl, Jim can automatically convert between a list (with an even
|
|
number of elements) and an array value. This is similar to the way Tcl
|
|
can convert between a string and a list.</p></div>
|
|
<div class="paragraph"><p>For example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a {1 one 2 two}
|
|
puts $a(2)</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>two</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Thus <a href="#_array"><strong><tt>array</tt></strong></a> <tt>set</tt> is equivalent to <a href="#_set"><strong><tt>set</tt></strong></a> when the variable does not
|
|
exist or is empty.</p></div>
|
|
<div class="paragraph"><p>The reverse is also true where an array will be converted into
|
|
a list.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a(1) one; set a(2) two
|
|
puts $a</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>1 one 2 two</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_dictionary_values">DICTIONARY VALUES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl 8.5 introduced the dict command, and Jim Tcl has added a version
|
|
of this command. Dictionaries provide efficient access to key-value
|
|
pairs, just like arrays, but dictionaries are pure values. This
|
|
means that you can pass them to a procedure just as a list or a
|
|
string. Tcl dictionaries are therefore much more like Tcl lists,
|
|
except that they represent a mapping from keys to values, rather
|
|
than an ordered sequence.</p></div>
|
|
<div class="paragraph"><p>You can nest dictionaries, so that the value for a particular key
|
|
consists of another dictionary. That way you can elegantly build
|
|
complicated data structures, such as hierarchical databases. You
|
|
can also combine dictionaries with other Tcl data structures. For
|
|
instance, you can build a list of dictionaries that themselves
|
|
contain lists.</p></div>
|
|
<div class="paragraph"><p>Dictionaries are values that contain an efficient, order-preserving
|
|
mapping from arbitrary keys to arbitrary values. Each key in the
|
|
dictionary maps to a single value. They have a textual format that
|
|
is exactly that of any list with an even number of elements, with
|
|
each mapping in the dictionary being represented as two items in
|
|
the list. When a command takes a dictionary and produces a new
|
|
dictionary based on it (either returning it or writing it back into
|
|
the variable that the starting dictionary was read from) the new
|
|
dictionary will have the same order of keys, modulo any deleted
|
|
keys and with new keys added on to the end. When a string is
|
|
interpreted as a dictionary and it would otherwise have duplicate
|
|
keys, only the last value for a particular key is used; the others
|
|
are ignored, meaning that, "apple banana" and "apple carrot apple
|
|
banana" are equivalent dictionaries (with different string
|
|
representations).</p></div>
|
|
<div class="paragraph"><p>Note that in Jim, arrays are implemented as dictionaries.
|
|
Thus automatic conversion between lists and dictionaries applies
|
|
as it does for arrays.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> dict set a 1 one
|
|
1 one
|
|
jim> dict set a 2 two
|
|
1 one 2 two
|
|
jim> puts $a
|
|
1 one 2 two
|
|
jim> puts $a(2)
|
|
two
|
|
jim> dict set a 3 T three
|
|
1 one 2 two 3 {T three}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See the <a href="#_dict"><strong><tt>dict</tt></strong></a> command for more details.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_namespaces">NAMESPACES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Tcl added namespaces as a mechanism avoiding name clashes, especially in applications
|
|
including a number of 3rd party components. While there is less need for namespaces
|
|
in Jim Tcl (which does not strive to support large applications), it is convenient to
|
|
provide a subset of the support for namespaces to easy porting code from Tcl.</p></div>
|
|
<div class="paragraph"><p>Jim Tcl currently supports "light-weight" namespaces which should be adequate for most
|
|
purposes. This feature is currently experimental. See README.namespaces for more information
|
|
and the documentation of the <a href="#_namespace"><strong><tt>namespace</tt></strong></a> command.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_garbage_collection_references_lambda">GARBAGE COLLECTION, REFERENCES, LAMBDA</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Unlike Tcl, Jim has some sophisticated support for functional programming.
|
|
These are described briefly below.</p></div>
|
|
<div class="paragraph"><p>More information may be found at <a href="http://wiki.tcl.tk/13847">http://wiki.tcl.tk/13847</a></p></div>
|
|
<div class="sect2">
|
|
<h3 id="_references">References</h3>
|
|
<div class="paragraph"><p>A reference can be thought of as holding a value with one level of indirection,
|
|
where the value may be garbage collected when unreferenced.
|
|
Consider the following example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> set r [ref "One String" test]
|
|
<reference.<test___>.00000000000000000000>
|
|
jim> getref $r
|
|
One String</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The operation <a href="#_ref"><strong><tt>ref</tt></strong></a> creates a references to the value specified by the
|
|
first argument. (The second argument is a "type" used for documentation purposes).</p></div>
|
|
<div class="paragraph"><p>The operation <a href="#_getref"><strong><tt>getref</tt></strong></a> is the dereferencing operation which retrieves the value
|
|
stored in the reference.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> setref $r "New String"
|
|
New String
|
|
jim> getref $r
|
|
New String</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The operation <a href="#_setref"><strong><tt>setref</tt></strong></a> replaces the value stored by the reference. If the old value
|
|
is no longer accessible by any reference, it will eventually be automatically be garbage
|
|
collected.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_garbage_collection">Garbage Collection</h3>
|
|
<div class="paragraph"><p>Normally, all values in Tcl are passed by value. As such values are copied and released
|
|
automatically as necessary.</p></div>
|
|
<div class="paragraph"><p>With the introduction of references, it is possible to create values whose lifetime
|
|
transcend their scope. To support this, case, the Jim system will periodically identify
|
|
and discard objects which are no longer accessible by any reference.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_collect"><strong><tt>collect</tt></strong></a> command may be used to force garbage collection. Consider a reference created
|
|
with a finalizer:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> proc f {ref value} { puts "Finaliser called for $ref,$value" }
|
|
jim> set r [ref "One String" test f]
|
|
<reference.<test___>.00000000000
|
|
jim> collect
|
|
0
|
|
jim> set r ""
|
|
jim> collect
|
|
Finaliser called for <reference.<test___>.00000000000,One String
|
|
1</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Note that once the reference, <em>r</em>, was modified so that it no longer
|
|
contained a reference to the value, the garbage collector discarded
|
|
the value (after calling the finalizer).</p></div>
|
|
<div class="paragraph"><p>The finalizer for a reference may be examined or changed with the <a href="#_finalize"><strong><tt>finalize</tt></strong></a> command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> finalize $r
|
|
f
|
|
jim> finalize $r newf
|
|
newf</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lambda">Lambda</h3>
|
|
<div class="paragraph"><p>Jim provides a garbage collected lambda function. This is a procedure
|
|
which is able to create an anonymous procedure. Consider:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> set f [lambda {a} {{x 0}} { incr x $a }]
|
|
jim> $f 1
|
|
1
|
|
jim> $f 2
|
|
3
|
|
jim> set f ""</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This create an anonymous procedure (with the name stored in <em>f</em>), with a static variable
|
|
which is incremented by the supplied value and the result returned.</p></div>
|
|
<div class="paragraph"><p>Once the procedure name is no longer accessible, it will automatically be deleted
|
|
when the garbage collector runs.</p></div>
|
|
<div class="paragraph"><p>The procedure may also be delete immediately by renaming it "". e.g.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> rename $f ""</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_utf_8_and_unicode">UTF-8 AND UNICODE</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>If Jim is built with UTF-8 support enabled (configure --enable-utf),
|
|
then most string-related commands become UTF-8 aware. These include,
|
|
but are not limited to, <a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>, <a href="#_split"><strong><tt>split</tt></strong></a>, <a href="#_glob"><strong><tt>glob</tt></strong></a>, <a href="#_scan"><strong><tt>scan</tt></strong></a> and
|
|
<a href="#_format"><strong><tt>format</tt></strong></a>.</p></div>
|
|
<div class="paragraph"><p>UTF-8 encoding has many advantages, but one of the complications is that
|
|
characters can take a variable number of bytes. Thus the addition of
|
|
<a href="#_string"><strong><tt>string</tt></strong></a> <tt>bytelength</tt> which returns the number of bytes in a string,
|
|
while <a href="#_string"><strong><tt>string</tt></strong></a> <tt>length</tt> returns the number of characters.</p></div>
|
|
<div class="paragraph"><p>If UTF-8 support is not enabled, all commands treat bytes as characters
|
|
and <a href="#_string"><strong><tt>string</tt></strong></a> <tt>bytelength</tt> returns the same value as <a href="#_string"><strong><tt>string</tt></strong></a> <tt>length</tt>.</p></div>
|
|
<div class="paragraph"><p>Note that even if UTF-8 support is not enabled, the <tt>\uNNNN</tt> and related syntax
|
|
is still available to embed UTF-8 sequences.</p></div>
|
|
<div class="paragraph"><p>Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +<em>U+1FFFFF</em>.</p></div>
|
|
<div class="sect2">
|
|
<h3 id="_string_matching">String Matching</h3>
|
|
<div class="paragraph"><p>Commands such as <a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>, <a href="#_lsearch"><strong><tt>lsearch</tt></strong></a> <tt>-glob</tt>, <a href="#_array"><strong><tt>array</tt></strong></a> <tt>names</tt> and others use string
|
|
pattern matching rules. These commands support UTF-8. For example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>string match a\[\ua0-\ubf\]b "a\u00a3b"</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_format_and_scan">format and scan</h3>
|
|
<div class="paragraph"><p><tt>format %c</tt> allows a unicode codepoint to be be encoded. For example, the following will return
|
|
a string with two bytes and one character. The same as <tt>\ub5</tt></p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>format %c 0xb5</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_format"><strong><tt>format</tt></strong></a> respects widths as character widths, not byte widths. For example, the following will
|
|
return a string with three characters, not three bytes.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>format %.3s \ub5\ub6\ub7\ub8</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Similarly, <tt>scan … %c</tt> allows a UTF-8 to be decoded to a unicode codepoint. The following will set
|
|
<tt><em>a</em></tt> to 181 (0xb5) and <tt><em>b</em></tt> to 65 (0x41).</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>scan \u00b5A %c%c a b</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_scan"><strong><tt>scan</tt></strong></a> <tt>%s</tt> will also accept a character class, including unicode ranges.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_string_classes">String Classes</h3>
|
|
<div class="paragraph"><p><a href="#_string"><strong><tt>string</tt></strong></a> <tt>is</tt> has <strong>not</strong> been extended to classify UTF-8 characters. Therefore, the following
|
|
will return 0, even though the string may be considered to be alphabetic.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>string is alpha \ub5Test</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This does not affect the string classes <em>ascii</em>, <em>control</em>, <em>digit</em>, <em>double</em>, <em>integer</em> or <em>xdigit</em>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_case_mapping_and_conversion">Case Mapping and Conversion</h3>
|
|
<div class="paragraph"><p>Jim provides a simplified unicode case mapping. This means that case conversion
|
|
and comparison will not increase or decrease the number of characters in a string.
|
|
(Although it may change the number of bytes).</p></div>
|
|
<div class="paragraph"><p><a href="#_string"><strong><tt>string</tt></strong></a> <tt>toupper</tt> will convert any lowercase letters to their uppercase equivalent.
|
|
Any character which is not a letter or has no uppercase equivalent is left unchanged.
|
|
Similarly for <a href="#_string"><strong><tt>string</tt></strong></a> <tt>tolower</tt> and <a href="#_string"><strong><tt>string</tt></strong></a> <tt>totitle</tt>.</p></div>
|
|
<div class="paragraph"><p>Commands which perform case insensitive matches, such as <a href="#_string"><strong><tt>string</tt></strong></a> <tt>compare -nocase</tt>
|
|
and <a href="#_lsearch"><strong><tt>lsearch</tt></strong></a> <tt>-nocase</tt> fold both strings to uppercase before comparison.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_invalid_utf_8_sequences">Invalid UTF-8 Sequences</h3>
|
|
<div class="paragraph"><p>Some UTF-8 character sequences are invalid, such as those beginning with <em>0xff</em>,
|
|
those which represent character sequences longer than 3 bytes (greater than U+FFFF),
|
|
and those which end prematurely, such as a lone <em>0xc2</em>.</p></div>
|
|
<div class="paragraph"><p>In these situations, the offending bytes are treated as single characters. For example,
|
|
the following returns 2.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>string bytelength \xff\xff</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_regular_expressions_2">Regular Expressions</h3>
|
|
<div class="paragraph"><p>If UTF-8 support is enabled, the built-in regular expression engine will be
|
|
selected which supports UTF-8 strings and patterns.</p></div>
|
|
<div class="paragraph"><p>See REGULAR EXPRESSIONS</p></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_built_in_commands">BUILT-IN COMMANDS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The Tcl library provides the following built-in commands, which will
|
|
be available in any application using Tcl. In addition to these
|
|
built-in commands, there may be additional commands defined by each
|
|
application, plus commands defined as Tcl procedures.</p></div>
|
|
<div class="paragraph"><p>In the command syntax descriptions below, words in <tt><strong>boldface</strong></tt> are
|
|
literals that you type verbatim to Tcl.</p></div>
|
|
<div class="paragraph"><p>Words in <tt><em>italics</em></tt> are meta-symbols; they serve as names for any of
|
|
a range of values that you can type.</p></div>
|
|
<div class="paragraph"><p>Optional arguments or groups of arguments are indicated by enclosing them
|
|
in <tt>?question-marks?</tt>.</p></div>
|
|
<div class="paragraph"><p>Ellipses (<tt>...</tt>) indicate that any number of additional
|
|
arguments or groups of arguments may appear, in the same format
|
|
as the preceding argument(s).</p></div>
|
|
<div class="sect2">
|
|
<h3 id="CommandIndex">Command Index</h3>
|
|
<div class="tableblock">
|
|
<table rules="none"
|
|
width="100%"
|
|
frame="void"
|
|
cellspacing="0" cellpadding="4">
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<col width="12%" />
|
|
<tbody>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><tt>after</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_aio"><strong><tt>aio</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_alarm"><strong><tt>alarm</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_alias"><strong><tt>alias</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_append"><strong><tt>append</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_apply"><strong><tt>apply</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_array"><strong><tt>array</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_binary"><strong><tt>binary</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_break"><strong><tt>break</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_case"><strong><tt>case</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_catch"><strong><tt>catch</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_cd"><strong><tt>cd</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><tt>class</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_clock"><strong><tt>clock</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_close"><strong><tt>close</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_collect"><strong><tt>collect</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_concat"><strong><tt>concat</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_continue"><strong><tt>continue</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_curry"><strong><tt>curry</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_dict"><strong><tt>dict</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_env"><strong><tt>env</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_eof"><strong><tt>eof</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_error"><strong><tt>error</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_eval"><strong><tt>eval</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><tt>eventloop</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exec"><strong><tt>exec</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exists"><strong><tt>exists</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exit"><strong><tt>exit</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_expr"><strong><tt>expr</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_fconfigure"><strong><tt>fconfigure</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_file"><strong><tt>file</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_finalize"><strong><tt>finalize</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_flush"><strong><tt>flush</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_for"><strong><tt>for</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_foreach"><strong><tt>foreach</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_format"><strong><tt>format</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_getref"><strong><tt>getref</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_gets"><strong><tt>gets</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_glob"><strong><tt>glob</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_global"><strong><tt>global</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_history"><strong><tt>history</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_if"><strong><tt>if</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_incr"><strong><tt>incr</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_info"><strong><tt>info</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_join"><strong><tt>join</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_kill"><strong><tt>kill</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lambda"><strong><tt>lambda</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lappend"><strong><tt>lappend</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lassign"><strong><tt>lassign</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lindex"><strong><tt>lindex</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_linsert"><strong><tt>linsert</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_list"><strong><tt>list</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_llength"><strong><tt>llength</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lmap"><strong><tt>lmap</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_load"><strong><tt>load</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_local"><strong><tt>local</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_loop"><strong><tt>loop</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lrange"><strong><tt>lrange</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lrepeat"><strong><tt>lrepeat</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lreplace"><strong><tt>lreplace</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lreverse"><strong><tt>lreverse</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lsearch"><strong><tt>lsearch</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lset"><strong><tt>lset</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lsort"><strong><tt>lsort</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_namespace"><strong><tt>namespace</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><tt>oo</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_open"><strong><tt>open</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>os.fork</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>os.gethostname</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>os.getids</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>os.uptime</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>os.wait</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><tt>pack</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><tt>pack</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_package"><strong><tt>package</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_pid"><strong><tt>pid</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><tt>posix</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_proc"><strong><tt>proc</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_puts"><strong><tt>puts</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_pwd"><strong><tt>pwd</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_rand"><strong><tt>rand</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_range"><strong><tt>range</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_read"><strong><tt>read</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_ref"><strong><tt>ref</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_regexp"><strong><tt>regexp</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_regsub"><strong><tt>regsub</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_rename"><strong><tt>rename</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_return"><strong><tt>return</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_scan"><strong><tt>scan</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_seek"><strong><tt>seek</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_set"><strong><tt>set</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_setref"><strong><tt>setref</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_signal"><strong><tt>signal</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_sleep"><strong><tt>sleep</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_socket"><strong><tt>socket</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_source"><strong><tt>source</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_split"><strong><tt>split</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_stackdump"><strong><tt>stackdump</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_stacktrace"><strong><tt>stacktrace</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_string"><strong><tt>string</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_subst"><strong><tt>subst</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><tt>super</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_switch"><strong><tt>switch</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_syslog"><strong><tt>syslog</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tailcall"><strong><tt>tailcall</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tcl_prefix"><strong><tt>tcl::prefix</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tell"><strong><tt>tell</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_throw"><strong><tt>throw</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_time"><strong><tt>time</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tree"><strong><tt>tree</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_try"><strong><tt>try</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_unknown"><strong><tt>unknown</tt></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><tt>unpack</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_unset"><strong><tt>unset</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_upcall"><strong><tt>upcall</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><tt>update</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_uplevel"><strong><tt>uplevel</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_upvar"><strong><tt>upvar</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><tt>vwait</tt></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_while"><strong><tt>while</tt></strong></a></p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_alarm">alarm</h3>
|
|
<div class="paragraph"><p><tt><strong>alarm</strong> <em>seconds</em></tt></p></div>
|
|
<div class="paragraph"><p>Delivers the <tt>SIGALRM</tt> signal to the process after the given
|
|
number of seconds. If the platform supports <em>ualarm(3)</em> then
|
|
the argument may be a floating point value. Otherwise it must
|
|
be an integer.</p></div>
|
|
<div class="paragraph"><p>Note that unless a signal handler for <tt>SIGALRM</tt> has been installed
|
|
(see <a href="#_signal"><strong><tt>signal</tt></strong></a>), the process will exit on this signal.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_alias">alias</h3>
|
|
<div class="paragraph"><p><tt><strong>alias</strong> <em>name args...</em></tt></p></div>
|
|
<div class="paragraph"><p>Creates a single word alias (command) for one or more words. For example,
|
|
the following creates an alias for the command <a href="#_info"><strong><tt>info</tt></strong></a> <tt>exists</tt>.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>alias e info exists
|
|
if {[e var]} {
|
|
...
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_alias"><strong><tt>alias</tt></strong></a> returns <tt><em>name</em></tt>, allowing it to be used with <a href="#_local"><strong><tt>local</tt></strong></a>.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_proc"><strong><tt>proc</tt></strong></a>, <a href="#_curry"><strong><tt>curry</tt></strong></a>, <a href="#_lambda"><strong><tt>lambda</tt></strong></a>, <a href="#_local"><strong><tt>local</tt></strong></a>, <a href="#_info"><strong><tt>info</tt></strong></a> <tt>alias</tt>, <a href="#_exists"><strong><tt>exists</tt></strong></a> <tt>-alias</tt></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_append">append</h3>
|
|
<div class="paragraph"><p><tt><strong>append</strong> <em>varName value ?value value …?</em></tt></p></div>
|
|
<div class="paragraph"><p>Append all of the <tt><em>value</em></tt> arguments to the current value
|
|
of variable <tt><em>varName</em></tt>. If <tt><em>varName</em></tt> doesn’t exist,
|
|
it is given a value equal to the concatenation of all the
|
|
<tt><em>value</em></tt> arguments.</p></div>
|
|
<div class="paragraph"><p>This command provides an efficient way to build up long
|
|
variables incrementally.
|
|
For example, "<a href="#_append"><strong><tt>append</tt></strong></a> <tt>a $b</tt>" is much more efficient than
|
|
"<a href="#_set"><strong><tt>set</tt></strong></a> <tt>a $a$b</tt>" if <tt>$a</tt> is long.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_apply">apply</h3>
|
|
<div class="paragraph"><p><tt><strong>apply</strong> <em>lambdaExpr ?arg1 arg2 ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>The command <a href="#_apply"><strong><tt>apply</tt></strong></a> provides for anonymous procedure calls,
|
|
similar to <a href="#_lambda"><strong><tt>lambda</tt></strong></a>, but without command name being created, even temporarily.</p></div>
|
|
<div class="paragraph"><p>The function <tt><em>lambdaExpr</em></tt> is a two element list <tt>{args body}</tt>
|
|
or a three element list <tt>{args body namespace}</tt>. The first element
|
|
args specifies the formal arguments, in the same form as the <a href="#_proc"><strong><tt>proc</tt></strong></a> and <a href="#_lambda"><strong><tt>lambda</tt></strong></a> commands.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_array">array</h3>
|
|
<div class="paragraph"><p><tt><strong>array</strong> <em>option arrayName ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command performs one of several operations on the
|
|
variable given by <tt><em>arrayName</em></tt>.</p></div>
|
|
<div class="paragraph"><p>Note that in general, if the named array does not exist, the <tt><em>array</em></tt> command behaves
|
|
as though the array exists but is empty.</p></div>
|
|
<div class="paragraph"><p>The <tt><em>option</em></tt> argument determines what action is carried out by the
|
|
command. The legal <tt><em>options</em></tt> (which may be abbreviated) are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array exists</strong> <em>arrayName</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if arrayName is an array variable, 0 if there is
|
|
no variable by that name. This command is essentially
|
|
identical to <a href="#_info"><strong><tt>info</tt></strong></a> <tt>exists</tt>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array get</strong> <em>arrayName ?pattern?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing pairs of elements. The first
|
|
element in each pair is the name of an element in arrayName
|
|
and the second element of each pair is the value of the
|
|
array element. The order of the pairs is undefined. If
|
|
pattern is not specified, then all of the elements of the
|
|
array are included in the result. If pattern is specified,
|
|
then only those elements whose names match pattern (using
|
|
the matching rules of string match) are included. If arrayName
|
|
isn’t the name of an array variable, or if the array contains
|
|
no elements, then an empty list is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array names</strong> <em>arrayName ?pattern?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing the names of all of the elements
|
|
in the array that match pattern. If pattern is omitted then
|
|
the command returns all of the element names in the array.
|
|
If pattern is specified, then only those elements whose
|
|
names match pattern (using the matching rules of string
|
|
match) are included. If there are no (matching) elements
|
|
in the array, or if arrayName isn’t the name of an array
|
|
variable, then an empty string is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array set</strong> <em>arrayName list</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets the values of one or more elements in arrayName. list
|
|
must have a form like that returned by array get, consisting
|
|
of an even number of elements. Each odd-numbered element
|
|
in list is treated as an element name within arrayName, and
|
|
the following element in list is used as a new value for
|
|
that array element. If the variable arrayName does not
|
|
already exist and list is empty, arrayName is created with
|
|
an empty array value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array size</strong> <em>arrayName</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the number of elements in the array. If arrayName
|
|
isn’t the name of an array then 0 is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>array unset</strong> <em>arrayName ?pattern?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unsets all of the elements in the array that match pattern
|
|
(using the matching rules of string match). If arrayName
|
|
isn’t the name of an array variable or there are no matching
|
|
elements in the array, no error will be raised. If pattern
|
|
is omitted and arrayName is an array variable, then the
|
|
command unsets the entire array. The command always returns
|
|
an empty string.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_break">break</h3>
|
|
<div class="paragraph"><p><tt><strong>break</strong></tt></p></div>
|
|
<div class="paragraph"><p>This command may be invoked only inside the body of a loop command
|
|
such as <a href="#_for"><strong><tt>for</tt></strong></a> or <a href="#_foreach"><strong><tt>foreach</tt></strong></a> or <a href="#_while"><strong><tt>while</tt></strong></a>. It returns a <tt>JIM_BREAK</tt> code
|
|
to signal the innermost containing loop command to return immediately.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_case">case</h3>
|
|
<div class="paragraph"><p><tt><strong>case</strong> <em>string</em> ?in? <em>patList body ?patList body …?</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>case</strong> <em>string</em> ?in? {<em>patList body ?patList body …?</em>}</tt></p></div>
|
|
<div class="paragraph"><p><strong>Note</strong> that the <a href="#_switch"><strong><tt>switch</tt></strong></a> command should generally be preferred unless compatibility
|
|
with Tcl 6.x is desired.</p></div>
|
|
<div class="paragraph"><p>Match <tt><em>string</em></tt> against each of the <tt><em>patList</em></tt> arguments
|
|
in order. If one matches, then evaluate the following <tt><em>body</em></tt> argument
|
|
by passing it recursively to the Tcl interpreter, and return the result
|
|
of that evaluation. Each <tt><em>patList</em></tt> argument consists of a single
|
|
pattern or list of patterns. Each pattern may contain any of the wild-cards
|
|
described under <a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.</p></div>
|
|
<div class="paragraph"><p>If a <tt><em>patList</em></tt> argument is <tt>default</tt>, the corresponding body will be
|
|
evaluated if no <tt><em>patList</em></tt> matches <tt><em>string</em></tt>. If no <tt><em>patList</em></tt> argument
|
|
matches <tt><em>string</em></tt> and no default is given, then the <a href="#_case"><strong><tt>case</tt></strong></a> command returns
|
|
an empty string.</p></div>
|
|
<div class="paragraph"><p>Two syntaxes are provided.</p></div>
|
|
<div class="paragraph"><p>The first uses a separate argument for each of the patterns and commands;
|
|
this form is convenient if substitutions are desired on some of the
|
|
patterns or commands.</p></div>
|
|
<div class="paragraph"><p>The second form places all of the patterns and commands together into
|
|
a single argument; the argument must have proper list structure, with
|
|
the elements of the list being the patterns and commands.</p></div>
|
|
<div class="paragraph"><p>The second form makes it easy to construct multi-line case commands,
|
|
since the braces around the whole list make it unnecessary to include a
|
|
backslash at the end of each line.</p></div>
|
|
<div class="paragraph"><p>Since the <tt><em>patList</em></tt> arguments are in braces in the second form,
|
|
no command or variable substitutions are performed on them; this makes
|
|
the behaviour of the second form different than the first form in some
|
|
cases.</p></div>
|
|
<div class="paragraph"><p>Below are some examples of <a href="#_case"><strong><tt>case</tt></strong></a> commands:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>case abc in {a b} {format 1} default {format 2} a* {format 3}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return <em>3</em>,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>case a in {
|
|
{a b} {format 1}
|
|
default {format 2}
|
|
a* {format 3}
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return <em>1</em>, and</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>case xyz {
|
|
{a b}
|
|
{format 1}
|
|
default
|
|
{format 2}
|
|
a*
|
|
{format 3}
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return <em>2</em>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_catch">catch</h3>
|
|
<div class="paragraph"><p><tt><strong>catch</strong> ?-?no?<em>code ...</em>? ?--? <em>command ?resultVarName? ?optionsVarName?</em></tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_catch"><strong><tt>catch</tt></strong></a> command may be used to prevent errors from aborting
|
|
command interpretation. <a href="#_catch"><strong><tt>catch</tt></strong></a> evaluates <tt><em>command</em></tt>, and returns a
|
|
<tt>JIM_OK</tt> code, regardless of any errors that might occur while
|
|
executing <tt><em>command</em></tt> (with the possible exception of <tt>JIM_SIGNAL</tt> -
|
|
see below).</p></div>
|
|
<div class="paragraph"><p>The return value from <a href="#_catch"><strong><tt>catch</tt></strong></a> is a decimal string giving the code
|
|
returned by the Tcl interpreter after executing <tt><em>command</em></tt>. This
|
|
will be <em>0</em> (<tt>JIM_OK</tt>) if there were no errors in <tt><em>command</em></tt>; otherwise
|
|
it will have a non-zero value corresponding to one of the exceptional
|
|
return codes (see jim.h for the definitions of code values, or the
|
|
<a href="#_info"><strong><tt>info</tt></strong></a> <tt>returncodes</tt> command).</p></div>
|
|
<div class="paragraph"><p>If the <tt><em>resultVarName</em></tt> argument is given, then it gives the name
|
|
of a variable; <a href="#_catch"><strong><tt>catch</tt></strong></a> will set the value of the variable to the
|
|
string returned from <tt><em>command</em></tt> (either a result or an error message).</p></div>
|
|
<div class="paragraph"><p>If the <tt><em>optionsVarName</em></tt> argument is given, then it gives the name
|
|
of a variable; <a href="#_catch"><strong><tt>catch</tt></strong></a> will set the value of the variable to a
|
|
dictionary. For any return code other than <tt>JIM_RETURN</tt>, the value
|
|
for the key <tt>-code</tt> will be set to the return code. For <tt>JIM_RETURN</tt>
|
|
it will be set to the code given in <a href="#_return"><strong><tt>return</tt></strong></a> <tt>-code</tt>. Additionally,
|
|
for the return code <tt>JIM_ERR</tt>, the value of the key <tt>-errorinfo</tt>
|
|
will contain the current stack trace (the same result as <a href="#_info"><strong><tt>info</tt></strong></a> <tt>stacktrace</tt>),
|
|
the value of the key <tt>-errorcode</tt> will contain the
|
|
same value as the global variable $::errorCode, and the value of
|
|
the key <tt>-level</tt> will be the current return level (see <a href="#_return"><strong><tt>return</tt></strong></a> <tt>-level</tt>).
|
|
This can be useful to rethrow an error:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>if {[catch {...} msg opts]} {
|
|
...maybe do something with the error...
|
|
incr opts(-level)
|
|
return {*}$opts $msg
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Normally <a href="#_catch"><strong><tt>catch</tt></strong></a> will <tt><em>not</em></tt> catch any of the codes <tt>JIM_EXIT</tt>, <tt>JIM_EVAL</tt> or <tt>JIM_SIGNAL</tt>.
|
|
The set of codes which will be caught may be modified by specifying the one more codes before
|
|
<tt><em>command</em></tt>.</p></div>
|
|
<div class="paragraph"><p>e.g. To catch <tt>JIM_EXIT</tt> but not <tt>JIM_BREAK</tt> or <tt>JIM_CONTINUE</tt></p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>catch -exit -nobreak -nocontinue -- { ... }</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The use of <tt>--</tt> is optional. It signifies that no more return code options follow.</p></div>
|
|
<div class="paragraph"><p>Note that if a signal marked as <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>handle</tt> is caught with <a href="#_catch"><strong><tt>catch</tt></strong></a> <tt>-signal</tt>, the return value
|
|
(stored in <tt><em>resultVarName</em></tt>) is name of the signal caught.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_cd">cd</h3>
|
|
<div class="paragraph"><p><tt><strong>cd</strong> <em>dirName</em></tt></p></div>
|
|
<div class="paragraph"><p>Change the current working directory to <tt><em>dirName</em></tt>.</p></div>
|
|
<div class="paragraph"><p>Returns an empty string.</p></div>
|
|
<div class="paragraph"><p>This command can potentially be disruptive to an application, so it may
|
|
be removed in some applications.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_clock">clock</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>clock seconds</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current time as seconds since the epoch.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>clock format</strong> <em>seconds</em> ?<strong>-format</strong> <em>format?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Format the given time (seconds since the epoch) according to the given
|
|
format. See strftime(3) for supported formats.
|
|
If no format is supplied, "%c" is used.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>clock scan</strong> <em>str</em> <strong>-format</strong> <em>format</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Scan the given time string using the given format string.
|
|
See strptime(3) for supported formats.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_close">close</h3>
|
|
<div class="paragraph"><p><tt><strong>close</strong> <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>close</strong></tt></p></div>
|
|
<div class="paragraph"><p>Closes the file given by <tt><em>fileId</em></tt>.
|
|
<tt><em>fileId</em></tt> must be the return value from a previous invocation
|
|
of the <a href="#_open"><strong><tt>open</tt></strong></a> command; after this command, it should not be
|
|
used anymore.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_collect">collect</h3>
|
|
<div class="paragraph"><p><tt><strong>collect</strong></tt></p></div>
|
|
<div class="paragraph"><p>Normally reference garbage collection is automatically performed periodically.
|
|
However it may be run immediately with the <a href="#_collect"><strong><tt>collect</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_concat">concat</h3>
|
|
<div class="paragraph"><p><tt><strong>concat</strong> <em>arg ?arg ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command treats each argument as a list and concatenates them
|
|
into a single list. It permits any number of arguments. For example,
|
|
the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>concat a b {c d e} {f {g h}}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>a b c d e f {g h}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>as its result.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_continue">continue</h3>
|
|
<div class="paragraph"><p><tt><strong>continue</strong></tt></p></div>
|
|
<div class="paragraph"><p>This command may be invoked only inside the body of a loop command such
|
|
as <a href="#_for"><strong><tt>for</tt></strong></a> or <a href="#_foreach"><strong><tt>foreach</tt></strong></a> or <a href="#_while"><strong><tt>while</tt></strong></a>. It returns a <tt>JIM_CONTINUE</tt> code to
|
|
signal the innermost containing loop command to skip the remainder of
|
|
the loop’s body but continue with the next iteration of the loop.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_curry">curry</h3>
|
|
<div class="paragraph"><p><tt><strong>alias</strong> <em>args...</em></tt></p></div>
|
|
<div class="paragraph"><p>Similar to <a href="#_alias"><strong><tt>alias</tt></strong></a> except it creates an anonymous procedure (lambda) instead of
|
|
a named procedure.</p></div>
|
|
<div class="paragraph"><p>the following creates a local, unnamed alias for the command <a href="#_info"><strong><tt>info</tt></strong></a> <tt>exists</tt>.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set e [local curry info exists]
|
|
if {[$e var]} {
|
|
...
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_curry"><strong><tt>curry</tt></strong></a> returns the name of the procedure.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_proc"><strong><tt>proc</tt></strong></a>, <a href="#_alias"><strong><tt>alias</tt></strong></a>, <a href="#_lambda"><strong><tt>lambda</tt></strong></a>, <a href="#_local"><strong><tt>local</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_dict">dict</h3>
|
|
<div class="paragraph"><p><tt><strong>dict</strong> <em>option ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Performs one of several operations on dictionary values.</p></div>
|
|
<div class="paragraph"><p>The <tt><em>option</em></tt> argument determines what action is carried out by the
|
|
command. The legal <tt><em>options</em></tt> are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict create</strong> <em>?key value ...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Create and return a new dictionary value that contains each of
|
|
the key/value mappings listed as arguments (keys and values
|
|
alternating, with each key being followed by its associated
|
|
value.)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict exists</strong> <em>dictionary key ?key ...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a boolean value indicating whether the given key (or path
|
|
of keys through a set of nested dictionaries) exists in the given
|
|
dictionary value. This returns a true value exactly when <a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>get</tt>
|
|
on that path will succeed.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict get</strong> <em>dictionary ?key ...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Given a dictionary value (first argument) and a key (second argument),
|
|
this will retrieve the value for that key. Where several keys are
|
|
supplied, the behaviour of the command shall be as if the result
|
|
of "<a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>get $dictVal $key</tt>" was passed as the first argument to
|
|
dict get with the remaining arguments as second (and possibly
|
|
subsequent) arguments. This facilitates lookups in nested dictionaries.
|
|
If no keys are provided, dict would return a list containing pairs
|
|
of elements in a man- ner similar to array get. That is, the first
|
|
element of each pair would be the key and the second element would
|
|
be the value for that key. It is an error to attempt to retrieve
|
|
a value for a key that is not present in the dictionary.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict keys</strong> <em>dictionary ?pattern?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of the keys in the dictionary.
|
|
If pattern is specified, then only those keys whose
|
|
names match <tt><em>pattern</em></tt> (using the matching rules of string
|
|
match) are included.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict merge</strong> ?<em>dictionary ...</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a dictionary that contains the contents of each of the
|
|
<tt><em>dictionary</em></tt> arguments. Where two (or more) dictionaries
|
|
contain a mapping for the same key, the resulting dictionary
|
|
maps that key to the value according to the last dictionary on
|
|
the command line containing a mapping for that key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict set</strong> <em>dictionaryName key ?key ...? value</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This operation takes the <tt><em>name</em></tt> of a variable containing a dictionary
|
|
value and places an updated dictionary value in that variable
|
|
containing a mapping from the given key to the given value. When
|
|
multiple keys are present, this operation creates or updates a chain
|
|
of nested dictionaries.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict size</strong> <em>dictionary</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return the number of key/value mappings in the given dictionary value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict unset</strong> <em>dictionaryName key ?key ...? value</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This operation (the companion to <a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>set</tt>) takes the name of a
|
|
variable containing a dictionary value and places an updated
|
|
dictionary value in that variable that does not contain a mapping
|
|
for the given key. Where multiple keys are present, this describes
|
|
a path through nested dictionaries to the mapping to remove. At
|
|
least one key must be specified, but the last key on the key-path
|
|
need not exist. All other components on the path must exist.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>dict with</strong> <em>dictionaryName key ?key ...? script</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Execute the Tcl script in <tt><em>script</em></tt> with the value for each
|
|
key in <tt><em>dictionaryName</em></tt> mapped to a variable with the same
|
|
name. Where one or more keys are given, these indicate a chain
|
|
of nested dictionaries, with the innermost dictionary being the
|
|
one opened out for the execution of body. Making <tt><em>dictionaryName</em></tt>
|
|
unreadable will make the updates to the dictionary be discarded,
|
|
and this also happens if the contents of <tt><em>dictionaryName</em></tt> are
|
|
adjusted so that the chain of dictionaries no longer exists.
|
|
The result of <a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>with</tt> is (unless some kind of error occurs)
|
|
the result of the evaluation of body.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The variables are mapped in the scope enclosing the <a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>with</tt>;
|
|
it is recommended that this command only be used in a local
|
|
scope (procedure). Because of this, the variables set by
|
|
<a href="#_dict"><strong><tt>dict</tt></strong></a> <tt>with</tt> will continue to exist after the command finishes (unless
|
|
explicitly unset). Note that changes to the contents of <tt><em>dictionaryName</em></tt>
|
|
only happen when <tt><em>script</em></tt> terminates.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_env">env</h3>
|
|
<div class="paragraph"><p><tt><strong>env</strong> <em>?name? ?default?</em></tt></p></div>
|
|
<div class="paragraph"><p>If <tt><em>name</em></tt> is supplied, returns the value of <tt><em>name</em></tt> from the initial
|
|
environment (see getenv(3)). An error is returned if <tt><em>name</em></tt> does not
|
|
exist in the environment, unless <tt><em>default</em></tt> is supplied - in which case
|
|
that value is returned instead.</p></div>
|
|
<div class="paragraph"><p>If no arguments are supplied, returns a list of all environment variables
|
|
and their values as <tt>{name value ...}</tt></p></div>
|
|
<div class="paragraph"><p>See also the global variable <tt>::env</tt></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eof">eof</h3>
|
|
<div class="paragraph"><p><tt><strong>eof</strong> <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>eof</strong></tt></p></div>
|
|
<div class="paragraph"><p>Returns 1 if an end-of-file condition has occurred on <tt><em>fileId</em></tt>,
|
|
0 otherwise.</p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em></tt> must have been the return value from a previous call to <a href="#_open"><strong><tt>open</tt></strong></a>,
|
|
or it may be <tt>stdin</tt>, <tt>stdout</tt>, or <tt>stderr</tt> to refer to one of the
|
|
standard I/O channels.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_error">error</h3>
|
|
<div class="paragraph"><p><tt><strong>error</strong> <em>message ?stacktrace?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a <tt>JIM_ERR</tt> code, which causes command interpretation to be
|
|
unwound. <tt><em>message</em></tt> is a string that is returned to the application
|
|
to indicate what went wrong.</p></div>
|
|
<div class="paragraph"><p>If the <tt><em>stacktrace</em></tt> argument is provided and is non-empty,
|
|
it is used to initialize the stacktrace.</p></div>
|
|
<div class="paragraph"><p>This feature is most useful in conjunction with the <a href="#_catch"><strong><tt>catch</tt></strong></a> command:
|
|
if a caught error cannot be handled successfully, <tt><em>stacktrace</em></tt> can be used
|
|
to return a stack trace reflecting the original point of occurrence
|
|
of the error:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>catch {...} errMsg
|
|
...
|
|
error $errMsg [info stacktrace]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See also <tt>errorInfo</tt>, <a href="#_info"><strong><tt>info</tt></strong></a> <tt>stacktrace</tt>, <a href="#_catch"><strong><tt>catch</tt></strong></a> and <a href="#_return"><strong><tt>return</tt></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_errorinfo">errorInfo</h3>
|
|
<div class="paragraph"><p><tt><strong>errorInfo</strong> <em>error ?stacktrace?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a human-readable representation of the given error message and stack trace.
|
|
Typical usage is:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>if {[catch {...} error]} {
|
|
puts stderr [errorInfo $error [info stacktrace]]
|
|
exit 1
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See also <a href="#_error"><strong><tt>error</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eval">eval</h3>
|
|
<div class="paragraph"><p><tt><strong>eval</strong> <em>arg ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p><a href="#_eval"><strong><tt>eval</tt></strong></a> takes one or more arguments, which together comprise a Tcl
|
|
command (or collection of Tcl commands separated by newlines in the
|
|
usual way). <a href="#_eval"><strong><tt>eval</tt></strong></a> concatenates all its arguments in the same
|
|
fashion as the <a href="#_concat"><strong><tt>concat</tt></strong></a> command, passes the concatenated string to the
|
|
Tcl interpreter recursively, and returns the result of that
|
|
evaluation (or any error generated by it).</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_exec">exec</h3>
|
|
<div class="paragraph"><p><tt><strong>exec</strong> <em>arg ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command treats its arguments as the specification
|
|
of one or more UNIX commands to execute as subprocesses.
|
|
The commands take the form of a standard shell pipeline;
|
|
<tt>|</tt> arguments separate commands in the
|
|
pipeline and cause standard output of the preceding command
|
|
to be piped into standard input of the next command (or <tt>|&</tt> for
|
|
both standard output and standard error).</p></div>
|
|
<div class="paragraph"><p>Under normal conditions the result of the <a href="#_exec"><strong><tt>exec</tt></strong></a> command
|
|
consists of the standard output produced by the last command
|
|
in the pipeline.</p></div>
|
|
<div class="paragraph"><p>If any of the commands in the pipeline exit abnormally or
|
|
are killed or suspended, then <a href="#_exec"><strong><tt>exec</tt></strong></a> will return an error
|
|
and the error message will include the pipeline’s output followed by
|
|
error messages describing the abnormal terminations.</p></div>
|
|
<div class="paragraph"><p>If any of the commands writes to its standard error file,
|
|
then <a href="#_exec"><strong><tt>exec</tt></strong></a> will return an error, and the error message
|
|
will include the pipeline’s output, followed by messages
|
|
about abnormal terminations (if any), followed by the standard error
|
|
output.</p></div>
|
|
<div class="paragraph"><p>If the last character of the result or error message
|
|
is a newline then that character is deleted from the result
|
|
or error message for consistency with normal
|
|
Tcl return values.</p></div>
|
|
<div class="paragraph"><p>An <tt><em>arg</em></tt> may have one of the following special forms:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>>filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard output of the last command in the pipeline
|
|
is redirected to the file. In this situation <a href="#_exec"><strong><tt>exec</tt></strong></a>
|
|
will normally return an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>>>filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>>@fileId</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard output of the last command in the pipeline is
|
|
redirected to the given (writable) file descriptor (e.g. stdout,
|
|
stderr, or the result of <a href="#_open"><strong><tt>open</tt></strong></a>). In this situation <a href="#_exec"><strong><tt>exec</tt></strong></a>
|
|
will normally return an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>2>filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard error of the last command in the pipeline
|
|
is redirected to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>2>>filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>2>@fileId</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard error of the last command in the pipeline is
|
|
redirected to the given (writable) file descriptor.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>2>@1</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard error of the last command in the pipeline is
|
|
redirected to the same file descriptor as the standard output.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>>&filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Both the standard output and standard error of the last command
|
|
in the pipeline is redirected to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>>>&filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><filename</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard input of the first command in the pipeline
|
|
is taken from the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><<string</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard input of the first command is taken as the
|
|
given immediate value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><@fileId</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard input of the first command in the pipeline
|
|
is taken from the given (readable) file descriptor.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>If there is no redirection of standard input, standard error
|
|
or standard output, these are connected to the corresponding
|
|
input or output of the application.</p></div>
|
|
<div class="paragraph"><p>If the last <tt><em>arg</em></tt> is <tt>&</tt> then the command will be
|
|
executed in background.
|
|
In this case the standard output from the last command
|
|
in the pipeline will
|
|
go to the application’s standard output unless
|
|
redirected in the command, and error output from all
|
|
the commands in the pipeline will go to the application’s
|
|
standard error file. The return value of exec in this case
|
|
is a list of process ids (pids) in the pipeline.</p></div>
|
|
<div class="paragraph"><p>Each <tt><em>arg</em></tt> becomes one word for a command, except for
|
|
<tt>|</tt>, <tt><</tt>, <tt><<</tt>, <tt>></tt>, and <tt>&</tt> arguments, and the
|
|
arguments that follow <tt><</tt>, <tt><<</tt>, and <tt>></tt>.</p></div>
|
|
<div class="paragraph"><p>The first word in each command is taken as the command name;
|
|
the directories in the PATH environment variable are searched for
|
|
an executable by the given name.</p></div>
|
|
<div class="paragraph"><p>No <a href="#_glob"><strong><tt>glob</tt></strong></a> expansion or other shell-like substitutions
|
|
are performed on the arguments to commands.</p></div>
|
|
<div class="paragraph"><p>If the command fails, the global $::errorCode (and the -errorcode
|
|
option in <a href="#_catch"><strong><tt>catch</tt></strong></a>) will be set to a list, as follows:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>CHILDKILLED</strong> <em>pid sigName msg</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This format is used when a child process has been killed
|
|
because of a signal. The pid element will be the process’s
|
|
identifier (in decimal). The sigName element will be the
|
|
symbolic name of the signal that caused the process to
|
|
terminate; it will be one of the names from the include
|
|
file signal.h, such as SIGPIPE. The msg element will be a
|
|
short human-readable message describing the signal, such
|
|
as "write on pipe with no readers" for SIGPIPE.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>CHILDSUSP</strong> <em>pid sigName msg</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This format is used when a child process has been suspended
|
|
because of a signal. The pid element will be the process’s
|
|
identifier, in decimal. The sigName element will be the
|
|
symbolic name of the signal that caused the process to
|
|
suspend; this will be one of the names from the include
|
|
file signal.h, such as SIGTTIN. The msg element will be a
|
|
short human-readable message describing the signal, such
|
|
as "background tty read" for SIGTTIN.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>CHILDSTATUS</strong> <em>pid code</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This format is used when a child process has exited with a
|
|
non-zero exit status. The pid element will be the process’s
|
|
identifier (in decimal) and the code element will be the
|
|
exit code returned by the process (also in decimal).
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The environment for the executed command is set from $::env (unless
|
|
this variable is unset, in which case the original environment is used).</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_exists">exists</h3>
|
|
<div class="paragraph"><p><tt><strong>exists ?-var|-proc|-command|-alias?</strong> <em>name</em></tt></p></div>
|
|
<div class="paragraph"><p>Checks the existence of the given variable, procedure, command
|
|
or alias respectively and returns 1 if it exists or 0 if not. This command
|
|
provides a more simplified/convenient version of <a href="#_info"><strong><tt>info</tt></strong></a> <tt>exists</tt>,
|
|
<a href="#_info"><strong><tt>info</tt></strong></a> <tt>procs</tt> and <a href="#_info"><strong><tt>info</tt></strong></a> <tt>commands</tt>.</p></div>
|
|
<div class="paragraph"><p>If the type is omitted, a type of <em>-var</em> is used. The type may be abbreviated.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_exit">exit</h3>
|
|
<div class="paragraph"><p><tt><strong>exit</strong> <em>?returnCode?</em></tt></p></div>
|
|
<div class="paragraph"><p>Terminate the process, returning <tt><em>returnCode</em></tt> to the
|
|
parent as the exit status.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>returnCode</em></tt> isn’t specified then it defaults
|
|
to 0.</p></div>
|
|
<div class="paragraph"><p>Note that exit can be caught with <a href="#_catch"><strong><tt>catch</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_expr">expr</h3>
|
|
<div class="paragraph"><p><tt><strong>expr</strong> <em>arg</em></tt></p></div>
|
|
<div class="paragraph"><p>Calls the expression processor to evaluate <tt><em>arg</em></tt>, and returns
|
|
the result as a string. See the section EXPRESSIONS above.</p></div>
|
|
<div class="paragraph"><p>Note that Jim supports a shorthand syntax for <a href="#_expr"><strong><tt>expr</tt></strong></a> as <tt>$(...)</tt>
|
|
The following two are identical.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set x [expr {3 * 2 + 1}]
|
|
set x $(3 * 2 + 1)</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_file">file</h3>
|
|
<div class="paragraph"><p><tt><strong>file</strong> <em>option name ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Operate on a file or a file name. <tt><em>name</em></tt> is the name of a file.</p></div>
|
|
<div class="paragraph"><p><tt><em>option</em></tt> indicates what to do with the file name. Any unique
|
|
abbreviation for <tt><em>option</em></tt> is acceptable. The valid options are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file atime</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a decimal string giving the time at which file <tt><em>name</em></tt>
|
|
was last accessed. The time is measured in the standard UNIX
|
|
fashion as seconds from a fixed starting time (often January 1, 1970).
|
|
If the file doesn’t exist or its access time cannot be queried then an
|
|
error is generated.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file copy ?-force?</strong> <em>source target</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Copies file <tt><em>source</em></tt> to file <tt><em>target</em></tt>. The source file must exist.
|
|
The target file must not exist, unless <tt>-force</tt> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file delete ?-force?</strong> <em>name...</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Deletes file or directory <tt><em>name</em></tt>. If the file or directory doesn’t exist, nothing happens.
|
|
If it can’t be deleted, an error is generated. Non-empty directories will not be deleted
|
|
unless the <tt>-force</tt> options is given. In this case no errors will be generated, even
|
|
if the file/directory can’t be deleted.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file dirname</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <tt><em>name</em></tt> up to but not including
|
|
the last slash character. If there are no slashes in <tt><em>name</em></tt>
|
|
then return <tt>.</tt> (a single dot). If the last slash in <tt><em>name</em></tt> is its first
|
|
character, then return <tt>/</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file executable</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is executable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file exists</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> exists and the current user has
|
|
search privileges for the directories leading to it, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file extension</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <tt><em>name</em></tt> after and including the
|
|
last dot in <tt><em>name</em></tt>. If there is no dot in <tt><em>name</em></tt> then return
|
|
the empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file isdirectory</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is a directory,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file isfile</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is a regular file,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file join</strong> <em>arg...</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Joins multiple path components. Note that if any components is
|
|
an absolute path, the preceding components are ignored.
|
|
Thus <tt>"<a href="#_file"><strong><tt>file</tt></strong></a> join /tmp /root"</tt> returns <tt>"/root"</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file lstat</strong> <em>name varName</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Same as <em>stat</em> option (see below) except uses the <tt><em>lstat</em></tt>
|
|
kernel call instead of <tt><em>stat</em></tt>. This means that if <tt><em>name</em></tt>
|
|
refers to a symbolic link the information returned in <tt><em>varName</em></tt>
|
|
is for the link rather than the file it refers to. On systems that
|
|
don’t support symbolic links this option behaves exactly the same
|
|
as the <em>stat</em> option.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file mkdir</strong> <em>dir1 ?dir2...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates each directory specified. For each pathname <tt><em>dir</em></tt> specified,
|
|
this command will create all non-existing parent directories
|
|
as well as <tt><em>dir</em></tt> itself. If an existing directory is specified,
|
|
then no action is taken and no error is returned. Trying to
|
|
overwrite an existing file with a directory will result in an
|
|
error. Arguments are processed in the order specified, halting
|
|
at the first error, if any.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file mtime</strong> <em>name ?time?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a decimal string giving the time at which file <tt><em>name</em></tt>
|
|
was last modified. The time is measured in the standard UNIX
|
|
fashion as seconds from a fixed starting time (often January 1, 1970).
|
|
If the file doesn’t exist or its modified time cannot be queried then an
|
|
error is generated. If <tt><em>time</em></tt> is given, sets the modification time
|
|
of the file to the given value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file normalize</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return the normalized path of <tt><em>name</em></tt>. See <em>realpath(3)</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file owned</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is owned by the current user,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file readable</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is readable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file readlink</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the value of the symbolic link given by <tt><em>name</em></tt> (i.e. the
|
|
name of the file it points to). If
|
|
<tt><em>name</em></tt> isn’t a symbolic link or its value cannot be read, then
|
|
an error is returned. On systems that don’t support symbolic links
|
|
this option is undefined.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file rename</strong> <em>oldname</em> <em>newname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Renames the file from the old name to the new name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file rootname</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <tt><em>name</em></tt> up to but not including
|
|
the last <em>.</em> character in the name. If <tt><em>name</em></tt> doesn’t contain
|
|
a dot, then return <tt><em>name</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file size</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a decimal string giving the size of file <tt><em>name</em></tt> in bytes.
|
|
If the file doesn’t exist or its size cannot be queried then an
|
|
error is generated.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file stat</strong> <em>name varName</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invoke the <em>stat</em> kernel call on <tt><em>name</em></tt>, and use the
|
|
variable given by <tt><em>varName</em></tt> to hold information returned from
|
|
the kernel call.
|
|
<tt><em>varName</em></tt> is treated as an array variable,
|
|
and the following elements of that variable are set: <em>atime</em>,
|
|
<em>ctime</em>, <em>dev</em>, <em>gid</em>, <em>ino</em>, <em>mode</em>, <em>mtime</em>,
|
|
<em>nlink</em>, <em>size</em>, <em>type</em>, <em>uid</em>.
|
|
Each element except <em>type</em> is a decimal string with the value of
|
|
the corresponding field from the <em>stat</em> return structure; see the
|
|
manual entry for <em>stat</em> for details on the meanings of the values.
|
|
The <em>type</em> element gives the type of the file in the same form
|
|
returned by the command <a href="#_file"><strong><tt>file</tt></strong></a> <tt>type</tt>.
|
|
This command returns an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file tail</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <tt><em>name</em></tt> after the last slash.
|
|
If <tt><em>name</em></tt> contains no slashes then return <tt><em>name</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file tempfile</strong> <em>?template?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates and returns the name of a unique temporary file. If <tt><em>template</em></tt> is omitted, a
|
|
default template will be used to place the file in /tmp. See <em>mkstemp(3)</em> for
|
|
the format of the template and security concerns.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file type</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a string giving the type of file <tt><em>name</em></tt>, which will be
|
|
one of <tt>file</tt>, <tt>directory</tt>, <tt>characterSpecial</tt>,
|
|
<tt>blockSpecial</tt>, <tt>fifo</tt>, <tt>link</tt>, or <tt>socket</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>file writable</strong> <em>name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <tt><em>name</em></tt> is writable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The <a href="#_file"><strong><tt>file</tt></strong></a> commands that return 0/1 results are often used in
|
|
conditional or looping commands, for example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>if {![file exists foo]} {
|
|
error {bad file name}
|
|
} else {
|
|
...
|
|
}</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_finalize">finalize</h3>
|
|
<div class="paragraph"><p><tt><strong>finalize</strong> <em>reference ?command?</em></tt></p></div>
|
|
<div class="paragraph"><p>If <tt><em>command</em></tt> is omitted, returns the finalizer command for the given reference.</p></div>
|
|
<div class="paragraph"><p>Otherwise, sets a new finalizer command for the given reference. <tt><em>command</em></tt> may be
|
|
the empty string to remove the current finalizer.</p></div>
|
|
<div class="paragraph"><p>The reference must be a valid reference create with the <a href="#_ref"><strong><tt>ref</tt></strong></a>
|
|
command.</p></div>
|
|
<div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_flush">flush</h3>
|
|
<div class="paragraph"><p><tt><strong>flush</strong> <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>flush</strong></tt></p></div>
|
|
<div class="paragraph"><p>Flushes any output that has been buffered for <tt><em>fileId</em></tt>. <tt><em>fileId</em></tt> must
|
|
have been the return value from a previous call to <a href="#_open"><strong><tt>open</tt></strong></a>, or it may be
|
|
<tt>stdout</tt> or <tt>stderr</tt> to access one of the standard I/O streams; it must
|
|
refer to a file that was opened for writing. This command returns an
|
|
empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_for">for</h3>
|
|
<div class="paragraph"><p><tt><strong>for</strong> <em>start test next body</em></tt></p></div>
|
|
<div class="paragraph"><p><a href="#_for"><strong><tt>for</tt></strong></a> is a looping command, similar in structure to the C <a href="#_for"><strong><tt>for</tt></strong></a> statement.
|
|
The <tt><em>start</em></tt>, <tt><em>next</em></tt>, and <tt><em>body</em></tt> arguments must be Tcl command strings,
|
|
and <tt><em>test</em></tt> is an expression string.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_for"><strong><tt>for</tt></strong></a> command first invokes the Tcl interpreter to execute <tt><em>start</em></tt>.
|
|
Then it repeatedly evaluates <tt><em>test</em></tt> as an expression; if the result is
|
|
non-zero it invokes the Tcl interpreter on <tt><em>body</em></tt>, then invokes the Tcl
|
|
interpreter on <tt><em>next</em></tt>, then repeats the loop. The command terminates
|
|
when <tt><em>test</em></tt> evaluates to 0.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_continue"><strong><tt>continue</tt></strong></a> command is invoked within <tt><em>body</em></tt> then any remaining
|
|
commands in the current execution of <tt><em>body</em></tt> are skipped; processing
|
|
continues by invoking the Tcl interpreter on <tt><em>next</em></tt>, then evaluating
|
|
<tt><em>test</em></tt>, and so on.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_break"><strong><tt>break</tt></strong></a> command is invoked within <tt><em>body</em></tt> or <tt><em>next</em></tt>, then the <a href="#_for"><strong><tt>for</tt></strong></a>
|
|
command will return immediately.</p></div>
|
|
<div class="paragraph"><p>The operation of <a href="#_break"><strong><tt>break</tt></strong></a> and <a href="#_continue"><strong><tt>continue</tt></strong></a> are similar to the corresponding
|
|
statements in C.</p></div>
|
|
<div class="paragraph"><p><a href="#_for"><strong><tt>for</tt></strong></a> returns an empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_foreach">foreach</h3>
|
|
<div class="paragraph"><p><tt><strong>foreach</strong> <em>varName list body</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>foreach</strong> <em>varList list ?varList2 list2 ...? body</em></tt></p></div>
|
|
<div class="paragraph"><p>In this command, <tt><em>varName</em></tt> is the name of a variable, <tt><em>list</em></tt>
|
|
is a list of values to assign to <tt><em>varName</em></tt>, and <tt><em>body</em></tt> is a
|
|
collection of Tcl commands.</p></div>
|
|
<div class="paragraph"><p>For each field in <tt><em>list</em></tt> (in order from left to right), <a href="#_foreach"><strong><tt>foreach</tt></strong></a> assigns
|
|
the contents of the field to <tt><em>varName</em></tt> (as if the <a href="#_lindex"><strong><tt>lindex</tt></strong></a> command
|
|
had been used to extract the field), then calls the Tcl interpreter to
|
|
execute <tt><em>body</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If instead of being a simple name, <tt><em>varList</em></tt> is used, multiple assignments
|
|
are made each time through the loop, one for each element of <tt><em>varList</em></tt>.</p></div>
|
|
<div class="paragraph"><p>For example, if there are two elements in <tt><em>varList</em></tt> and six elements in
|
|
the list, the loop will be executed three times.</p></div>
|
|
<div class="paragraph"><p>If the length of the list doesn’t evenly divide by the number of elements
|
|
in <tt><em>varList</em></tt>, the value of the remaining variables in the last iteration
|
|
of the loop are undefined.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_break"><strong><tt>break</tt></strong></a> and <a href="#_continue"><strong><tt>continue</tt></strong></a> statements may be invoked inside <tt><em>body</em></tt>,
|
|
with the same effect as in the <a href="#_for"><strong><tt>for</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p><a href="#_foreach"><strong><tt>foreach</tt></strong></a> returns an empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_format">format</h3>
|
|
<div class="paragraph"><p><tt><strong>format</strong> <em>formatString ?arg ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command generates a formatted string in the same way as the
|
|
C <em>sprintf</em> procedure (it uses <em>sprintf</em> in its
|
|
implementation). <tt><em>formatString</em></tt> indicates how to format
|
|
the result, using <tt>%</tt> fields as in <em>sprintf</em>, and the additional
|
|
arguments, if any, provide values to be substituted into the result.</p></div>
|
|
<div class="paragraph"><p>All of the <em>sprintf</em> options are valid; see the <em>sprintf</em>
|
|
man page for details. Each <tt><em>arg</em></tt> must match the expected type
|
|
from the <tt>%</tt> field in <tt><em>formatString</em></tt>; the <a href="#_format"><strong><tt>format</tt></strong></a> command
|
|
converts each argument to the correct type (floating, integer, etc.)
|
|
before passing it to <em>sprintf</em> for formatting.</p></div>
|
|
<div class="paragraph"><p>The only unusual conversion is for <tt>%c</tt>; in this case the argument
|
|
must be a decimal string, which will then be converted to the corresponding
|
|
ASCII character value.</p></div>
|
|
<div class="paragraph"><p><a href="#_format"><strong><tt>format</tt></strong></a> does backslash substitution on its <tt><em>formatString</em></tt>
|
|
argument, so backslash sequences in <tt><em>formatString</em></tt> will be handled
|
|
correctly even if the argument is in braces.</p></div>
|
|
<div class="paragraph"><p>The return value from <a href="#_format"><strong><tt>format</tt></strong></a> is the formatted string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_getref">getref</h3>
|
|
<div class="paragraph"><p><tt><strong>getref</strong> <em>reference</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns the string associated with <tt><em>reference</em></tt>. The reference must
|
|
be a valid reference create with the <a href="#_ref"><strong><tt>ref</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_gets">gets</h3>
|
|
<div class="paragraph"><p><tt><strong>gets</strong> <em>fileId ?varName?</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>gets</strong> <em>?varName?</em></tt></p></div>
|
|
<div class="paragraph"><p>Reads the next line from the file given by <tt><em>fileId</em></tt> and discards
|
|
the terminating newline character.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> is specified, then the line is placed in the variable
|
|
by that name and the return value is a count of the number of characters
|
|
read (not including the newline).</p></div>
|
|
<div class="paragraph"><p>If the end of the file is reached before reading
|
|
any characters then -1 is returned and <tt><em>varName</em></tt> is set to an
|
|
empty string.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> is not specified then the return value will be
|
|
the line (minus the newline character) or an empty string if
|
|
the end of the file is reached before reading any characters.</p></div>
|
|
<div class="paragraph"><p>An empty string will also be returned if a line contains no characters
|
|
except the newline, so <a href="#_eof"><strong><tt>eof</tt></strong></a> may have to be used to determine
|
|
what really happened.</p></div>
|
|
<div class="paragraph"><p>If the last character in the file is not a newline character, then
|
|
<a href="#_gets"><strong><tt>gets</tt></strong></a> behaves as if there were an additional newline character
|
|
at the end of the file.</p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em></tt> must be <tt>stdin</tt> or the return value from a previous
|
|
call to <a href="#_open"><strong><tt>open</tt></strong></a>; it must refer to a file that was opened
|
|
for reading.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_glob">glob</h3>
|
|
<div class="paragraph"><p><tt><strong>glob</strong> ?<strong>-nocomplain</strong>? <em>pattern ?pattern ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command performs filename globbing, using csh rules. The returned
|
|
value from <a href="#_glob"><strong><tt>glob</tt></strong></a> is the list of expanded filenames.</p></div>
|
|
<div class="paragraph"><p>If <tt>-nocomplain</tt> is specified as the first argument then an empty
|
|
list may be returned; otherwise an error is returned if the expanded
|
|
list is empty. The <tt>-nocomplain</tt> argument must be provided
|
|
exactly: an abbreviation will not be accepted.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_global">global</h3>
|
|
<div class="paragraph"><p><tt><strong>global</strong> <em>varName ?varName ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command is ignored unless a Tcl procedure is being interpreted.
|
|
If so, then it declares each given <tt><em>varName</em></tt> to be a global variable
|
|
rather than a local one. For the duration of the current procedure
|
|
(and only while executing in the current procedure), any reference to
|
|
<tt><em>varName</em></tt> will be bound to a global variable instead
|
|
of a local one.</p></div>
|
|
<div class="paragraph"><p>An alternative to using <a href="#_global"><strong><tt>global</tt></strong></a> is to use the <tt>::</tt> prefix
|
|
to explicitly name a variable in the global scope.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_if">if</h3>
|
|
<div class="paragraph"><p><tt><strong>if</strong> <em>expr1</em> ?<strong>then</strong>? <em>body1</em> <strong>elseif</strong> <em>expr2</em> ?<strong>then</strong>? <em>body2</em> <strong>elseif</strong> ... ?<strong>else</strong>? ?<em>bodyN</em>?</tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_if"><strong><tt>if</tt></strong></a> command evaluates <tt><em>expr1</em></tt> as an expression (in the same way
|
|
that <a href="#_expr"><strong><tt>expr</tt></strong></a> evaluates its argument). The value of the expression must
|
|
be numeric; if it is non-zero then <tt><em>body1</em></tt> is executed by passing it to
|
|
the Tcl interpreter.</p></div>
|
|
<div class="paragraph"><p>Otherwise <tt><em>expr2</em></tt> is evaluated as an expression and if it is non-zero
|
|
then <tt><em>body2</em></tt> is executed, and so on.</p></div>
|
|
<div class="paragraph"><p>If none of the expressions evaluates to non-zero then <tt><em>bodyN</em></tt> is executed.</p></div>
|
|
<div class="paragraph"><p>The <tt>then</tt> and <tt>else</tt> arguments are optional "noise words" to make the
|
|
command easier to read.</p></div>
|
|
<div class="paragraph"><p>There may be any number of <tt>elseif</tt> clauses, including zero. <tt><em>bodyN</em></tt>
|
|
may also be omitted as long as <tt>else</tt> is omitted too.</p></div>
|
|
<div class="paragraph"><p>The return value from the command is the result of the body script that
|
|
was executed, or an empty string if none of the expressions was non-zero
|
|
and there was no <tt><em>bodyN</em></tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_incr">incr</h3>
|
|
<div class="paragraph"><p><tt><strong>incr</strong> <em>varName ?increment?</em></tt></p></div>
|
|
<div class="paragraph"><p>Increment the value stored in the variable whose name is <tt><em>varName</em></tt>.
|
|
The value of the variable must be integral.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>increment</em></tt> is supplied then its value (which must be an
|
|
integer) is added to the value of variable <tt><em>varName</em></tt>; otherwise
|
|
1 is added to <tt><em>varName</em></tt>.</p></div>
|
|
<div class="paragraph"><p>The new value is stored as a decimal string in variable <tt><em>varName</em></tt>
|
|
and also returned as result.</p></div>
|
|
<div class="paragraph"><p>If the variable does not exist, the variable is implicitly created
|
|
and set to <tt>0</tt> first.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_info">info</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info</strong> <em>option ?arg...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Provide information about various internals to the Tcl interpreter.
|
|
The legal <tt><em>option</em></tt>'s (which may be abbreviated) are:
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info args</strong> <em>procname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing the names of the arguments to procedure
|
|
<tt><em>procname</em></tt>, in order. <tt><em>procname</em></tt> must be the name of a
|
|
Tcl command procedure.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info alias</strong> <em>command</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt><em>command</em></tt> must be an alias created with <a href="#_alias"><strong><tt>alias</tt></strong></a>. In which case the target
|
|
command and arguments, as passed to <a href="#_alias"><strong><tt>alias</tt></strong></a> are returned. See <a href="#_exists"><strong><tt>exists</tt></strong></a> <tt>-alias</tt>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info body</strong> <em>procname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the body of procedure <tt><em>procname</em></tt>. <tt><em>procname</em></tt> must be
|
|
the name of a Tcl command procedure.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info channels</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all open file handles from <a href="#_open"><strong><tt>open</tt></strong></a> or <a href="#_socket"><strong><tt>socket</tt></strong></a>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info commands</strong> ?<em>pattern</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>pattern</em></tt> isn’t specified, returns a list of names of all the
|
|
Tcl commands, including both the built-in commands written in C and
|
|
the command procedures defined using the <a href="#_proc"><strong><tt>proc</tt></strong></a> command.
|
|
If <tt><em>pattern</em></tt> is specified, only those names matching <tt><em>pattern</em></tt>
|
|
are returned. Matching is determined using the same rules as for
|
|
<a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info complete</strong> <em>command</em> ?<em>missing</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if <tt><em>command</em></tt> is a complete Tcl command in the sense of
|
|
having no unclosed quotes, braces, brackets or array element names,
|
|
If the command doesn’t appear to be complete then 0 is returned.
|
|
This command is typically used in line-oriented input environments
|
|
to allow users to type in commands that span multiple lines; if the
|
|
command isn’t complete, the script can delay evaluating it until additional
|
|
lines have been typed to complete the command. If <tt><em>varName</em></tt> is specified, the
|
|
missing character is stored in the variable with that name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info exists</strong> <em>varName</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns <em>1</em> if the variable named <tt><em>varName</em></tt> exists in the
|
|
current context (either as a global or local variable), returns <em>0</em>
|
|
otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info frame</strong> ?<em>number</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>number</em></tt> is not specified, this command returns a number
|
|
which is the same result as <a href="#_info"><strong><tt>info</tt></strong></a> <tt>level</tt> - the current stack frame level.
|
|
If <tt><em>number</em></tt> is specified, then the result is a list consisting of the procedure,
|
|
filename and line number for the procedure call at level <tt><em>number</em></tt> on the stack.
|
|
If <tt><em>number</em></tt> is positive then it selects a particular stack level (1 refers
|
|
to the top-most active procedure, 2 to the procedure it called, and
|
|
so on); otherwise it gives a level relative to the current level
|
|
(0 refers to the current procedure, -1 to its caller, and so on).
|
|
The level has an identical meaning to <a href="#_info"><strong><tt>info</tt></strong></a> <tt>level</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info globals</strong> ?<em>pattern</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>pattern</em></tt> isn’t specified, returns a list of all the names
|
|
of currently-defined global variables.
|
|
If <tt><em>pattern</em></tt> is specified, only those names matching <tt><em>pattern</em></tt>
|
|
are returned. Matching is determined using the same rules as for
|
|
<a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info hostname</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
An alias for <a href="#cmd_1"><strong><tt>os.gethostname</tt></strong></a> for compatibility with Tcl 6.x
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info level</strong> ?<em>number</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>number</em></tt> is not specified, this command returns a number
|
|
giving the stack level of the invoking procedure, or 0 if the
|
|
command is invoked at top-level. If <tt><em>number</em></tt> is specified,
|
|
then the result is a list consisting of the name and arguments for the
|
|
procedure call at level <tt><em>number</em></tt> on the stack. If <tt><em>number</em></tt>
|
|
is positive then it selects a particular stack level (1 refers
|
|
to the top-most active procedure, 2 to the procedure it called, and
|
|
so on); otherwise it gives a level relative to the current level
|
|
(0 refers to the current procedure, -1 to its caller, and so on).
|
|
See the <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> command for more information on what stack
|
|
levels mean.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info locals</strong> ?<em>pattern</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>pattern</em></tt> isn’t specified, returns a list of all the names
|
|
of currently-defined local variables, including arguments to the
|
|
current procedure, if any. Variables defined with the <a href="#_global"><strong><tt>global</tt></strong></a>
|
|
and <a href="#_upvar"><strong><tt>upvar</tt></strong></a> commands will not be returned. If <tt><em>pattern</em></tt> is
|
|
specified, only those names matching <tt><em>pattern</em></tt> are returned.
|
|
Matching is determined using the same rules as for <a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info nameofexecutable</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the name of the binary file from which the application
|
|
was invoked. A full path will be returned, unless the path
|
|
can’t be determined, in which case the empty string will be returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info procs</strong> ?<em>pattern</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>pattern</em></tt> isn’t specified, returns a list of all the
|
|
names of Tcl command procedures.
|
|
If <tt><em>pattern</em></tt> is specified, only those names matching <tt><em>pattern</em></tt>
|
|
are returned. Matching is determined using the same rules as for
|
|
<a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info references</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all references which have not yet been garbage
|
|
collected.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info returncodes</strong> ?<em>code</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list representing the mapping of standard return codes
|
|
to names. e.g. <tt>{0 ok 1 error 2 return ...}</tt>. If a code is given,
|
|
instead returns the name for the given code.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info script</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If a Tcl script file is currently being evaluated (i.e. there is a
|
|
call to <em>Jim_EvalFile</em> active or there is an active invocation
|
|
of the <a href="#_source"><strong><tt>source</tt></strong></a> command), then this command returns the name
|
|
of the innermost file being processed. Otherwise the command returns an
|
|
empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info source</strong> <em>script</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the original source location of the given script as a list of
|
|
<tt>{filename linenumber}</tt>. If the source location can’t be determined, the
|
|
list <tt>{{} 0}</tt> is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info stacktrace</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
After an error is caught with <a href="#_catch"><strong><tt>catch</tt></strong></a>, returns the stack trace as a list
|
|
of <tt>{procedure filename line ...}</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info statics</strong> <em>procname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a dictionary of the static variables of procedure
|
|
<tt><em>procname</em></tt>. <tt><em>procname</em></tt> must be the name of a Tcl command
|
|
procedure. An empty dictionary is returned if the procedure has
|
|
no static variables.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info version</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the version number for this version of Jim in the form <tt><strong>x.yy</strong></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>info vars</strong> ?<em>pattern</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>pattern</em></tt> isn’t specified,
|
|
returns a list of all the names of currently-visible variables, including
|
|
both locals and currently-visible globals.
|
|
If <tt><em>pattern</em></tt> is specified, only those names matching <tt><em>pattern</em></tt>
|
|
are returned. Matching is determined using the same rules as for
|
|
<a href="#_string"><strong><tt>string</tt></strong></a> <tt>match</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_join">join</h3>
|
|
<div class="paragraph"><p><tt><strong>join</strong> <em>list ?joinString?</em></tt></p></div>
|
|
<div class="paragraph"><p>The <tt><em>list</em></tt> argument must be a valid Tcl list. This command returns the
|
|
string formed by joining all of the elements of <tt><em>list</em></tt> together with
|
|
<tt><em>joinString</em></tt> separating each adjacent pair of elements.</p></div>
|
|
<div class="paragraph"><p>The <tt><em>joinString</em></tt> argument defaults to a space character.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_kill">kill</h3>
|
|
<div class="paragraph"><p><tt><strong>kill</strong> ?<em>SIG</em>|<strong>-0</strong>? <em>pid</em></tt></p></div>
|
|
<div class="paragraph"><p>Sends the given signal to the process identified by <tt><em>pid</em></tt>.</p></div>
|
|
<div class="paragraph"><p>The signal may be specified by name or number in one of the following forms:</p></div>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<tt>TERM</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt>SIGTERM</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt>-TERM</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt>15</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<tt>-15</tt>
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
<div class="paragraph"><p>The signal name may be in either upper or lower case.</p></div>
|
|
<div class="paragraph"><p>The special signal name <tt>-0</tt> simply checks that a signal <tt><em>could</em></tt> be sent.</p></div>
|
|
<div class="paragraph"><p>If no signal is specified, SIGTERM is used.</p></div>
|
|
<div class="paragraph"><p>An error is raised if the signal could not be delivered.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lambda_2">lambda</h3>
|
|
<div class="paragraph"><p><tt><strong>lambda</strong> <em>args ?statics? body</em></tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_lambda"><strong><tt>lambda</tt></strong></a> command is identical to <a href="#_proc"><strong><tt>proc</tt></strong></a>, except rather than
|
|
creating a named procedure, it creates an anonymous procedure and returns
|
|
the name of the procedure.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_proc"><strong><tt>proc</tt></strong></a> and GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lappend">lappend</h3>
|
|
<div class="paragraph"><p><tt><strong>lappend</strong> <em>varName value ?value value ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Treat the variable given by <tt><em>varName</em></tt> as a list and append each of
|
|
the <tt><em>value</em></tt> arguments to that list as a separate element, with spaces
|
|
between elements.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> doesn’t exist, it is created as a list with elements given
|
|
by the <tt><em>value</em></tt> arguments. <a href="#_lappend"><strong><tt>lappend</tt></strong></a> is similar to <a href="#_append"><strong><tt>append</tt></strong></a> except that
|
|
each <tt><em>value</em></tt> is appended as a list element rather than raw text.</p></div>
|
|
<div class="paragraph"><p>This command provides a relatively efficient way to build up large lists.
|
|
For example,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>lappend a $b</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is much more efficient than</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a [concat $a [list $b]]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>when <tt>$a</tt> is long.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lassign">lassign</h3>
|
|
<div class="paragraph"><p><tt><strong>lassign</strong> <em>list varName ?varName ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command treats the value <tt><em>list</em></tt> as a list and assigns successive elements from that list to
|
|
the variables given by the <tt><em>varName</em></tt> 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 ele-
|
|
ments than variables, a list of unassigned elements is returned.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> lassign {1 2 3} a b; puts a=$a,b=$b
|
|
3
|
|
a=1,b=2</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_local">local</h3>
|
|
<div class="paragraph"><p><tt><strong>local</strong> <em>cmd ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>First, <a href="#_local"><strong><tt>local</tt></strong></a> evaluates <tt><em>cmd</em></tt> with the given arguments. The return value must
|
|
be the name of an existing command, which is marked as having local scope.
|
|
This means that when the current procedure exits, the specified
|
|
command is deleted. This can be useful with <a href="#_lambda"><strong><tt>lambda</tt></strong></a>, local procedures or
|
|
to automatically close a filehandle.</p></div>
|
|
<div class="paragraph"><p>In addition, if a command already exists with the same name,
|
|
the existing command will be kept rather than deleted, and may be called
|
|
via <a href="#_upcall"><strong><tt>upcall</tt></strong></a>. The previous command will be restored when the current
|
|
procedure exits. See <a href="#_upcall"><strong><tt>upcall</tt></strong></a> for more details.</p></div>
|
|
<div class="paragraph"><p>In this example, a local procedure is created. Note that the procedure
|
|
continues to have global scope while it is active.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>proc outer {} {
|
|
# proc ... returns "inner" which is marked local
|
|
local proc inner {} {
|
|
# will be deleted when 'outer' exits
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt> inner
|
|
...
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>In this example, the lambda is deleted at the end of the procedure rather
|
|
than waiting until garbage collection.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>proc outer {} {
|
|
set x [lambda inner {args} {
|
|
# will be deleted when 'outer' exits
|
|
}]
|
|
# Use 'function' here which simply returns $x
|
|
local function $x</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt> $x ...
|
|
...
|
|
}</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_loop">loop</h3>
|
|
<div class="paragraph"><p><tt><strong>loop</strong> <em>var first limit ?incr? body</em></tt></p></div>
|
|
<div class="paragraph"><p>Similar to <a href="#_for"><strong><tt>for</tt></strong></a> except simpler and possibly more efficient.
|
|
With a positive increment, equivalent to:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>for {set var $first} {$var < $limit} {incr var $incr} $body</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If <tt><em>incr</em></tt> is not specified, 1 is used.
|
|
Note that setting the loop variable inside the loop does not
|
|
affect the loop count.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lindex">lindex</h3>
|
|
<div class="paragraph"><p><tt><strong>lindex</strong> <em>list index</em></tt></p></div>
|
|
<div class="paragraph"><p>Treats <tt><em>list</em></tt> as a Tcl list and returns element <tt><em>index</em></tt> from it
|
|
(0 refers to the first element of the list).
|
|
See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>index</em></tt>.</p></div>
|
|
<div class="paragraph"><p>In extracting the element, <tt><em>lindex</em></tt> observes the same rules concerning
|
|
braces and quotes and backslashes as the Tcl command interpreter; however,
|
|
variable substitution and command substitution do not occur.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>index</em></tt> is negative or greater than or equal to the number of elements
|
|
in <tt><em>value</em></tt>, then an empty string is returned.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_linsert">linsert</h3>
|
|
<div class="paragraph"><p><tt><strong>linsert</strong> <em>list index element ?element element ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command produces a new list from <tt><em>list</em></tt> by inserting all
|
|
of the <tt><em>element</em></tt> arguments just before the element <tt><em>index</em></tt>
|
|
of <tt><em>list</em></tt>. Each <tt><em>element</em></tt> argument will become
|
|
a separate element of the new list. If <tt><em>index</em></tt> is less than
|
|
or equal to zero, then the new elements are inserted at the
|
|
beginning of the list. If <tt><em>index</em></tt> is greater than or equal
|
|
to the number of elements in the list, then the new elements are
|
|
appended to the list.</p></div>
|
|
<div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>index</em></tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_list">list</h3>
|
|
<div class="paragraph"><p><tt><strong>list</strong> <em>arg ?arg ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command returns a list comprised of all the arguments, <tt><em>arg</em></tt>. Braces
|
|
and backslashes get added as necessary, so that the <a href="#_lindex"><strong><tt>lindex</tt></strong></a> command
|
|
may be used on the result to re-extract the original arguments, and also
|
|
so that <a href="#_eval"><strong><tt>eval</tt></strong></a> may be used to execute the resulting list, with
|
|
<tt><em>arg1</em></tt> comprising the command’s name and the other args comprising
|
|
its arguments. <a href="#_list"><strong><tt>list</tt></strong></a> produces slightly different results than
|
|
<a href="#_concat"><strong><tt>concat</tt></strong></a>: <a href="#_concat"><strong><tt>concat</tt></strong></a> removes one level of grouping before forming
|
|
the list, while <a href="#_list"><strong><tt>list</tt></strong></a> works directly from the original arguments.
|
|
For example, the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>list a b {c d e} {f {g h}}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>a b {c d e} {f {g h}}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>while <a href="#_concat"><strong><tt>concat</tt></strong></a> with the same arguments will return</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>a b c d e f {g h}</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_llength">llength</h3>
|
|
<div class="paragraph"><p><tt><strong>llength</strong> <em>list</em></tt></p></div>
|
|
<div class="paragraph"><p>Treats <tt><em>list</em></tt> as a list and returns a decimal string giving
|
|
the number of elements in it.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lset">lset</h3>
|
|
<div class="paragraph"><p><tt><strong>lset</strong> <em>varName ?index ..? newValue</em></tt></p></div>
|
|
<div class="paragraph"><p>Sets an element in a list.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_lset"><strong><tt>lset</tt></strong></a> command accepts a parameter, <tt><em>varName</em></tt>, which it interprets
|
|
as the name of a variable containing a Tcl list. It also accepts
|
|
zero or more indices into the list. Finally, it accepts a new value
|
|
for an element of varName. If no indices are presented, the command
|
|
takes the form:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>lset varName newValue</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>In this case, newValue replaces the old value of the variable
|
|
varName.</p></div>
|
|
<div class="paragraph"><p>When presented with a single index, the <a href="#_lset"><strong><tt>lset</tt></strong></a> command
|
|
treats the content of the varName variable as a Tcl list. It addresses
|
|
the index’th element in it (0 refers to the first element of the
|
|
list). When interpreting the list, <a href="#_lset"><strong><tt>lset</tt></strong></a> observes the same rules
|
|
concerning braces and quotes and backslashes as the Tcl command
|
|
interpreter; however, variable substitution and command substitution
|
|
do not occur. The command constructs a new list in which the
|
|
designated element is replaced with newValue. This new list is
|
|
stored in the variable varName, and is also the return value from
|
|
the <a href="#_lset"><strong><tt>lset</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If index is negative or greater than or equal to the number of
|
|
elements in $varName, then an error occurs.</p></div>
|
|
<div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>index</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If additional index arguments are supplied, then each argument is
|
|
used in turn to address an element within a sublist designated by
|
|
the previous indexing operation, allowing the script to alter
|
|
elements in sublists. The command,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>lset a 1 2 newValue</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>replaces element 2 of sublist 1 with <tt><em>newValue</em></tt>.</p></div>
|
|
<div class="paragraph"><p>The integer appearing in each index argument must be greater than
|
|
or equal to zero. The integer appearing in each index argument must
|
|
be strictly less than the length of the corresponding list. In other
|
|
words, the <a href="#_lset"><strong><tt>lset</tt></strong></a> command cannot change the size of a list. If an
|
|
index is outside the permitted range, an error is reported.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lmap">lmap</h3>
|
|
<div class="paragraph"><p><tt><strong>lmap</strong> <em>varName list body</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>lmap</strong> <em>varList list ?varList2 list2 ...? body</em></tt></p></div>
|
|
<div class="paragraph"><p><a href="#_lmap"><strong><tt>lmap</tt></strong></a> is a "collecting" <a href="#_foreach"><strong><tt>foreach</tt></strong></a> which returns a list of its results.</p></div>
|
|
<div class="paragraph"><p>For example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> lmap i {1 2 3 4 5} {expr $i*$i}
|
|
1 4 9 16 25
|
|
jim> lmap a {1 2 3} b {A B C} {list $a $b}
|
|
{1 A} {2 B} {3 C}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If the body invokes <a href="#_continue"><strong><tt>continue</tt></strong></a>, no value is added for this iteration.
|
|
If the body invokes <a href="#_break"><strong><tt>break</tt></strong></a>, the loop ends and no more values are added.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_load">load</h3>
|
|
<div class="paragraph"><p><tt><strong>load</strong> <em>filename</em></tt></p></div>
|
|
<div class="paragraph"><p>Loads the dynamic extension, <tt><em>filename</em></tt>. Generally the filename should have
|
|
the extension <tt>.so</tt>. The initialisation function for the module must be based
|
|
on the name of the file. For example loading <tt>hwaccess.so</tt> will invoke
|
|
the initialisation function, <tt>Jim_hwaccessInit</tt>. Normally the <a href="#_load"><strong><tt>load</tt></strong></a> command
|
|
should not be used directly. Instead it is invoked automatically by <a href="#_package"><strong><tt>package</tt></strong></a> <tt>require</tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lrange">lrange</h3>
|
|
<div class="paragraph"><p><tt><strong>lrange</strong> <em>list first last</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>list</em></tt> must be a valid Tcl list. This command will return a new
|
|
list consisting of elements <tt><em>first</em></tt> through <tt><em>last</em></tt>, inclusive.</p></div>
|
|
<div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>first</em></tt> and <tt><em>last</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>last</em></tt> is greater than or equal to the number of elements
|
|
in the list, then it is treated as if it were <tt>end</tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>first</em></tt> is greater than <tt><em>last</em></tt> then an empty string
|
|
is returned.</p></div>
|
|
<div class="paragraph"><p>Note: <tt>"<a href="#_lrange"><strong><tt>lrange</tt></strong></a> <em>list first first</em>"</tt> does not always produce the
|
|
same result as <tt>"<a href="#_lindex"><strong><tt>lindex</tt></strong></a> <em>list first</em>"</tt> (although it often does
|
|
for simple fields that aren’t enclosed in braces); it does, however,
|
|
produce exactly the same results as <tt>"<a href="#_list"><strong><tt>list</tt></strong></a> [<a href="#_lindex"><strong><tt>lindex</tt></strong></a> <em>list first</em>]"</tt></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lreplace">lreplace</h3>
|
|
<div class="paragraph"><p><tt><strong>lreplace</strong> <em>list first last ?element element ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a new list formed by replacing one or more elements of
|
|
<tt><em>list</em></tt> with the <tt><em>element</em></tt> arguments.</p></div>
|
|
<div class="paragraph"><p><tt><em>first</em></tt> gives the index in <tt><em>list</em></tt> of the first element
|
|
to be replaced.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>first</em></tt> is less than zero then it refers to the first
|
|
element of <tt><em>list</em></tt>; the element indicated by <tt><em>first</em></tt>
|
|
must exist in the list.</p></div>
|
|
<div class="paragraph"><p><tt><em>last</em></tt> gives the index in <tt><em>list</em></tt> of the last element
|
|
to be replaced; it must be greater than or equal to <tt><em>first</em></tt>.</p></div>
|
|
<div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>first</em></tt> and <tt><em>last</em></tt>.</p></div>
|
|
<div class="paragraph"><p>The <tt><em>element</em></tt> arguments specify zero or more new arguments to
|
|
be added to the list in place of those that were deleted.</p></div>
|
|
<div class="paragraph"><p>Each <tt><em>element</em></tt> argument will become a separate element of
|
|
the list.</p></div>
|
|
<div class="paragraph"><p>If no <tt><em>element</em></tt> arguments are specified, then the elements
|
|
between <tt><em>first</em></tt> and <tt><em>last</em></tt> are simply deleted.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lrepeat">lrepeat</h3>
|
|
<div class="paragraph"><p><tt><strong>lrepeat</strong> <em>number element1 ?element2 ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Build a list by repeating elements <tt><em>number</em></tt> times (which must be
|
|
a positive integer).</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> lrepeat 3 a b
|
|
a b a b a b</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lreverse">lreverse</h3>
|
|
<div class="paragraph"><p><tt><strong>lreverse</strong> <em>list</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns the list in reverse order.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> lreverse {1 2 3}
|
|
3 2 1</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lsearch">lsearch</h3>
|
|
<div class="paragraph"><p><tt><strong>lsearch</strong> <em>?options? list pattern</em></tt></p></div>
|
|
<div class="paragraph"><p>This command searches the elements <tt><em>list</em></tt> to see if one of them matches <tt><em>pattern</em></tt>. If so, the
|
|
command returns the index of the first matching element (unless the options <tt>-all</tt>, <tt>-inline</tt> or <tt>-bool</tt> are
|
|
specified.) If not, the command returns -1. The option arguments indicates how the elements of
|
|
the list are to be matched against pattern and must have one of the values below:</p></div>
|
|
<div class="paragraph"><p><strong>Note</strong> that this command is different from Tcl in that default match type is <tt>-exact</tt> rather than <tt>-glob</tt>.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-exact</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt><em>pattern</em></tt> is a literal string that is compared for exact equality against each list element.
|
|
This is the default.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-glob</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt><em>pattern</em></tt> is a glob-style pattern which is matched against each list element using the same
|
|
rules as the string match command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-regexp</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt><em>pattern</em></tt> is treated as a regular expression and matched against each list element using
|
|
the rules described by <a href="#_regexp"><strong><tt>regexp</tt></strong></a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-command</strong> <em>cmdname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt><em>cmdname</em></tt> is a command which is used to match the pattern against each element of the
|
|
list. It is invoked as <tt><em>cmdname</em> ?<strong>-nocase</strong>? <em>pattern listvalue</em></tt> and should return 1
|
|
for a match, or 0 for no match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-all</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Changes the result to be the list of all matching indices (or all matching values if
|
|
<tt>-inline</tt> is specified as well). If indices are returned, the indices will be in numeric
|
|
order. If values are returned, the order of the values will be the order of those values
|
|
within the input list.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-inline</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The matching value is returned instead of its index (or an empty string if no value
|
|
matches). If <tt>-all</tt> is also specified, then the result of the command is the list of all
|
|
values that matched. The <tt>-inline</tt> and <tt>-bool</tt> options are mutually exclusive.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-bool</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Changes the result to <em>1</em> if a match was found, or <em>0</em> otherwise. If <tt>-all</tt> is also specified,
|
|
the result will be a list of <em>0</em> and <em>1</em> for each element of the list depending upon whether
|
|
the corresponding element matches. The <tt>-inline</tt> and <tt>-bool</tt> options are mutually exclusive.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-not</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This negates the sense of the match, returning the index (or value
|
|
if <tt>-inline</tt> is specified) of the first non-matching value in the
|
|
list. If <tt>-bool</tt> is also specified, the <em>0</em> will be returned if a
|
|
match is found, or <em>1</em> otherwise. If <tt>-all</tt> is also specified,
|
|
non-matches will be returned rather than matches.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-nocase</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes comparisons to be handled in a case-insensitive manner.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lsort">lsort</h3>
|
|
<div class="paragraph"><p><tt><strong>lsort</strong> ?<strong>-index</strong> <em>listindex</em>? ?<strong>-integer</strong>|<strong>-command</strong> <em>cmdname</em>? ?<strong>-decreasing</strong>|<strong>-increasing</strong>? <em>list</em></tt></p></div>
|
|
<div class="paragraph"><p>Sort the elements of <tt><em>list</em></tt>, returning a new list in sorted order.
|
|
By default, ASCII sorting is used, with the result in increasing order.</p></div>
|
|
<div class="paragraph"><p>If <tt>-integer</tt> is specified, numeric sorting is used.</p></div>
|
|
<div class="paragraph"><p>If <tt>-command <em>cmdname</em></tt> is specified, <tt><em>cmdname</em></tt> is treated as a command
|
|
name. For each comparison, <tt><em>cmdname $value1 $value2</tt></em> is called which
|
|
should compare the values and return an integer less than, equal
|
|
to, or greater than zero if the <tt><em>$value1</em></tt> is to be considered less
|
|
than, equal to, or greater than <tt><em>$value2</em></tt>, respectively.</p></div>
|
|
<div class="paragraph"><p>If <tt>-decreasing</tt> is specified, the resulting list is in the opposite
|
|
order to what it would be otherwise. <tt>-increasing</tt> is the default.</p></div>
|
|
<div class="paragraph"><p>If <tt>-index <em>listindex</em></tt> is specified, each element of the list is treated as a list and
|
|
the given index is extracted from the list for comparison. The list index may
|
|
be any valid list index, such as <tt>1</tt>, <tt>end</tt> or <tt>end-2</tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt>-index <em>listindex</em></tt> is specified, each element of the list is treated as a list and
|
|
the given index is extracted from the list for comparison. The list index may
|
|
be any valid list index, such as <tt>1</tt>, <tt>end</tt> or <tt>end-2</tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_open">open</h3>
|
|
<div class="paragraph"><p><tt><strong>open</strong> <em>fileName ?access?</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>open</strong> <em>|command-pipeline ?access?</em></tt></p></div>
|
|
<div class="paragraph"><p>Opens a file and returns an identifier
|
|
that may be used in future invocations
|
|
of commands like <a href="#_read"><strong><tt>read</tt></strong></a>, <a href="#_puts"><strong><tt>puts</tt></strong></a>, and <a href="#_close"><strong><tt>close</tt></strong></a>.
|
|
<tt><em>fileName</em></tt> gives the name of the file to open.</p></div>
|
|
<div class="paragraph"><p>The <tt><em>access</em></tt> argument indicates the way in which the file is to be accessed.
|
|
It may have any of the following values:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>r</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for reading only; the file must already exist.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>r</tt>+
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for both reading and writing; the file must
|
|
already exist.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>w</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for writing only. Truncate it if it exists. If it doesn’t
|
|
exist, create a new file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>w</tt>+
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for reading and writing. Truncate it if it exists.
|
|
If it doesn’t exist, create a new file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>a</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for writing only. The file must already exist, and the file
|
|
is positioned so that new data is appended to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>a</tt>+
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for reading and writing. If the file doesn’t
|
|
exist, create a new empty file. Set the initial access position
|
|
to the end of the file.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p><tt><em>access</em></tt> defaults to <em>r</em>.</p></div>
|
|
<div class="paragraph"><p>If a file is opened for both reading and writing, then <a href="#_seek"><strong><tt>seek</tt></strong></a>
|
|
must be invoked between a read and a write, or vice versa.</p></div>
|
|
<div class="paragraph"><p>If the first character of <tt><em>fileName</em></tt> is "|" then the remaining
|
|
characters of <tt><em>fileName</em></tt> are treated as a list of arguments that
|
|
describe a command pipeline to invoke, in the same style as the
|
|
arguments for exec. In this case, the channel identifier returned
|
|
by open may be used to write to the command’s input pipe or read
|
|
from its output pipe, depending on the value of <tt><em>access</em></tt>. If write-only
|
|
access is used (e.g. <tt><em>access</em></tt> is <em>w</em>), then standard output for the
|
|
pipeline is directed to the current standard output unless overridden
|
|
by the command. If read-only access is used (e.g. <tt><em>access</em></tt> is r),
|
|
standard input for the pipeline is taken from the current standard
|
|
input unless overridden by the command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_pid"><strong><tt>pid</tt></strong></a> command may be used to return the process ids of the commands
|
|
forming the command pipeline.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_socket"><strong><tt>socket</tt></strong></a>, <a href="#_pid"><strong><tt>pid</tt></strong></a>, <a href="#_exec"><strong><tt>exec</tt></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_package">package</h3>
|
|
<div class="paragraph"><p><tt><strong>package provide</strong> <em>name ?version?</em></tt></p></div>
|
|
<div class="paragraph"><p>Indicates that the current script provides the package named <tt><em>name</em></tt>.
|
|
If no version is specified, <em>1.0</em> is used.</p></div>
|
|
<div class="paragraph"><p>Any script which provides a package may include this statement
|
|
as the first statement, although it is not required.</p></div>
|
|
<div class="paragraph"><p><tt><strong>package require</strong> <em>name ?version?</em>*</tt></p></div>
|
|
<div class="paragraph"><p>Searches for the package with the given <tt><em>name</em></tt> by examining each path
|
|
in <em>$::auto_path</em> and trying to load <em>$path/$name.so</em> as a dynamic extension,
|
|
or <em>$path/$name.tcl</em> as a script package.</p></div>
|
|
<div class="paragraph"><p>The first such file which is found is considered to provide the the package.
|
|
(The version number is ignored).</p></div>
|
|
<div class="paragraph"><p>If <em>$name.so</em> exists, it is loaded with the <a href="#_load"><strong><tt>load</tt></strong></a> command,
|
|
otherwise if <em>$name.tcl</em> exists it is loaded with the <a href="#_source"><strong><tt>source</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If <a href="#_load"><strong><tt>load</tt></strong></a> or <a href="#_source"><strong><tt>source</tt></strong></a> fails, <a href="#_package"><strong><tt>package</tt></strong></a> <tt>require</tt> will fail immediately.
|
|
No further attempt will be made to locate the file.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_pid">pid</h3>
|
|
<div class="paragraph"><p><tt><strong>pid</strong></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>pid</strong> <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p>The first form returns the process identifier of the current process.</p></div>
|
|
<div class="paragraph"><p>The second form accepts a handle returned by <a href="#_open"><strong><tt>open</tt></strong></a> and returns a list
|
|
of the process ids forming the pipeline in the same form as <a href="#_exec"><strong><tt>exec</tt></strong></a> <tt>... &</tt>.
|
|
If <em>fileId</em> represents a regular file handle rather than a command pipeline,
|
|
the empty string is returned instead.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_open"><strong><tt>open</tt></strong></a>, <a href="#_exec"><strong><tt>exec</tt></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_proc">proc</h3>
|
|
<div class="paragraph"><p><tt><strong>proc</strong> <em>name args ?statics? body</em></tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_proc"><strong><tt>proc</tt></strong></a> command creates a new Tcl command procedure, <tt><em>name</em></tt>.
|
|
When the new command is invoked, the contents of <tt><em>body</em></tt> will be executed.
|
|
Tcl interpreter. <tt><em>args</em></tt> specifies the formal arguments to the procedure.
|
|
If specified, <tt><em>static</em></tt>, declares static variables which are bound to the
|
|
procedure.</p></div>
|
|
<div class="paragraph"><p>See PROCEDURES for detailed information about Tcl procedures.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_proc"><strong><tt>proc</tt></strong></a> command returns <tt><em>name</em></tt> (which is useful with <a href="#_local"><strong><tt>local</tt></strong></a>).</p></div>
|
|
<div class="paragraph"><p>When a procedure is invoked, the procedure’s return value is the
|
|
value specified in a <a href="#_return"><strong><tt>return</tt></strong></a> command. If the procedure doesn’t
|
|
execute an explicit <a href="#_return"><strong><tt>return</tt></strong></a>, then its return value is the value
|
|
of the last command executed in the procedure’s body.</p></div>
|
|
<div class="paragraph"><p>If an error occurs while executing the procedure body, then the
|
|
procedure-as-a-whole will return that same error.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_puts">puts</h3>
|
|
<div class="paragraph"><p><tt><strong>puts</strong> ?<strong>-nonewline</strong>? <em>?fileId? string</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>puts</strong> ?<strong>-nonewline</strong>? <em>string</em></tt></p></div>
|
|
<div class="paragraph"><p>Writes the characters given by <tt><em>string</em></tt> to the file given
|
|
by <tt><em>fileId</em></tt>. <tt><em>fileId</em></tt> must have been the return
|
|
value from a previous call to <a href="#_open"><strong><tt>open</tt></strong></a>, or it may be
|
|
<tt>stdout</tt> or <tt>stderr</tt> to refer to one of the standard I/O
|
|
channels; it must refer to a file that was opened for
|
|
writing.</p></div>
|
|
<div class="paragraph"><p>In the first form, if no <tt><em>fileId</em></tt> is specified then it defaults to <tt>stdout</tt>.
|
|
<a href="#_puts"><strong><tt>puts</tt></strong></a> normally outputs a newline character after <tt><em>string</em></tt>,
|
|
but this feature may be suppressed by specifying the <tt>-nonewline</tt>
|
|
switch.</p></div>
|
|
<div class="paragraph"><p>Output to files is buffered internally by Tcl; the <a href="#_flush"><strong><tt>flush</tt></strong></a>
|
|
command may be used to force buffered characters to be output.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_pwd">pwd</h3>
|
|
<div class="paragraph"><p><tt><strong>pwd</strong></tt></p></div>
|
|
<div class="paragraph"><p>Returns the path name of the current working directory.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_rand">rand</h3>
|
|
<div class="paragraph"><p><tt><strong>rand</strong> <em>?min? ?max?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a random integer between <tt><em>min</em></tt> (defaults to 0) and <tt><em>max</em></tt>
|
|
(defaults to the maximum integer).</p></div>
|
|
<div class="paragraph"><p>If only one argument is given, it is interpreted as <tt><em>max</em></tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_range">range</h3>
|
|
<div class="paragraph"><p><tt><strong>range</strong> <em>?start? end ?step?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a list of integers starting at <tt><em>start</em></tt> (defaults to 0)
|
|
and ranging up to but not including <tt><em>end</em></tt> in steps of <tt><em>step</em></tt> defaults to 1).</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> range 5
|
|
0 1 2 3 4
|
|
jim> range 2 5
|
|
2 3 4
|
|
jim> range 2 10 4
|
|
2 6
|
|
jim> range 7 4 -2
|
|
7 5</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_read">read</h3>
|
|
<div class="paragraph"><p><tt><strong>read</strong> ?<strong>-nonewline</strong>? <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>read</strong> ?<strong>-nonewline</strong>?</tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>read</strong> <em>fileId numBytes</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>read</strong> <em>numBytes</em></tt></p></div>
|
|
<div class="paragraph"><p>In the first form, all of the remaining bytes are read from the file
|
|
given by <tt><em>fileId</em></tt>; they are returned as the result of the command.
|
|
If the <tt>-nonewline</tt> switch is specified then the last
|
|
character of the file is discarded if it is a newline.</p></div>
|
|
<div class="paragraph"><p>In the second form, the extra argument specifies how many bytes to read;
|
|
exactly this many bytes will be read and returned, unless there are fewer than
|
|
<tt><em>numBytes</em></tt> bytes left in the file; in this case, all the remaining
|
|
bytes are returned.</p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em></tt> must be <tt>stdin</tt> or the return value from a previous call
|
|
to <a href="#_open"><strong><tt>open</tt></strong></a>; it must refer to a file that was opened for reading.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_regexp">regexp</h3>
|
|
<div class="paragraph"><p><tt><strong>regexp ?-nocase? ?-line? ?-indices? ?-start</strong> <em>offset</em>? <strong>?-all? ?-inline? ?--?</strong> <em>exp string ?matchVar? ?subMatchVar subMatchVar ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Determines whether the regular expression <tt><em>exp</em></tt> matches part or
|
|
all of <tt><em>string</em></tt> and returns 1 if it does, 0 if it doesn’t.</p></div>
|
|
<div class="paragraph"><p>See REGULAR EXPRESSIONS above for complete information on the
|
|
syntax of <tt><em>exp</em></tt> and how it is matched against <tt><em>string</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If additional arguments are specified after <tt><em>string</em></tt> then they
|
|
are treated as the names of variables to use to return
|
|
information about which part(s) of <tt><em>string</em></tt> matched <tt><em>exp</em></tt>.
|
|
<tt><em>matchVar</em></tt> will be set to the range of <tt><em>string</em></tt> that
|
|
matched all of <tt><em>exp</em></tt>. The first <tt><em>subMatchVar</em></tt> will contain
|
|
the characters in <tt><em>string</em></tt> that matched the leftmost parenthesized
|
|
subexpression within <tt><em>exp</em></tt>, the next <tt><em>subMatchVar</em></tt> will
|
|
contain the characters that matched the next parenthesized
|
|
subexpression to the right in <tt><em>exp</em></tt>, and so on.</p></div>
|
|
<div class="paragraph"><p>Normally, <tt><em>matchVar</em></tt> and the each <tt><em>subMatchVar</em></tt> are set to hold the
|
|
matching characters from <a href="#_string"><strong><tt>string</tt></strong></a>, however see <tt>-indices</tt> and
|
|
<tt>-inline</tt> below.</p></div>
|
|
<div class="paragraph"><p>If there are more values for <tt><em>subMatchVar</em></tt> than parenthesized subexpressions
|
|
within <tt><em>exp</em></tt>, or if a particular subexpression in <tt><em>exp</em></tt> doesn’t
|
|
match the string (e.g. because it was in a portion of the expression
|
|
that wasn’t matched), then the corresponding <tt><em>subMatchVar</em></tt> will be
|
|
set to <tt>"-1 -1"</tt> if <tt>-indices</tt> has been specified or to an empty
|
|
string otherwise.</p></div>
|
|
<div class="paragraph"><p>The following switches modify the behaviour of <tt><em>regexp</em></tt></p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-nocase</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes upper-case and lower-case characters to be treated as
|
|
identical during the matching process.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-line</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use newline-sensitive matching. By default, newline
|
|
is a completely ordinary character with no special meaning in
|
|
either REs or strings. With this flag, <tt>[<sup></tt> bracket expressions
|
|
and <tt>.</tt> never match newline, a <tt></sup></tt> anchor matches the null
|
|
string after any newline in the string in addition to its normal
|
|
function, and the <tt>$</tt> anchor matches the null string before any
|
|
newline in the string in addition to its normal function.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-indices</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Changes what is stored in the subMatchVars. Instead of
|
|
storing the matching characters from string, each variable
|
|
will contain a list of two decimal strings giving the indices
|
|
in string of the first and last characters in the matching
|
|
range of characters.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-start</strong> <em>offset</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Specifies a character index offset into the string at which to start
|
|
matching the regular expression. If <tt>-indices</tt> is
|
|
specified, the indices will be indexed starting from the
|
|
absolute beginning of the input string. <tt><em>offset</em></tt> will be
|
|
constrained to the bounds of the input string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-all</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes the regular expression to be matched as many times as possible
|
|
in the string, returning the total number of matches found. If this
|
|
is specified with match variables, they will contain information
|
|
for the last match only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-inline</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes the command to return, as a list, the data that would otherwise
|
|
be placed in match variables. When using <tt>-inline</tt>, match variables
|
|
may not be specified. If used with <tt>-all</tt>, the list will be concatenated
|
|
at each iteration, such that a flat list is always returned. For
|
|
each match iteration, the command will append the overall match
|
|
data, plus one element for each subexpression in the regular
|
|
expression.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>--</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of switches. The argument following this one will be
|
|
treated as <tt><em>exp</em></tt> even if it starts with a <tt>-</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_regsub">regsub</h3>
|
|
<div class="paragraph"><p><tt><strong>regsub ?-nocase? ?-all? ?-line? ?-start</strong> <em>offset</em>? ?<strong>--</strong>? <em>exp string subSpec ?varName?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command matches the regular expression <tt><em>exp</em></tt> against
|
|
<tt><em>string</em></tt> using the rules described in REGULAR EXPRESSIONS
|
|
above.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> is specified, the commands stores <tt><em>string</em></tt> to <tt><em>varName</em></tt>
|
|
with the substitutions detailed below, and returns the number of
|
|
substitutions made (normally 1 unless <tt>-all</tt> is specified).
|
|
This is 0 if there were no matches.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> is not specified, the substituted string will be returned
|
|
instead.</p></div>
|
|
<div class="paragraph"><p>When copying <tt><em>string</em></tt>, the portion of <tt><em>string</em></tt> that
|
|
matched <tt><em>exp</em></tt> is replaced with <tt><em>subSpec</em></tt>.
|
|
If <tt><em>subSpec</em></tt> contains a <tt>&</tt> or <tt>\0</tt>, then it is replaced
|
|
in the substitution with the portion of <tt><em>string</em></tt> that
|
|
matched <tt><em>exp</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>subSpec</em></tt> contains a <tt>\n</tt>, where <tt><em>n</em></tt> is a digit
|
|
between 1 and 9, then it is replaced in the substitution with
|
|
the portion of <tt><em>string</em></tt> that matched the <tt><em>n</em></tt>'-th
|
|
parenthesized subexpression of <tt><em>exp</em></tt>.
|
|
Additional backslashes may be used in <tt><em>subSpec</em></tt> to prevent special
|
|
interpretation of <tt>&</tt> or <tt>\0</tt> or <tt>\n</tt> or
|
|
backslash.</p></div>
|
|
<div class="paragraph"><p>The use of backslashes in <tt><em>subSpec</em></tt> tends to interact badly
|
|
with the Tcl parser’s use of backslashes, so it’s generally
|
|
safest to enclose <tt><em>subSpec</em></tt> in braces if it includes
|
|
backslashes.</p></div>
|
|
<div class="paragraph"><p>The following switches modify the behaviour of <tt><em>regsub</em></tt></p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-nocase</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Upper-case characters in <tt><em>string</em></tt> are converted to lower-case
|
|
before matching against <tt><em>exp</em></tt>; however, substitutions
|
|
specified by <tt><em>subSpec</em></tt> use the original unconverted form
|
|
of <tt><em>string</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-all</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
All ranges in <tt><em>string</em></tt> that match <tt><em>exp</em></tt> are found and substitution
|
|
is performed for each of these ranges, rather than only the
|
|
first. The <tt>&</tt> and <tt>\n</tt> sequences are handled for
|
|
each substitution using the information from the corresponding
|
|
match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-line</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use newline-sensitive matching. By default, newline
|
|
is a completely ordinary character with no special meaning in
|
|
either REs or strings. With this flag, <tt>[<sup></tt> bracket expressions
|
|
and <tt>.</tt> never match newline, a <tt></sup></tt> anchor matches the null
|
|
string after any newline in the string in addition to its normal
|
|
function, and the <tt>$</tt> anchor matches the null string before any
|
|
newline in the string in addition to its normal function.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-start</strong> <em>offset</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Specifies a character index offset into the string at which to
|
|
start matching the regular expression. <tt><em>offset</em></tt> will be
|
|
constrained to the bounds of the input string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>--</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of switches. The argument following this one will be
|
|
treated as <tt><em>exp</em></tt> even if it starts with a <tt>-</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_ref">ref</h3>
|
|
<div class="paragraph"><p><tt><strong>ref</strong> <em>string tag ?finalizer?</em></tt></p></div>
|
|
<div class="paragraph"><p>Create a new reference containing <tt><em>string</em></tt> of type <tt><em>tag</em></tt>.
|
|
If <tt><em>finalizer</em></tt> is specified, it is a command which will be invoked
|
|
when the a garbage collection cycle runs and this reference is
|
|
no longer accessible.</p></div>
|
|
<div class="paragraph"><p>The finalizer is invoked as:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>finalizer reference string</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_rename">rename</h3>
|
|
<div class="paragraph"><p><tt><strong>rename</strong> <em>oldName newName</em></tt></p></div>
|
|
<div class="paragraph"><p>Rename the command that used to be called <tt><em>oldName</em></tt> so that it
|
|
is now called <tt><em>newName</em></tt>. If <tt><em>newName</em></tt> is an empty string
|
|
(e.g. {}) then <tt><em>oldName</em></tt> is deleted. The <a href="#_rename"><strong><tt>rename</tt></strong></a> command
|
|
returns an empty string as result.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_return">return</h3>
|
|
<div class="paragraph"><p><tt><strong>return</strong> ?<strong>-code</strong> <em>code</em>? ?<strong>-errorinfo</strong> <em>stacktrace</em>? ?<strong>-errorcode</strong> <em>errorcode</em>? ?<strong>-level</strong> <em>n</em>? ?<em>value</em>?</tt></p></div>
|
|
<div class="paragraph"><p>Return immediately from the current procedure (or top-level command
|
|
or <a href="#_source"><strong><tt>source</tt></strong></a> command), with <tt><em>value</em></tt> as the return value. If <tt><em>value</em></tt>
|
|
is not specified, an empty string will be returned as result.</p></div>
|
|
<div class="paragraph"><p>If <tt>-code</tt> is specified (as either a number or ok, error, break,
|
|
continue, signal, return or exit), this code will be used instead
|
|
of <tt>JIM_OK</tt>. This is generally useful when implementing flow of control
|
|
commands.</p></div>
|
|
<div class="paragraph"><p>If <tt>-level</tt> is specified and greater than 1, it has the effect of delaying
|
|
the new return code from <tt>-code</tt>. This is useful when rethrowing an error
|
|
from <a href="#_catch"><strong><tt>catch</tt></strong></a>. See the implementation of try/catch in tclcompat.tcl for
|
|
an example of how this is done.</p></div>
|
|
<div class="paragraph"><p>Note: The following options are only used when <tt>-code</tt> is JIM_ERR.</p></div>
|
|
<div class="paragraph"><p>If <tt>-errorinfo</tt> is specified (as returned from <a href="#_info"><strong><tt>info</tt></strong></a> <tt>stacktrace</tt>)
|
|
it is used to initialize the stacktrace.</p></div>
|
|
<div class="paragraph"><p>If <tt>-errorcode</tt> is specified, it is used to set the global variable $::errorCode.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_scan">scan</h3>
|
|
<div class="paragraph"><p><tt><strong>scan</strong> <em>string format varName1 ?varName2 ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command parses fields from an input string in the same fashion
|
|
as the C <em>sscanf</em> procedure. <tt><em>string</em></tt> gives the input to be parsed
|
|
and <tt><em>format</em></tt> indicates how to parse it, using <em>%</em> fields as in
|
|
<em>sscanf</em>. All of the <em>sscanf</em> options are valid; see the <em>sscanf</em>
|
|
man page for details. Each <tt><em>varName</em></tt> gives the name of a variable;
|
|
when a field is scanned from <tt><em>string</em></tt>, the result is converted back
|
|
into a string and assigned to the corresponding <tt><em>varName</em></tt>. The
|
|
only unusual conversion is for <em>%c</em>. For <em>%c</em> conversions a single
|
|
character value is converted to a decimal string, which is then
|
|
assigned to the corresponding <tt><em>varName</em></tt>; no field width may be
|
|
specified for this conversion.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_seek">seek</h3>
|
|
<div class="paragraph"><p><tt><strong>seek</strong> <em>fileId offset ?origin?</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>seek</strong> <em>offset ?origin?</em></tt></p></div>
|
|
<div class="paragraph"><p>Change the current access position for <tt><em>fileId</em></tt>.
|
|
The <tt><em>offset</em></tt> and <tt><em>origin</em></tt> arguments specify the position at
|
|
which the next read or write will occur for <tt><em>fileId</em></tt>.
|
|
<tt><em>offset</em></tt> must be a number (which may be negative) and <tt><em>origin</em></tt>
|
|
must be one of the following:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>start</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <tt><em>offset</em></tt> bytes from the start
|
|
of the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>current</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <tt><em>offset</em></tt> bytes from the current
|
|
access position; a negative <tt><em>offset</em></tt> moves the access position
|
|
backwards in the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>end</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <tt><em>offset</em></tt> bytes from the end of
|
|
the file. A negative <tt><em>offset</em></tt> places the access position before
|
|
the end-of-file, and a positive <tt><em>offset</em></tt> places the access position
|
|
after the end-of-file.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The <tt><em>origin</em></tt> argument defaults to <tt>start</tt>.</p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em></tt> must have been the return value from a previous call to
|
|
<a href="#_open"><strong><tt>open</tt></strong></a>, or it may be <tt>stdin</tt>, <tt>stdout</tt>, or <tt>stderr</tt> to refer to one
|
|
of the standard I/O channels.</p></div>
|
|
<div class="paragraph"><p>This command returns an empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_set">set</h3>
|
|
<div class="paragraph"><p><tt><strong>set</strong> <em>varName ?value?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns the value of variable <tt><em>varName</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>value</em></tt> is specified, then set the value of <tt><em>varName</em></tt> to <tt><em>value</em></tt>,
|
|
creating a new variable if one doesn’t already exist, and return
|
|
its value.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>varName</em></tt> contains an open parenthesis and ends with a
|
|
close parenthesis, then it refers to an array element: the characters
|
|
before the open parenthesis are the name of the array, and the characters
|
|
between the parentheses are the index within the array.
|
|
Otherwise <tt><em>varName</em></tt> refers to a scalar variable.</p></div>
|
|
<div class="paragraph"><p>If no procedure is active, then <tt><em>varName</em></tt> refers to a global
|
|
variable.</p></div>
|
|
<div class="paragraph"><p>If a procedure is active, then <tt><em>varName</em></tt> refers to a parameter
|
|
or local variable of the procedure, unless the <tt><em>global</em></tt> command
|
|
has been invoked to declare <tt><em>varName</em></tt> to be global.</p></div>
|
|
<div class="paragraph"><p>The <tt>::</tt> prefix may also be used to explicitly reference a variable
|
|
in the global scope.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_setref">setref</h3>
|
|
<div class="paragraph"><p><tt><strong>setref</strong> <em>reference string</em></tt></p></div>
|
|
<div class="paragraph"><p>Store a new string in <tt><em>reference</em></tt>, replacing the existing string.
|
|
The reference must be a valid reference create with the <a href="#_ref"><strong><tt>ref</tt></strong></a>
|
|
command.</p></div>
|
|
<div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_signal">signal</h3>
|
|
<div class="paragraph"><p>Command for signal handling.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_kill"><strong><tt>kill</tt></strong></a> for the different forms which may be used to specify signals.</p></div>
|
|
<div class="paragraph"><p>Commands which return a list of signal names do so using the canonical form:
|
|
"<tt>SIGINT SIGTERM</tt>".</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>signal handle</strong> ?<em>signals ...</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no signals are given, returns a list of all signals which are currently
|
|
being handled.
|
|
If signals are specified, these are added to the list of signals currently
|
|
being handled.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>signal ignore</strong> ?<em>signals ...</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no signals are given, returns a lists all signals which are currently
|
|
being ignored.
|
|
If signals are specified, these are added to the list of signals
|
|
currently being ignored. These signals are still delivered, but
|
|
are not considered by <a href="#_catch"><strong><tt>catch</tt></strong></a> <tt>-signal</tt> or <a href="#_try"><strong><tt>try</tt></strong></a> <tt>-signal</tt>. Use
|
|
<a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>check</tt> to determine which signals have occurred but
|
|
been ignored.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>signal default</strong> ?<em>signals ...</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no signals are given, returns a lists all signals which are currently have
|
|
the default behaviour.
|
|
If signals are specified, these are added to the list of signals which have
|
|
the default behaviour.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>signal check ?-clear?</strong> ?<em>signals ...</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of signals which have been delivered to the process
|
|
but are <em>ignored</em>. If signals are specified, only that set of signals will
|
|
be checked, otherwise all signals will be checked.
|
|
If <tt>-clear</tt> is specified, any signals returned are removed and will not be
|
|
returned by subsequent calls to <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>check</tt> unless delivered again.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>signal throw</strong> ?<em>signal</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Raises the given signal, which defaults to <tt>SIGINT</tt> if not specified.
|
|
The behaviour is identical to:
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>kill signal [pid]</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>Note that <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>handle</tt> and <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>ignore</tt> represent two forms of signal
|
|
handling. <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>handle</tt> is used in conjunction with <a href="#_catch"><strong><tt>catch</tt></strong></a> <tt>-signal</tt> or <a href="#_try"><strong><tt>try</tt></strong></a> <tt>-signal</tt>
|
|
to immediately abort execution when the signal is delivered. Alternatively, <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>ignore</tt>
|
|
is used in conjunction with <a href="#_signal"><strong><tt>signal</tt></strong></a> <tt>check</tt> to handle signal synchronously. Consider the
|
|
two examples below.</p></div>
|
|
<div class="paragraph"><p>Prevent a processing from taking too long</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>signal handle SIGALRM
|
|
alarm 20
|
|
try -signal {
|
|
.. possibly long running process ..
|
|
alarm 0
|
|
} on signal {sig} {
|
|
puts stderr "Process took too long"
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Handle SIGHUP to reconfigure:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>signal ignore SIGHUP
|
|
while {1} {
|
|
... handle configuration/reconfiguration ...
|
|
while {[signal check -clear SIGHUP] eq ""} {
|
|
... do processing ..
|
|
}
|
|
# Received SIGHUP, so reconfigure
|
|
}</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_sleep">sleep</h3>
|
|
<div class="paragraph"><p><tt><strong>sleep</strong> <em>seconds</em></tt></p></div>
|
|
<div class="paragraph"><p>Pauses for the given number of seconds, which may be a floating
|
|
point value less than one to sleep for less than a second, or an
|
|
integer to sleep for one or more seconds.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_source">source</h3>
|
|
<div class="paragraph"><p><tt><strong>source</strong> <em>fileName</em></tt></p></div>
|
|
<div class="paragraph"><p>Read file <tt><em>fileName</em></tt> and pass the contents to the Tcl interpreter
|
|
as a sequence of commands to execute in the normal fashion. The return
|
|
value of <a href="#_source"><strong><tt>source</tt></strong></a> is the return value of the last command executed
|
|
from the file. If an error occurs in executing the contents of the
|
|
file, then the <a href="#_source"><strong><tt>source</tt></strong></a> command will return that error.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_return"><strong><tt>return</tt></strong></a> command is invoked from within the file, the remainder of
|
|
the file will be skipped and the <a href="#_source"><strong><tt>source</tt></strong></a> command will return
|
|
normally with the result from the <a href="#_return"><strong><tt>return</tt></strong></a> command.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_split">split</h3>
|
|
<div class="paragraph"><p><tt><strong>split</strong> <em>string ?splitChars?</em></tt></p></div>
|
|
<div class="paragraph"><p>Returns a list created by splitting <tt><em>string</em></tt> at each character
|
|
that is in the <tt><em>splitChars</em></tt> argument.</p></div>
|
|
<div class="paragraph"><p>Each element of the result list will consist of the
|
|
characters from <tt><em>string</em></tt> between instances of the
|
|
characters in <tt><em>splitChars</em></tt>.</p></div>
|
|
<div class="paragraph"><p>Empty list elements will be generated if <tt><em>string</em></tt> contains
|
|
adjacent characters in <tt><em>splitChars</em></tt>, or if the first or last
|
|
character of <tt><em>string</em></tt> is in <tt><em>splitChars</em></tt>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>splitChars</em></tt> is an empty string then each character of
|
|
<tt><em>string</em></tt> becomes a separate element of the result list.</p></div>
|
|
<div class="paragraph"><p><tt><em>splitChars</em></tt> defaults to the standard white-space characters.
|
|
For example,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>split "comp.unix.misc" .</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>returns <tt><em>"comp unix misc"</em></tt> and</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>split "Hello world" {}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>returns <tt><em>"H e l l o { } w o r l d"</em></tt>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_stackdump">stackdump</h3>
|
|
<div class="paragraph"><p><tt><strong>stackdump</strong> <em>stacktrace</em></tt></p></div>
|
|
<div class="paragraph"><p>Creates a human readable representation of a stack trace.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_stacktrace">stacktrace</h3>
|
|
<div class="paragraph"><p><tt><strong>stacktrace</strong></tt></p></div>
|
|
<div class="paragraph"><p>Returns a live stack trace as a list of <tt>proc file line proc file line ...</tt>.
|
|
Iteratively uses <a href="#_info"><strong><tt>info</tt></strong></a> <tt>frame</tt> to create the stack trace. This stack trace is in the
|
|
same form as produced by <a href="#_catch"><strong><tt>catch</tt></strong></a> and <a href="#_info"><strong><tt>info</tt></strong></a> <tt>stacktrace</tt></p></div>
|
|
<div class="paragraph"><p>See also <a href="#_stackdump"><strong><tt>stackdump</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_string">string</h3>
|
|
<div class="paragraph"><p><tt><strong>string</strong> <em>option arg ?arg ...?</em></tt></p></div>
|
|
<div class="paragraph"><p>Perform one of several string operations, depending on <tt><em>option</em></tt>.
|
|
The legal options (which may be abbreviated) are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string bytelength</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the length of the string in bytes. This will return
|
|
the same value as <a href="#_string"><strong><tt>string</tt></strong></a> <tt>length</tt> if UTF-8 support is not enabled,
|
|
or if the string is composed entirely of ASCII characters.
|
|
See UTF-8 AND UNICODE.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string byterange</strong> <em>string first last</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Like <a href="#_string"><strong><tt>string</tt></strong></a> <tt>range</tt> except works on bytes rather than characters.
|
|
These commands are identical if UTF-8 support is not enabled.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string compare ?-nocase?</strong> <em>string1 string2</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Perform a character-by-character comparison of strings <tt><em>string1</em></tt> and
|
|
<tt><em>string2</em></tt> in the same way as the C <em>strcmp</em> procedure. Return
|
|
-1, 0, or 1, depending on whether <tt><em>string1</em></tt> is lexicographically
|
|
less than, equal to, or greater than <tt><em>string2</em></tt>.
|
|
Performs a case-insensitive comparison if <tt>-nocase</tt> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string equal ?-nocase?</strong> <em>string1 string2</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if the strings are equal, or 0 otherwise.
|
|
Performs a case-insensitive comparison if <tt>-nocase</tt> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string first</strong> <em>string1 string2 ?firstIndex?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Search <tt><em>string2</em></tt> for a sequence of characters that exactly match
|
|
the characters in <tt><em>string1</em></tt>. If found, return the index of the
|
|
first character in the first such match within <tt><em>string2</em></tt>. If not
|
|
found, return -1. If <tt><em>firstIndex</em></tt> is specified, matching will start
|
|
from <tt><em>firstIndex</em></tt> of <tt><em>string1</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>firstIndex</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string index</strong> <em>string charIndex</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the <tt><em>charIndex</em></tt><em>th character of the <tt>'string</em></tt>
|
|
argument. A <tt><em>charIndex</em></tt> of 0 corresponds to the first
|
|
character of the string.
|
|
If <tt><em>charIndex</em></tt> is less than 0 or greater than
|
|
or equal to the length of the string then an empty string is
|
|
returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>charIndex</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string is</strong> <em>class</em> ?<strong>-strict</strong>? <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if <tt><em>string</em></tt> is a valid member of the specified character
|
|
class, otherwise returns 0. If <tt>-strict</tt> is specified, then an
|
|
empty string returns 0, otherwise an empty string will return 1
|
|
on any class. The following character classes are recognized
|
|
(the class name can be abbreviated):
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>alnum</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any alphabet or digit character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>alpha</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>ascii</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any character with a value less than 128 (those that are in the 7-bit ascii range).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>control</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any control character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>digit</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any digit character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>double</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any of the valid forms for a double in Tcl, with optional surrounding whitespace.
|
|
In case of under/overflow in the value, 0 is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>graph</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any printing character, except space.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>integer</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>lower</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any lower case alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>print</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any printing character, including space.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>punct</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any punctuation character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>space</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any space character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>upper</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any upper case alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>xdigit</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any hexadecimal digit character ([0-9A-Fa-f]).
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Note that string classification does <tt><em>not</em></tt> respect UTF-8. See UTF-8 AND UNICODE
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string last</strong> <em>string1 string2 ?lastIndex?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Search <tt><em>string2</em></tt> for a sequence of characters that exactly match
|
|
the characters in <tt><em>string1</em></tt>. If found, return the index of the
|
|
first character in the last such match within <tt><em>string2</em></tt>. If there
|
|
is no match, then return -1. If <tt><em>lastIndex</em></tt> is specified, only characters
|
|
up to <tt><em>lastIndex</em></tt> of <tt><em>string2</em></tt> will be considered in the match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>lastIndex</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string length</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a decimal string giving the number of characters in <tt><em>string</em></tt>.
|
|
If UTF-8 support is enabled, this may be different than the number of bytes.
|
|
See UTF-8 AND UNICODE
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string map ?-nocase?</strong> <em>mapping string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Replaces substrings in <tt><em>string</em></tt> based on the key-value pairs in
|
|
<tt><em>mapping</em></tt>, which is a list of <tt>key value key value ...</tt> as in the form
|
|
returned by <a href="#_array"><strong><tt>array</tt></strong></a> <tt>get</tt>. Each instance of a key in the string will be
|
|
replaced with its corresponding value. If <tt>-nocase</tt> is specified, then
|
|
matching is done without regard to case differences. Both key and value may
|
|
be multiple characters. Replacement is done in an ordered manner, so the
|
|
key appearing first in the list will be checked first, and so on. <tt><em>string</em></tt> is
|
|
only iterated over once, so earlier key replacements will have no affect for
|
|
later key matches. For example,
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
will return the string <tt>01321221</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Note that if an earlier key is a prefix of a later one, it will completely mask the later
|
|
one. So if the previous example is reordered like this,
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
it will return the string <tt>02c322c222c</tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string match ?-nocase?</strong> <em>pattern string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See if <tt><em>pattern</em></tt> matches <tt><em>string</em></tt>; return 1 if it does, 0
|
|
if it doesn’t. Matching is done in a fashion similar to that
|
|
used by the C-shell. For the two strings to match, their contents
|
|
must be identical except that the following special sequences
|
|
may appear in <tt><em>pattern</em></tt>:
|
|
</p>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>*</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any sequence of characters in <tt><em>string</em></tt>,
|
|
including a null string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any single character in <tt><em>string</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>[<em>chars</em>]</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any character in the set given by <tt><em>chars</em></tt>.
|
|
If a sequence of the form <tt><em>x-y</em></tt> appears in <tt><em>chars</em></tt>,
|
|
then any character between <tt><em>x</em></tt> and <tt><em>y</em></tt>, inclusive,
|
|
will match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>\x</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches the single character <tt><em>x</em></tt>. This provides a way of
|
|
avoiding the special interpretation of the characters <tt>\*?[]</tt>
|
|
in <tt><em>pattern</em></tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Performs a case-insensitive comparison if <tt>-nocase</tt> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string range</strong> <em>string first last</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a range of consecutive characters from <tt><em>string</em></tt>, starting
|
|
with the character whose index is <tt><em>first</em></tt> and ending with the
|
|
character whose index is <tt><em>last</em></tt>. An index of 0 refers to the
|
|
first character of the string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <tt><em>first</em></tt> and <tt><em>last</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>first</em></tt> is less than zero then it is treated as if it were zero, and
|
|
if <tt><em>last</em></tt> is greater than or equal to the length of the string then
|
|
it is treated as if it were <tt>end</tt>. If <tt><em>first</em></tt> is greater than
|
|
<tt><em>last</em></tt> then an empty string is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string repeat</strong> <em>string count</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a new string consisting of <tt><em>string</em></tt> repeated <tt><em>count</em></tt> times.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string replace</strong> <em>string first last ?newstring?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Removes a range of consecutive characters from <tt><em>string</em></tt>, starting
|
|
with the character whose index is <tt><em>first</em></tt> and ending with the
|
|
character whose index is <tt><em>last</em></tt>. If <tt><em>newstring</em></tt> is specified,
|
|
then it is placed in the removed character range. If <tt><em>first</em></tt> is
|
|
less than zero then it is treated as if it were zero, and if <tt><em>last</em></tt>
|
|
is greater than or equal to the length of the string then it is
|
|
treated as if it were <tt>end</tt>. If <tt><em>first</em></tt> is greater than <tt><em>last</em></tt>
|
|
or the length of the initial string, or <tt><em>last</em></tt> is less than 0,
|
|
then the initial string is returned untouched.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string reverse</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a string that is the same length as <tt><em>string</em></tt> but
|
|
with its characters in the reverse order.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string tolower</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that all upper case
|
|
letters have been converted to lower case.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string totitle</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that the first character
|
|
is converted to title case (or upper case if there is no UTF-8 titlecase variant)
|
|
and all remaining characters have been converted to lower case.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string toupper</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that all lower case
|
|
letters have been converted to upper case.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string trim</strong> <em>string ?chars?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that any leading
|
|
or trailing characters from the set given by <tt><em>chars</em></tt> are
|
|
removed.
|
|
If <tt><em>chars</em></tt> is not specified then white space is removed
|
|
(spaces, tabs, newlines, and carriage returns).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string trimleft</strong> <em>string ?chars?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that any
|
|
leading characters from the set given by <tt><em>chars</em></tt> are
|
|
removed.
|
|
If <tt><em>chars</em></tt> is not specified then white space is removed
|
|
(spaces, tabs, newlines, and carriage returns).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>string trimright</strong> <em>string ?chars?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <tt><em>string</em></tt> except that any
|
|
trailing characters from the set given by <tt><em>chars</em></tt> are
|
|
removed.
|
|
If <tt><em>chars</em></tt> is not specified then white space is removed
|
|
(spaces, tabs, newlines, and carriage returns).
|
|
Null characters are always removed.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_subst">subst</h3>
|
|
<div class="paragraph"><p><tt><strong>subst ?-nobackslashes? ?-nocommands? ?-novariables?</strong> <em>string</em></tt></p></div>
|
|
<div class="paragraph"><p>This command performs variable substitutions, command substitutions,
|
|
and backslash substitutions on its string argument and returns the
|
|
fully-substituted result. The substitutions are performed in exactly
|
|
the same way as for Tcl commands. As a result, the string argument
|
|
is actually substituted twice, once by the Tcl parser in the usual
|
|
fashion for Tcl commands, and again by the subst command.</p></div>
|
|
<div class="paragraph"><p>If any of the <tt>-nobackslashes</tt>, <tt>-nocommands</tt>, or <tt>-novariables</tt> are
|
|
specified, then the corresponding substitutions are not performed.
|
|
For example, if <tt>-nocommands</tt> is specified, no command substitution
|
|
is performed: open and close brackets are treated as ordinary
|
|
characters with no special interpretation.</p></div>
|
|
<div class="paragraph"><p><strong>Note</strong>: when it performs its substitutions, subst does not give any
|
|
special treatment to double quotes or curly braces. For example,
|
|
the following script returns <tt>xyz {44}</tt>, not <tt>xyz {$a}</tt>.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set a 44
|
|
subst {xyz {$a}}</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_switch">switch</h3>
|
|
<div class="paragraph"><p><tt><strong>switch</strong> <em>?options? string pattern body ?pattern body ...?</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><strong>switch</strong> <em>?options? string {pattern body ?pattern body ...?}</em></tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_switch"><strong><tt>switch</tt></strong></a> command matches its string argument against each of
|
|
the pattern arguments in order. As soon as it finds a pattern that
|
|
matches string it evaluates the following body and returns the
|
|
result of that evaluation. If the last pattern argument is default
|
|
then it matches anything. If no pattern argument matches string and
|
|
no default is given, then the <a href="#_switch"><strong><tt>switch</tt></strong></a> command returns an empty string.
|
|
If the initial arguments to switch start with - then they are treated
|
|
as options. The following options are currently supported:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>-exact</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use exact matching when comparing string to a
|
|
pattern. This is the default.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-glob</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
When matching string to the patterns, use glob-style
|
|
matching (i.e. the same as implemented by the string
|
|
match command).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-regexp</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
When matching string to the patterns, use regular
|
|
expression matching (i.e. the same as implemented
|
|
by the regexp command).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-command <em>commandname</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
When matching string to the patterns, use the given command, which
|
|
must be a single word. The command is invoked as
|
|
<em>commandname pattern string</em>, or <em>commandname -nocase pattern string</em>
|
|
and must return 1 if matched, or 0 if not.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>--</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of options. The argument following
|
|
this one will be treated as string even if it starts
|
|
with a <tt>-</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>Two syntaxes are provided for the pattern and body arguments. The
|
|
first uses a separate argument for each of the patterns and commands;
|
|
this form is convenient if substitutions are desired on some of the
|
|
patterns or commands. The second form places all of the patterns
|
|
and commands together into a single argument; the argument must
|
|
have proper list structure, with the elements of the list being the
|
|
patterns and commands. The second form makes it easy to construct
|
|
multi-line <a href="#_switch"><strong><tt>switch</tt></strong></a> commands, since the braces around the whole list
|
|
make it unnecessary to include a backslash at the end of each line.
|
|
Since the pattern arguments are in braces in the second form, no
|
|
command or variable substitutions are performed on them; this makes
|
|
the behaviour of the second form different than the first form in
|
|
some cases.</p></div>
|
|
<div class="paragraph"><p>If a body is specified as <tt>-</tt> it means that the body for the next
|
|
pattern should also be used as the body for this pattern (if the
|
|
next pattern also has a body of <tt>-</tt> then the body after that is
|
|
used, and so on). This feature makes it possible to share a single
|
|
body among several patterns.</p></div>
|
|
<div class="paragraph"><p>Below are some examples of <a href="#_switch"><strong><tt>switch</tt></strong></a> commands:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>switch abc a - b {format 1} abc {format 2} default {format 3}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return 2,</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>switch -regexp aaab {
|
|
^a.*b$ -
|
|
b {format 1}
|
|
a* {format 2}
|
|
default {format 3}
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return 1, and</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>switch xyz {
|
|
a -
|
|
b {format 1}
|
|
a* {format 2}
|
|
default {format 3}
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return 3.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tailcall">tailcall</h3>
|
|
<div class="paragraph"><p><tt><strong>tailcall</strong> <em>cmd ?arg...?</em></tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_tailcall"><strong><tt>tailcall</tt></strong></a> command provides an optimised way of invoking a command whilst replacing
|
|
the current call frame. This is similar to <em>exec</em> in Bourne Shell.</p></div>
|
|
<div class="paragraph"><p>The following are identical except the first immediately replaces the current call frame.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>tailcall a b c</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>return [uplevel 1 [list a b c]]</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_tailcall"><strong><tt>tailcall</tt></strong></a> is useful as a dispatch mechanism:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>proc a {cmd args} {
|
|
tailcall sub_$cmd {*}$args
|
|
}
|
|
proc sub_cmd1 ...
|
|
proc sub_cmd2 ...</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tell">tell</h3>
|
|
<div class="paragraph"><p><tt><strong>tell</strong> <em>fileId</em></tt></p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em> <strong>tell</strong></tt></p></div>
|
|
<div class="paragraph"><p>Returns a decimal string giving the current access position in
|
|
<tt><em>fileId</em></tt>.</p></div>
|
|
<div class="paragraph"><p><tt><em>fileId</em></tt> must have been the return value from a previous call to
|
|
<a href="#_open"><strong><tt>open</tt></strong></a>, or it may be <tt>stdin</tt>, <tt>stdout</tt>, or <tt>stderr</tt> to refer to one
|
|
of the standard I/O channels.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_throw">throw</h3>
|
|
<div class="paragraph"><p><tt><strong>throw</strong> <em>code ?msg?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command throws an exception (return) code along with an optional message.
|
|
This command is mostly for convenient usage with <a href="#_try"><strong><tt>try</tt></strong></a>.</p></div>
|
|
<div class="paragraph"><p>The command <tt>throw break</tt> is equivalent to <tt>break</tt>.
|
|
The command <tt>throw 20 message</tt> can be caught with an <tt>on 20 ...</tt> clause to <a href="#_try"><strong><tt>try</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_time">time</h3>
|
|
<div class="paragraph"><p><tt><strong>time</strong> <em>command ?count?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command will call the Tcl interpreter <tt><em>count</em></tt>
|
|
times to execute <tt><em>command</em></tt> (or once if <tt><em>count</em></tt> isn’t
|
|
specified). It will then return a string of the form</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>503 microseconds per iteration</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>which indicates the average amount of time required per iteration,
|
|
in microseconds.</p></div>
|
|
<div class="paragraph"><p>Time is measured in elapsed time, not CPU time.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_try">try</h3>
|
|
<div class="paragraph"><p><tt><strong>try</strong> <em>?catchopts? tryscript</em> ?<strong>on</strong> <em>returncodes {?resultvar? ?optsvar?} handlerscript ...</em>? ?<strong>finally</strong> <em>finalscript</em>?</tt></p></div>
|
|
<div class="paragraph"><p>The <a href="#_try"><strong><tt>try</tt></strong></a> command is provided as a convenience for exception handling.</p></div>
|
|
<div class="paragraph"><p>This interpeter first evaluates <tt><em>tryscript</em></tt> under the effect of the catch
|
|
options <tt><em>catchopts</em></tt> (e.g. <tt>-signal -noexit --</tt>, see <a href="#_catch"><strong><tt>catch</tt></strong></a>).</p></div>
|
|
<div class="paragraph"><p>It then evaluates the script for the first matching <em>on</em> handler
|
|
(there many be zero or more) based on the return code from the <a href="#_try"><strong><tt>try</tt></strong></a>
|
|
section. For example a normal <tt>JIM_ERR</tt> error will be matched by
|
|
an <em>on error</em> handler.</p></div>
|
|
<div class="paragraph"><p>Finally, any <tt><em>finalscript</em></tt> is evaluated.</p></div>
|
|
<div class="paragraph"><p>The result of this command is the result of <tt><em>tryscript</em></tt>, except in the
|
|
case where an exception occurs in a matching <em>on</em> handler script or the <em>finally</em> script,
|
|
in which case the result is this new exception.</p></div>
|
|
<div class="paragraph"><p>The specified <tt><em>returncodes</em></tt> is a list of return codes either as names (<em>ok</em>, <em>error</em>, <em>break</em>, etc.)
|
|
or as integers.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>resultvar</em></tt> and <tt><em>optsvar</em></tt> are specified, they are set as for <a href="#_catch"><strong><tt>catch</tt></strong></a> before evaluating
|
|
the matching handler.</p></div>
|
|
<div class="paragraph"><p>For example:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set f [open input]
|
|
try -signal {
|
|
process $f
|
|
} on {continue break} {} {
|
|
error "Unexpected break/continue"
|
|
} on error {msg opts} {
|
|
puts "Dealing with error"
|
|
return {*}$opts $msg
|
|
} on signal sig {
|
|
puts "Got signal: $sig"
|
|
} finally {
|
|
$f close
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If break, continue or error are raised, they are dealt with by the matching
|
|
handler.</p></div>
|
|
<div class="paragraph"><p>In any case, the file will be closed via the <em>finally</em> clause.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_throw"><strong><tt>throw</tt></strong></a>, <a href="#_catch"><strong><tt>catch</tt></strong></a>, <a href="#_return"><strong><tt>return</tt></strong></a>, <a href="#_error"><strong><tt>error</tt></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_unknown">unknown</h3>
|
|
<div class="paragraph"><p><tt><strong>unknown</strong> <em>cmdName ?arg arg …?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command doesn’t actually exist as part of Tcl, but Tcl will
|
|
invoke it if it does exist.</p></div>
|
|
<div class="paragraph"><p>If the Tcl interpreter encounters a command name for which there
|
|
is not a defined command, then Tcl checks for the existence of
|
|
a command named <a href="#_unknown"><strong><tt>unknown</tt></strong></a>.</p></div>
|
|
<div class="paragraph"><p>If there is no such command, then the interpreter returns an
|
|
error.</p></div>
|
|
<div class="paragraph"><p>If the <a href="#_unknown"><strong><tt>unknown</tt></strong></a> command exists, then it is invoked with
|
|
arguments consisting of the fully-substituted name and arguments
|
|
for the original non-existent command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_unknown"><strong><tt>unknown</tt></strong></a> command typically does things like searching
|
|
through library directories for a command procedure with the name
|
|
<tt><em>cmdName</em></tt>, or expanding abbreviated command names to full-length,
|
|
or automatically executing unknown commands as UNIX sub-processes.</p></div>
|
|
<div class="paragraph"><p>In some cases (such as expanding abbreviations) <a href="#_unknown"><strong><tt>unknown</tt></strong></a> will
|
|
change the original command slightly and then (re-)execute it.
|
|
The result of the <a href="#_unknown"><strong><tt>unknown</tt></strong></a> command is used as the result for
|
|
the original non-existent command.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_unset">unset</h3>
|
|
<div class="paragraph"><p><tt><strong>unset ?-nocomplain? ?--?</strong> <em>?name name …?</em></tt></p></div>
|
|
<div class="paragraph"><p>Remove variables.
|
|
Each <tt><em>name</em></tt> is a variable name, specified in any of the
|
|
ways acceptable to the <a href="#_set"><strong><tt>set</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If a <tt><em>name</em></tt> refers to an element of an array, then that
|
|
element is removed without affecting the rest of the array.</p></div>
|
|
<div class="paragraph"><p>If a <tt><em>name</em></tt> consists of an array name with no parenthesized
|
|
index, then the entire array is deleted.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_unset"><strong><tt>unset</tt></strong></a> command returns an empty string as result.</p></div>
|
|
<div class="paragraph"><p>An error occurs if any of the variables doesn’t exist, unless <em>-nocomplain</em>
|
|
is specified. The <em>--</em> argument may be specified to stop option processing
|
|
in case the variable name may be <em>-nocomplain</em>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_upcall">upcall</h3>
|
|
<div class="paragraph"><p><tt><strong>upcall</strong> <em>command ?args …?</em></tt></p></div>
|
|
<div class="paragraph"><p>May be used from within a proc defined as <a href="#_local"><strong><tt>local</tt></strong></a> <a href="#_proc"><strong><tt>proc</tt></strong></a> in order to call
|
|
the previous, hidden version of the same command.</p></div>
|
|
<div class="paragraph"><p>If there is no previous definition of the command, an error is returned.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_uplevel">uplevel</h3>
|
|
<div class="paragraph"><p><tt><strong>uplevel</strong> <em>?level? command ?command …?</em></tt></p></div>
|
|
<div class="paragraph"><p>All of the <tt><em>command</em></tt> arguments are concatenated as if they had
|
|
been passed to <a href="#_concat"><strong><tt>concat</tt></strong></a>; the result is then evaluated in the
|
|
variable context indicated by <tt><em>level</em></tt>. <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> returns
|
|
the result of that evaluation. If <tt><em>level</em></tt> is an integer, then
|
|
it gives a distance (up the procedure calling stack) to move before
|
|
executing the command. If <tt><em>level</em></tt> consists of <tt>#</tt> followed by
|
|
a number then the number gives an absolute level number. If <tt><em>level</em></tt>
|
|
is omitted then it defaults to <tt>1</tt>. <tt><em>level</em></tt> cannot be
|
|
defaulted if the first <tt><em>command</em></tt> argument starts with a digit or <tt>#</tt>.</p></div>
|
|
<div class="paragraph"><p>For example, suppose that procedure <em>a</em> was invoked
|
|
from top-level, and that it called <em>b</em>, and that <em>b</em> called <em>c</em>.
|
|
Suppose that <em>c</em> invokes the <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> command. If <tt><em>level</em></tt>
|
|
is <tt>1</tt> or <tt>#2</tt> or omitted, then the command will be executed
|
|
in the variable context of <em>b</em>. If <tt><em>level</em></tt> is <tt>2</tt> or <tt>#1</tt>
|
|
then the command will be executed in the variable context of <em>a</em>.</p></div>
|
|
<div class="paragraph"><p>If <tt><em>level</em></tt> is <em>3</em> or <tt>#0</tt> then the command will be executed
|
|
at top-level (only global variables will be visible).
|
|
The <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> command causes the invoking procedure to disappear
|
|
from the procedure calling stack while the command is being executed.
|
|
In the above example, suppose <em>c</em> invokes the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>uplevel 1 {set x 43; d}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>where <em>d</em> is another Tcl procedure. The <a href="#_set"><strong><tt>set</tt></strong></a> command will
|
|
modify the variable <em>x</em> in <em>b’s context, and 'd</em> will execute
|
|
at level 3, as if called from <em>b</em>. If it in turn executes
|
|
the command</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>uplevel {set x 42}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>then the <a href="#_set"><strong><tt>set</tt></strong></a> command will modify the same variable <em>x</em> in <em>b’s
|
|
context: the procedure 'c</em> does not appear to be on the call stack
|
|
when <em>d</em> is executing. The command <a href="#_info"><strong><tt>info</tt></strong></a> <tt>level</tt> may
|
|
be used to obtain the level of the current procedure.</p></div>
|
|
<div class="paragraph"><p><a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> makes it possible to implement new control
|
|
constructs as Tcl procedures (for example, <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a> could
|
|
be used to implement the <a href="#_while"><strong><tt>while</tt></strong></a> construct as a Tcl procedure).</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_upvar">upvar</h3>
|
|
<div class="paragraph"><p><tt><strong>upvar</strong> <em>?level? otherVar myVar ?otherVar myVar …?</em></tt></p></div>
|
|
<div class="paragraph"><p>This command arranges for one or more local variables in the current
|
|
procedure to refer to variables in an enclosing procedure call or
|
|
to global variables.</p></div>
|
|
<div class="paragraph"><p><tt><em>level</em></tt> may have any of the forms permitted for the <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a>
|
|
command, and may be omitted if the first letter of the first <tt><em>otherVar</em></tt>
|
|
isn’t <tt>#</tt> or a digit (it defaults to <em>1</em>).</p></div>
|
|
<div class="paragraph"><p>For each <tt><em>otherVar</em></tt> argument, <a href="#_upvar"><strong><tt>upvar</tt></strong></a> makes the variable
|
|
by that name in the procedure frame given by <tt><em>level</em></tt> (or at
|
|
global level, if <tt><em>level</em></tt> is <tt>#0</tt>) accessible
|
|
in the current procedure by the name given in the corresponding
|
|
<tt><em>myVar</em></tt> argument.</p></div>
|
|
<div class="paragraph"><p>The variable named by <tt><em>otherVar</em></tt> need not exist at the time of the
|
|
call; it will be created the first time <tt><em>myVar</em></tt> is referenced, just like
|
|
an ordinary variable.</p></div>
|
|
<div class="paragraph"><p><a href="#_upvar"><strong><tt>upvar</tt></strong></a> may only be invoked from within procedures.</p></div>
|
|
<div class="paragraph"><p><a href="#_upvar"><strong><tt>upvar</tt></strong></a> returns an empty string.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_upvar"><strong><tt>upvar</tt></strong></a> command simplifies the implementation of call-by-name
|
|
procedure calling and also makes it easier to build new control constructs
|
|
as Tcl procedures.
|
|
For example, consider the following procedure:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>proc add2 name {
|
|
upvar $name x
|
|
set x [expr $x+2]
|
|
}</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><em>add2</em> is invoked with an argument giving the name of a variable,
|
|
and it adds two to the value of that variable.
|
|
Although <em>add2</em> could have been implemented using <a href="#_uplevel"><strong><tt>uplevel</tt></strong></a>
|
|
instead of <a href="#_upvar"><strong><tt>upvar</tt></strong></a>, <a href="#_upvar"><strong><tt>upvar</tt></strong></a> makes it simpler for <em>add2</em>
|
|
to access the variable in the caller’s procedure frame.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_while">while</h3>
|
|
<div class="paragraph"><p><tt><strong>while</strong> <em>test body</em></tt></p></div>
|
|
<div class="paragraph"><p>The <tt><em>while</em></tt> command evaluates <tt><em>test</em></tt> as an expression
|
|
(in the same way that <a href="#_expr"><strong><tt>expr</tt></strong></a> evaluates its argument).
|
|
The value of the expression must be numeric; if it is non-zero
|
|
then <tt><em>body</em></tt> is executed by passing it to the Tcl interpreter.</p></div>
|
|
<div class="paragraph"><p>Once <tt><em>body</em></tt> has been executed then <tt><em>test</em></tt> is evaluated
|
|
again, and the process repeats until eventually <tt><em>test</em></tt>
|
|
evaluates to a zero numeric value. <a href="#_continue"><strong><tt>continue</tt></strong></a>
|
|
commands may be executed inside <tt><em>body</em></tt> to terminate the current
|
|
iteration of the loop, and <a href="#_break"><strong><tt>break</tt></strong></a>
|
|
commands may be executed inside <tt><em>body</em></tt> to cause immediate
|
|
termination of the <a href="#_while"><strong><tt>while</tt></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_while"><strong><tt>while</tt></strong></a> command always returns an empty string.</p></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_optional_extensions">OPTIONAL-EXTENSIONS</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The following extensions may or may not be available depending upon
|
|
what options were selected when Jim Tcl was built.</p></div>
|
|
<div class="sect2">
|
|
<h3 id="cmd_1">posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>os.fork</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invokes <em>fork(2)</em> and returns the result.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>os.wait -nohang</strong> <em>pid</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invokes waitpid(2), with WNOHANG if <tt>-nohang</tt> is specified.
|
|
Returns a list of 3 elements.
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>{0 none 0} if -nohang is specified, and the process is still alive.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>{-1 error <error-description>} if the process does not exist or has already been waited for.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>{<pid> exit <exit-status>} if the process exited normally.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>{<pid> signal <signal-number>} if the process terminated on a signal.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>{<pid> other 0} otherwise (core dump, stopped, continued, etc.)</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>os.gethostname</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invokes <em>gethostname(3)</em> and returns the result.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>os.getids</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the various user/group ids for the current process.
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>jim> os.getids
|
|
uid 1000 euid 1000 gid 100 egid 100</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>os.uptime</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the number of seconds since system boot. See description of <em>uptime</em> in <em>sysinfo(2)</em>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_ansi_i_o_aio_and_eventloop_api">ANSI I/O (aio) and EVENTLOOP API</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>Jim provides an alternative object-based API for I/O.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_open"><strong><tt>open</tt></strong></a> and <a href="#_socket"><strong><tt>socket</tt></strong></a> for commands which return an I/O handle.</p></div>
|
|
<div class="sect2">
|
|
<h3 id="_aio">aio</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>read ?-nonewline?</strong> <em>?len?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Read and return bytes from the stream. To eof if no len.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>gets</strong> <em>?var?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Read one line and return it or store it in the var
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>puts ?-nonewline?</strong> <em>str</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Write the string, with newline unless -nonewline
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>copyto</strong> <em>tofd ?size?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Copy bytes to the file descriptor <tt><em>tofd</em></tt>. If <tt><em>size</em></tt> is specified, at most
|
|
that many bytes will be copied. Otherwise copying continues until the end
|
|
of the input file. Returns the number of bytes actually copied.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>flush</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Flush the stream
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>filename</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the original filename associated with the handle.
|
|
Handles returned by <a href="#_socket"><strong><tt>socket</tt></strong></a> give the socket type instead of a filename.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>eof</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if stream is at eof
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>close</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Closes the stream
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>seek</strong> <em>offset</em> <strong>?start|current|end?</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Seeks in the stream (default <em>current</em>)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>tell</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current seek position
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>filename</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the original filename used when opening the file.
|
|
If the handle was returned from <a href="#_socket"><strong><tt>socket</tt></strong></a>, the type of the
|
|
handle is returned instead.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>ndelay ?0|1?</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Set O_NDELAY (if arg). Returns current/new setting.
|
|
Note that in general ANSI I/O interacts badly with non-blocking I/O.
|
|
Use with care.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>buffering none|line|full</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets the buffering mode of the stream.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>accept</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Server socket only: Accept a connection and return stream
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>sendto</strong> <em>str ?hostname:?port</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sends the string, <tt><em>str</em></tt>, to the given address via the socket using sendto(2).
|
|
This is intended for udp sockets and may give an error or behave in unintended
|
|
ways for other handle types.
|
|
Returns the number of bytes written.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>recvfrom</strong> <em>maxlen ?addrvar?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Receives a message from the handle via recvfrom(2) and returns it.
|
|
At most <tt><em>maxlen</em></tt> bytes are read.
|
|
If <tt><em>addrvar</em></tt> is specified, the sending address of the message is stored in
|
|
the named variable in the form <em>addr:port</em>. See <a href="#_socket"><strong><tt>socket</tt></strong></a> for details.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_fconfigure">fconfigure</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>fconfigure</strong> <em>handle</em> <strong>?-blocking 0|1? ?-buffering noneline|full? ?-translation</strong> <em>mode</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
For compatibility with Tcl, a limited form of the <a href="#_fconfigure"><strong><tt>fconfigure</tt></strong></a>
|
|
command is supported.
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><tt>fconfigure</tt></strong></a> <tt>... -blocking</tt> maps to <a href="#_aio"><strong><tt>aio</tt></strong></a> <tt>ndelay</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><tt>fconfigure</tt></strong></a> <tt>... -buffering</tt> maps to <a href="#_aio"><strong><tt>aio</tt></strong></a> <tt>buffering</tt>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><tt>fconfigure</tt></strong></a> <tt>... -translation</tt> is accepted but ignored
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="cmd_2">eventloop: after, vwait, update</h3>
|
|
<div class="paragraph"><p>The following commands allow a script to be invoked when the given condition occurs.
|
|
If no script is given, returns the current script. If the given script is the empty, the
|
|
handler is removed.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>readable</strong> <em>?readable-script?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when the socket is readable.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>writable</strong> <em>?writable-script?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when the socket is writable.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$handle <strong>onexception</strong> <em>?exception-script?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when when oob data received.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>For compatibility with <em>Tcl</em>, these may be prefixed with <tt>fileevent</tt>. e.g.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<tt>fileevent $handle <strong>readable</strong> <em>...</em></tt>
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>Time-based execution is also available via the eventloop API.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>after</strong> <em>ms</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sleeps for the given number of milliseconds. No events are
|
|
processed during this time.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>after</strong> <em>ms</em>|<strong>idle</strong> script ?script ...?'</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The scripts are concatenated and executed after the given
|
|
number of milliseconds have elapsed. If <em>idle</em> is specified,
|
|
the script will run the next time the event loop is processed
|
|
with <a href="#cmd_2"><strong><tt>vwait</tt></strong></a> or <a href="#cmd_2"><strong><tt>update</tt></strong></a>. The script is only run once and
|
|
then removed. Returns an event id.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>after cancel</strong> <em>id|command</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Cancels an <a href="#cmd_2"><strong><tt>after</tt></strong></a> event with the given event id or matching
|
|
command (script). Returns the number of milliseconds
|
|
remaining until the event would have fired. Returns the
|
|
empty string if no matching event is found.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>after info</strong> <em>?id?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>id</em></tt> is not given, returns a list of current <a href="#cmd_2"><strong><tt>after</tt></strong></a>
|
|
events. If <tt><em>id</em></tt> is given, returns a list containing the
|
|
associated script and either <em>timer</em> or <em>idle</em> to indicated
|
|
the type of the event. An error occurs if <tt><em>id</em></tt> does not
|
|
match an event.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>vwait</strong> <em>variable</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A call to <a href="#cmd_2"><strong><tt>vwait</tt></strong></a> is enters the eventloop. <a href="#cmd_2"><strong><tt>vwait</tt></strong></a> processes
|
|
events until the named (global) variable changes or all
|
|
event handlers are removed. The variable need not exist
|
|
beforehand. If there are no event handlers defined, <a href="#cmd_2"><strong><tt>vwait</tt></strong></a>
|
|
returns immediately.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>update ?idletasks?</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A call to <a href="#cmd_2"><strong><tt>update</tt></strong></a> enters the eventloop to process expired events, but
|
|
no new events. If <em>idletasks</em> is specified, only expired time events are handled,
|
|
not file events.
|
|
Returns once handlers have been run for all expired events.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>Scripts are executed at the global scope. If an error occurs during a handler script,
|
|
an attempt is made to call (the user-defined command) <tt>bgerror</tt> with the details of the error.
|
|
If the <tt>bgerror</tt> commands does not exist, it is printed to stderr instead.</p></div>
|
|
<div class="paragraph"><p>If a file event handler script generates an error, the handler is automatically removed
|
|
to prevent infinite errors. (A time event handler is always removed after execution).</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>bgerror</strong> <em>error</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Called when an event handler script generates an error.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_socket">socket</h3>
|
|
<div class="paragraph"><p>Various socket types may be created.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket unix</strong> <em>path</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket client.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket unix.server</strong> <em>path</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket server.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket ?-ipv6? stream</strong> <em>addr:port</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A TCP socket client.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket ?-ipv6? stream.server</strong> <em>?addr:?port</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A TCP socket server (<tt><em>addr</em></tt> defaults to <tt>0.0.0.0</tt> for IPv4 or <tt>[::]</tt> for IPv6).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket ?-ipv6? dgram</strong> ?<em>addr:port</em>?</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A UDP socket client. If the address is not specified,
|
|
the client socket will be unbound and <em>sendto</em> must be used
|
|
to indicated the destination.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket ?-ipv6? dgram.server</strong> <em>addr:port</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A UDP socket server.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>socket pipe</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A pipe. Note that unlike all other socket types, this command returns
|
|
a list of two channels: {read write}
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>This command creates a socket connected (client) or bound (server) to the given
|
|
address.</p></div>
|
|
<div class="paragraph"><p>The returned value is channel and may generally be used with the various file I/O
|
|
commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set f [socket stream www.google.com:80]
|
|
aio.sockstream1
|
|
$f puts -nonewline "GET / HTTP/1.0\r\n\r\n"
|
|
$f gets
|
|
HTTP/1.0 302 Found
|
|
$f close</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Server sockets, however support only <em>accept</em>, which is most useful in conjunction with
|
|
the EVENTLOOP API.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>set f [socket stream.server 80]
|
|
$f readable {
|
|
set client [$f accept]
|
|
$client gets $buf
|
|
...
|
|
$client puts -nonewline "HTTP/1.1 404 Not found\r\n"
|
|
$client close
|
|
}
|
|
vwait done</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The address, <tt><em>addr</em></tt>, can be given in one of the following forms:</p></div>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
For IPv4 socket types, an IPv4 address such as 192.168.1.1
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
For IPv6 socket types, an IPv6 address such as [fe80::1234] or [::]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
A hostname
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
<div class="paragraph"><p>Note that on many systems, listening on an IPv6 address such as [::] will
|
|
also accept requests via IPv4.</p></div>
|
|
<div class="paragraph"><p>Where a hostname is specified, the <tt><em>first</em></tt> returned address is used
|
|
which matches the socket type is used.</p></div>
|
|
<div class="paragraph"><p>The special type <em>pipe</em> isn’t really a socket.</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>lassign [socket pipe] r w</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt># Must close $w after exec
|
|
exec ps >@$w &
|
|
$w close</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>$r readable ...</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_syslog">syslog</h3>
|
|
<div class="paragraph"><p><tt><strong>syslog</strong> <em>?options? ?priority? message</em></tt></p></div>
|
|
<div class="paragraph"><p>This command sends message to system syslog facility with given
|
|
priority. Valid priorities are:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>emerg, alert, crit, err, error, warning, notice, info, debug</tt></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If a message is specified, but no priority is specified, then a
|
|
priority of info is used.</p></div>
|
|
<div class="paragraph"><p>By default, facility user is used and the value of global tcl variable
|
|
argv0 is used as ident string. However, any of the following options
|
|
may be specified before priority to control these parameters:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-facility</strong> <em>value</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use specified facility instead of user. The following
|
|
values for facility are recognized:
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
|
|
uucp, local0-local7</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-ident</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use given string instead of argv0 variable for ident string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>-options</strong> <em>integer</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Set syslog options such as <tt>LOG_CONS</tt>, <tt>LOG_NDELAY</tt>. You should
|
|
use numeric values of those from your system syslog.h file,
|
|
because I haven’t got time to implement yet another hash
|
|
table.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="cmd_3">pack: pack, unpack</h3>
|
|
<div class="paragraph"><p>The optional <em>pack</em> extension provides commands to encode and decode binary strings.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>pack</strong> <em>varName value</em> <strong>-intle|-intbe|-str</strong> <em>bitwidth ?bitoffset?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Packs the binary representation of <tt><em>value</em></tt> into the variable
|
|
<tt><em>varName</em></tt>. The value is packed according to the given type
|
|
(integer/string, big-endian/little-endian), width and bit offset.
|
|
The variable is created if necessary (like <a href="#_append"><strong><tt>append</tt></strong></a>).
|
|
Ihe variable is expanded if necessary.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>unpack</strong> <em>binvalue</em> <strong>-intbe|-intle|-uintbe|-uintle|-str</strong> <em>bitpos bitwidth</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unpacks bits from <tt><em>binvalue</em></tt> at bit position <tt><em>bitpos</em></tt> and with <tt><em>bitwidth</em></tt>.
|
|
Interprets the value according to the type (integer/string, big-endian/little-endian
|
|
and signed/unsigned) and returns it. For integer types, <tt><em>bitwidth</em></tt>
|
|
may be up to the size of a Jim Tcl integer (typically 64 bits). For the string type,
|
|
both the width and the offset must be on a byte boundary (multiple of 8). Attempting to
|
|
access outside the length of the value will return 0 for integer types or the empty string
|
|
for the string type.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_binary">binary</h3>
|
|
<div class="paragraph"><p>The optional, pure-Tcl <em>binary</em> extension provides the Tcl-compatible <a href="#_binary"><strong><tt>binary</tt></strong></a> <tt>scan</tt> and <a href="#_binary"><strong><tt>binary</tt></strong></a> <tt>format</tt>
|
|
commands based on the low-level <a href="#cmd_3"><strong><tt>pack</tt></strong></a> and <a href="#cmd_3"><strong><tt>unpack</tt></strong></a> commands.</p></div>
|
|
<div class="paragraph"><p>See the Tcl documentation at: <a href="http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm">http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm</a></p></div>
|
|
<div class="paragraph"><p>Note that packing and unpacking of floating point values is not supported.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="cmd_4">oo: class, super</h3>
|
|
<div class="paragraph"><p>The optional, pure-Tcl <em>oo</em> extension provides object-oriented (OO) support for Jim Tcl.</p></div>
|
|
<div class="paragraph"><p>See the online documentation (<a href="http://jim.berlios.de/documentation/oo/">http://jim.berlios.de/documentation/oo/</a>) for more details.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>class</strong> <em>classname ?baseclasses? classvars</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Create a new class, <tt><em>classname</em></tt>, with the given dictionary
|
|
(<tt><em>classvars</em></tt>) as class variables. These are the initial variables
|
|
which all newly created objects of this class are initialised with.
|
|
If a list of baseclasses is given, methods and instance variables
|
|
are inherited.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>super</strong> <em>method ?args ...?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
From within a method, invokes the given method on the base class.
|
|
Note that this will only call the last baseclass given.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tree">tree</h3>
|
|
<div class="paragraph"><p>The optional, pure-Tcl <em>tree</em> extension implements an OO, general purpose tree structure
|
|
similar to that provided by tcllib ::struct::tree (<a href="http://tcllib.sourceforge.net/doc/struct_tree.html">http://tcllib.sourceforge.net/doc/struct_tree.html</a>)</p></div>
|
|
<div class="paragraph"><p>A tree is a collection of nodes, where each node (except the root node) has a single parent
|
|
and zero or more child nodes (ordered), as well as zero or more attribute/value pairs.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tree</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates and returns a new tree object with a single node named "root".
|
|
All operations on the tree are invoked through this object.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>destroy</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Destroy the tree and all it’s nodes. (Note that the the tree will also
|
|
be automatically garbage collected once it goes out of scope).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>set</strong> <em>nodename key value</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Set the value for the given attribute key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>lappend</strong> <em>nodename key value ...</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Append to the (list) value(s) for the given attribute key, or set if not yet set.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>keyexists</strong> <em>nodename key</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if the given attribute key exists.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>get</strong> <em>nodename key</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the value associated with the given attribute key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>getall</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the entire attribute dictionary associated with the given key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>depth</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the depth of the given node. The depth of "root" is 0.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>parent</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the node name of the parent node, or "" for the root node.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>numchildren</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the number of child nodes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>children</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of the child nodes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>next</strong> <em>nodename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the next sibling node, or "" if none.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>insert</strong> <em>nodename ?index?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Add a new child node to the given node. The index is a list index
|
|
such as <tt>3</tt> or <tt>end-2</tt>. The default index is <tt>end</tt>.
|
|
Returns the name of the newly added node.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>walk</strong> <em>nodename</em> <strong>dfs|bfs</strong> {<em>actionvar nodevar</em>} <em>script</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Walks the tree starting from the given node, either breadth first (<tt>bfs</tt>)
|
|
depth first (<tt>dfs</tt>).
|
|
The value <tt>"enter"</tt> or <tt>"exit"</tt> is stored in variable <tt><em>actionvar</em></tt>.
|
|
The name of each node is stored in <tt><em>nodevar</em></tt>.
|
|
The script is evaluated twice for each node, on entry and exit.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>$tree <strong>dump</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Dumps the tree contents to stdout
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tcl_prefix">tcl::prefix</h3>
|
|
<div class="paragraph"><p>The optional tclprefix extension provides the Tcl8.6-compatible <em>tcl::prefix</em> command
|
|
(<a href="http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm">http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm</a>) for matching strings against a table
|
|
of possible values (typically commands or options).</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tcl::prefix all</strong> <em>table string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all elements in <tt><em>table</em></tt> that begin with the prefix <tt><em>string</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tcl::prefix longest</strong> <em>table string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the longest common prefix of all elements in <tt><em>table</em></tt> that begin with the prefix <tt><em>string</em></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tcl::prefix match</strong> <em>?options? table string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <tt><em>string</em></tt> equals one element in <tt><em>table</em></tt> or is a prefix to
|
|
exactly one element, the matched element is returned. If not, the
|
|
result depends on the <tt>-error</tt> option.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-exact</tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Accept only exact matches.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-message <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use <tt><em>string</em></tt> in the error message at a mismatch. Default is "option".
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt>-error <em>options</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The options are used when no match is found. If <tt><em>options</em></tt> is
|
|
empty, no error is generated and an empty string is returned.
|
|
Otherwise the options are used as return options when
|
|
generating the error message. The default corresponds to
|
|
setting <tt>-level 0</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_history">history</h3>
|
|
<div class="paragraph"><p>The optional history extension provides script access to the command line editing
|
|
and history support available in <em>jimsh</em>. See <em>examples/jtclsh.tcl</em> for an example.
|
|
Note: if line editing support is not available, <a href="#_history"><strong><tt>history</tt></strong></a> <tt>getline</tt> acts like <a href="#_gets"><strong><tt>gets</tt></strong></a> and
|
|
the remaining subcommands do nothing.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>history load</strong> <em>filename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Load history from a (text) file. If the file does not exist or is not readable,
|
|
it is ignored.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>history getline</strong> <em>prompt ?varname?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Displays the given prompt and allows a line to be entered. Similarly to <a href="#_gets"><strong><tt>gets</tt></strong></a>,
|
|
if <tt><em>varname</em></tt> is given, it receives the line and the length of the line is returned,
|
|
or -1 on EOF. If <tt><em>varname</em></tt> is not given, the line is returned directly.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>history add</strong> <em>line</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Adds the given line to the history buffer.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>history save</strong> <em>filename</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Saves the current history buffer to the given file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>history show</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Displays the current history buffer to standard output.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_namespace">namespace</h3>
|
|
<div class="paragraph"><p>Provides namespace-related functions. See also: <a href="http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm">http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm</a></p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace code</strong> <em>script</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Captures the current namespace context for later execution of
|
|
the script <tt><em>script</em></tt>. It returns a new script in which script has
|
|
been wrapped in a <tt><strong>namespace inscope</strong></tt> command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace current</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name for the current namespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace delete</strong> <em>?namespace …?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Deletes all commands and variables with the given namespace prefixes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace eval</strong> <em>namespace arg ?arg…?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Activates a namespace called <tt><em>namespace</em></tt> and evaluates some code in that context.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace origin</strong> <em>command</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name of the original command to which the imported command <tt><em>command</em></tt> refers.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
+<strong>namespace parent</strong> ?namespace?
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name of the parent namespace for namespace <tt><em>namespace</em></tt>, if given, otherwise
|
|
for the current namespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace qualifiers</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns any leading namespace qualifiers for <tt><em>string</em></tt>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace tail</strong> <em>string</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the simple name at the end of a qualified string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace upvar</strong> <em>namespace ?arg…?</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This command arranges for zero or more local variables in the current procedure to refer to variables in <tt><em>namespace</em></tt>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>namespace which</strong> <em>?-command|-variable? name</em></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Looks up <tt><em>name</em></tt> as either a command (the default) or variable and returns its fully-qualified name.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="BuiltinVariables">BUILT-IN VARIABLES</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The following global variables are created automatically
|
|
by the Tcl library.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>env</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable is set by Jim as an array
|
|
whose elements are the environment variables for the process.
|
|
Reading an element will return the value of the corresponding
|
|
environment variable.
|
|
This array is initialised at startup from the <a href="#_env"><strong><tt>env</tt></strong></a> command.
|
|
It may be modified and will affect the environment passed to
|
|
commands invoked with <a href="#_exec"><strong><tt>exec</tt></strong></a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>platform_tcl</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable is set by Jim as an array containing information
|
|
about the platform on which Jim was built. Currently this includes
|
|
<em>os</em> and <em>platform</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>auto_path</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable contains a list of paths to search for packages.
|
|
It defaults to a location based on where jim is installed
|
|
(e.g. <tt>/usr/local/lib/jim</tt>), but may be changed by <tt>jimsh</tt>
|
|
or the embedding application. Note that <tt>jimsh</tt> will consider
|
|
the environment variable <tt>$JIMLIB</tt> to be a list of colon-separated
|
|
list of paths to add to <tt><strong>auto_path</strong></tt>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>errorCode</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable holds the value of the -errorcode return
|
|
option set by the most recent error that occurred in this
|
|
interpreter. This list value represents additional information
|
|
about the error in a form that is easy to process with
|
|
programs. The first element of the list identifies a general
|
|
class of errors, and determines the format of the rest of
|
|
the list. The following formats for -errorcode return options
|
|
are used by the Tcl core; individual applications may define
|
|
additional formats. Currently only <a href="#_exec"><strong><tt>exec</tt></strong></a> sets this variable.
|
|
Otherwise it will be <tt>NONE</tt>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The following global variables are set by jimsh.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tcl_interactive</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable is set to 1 if jimsh is started in interactive mode
|
|
or 0 otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>tcl_platform</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable is set by Jim as an array containing information
|
|
about the platform upon which Jim was built. The following is an
|
|
example of the contents of this array.
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>tcl_platform(byteOrder) = littleEndian
|
|
tcl_platform(os) = Darwin
|
|
tcl_platform(platform) = unix
|
|
tcl_platform(pointerSize) = 8
|
|
tcl_platform(threaded) = 0
|
|
tcl_platform(wordSize) = 8
|
|
tcl_platform(pathSeparator) = :</tt></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>argv0</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If jimsh is invoked to run a script, this variable contains the name
|
|
of the script.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>argv</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If jimsh is invoked to run a script, this variable contains a list
|
|
of any arguments supplied to the script.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>argc</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If jimsh is invoked to run a script, this variable contains the number
|
|
of arguments supplied to the script.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<tt><strong>jim_argv0</strong></tt>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The value of argv[0] when jimsh was invoked.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_changes_in_previous_releases">CHANGES IN PREVIOUS RELEASES</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_63">In v0.63</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<a href="#_source"><strong><tt>source</tt></strong></a> now checks that a script is complete (.i.e. not missing a brace)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>info complete</em> now uses the real parser and so is 100% accurate
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Better access to live stack frames with <em>info frame</em>, <a href="#_stacktrace"><strong><tt>stacktrace</tt></strong></a> and <a href="#_stackdump"><strong><tt>stackdump</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_tailcall"><strong><tt>tailcall</tt></strong></a> no longer loses stack trace information
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_alias"><strong><tt>alias</tt></strong></a> and <a href="#_curry"><strong><tt>curry</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_lambda"><strong><tt>lambda</tt></strong></a>, <a href="#_alias"><strong><tt>alias</tt></strong></a> and <a href="#_curry"><strong><tt>curry</tt></strong></a> are implemented via <a href="#_tailcall"><strong><tt>tailcall</tt></strong></a> for efficiency
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><tt>local</tt></strong></a> allows procedures to be deleted automatically at the end of the current procedure
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
udp sockets are now supported for both clients and servers.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
vfork-based exec is now working correctly
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>file tempfile</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>socket pipe</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Enhance <em>try … on … finally</em> to be more Tcl 8.6 compatible
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
It is now possible to <a href="#_return"><strong><tt>return</tt></strong></a> from within <a href="#_try"><strong><tt>try</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
IPv6 support is now included
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>string is</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Event handlers works better if an error occurs. eof handler has been removed.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_exec"><strong><tt>exec</tt></strong></a> now sets $::errorCode, and catch sets opts(-errorcode) for exit status
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Command pipelines via open "|…" are now supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_pid"><strong><tt>pid</tt></strong></a> can now return pids of a command pipeline
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>info references</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <em>after <tt>'ms</em></tt><em>, 'after idle</em>, <em>after info</em>, <a href="#cmd_2"><strong><tt>update</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_exec"><strong><tt>exec</tt></strong></a> now sets environment based on $::env
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>dict keys</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <em>lsort -index</em>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_62">In v0.62</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Add support to <a href="#_exec"><strong><tt>exec</tt></strong></a> for <em>>&</em>, <em>>>&</em>, <em>|&</em>, <em>2>@1</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fix <a href="#_exec"><strong><tt>exec</tt></strong></a> error messages when special token (e.g. <em>></em>) is the last token
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fix <a href="#_subst"><strong><tt>subst</tt></strong></a> handling of backslash escapes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow abbreviated options for <a href="#_subst"><strong><tt>subst</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_return"><strong><tt>return</tt></strong></a>, <a href="#_break"><strong><tt>break</tt></strong></a>, <a href="#_continue"><strong><tt>continue</tt></strong></a> in subst
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Many <a href="#_expr"><strong><tt>expr</tt></strong></a> bug fixes
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for functions in <a href="#_expr"><strong><tt>expr</tt></strong></a> (e.g. int(), abs()), and also <em>in</em>, <em>ni</em> list operations
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The variable name argument to <a href="#_regsub"><strong><tt>regsub</tt></strong></a> is now optional
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <em>unset -nocomplain</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for list commands: <a href="#_lassign"><strong><tt>lassign</tt></strong></a>, <a href="#_lrepeat"><strong><tt>lrepeat</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fully-functional <a href="#_lsearch"><strong><tt>lsearch</tt></strong></a> is now implemented
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>info nameofexecutable</em> and <em>info returncodes</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow <a href="#_catch"><strong><tt>catch</tt></strong></a> to determine what return codes are caught
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow <a href="#_incr"><strong><tt>incr</tt></strong></a> to increment an unset variable by first setting to 0
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow <em>args</em> and optional arguments to the left or required arguments in <a href="#_proc"><strong><tt>proc</tt></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>file copy</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>try … finally</em> command
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_licence">LICENCE</h2>
|
|
<div class="sectionbody">
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
|
|
Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
|
|
Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
|
|
Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
|
|
Copyright 2008 Andrew Lunn <andrew@lunn.ch>
|
|
Copyright 2008 Duane Ellis <openocd@duaneellis.com>
|
|
Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
|
|
Copyright 2009 Steve Bennett <steveb@workware.net.au></tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>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.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``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
|
|
JIM TCL PROJECT 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.</tt></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><tt>The views and conclusions contained in the software and documentation
|
|
are those of the authors and should not be interpreted as representing
|
|
official policies, either expressed or implied, of the Jim Tcl Project.</tt></pre>
|
|
</div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footnotes"><hr /></div>
|
|
<div id="footer">
|
|
<div id="footer-text">
|
|
Last updated 2011-12-14 07:33:13 EST
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|