9022 lines
371 KiB
HTML
9022 lines
371 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!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.10" />
|
|
<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; }
|
|
|
|
.monospaced, code, pre {
|
|
font-family: "Courier New", Courier, monospace;
|
|
font-size: inherit;
|
|
color: navy;
|
|
padding: 0;
|
|
margin: 0;
|
|
}
|
|
pre {
|
|
white-space: pre-wrap;
|
|
}
|
|
|
|
#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: #888;
|
|
}
|
|
|
|
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; vertical-align: text-bottom; }
|
|
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.toclevel0, 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; }
|
|
|
|
div.unbreakable { page-break-inside: avoid; }
|
|
|
|
|
|
/*
|
|
* xhtml11 specific
|
|
*
|
|
* */
|
|
|
|
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
|
|
*
|
|
* */
|
|
|
|
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;
|
|
}
|
|
|
|
|
|
/*
|
|
* manpage specific
|
|
*
|
|
* */
|
|
|
|
body.manpage h1 {
|
|
padding-top: 0.5em;
|
|
padding-bottom: 0.5em;
|
|
border-top: 2px solid silver;
|
|
border-bottom: 2px solid silver;
|
|
}
|
|
body.manpage h2 {
|
|
border-style: none;
|
|
}
|
|
body.manpage div.sectionbody {
|
|
margin-left: 3em;
|
|
}
|
|
|
|
@media print {
|
|
body.manpage 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.toLowerCase() == '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.toLowerCase() == '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.80 -
|
|
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><code>cc <source> -ljim</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>or</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>jimsh [<scriptfile>|-]
|
|
jimsh -e '<immediate-script>'
|
|
jimsh --version
|
|
jimsh --help</code></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/8.7 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><code>ref</code></strong></a>/<a href="#_getref"><strong><code>getref</code></strong></a>/<a href="#_setref"><strong><code>setref</code></strong></a>) and garbage collection
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Builtin dictionary type (<a href="#_dict"><strong><code>dict</code></strong></a>) with some limitations compared to Tcl 8.6
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_env"><strong><code>env</code></strong></a> command to access environment variables
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Operating system features: <a href="#cmd_1"><strong><code>os.fork</code></strong></a>, <a href="#cmd_1"><strong><code>os.uptime</code></strong></a>, <a href="#_wait"><strong><code>wait</code></strong></a>, <a href="#_signal"><strong><code>signal</code></strong></a>, <a href="#_alarm"><strong><code>alarm</code></strong></a>, <a href="#_sleep"><strong><code>sleep</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Much better error reporting. <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code> 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: <code>$(…)</code>
|
|
</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_79_and_0_80">Changes between 0.79 and 0.80</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<a href="#_regsub"><strong><code>regsub</code></strong></a> now fully supports <code>\A</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_socket"><strong><code>socket</code></strong></a> <code>pty</code> to create a pseudo-tty pair
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Null characters (\x00) are now supported in variable and proc names
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
dictionaries and arrays now preserve insertion order, matching Tcl and the documentation
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_dict"><strong><code>dict</code></strong></a> <code>getwithdefault</code> (and the alias <a href="#_dict"><strong><code>dict</code></strong></a> <code>getdef</code>) per TIP 342
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add string comparison operators (lt, gt, le, ge) per TIP 461
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Implement 0d radix prefix for decimal per TIP 472
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_78_and_0_79">Changes between 0.78 and 0.79</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Add <a href="#_file"><strong><code>file</code></strong></a> <code>mtimeus</code> for high resolution file timestamps
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_aio"><strong><code>aio</code></strong></a> now supports datagram Unix-Domain sockets
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_aio"><strong><code>aio</code></strong></a> <code>lock -wait</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_signal"><strong><code>signal</code></strong></a> <code>block</code> to prevent delivery of signals
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_file"><strong><code>file</code></strong></a> <code>split</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_json_encode"><strong><code>json::encode</code></strong></a> and <a href="#_json_decode"><strong><code>json::decode</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_aio"><strong><code>aio</code></strong></a> <code>tty</code> now allows setting <code>echo</code> without full <code>raw</code> mode
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_77_and_0_78">Changes between 0.77 and 0.78</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Add serial/tty support with <a href="#_aio"><strong><code>aio</code></strong></a> <code>tty</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <em>jimsh -</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add hidden <em>-commands</em> option to many commands
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add scriptable autocompletion support in interactive mode with <a href="#_tcl_autocomplete"><strong><code>tcl::autocomplete</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_aio"><strong><code>aio</code></strong></a> <code>sockopt</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add scriptable autocompletion support with <a href="#_history"><strong><code>history</code></strong></a> <code>completion</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_tree"><strong><code>tree</code></strong></a> <code>delete</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_defer"><strong><code>defer</code></strong></a> and <em>$jim::defer</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Renamed <code>os.wait</code> to <a href="#_wait"><strong><code>wait</code></strong></a>, now more Tcl-compatible and compatible with <a href="#_exec"><strong><code>exec</code></strong></a> <code>... &</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_pipe"><strong><code>pipe</code></strong></a> is now a synonym for <a href="#_socket"><strong><code>socket</code></strong></a> <code>pipe</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Closing a pipe open with <a href="#_open"><strong><code>open</code></strong></a> <code>|...</code> now returns Tcl-like status
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
It is now possible to used <a href="#_exec"><strong><code>exec</code></strong></a> redirection with a pipe opened with <a href="#_open"><strong><code>open</code></strong></a> <code>|...</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Interactive line editing now supports multiline mode if $::history::multiline is set
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_76_and_0_77">Changes between 0.76 and 0.77</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_aio"><strong><code>aio</code></strong></a> <code>sync</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add SSL and TLS support in aio
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Added <a href="#_zlib"><strong><code>zlib</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Added support for boolean constants in <a href="#_expr"><strong><code>expr</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_string"><strong><code>string</code></strong></a> <code>is</code> now supports <em>boolean</em> class
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_aio"><strong><code>aio</code></strong></a> <code>lock</code> and <a href="#_aio"><strong><code>aio</code></strong></a> <code>unlock</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add new <a href="#_interp"><strong><code>interp</code></strong></a> command
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_75_and_0_76">Changes between 0.75 and 0.76</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<a href="#_glob"><strong><code>glob</code></strong></a> now supports the <code>-tails</code> option
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_string"><strong><code>string</code></strong></a> <code>cat</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow <a href="#_info"><strong><code>info</code></strong></a> <code>source</code> to add source info
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_changes_between_0_74_and_0_75">Changes between 0.74 and 0.75</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<a href="#_binary"><strong><code>binary</code></strong></a>, <a href="#cmd_3"><strong><code>pack</code></strong></a> and <a href="#cmd_3"><strong><code>unpack</code></strong></a> now support floating point
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_file"><strong><code>file</code></strong></a> <code>copy</code> <code>-force</code> handles source and target as the same file
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_format"><strong><code>format</code></strong></a> now supports <code>%b</code> for binary conversion
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_lsort"><strong><code>lsort</code></strong></a> now supports <code>-unique</code> and <code>-real</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for half-close with <a href="#_aio"><strong><code>aio</code></strong></a> <code>close</code> <code>?r|w?</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_socket"><strong><code>socket</code></strong></a> <code>pair</code> for a bidirectional pipe
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <em>--random-hash</em> to randomise hash tables for greater security
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_dict"><strong><code>dict</code></strong></a> now supports <em>for</em>, <em>values</em>, <em>incr</em>, <em>append</em>, <em>lappend</em>, <em>update</em>, <em>info</em> and <em>replace</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_file"><strong><code>file</code></strong></a> <code>stat</code> no longer requires the variable name
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_file"><strong><code>file</code></strong></a> <code>link</code>
|
|
</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><a href="http://www.oxforddictionaries.com/definition/american_english/tickle">tickle</a></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, <code>jimsh</code>, 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, <code>jimsh</code>, is part of Jim Tcl.
|
|
It may be invoked in interactive mode as:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>jimsh</code></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><code>jimsh filename</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>or to process the Tcl script from standard input:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>jimsh -</code></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><code>jimsh -e "script"</code></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><code>$ 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
|
|
$</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If <code>jimsh</code> 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, <code>^W</code> to erase a word, <code>^U</code> to erase the line, <code>^R</code> for reverse incremental search
|
|
in history. Additionally, the <code>h</code> command may be used to display the command history.</p></div>
|
|
<div class="paragraph"><p>Command line history is automatically saved and loaded from <code>~/.jim_history</code></p></div>
|
|
<div class="paragraph"><p>In interactive mode, <code>jimsh</code> automatically runs the script <code>~/.jimrc</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a 22</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>has three fields: the first, <a href="#_set"><strong><code>set</code></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><code>set</code></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><code>proc</code></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><code>set</code></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><code>unknown</code></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><code>unknown</code></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><code>unknown</code></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 <code>#</code>, then everything
|
|
from the <code>#</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a "This is a single argument"</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will pass two arguments to <a href="#_set"><strong><code>set</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a {xyz a {b c d}}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the <a href="#_set"><strong><code>set</code></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><code>eval</code></strong></a>
|
|
command takes one argument, which is a command string; <a href="#_eval"><strong><code>eval</code></strong></a> invokes
|
|
the Tcl interpreter to execute the command string. The command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> eval {
|
|
set a 22
|
|
set b 33
|
|
}</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a [set b]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>When the <a href="#_set"><strong><code>set</code></strong></a> command has only a single argument, it is the name of a
|
|
variable and <a href="#_set"><strong><code>set</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a foo</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyz[set b].[set c]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyzfoo.gorp</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a x[set b 22
|
|
expr $b+2]x</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a x24x</code></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 (<code>$</code>) may be used as a special shorthand form for
|
|
substituting variable values. If <code>$</code> appears in an argument that isn’t
|
|
enclosed in braces then variable substitution will occur. The characters
|
|
after the <code>$</code>, 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a $foo.c</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a test.c</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyz$x(first)zyx</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyz87zyx</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyz$x($index)zyx</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a xyzmorezyx</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>For more information on arrays, see <a href="#_variables_scalars_and_arrays">VARIABLES - SCALARS AND ARRAYS</a> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a abc${foo}bar</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is equivalent to the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a abctestbar</code></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. <code>$a</code> is
|
|
completely equivalent to <code>[set a]</code>; 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 (<code>;</code>) 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">
|
|
<code>\b</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Backspace (0x8)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\f</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Form feed (0xc)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\n</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Newline (0xa)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\r</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Carriage-return (0xd).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\t</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Tab (0x9).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\v</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Vertical tab (0xb).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\{</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Left brace ({).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\}</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Right brace (}).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\[</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open bracket ([).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\]</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Close bracket (]).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\$</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Dollar sign ($).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\<space></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Space ( ): doesn’t terminate argument.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\;</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Semi-colon: doesn’t terminate command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\"</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Double-quote.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\<newline></code>
|
|
</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">
|
|
<code>\\</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Backslash (<em>\</em>).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\ddd</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The digits <code><em>ddd</em></code> (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">
|
|
<code>\unnnn</code>
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<code>\u{nnn}</code>
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<code>\Unnnnnnnn</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The UTF-8 encoding of the unicode codepoint represented by the hex digits, <code><em>nnnn</em></code>, 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a \{x\[\ yz\141</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the second argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>{x[ yza</code>.</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set \*a \\\{foo</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The first argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>\*a</code> and the second
|
|
argument will be <code>\{foo</code>.</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a {\{abc}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>the second argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>\{abc</code>.</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><code>format</code></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">
|
|
<code>integer</code>
|
|
</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">
|
|
<code>integer+integer</code> or
|
|
</dt>
|
|
<dt class="hdlist1">
|
|
<code>integer-integer</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The sum or difference of the two integers. e.g. <code>2+3</code> refers to the 5th element.
|
|
This is useful when used with (e.g.) <code>$i+1</code> rather than the more verbose
|
|
<code>[expr {$i+1}]</code>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>end</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The last element of the string or list.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>end-integer</code>
|
|
</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 <code>#</code>, everything
|
|
from the <code>#</code> 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><code>expr</code></strong></a>, <a href="#_for"><strong><code>for</code></strong></a>,
|
|
and <a href="#_if"><strong><code>if</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> 8.2 + 6</code></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 are interpreted as decimal, binary, octal or
|
|
hexadecimal if prepended with <em>0d</em>, <em>0b</em>, <em>0o</em> or <em>0x</em>
|
|
respectively. Otherwise they are interpreted as decimal by default.
|
|
(Jim Tcl does not interpret numbers with leading zeros as octal.)</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="paragraph"><p>String constants representing boolean constants
|
|
(<code><em>0</em></code>, <code><em>1</em></code>, <code><em>false</em></code>, <code><em>off</em></code>, <code><em>no</em></code>, <code><em>true</em></code>, <code><em>on</em></code>, <code><em>yes</em></code>)
|
|
are also recognized and can be used in logical operations.</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 one of valid boolean constants
|
|
</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> $a + 3.1 6.1
|
|
2 + "$a.$b" 5.6
|
|
4*[llength "6 2"] 8
|
|
{word one} < "word $a" 0</code></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">
|
|
<code>int() double() round() abs(), rand(), srand()</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unary functions (except rand() which takes no arguments)
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<code><em>int()</em></code> converts the numeric argument to an integer by truncating down.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><em>double()</em></code> converts the numeric argument to floating point.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><em>round()</em></code> converts the numeric argument to the closest integer value.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><em>abs()</em></code> takes the absolute value of the numeric argument.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><em>rand()</em></code> returns a pseudo-random floating-point value in the range (0,1).
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><em>srand()</em></code> 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">
|
|
<code>sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unary math functions.
|
|
If Jim is compiled with math support, these functions are available.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>- + ~ !</code>
|
|
</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">
|
|
<code>** pow(x,y)</code>
|
|
</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">
|
|
<code>* / %</code>
|
|
</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">
|
|
<code>+ -</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Add and subtract. Valid for any numeric operands.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><< >> <<< >>></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Left and right shift, left and right rotate. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>< > <= >=</code>
|
|
</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">
|
|
<code>lt gt le ge</code>
|
|
</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 differ from the above in that they use string comparison
|
|
for all operands, including numeric.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>== !=</code>
|
|
</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">
|
|
<code>eq ne</code>
|
|
</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">
|
|
<code>in ni</code>
|
|
</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
|
|
<code>{$a ni $list}</code> is equivalent to <code>{!($a in $list)}</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>&</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise AND. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>|</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise OR. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>^</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Bit-wise exclusive OR. Valid for integer operands only.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>&&</code>
|
|
</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">
|
|
<code>||</code>
|
|
</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">
|
|
<code>x ? y : z</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If-then-else, as in C. If <code><em>x</em></code>
|
|
evaluates to non-zero, then the result is the value of <code><em>y</em></code>.
|
|
Otherwise the result is the value of <code><em>z</em></code>.
|
|
The <code><em>x</em></code> operand must have a numeric value, while <code><em>y</em></code> and <code><em>z</em></code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> 4*2 < 7</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>evaluates to 0.</p></div>
|
|
<div class="paragraph"><p>The <code>&&</code>, <code>||</code>, and <code>?:</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> $v ? [a] : [b]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>only one of <code>[a]</code> or <code>[b]</code> will actually be evaluated,
|
|
depending on the value of <code>$v</code>.</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,
|
|
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="listingblock">
|
|
<div class="content">
|
|
<pre><code> 5 / 4</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>yields the result 1, while</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> 5 / 4.0
|
|
5 / ( [string length "abcd"] + 0.0 )</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> "0x03" > "2"
|
|
"0y" < "0x12"</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> expr $a + $b</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>results in three arguments being passed to <a href="#_expr"><strong><code>expr</code></strong></a>: <code>$a</code>,
|
|
+, and <code>$b</code>. 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> for {set i 1} $i<=10 {incr i} {...} ** WRONG **</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is probably intended to iterate over all values of <code>i</code> from 1 to 10.
|
|
After each iteration of the body of the loop, <a href="#_for"><strong><code>for</code></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 <code>i</code>
|
|
in the second argument will be substituted once and for all when the
|
|
<a href="#_for"><strong><code>for</code></strong></a> command is parsed. If <code>i</code> was 0 before the <a href="#_for"><strong><code>for</code></strong></a>
|
|
command was invoked then the second argument of <a href="#_for"><strong><code>for</code></strong></a> will be <code>0<=10</code>
|
|
which will always evaluate to 1, even though <code>i</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> for {set i 1} {$i<=10} {incr i} {...} ** RIGHT **</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> Al Sue Anne John</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> a b\ c {d e {f g h}}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is a list with three elements: <code>a</code>, <code>b c</code>, and <code>d e {f g h}</code>.</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> d e {f g h}</code></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><code>concat</code></strong></a>, <a href="#_foreach"><strong><code>foreach</code></strong></a>, <a href="#_lappend"><strong><code>lappend</code></strong></a>, <a href="#_lindex"><strong><code>lindex</code></strong></a>, <a href="#_linsert"><strong><code>linsert</code></strong></a>,
|
|
<a href="#_list"><strong><code>list</code></strong></a>, <a href="#_llength"><strong><code>llength</code></strong></a>, <a href="#_lrange"><strong><code>lrange</code></strong></a>, <a href="#_lreplace"><strong><code>lreplace</code></strong></a>, <a href="#_lsearch"><strong><code>lsearch</code></strong></a>, and <a href="#_lsort"><strong><code>lsort</code></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><code>lrepeat</code></strong></a>, <a href="#_lreverse"><strong><code>lreverse</code></strong></a>, <a href="#_lmap"><strong><code>lmap</code></strong></a>, <a href="#_lassign"><strong><code>lassign</code></strong></a>, <a href="#_lset"><strong><code>lset</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set cmd {ls -l}
|
|
exec $cmd</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This will attempt to exec 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 <code>{*}</code>.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> exec {*}$cmd</code></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 <code>{*}</code>, however <code>{expand}</code> 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>Jim Tcl provides two commands that support string matching using regular
|
|
expressions, <a href="#_regexp"><strong><code>regexp</code></strong></a> and <a href="#_regsub"><strong><code>regsub</code></strong></a>, as well as <a href="#_switch"><strong><code>switch</code></strong></a> <code>-regexp</code> and
|
|
<a href="#_lsearch"><strong><code>lsearch</code></strong></a> <code>-regexp</code>.</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 (<code>ARE</code>).</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 (<code>ERE</code>) rather than Basic Regular Expressions (<code>BRE</code>).
|
|
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 <code>\w</code>, <code>\d</code>, <code>\s</code> are not supported, and null characters
|
|
in strings 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 regular expression engine may be selected with <code>./configure --with-jim-regexp</code>
|
|
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 <code>ARE</code> 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>
|
|
All Tcl character classes are supported (e.g. <code>[:alnum:]</code>, <code>[:digit:]</code>, <code>[:space:]</code>), but…
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Character classes apply to ASCII characters only
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Supported shorthand character classes: <code>\w</code> = <code>[:alnum:]</code>, <code>\W</code> = <code><sup>[:alnum:]</code>, <code>\d</code> = <code>[:digit:],</code> <code>\D</code> = <code></sup>[:digit:],</code> <code>\s</code> = <code>[:space:]</code>, + <code>\S</code> = <code>^[:space:]</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Supported constraint escapes: <code>\m</code> = <code>\<</code> = start of word, <code>\M</code> = <code>\></code> = end of word, <code>\A</code> = start of string, <code>\Z</code> = end of string
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Backslash escapes may be used within regular expressions, such as <code>\n</code> = newline, <code>\uNNNN</code> = unicode
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for the <code>?</code> non-greedy quantifier. e.g. <code>*?</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support for non-capturing parentheses <code>(?:…)</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Jim Tcl considers that both patterns and strings end at a null character (<code>\x00</code>)
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_string_matching">STRING MATCHING</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>A number of commands in Jim support C-shell style "glob matching", including
|
|
<a href="#_string"><strong><code>string</code></strong></a> <code>match</code>, <a href="#_switch"><strong><code>switch</code></strong></a> <code>-glob</code>, <a href="#_array"><strong><code>array</code></strong></a> <code>names</code> and others. This form of string matching
|
|
works as follows:</p></div>
|
|
<div class="paragraph"><p>A test occurs where a <code><em>string</em></code> is matched against a <code><em>pattern</em></code>. The match is considered
|
|
successful if the contents of <code><em>string</em></code> and <code><em>pattern</em></code> are identical except that the
|
|
following special sequences may appear in <code><em>pattern</em></code>:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code>*</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any sequence of characters in <code><em>string</em></code>, including an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any single character in <code><em>string</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>[<em>chars</em>]</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches any character in the set given by <code><em>chars</em></code>.
|
|
If a sequence of the form <code><em>x-y</em></code> appears in <code><em>chars</em></code>,
|
|
then any character between <code><em>x</em></code> and <code><em>y</em></code>, inclusive,
|
|
will match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>\x</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Matches the single character <code><em>x</em></code>. This provides a way of
|
|
avoiding the special interpretation of the characters <code>\*?[]</code>
|
|
in <code><em>pattern</em></code>.
|
|
</p>
|
|
</dd>
|
|
</dl></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">
|
|
<code>JIM_OK(0)</code>
|
|
</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">
|
|
<code>JIM_ERR(1)</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that an error occurred; the string gives a message describing
|
|
the error.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>JIM_RETURN(2)</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_return"><strong><code>return</code></strong></a> command has been invoked, and that the
|
|
current procedure (or top-level command or <a href="#_source"><strong><code>source</code></strong></a> command)
|
|
should return immediately. The
|
|
string gives the return value for the procedure or command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>JIM_BREAK(3)</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_break"><strong><code>break</code></strong></a> command has been invoked, so the
|
|
innermost loop should abort immediately. The string should always
|
|
be empty.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>JIM_CONTINUE(4)</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the <a href="#_continue"><strong><code>continue</code></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">
|
|
<code>JIM_SIGNAL(5)</code>
|
|
</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><code>signal</code></strong></a> and <a href="#_catch"><strong><code>catch</code></strong></a> commands.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>JIM_EXIT(6)</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Indicates that the command called the <a href="#_exit"><strong><code>exit</code></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 <code>JIM_OK</code> 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><code>error</code></strong></a> conditions
|
|
themselves and not return them upwards. For example, the <a href="#_for"><strong><code>for</code></strong></a>
|
|
command checks for the <code>JIM_BREAK</code> code; if it occurs, then <a href="#_for"><strong><code>for</code></strong></a>
|
|
stops executing the body of the loop and returns <code>JIM_OK</code> to its
|
|
caller. The <a href="#_for"><strong><code>for</code></strong></a> command also handles <code>JIM_CONTINUE</code> codes and the
|
|
procedure interpreter handles <code>JIM_RETURN</code> codes. The <a href="#_catch"><strong><code>catch</code></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><code>info</code></strong></a> <code>returncodes</code> 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><code>proc</code></strong></a> command is used to create a new Tcl command procedure:</p></div>
|
|
<div class="paragraph"><p><code><strong>proc</strong> <em>name arglist ?statics? body</em></code></p></div>
|
|
<div class="paragraph"><p>The new command is named <code><em>name</em></code>, and it replaces any existing command
|
|
there may have been by that name. Whenever the new command is
|
|
invoked, the contents of <code><em>body</em></code> will be executed by the Tcl
|
|
interpreter.</p></div>
|
|
<div class="paragraph"><p><code><em>arglist</em></code> 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">
|
|
<code>name</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Required Argument - A simple argument name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>{name default}</code>
|
|
</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">
|
|
<code>&name</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Reference Argument - The caller is expected to pass the name of
|
|
an existing variable. An implicit <code><a href="#_upvar"><strong><code>upvar</code></strong></a> 1 origname name</code> is done
|
|
to make the variable available in the proc scope.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>args</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Variable Argument - The special name <code><em>args</em></code>, which is
|
|
assigned all remaining arguments (including none) as a list. The
|
|
variable argument may only be specified once. Note that
|
|
the syntax <code>{args newname}</code> may be used to retain the special
|
|
behaviour of <code><em>args</em></code> with a different local name. In this case,
|
|
the variable is named <code><em>newname</em></code> rather than <code><em>args</em></code>.
|
|
</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> proc p {{a A} args b {c C} d} {...}</code></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 <code>-</code> 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 <code><em>body</em></code> 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><code>global</code></strong></a> command or via the <code>::</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> . set a 1
|
|
. proc a {} {a {b 2}} {
|
|
set c 1
|
|
puts "$a $b $c"
|
|
incr a
|
|
incr b
|
|
incr c
|
|
}
|
|
. a
|
|
1 2 1
|
|
. a
|
|
2 3 1</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The static variable <code><em>a</em></code> 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 <code><em>b</em></code>
|
|
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><code>proc</code></strong></a> command for information on how to define procedures
|
|
and what happens when they are invoked. See also <a href="#_namespaces">NAMESPACES</a>.</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><code>set</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set x(first) 44</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a(2,3) 1
|
|
set a(3,6) 2</code></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><code>unset</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_array"><strong><code>array</code></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><code>global</code></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 <code>::</code> prefix. For example</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . set a 1
|
|
. set b 2
|
|
. proc p {} {
|
|
set c 3
|
|
global a
|
|
|
|
puts "$a $::b $c"
|
|
}
|
|
. p</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>1 2 3</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a {1 one 2 two}
|
|
puts $a(2)</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> two</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Thus <a href="#_array"><strong><code>array</code></strong></a> <code>set</code> is equivalent to <a href="#_set"><strong><code>set</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a(1) one; set a(2) two
|
|
puts $a</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will output:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> 1 one 2 two</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> . dict set a 1 one
|
|
1 one
|
|
. dict set a 2 two
|
|
1 one 2 two
|
|
. puts $a
|
|
1 one 2 two
|
|
. puts $a(2)
|
|
two
|
|
. dict set a 3 T three
|
|
1 one 2 two 3 {T three}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See the <a href="#_dict"><strong><code>dict</code></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><code>namespace</code></strong></a> command.</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_garbage_collection_references_lambda_function">GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> . set r [ref "One String" test]
|
|
<reference.<test___>.00000000000000000000>
|
|
. getref $r
|
|
One String</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The operation <a href="#_ref"><strong><code>ref</code></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><code>getref</code></strong></a> is the dereferencing operation which retrieves the value
|
|
stored in the reference.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . setref $r "New String"
|
|
New String
|
|
. getref $r
|
|
New String</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The operation <a href="#_setref"><strong><code>setref</code></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><code>collect</code></strong></a> command may be used to force garbage collection. Consider a reference created
|
|
with a finalizer:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . proc f {ref value} { puts "Finaliser called for $ref,$value" }
|
|
. set r [ref "One String" test f]
|
|
<reference.<test___>.00000000000
|
|
. collect
|
|
0
|
|
. set r ""
|
|
. collect
|
|
Finaliser called for <reference.<test___>.00000000000,One String
|
|
1</code></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><code>finalize</code></strong></a> command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . finalize $r
|
|
f
|
|
. finalize $r newf
|
|
newf</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lambda_function">Lambda Function</h3>
|
|
<div class="paragraph"><p>Jim provides a garbage collected <a href="#_lambda"><strong><code>lambda</code></strong></a> function. This is a procedure
|
|
which is able to create an anonymous procedure. Consider:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . set f [lambda {a} {{x 0}} { incr x $a }]
|
|
. $f 1
|
|
1
|
|
. $f 2
|
|
3
|
|
. set f ""</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> . rename $f ""</code></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><code>string</code></strong></a> <code>match</code>, <a href="#_split"><strong><code>split</code></strong></a>, <a href="#_glob"><strong><code>glob</code></strong></a>, <a href="#_scan"><strong><code>scan</code></strong></a> and
|
|
<a href="#_format"><strong><code>format</code></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><code>string</code></strong></a> <code>bytelength</code> which returns the number of bytes in a string,
|
|
while <a href="#_string"><strong><code>string</code></strong></a> <code>length</code> 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><code>string</code></strong></a> <code>bytelength</code> returns the same value as <a href="#_string"><strong><code>string</code></strong></a> <code>length</code>.</p></div>
|
|
<div class="paragraph"><p>Note that even if UTF-8 support is not enabled, the <code>\uNNNN</code> 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_2">String Matching</h3>
|
|
<div class="paragraph"><p>Commands such as <a href="#_string"><strong><code>string</code></strong></a> <code>match</code>, <a href="#_lsearch"><strong><code>lsearch</code></strong></a> <code>-glob</code>, <a href="#_array"><strong><code>array</code></strong></a> <code>names</code> and others use
|
|
<a href="#_string_matching">STRING MATCHING</a> rules. These commands support UTF-8. For example:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> string match a\[\ua0-\ubf\]b "a\u00a3b"</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_format_and_scan">format and scan</h3>
|
|
<div class="paragraph"><p><code>format %c</code> 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 <code>\ub5</code></p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> format %c 0xb5</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_format"><strong><code>format</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> format %.3s \ub5\ub6\ub7\ub8</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Similarly, <code>scan … %c</code> allows a UTF-8 to be decoded to a unicode codepoint. The following will set
|
|
<code><em>a</em></code> to 181 (0xb5) and <code><em>b</em></code> to 65 (0x41).</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> scan \u00b5A %c%c a b</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_scan"><strong><code>scan</code></strong></a> <code>%s</code> 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><code>string</code></strong></a> <code>is</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> string is alpha \ub5Test</code></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><code>string</code></strong></a> <code>toupper</code> 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><code>string</code></strong></a> <code>tolower</code> and <a href="#_string"><strong><code>string</code></strong></a> <code>totitle</code>.</p></div>
|
|
<div class="paragraph"><p>Commands which perform case insensitive matches, such as <a href="#_string"><strong><code>string</code></strong></a> <code>compare -nocase</code>
|
|
and <a href="#_lsearch"><strong><code>lsearch</code></strong></a> <code>-nocase</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> string bytelength \xff\xff</code></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 <a href="#_regular_expressions">REGULAR EXPRESSIONS</a></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 <code><strong>boldface</strong></code> are
|
|
literals that you type verbatim to Tcl.</p></div>
|
|
<div class="paragraph"><p>Words in <code><em>italics</em></code> 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 <code>?question-marks?</code>.</p></div>
|
|
<div class="paragraph"><p>Ellipses (<code>...</code>) 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><code>after</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_aio"><strong><code>aio</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_alarm"><strong><code>alarm</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_alias"><strong><code>alias</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_append"><strong><code>append</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_apply"><strong><code>apply</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_array"><strong><code>array</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_binary"><strong><code>binary</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_break"><strong><code>break</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_case"><strong><code>case</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_catch"><strong><code>catch</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_cd"><strong><code>cd</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>class</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_clock"><strong><code>clock</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_close"><strong><code>close</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_collect"><strong><code>collect</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_concat"><strong><code>concat</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_continue"><strong><code>continue</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_curry"><strong><code>curry</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_defer"><strong><code>defer</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_dict"><strong><code>dict</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_env"><strong><code>env</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_eof"><strong><code>eof</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_error"><strong><code>error</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_eval"><strong><code>eval</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>eventloop</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exec"><strong><code>exec</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exists"><strong><code>exists</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_exit"><strong><code>exit</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_expr"><strong><code>expr</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_fconfigure"><strong><code>fconfigure</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_file"><strong><code>file</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_finalize"><strong><code>finalize</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_flush"><strong><code>flush</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_for"><strong><code>for</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_foreach"><strong><code>foreach</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_format"><strong><code>format</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_getref"><strong><code>getref</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_gets"><strong><code>gets</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_glob"><strong><code>glob</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_global"><strong><code>global</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_history"><strong><code>history</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_if"><strong><code>if</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_incr"><strong><code>incr</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_info"><strong><code>info</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_interp"><strong><code>interp</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_join"><strong><code>join</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_json_decode"><strong><code>json::decode</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_json_encode"><strong><code>json::encode</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_kill"><strong><code>kill</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lambda"><strong><code>lambda</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lappend"><strong><code>lappend</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lassign"><strong><code>lassign</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lindex"><strong><code>lindex</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_linsert"><strong><code>linsert</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_list"><strong><code>list</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_llength"><strong><code>llength</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lmap"><strong><code>lmap</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_load"><strong><code>load</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_local"><strong><code>local</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_loop"><strong><code>loop</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lrange"><strong><code>lrange</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lrepeat"><strong><code>lrepeat</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lreplace"><strong><code>lreplace</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lreverse"><strong><code>lreverse</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lsearch"><strong><code>lsearch</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lset"><strong><code>lset</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_lsort"><strong><code>lsort</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_namespace"><strong><code>namespace</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>oo</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_open"><strong><code>open</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.fork</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.gethostname</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.getids</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.uptime</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>pack</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>pack</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_package"><strong><code>package</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_pid"><strong><code>pid</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_pipe"><strong><code>pipe</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>posix</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_proc"><strong><code>proc</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_puts"><strong><code>puts</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_pwd"><strong><code>pwd</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_rand"><strong><code>rand</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_range"><strong><code>range</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_read"><strong><code>read</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_ref"><strong><code>ref</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_regexp"><strong><code>regexp</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_regsub"><strong><code>regsub</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_rename"><strong><code>rename</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_return"><strong><code>return</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_scan"><strong><code>scan</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_seek"><strong><code>seek</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_set"><strong><code>set</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_setref"><strong><code>setref</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_signal"><strong><code>signal</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_sleep"><strong><code>sleep</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_socket"><strong><code>socket</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_source"><strong><code>source</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_split"><strong><code>split</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_stackdump"><strong><code>stackdump</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_stacktrace"><strong><code>stacktrace</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_string"><strong><code>string</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_subst"><strong><code>subst</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>super</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_switch"><strong><code>switch</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_syslog"><strong><code>syslog</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tailcall"><strong><code>tailcall</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tcl_autocomplete"><strong><code>tcl::autocomplete</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tcl_prefix"><strong><code>tcl::prefix</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tell"><strong><code>tell</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#_throw"><strong><code>throw</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_time"><strong><code>time</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_tree"><strong><code>tree</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_try"><strong><code>try</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_unknown"><strong><code>unknown</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>unpack</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_unset"><strong><code>unset</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_upcall"><strong><code>upcall</code></strong></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>update</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_uplevel"><strong><code>uplevel</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_upvar"><strong><code>upvar</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>vwait</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_wait"><strong><code>wait</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_while"><strong><code>while</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"><a href="#_zlib"><strong><code>zlib</code></strong></a></p></td>
|
|
<td align="left" valign="top"><p class="table"></p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_alarm">alarm</h3>
|
|
<div class="paragraph"><p><code><strong>alarm</strong> <em>seconds</em></code></p></div>
|
|
<div class="paragraph"><p>Delivers the <code>SIGALRM</code> 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 <code>SIGALRM</code> has been installed
|
|
(see <a href="#_signal"><strong><code>signal</code></strong></a>), the process will exit on this signal.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_alias">alias</h3>
|
|
<div class="paragraph"><p><code><strong>alias</strong> <em>name args...</em></code></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><code>info</code></strong></a> <code>exists</code>.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> alias e info exists
|
|
if {[e var]} {
|
|
...
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_alias"><strong><code>alias</code></strong></a> returns <code><em>name</em></code>, allowing it to be used with <a href="#_local"><strong><code>local</code></strong></a>.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_proc"><strong><code>proc</code></strong></a>, <a href="#_curry"><strong><code>curry</code></strong></a>, <a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_local"><strong><code>local</code></strong></a>, <a href="#_info"><strong><code>info</code></strong></a> <code>alias</code>, <a href="#_exists"><strong><code>exists</code></strong></a> <code>-alias</code></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_append">append</h3>
|
|
<div class="paragraph"><p><code><strong>append</strong> <em>varName value ?value value …?</em></code></p></div>
|
|
<div class="paragraph"><p>Append all of the <code><em>value</em></code> arguments to the current value
|
|
of variable <code><em>varName</em></code>. If <code><em>varName</em></code> doesn’t exist,
|
|
it is given a value equal to the concatenation of all the
|
|
<code><em>value</em></code> 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><code>append</code></strong></a> <code>a $b</code>" is much more efficient than
|
|
"<a href="#_set"><strong><code>set</code></strong></a> <code>a $a$b</code>" if <code>$a</code> is long.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_apply">apply</h3>
|
|
<div class="paragraph"><p><code><strong>apply</strong> <em>lambdaExpr ?arg1 arg2 ...?</em></code></p></div>
|
|
<div class="paragraph"><p>The command <a href="#_apply"><strong><code>apply</code></strong></a> provides for anonymous procedure calls,
|
|
similar to <a href="#_lambda"><strong><code>lambda</code></strong></a>, but without a command name being created, even temporarily.</p></div>
|
|
<div class="paragraph"><p>The function <code><em>lambdaExpr</em></code> is a two element list, <code>{args body}</code>
|
|
or a three element list, <code>{args body namespace}</code>. The first element
|
|
<code><em>args</em></code> specifies the formal arguments in the same form as the <a href="#_proc"><strong><code>proc</code></strong></a> and <a href="#_lambda"><strong><code>lambda</code></strong></a> commands.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_array">array</h3>
|
|
<div class="paragraph"><p><code><strong>array</strong> <em>option arrayName ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command performs one of several operations on the
|
|
variable given by <code><em>arrayName</em></code>.</p></div>
|
|
<div class="paragraph"><p>Note that in general, if the named array does not exist, the <code><em>array</em></code> command behaves
|
|
as though the array exists but is empty.</p></div>
|
|
<div class="paragraph"><p>The <code><em>option</em></code> argument determines what action is carried out by the
|
|
command. The legal <code><em>options</em></code> (which may be abbreviated) are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>array exists</strong> <em>arrayName</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if <code><em>arrayName</em></code> is an array variable, 0 if there is
|
|
no variable by that name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>array get</strong> <em>arrayName ?pattern?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing pairs of elements. The first
|
|
element in each pair is the name of an element in <code><em>arrayName</em></code>
|
|
and the second element of each pair is the value of the
|
|
array element. The order of the pairs is undefined. If
|
|
<code><em>pattern</em></code> is not specified, then all of the elements of the
|
|
array are included in the result. If <code><em>pattern</em></code> is specified,
|
|
then only those elements whose names match <code><em>pattern</em></code> (using
|
|
<a href="#_string_matching">STRING MATCHING</a> rules) are included. If <code><em>arrayName</em></code>
|
|
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">
|
|
<code><strong>array names</strong> <em>arrayName ?pattern?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing the names of all of the elements
|
|
in the array that match <code><em>pattern</em></code>. If <code><em>pattern</em></code> is omitted then
|
|
the command returns all of the element names in the array.
|
|
If <code><em>pattern</em></code> is specified, then only those elements whose
|
|
names match <code><em>pattern</em></code> (using <a href="#_string_matching">STRING MATCHING</a> rules)
|
|
are included. If there are no (matching) elements
|
|
in the array, or if <code><em>arrayName</em></code> isn’t the name of an array
|
|
variable, then an empty string is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>array set</strong> <em>arrayName list</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets the values of one or more elements in <code><em>arrayName</em></code>. <code><em>list</em></code>
|
|
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 <code><em>arrayName</em></code> does not
|
|
already exist and list is empty, <code><em>arrayName</em></code> is created with
|
|
an empty array value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>array size</strong> <em>arrayName</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the number of elements in the array. If <code><em>arrayName</em></code>
|
|
isn’t the name of an array then 0 is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>array unset</strong> <em>arrayName ?pattern?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unsets all of the elements in the array that match <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules). If <code><em>arrayName</em></code>
|
|
isn’t the name of an array variable or there are no matching
|
|
elements in the array, no error will be raised. If <code><em>pattern</em></code>
|
|
is omitted and <code><em>arrayName</em></code> 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><code><strong>break</strong></code></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><code>for</code></strong></a> or <a href="#_foreach"><strong><code>foreach</code></strong></a> or <a href="#_while"><strong><code>while</code></strong></a>. It returns a <code>JIM_BREAK</code> 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>The obsolete <em><code><strong>case</strong></code></em> command has been removed from Jim Tcl since v0.75.
|
|
Use <a href="#_switch"><strong><code>switch</code></strong></a> instead.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_catch">catch</h3>
|
|
<div class="paragraph"><p><code><strong>catch</strong> ?-?no?<em>code ...</em>? ?--? <em>command ?resultVarName? ?optionsVarName?</em></code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_catch"><strong><code>catch</code></strong></a> command may be used to prevent errors from aborting
|
|
command interpretation. <a href="#_catch"><strong><code>catch</code></strong></a> evaluates <code><em>command</em></code>, and returns a
|
|
<code>JIM_OK</code> code, regardless of any errors that might occur while
|
|
executing <code><em>command</em></code> (with the possible exception of <code>JIM_SIGNAL</code> -
|
|
see below).</p></div>
|
|
<div class="paragraph"><p>The return value from <a href="#_catch"><strong><code>catch</code></strong></a> is a decimal string giving the code
|
|
returned by the Tcl interpreter after executing <code><em>command</em></code>. This
|
|
will be <em>0</em> (<code>JIM_OK</code>) if there were no errors in <code><em>command</em></code>; 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><code>info</code></strong></a> <code>returncodes</code> command).</p></div>
|
|
<div class="paragraph"><p>If the <code><em>resultVarName</em></code> argument is given, then it gives the name
|
|
of a variable; <a href="#_catch"><strong><code>catch</code></strong></a> will set the value of the variable to the
|
|
string returned from <code><em>command</em></code> (either a result or an error message).</p></div>
|
|
<div class="paragraph"><p>If the <code><em>optionsVarName</em></code> argument is given, then it gives the name
|
|
of a variable; <a href="#_catch"><strong><code>catch</code></strong></a> will set the value of the variable to a
|
|
dictionary. For any return code other than <code>JIM_RETURN</code>, the value
|
|
for the key <code>-code</code> will be set to the return code. For <code>JIM_RETURN</code>
|
|
it will be set to the code given in <a href="#_return"><strong><code>return</code></strong></a> <code>-code</code>. Additionally,
|
|
for the return code <code>JIM_ERR</code>, the value of the key <code>-errorinfo</code>
|
|
will contain the current stack trace (the same result as <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>),
|
|
the value of the key <code>-errorcode</code> will contain the
|
|
same value as the global variable $::errorCode, and the value of
|
|
the key <code>-level</code> will be the current return level (see <a href="#_return"><strong><code>return</code></strong></a> <code>-level</code>).
|
|
This can be useful to rethrow an error:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> if {[catch {...} msg opts]} {
|
|
...maybe do something with the error...
|
|
incr opts(-level)
|
|
return {*}$opts $msg
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Normally <a href="#_catch"><strong><code>catch</code></strong></a> will <code><em>not</em></code> catch any of the codes <code>JIM_EXIT</code>, <code>JIM_EVAL</code> or <code>JIM_SIGNAL</code>.
|
|
The set of codes which will be caught may be modified by specifying the one more codes before
|
|
<code><em>command</em></code>.</p></div>
|
|
<div class="paragraph"><p>e.g. To catch <code>JIM_EXIT</code> but not <code>JIM_BREAK</code> or <code>JIM_CONTINUE</code></p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> catch -exit -nobreak -nocontinue -- { ... }</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The use of <code>--</code> 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><code>signal</code></strong></a> <code>handle</code> is caught with <a href="#_catch"><strong><code>catch</code></strong></a> <code>-signal</code>, the return value
|
|
(stored in <code><em>resultVarName</em></code>) is name of the signal caught.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_cd">cd</h3>
|
|
<div class="paragraph"><p><code><strong>cd</strong> <em>dirName</em></code></p></div>
|
|
<div class="paragraph"><p>Change the current working directory to <code><em>dirName</em></code>.</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">
|
|
<code><strong>clock seconds</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current time as seconds since the epoch.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>clock clicks</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current time in "clicks", a system-dependent, high-resolution time.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>clock microseconds</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current time in microseconds.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>clock milliseconds</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current time in milliseconds.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>clock format</strong> <em>seconds</em> ?<strong>-format</strong> <em>format?</em> ?<strong>-gmt</strong> <em>boolean?</em></code>
|
|
</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">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>boolean</em></code> is true, processing is performed in UTC.
|
|
If <code><em>boolean</em></code> is false (the default), processing is performed in the local time zone.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>clock scan</strong> <em>str</em> <strong>-format</strong> <em>format</em> ?<strong>-gmt</strong> <em>boolean?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Scan the given time string using the given format string.
|
|
See strptime(3) for supported formats.
|
|
See <a href="#_clock"><strong><code>clock</code></strong></a> <code>format</code> for the handling of <em>-gmt</em>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p><strong>NOTE</strong> Some systems such as 32-bit Linux have only a 32-bit time_t, and are therefore not year 2038
|
|
compliant.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_close">close</h3>
|
|
<div class="paragraph"><p><code><strong>close</strong> <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>close</strong></code></p></div>
|
|
<div class="paragraph"><p>Closes the file given by <code><em>fileId</em></code>.
|
|
<code><em>fileId</em></code> must be the return value from a previous invocation
|
|
of the <a href="#_open"><strong><code>open</code></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><code><strong>collect</strong></code></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><code>collect</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_concat">concat</h3>
|
|
<div class="paragraph"><p><code><strong>concat</strong> <em>arg ?arg ...?</em></code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> concat a b {c d e} {f {g h}}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> a b c d e f {g h}</code></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><code><strong>continue</strong></code></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><code>for</code></strong></a> or <a href="#_foreach"><strong><code>foreach</code></strong></a> or <a href="#_while"><strong><code>while</code></strong></a>. It returns a <code>JIM_CONTINUE</code> 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><code><strong>alias</strong> <em>args...</em></code></p></div>
|
|
<div class="paragraph"><p>Similar to <a href="#_alias"><strong><code>alias</code></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><code>info</code></strong></a> <code>exists</code>.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set e [local curry info exists]
|
|
if {[$e var]} {
|
|
...
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_curry"><strong><code>curry</code></strong></a> returns the name of the procedure.</p></div>
|
|
<div class="paragraph"><p>See also <a href="#_proc"><strong><code>proc</code></strong></a>, <a href="#_alias"><strong><code>alias</code></strong></a>, <a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_local"><strong><code>local</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_dict">dict</h3>
|
|
<div class="paragraph"><p><code><strong>dict</strong> <em>option ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p>Performs one of several operations on dictionary values.</p></div>
|
|
<div class="paragraph"><p>The <code><em>option</em></code> argument determines what action is carried out by the
|
|
command. The legal <code><em>options</em></code> are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict create</strong> <em>?key value ...?</em></code>
|
|
</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">
|
|
<code><strong>dict exists</strong> <em>dictionary key ?key ...?</em></code>
|
|
</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><code>dict</code></strong></a> <code>get</code>
|
|
on that path will succeed.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict get</strong> <em>dictionary ?key ...?</em></code>
|
|
</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><code>dict</code></strong></a> <code>get $dictVal $key</code>" 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 manner 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">
|
|
<code><strong>dict getdef</strong> <em>dictionary ?key ...? key default</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Alias for <a href="#_dict"><strong><code>dict</code></strong></a> <code>getwithdefault</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict getwithdefault</strong> <em>dictionary ?key ...? key default</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Similar to <a href="#_dict"><strong><code>dict</code></strong></a> <code>get</code> except if no value exists in the dictionary for the
|
|
give key(s), returns <code><em>default</em></code> instead.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict keys</strong> <em>dictionary ?pattern?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of the keys in the dictionary.
|
|
If <code><em>pattern</em></code> is specified, then only those keys whose
|
|
names match <code><em>pattern</em></code> (using <a href="#_string_matching">STRING MATCHING</a> rules)
|
|
are included.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict merge</strong> ?<em>dictionary ...</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a dictionary that contains the contents of each of the
|
|
<code><em>dictionary</em></code> 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">
|
|
<code><strong>dict set</strong> <em>dictionaryName key ?key ...? value</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This operation takes the <code><em>name</em></code> 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">
|
|
<code><strong>dict size</strong> <em>dictionary</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return the number of key/value mappings in the given dictionary value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>dict unset</strong> <em>dictionaryName key ?key ...? value</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This operation (the companion to <a href="#_dict"><strong><code>dict</code></strong></a> <code>set</code>) 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">
|
|
<code><strong>dict with</strong> <em>dictionaryName key ?key ...? script</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Execute the Tcl script in <code><em>script</em></code> with the value for each
|
|
key in <code><em>dictionaryName</em></code> 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 <code><em>dictionaryName</em></code>
|
|
unreadable will make the updates to the dictionary be discarded,
|
|
and this also happens if the contents of <code><em>dictionaryName</em></code> are
|
|
adjusted so that the chain of dictionaries no longer exists.
|
|
The result of <a href="#_dict"><strong><code>dict</code></strong></a> <code>with</code> 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><code>dict</code></strong></a> <code>with</code>;
|
|
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><code>dict</code></strong></a> <code>with</code> will continue to exist after the command finishes (unless
|
|
explicitly unset). Note that changes to the contents of <code><em>dictionaryName</em></code>
|
|
only happen when <code><em>script</em></code> terminates.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p><code><strong>dict for, values, incr, append, lappend, update, info, replace</strong></code> to be documented…</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_env">env</h3>
|
|
<div class="paragraph"><p><code><strong>env</strong> <em>?name? ?default?</em></code></p></div>
|
|
<div class="paragraph"><p>If <code><em>name</em></code> is supplied, returns the value of <code><em>name</em></code> from the initial
|
|
environment (see getenv(3)). An error is returned if <code><em>name</em></code> does not
|
|
exist in the environment, unless <code><em>default</em></code> 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 <code>{name value ...}</code></p></div>
|
|
<div class="paragraph"><p>See also the global variable <code>::env</code></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eof">eof</h3>
|
|
<div class="paragraph"><p><code><strong>eof</strong> <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>eof</strong></code></p></div>
|
|
<div class="paragraph"><p>Returns 1 if an end-of-file condition has occurred on <code><em>fileId</em></code>,
|
|
0 otherwise.</p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>,
|
|
or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> 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><code><strong>error</strong> <em>message ?stacktrace?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns a <code>JIM_ERR</code> code, which causes command interpretation to be
|
|
unwound. <code><em>message</em></code> is a string that is returned to the application
|
|
to indicate what went wrong.</p></div>
|
|
<div class="paragraph"><p>If the <code><em>stacktrace</em></code> 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><code>catch</code></strong></a> command:
|
|
if a caught error cannot be handled successfully, <code><em>stacktrace</em></code> can be used
|
|
to return a stack trace reflecting the original point of occurrence
|
|
of the error:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> catch {...} errMsg
|
|
...
|
|
error $errMsg [info stacktrace]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See also <code>errorInfo</code>, <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>, <a href="#_catch"><strong><code>catch</code></strong></a> and <a href="#_return"><strong><code>return</code></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_errorinfo">errorInfo</h3>
|
|
<div class="paragraph"><p><code><strong>errorInfo</strong> <em>error ?stacktrace?</em></code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> if {[catch {...} error]} {
|
|
puts stderr [errorInfo $error [info stacktrace]]
|
|
exit 1
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See also <a href="#_error"><strong><code>error</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_eval">eval</h3>
|
|
<div class="paragraph"><p><code><strong>eval</strong> <em>arg ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p><a href="#_eval"><strong><code>eval</code></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><code>eval</code></strong></a> concatenates all its arguments in the same
|
|
fashion as the <a href="#_concat"><strong><code>concat</code></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><code><strong>exec</strong> <em>arg ?arg...?</em></code></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;
|
|
<code>|</code> 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 <code>|&</code> for
|
|
both standard output and standard error).</p></div>
|
|
<div class="paragraph"><p>Under normal conditions the result of the <a href="#_exec"><strong><code>exec</code></strong></a> command
|
|
consists of the standard output produced by the last command
|
|
in the pipeline followed by the standard error output.</p></div>
|
|
<div class="paragraph"><p>If any of the commands writes to its standard error file,
|
|
then this will be included in the result after the standard output
|
|
of the last command.</p></div>
|
|
<div class="paragraph"><p>Note that unlike Tcl, data written to standard error does not cause
|
|
<a href="#_exec"><strong><code>exec</code></strong></a> to return an error.</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><code>exec</code></strong></a> will return an error.
|
|
If no standard error output was produced, or is redirected,
|
|
the error message will include the normal result, as above,
|
|
followed by error messages describing the abnormal terminations.</p></div>
|
|
<div class="paragraph"><p>If any standard error output was produced, these abnormal termination
|
|
messages are suppressed.</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 <code><em>arg</em></code> may have one of the following special forms:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code>>filename</code>
|
|
</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><code>exec</code></strong></a>
|
|
will normally return an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>>>filename</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>>@fileId</code>
|
|
</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><code>open</code></strong></a>). In this situation <a href="#_exec"><strong><code>exec</code></strong></a>
|
|
will normally return an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>2>filename</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard error of the last command in the pipeline
|
|
is redirected to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>2>>filename</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>2>@fileId</code>
|
|
</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">
|
|
<code>2>@1</code>
|
|
</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">
|
|
<code>>&filename</code>
|
|
</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">
|
|
<code>>>&filename</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As above, but append to the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><filename</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard input of the first command in the pipeline
|
|
is taken from the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><<string</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The standard input of the first command is taken as the
|
|
given immediate value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><@fileId</code>
|
|
</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 <code><em>arg</em></code> is <code>&</code> 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 <code><em>arg</em></code> becomes one word for a command, except for
|
|
<code>|</code>, <code><</code>, <code><<</code>, <code>></code>, and <code>&</code> arguments, and the
|
|
arguments that follow <code><</code>, <code><<</code>, and <code>></code>.</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><code>glob</code></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><code>catch</code></strong></a>) will be set to a list, as follows:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>CHILDKILLED</strong> <em>pid sigName msg</em></code>
|
|
</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">
|
|
<code><strong>CHILDSUSP</strong> <em>pid sigName msg</em></code>
|
|
</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">
|
|
<code><strong>CHILDSTATUS</strong> <em>pid code</em></code>
|
|
</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><code><strong>exists ?-var|-proc|-command|-alias?</strong> <em>name</em></code></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><code>info</code></strong></a> <code>exists</code>,
|
|
<a href="#_info"><strong><code>info</code></strong></a> <code>procs</code> and <a href="#_info"><strong><code>info</code></strong></a> <code>commands</code>.</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><code><strong>exit</strong> <em>?returnCode?</em></code></p></div>
|
|
<div class="paragraph"><p>Terminate the process, returning <code><em>returnCode</em></code> to the
|
|
parent as the exit status.</p></div>
|
|
<div class="paragraph"><p>If <code><em>returnCode</em></code> 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><code>catch</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_expr">expr</h3>
|
|
<div class="paragraph"><p><code><strong>expr</strong> <em>arg</em></code></p></div>
|
|
<div class="paragraph"><p>Calls the expression processor to evaluate <code><em>arg</em></code>, and returns
|
|
the result as a string. See the section <a href="#_expressions">EXPRESSIONS</a> above.</p></div>
|
|
<div class="paragraph"><p>Note that Jim supports a shorthand syntax for <a href="#_expr"><strong><code>expr</code></strong></a> as <code>$(...)</code>
|
|
The following two are identical.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set x [expr {3 * 2 + 1}]
|
|
set x $(3 * 2 + 1)</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_file">file</h3>
|
|
<div class="paragraph"><p><code><strong>file</strong> <em>option name ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p>Operate on a file or a file name. <code><em>name</em></code> is the name of a file.</p></div>
|
|
<div class="paragraph"><p><code><em>option</em></code> indicates what to do with the file name. Any unique
|
|
abbreviation for <code><em>option</em></code> is acceptable. The valid options are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>file atime</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a decimal string giving the time at which file <code><em>name</em></code>
|
|
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">
|
|
<code><strong>file copy ?-force?</strong> <em>source target</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Copies file <code><em>source</em></code> to file <code><em>target</em></code>. The source file must exist.
|
|
The target file must not exist, unless <code>-force</code> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file delete ?-force? ?--?</strong> <em>name...</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Deletes file or directory <code><em>name</em></code>. 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 <code>-force</code> options is given. In this case no errors will be generated, even
|
|
if the file/directory can’t be deleted. Use <code><em>--</em></code> if there is any possibility of
|
|
the first name being <code><em>-force</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file dirname</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <code><em>name</em></code> up to but not including
|
|
the last slash character. If there are no slashes in <code><em>name</em></code>
|
|
then return <code>.</code> (a single dot). If the last slash in <code><em>name</em></code> is its first
|
|
character, then return <code>/</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file executable</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is executable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file exists</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> exists and the current user has
|
|
search privileges for the directories leading to it, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file extension</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <code><em>name</em></code> after and including the
|
|
last dot in <code><em>name</em></code>. If there is no dot in <code><em>name</em></code> then return
|
|
the empty string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file isdirectory</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is a directory,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file isfile</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is a regular file,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file join</strong> <em>arg...</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Joins multiple path components. Note that if any components is
|
|
an absolute path, the preceding components are ignored.
|
|
Thus <code>"<a href="#_file"><strong><code>file</code></strong></a> join /tmp /root"</code> returns <code>"/root"</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file link</strong> ?<strong>-hard|-symbolic</strong>? <em>newname target</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates a hard link (default) or symbolic link from <code><em>newname</em></code> to <code><em>target</em></code>.
|
|
Note that the sense of this command is the opposite of <a href="#_file"><strong><code>file</code></strong></a> <code>rename</code> and <a href="#_file"><strong><code>file</code></strong></a> <code>copy</code>
|
|
and also of <code>ln</code>, but this is compatible with Tcl.
|
|
An error is returned if <code><em>target</em></code> doesn’t exist or <code><em>newname</em></code> already exists.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file lstat</strong> <em>name varName</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Same as <em>stat</em> option (see below) except uses the <code><em>lstat</em></code>
|
|
kernel call instead of <code><em>stat</em></code>. This means that if <code><em>name</em></code>
|
|
refers to a symbolic link the information returned in <code><em>varName</em></code>
|
|
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">
|
|
<code><strong>file mkdir</strong> <em>dir1 ?dir2...?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates each directory specified. For each pathname <code><em>dir</em></code> specified,
|
|
this command will create all non-existing parent directories
|
|
as well as <code><em>dir</em></code> 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">
|
|
<code><strong>file mtime</strong> <em>name ?time?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return a decimal string giving the time at which file <code><em>name</em></code>
|
|
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 <code><em>time</em></code> is given, sets the modification time
|
|
of the file to the given value.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file mtimeus</strong> <em>name ?time_us?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
As for <a href="#_file"><strong><code>file</code></strong></a> <code>mtime</code> except the time value is in microseconds
|
|
since the epoch (see also <a href="#_clock"><strong><code>clock</code></strong></a> <code>microseconds</code>).
|
|
Note that some platforms and some filesystems don’t support high
|
|
resolution timestamps for files.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file normalize</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return the normalized path of <code><em>name</em></code>. See <em>realpath(3)</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file owned</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is owned by the current user,
|
|
<em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file readable</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is readable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file readlink</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the value of the symbolic link given by <code><em>name</em></code> (i.e. the
|
|
name of the file it points to). If
|
|
<code><em>name</em></code> 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">
|
|
<code><strong>file rename</strong> ?<strong>-force</strong>? <em>oldname</em> <em>newname</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Renames the file from the old name to the new name.
|
|
If <code><em>newname</em></code> already exists, an error is returned unless <code><em>-force</em></code> is
|
|
specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file rootname</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <code><em>name</em></code> up to but not including
|
|
the last <em>.</em> character in the name. If <code><em>name</em></code> doesn’t contain
|
|
a dot, then return <code><em>name</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file split</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list whose elements are the path components in <code><em>name</em></code>.
|
|
The first element of the list will have the same path type as
|
|
<code><em>name</em></code>. All other elements will be relative. Path separators
|
|
will be discarded.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file stat</strong> <em>name ?varName?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invoke the <em>stat</em> kernel call on <code><em>name</em></code>, and return the result
|
|
as a dictionary with the following keys: <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>, <em>mtimeus</em> (if supported - see <a href="#_file"><strong><code>file</code></strong></a> <code>mtimeus</code>)
|
|
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><code>file</code></strong></a> <code>type</code>.
|
|
If <code><em>varName</em></code> is specified, it is taken to be the name of an array
|
|
variable and the values are also stored into the array.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file tail</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return all of the characters in <code><em>name</em></code> after the last slash.
|
|
If <code><em>name</em></code> contains no slashes then return <code><em>name</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file tempfile</strong> <em>?template?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates and returns the name of a unique temporary file. If <code><em>template</em></code> 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">
|
|
<code><strong>file type</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a string giving the type of file <code><em>name</em></code>, which will be
|
|
one of <code>file</code>, <code>directory</code>, <code>characterSpecial</code>,
|
|
<code>blockSpecial</code>, <code>fifo</code>, <code>link</code>, or <code>socket</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>file writable</strong> <em>name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Return <em>1</em> if file <code><em>name</em></code> is writable by
|
|
the current user, <em>0</em> otherwise.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The <a href="#_file"><strong><code>file</code></strong></a> commands that return 0/1 results are often used in
|
|
conditional or looping commands, for example:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> if {![file exists foo]} {
|
|
error {bad file name}
|
|
} else {
|
|
...
|
|
}</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_finalize">finalize</h3>
|
|
<div class="paragraph"><p><code><strong>finalize</strong> <em>reference ?command?</em></code></p></div>
|
|
<div class="paragraph"><p>If <code><em>command</em></code> 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. <code><em>command</em></code> 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><code>ref</code></strong></a>
|
|
command.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_flush">flush</h3>
|
|
<div class="paragraph"><p><code><strong>flush</strong> <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>flush</strong></code></p></div>
|
|
<div class="paragraph"><p>Flushes any output that has been buffered for <code><em>fileId</em></code>. <code><em>fileId</em></code> must
|
|
have been the return value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>, or it may be
|
|
<code>stdout</code> or <code>stderr</code> 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><code><strong>for</strong> <em>start test next body</em></code></p></div>
|
|
<div class="paragraph"><p><a href="#_for"><strong><code>for</code></strong></a> is a looping command, similar in structure to the C <a href="#_for"><strong><code>for</code></strong></a> statement.
|
|
The <code><em>start</em></code>, <code><em>next</em></code>, and <code><em>body</em></code> arguments must be Tcl command strings,
|
|
and <code><em>test</em></code> is an expression string.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_for"><strong><code>for</code></strong></a> command first invokes the Tcl interpreter to execute <code><em>start</em></code>.
|
|
Then it repeatedly evaluates <code><em>test</em></code> as an expression; if the result is
|
|
non-zero it invokes the Tcl interpreter on <code><em>body</em></code>, then invokes the Tcl
|
|
interpreter on <code><em>next</em></code>, then repeats the loop. The command terminates
|
|
when <code><em>test</em></code> evaluates to 0.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_continue"><strong><code>continue</code></strong></a> command is invoked within <code><em>body</em></code> then any remaining
|
|
commands in the current execution of <code><em>body</em></code> are skipped; processing
|
|
continues by invoking the Tcl interpreter on <code><em>next</em></code>, then evaluating
|
|
<code><em>test</em></code>, and so on.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_break"><strong><code>break</code></strong></a> command is invoked within <code><em>body</em></code> or <code><em>next</em></code>, then the <a href="#_for"><strong><code>for</code></strong></a>
|
|
command will return immediately.</p></div>
|
|
<div class="paragraph"><p>The operation of <a href="#_break"><strong><code>break</code></strong></a> and <a href="#_continue"><strong><code>continue</code></strong></a> are similar to the corresponding
|
|
statements in C.</p></div>
|
|
<div class="paragraph"><p><a href="#_for"><strong><code>for</code></strong></a> returns an empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_foreach">foreach</h3>
|
|
<div class="paragraph"><p><code><strong>foreach</strong> <em>varName list body</em></code></p></div>
|
|
<div class="paragraph"><p><code><strong>foreach</strong> <em>varList list ?varList2 list2 ...? body</em></code></p></div>
|
|
<div class="paragraph"><p>In this command, <code><em>varName</em></code> is the name of a variable, <code><em>list</em></code>
|
|
is a list of values to assign to <code><em>varName</em></code>, and <code><em>body</em></code> is a
|
|
collection of Tcl commands.</p></div>
|
|
<div class="paragraph"><p>For each field in <code><em>list</em></code> (in order from left to right), <a href="#_foreach"><strong><code>foreach</code></strong></a> assigns
|
|
the contents of the field to <code><em>varName</em></code> (as if the <a href="#_lindex"><strong><code>lindex</code></strong></a> command
|
|
had been used to extract the field), then calls the Tcl interpreter to
|
|
execute <code><em>body</em></code>.</p></div>
|
|
<div class="paragraph"><p>If instead of being a simple name, <code><em>varList</em></code> is used, multiple assignments
|
|
are made each time through the loop, one for each element of <code><em>varList</em></code>.</p></div>
|
|
<div class="paragraph"><p>For example, if there are two elements in <code><em>varList</em></code> 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 <code><em>varList</em></code>, 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><code>break</code></strong></a> and <a href="#_continue"><strong><code>continue</code></strong></a> statements may be invoked inside <code><em>body</em></code>,
|
|
with the same effect as in the <a href="#_for"><strong><code>for</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p><a href="#_foreach"><strong><code>foreach</code></strong></a> returns an empty string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_format">format</h3>
|
|
<div class="paragraph"><p><code><strong>format</strong> <em>formatString ?arg ...?</em></code></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). <code><em>formatString</em></code> indicates how to format
|
|
the result, using <code>%</code> 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 <code><em>arg</em></code> must match the expected type
|
|
from the <code>%</code> field in <code><em>formatString</em></code>; the <a href="#_format"><strong><code>format</code></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 <code>%c</code>; in this case the argument
|
|
must be a decimal string, which will then be converted to the corresponding
|
|
ASCII (or UTF-8) character value.</p></div>
|
|
<div class="paragraph"><p>In addition, Jim Tcl provides basic support for conversion to binary with <code>%b</code>.</p></div>
|
|
<div class="paragraph"><p><a href="#_format"><strong><code>format</code></strong></a> does backslash substitution on its <code><em>formatString</em></code>
|
|
argument, so backslash sequences in <code><em>formatString</em></code> 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><code>format</code></strong></a> is the formatted string.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_getref">getref</h3>
|
|
<div class="paragraph"><p><code><strong>getref</strong> <em>reference</em></code></p></div>
|
|
<div class="paragraph"><p>Returns the string associated with <code><em>reference</em></code>. The reference must
|
|
be a valid reference create with the <a href="#_ref"><strong><code>ref</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_gets">gets</h3>
|
|
<div class="paragraph"><p><code><strong>gets</strong> <em>fileId ?varName?</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>gets</strong> <em>?varName?</em></code></p></div>
|
|
<div class="paragraph"><p>Reads the next line from the file given by <code><em>fileId</em></code> and discards
|
|
the terminating newline character.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> 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 <code><em>varName</em></code> is set to an
|
|
empty string.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> 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><code>eof</code></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><code>gets</code></strong></a> behaves as if there were an additional newline character
|
|
at the end of the file.</p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em></code> must be <code>stdin</code> or the return value from a previous
|
|
call to <a href="#_open"><strong><code>open</code></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><code><strong>glob</strong> ?<strong>-nocomplain</strong>? ?<strong>-directory</strong> <em>dir</em>? ?<strong>-tails</strong>? ?<strong>--</strong>? <em>pattern ?pattern ...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command performs filename globbing, using csh rules. The returned
|
|
value from <a href="#_glob"><strong><code>glob</code></strong></a> is the list of expanded filenames.</p></div>
|
|
<div class="paragraph"><p>If <code>-nocomplain</code> 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 <code>-nocomplain</code> argument must be provided
|
|
exactly: an abbreviation will not be accepted.</p></div>
|
|
<div class="paragraph"><p>If <code>-directory</code> is given, the <code><em>dir</em></code> is understood to contain a
|
|
directory name to search in. This allows globbing inside directories
|
|
whose names may contain glob-sensitive characters. The returned names
|
|
include the directory name unless <code><em>-tails</em></code> is specified.</p></div>
|
|
<div class="paragraph"><p>If <code><em>-tails</em></code> is specified, along with <code>-directory</code>, the returned names
|
|
are relative to the given directory.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_global">global</h3>
|
|
<div class="paragraph"><p><code><strong>global</strong> <em>varName ?varName ...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command is ignored unless a Tcl procedure is being interpreted.
|
|
If so, then it declares each given <code><em>varName</em></code> 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
|
|
<code><em>varName</em></code> 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><code>global</code></strong></a> is to use the <code>::</code> 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><code><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>?</code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_if"><strong><code>if</code></strong></a> command evaluates <code><em>expr1</em></code> as an expression (in the same way
|
|
that <a href="#_expr"><strong><code>expr</code></strong></a> evaluates its argument). The value of the expression must
|
|
be numeric; if it is non-zero then <code><em>body1</em></code> is executed by passing it to
|
|
the Tcl interpreter.</p></div>
|
|
<div class="paragraph"><p>Otherwise <code><em>expr2</em></code> is evaluated as an expression and if it is non-zero
|
|
then <code><em>body2</em></code> is executed, and so on.</p></div>
|
|
<div class="paragraph"><p>If none of the expressions evaluates to non-zero then <code><em>bodyN</em></code> is executed.</p></div>
|
|
<div class="paragraph"><p>The <code>then</code> and <code>else</code> arguments are optional "noise words" to make the
|
|
command easier to read.</p></div>
|
|
<div class="paragraph"><p>There may be any number of <code>elseif</code> clauses, including zero. <code><em>bodyN</em></code>
|
|
may also be omitted as long as <code>else</code> 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 <code><em>bodyN</em></code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_incr">incr</h3>
|
|
<div class="paragraph"><p><code><strong>incr</strong> <em>varName ?increment?</em></code></p></div>
|
|
<div class="paragraph"><p>Increment the value stored in the variable whose name is <code><em>varName</em></code>.
|
|
The value of the variable must be integral.</p></div>
|
|
<div class="paragraph"><p>If <code><em>increment</em></code> is supplied then its value (which must be an
|
|
integer) is added to the value of variable <code><em>varName</em></code>; otherwise
|
|
1 is added to <code><em>varName</em></code>.</p></div>
|
|
<div class="paragraph"><p>The new value is stored as a decimal string in variable <code><em>varName</em></code>
|
|
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 <code>0</code> first.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_info">info</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>info</strong> <em>option ?arg...?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Provide information about various internals to the Tcl interpreter.
|
|
The legal <code><em>option</em></code>'s (which may be abbreviated) are:
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info args</strong> <em>procname</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list containing the names of the arguments to procedure
|
|
<code><em>procname</em></code>, in order. <code><em>procname</em></code> must be the name of a
|
|
Tcl command procedure.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info alias</strong> <em>command</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code><em>command</em></code> must be an alias created with <a href="#_alias"><strong><code>alias</code></strong></a>. In which case the target
|
|
command and arguments, as passed to <a href="#_alias"><strong><code>alias</code></strong></a> are returned. See <a href="#_exists"><strong><code>exists</code></strong></a> <code>-alias</code>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info body</strong> <em>procname</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the body of procedure <code><em>procname</em></code>. <code><em>procname</em></code> must be
|
|
the name of a Tcl command procedure.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info channels</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all open file handles from <a href="#_open"><strong><code>open</code></strong></a> or <a href="#_socket"><strong><code>socket</code></strong></a>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info commands</strong> ?<em>pattern</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>pattern</em></code> 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><code>proc</code></strong></a> command.
|
|
If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules) are returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info complete</strong> <em>command</em> ?<em>missing</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if <code><em>command</em></code> 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 <code><em>varName</em></code> is specified, the
|
|
missing character is stored in the variable with that name.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info exists</strong> <em>varName</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns <em>1</em> if the variable named <code><em>varName</em></code> exists in the
|
|
current context (either as a global or local variable), returns <em>0</em>
|
|
otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info frame</strong> ?<em>number</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>number</em></code> is not specified, this command returns a number
|
|
which is the same result as <a href="#_info"><strong><code>info</code></strong></a> <code>level</code> - the current stack frame level.
|
|
If <code><em>number</em></code> is specified, then the result is a list consisting of the procedure,
|
|
filename and line number for the procedure call at level <code><em>number</em></code> on the stack.
|
|
If <code><em>number</em></code> 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><code>info</code></strong></a> <code>level</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info globals</strong> ?<em>pattern</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>pattern</em></code> isn’t specified, returns a list of all the names
|
|
of currently-defined global variables.
|
|
If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules) are returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info hostname</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
An alias for <a href="#cmd_1"><strong><code>os.gethostname</code></strong></a> for compatibility with Tcl 6.x
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info level</strong> ?<em>number</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>number</em></code> 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 <code><em>number</em></code> is specified,
|
|
then the result is a list consisting of the name and arguments for the
|
|
procedure call at level <code><em>number</em></code> on the stack. If <code><em>number</em></code>
|
|
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><code>uplevel</code></strong></a> command for more information on what stack
|
|
levels mean.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info locals</strong> ?<em>pattern</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>pattern</em></code> 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><code>global</code></strong></a>
|
|
and <a href="#_upvar"><strong><code>upvar</code></strong></a> commands will not be returned. If <code><em>pattern</em></code> is
|
|
specified, only those names matching <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules) are returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info nameofexecutable</strong></code>
|
|
</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">
|
|
<code><strong>info procs</strong> ?<em>pattern</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>pattern</em></code> isn’t specified, returns a list of all the
|
|
names of Tcl command procedures.
|
|
If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules) are returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info references</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all references which have not yet been garbage
|
|
collected.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info returncodes</strong> ?<em>code</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list representing the mapping of standard return codes
|
|
to names. e.g. <code>{0 ok 1 error 2 return ...}</code>. If a code is given,
|
|
instead returns the name for the given code.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info script</strong></code>
|
|
</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><code>source</code></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">
|
|
<code><strong>info source</strong> <em>script ?filename line?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
With a single argument, returns the original source location of the given script as a list of
|
|
<code>{filename linenumber}</code>. If the source location can’t be determined, the
|
|
list <code>{{} 0}</code> is returned. If <code><em>filename</em></code> and <code><em>line</em></code> are given, returns a copy
|
|
of <code><em>script</em></code> with the associate source information. This can be useful to produce
|
|
useful messages from <a href="#_eval"><strong><code>eval</code></strong></a>, etc. if the original source information may be lost.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info stacktrace</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
After an error is caught with <a href="#_catch"><strong><code>catch</code></strong></a>, returns the stack trace as a list
|
|
of <code>{procedure filename line ...}</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info statics</strong> <em>procname</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a dictionary of the static variables of procedure
|
|
<code><em>procname</em></code>. <code><em>procname</em></code> 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">
|
|
<code><strong>info version</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the version number for this version of Jim in the form <code><strong>x.yy</strong></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>info vars</strong> ?<em>pattern</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>pattern</em></code> isn’t specified,
|
|
returns a list of all the names of currently-visible variables, including
|
|
both locals and currently-visible globals.
|
|
If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
|
|
(using <a href="#_string_matching">STRING MATCHING</a> rules) are returned.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_join">join</h3>
|
|
<div class="paragraph"><p><code><strong>join</strong> <em>list ?joinString?</em></code></p></div>
|
|
<div class="paragraph"><p>The <code><em>list</em></code> argument must be a valid Tcl list. This command returns the
|
|
string formed by joining all of the elements of <code><em>list</em></code> together with
|
|
<code><em>joinString</em></code> separating each adjacent pair of elements.</p></div>
|
|
<div class="paragraph"><p>The <code><em>joinString</em></code> argument defaults to a space character.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_kill">kill</h3>
|
|
<div class="paragraph"><p><code><strong>kill</strong> ?<em>SIG</em>|<strong>-0</strong>? <em>pid</em></code></p></div>
|
|
<div class="paragraph"><p>Sends the given signal to the process identified by <code><em>pid</em></code>.</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>
|
|
<code>TERM</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code>SIGTERM</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code>-TERM</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code>15</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code>-15</code>
|
|
</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 <code>-0</code> simply checks that a signal <code><em>could</em></code> 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">lambda</h3>
|
|
<div class="paragraph"><p><code><strong>lambda</strong> <em>args ?statics? body</em></code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_lambda"><strong><code>lambda</code></strong></a> command is identical to <a href="#_proc"><strong><code>proc</code></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><code>proc</code></strong></a> and <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lappend">lappend</h3>
|
|
<div class="paragraph"><p><code><strong>lappend</strong> <em>varName value ?value value ...?</em></code></p></div>
|
|
<div class="paragraph"><p>Treat the variable given by <code><em>varName</em></code> as a list and append each of
|
|
the <code><em>value</em></code> arguments to that list as a separate element, with spaces
|
|
between elements.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> doesn’t exist, it is created as a list with elements given
|
|
by the <code><em>value</em></code> arguments. <a href="#_lappend"><strong><code>lappend</code></strong></a> is similar to <a href="#_append"><strong><code>append</code></strong></a> except that
|
|
each <code><em>value</em></code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> lappend a $b</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>is much more efficient than</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a [concat $a [list $b]]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>when <code>$a</code> is long.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lassign">lassign</h3>
|
|
<div class="paragraph"><p><code><strong>lassign</strong> <em>list varName ?varName ...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command treats the value <code><em>list</em></code> as a list and assigns successive elements from that list to
|
|
the variables given by the <code><em>varName</em></code> arguments in order. If there are more variable names than
|
|
list elements, the remaining variables are set to the empty string. If there are more list elements
|
|
than variables, a list of unassigned elements is returned.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . lassign {1 2 3} a b; puts a=$a,b=$b
|
|
3
|
|
a=1,b=2</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_local">local</h3>
|
|
<div class="paragraph"><p><code><strong>local</strong> <em>cmd ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p>First, <a href="#_local"><strong><code>local</code></strong></a> evaluates <code><em>cmd</em></code> with the given arguments. The return value must
|
|
be the name of an existing command, which is then 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><code>lambda</code></strong></a>, local procedures or
|
|
to automatically close a filehandle.</p></div>
|
|
<div class="paragraph"><p>In addition, if a the command already exists with the same name,
|
|
the existing command will be kept rather than being deleted, and may be called
|
|
via <a href="#_upcall"><strong><code>upcall</code></strong></a>. The previous command will be restored when the current
|
|
procedure exits. See <a href="#_upcall"><strong><code>upcall</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> proc outer {} {
|
|
# proc ... returns "inner" which is marked local
|
|
local proc inner {} {
|
|
# will be deleted when 'outer' exits
|
|
}
|
|
|
|
inner
|
|
...
|
|
}</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> proc outer {} {
|
|
set x [lambda inner {args} {
|
|
# will be deleted when 'outer' exits
|
|
}]
|
|
# Use 'function' here which simply returns $x
|
|
local function $x
|
|
|
|
$x ...
|
|
...
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Also see <a href="#_defer"><strong><code>defer</code></strong></a> as another mechanism for cleaning up at the end of a procedure.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_loop">loop</h3>
|
|
<div class="paragraph"><p><code><strong>loop</strong> <em>var first limit ?incr? body</em></code></p></div>
|
|
<div class="paragraph"><p>Similar to <a href="#_for"><strong><code>for</code></strong></a> except simpler and possibly more efficient.
|
|
If <code><em>incr</em></code> is positive, the effect is, equivalent to:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> for {set var $first} {$var < $limit} {incr var $incr} $body</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>While if <code><em>incr</em></code> is negative, the count is downwards.</p></div>
|
|
<div class="paragraph"><p>If <code><em>incr</em></code> 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><code><strong>lindex</strong> <em>list ?index …?</em></code></p></div>
|
|
<div class="paragraph"><p>Treats <code><em>list</em></code> as a Tcl list and returns element <code><em>index</em></code> from it
|
|
(0 refers to the first element of the list).
|
|
See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>index</em></code>.</p></div>
|
|
<div class="paragraph"><p>In extracting the element, <code><em>lindex</em></code> 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 no index values are given, simply returns <code><em>list</em></code></p></div>
|
|
<div class="paragraph"><p>If <code><em>index</em></code> is negative or greater than or equal to the number of elements
|
|
in <code><em>list</em></code>, then an empty string is returned.</p></div>
|
|
<div class="paragraph"><p>If additional index arguments are supplied, then each argument is
|
|
used in turn to select an element from the previous indexing
|
|
operation, allowing the script to select elements from sublists.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_linsert">linsert</h3>
|
|
<div class="paragraph"><p><code><strong>linsert</strong> <em>list index element ?element element ...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command produces a new list from <code><em>list</em></code> by inserting all
|
|
of the <code><em>element</em></code> arguments just before the element <code><em>index</em></code>
|
|
of <code><em>list</em></code>. Each <code><em>element</em></code> argument will become
|
|
a separate element of the new list. If <code><em>index</em></code> is less than
|
|
or equal to zero, then the new elements are inserted at the
|
|
beginning of the list. If <code><em>index</em></code> 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 <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>index</em></code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_list">list</h3>
|
|
<div class="paragraph"><p><code><strong>list</strong> <em>arg ?arg ...?</em></code></p></div>
|
|
<div class="paragraph"><p>This command returns a list comprised of all the arguments, <code><em>arg</em></code>. Braces
|
|
and backslashes get added as necessary, so that the <a href="#_lindex"><strong><code>lindex</code></strong></a> command
|
|
may be used on the result to re-extract the original arguments, and also
|
|
so that <a href="#_eval"><strong><code>eval</code></strong></a> may be used to execute the resulting list, with
|
|
<code><em>arg1</em></code> comprising the command’s name and the other args comprising
|
|
its arguments. <a href="#_list"><strong><code>list</code></strong></a> produces slightly different results than
|
|
<a href="#_concat"><strong><code>concat</code></strong></a>: <a href="#_concat"><strong><code>concat</code></strong></a> removes one level of grouping before forming
|
|
the list, while <a href="#_list"><strong><code>list</code></strong></a> works directly from the original arguments.
|
|
For example, the command</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> list a b {c d e} {f {g h}}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> a b {c d e} {f {g h}}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>while <a href="#_concat"><strong><code>concat</code></strong></a> with the same arguments will return</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> a b c d e f {g h}</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_llength">llength</h3>
|
|
<div class="paragraph"><p><code><strong>llength</strong> <em>list</em></code></p></div>
|
|
<div class="paragraph"><p>Treats <code><em>list</em></code> as a list and returns the number of elements in that list.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lset">lset</h3>
|
|
<div class="paragraph"><p><code><strong>lset</strong> <em>varName ?index ..? newValue</em></code></p></div>
|
|
<div class="paragraph"><p>Sets an element in a list.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_lset"><strong><code>lset</code></strong></a> command accepts a parameter, <code><em>varName</em></code>, 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 <code><em>varName</em></code>. If no indices are presented, the command
|
|
takes the form:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> lset varName newValue</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>In this case, newValue replaces the old value of the variable
|
|
<code><em>varName</em></code>.</p></div>
|
|
<div class="paragraph"><p>When presented with a single index, the <a href="#_lset"><strong><code>lset</code></strong></a> command
|
|
treats the content of the <code><em>varName</em></code> 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><code>lset</code></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 <code><em>varName</em></code>, and is also the return value from
|
|
the <a href="#_lset"><strong><code>lset</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If index is negative or greater than or equal to the number of
|
|
elements in <code>$varName</code>, then an error occurs.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>index</em></code>.</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> lset a 1 2 newValue</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>replaces element 2 of sublist 1 with <code><em>newValue</em></code>.</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><code>lset</code></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><code><strong>lmap</strong> <em>varName list body</em></code></p></div>
|
|
<div class="paragraph"><p><code><strong>lmap</strong> <em>varList list ?varList2 list2 ...? body</em></code></p></div>
|
|
<div class="paragraph"><p><a href="#_lmap"><strong><code>lmap</code></strong></a> is a "collecting" <a href="#_foreach"><strong><code>foreach</code></strong></a> which returns a list of its results.</p></div>
|
|
<div class="paragraph"><p>For example:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . lmap i {1 2 3 4 5} {expr $i*$i}
|
|
1 4 9 16 25
|
|
. lmap a {1 2 3} b {A B C} {list $a $b}
|
|
{1 A} {2 B} {3 C}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If the body invokes <a href="#_continue"><strong><code>continue</code></strong></a>, no value is added for this iteration.
|
|
If the body invokes <a href="#_break"><strong><code>break</code></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><code><strong>load</strong> <em>filename</em></code></p></div>
|
|
<div class="paragraph"><p>Loads the dynamic extension, <code><em>filename</em></code>. Generally the filename should have
|
|
the extension <code>.so</code>. The initialisation function for the module must be based
|
|
on the name of the file. For example loading <code>hwaccess.so</code> will invoke
|
|
the initialisation function, <code>Jim_hwaccessInit</code>. Normally the <a href="#_load"><strong><code>load</code></strong></a> command
|
|
should not be used directly. Instead it is invoked automatically by <a href="#_package"><strong><code>package</code></strong></a> <code>require</code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lrange">lrange</h3>
|
|
<div class="paragraph"><p><code><strong>lrange</strong> <em>list first last</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>list</em></code> must be a valid Tcl list. This command will return a new
|
|
list consisting of elements <code><em>first</em></code> through <code><em>last</em></code>, inclusive.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>last</em></code> is greater than or equal to the number of elements
|
|
in the list, then it is treated as if it were <code>end</code>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>first</em></code> is greater than <code><em>last</em></code> then an empty string
|
|
is returned.</p></div>
|
|
<div class="paragraph"><p>Note: <code>"<a href="#_lrange"><strong><code>lrange</code></strong></a> <em>list first first</em>"</code> does not always produce the
|
|
same result as <code>"<a href="#_lindex"><strong><code>lindex</code></strong></a> <em>list first</em>"</code> (although it often does
|
|
for simple fields that aren’t enclosed in braces); it does, however,
|
|
produce exactly the same results as <code>"<a href="#_list"><strong><code>list</code></strong></a> [<a href="#_lindex"><strong><code>lindex</code></strong></a> <em>list first</em>]"</code></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lreplace">lreplace</h3>
|
|
<div class="paragraph"><p><code><strong>lreplace</strong> <em>list first last ?element element ...?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns a new list formed by replacing one or more elements of
|
|
<code><em>list</em></code> with the <code><em>element</em></code> arguments.</p></div>
|
|
<div class="paragraph"><p><code><em>first</em></code> gives the index in <code><em>list</em></code> of the first element
|
|
to be replaced.</p></div>
|
|
<div class="paragraph"><p>If <code><em>first</em></code> is less than zero then it refers to the first
|
|
element of <code><em>list</em></code>; the element indicated by <code><em>first</em></code>
|
|
must exist in the list.</p></div>
|
|
<div class="paragraph"><p><code><em>last</em></code> gives the index in <code><em>list</em></code> of the last element
|
|
to be replaced; it must be greater than or equal to <code><em>first</em></code>.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.</p></div>
|
|
<div class="paragraph"><p>The <code><em>element</em></code> 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 <code><em>element</em></code> argument will become a separate element of
|
|
the list.</p></div>
|
|
<div class="paragraph"><p>If no <code><em>element</em></code> arguments are specified, then the elements
|
|
between <code><em>first</em></code> and <code><em>last</em></code> are simply deleted.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lrepeat">lrepeat</h3>
|
|
<div class="paragraph"><p><code><strong>lrepeat</strong> <em>number element1 ?element2 ...?</em></code></p></div>
|
|
<div class="paragraph"><p>Build a list by repeating elements <code><em>number</em></code> times (which must be
|
|
a positive integer).</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . lrepeat 3 a b
|
|
a b a b a b</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lreverse">lreverse</h3>
|
|
<div class="paragraph"><p><code><strong>lreverse</strong> <em>list</em></code></p></div>
|
|
<div class="paragraph"><p>Returns the list in reverse order.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . lreverse {1 2 3}
|
|
3 2 1</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_lsearch">lsearch</h3>
|
|
<div class="paragraph"><p><code><strong>lsearch</strong> <em>?options? list pattern</em></code></p></div>
|
|
<div class="paragraph"><p>This command searches the elements <code><em>list</em></code> to see if one of them matches <code><em>pattern</em></code>. If so, the
|
|
command returns the index of the first matching element (unless the options <code>-all</code>, <code>-inline</code> or <code>-bool</code> 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 <code>-exact</code> rather than <code>-glob</code>.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>-exact</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code><em>pattern</em></code> is a literal string that is compared for exact equality against each list element.
|
|
This is the default.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-glob</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code><em>pattern</em></code> is a glob-style pattern which is matched against each list element using
|
|
<a href="#_string_matching">STRING MATCHING</a> rules.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-regexp</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code><em>pattern</em></code> is treated as a regular expression and matched against each list element using
|
|
<a href="#_regular_expressions">REGULAR EXPRESSIONS</a> rules.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-command</strong> <em>cmdname</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code><em>cmdname</em></code> is a command which is used to match the pattern against each element of the
|
|
list. It is invoked as <code><em>cmdname</em> ?<strong>-nocase</strong>? <em>pattern listvalue</em></code> and should return 1
|
|
for a match, or 0 for no match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-all</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Changes the result to be the list of all matching indices (or all matching values if
|
|
<code>-inline</code> 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">
|
|
<code><strong>-inline</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The matching value is returned instead of its index (or an empty string if no value
|
|
matches). If <code>-all</code> is also specified, then the result of the command is the list of all
|
|
values that matched. The <code>-inline</code> and <code>-bool</code> options are mutually exclusive.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-bool</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Changes the result to <em>1</em> if a match was found, or <em>0</em> otherwise. If <code>-all</code> 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 <code>-inline</code> and <code>-bool</code> options are mutually exclusive.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-not</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This negates the sense of the match, returning the index (or value
|
|
if <code>-inline</code> is specified) of the first non-matching value in the
|
|
list. If <code>-bool</code> is also specified, the <em>0</em> will be returned if a
|
|
match is found, or <em>1</em> otherwise. If <code>-all</code> is also specified,
|
|
non-matches will be returned rather than matches.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-nocase</strong></code>
|
|
</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><code><strong>lsort</strong> ?<strong>-index</strong> <em>listindex</em>? ?<strong>-nocase|-integer|-real|-command</strong> <em>cmdname</em>? ?<strong>-unique</strong>? ?<strong>-decreasing</strong>|<strong>-increasing</strong>? <em>list</em></code></p></div>
|
|
<div class="paragraph"><p>Sort the elements of <code><em>list</em></code>, returning a new list in sorted order.
|
|
By default, ASCII (or UTF-8) sorting is used, with the result in increasing order.</p></div>
|
|
<div class="paragraph"><p>If <code>-nocase</code> is specified, comparisons are case-insensitive.</p></div>
|
|
<div class="paragraph"><p>If <code>-integer</code> is specified, numeric sorting is used.</p></div>
|
|
<div class="paragraph"><p>If <code>-real</code> is specified, floating point number sorting is used.</p></div>
|
|
<div class="paragraph"><p>If <code>-command <em>cmdname</em></code> is specified, <code><em>cmdname</em></code> is treated as a command
|
|
name. For each comparison, <code><em>cmdname $value1 $value2</code></em> is called which
|
|
should compare the values and return an integer less than, equal
|
|
to, or greater than zero if the <code><em>$value1</em></code> is to be considered less
|
|
than, equal to, or greater than <code><em>$value2</em></code>, respectively.</p></div>
|
|
<div class="paragraph"><p>If <code>-decreasing</code> is specified, the resulting list is in the opposite
|
|
order to what it would be otherwise. <code>-increasing</code> is the default.</p></div>
|
|
<div class="paragraph"><p>If <code>-unique</code> is specified, then only the last set of duplicate elements found in the list will be retained.
|
|
Note that duplicates are determined relative to the comparison used in the sort. Thus if <code>-index 0</code> is used,
|
|
<code>{1 a}</code> and <code>{1 b}</code> would be considered duplicates and only the second element, <code>{1 b}</code>, would be retained.</p></div>
|
|
<div class="paragraph"><p>If <code>-index <em>listindex</em></code> 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 <code>1</code>, <code>end</code> or <code>end-2</code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_defer">defer</h3>
|
|
<div class="paragraph"><p><code><strong>defer</strong> <em>script</em></code></p></div>
|
|
<div class="paragraph"><p>This command is a simple helper command to add a script to the <em><code>$jim::defer</code></em> variable
|
|
that will run when the current proc or interpreter exits. For example:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . proc a {} { defer {puts "Leaving a"}; puts "Exit" }
|
|
. a
|
|
Exit
|
|
Leaving a</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>If the <em><code>$jim::defer</code></em> variable exists, it is treated as a list of scripts to run
|
|
when the proc or interpreter exits.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_open">open</h3>
|
|
<div class="paragraph"><p><code><strong>open</strong> <em>fileName ?access?</em></code></p></div>
|
|
<div class="paragraph"><p><code><strong>open</strong> <em>|command-pipeline ?access?</em></code></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><code>read</code></strong></a>, <a href="#_puts"><strong><code>puts</code></strong></a>, and <a href="#_close"><strong><code>close</code></strong></a>.
|
|
<code><em>fileName</em></code> gives the name of the file to open.</p></div>
|
|
<div class="paragraph"><p>The <code><em>access</em></code> 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">
|
|
<code>r</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for reading only; the file must already exist.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>r</code>+
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Open the file for both reading and writing; the file must
|
|
already exist.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>w</code>
|
|
</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">
|
|
<code>w</code>+
|
|
</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">
|
|
<code>a</code>
|
|
</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">
|
|
<code>a</code>+
|
|
</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><code><em>access</em></code> 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><code>seek</code></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 <code><em>fileName</em></code> is "|" then the remaining
|
|
characters of <code><em>fileName</em></code> 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 <code><em>access</em></code>. If write-only
|
|
access is used (e.g. <code><em>access</em></code> 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. <code><em>access</em></code> 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><code>pid</code></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><code>socket</code></strong></a>, <a href="#_pid"><strong><code>pid</code></strong></a>, <a href="#_exec"><strong><code>exec</code></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_package">package</h3>
|
|
<div class="paragraph"><p><code><strong>package provide</strong> <em>name ?version?</em></code></p></div>
|
|
<div class="paragraph"><p>Indicates that the current script provides the package named <code><em>name</em></code>.
|
|
<strong>Note</strong>: The supplied version is ignored. All packages are registered as version 1.0
|
|
(it is simply accepted for compatibility purposes).</p></div>
|
|
<div class="paragraph"><p>Any script that provides a package may include this statement
|
|
as the first statement, although it is not required.</p></div>
|
|
<div class="paragraph"><p><code><strong>package require</strong> <em>name ?version?</em></code></p></div>
|
|
<div class="paragraph"><p>Searches for the package with the given <code><em>name</em></code> 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 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><code>load</code></strong></a> command,
|
|
otherwise if <em>$name.tcl</em> exists it is loaded with the <a href="#_source"><strong><code>source</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If <a href="#_load"><strong><code>load</code></strong></a> or <a href="#_source"><strong><code>source</code></strong></a> fails, <a href="#_package"><strong><code>package</code></strong></a> <code>require</code> will fail immediately.
|
|
No further attempt will be made to locate the file.</p></div>
|
|
<div class="paragraph"><p><code><strong>package names</strong></code></p></div>
|
|
<div class="paragraph"><p>Returns a list of all known/loaded packages, including internal packages.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_pid">pid</h3>
|
|
<div class="paragraph"><p><code><strong>pid</strong></code></p></div>
|
|
<div class="paragraph"><p><code><strong>pid</strong> <em>fileId</em></code></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><code>open</code></strong></a> and returns a list
|
|
of the process ids forming the pipeline in the same form as <a href="#_exec"><strong><code>exec</code></strong></a> <code>... &</code>.
|
|
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><code>open</code></strong></a>, <a href="#_exec"><strong><code>exec</code></strong></a></p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_proc">proc</h3>
|
|
<div class="paragraph"><p><code><strong>proc</strong> <em>name args ?statics? body</em></code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_proc"><strong><code>proc</code></strong></a> command creates a new Tcl command procedure, <code><em>name</em></code>.
|
|
When the new command is invoked, the contents of <code><em>body</em></code> will be executed.
|
|
Tcl interpreter. <code><em>args</em></code> specifies the formal arguments to the procedure.
|
|
If specified, <code><em>statics</em></code>, declares static variables which are bound to the
|
|
procedure.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_procedures">PROCEDURES</a> for detailed information about Tcl procedures.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_proc"><strong><code>proc</code></strong></a> command returns <code><em>name</em></code> (which is useful with <a href="#_local"><strong><code>local</code></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><code>return</code></strong></a> command. If the procedure doesn’t
|
|
execute an explicit <a href="#_return"><strong><code>return</code></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><code><strong>puts</strong> ?<strong>-nonewline</strong>? <em>?fileId? string</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>puts</strong> ?<strong>-nonewline</strong>? <em>string</em></code></p></div>
|
|
<div class="paragraph"><p>Writes the characters given by <code><em>string</em></code> to the file given
|
|
by <code><em>fileId</em></code>. <code><em>fileId</em></code> must have been the return
|
|
value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>, or it may be
|
|
<code>stdout</code> or <code>stderr</code> 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 <code><em>fileId</em></code> is specified then it defaults to <code>stdout</code>.
|
|
<a href="#_puts"><strong><code>puts</code></strong></a> normally outputs a newline character after <code><em>string</em></code>,
|
|
but this feature may be suppressed by specifying the <code>-nonewline</code>
|
|
switch.</p></div>
|
|
<div class="paragraph"><p>Output to files is buffered internally by Tcl; the <a href="#_flush"><strong><code>flush</code></strong></a>
|
|
command may be used to force buffered characters to be output.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_pipe">pipe</h3>
|
|
<div class="paragraph"><p>Creates a pair of <a href="#_aio"><strong><code>aio</code></strong></a> channels and returns the handles as a list: <code>{read write}</code></p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> lassign [pipe] r w
|
|
|
|
# Must close $w after exec
|
|
exec ps >@$w &
|
|
$w close
|
|
|
|
$r readable ...</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_pwd">pwd</h3>
|
|
<div class="paragraph"><p><code><strong>pwd</strong></code></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><code><strong>rand</strong> <em>?min? ?max?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns a random integer between <code><em>min</em></code> (defaults to 0) and <code><em>max</em></code>
|
|
(defaults to the maximum integer).</p></div>
|
|
<div class="paragraph"><p>If only one argument is given, it is interpreted as <code><em>max</em></code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_range">range</h3>
|
|
<div class="paragraph"><p><code><strong>range</strong> <em>?start? end ?step?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns a list of integers starting at <code><em>start</em></code> (defaults to 0)
|
|
and ranging up to but not including <code><em>end</em></code> in steps of <code><em>step</em></code> defaults to 1).</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . range 5
|
|
0 1 2 3 4
|
|
. range 2 5
|
|
2 3 4
|
|
. range 2 10 4
|
|
2 6
|
|
. range 7 4 -2
|
|
7 5</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_read">read</h3>
|
|
<div class="paragraph"><p><code><strong>read</strong> ?<strong>-nonewline</strong>? <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>read</strong> ?<strong>-nonewline</strong>?</code></p></div>
|
|
<div class="paragraph"><p><code><strong>read</strong> <em>fileId numBytes</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>read</strong> <em>numBytes</em></code></p></div>
|
|
<div class="paragraph"><p><code><strong>read</strong> ?<strong>-pending</strong>? <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>read</strong> ?<strong>-pending</strong>?</code></p></div>
|
|
<div class="paragraph"><p>In the first form, all of the remaining bytes are read from the file
|
|
given by <code><em>fileId</em></code>; they are returned as the result of the command.
|
|
If the <code>-nonewline</code> 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
|
|
<code><em>numBytes</em></code> bytes left in the file; in this case, all the remaining
|
|
bytes are returned.</p></div>
|
|
<div class="paragraph"><p>The third form is currently only useful with SSL sockets. It reads at least 1 byte
|
|
and then any additional data that is buffered. This allows for use in an event handler.
|
|
e.g.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> $sock readable {
|
|
set buf [$sock read -pending]
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This is necessary because otherwise pending data may be buffered, but
|
|
the underlying socket will not be marked <em>readable</em>. This featured is not
|
|
currently supported for regular sockets, and so these sockets must be
|
|
set to unbufferred (<code>$sock buffering false</code>) to work in an event loop.</p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em></code> must be <code>stdin</code> or the return value from a previous call
|
|
to <a href="#_open"><strong><code>open</code></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><code><strong>regexp ?-nocase? ?-line? ?-indices? ?-start</strong> <em>offset</em>? <strong>?-all? ?-inline? ?--?</strong> <em>exp string ?matchVar? ?subMatchVar subMatchVar ...?</em></code></p></div>
|
|
<div class="paragraph"><p>Determines whether the regular expression <code><em>exp</em></code> matches part or
|
|
all of <code><em>string</em></code> and returns 1 if it does, 0 if it doesn’t.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_regular_expressions">REGULAR EXPRESSIONS</a> above for complete information on the
|
|
syntax of <code><em>exp</em></code> and how it is matched against <code><em>string</em></code>.</p></div>
|
|
<div class="paragraph"><p>If additional arguments are specified after <code><em>string</em></code> then they
|
|
are treated as the names of variables to use to return
|
|
information about which part(s) of <code><em>string</em></code> matched <code><em>exp</em></code>.
|
|
<code><em>matchVar</em></code> will be set to the range of <code><em>string</em></code> that
|
|
matched all of <code><em>exp</em></code>. The first <code><em>subMatchVar</em></code> will contain
|
|
the characters in <code><em>string</em></code> that matched the leftmost parenthesized
|
|
subexpression within <code><em>exp</em></code>, the next <code><em>subMatchVar</em></code> will
|
|
contain the characters that matched the next parenthesized
|
|
subexpression to the right in <code><em>exp</em></code>, and so on.</p></div>
|
|
<div class="paragraph"><p>Normally, <code><em>matchVar</em></code> and the each <code><em>subMatchVar</em></code> are set to hold the
|
|
matching characters from <a href="#_string"><strong><code>string</code></strong></a>, however see <code>-indices</code> and
|
|
<code>-inline</code> below.</p></div>
|
|
<div class="paragraph"><p>If there are more values for <code><em>subMatchVar</em></code> than parenthesized subexpressions
|
|
within <code><em>exp</em></code>, or if a particular subexpression in <code><em>exp</em></code> doesn’t
|
|
match the string (e.g. because it was in a portion of the expression
|
|
that wasn’t matched), then the corresponding <code><em>subMatchVar</em></code> will be
|
|
set to <code>"-1 -1"</code> if <code>-indices</code> has been specified or to an empty
|
|
string otherwise.</p></div>
|
|
<div class="paragraph"><p>The following switches modify the behaviour of <code><em>regexp</em></code></p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>-nocase</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes upper-case and lower-case characters to be treated as
|
|
identical during the matching process.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-line</strong></code>
|
|
</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, <code>[<sup></code> bracket expressions
|
|
and <code>.</code> never match newline, an <code></sup></code> anchor matches the empty
|
|
string after any newline in the string in addition to its normal
|
|
function, and the <code>$</code> anchor matches the empty string before any
|
|
newline in the string in addition to its normal function.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-indices</strong></code>
|
|
</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">
|
|
<code><strong>-start</strong> <em>offset</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Specifies a character index offset into the string at which to start
|
|
matching the regular expression. If <code>-indices</code> is
|
|
specified, the indices will be indexed starting from the
|
|
absolute beginning of the input string. <code><em>offset</em></code> will be
|
|
constrained to the bounds of the input string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-all</strong></code>
|
|
</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">
|
|
<code><strong>-inline</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Causes the command to return, as a list, the data that would otherwise
|
|
be placed in match variables. When using <code>-inline</code>, match variables
|
|
may not be specified. If used with <code>-all</code>, 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">
|
|
<code><strong>--</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of switches. The argument following this one will be
|
|
treated as <code><em>exp</em></code> even if it starts with a <code>-</code>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_regsub">regsub</h3>
|
|
<div class="paragraph"><p><code><strong>regsub ?-nocase? ?-all? ?-line? ?-start</strong> <em>offset</em>? ?<strong>--</strong>? <em>exp string subSpec ?varName?</em></code></p></div>
|
|
<div class="paragraph"><p>This command matches the regular expression <code><em>exp</em></code> against
|
|
<code><em>string</em></code> using the rules described in REGULAR EXPRESSIONS
|
|
above.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> is specified, the commands stores <code><em>string</em></code> to <code><em>varName</em></code>
|
|
with the substitutions detailed below, and returns the number of
|
|
substitutions made (normally 1 unless <code>-all</code> is specified).
|
|
This is 0 if there were no matches.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> is not specified, the substituted string will be returned
|
|
instead.</p></div>
|
|
<div class="paragraph"><p>When copying <code><em>string</em></code>, the portion of <code><em>string</em></code> that
|
|
matched <code><em>exp</em></code> is replaced with <code><em>subSpec</em></code>.
|
|
If <code><em>subSpec</em></code> contains a <code>&</code> or <code>\0</code>, then it is replaced
|
|
in the substitution with the portion of <code><em>string</em></code> that
|
|
matched <code><em>exp</em></code>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>subSpec</em></code> contains a <code>\n</code>, where <code><em>n</em></code> is a digit
|
|
between 1 and 9, then it is replaced in the substitution with
|
|
the portion of <code><em>string</em></code> that matched the <code><em>n</em></code>'-th
|
|
parenthesized subexpression of <code><em>exp</em></code>.
|
|
Additional backslashes may be used in <code><em>subSpec</em></code> to prevent special
|
|
interpretation of <code>&</code> or <code>\0</code> or <code>\n</code> or
|
|
backslash.</p></div>
|
|
<div class="paragraph"><p>The use of backslashes in <code><em>subSpec</em></code> tends to interact badly
|
|
with the Tcl parser’s use of backslashes, so it’s generally
|
|
safest to enclose <code><em>subSpec</em></code> in braces if it includes
|
|
backslashes.</p></div>
|
|
<div class="paragraph"><p>The following switches modify the behaviour of <code><em>regsub</em></code></p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>-nocase</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Upper-case characters in <code><em>string</em></code> are converted to lower-case
|
|
before matching against <code><em>exp</em></code>; however, substitutions
|
|
specified by <code><em>subSpec</em></code> use the original unconverted form
|
|
of <code><em>string</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-all</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
All ranges in <code><em>string</em></code> that match <code><em>exp</em></code> are found and substitution
|
|
is performed for each of these ranges, rather than only the
|
|
first. The <code>&</code> and <code>\n</code> sequences are handled for
|
|
each substitution using the information from the corresponding
|
|
match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-line</strong></code>
|
|
</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, <code>[<sup></code> bracket expressions
|
|
and <code>.</code> never match newline, an <code></sup></code> anchor matches the empty
|
|
string after any newline in the string in addition to its normal
|
|
function, and the <code>$</code> anchor matches the empty string before any
|
|
newline in the string in addition to its normal function.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-start</strong> <em>offset</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Specifies a character index offset into the string at which to
|
|
start matching the regular expression. <code><em>offset</em></code> will be
|
|
constrained to the bounds of the input string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>--</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of switches. The argument following this one will be
|
|
treated as <code><em>exp</em></code> even if it starts with a <code>-</code>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_ref">ref</h3>
|
|
<div class="paragraph"><p><code><strong>ref</strong> <em>string tag ?finalizer?</em></code></p></div>
|
|
<div class="paragraph"><p>Create a new reference containing <code><em>string</em></code> of type <code><em>tag</em></code>.
|
|
If <code><em>finalizer</em></code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> finalizer reference string</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>See <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_rename">rename</h3>
|
|
<div class="paragraph"><p><code><strong>rename</strong> <em>oldName newName</em></code></p></div>
|
|
<div class="paragraph"><p>Rename the command that used to be called <code><em>oldName</em></code> so that it
|
|
is now called <code><em>newName</em></code>. If <code><em>newName</em></code> is an empty string
|
|
(e.g. {}) then <code><em>oldName</em></code> is deleted. The <a href="#_rename"><strong><code>rename</code></strong></a> command
|
|
returns an empty string as result.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_return">return</h3>
|
|
<div class="paragraph"><p><code><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>?</code></p></div>
|
|
<div class="paragraph"><p>Return immediately from the current procedure (or top-level command
|
|
or <a href="#_source"><strong><code>source</code></strong></a> command), with <code><em>value</em></code> as the return value. If <code><em>value</em></code>
|
|
is not specified, an empty string will be returned as result.</p></div>
|
|
<div class="paragraph"><p>If <code>-code</code> is specified (as either a number or ok, error, break,
|
|
continue, signal, return or exit), this code will be used instead
|
|
of <code>JIM_OK</code>. This is generally useful when implementing flow of control
|
|
commands.</p></div>
|
|
<div class="paragraph"><p>If <code>-level</code> is specified and greater than 1, it has the effect of delaying
|
|
the new return code from <code>-code</code>. This is useful when rethrowing an error
|
|
from <a href="#_catch"><strong><code>catch</code></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 <code>-code</code> is JIM_ERR.</p></div>
|
|
<div class="paragraph"><p>If <code>-errorinfo</code> is specified (as returned from <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>)
|
|
it is used to initialize the stacktrace.</p></div>
|
|
<div class="paragraph"><p>If <code>-errorcode</code> 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><code><strong>scan</strong> <em>string format varName1 ?varName2 ...?</em></code></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. <code><em>string</em></code> gives the input to be parsed
|
|
and <code><em>format</em></code> 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 <code><em>varName</em></code> gives the name of a variable;
|
|
when a field is scanned from <code><em>string</em></code>, the result is converted back
|
|
into a string and assigned to the corresponding <code><em>varName</em></code>. 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 <code><em>varName</em></code>; no field width may be
|
|
specified for this conversion.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_seek">seek</h3>
|
|
<div class="paragraph"><p><code><strong>seek</strong> <em>fileId offset ?origin?</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>seek</strong> <em>offset ?origin?</em></code></p></div>
|
|
<div class="paragraph"><p>Change the current access position for <code><em>fileId</em></code>.
|
|
The <code><em>offset</em></code> and <code><em>origin</em></code> arguments specify the position at
|
|
which the next read or write will occur for <code><em>fileId</em></code>.
|
|
<code><em>offset</em></code> must be a number (which may be negative) and <code><em>origin</em></code>
|
|
must be one of the following:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>start</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <code><em>offset</em></code> bytes from the start
|
|
of the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>current</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <code><em>offset</em></code> bytes from the current
|
|
access position; a negative <code><em>offset</em></code> moves the access position
|
|
backwards in the file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>end</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The new access position will be <code><em>offset</em></code> bytes from the end of
|
|
the file. A negative <code><em>offset</em></code> places the access position before
|
|
the end-of-file, and a positive <code><em>offset</em></code> places the access position
|
|
after the end-of-file.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The <code><em>origin</em></code> argument defaults to <code>start</code>.</p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to
|
|
<a href="#_open"><strong><code>open</code></strong></a>, or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> 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><code><strong>set</strong> <em>varName ?value?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns the value of variable <code><em>varName</em></code>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>value</em></code> is specified, then set the value of <code><em>varName</em></code> to <code><em>value</em></code>,
|
|
creating a new variable if one doesn’t already exist, and return
|
|
its value.</p></div>
|
|
<div class="paragraph"><p>If <code><em>varName</em></code> 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 <code><em>varName</em></code> refers to a scalar variable.</p></div>
|
|
<div class="paragraph"><p>If no procedure is active, then <code><em>varName</em></code> refers to a global
|
|
variable.</p></div>
|
|
<div class="paragraph"><p>If a procedure is active, then <code><em>varName</em></code> refers to a parameter
|
|
or local variable of the procedure, unless the <code><em>global</em></code> command
|
|
has been invoked to declare <code><em>varName</em></code> to be global.</p></div>
|
|
<div class="paragraph"><p>The <code>::</code> 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><code><strong>setref</strong> <em>reference string</em></code></p></div>
|
|
<div class="paragraph"><p>Store a new string in <code><em>reference</em></code>, replacing the existing string.
|
|
The reference must be a valid reference create with the <a href="#_ref"><strong><code>ref</code></strong></a>
|
|
command.</p></div>
|
|
<div class="paragraph"><p>See <a href="#_garbage_collection_references_lambda_function">GARBAGE COLLECTION</a> 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><code>kill</code></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:
|
|
"<code>SIGINT SIGTERM</code>".</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>signal handle</strong> ?<em>signals ...</em>?</code>
|
|
</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">
|
|
<code><strong>signal ignore</strong> ?<em>signals ...</em>?</code>
|
|
</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><code>catch</code></strong></a> <code>-signal</code> or <a href="#_try"><strong><code>try</code></strong></a> <code>-signal</code>. Use
|
|
<a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> to determine which signals have occurred but
|
|
been ignored.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>signal block</strong> ?<em>signals ...</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no signals are given, returns a lists all signals which are currently
|
|
being blocked.
|
|
If signals are specified, these are added to the list of signals
|
|
currently being blocked. These signals are not delivered to the process.
|
|
This can be useful for signals such as <code>SIGPIPE</code>, especially in conjunction
|
|
with <a href="#_exec"><strong><code>exec</code></strong></a> as child processes inherit the parent’s signal disposition.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>signal default</strong> ?<em>signals ...</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no signals are given, returns a lists all signals which 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">
|
|
<code><strong>signal check ?-clear?</strong> ?<em>signals ...</em>?</code>
|
|
</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 <code>-clear</code> is specified, any signals returned are removed and will not be
|
|
returned by subsequent calls to <a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> unless delivered again.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>signal throw</strong> ?<em>signal</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Raises the given signal, which defaults to <code>SIGINT</code> if not specified.
|
|
The behaviour is identical to:
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> kill signal [pid]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Note that <a href="#_signal"><strong><code>signal</code></strong></a> <code>handle</code> and <a href="#_signal"><strong><code>signal</code></strong></a> <code>ignore</code> represent two forms of signal
|
|
handling. <a href="#_signal"><strong><code>signal</code></strong></a> <code>handle</code> is used in conjunction with <a href="#_catch"><strong><code>catch</code></strong></a> <code>-signal</code> or <a href="#_try"><strong><code>try</code></strong></a> <code>-signal</code>
|
|
to immediately abort execution when the signal is delivered. Alternatively, <a href="#_signal"><strong><code>signal</code></strong></a> <code>ignore</code>
|
|
is used in conjunction with <a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> 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="listingblock">
|
|
<div class="content">
|
|
<pre><code> signal handle SIGALRM
|
|
alarm 20
|
|
try -signal {
|
|
.. possibly long running process ..
|
|
alarm 0
|
|
} on signal {sig} {
|
|
puts stderr "Process took too long"
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Handle SIGHUP to reconfigure:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> signal ignore SIGHUP
|
|
while {1} {
|
|
... handle configuration/reconfiguration ...
|
|
while {[signal check -clear SIGHUP] eq ""} {
|
|
... do processing ..
|
|
}
|
|
# Received SIGHUP, so reconfigure
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>Note: signal handling is currently not supported in child interpreters.
|
|
In these interpreters, the signal command does not exist.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_sleep">sleep</h3>
|
|
<div class="paragraph"><p><code><strong>sleep</strong> <em>seconds</em></code></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><code><strong>source</strong> <em>fileName</em></code></p></div>
|
|
<div class="paragraph"><p>Read file <code><em>fileName</em></code> 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><code>source</code></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><code>source</code></strong></a> command will return that error.</p></div>
|
|
<div class="paragraph"><p>If a <a href="#_return"><strong><code>return</code></strong></a> command is invoked from within the file, the remainder of
|
|
the file will be skipped and the <a href="#_source"><strong><code>source</code></strong></a> command will return
|
|
normally with the result from the <a href="#_return"><strong><code>return</code></strong></a> command.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_split">split</h3>
|
|
<div class="paragraph"><p><code><strong>split</strong> <em>string ?splitChars?</em></code></p></div>
|
|
<div class="paragraph"><p>Returns a list created by splitting <code><em>string</em></code> at each character
|
|
that is in the <code><em>splitChars</em></code> argument.</p></div>
|
|
<div class="paragraph"><p>Each element of the result list will consist of the
|
|
characters from <code><em>string</em></code> between instances of the
|
|
characters in <code><em>splitChars</em></code>.</p></div>
|
|
<div class="paragraph"><p>Empty list elements will be generated if <code><em>string</em></code> contains
|
|
adjacent characters in <code><em>splitChars</em></code>, or if the first or last
|
|
character of <code><em>string</em></code> is in <code><em>splitChars</em></code>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>splitChars</em></code> is an empty string then each character of
|
|
<code><em>string</em></code> becomes a separate element of the result list.</p></div>
|
|
<div class="paragraph"><p><code><em>splitChars</em></code> defaults to the standard white-space characters.
|
|
For example,</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> split "comp.unix.misc" .</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>returns <code><em>"comp unix misc"</em></code> and</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> split "Hello world" {}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>returns <code><em>"H e l l o { } w o r l d"</em></code>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_stackdump">stackdump</h3>
|
|
<div class="paragraph"><p><code><strong>stackdump</strong> <em>stacktrace</em></code></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><code><strong>stacktrace</strong></code></p></div>
|
|
<div class="paragraph"><p>Returns a live stack trace as a list of <code>proc file line proc file line ...</code>.
|
|
Iteratively uses <a href="#_info"><strong><code>info</code></strong></a> <code>frame</code> to create the stack trace. This stack trace is in the
|
|
same form as produced by <a href="#_catch"><strong><code>catch</code></strong></a> and <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code></p></div>
|
|
<div class="paragraph"><p>See also <a href="#_stackdump"><strong><code>stackdump</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_string">string</h3>
|
|
<div class="paragraph"><p><code><strong>string</strong> <em>option arg ?arg ...?</em></code></p></div>
|
|
<div class="paragraph"><p>Perform one of several string operations, depending on <code><em>option</em></code>.
|
|
The legal options (which may be abbreviated) are:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>string bytelength</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the length of the string in bytes. This will return
|
|
the same value as <a href="#_string"><strong><code>string</code></strong></a> <code>length</code> if UTF-8 support is not enabled,
|
|
or if the string is composed entirely of ASCII characters.
|
|
See <a href="#_utf_8_and_unicode">UTF-8 AND UNICODE</a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string byterange</strong> <em>string first last</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Like <a href="#_string"><strong><code>string</code></strong></a> <code>range</code> except works on bytes rather than characters.
|
|
These commands are identical if UTF-8 support is not enabled.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string cat</strong> <em>?string1 string2 ...?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Concatenates the given strings into a single string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string compare ?-nocase?</strong> ?<strong>-length</strong> <em>len? string1 string2</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Perform a character-by-character comparison of strings <code><em>string1</em></code> and
|
|
<code><em>string2</em></code> in the same way as the C <em>strcmp</em> procedure. Return
|
|
-1, 0, or 1, depending on whether <code><em>string1</em></code> is lexicographically
|
|
less than, equal to, or greater than <code><em>string2</em></code>. If <code>-length</code>
|
|
is specified, then only the first <code><em>len</em></code> characters are used
|
|
in the comparison. If <code><em>len</em></code> is negative, it is ignored.
|
|
Performs a case-insensitive comparison if <code>-nocase</code> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string equal ?-nocase?</strong> <em>?<strong>-length</strong> len?</em> <em>string1 string2</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if the strings are equal, or 0 otherwise. If <code>-length</code>
|
|
is specified, then only the first <code><em>len</em></code> characters are used
|
|
in the comparison. If <code><em>len</em></code> is negative, it is ignored.
|
|
Performs a case-insensitive comparison if <code>-nocase</code> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string first</strong> <em>string1 string2 ?firstIndex?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Search <code><em>string2</em></code> for a sequence of characters that exactly match
|
|
the characters in <code><em>string1</em></code>. If found, return the index of the
|
|
first character in the first such match within <code><em>string2</em></code>. If not
|
|
found, return -1. If <code><em>firstIndex</em></code> is specified, matching will start
|
|
from <code><em>firstIndex</em></code> of <code><em>string1</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>firstIndex</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string index</strong> <em>string charIndex</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the <code><em>charIndex</em></code><em>th character of the <code>'string</em></code>
|
|
argument. A <code><em>charIndex</em></code> of 0 corresponds to the first
|
|
character of the string.
|
|
If <code><em>charIndex</em></code> 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 <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>charIndex</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string is</strong> <em>class</em> ?<strong>-strict</strong>? <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if <code><em>string</em></code> is a valid member of the specified character
|
|
class, otherwise returns 0. If <code>-strict</code> 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">
|
|
<code>alnum</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any alphabet or digit character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>alpha</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>ascii</code>
|
|
</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">
|
|
<code>boolean</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any of the valid string formats for a boolean value in Tcl (0, false, no, off, 1, true, yes, on)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>control</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any control character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>digit</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any digit character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>double</code>
|
|
</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">
|
|
<code>graph</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any printing character, except space.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>integer</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>lower</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any lower case alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>print</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any printing character, including space.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>punct</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any punctuation character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>space</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any space character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>upper</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Any upper case alphabet character.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>xdigit</code>
|
|
</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 <code><em>not</em></code> respect UTF-8. See <a href="#_utf_8_and_unicode">UTF-8 AND UNICODE</a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Note that only <code><em>lowercase</em></code> boolean values are recognized (Tcl accepts any case).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string last</strong> <em>string1 string2 ?lastIndex?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Search <code><em>string2</em></code> for a sequence of characters that exactly match
|
|
the characters in <code><em>string1</em></code>. If found, return the index of the
|
|
first character in the last such match within <code><em>string2</em></code>. If there
|
|
is no match, then return -1. If <code><em>lastIndex</em></code> is specified, only characters
|
|
up to <code><em>lastIndex</em></code> of <code><em>string2</em></code> will be considered in the match.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>lastIndex</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string length</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a decimal string giving the number of characters in <code><em>string</em></code>.
|
|
If UTF-8 support is enabled, this may be different than the number of bytes.
|
|
See <a href="#_utf_8_and_unicode">UTF-8 AND UNICODE</a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string map ?-nocase?</strong> <em>mapping string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Replaces substrings in <code><em>string</em></code> based on the key-value pairs in
|
|
<code><em>mapping</em></code>, which is a list of <code>key value key value ...</code> as in the form
|
|
returned by <a href="#_array"><strong><code>array</code></strong></a> <code>get</code>. Each instance of a key in the string will be
|
|
replaced with its corresponding value. If <code>-nocase</code> 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. <code><em>string</em></code> is
|
|
only iterated over once, so earlier key replacements will have no affect for
|
|
later key matches. For example,
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</code></pre>
|
|
</div></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
will return the string <code>01321221</code>.
|
|
</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>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc</code></pre>
|
|
</div></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
it will return the string <code>02c322c222c</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string match ?-nocase?</strong> <em>pattern string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See if <code><em>pattern</em></code> matches <code><em>string</em></code> according to
|
|
<a href="#_string_matching">STRING MATCHING</a> rules
|
|
; return 1 if it does, 0
|
|
if it doesn’t. The match is performed in a case-insensitive manner if <code>-nocase</code> is specified.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string range</strong> <em>string first last</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a range of consecutive characters from <code><em>string</em></code>, starting
|
|
with the character whose index is <code><em>first</em></code> and ending with the
|
|
character whose index is <code><em>last</em></code>. An index of 0 refers to the
|
|
first character of the string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
See <a href="#_string_and_list_index_specifications">STRING AND LIST INDEX SPECIFICATIONS</a> for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>first</em></code> is less than zero then it is treated as if it were zero, and
|
|
if <code><em>last</em></code> is greater than or equal to the length of the string then
|
|
it is treated as if it were <code>end</code>. If <code><em>first</em></code> is greater than
|
|
<code><em>last</em></code> then an empty string is returned.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string repeat</strong> <em>string count</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a new string consisting of <code><em>string</em></code> repeated <code><em>count</em></code> times.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string replace</strong> <em>string first last ?newstring?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Removes a range of consecutive characters from <code><em>string</em></code>, starting
|
|
with the character whose index is <code><em>first</em></code> and ending with the
|
|
character whose index is <code><em>last</em></code>. If <code><em>newstring</em></code> is specified,
|
|
then it is placed in the removed character range. If <code><em>first</em></code> is
|
|
less than zero then it is treated as if it were zero, and if <code><em>last</em></code>
|
|
is greater than or equal to the length of the string then it is
|
|
treated as if it were <code>end</code>. If <code><em>first</em></code> is greater than <code><em>last</em></code>
|
|
or the length of the initial string, or <code><em>last</em></code> is less than 0,
|
|
then the initial string is returned untouched.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string reverse</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a string that is the same length as <code><em>string</em></code> but
|
|
with its characters in the reverse order.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string tolower</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> except that all upper case
|
|
letters have been converted to lower case.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string totitle</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> 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">
|
|
<code><strong>string toupper</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> except that all lower case
|
|
letters have been converted to upper case.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string trim</strong> <em>string ?chars?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> except that any leading
|
|
or trailing characters from the set given by <code><em>chars</em></code> are
|
|
removed.
|
|
If <code><em>chars</em></code> is not specified then white space is removed
|
|
(spaces, tabs, newlines, and carriage returns).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string trimleft</strong> <em>string ?chars?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> except that any
|
|
leading characters from the set given by <code><em>chars</em></code> are
|
|
removed.
|
|
If <code><em>chars</em></code> is not specified then white space is removed
|
|
(spaces, tabs, newlines, and carriage returns).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>string trimright</strong> <em>string ?chars?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a value equal to <code><em>string</em></code> except that any
|
|
trailing characters from the set given by <code><em>chars</em></code> are
|
|
removed.
|
|
If <code><em>chars</em></code> 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><code><strong>subst ?-nobackslashes? ?-nocommands? ?-novariables?</strong> <em>string</em></code></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 <code>-nobackslashes</code>, <code>-nocommands</code>, or <code>-novariables</code> are
|
|
specified, then the corresponding substitutions are not performed.
|
|
For example, if <code>-nocommands</code> 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 <code>xyz {44}</code>, not <code>xyz {$a}</code>.</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> set a 44
|
|
subst {xyz {$a}}</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_switch">switch</h3>
|
|
<div class="paragraph"><p><code><strong>switch</strong> <em>?options? string pattern body ?pattern body ...?</em></code></p></div>
|
|
<div class="paragraph"><p><code><strong>switch</strong> <em>?options? string {pattern body ?pattern body ...?}</em></code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_switch"><strong><code>switch</code></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><code>switch</code></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">
|
|
<code>-exact</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use exact matching when comparing string to a
|
|
pattern. This is the default.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>-glob</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
When matching string to the patterns, use glob-style
|
|
<a href="#_string_matching">STRING MATCHING</a> rules.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>-regexp</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
When matching string to the patterns, use
|
|
<a href="#_regular_expressions">REGULAR EXPRESSIONS</a> rules.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>-command <em>commandname</em></code>
|
|
</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">
|
|
<code>--</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Marks the end of options. The argument following
|
|
this one will be treated as string even if it starts
|
|
with a <code>-</code>.
|
|
</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><code>switch</code></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 <code>-</code> 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 <code>-</code> 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><code>switch</code></strong></a> commands:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> switch abc a - b {format 1} abc {format 2} default {format 3}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return 2,</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> switch -regexp aaab {
|
|
^a.*b$ -
|
|
b {format 1}
|
|
a* {format 2}
|
|
default {format 3}
|
|
}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>will return 1, and</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> switch xyz {
|
|
a -
|
|
b {format 1}
|
|
a* {format 2}
|
|
default {format 3}
|
|
}</code></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><code><strong>tailcall</strong> <em>cmd ?arg...?</em></code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_tailcall"><strong><code>tailcall</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> tailcall a b c</code></pre>
|
|
</div></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> return [uplevel 1 [list a b c]]</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p><a href="#_tailcall"><strong><code>tailcall</code></strong></a> is useful as a dispatch mechanism:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> proc a {cmd args} {
|
|
tailcall sub_$cmd {*}$args
|
|
}
|
|
proc sub_cmd1 ...
|
|
proc sub_cmd2 ...</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tell">tell</h3>
|
|
<div class="paragraph"><p><code><strong>tell</strong> <em>fileId</em></code></p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em> <strong>tell</strong></code></p></div>
|
|
<div class="paragraph"><p>Returns a decimal string giving the current access position in
|
|
<code><em>fileId</em></code>.</p></div>
|
|
<div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to
|
|
<a href="#_open"><strong><code>open</code></strong></a>, or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> 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><code><strong>throw</strong> <em>code ?msg?</em></code></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><code>try</code></strong></a>.</p></div>
|
|
<div class="paragraph"><p>The command <code>throw break</code> is equivalent to <code>break</code>.
|
|
The command <code>throw 20 message</code> can be caught with an <code>on 20 ...</code> clause to <a href="#_try"><strong><code>try</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_time">time</h3>
|
|
<div class="paragraph"><p><code><strong>time</strong> <em>command ?count?</em></code></p></div>
|
|
<div class="paragraph"><p>This command will call the Tcl interpreter <code><em>count</em></code>
|
|
times to execute <code><em>command</em></code> (or once if <code><em>count</em></code> isn’t
|
|
specified). It will then return a string of the form</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> 503 microseconds per iteration</code></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><code><strong>try</strong> <em>?catchopts? tryscript</em> ?<strong>on</strong> <em>returncodes {?resultvar? ?optsvar?} handlerscript ...</em>? ?<strong>finally</strong> <em>finalscript</em>?</code></p></div>
|
|
<div class="paragraph"><p>The <a href="#_try"><strong><code>try</code></strong></a> command is provided as a convenience for exception handling.</p></div>
|
|
<div class="paragraph"><p>This interpeter first evaluates <code><em>tryscript</em></code> under the effect of the catch
|
|
options <code><em>catchopts</em></code> (e.g. <code>-signal -noexit --</code>, see <a href="#_catch"><strong><code>catch</code></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><code>try</code></strong></a>
|
|
section. For example a normal <code>JIM_ERR</code> error will be matched by
|
|
an <em>on error</em> handler.</p></div>
|
|
<div class="paragraph"><p>Finally, any <code><em>finalscript</em></code> is evaluated.</p></div>
|
|
<div class="paragraph"><p>The result of this command is the result of <code><em>tryscript</em></code>, 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 <code><em>returncodes</em></code> 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 <code><em>resultvar</em></code> and <code><em>optsvar</em></code> are specified, they are set as for <a href="#_catch"><strong><code>catch</code></strong></a> before evaluating
|
|
the matching handler.</p></div>
|
|
<div class="paragraph"><p>For example:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> 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
|
|
}</code></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><code>throw</code></strong></a>, <a href="#_catch"><strong><code>catch</code></strong></a>, <a href="#_return"><strong><code>return</code></strong></a>, <a href="#_error"><strong><code>error</code></strong></a>.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_unknown">unknown</h3>
|
|
<div class="paragraph"><p><code><strong>unknown</strong> <em>cmdName ?arg arg …?</em></code></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><code>unknown</code></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><code>unknown</code></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><code>unknown</code></strong></a> command typically does things like searching
|
|
through library directories for a command procedure with the name
|
|
<code><em>cmdName</em></code>, 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><code>unknown</code></strong></a> will
|
|
change the original command slightly and then (re-)execute it.
|
|
The result of the <a href="#_unknown"><strong><code>unknown</code></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><code><strong>unset ?-nocomplain? ?--?</strong> <em>?name name …?</em></code></p></div>
|
|
<div class="paragraph"><p>Remove variables.
|
|
Each <code><em>name</em></code> is a variable name, specified in any of the
|
|
ways acceptable to the <a href="#_set"><strong><code>set</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>If a <code><em>name</em></code> 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 <code><em>name</em></code> 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><code>unset</code></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><code><strong>upcall</strong> <em>command ?args …?</em></code></p></div>
|
|
<div class="paragraph"><p>May be used from within a proc defined as <a href="#_local"><strong><code>local</code></strong></a> <a href="#_proc"><strong><code>proc</code></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><code><strong>uplevel</strong> <em>?level? command ?command …?</em></code></p></div>
|
|
<div class="paragraph"><p>All of the <code><em>command</em></code> arguments are concatenated as if they had
|
|
been passed to <a href="#_concat"><strong><code>concat</code></strong></a>; the result is then evaluated in the
|
|
variable context indicated by <code><em>level</em></code>. <a href="#_uplevel"><strong><code>uplevel</code></strong></a> returns
|
|
the result of that evaluation. If <code><em>level</em></code> is an integer, then
|
|
it gives a distance (up the procedure calling stack) to move before
|
|
executing the command. If <code><em>level</em></code> consists of <code>#</code> followed by
|
|
a number then the number gives an absolute level number. If <code><em>level</em></code>
|
|
is omitted then it defaults to <code>1</code>. <code><em>level</em></code> cannot be
|
|
defaulted if the first <code><em>command</em></code> argument starts with a digit or <code>#</code>.</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><code>uplevel</code></strong></a> command. If <code><em>level</em></code>
|
|
is <code>1</code> or <code>#2</code> or omitted, then the command will be executed
|
|
in the variable context of <em>b</em>. If <code><em>level</em></code> is <code>2</code> or <code>#1</code>
|
|
then the command will be executed in the variable context of <em>a</em>.</p></div>
|
|
<div class="paragraph"><p>If <code><em>level</em></code> is <em>3</em> or <code>#0</code> then the command will be executed
|
|
at top-level (only global variables will be visible).
|
|
The <a href="#_uplevel"><strong><code>uplevel</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> uplevel 1 {set x 43; d}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>where <em>d</em> is another Tcl procedure. The <a href="#_set"><strong><code>set</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> uplevel {set x 42}</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>then the <a href="#_set"><strong><code>set</code></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><code>info</code></strong></a> <code>level</code> may
|
|
be used to obtain the level of the current procedure.</p></div>
|
|
<div class="paragraph"><p><a href="#_uplevel"><strong><code>uplevel</code></strong></a> makes it possible to implement new control
|
|
constructs as Tcl procedures (for example, <a href="#_uplevel"><strong><code>uplevel</code></strong></a> could
|
|
be used to implement the <a href="#_while"><strong><code>while</code></strong></a> construct as a Tcl procedure).</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_upvar">upvar</h3>
|
|
<div class="paragraph"><p><code><strong>upvar</strong> <em>?level? otherVar myVar ?otherVar myVar …?</em></code></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><code><em>level</em></code> may have any of the forms permitted for the <a href="#_uplevel"><strong><code>uplevel</code></strong></a>
|
|
command, and may be omitted if the first letter of the first <code><em>otherVar</em></code>
|
|
isn’t <code>#</code> or a digit (it defaults to <em>1</em>).</p></div>
|
|
<div class="paragraph"><p>For each <code><em>otherVar</em></code> argument, <a href="#_upvar"><strong><code>upvar</code></strong></a> makes the variable
|
|
by that name in the procedure frame given by <code><em>level</em></code> (or at
|
|
global level, if <code><em>level</em></code> is <code>#0</code>) accessible
|
|
in the current procedure by the name given in the corresponding
|
|
<code><em>myVar</em></code> argument.</p></div>
|
|
<div class="paragraph"><p>The variable named by <code><em>otherVar</em></code> need not exist at the time of the
|
|
call; it will be created the first time <code><em>myVar</em></code> is referenced, just like
|
|
an ordinary variable.</p></div>
|
|
<div class="paragraph"><p><a href="#_upvar"><strong><code>upvar</code></strong></a> may only be invoked from within procedures.</p></div>
|
|
<div class="paragraph"><p><a href="#_upvar"><strong><code>upvar</code></strong></a> returns an empty string.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_upvar"><strong><code>upvar</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> proc add2 name {
|
|
upvar $name x
|
|
set x [expr $x+2]
|
|
}</code></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><code>uplevel</code></strong></a>
|
|
instead of <a href="#_upvar"><strong><code>upvar</code></strong></a>, <a href="#_upvar"><strong><code>upvar</code></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="_wait">wait</h3>
|
|
<div class="paragraph"><p><code><strong>wait</strong></code></p></div>
|
|
<div class="paragraph"><p><code><strong>wait -nohang</strong> <em>pid</em></code></p></div>
|
|
<div class="paragraph"><p>With no arguments, cleans up any processes started by <a href="#_exec"><strong><code>exec</code></strong></a> <code>... &</code> that have completed
|
|
(reaps zombie processes).</p></div>
|
|
<div class="paragraph"><p>With one or two arguments, waits for a process by id, either returned by <a href="#_exec"><strong><code>exec</code></strong></a> <code>... &</code>
|
|
or by <a href="#cmd_1"><strong><code>os.fork</code></strong></a> (if supported).</p></div>
|
|
<div class="paragraph"><p>Waits for the process to complete, unless <code>-nohang</code> is specified, in which case returns
|
|
immediately if the process is still running.</p></div>
|
|
<div class="paragraph"><p>Returns a list of 3 elements.</p></div>
|
|
<div class="paragraph"><p><code>{NONE x x}</code> if the process does not exist or has already been waited for, or
|
|
if -nohang is specified, and the process is still alive.</p></div>
|
|
<div class="paragraph"><p><code>{CHILDSTATUS <pid> <exit-status>}</code> if the process exited normally.</p></div>
|
|
<div class="paragraph"><p><code>{CHILDKILLED <pid> <signal>}</code> if the process terminated on a signal.</p></div>
|
|
<div class="paragraph"><p><code>{CHILDSUSP <pid> none}</code> if the process terminated for some other reason.</p></div>
|
|
<div class="paragraph"><p>Note that on platforms supporting waitpid(2), <code>pid</code> can also be given special values such
|
|
as 0 or -1. See waitpid(2) for more detail.</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_while">while</h3>
|
|
<div class="paragraph"><p><code><strong>while</strong> <em>test body</em></code></p></div>
|
|
<div class="paragraph"><p>The <code><em>while</em></code> command evaluates <code><em>test</em></code> as an expression
|
|
(in the same way that <a href="#_expr"><strong><code>expr</code></strong></a> evaluates its argument).
|
|
The value of the expression must be numeric; if it is non-zero
|
|
then <code><em>body</em></code> is executed by passing it to the Tcl interpreter.</p></div>
|
|
<div class="paragraph"><p>Once <code><em>body</em></code> has been executed then <code><em>test</em></code> is evaluated
|
|
again, and the process repeats until eventually <code><em>test</em></code>
|
|
evaluates to a zero numeric value. <a href="#_continue"><strong><code>continue</code></strong></a>
|
|
commands may be executed inside <code><em>body</em></code> to terminate the current
|
|
iteration of the loop, and <a href="#_break"><strong><code>break</code></strong></a>
|
|
commands may be executed inside <code><em>body</em></code> to cause immediate
|
|
termination of the <a href="#_while"><strong><code>while</code></strong></a> command.</p></div>
|
|
<div class="paragraph"><p>The <a href="#_while"><strong><code>while</code></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.gethostname, os.getids, os.uptime</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>os.fork</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invokes <em>fork(2)</em> and returns the result.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>os.gethostname</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Invokes <em>gethostname(3)</em> and returns the result.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>os.getids</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the various user/group ids for the current process.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . os.getids
|
|
uid 1000 euid 1000 gid 100 egid 100</code></pre>
|
|
</div></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>os.uptime</strong></code>
|
|
</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><code>open</code></strong></a> and <a href="#_socket"><strong><code>socket</code></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">
|
|
<code>$handle <strong>accept</strong> ?addrvar?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Server socket only: Accept a connection and return stream.
|
|
If <code><em>addrvar</em></code> is specified, the address of the connected client is stored
|
|
in the named variable in the form <em>addr:port</em> for IP sockets or <em>path</em> for Unix domain sockets.
|
|
See <a href="#_socket"><strong><code>socket</code></strong></a> for details.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>buffering none|line|full</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets the buffering mode of the stream.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>close ?r(ead)|w(rite)|-nodelete?</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Closes the stream.
|
|
The <code><em>read</em></code> and <code><em>write</em></code> arguments perform a "half-close" on a socket. See the <em>shutdown(2)</em> man page.
|
|
The <code><em>-nodelete</em></code> option is applicable only for Unix domain sockets. It closes the socket
|
|
but does not delete the bound path (e.g. after <a href="#cmd_1"><strong><code>os.fork</code></strong></a>).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>copyto</strong> <em>tofd ?size?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Copy bytes to the file descriptor <code><em>tofd</em></code>. If <code><em>size</em></code> 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">
|
|
<code>$handle <strong>eof</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if stream is at eof
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>filename</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the original filename associated with the handle.
|
|
Handles returned by <a href="#_socket"><strong><code>socket</code></strong></a> give the socket type instead of a filename.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>flush</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Flush the stream
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>gets</strong> <em>?var?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Read one line and return it or store it in the var
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>isatty</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if the stream is a tty device.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>lock ?-wait?</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Apply a POSIX lock to the open file associated with the handle using
|
|
<em>fcntl(F_SETLK)</em>, or <em>fcntl(F_SETLKW)</em> to wait for the lock to be available if <code><em>-wait</em></code>
|
|
is specified.
|
|
The handle must be open for write access.
|
|
Returns 1 if the lock was successfully obtained, 0 otherwise.
|
|
An error occurs if the handle is not suitable for locking (e.g.
|
|
if it is not open for write)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>ndelay ?0|1?</strong></code>
|
|
</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">
|
|
<code>$handle <strong>peername</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the remote address or path of the connected socket. See <em>getpeername(2)</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>puts ?-nonewline?</strong> <em>str</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Write the string, with newline unless -nonewline
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>read ?-nonewline|-pending</strong>|len?'</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Read and return bytes from the stream. To eof if no len. See <a href="#_read"><strong><code>read</code></strong></a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>recvfrom</strong> <em>maxlen ?addrvar?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Receives a message from the handle via recvfrom(2) and returns it.
|
|
At most <code><em>maxlen</em></code> bytes are read. If <code><em>addrvar</em></code> is specified, the sending address
|
|
of the message is stored in the named variable in the form <em>addr:port</em> for IP sockets
|
|
or <em>path</em> for Unix domain sockets. See <a href="#_socket"><strong><code>socket</code></strong></a> for details.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>seek</strong> <em>offset</em> <strong>?start|current|end?</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Seeks in the stream (default <em>current</em>)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>sendto</strong> <em>str ?address</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sends the string, <code><em>str</em></code>, to the given address (host:port or path) via the socket using <em>sendto(2)</em>.
|
|
This is intended for udp/dgram 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">
|
|
<code>$handle <strong>sockname</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the bound address or path of the socket. See <em>getsockname(2)</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>sockopt</strong> <em>?name value?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
With no arguments, returns a dictionary of socket options currently set for the handle
|
|
(will be empty for a non-socket). With <code><em>name</em></code> and <code><em>value</em></code>, sets the socket option
|
|
to the given value. Currently supports the following boolean socket options:
|
|
<code>broadcast, debug, keepalive, nosigpipe, oobinline, tcp_nodelay</code>, and the following
|
|
integer socket options: <code>sndbuf, rcvbuf</code>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>sync</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Flush the stream, then <em>fsync(2)</em> to commit any changes to storage.
|
|
Only available on platforms that support <em>fsync(2)</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>tell</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the current seek position
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>tty</strong> ?settings?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If no arguments are given, returns a dictionary containing the tty settings for the stream.
|
|
If arguments are given, they must either be a dictionary, or <code>setting value ...</code>
|
|
Abbreviations are supported for both settings and values, so the following is acceptable:
|
|
<code>$f tty parity e input c out raw</code>.
|
|
Only available on platforms that support <em>termios(3)</em>. Supported settings are:
|
|
</p>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>baud</strong> <em>rate</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Baud rate. e.g. 115200
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>data 5|6|7|8</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Number of data bits
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>stop 1|2</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Number of stop bits
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>parity even|odd|none</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Parity setting
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>handshake xonxoff|rtscts|none</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Handshaking type
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>input raw|cooked</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Input character processing. In raw mode, the usual key sequences such as ^C do
|
|
not generate signals.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>output raw|cooked</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Output character processing. Typically CR → CRNL is disabled in raw mode.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>echo 0|1</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Disable or enable echo on input. Note that this is a set-only value.
|
|
Setting <code>input</code> to <code>raw</code> or <code>cooked</code> will overwrite this setting.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>vmin</strong> <em>numchars</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Minimum number of characters to read.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>vtime</strong> <em>time</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Timeout for noncanonical read (units of 0.1 seconds)
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>ssl</strong> ?<strong>-server</strong> <em>cert ?key?</em>|<strong>-sni</strong> <em>servername</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Upgrades the stream to a SSL/TLS session and returns the handle.
|
|
If <code>-server</code> is specified, either both the certificate and private key files
|
|
must be specified, or a single file must be specified containing both.
|
|
If <code>-server</code> is not specified, the connection is a client connection. In this case
|
|
<code>-sni</code> may be specified if required to set the Server Name Indication.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>unlock</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Release a POSIX lock previously acquired by <a href="#_aio"><strong><code>aio</code></strong></a> <code>lock</code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>verify</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Verifies the certificate of a SSL/TLS stream peer
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>load_ssl_certs</strong> <em>dir</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Loads SSL/TLS CA certificates for use during verification
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_fconfigure">fconfigure</h3>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>fconfigure</strong> <em>handle</em> <strong>?-blocking 0|1? ?-buffering noneline|full? ?-translation</strong> <em>mode</em>?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
For compatibility with Tcl, a limited form of the <a href="#_fconfigure"><strong><code>fconfigure</code></strong></a>
|
|
command is supported.
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -blocking</code> maps to <a href="#_aio"><strong><code>aio</code></strong></a> <code>ndelay</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -buffering</code> maps to <a href="#_aio"><strong><code>aio</code></strong></a> <code>buffering</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -translation</code> 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">
|
|
<code>$handle <strong>readable</strong> <em>?readable-script?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when the socket is readable.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>writable</strong> <em>?writable-script?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when the socket is writable.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$handle <strong>onexception</strong> <em>?exception-script?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets or returns the script for when oob data received.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>For compatibility with <em>Tcl</em>, these may be prefixed with <code>fileevent</code>. e.g.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
<code>fileevent $handle <strong>readable</strong> <em>...</em></code>
|
|
</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">
|
|
<code><strong>after</strong> <em>ms</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sleeps for the given number of milliseconds. No events are
|
|
processed during this time.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>after</strong> <em>ms</em>|<strong>idle</strong> <em>script ?script ...?</em></code>
|
|
</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><code>vwait</code></strong></a> or <a href="#cmd_2"><strong><code>update</code></strong></a>. The script is only run once and
|
|
then removed. Returns an event id.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>after cancel</strong> <em>id|command</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Cancels an <a href="#cmd_2"><strong><code>after</code></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">
|
|
<code><strong>after info</strong> <em>?id?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>id</em></code> is not given, returns a list of current <a href="#cmd_2"><strong><code>after</code></strong></a>
|
|
events. If <code><em>id</em></code> 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 <code><em>id</em></code> does not
|
|
match an event.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>vwait</strong> <em>variable</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A call to <a href="#cmd_2"><strong><code>vwait</code></strong></a> enters the eventloop. <a href="#cmd_2"><strong><code>vwait</code></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><code>vwait</code></strong></a>
|
|
returns immediately.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>update ?idletasks?</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A call to <a href="#cmd_2"><strong><code>update</code></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) <code>bgerror</code> with the details of the error.
|
|
If the <code>bgerror</code> command does not exist, the error message details are 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">
|
|
<code><strong>bgerror</strong> <em>msg</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Called when an event handler script generates an error. Note that the normal command resolution
|
|
rules are used for bgerror. First the name is resolved in the current namespace, then in the
|
|
global scope.
|
|
</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">
|
|
<code><strong>socket unix</strong> <em>path</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket client connected to <em>path</em>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket unix.server</strong> <em>path</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket server listening on <em>path</em>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket unix.dgram</strong> <em>?path?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket datagram client, optionally connected to <em>path</em>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket unix.dgram.server</strong> <em>path</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A unix domain socket datagram server server listening on <em>path</em>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket ?-ipv6? stream</strong> <em>addr:port</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A TCP socket client. (See the forms for <code><em>addr</em></code> below)
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket ?-ipv6? stream.server</strong> <em>?addr:?port</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A TCP socket server (<code><em>addr</em></code> defaults to <code>0.0.0.0</code> for IPv4 or <code>[::]</code> for IPv6).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket ?-ipv6? dgram</strong> ?<em>addr:port</em>?</code>
|
|
</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">
|
|
<code><strong>socket ?-ipv6? dgram.server</strong> <em>addr:port</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A UDP socket server.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket pipe</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A synonym for <a href="#_pipe"><strong><code>pipe</code></strong></a>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket pair</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A socketpair (see socketpair(2)). Like <a href="#_pipe"><strong><code>pipe</code></strong></a>, this command returns
|
|
a list of two channels: {s1 s2}. These channels are both readable and writable.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>socket pty</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
A pseudo-tty pair (see openpty(3)). Like <a href="#_pipe"><strong><code>pipe</code></strong></a>, this command returns
|
|
a list of two channels: {master slave}. These channels are both readable and writable.
|
|
</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="listingblock">
|
|
<div class="content">
|
|
<pre><code> . 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</code></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="listingblock">
|
|
<div class="content">
|
|
<pre><code> 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</code></pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>The address, <code><em>addr</em></code>, 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 <code><em>first</em></code> returned address is used
|
|
which matches the socket type is used.</p></div>
|
|
<div class="paragraph"><p>An unconnected dgram socket (either <em>dgram</em> or <em>unix.dgram</em>) must use
|
|
<code>sendto</code> to specify the destination address.</p></div>
|
|
<div class="paragraph"><p>The path for Unix domain sockets is automatically removed when the socket
|
|
is closed. Use <a href="#_close"><strong><code>close</code></strong></a> <code>-nodelete</code> in the rare case where this behaviour
|
|
should be avoided (e.g. after <a href="#cmd_1"><strong><code>os.fork</code></strong></a>).</p></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_syslog">syslog</h3>
|
|
<div class="paragraph"><p><code><strong>syslog</strong> <em>?options? ?priority? message</em></code></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><code>emerg, alert, crit, err, error, warning, notice, info, debug</code></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">
|
|
<code><strong>-facility</strong> <em>value</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use specified facility instead of user. The following
|
|
values for facility are recognized:
|
|
</p>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
|
|
uucp, local0-local7</code></pre>
|
|
</div></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-ident</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Use given string instead of argv0 variable for ident string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>-options</strong> <em>integer</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Set syslog options such as <code>LOG_CONS</code>, <code>LOG_NDELAY</code>. 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">
|
|
<code><strong>pack</strong> <em>varName value</em> <strong>-intle|-intbe|-floatle|-floatbe|-str</strong> <em>bitwidth ?bitoffset?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Packs the binary representation of <code><em>value</em></code> into the variable
|
|
<code><em>varName</em></code>. The value is packed according to the given type
|
|
(integer/floating point/string, big-endian/little-endian), width and bit offset.
|
|
The variable is created if necessary (like <a href="#_append"><strong><code>append</code></strong></a>).
|
|
The variable is expanded if necessary.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>unpack</strong> <em>binvalue</em> <strong>-intbe|-intle|-uintbe|-uintle|-floatbe|-floatle|-str</strong> <em>bitpos bitwidth</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Unpacks bits from <code><em>binvalue</em></code> at bit position <code><em>bitpos</em></code> and with <code><em>bitwidth</em></code>.
|
|
Interprets the value according to the type (integer/floating point/string, big-endian/little-endian
|
|
and signed/unsigned) and returns it. For integer types, <code><em>bitwidth</em></code>
|
|
may be up to the size of a Jim Tcl integer (typically 64 bits). For floating point types,
|
|
<code><em>bitwidth</em></code> may be 32 bits (for single precision numbers) or 64 bits (for double precision).
|
|
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, 0.0 for floating point types
|
|
or the empty string for the string type.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_zlib">zlib</h3>
|
|
<div class="paragraph"><p>The optional <em>zlib</em> extension provides a Tcl-compatible subset of the <a href="#_zlib"><strong><code>zlib</code></strong></a> command.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>crc32</strong> <em>data</em> <em>?startValue?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the CRC32 checksum of a buffer. Optionally, an initial value may be specified; this is most useful
|
|
for calculating the checksum of chunked data read from a stream (for instance, a pipe).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>deflate</strong> <em>string</em> <em>?level?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Compresses a buffer and outputs a raw, Deflate-compressed stream. Optionally, a compression level (1-9) may
|
|
be specified to choose the desired speed vs. compression rate ratio.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>inflate</strong> <em>data</em> <em>?bufferSize?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Decompresses a raw, Deflate-compressed stream. When the uncompressed data size is known and specified, memory
|
|
allocation is more efficient. Otherwise, decompression is chunked and therefore slower.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>gzip</strong> <em>string</em> <em>?-level level?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Compresses a buffer and adds a gzip header.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>gunzip</strong> <em>data</em> <em>?-buffersize size?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Decompresses a gzip-compressed buffer. Decompression is chunked, with a default, small buffer size of 64K
|
|
which guarantees lower memory footprint at the cost of speed. It is recommended to use a bigger size, on
|
|
systems without a severe memory constraint.
|
|
</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><code>binary</code></strong></a> <code>scan</code> and <a href="#_binary"><strong><code>binary</code></strong></a> <code>format</code>
|
|
commands based on the low-level <a href="#cmd_3"><strong><code>pack</code></strong></a> and <a href="#cmd_3"><strong><code>unpack</code></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 <em>binary format</em> with f/r/R specifiers (single-precision float) uses the value of Infinity
|
|
in case of overflow.</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.tcl.tk/index.html/doc/www/www/documentation/oo/">http://jim.tcl.tk/index.html/doc/www/www/documentation/oo/</a>) for more details.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>class</strong> <em>classname ?baseclasses? classvars</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Create a new class, <code><em>classname</em></code>, with the given dictionary
|
|
(<code><em>classvars</em></code>) 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">
|
|
<code><strong>super</strong> <em>method ?args ...?</em></code>
|
|
</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://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/struct_tree.html">http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/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">
|
|
<code><strong>tree</strong></code>
|
|
</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">
|
|
<code>$tree <strong>destroy</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Destroy the tree and all it’s nodes. (Note that the tree will also
|
|
be automatically garbage collected once it goes out of scope).
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>set</strong> <em>nodename key value</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Set the value for the given attribute key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>lappend</strong> <em>nodename key value ...</em></code>
|
|
</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">
|
|
<code>$tree <strong>keyexists</strong> <em>nodename key</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns 1 if the given attribute key exists.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>get</strong> <em>nodename key</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the value associated with the given attribute key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>getall</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the entire attribute dictionary associated with the given key.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>depth</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the depth of the given node. The depth of "root" is 0.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>parent</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the node name of the parent node, or "" for the root node.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>numchildren</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the number of child nodes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>children</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of the child nodes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>next</strong> <em>nodename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the next sibling node, or "" if none.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>insert</strong> <em>nodename ?index?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Add a new child node to the given node. The index is a list index
|
|
such as <code>3</code> or <code>end-2</code>. The default index is <code>end</code>.
|
|
Returns the name of the newly added node.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>walk</strong> <em>nodename</em> <strong>dfs|bfs</strong> {<em>actionvar nodevar</em>} <em>script</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Walks the tree starting from the given node, either breadth first (<code>bfs</code>)
|
|
depth first (<code>dfs</code>).
|
|
The value <code>"enter"</code> or <code>"exit"</code> is stored in variable <code><em>actionvar</em></code>.
|
|
The name of each node is stored in <code><em>nodevar</em></code>.
|
|
The script is evaluated twice for each node, on entry and exit.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code>$tree <strong>dump</strong></code>
|
|
</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 <a href="#_tcl_prefix"><strong><code>tcl::prefix</code></strong></a> 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">
|
|
<code><strong>tcl::prefix all</strong> <em>table string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns a list of all elements in <code><em>table</em></code> that begin with the prefix <code><em>string</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>tcl::prefix longest</strong> <em>table string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the longest common prefix of all elements in <code><em>table</em></code> that begin with the prefix <code><em>string</em></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>tcl::prefix match</strong> <em>?options? table string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If <code><em>string</em></code> equals one element in <code><em>table</em></code> or is a prefix to
|
|
exactly one element, the matched element is returned. If not, the
|
|
result depends on the <code>-error</code> option.
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<code><strong>-exact</strong></code> Accept only exact matches.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><strong>-message</strong> <em>string</em></code> Use <code><em>string</em></code> in the error message at a mismatch. Default is "option".
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<code><strong>-error</strong> <em>options</em></code> The options are used when no match is found. If <code><em>options</em></code> 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 <code>-level 0</code>.
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_tcl_autocomplete">tcl::autocomplete</h3>
|
|
<div class="paragraph"><p>Scriptable command line completion is supported in the interactive shell, <em>jimsh</em>, through
|
|
the <a href="#_tcl_autocomplete"><strong><code>tcl::autocomplete</code></strong></a> callback. A simple implementation is provided, however this may
|
|
be replaced with a custom command instead if desired.</p></div>
|
|
<div class="paragraph"><p>In the interactive shell, press <TAB> to activate command line completion.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>tcl::autocomplete</strong> <em>commandline</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This command is called with the current command line when the user presses <TAB>.
|
|
The command should return a list of all possible command lines that match the current command line.
|
|
For example if <code><strong>pr</strong></code> is the current command line, the list <code><strong>{prefix proc}</strong></code> may be returned.
|
|
</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><code>history</code></strong></a> <code>getline</code> acts like <a href="#_gets"><strong><code>gets</code></strong></a> and
|
|
the remaining subcommands do nothing.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>history load</strong> <em>filename</em></code>
|
|
</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">
|
|
<code><strong>history getline</strong> <em>prompt ?varname?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Displays the given prompt and allows a line to be entered. Similarly to <a href="#_gets"><strong><code>gets</code></strong></a>,
|
|
if <code><em>varname</em></code> is given, it receives the line and the length of the line is returned,
|
|
or -1 on EOF. If <code><em>varname</em></code> is not given, the line is returned directly.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>history completion</strong> <em>command</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Sets an autocompletion command (see <a href="#_tcl_autocomplete"><strong><code>tcl::autocomplete</code></strong></a>) that is active during <a href="#_history"><strong><code>history</code></strong></a> <code>getline</code>.
|
|
If the command is empty, autocompletion is disabled.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>history add</strong> <em>line</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Adds the given line to the history buffer.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>history save</strong> <em>filename</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Saves the current history buffer to the given file.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>history show</strong></code>
|
|
</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">
|
|
<code><strong>namespace code</strong> <em>script</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Captures the current namespace context for later execution of
|
|
the script <code><em>script</em></code>. It returns a new script in which script has
|
|
been wrapped in a <code><strong>namespace inscope</strong></code> command.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace current</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name for the current namespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace delete</strong> <em>?namespace …?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Deletes all commands and variables with the given namespace prefixes.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace eval</strong> <em>namespace arg ?arg…?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Activates a namespace called <code><em>namespace</em></code> and evaluates some code in that context.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace origin</strong> <em>command</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name of the original command to which the imported command <code><em>command</em></code> refers.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace parent</strong> ?namespace?</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the fully-qualified name of the parent namespace for namespace <code><em>namespace</em></code>, if given, otherwise
|
|
for the current namespace.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace qualifiers</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns any leading namespace qualifiers for <code><em>string</em></code>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace tail</strong> <em>string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Returns the simple name at the end of a qualified string.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace upvar</strong> <em>namespace ?arg…?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This command arranges for zero or more local variables in the current procedure to refer to variables in <code><em>namespace</em></code>
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>namespace which</strong> <em>?-command|-variable? name</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Looks up <code><em>name</em></code> as either a command (the default) or variable and returns its fully-qualified name.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_interp">interp</h3>
|
|
<div class="paragraph"><p>The optional <em>interp</em> command allows sub-interpreters to be created where commands may be run
|
|
independently (but synchronously) of the main interpreter.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>interp</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Creates and returns a new interpreter object (command).
|
|
The created interpreter contains any built-in commands along with static extensions,
|
|
but does not include any dynamically loaded commands (package require, load).
|
|
These must be reloaded in the child interpreter if required.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>$interp delete</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Deletes the interpreter object.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>$interp eval</strong> <em>script</em> …</code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Evaluates a script in the context for the child interpreter, in the same way as <em>eval</em>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>$interp alias</strong> <em>alias childcmd parentcmd ?arg …?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Similar to <em>alias</em>, but creates a command, <code><em>childcmd</em></code>, in the child interpreter that is an
|
|
alias for <code><em>parentcmd</em></code> in the parent interpreter, with the given, fixed arguments.
|
|
The alias may be deleted in the child with <em>rename</em>.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_json_encode">json::encode</h3>
|
|
<div class="paragraph"><p>The Tcl → JSON encoder is part of the optional <em>json</em> package.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>json::encode</strong> <em>value ?schema?</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Encode a Tcl value as JSON according to the schema (defaults to <code><em>str</em></code>). The following schema types are supported:
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
<em>str</em> - Tcl string → JSON string
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>num</em> - Tcl value → bare numeric value or null
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>bool</em> - Tcl boolean value → true, false
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>obj ?name subschema …?</em> - Tcl dict → JSON object. For each dict key matching <em>name</em>, the corresponding <em>subschema</em>
|
|
is applied. The special name <code><em>*</em></code> matches any keys not otherwise matched, otherwise the default <code><em>str</em></code> is used.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>list ?subschema?</em> - Tcl list → JSON array. The <em>subschema</em> (default <code><em>str</em></code>) is applied for each element of the list/array.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<em>mixed ?subschema …?</em> = Tcl list → JSON array. Each <em>subschema</em> is applied for the corresponding element of the list/array.
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The following are examples:
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . json::encode {1 2 true false null 5.0} list
|
|
[ "1", "2", "true", "false", "null", "5.0" ]
|
|
. json::encode {1 2 true false null 5.0} {list num}
|
|
[ 1, 2, true, false, null, 5.0 ]
|
|
. json::encode {0 1 2 true false 5.0 off} {list bool}
|
|
[ false, true, true, true, false, true, false ]
|
|
. json::encode {a 1 b hello c {3 4}} obj
|
|
{ "a":"1", "b":"hello", "c":"3 4" }
|
|
. json::encode {a 1 b hello c {3 4}} {obj a num c {list num}}
|
|
{ "a":1, "b":"hello", "c":[ 3, 4 ] }
|
|
. json::encode {true true {abc def}} {mixed str num obj}
|
|
[ "true", true, { "abc":"def" } ]
|
|
. json::encode {a 1 b 3.0 c hello d null} {obj c str * num}
|
|
{ "a":1, "b":3.0, "c":"hello", "d":null }</code></pre>
|
|
</div></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_json_decode">json::decode</h3>
|
|
<div class="paragraph"><p>The JSON → Tcl decoder is part of the optional <em>json</em> package.</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>json::decode</strong> ?<strong>-index</strong>? ?<strong>-null</strong> <em>string</em>? ?<strong>-schema</strong>? <em>json-string</em></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Decodes the given JSON string (must be array or object) into a Tcl data structure. If <em><code>-index</code></em> is specified,
|
|
decodes JSON arrays as dictionaries with numeric keys. This makes it possible to retrieve data from nested
|
|
arrays and dictionaries with just <em><code>dict get</code></em>. With the option <em><code>-schema</code></em> returns a list of <code><em>{data schema}</em></code>
|
|
where the schema is compatible with <a href="#_json_encode"><strong><code>json::encode</code></strong></a>. Otherwise just returns the data.
|
|
Decoding is as follows (with schema types listed in parentheses):
|
|
</p>
|
|
<div class="ulist"><ul>
|
|
<li>
|
|
<p>
|
|
object → dict (<em>obj</em>)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
array → list (<em>mixed</em> or <em>list</em>)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
number → as-is (<em>num</em>)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
boolean → as-is (<em>bool</em>)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
string → string (<em>str</em>)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
null → supplied null string or the default <code><em>"null"</em></code> (<em>num</em>)
|
|
</p>
|
|
</li>
|
|
</ul></div>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
Note that an object decoded into a dict will return the keys in the same order as the original string.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> . json::decode {[1, 2]}
|
|
{1 2}
|
|
. json::decode -schema {[1, 2]}
|
|
{1 2} {list num}
|
|
. json::decode -schema {{"a":1, "b":2}}
|
|
{a 1 b 2} {obj a num b num}
|
|
. json::decode -schema {[1, 2, {a:"b", c:false}, "hello"]}
|
|
{1 2 {a b c false} hello} {mixed num num {obj a str c bool} str}
|
|
. json::decode -index {["foo", "bar"]}
|
|
{0 foo 1 bar}</code></pre>
|
|
</div></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">
|
|
<code><strong>env</strong></code>
|
|
</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><code>env</code></strong></a> command.
|
|
It may be modified and will affect the environment passed to
|
|
commands invoked with <a href="#_exec"><strong><code>exec</code></strong></a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>platform_tcl</strong></code>
|
|
</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">
|
|
<code><strong>auto_path</strong></code>
|
|
</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. <code>/usr/local/lib/jim</code>), but may be changed by <code>jimsh</code>
|
|
or the embedding application. Note that <code>jimsh</code> will consider
|
|
the environment variable <code>$JIMLIB</code> to be a list of colon-separated
|
|
list of paths to add to <code><strong>auto_path</strong></code>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>errorCode</strong></code>
|
|
</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><code>exec</code></strong></a> sets this variable.
|
|
Otherwise it will be <code>NONE</code>.
|
|
</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">
|
|
<code><strong>tcl_interactive</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
This variable is set to 1 if jimsh is started in interactive mode
|
|
or 0 otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>tcl_platform</strong></code>
|
|
</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>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre><code> tcl_platform(byteOrder) = littleEndian
|
|
tcl_platform(engine) = Jim
|
|
tcl_platform(os) = Darwin
|
|
tcl_platform(platform) = unix
|
|
tcl_platform(pointerSize) = 8
|
|
tcl_platform(threaded) = 0
|
|
tcl_platform(wordSize) = 8
|
|
tcl_platform(pathSeparator) = :</code></pre>
|
|
</div></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>argv0</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If jimsh is invoked to run a script, this variable contains the name
|
|
of the script.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>argv</strong></code>
|
|
</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">
|
|
<code><strong>argc</strong></code>
|
|
</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">
|
|
<code><strong>jim::argv0</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
The value of argv[0] when jimsh was invoked.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
<div class="paragraph"><p>The following variables have special meaning to Jim Tcl:</p></div>
|
|
<div class="dlist"><dl>
|
|
<dt class="hdlist1">
|
|
<code><strong>jim::defer</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If this variable is set, it is considered to be a list of scripts to evaluate
|
|
when the current proc exits (local variables), or the interpreter exits (global variable).
|
|
See <a href="#_defer"><strong><code>defer</code></strong></a>.
|
|
</p>
|
|
</dd>
|
|
<dt class="hdlist1">
|
|
<code><strong>history::multiline</strong></code>
|
|
</dt>
|
|
<dd>
|
|
<p>
|
|
If this variable is set to "1", interactive line editing operates in multiline mode.
|
|
That is, long lines will wrap across multiple lines rather than scrolling within a
|
|
single line.
|
|
</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_74">In v0.74</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
Numbers with leading zeros are treated as decimal, not octal
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_aio"><strong><code>aio</code></strong></a> <code>isatty</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add LFS (64 bit) support for <a href="#_aio"><strong><code>aio</code></strong></a> <code>seek</code>, <a href="#_aio"><strong><code>aio</code></strong></a> <code>tell</code>, <a href="#_aio"><strong><code>aio</code></strong></a> <code>copyto</code>, <a href="#_file"><strong><code>file</code></strong></a> <code>copy</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_string"><strong><code>string</code></strong></a> <code>compare</code> and <a href="#_string"><strong><code>string</code></strong></a> <code>equal</code> now support <em>-length</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_glob"><strong><code>glob</code></strong></a> now supports <em>-directory</em>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_73">In v0.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><code>string</code></strong></a> <code>replace</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_string"><strong><code>string</code></strong></a> <code>totitle</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><code>info</code></strong></a> <code>statics</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <code>build-jim-ext</code> for easy separate building of loadable modules (extensions)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><code>local</code></strong></a> now works with any command, not just procs
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><code>info</code></strong></a> <code>alias</code> 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><code>tcl::prefix</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_history"><strong><code>history</code></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><code>namespace</code></strong></a> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_apply"><strong><code>apply</code></strong></a>
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_72">In v0.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, <code>rand()</code>, <code>srand()</code> and <code>pow()</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for the <em>-force</em> option to <a href="#_file"><strong><code>file</code></strong></a> <code>delete</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Better diagnostics when <a href="#_source"><strong><code>source</code></strong></a> fails to load a script with a missing quote or bracket
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
New <code>tcl_platform(pathSeparator)</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support settings the modification time with <a href="#_file"><strong><code>file</code></strong></a> <code>mtime</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_exec"><strong><code>exec</code></strong></a> is now fully supported on win32 (mingw32)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_file"><strong><code>file</code></strong></a> <code>join</code>, <a href="#_pwd"><strong><code>pwd</code></strong></a>, <a href="#_glob"><strong><code>glob</code></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><code>aio</code></strong></a> <code>listen</code> command
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_71">In v0.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 <code>$(…)</code> shorthand syntax for expressions
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add automatic reference variables in procs with <code>&var</code> syntax
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Support <code>jimsh --version</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Additional variables in <code>tcl_platform()</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><code>local</code></strong></a> procs now push existing commands and <a href="#_upcall"><strong><code>upcall</code></strong></a> can call them
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_loop"><strong><code>loop</code></strong></a> command (TclX compatible)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_aio"><strong><code>aio</code></strong></a> <code>buffering</code> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_info"><strong><code>info</code></strong></a> <code>complete</code> can now return the missing character
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_binary"><strong><code>binary</code></strong></a> <code>format</code> and <a href="#_binary"><strong><code>binary</code></strong></a> <code>scan</code> are now (optionally) supported
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_string"><strong><code>string</code></strong></a> <code>byterange</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Built-in regexp now support non-greedy repetition (*?, +?, ??)
|
|
</p>
|
|
</li>
|
|
</ol></div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_in_v0_70">In v0.70</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<code>platform_tcl()</code> settings are now automatically determined
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add aio <code>$handle filename</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_info"><strong><code>info</code></strong></a> <code>channels</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <em>bio</em> extension is gone. Now <a href="#_aio"><strong><code>aio</code></strong></a> supports <em>copyto</em>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_exists"><strong><code>exists</code></strong></a> command
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add the pure-Tcl <em>oo</em> extension
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The <a href="#_exec"><strong><code>exec</code></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 class="sect2">
|
|
<h3 id="_in_v0_63">In v0.63</h3>
|
|
<div class="olist arabic"><ol class="arabic">
|
|
<li>
|
|
<p>
|
|
<a href="#_source"><strong><code>source</code></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><code>stacktrace</code></strong></a> and <a href="#_stackdump"><strong><code>stackdump</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_tailcall"><strong><code>tailcall</code></strong></a> no longer loses stack trace information
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add <a href="#_alias"><strong><code>alias</code></strong></a> and <a href="#_curry"><strong><code>curry</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_alias"><strong><code>alias</code></strong></a> and <a href="#_curry"><strong><code>curry</code></strong></a> are implemented via <a href="#_tailcall"><strong><code>tailcall</code></strong></a> for efficiency
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_local"><strong><code>local</code></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><code>return</code></strong></a> from within <a href="#_try"><strong><code>try</code></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><code>exec</code></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><code>pid</code></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 <code>'ms</em></code><em>, 'after idle</em>, <em>after info</em>, <a href="#cmd_2"><strong><code>update</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
<a href="#_exec"><strong><code>exec</code></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><code>exec</code></strong></a> for <em>>&</em>, <em>>>&</em>, <em>|&</em>, <em>2>@1</em>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fix <a href="#_exec"><strong><code>exec</code></strong></a> error messages when special token (e.g. <em>></em>) is the last token
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fix <a href="#_subst"><strong><code>subst</code></strong></a> handling of backslash escapes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow abbreviated options for <a href="#_subst"><strong><code>subst</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for <a href="#_return"><strong><code>return</code></strong></a>, <a href="#_break"><strong><code>break</code></strong></a>, <a href="#_continue"><strong><code>continue</code></strong></a> in subst
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Many <a href="#_expr"><strong><code>expr</code></strong></a> bug fixes
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Add support for functions in <a href="#_expr"><strong><code>expr</code></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><code>regsub</code></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><code>lassign</code></strong></a>, <a href="#_lrepeat"><strong><code>lrepeat</code></strong></a>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fully-functional <a href="#_lsearch"><strong><code>lsearch</code></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><code>catch</code></strong></a> to determine what return codes are caught
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Allow <a href="#_incr"><strong><code>incr</code></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><code>proc</code></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><code>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></code></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>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.</code></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>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.</code></pre>
|
|
</div></div>
|
|
<div class="literalblock">
|
|
<div class="content">
|
|
<pre><code>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.</code></pre>
|
|
</div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footnotes"><hr /></div>
|
|
<div id="footer">
|
|
</div>
|
|
</body>
|
|
</html>
|