| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.10"> |
| <meta name="author" content="Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation"> |
| <link rel="icon" type="image/png" href="favicon.png"> |
| <title>ToolDef documentation (Incubation)</title> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
| <style> |
| /* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ |
| /* Uncomment @import statement to use as custom stylesheet */ |
| /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
| article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block} |
| audio,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| a{background:none} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| abbr[title]{border-bottom:1px dotted} |
| b,strong{font-weight:bold} |
| dfn{font-style:italic} |
| hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
| html,body{font-size:100%} |
| body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .center{margin-left:auto;margin-right:auto} |
| .stretch{width:100%} |
| .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
| div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:0} |
| p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
| h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
| ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
| ul.square{list-style-type:square} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
| abbr{text-transform:none} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
| blockquote cite::before{content:"\2014 \0020"} |
| blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} |
| table thead,table tfoot{background:#f7f8f7} |
| table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt{background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
| .clearfix::after,.float-group::after{clear:both} |
| :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} |
| :not(pre)>code.nobreak{word-wrap:normal} |
| :not(pre)>code.nowrap{white-space:nowrap} |
| pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
| pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
| pre>code{display:block} |
| pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
| em em{font-style:normal} |
| strong strong{font-weight:400} |
| .keyseq{color:rgba(51,51,51,.8)} |
| kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menuref{color:#000} |
| .menuseq b:not(.caret),.menuref{font-weight:inherit} |
| .menuseq{word-spacing:-.02em} |
| .menuseq b.caret{font-size:1.25em;line-height:.8} |
| .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
| b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} |
| b.button::before{content:"[";padding:0 3px 0 2px} |
| b.button::after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} |
| #header::after,#content::after,#footnotes::after,#footer::after{clear:both} |
| #content{margin-top:1.25em} |
| #content::before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span::before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark::before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber::after{content:"\00a0"} |
| #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} |
| @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| #content{margin-bottom:.625em} |
| .sect1{padding-bottom:.625em} |
| @media screen and (min-width:768px){#content{margin-bottom:1.25em} |
| .sect1{padding-bottom:1.25em}} |
| .sect1:last-child{padding-bottom:0} |
| .sect1+.sect1{border-top:1px solid #e7e7e9} |
| #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
| #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
| #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
| #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
| #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
| details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em} |
| .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
| table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
| .exampleblock>.content>:first-child{margin-top:0} |
| .exampleblock>.content>:last-child{margin-bottom:0} |
| .sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px} |
| .sidebarblock>:first-child{margin-top:0} |
| .sidebarblock>:last-child{margin-bottom:0} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
| .literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em} |
| @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
| @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
| .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
| .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
| .listingblock>.content{position:relative} |
| .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} |
| .listingblock:hover code[data-lang]::before{display:block} |
| .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
| .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .prettyprint{background:#f7f7f8} |
| pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
| pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
| pre.prettyprint li code[data-lang]::before{opacity:1} |
| pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
| table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
| table.linenotable td.code{padding-left:.75em} |
| table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em} |
| pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em} |
| pre.pygments .lineno::before{content:"";margin-right:-.125em} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} |
| .verseblock{margin:0 1em 1.25em} |
| .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
| .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} |
| .quoteblock.abstract{margin:0 1em 1.25em;display:block} |
| .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
| .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
| .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
| .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
| .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} |
| table.tableblock{max-width:100%;border-collapse:separate} |
| p.tableblock:last-child{margin-bottom:0} |
| td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
| td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} |
| table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} |
| table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} |
| table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} |
| table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} |
| table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} |
| table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} |
| table.frame-all{border-width:1px} |
| table.frame-sides{border-width:0 1px} |
| table.frame-topbot,table.frame-ends{border-width:1px 0} |
| table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
| ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
| ul.unstyled,ol.unstyled{margin-left:0} |
| ul.checklist{margin-left:.625em} |
| ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} |
| ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
| ul.inline>li{margin-left:1.25em} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| 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} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
| .colist td:not([class]):first-child img{max-width:none} |
| .colist td:not([class]):last-child{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left{margin:.25em .625em 1.25em 0} |
| .imageblock.right{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
| .gist .file-data>table td.line-data{width:99%} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background:#00fafa} |
| .black{color:#000} |
| .black-background{background:#000} |
| .blue{color:#0000bf} |
| .blue-background{background:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background:#00007d} |
| .olive{color:#606000} |
| .olive-background{background:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background:#fafa00} |
| span.icon>.fa{cursor:default} |
| a span.icon>.fa{cursor:inherit} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} |
| .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]::after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @page{margin:1.25cm .75cm} |
| @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| html{font-size:80%} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]::after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span::before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]::before{display:block} |
| #footer{padding:0 .9375em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} |
| .sect1{padding:0!important} |
| .sect1+.sect1{border:0} |
| #footer{background:none} |
| #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
| @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
| </style> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
| <!-- |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| <style> |
| .menu, .submenu, .menuitem, .menuref { |
| background-color: Menu; |
| } |
| |
| .button { |
| border: 1px solid ButtonFace; |
| /* |
| Styling too similar to a real button is considered bad practice, see https://github.com/asciidoctor/asciidoctor/issues/1881#issuecomment-250702085 |
| border: 2px outset ButtonFace; |
| background-color: ButtonFace; |
| */ |
| padding-left: 0.5ex; |
| padding-right: 0.5ex; |
| font-weight: normal; |
| font-family: "Segoe UI","Open Sans","DejaVu Sans",sans-serif; |
| white-space: nowrap; |
| } |
| .button:before { |
| content: none !important; |
| } |
| .button:after { |
| content: none !important; |
| } |
| |
| #footer-text, #footer-text a { |
| color: rgba(255,255,255,.8) |
| } |
| </style> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>ToolDef documentation (Incubation)</h1> |
| <div class="details"> |
| <span id="author" class="author">Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation</span><br> |
| <span id="revnumber">version 0.1.0.20210126-175926</span> |
| </div> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#introduction-chapter-index">Introduction</a></li> |
| <li><a href="#lang-ref-chapter-index">Language reference</a> |
| <ul class="sectlevel2"> |
| <li><a href="#lang-ref-syntax">Syntax</a> |
| <ul class="sectlevel3"> |
| <li><a href="#lang-ref-syntax-lexical">Lexical syntax</a></li> |
| <li><a href="#lang-ref-syntax-grammar">Grammar</a></li> |
| </ul> |
| </li> |
| <li><a href="#lang-ref-built-in-tools-and-operators">Built-in tools and operators</a> |
| <ul class="sectlevel3"> |
| <li><a href="#lang-ref-builtins-operators">Built-in operators</a></li> |
| <li><a href="#lang-ref-builtins-data">Built-in data tools</a></li> |
| <li><a href="#lang-ref-builtins-io">Built-in I/O tools</a></li> |
| <li><a href="#lang-ref-builtins-generic">Built-in generic tools</a></li> |
| <li><a href="#lang-ref-builtins-path">Built-in path tools</a></li> |
| <li><a href="#lang-ref-builtins-file">Built-in file tools</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#tools-chapter-index">Tooling</a> |
| <ul class="sectlevel2"> |
| <li><a href="#tools-command-line">Command line</a></li> |
| <li><a href="#tools-eclipse-ide">Eclipse IDE</a></li> |
| </ul> |
| </li> |
| <li><a href="#release-notes-chapter-index">ToolDef release notes</a> |
| <ul class="sectlevel2"> |
| <li><a href="#version-0-1-unreleased">Version 0.1 (unreleased)</a></li> |
| </ul> |
| </li> |
| <li><a href="#legal-chapter-index">Legal</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>ToolDef is a cross-platform and machine-independent scripting language. |
| It supports command line execution, but is also available as plug-in for |
| the <a href="https://eclipse.org">Eclipse</a> IDE, providing an integrated development |
| experience.</p> |
| </div> |
| <div class="paragraph"> |
| <p>ToolDef is one of the tools of the |
| <a href="https://eclipse.org/escet">Eclipse ESCET™ project</a>.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project, including the ToolDef language and toolset, |
| is currently in the |
| <a href="https://wiki.eclipse.org/Development_Resources/Process_Guidelines/What_is_Incubation">Incubation Phase</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="./eclipse-incubation.png" alt="eclipse incubation" width="300"></span></p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| You can <a href="eclipse-escet-incubation-tooldef-manual.pdf">download this manual</a> |
| as a PDF as well. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The documentation consists of:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-chapter-index">ToolDef language reference manual</a></p> |
| </li> |
| <li> |
| <p><a href="#tools-chapter-index">ToolDef tool manual</a></p> |
| </li> |
| <li> |
| <p><a href="#release-notes-chapter-index">ToolDef release notes</a></p> |
| </li> |
| <li> |
| <p><a href="#legal-chapter-index">Legal information</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Some screenshots of ToolDef editing and execution:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./screenshot_ide.png" alt="screenshot ide"> |
| </div> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./screenshot_cmdline.png" alt="screenshot cmdline"> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="introduction-chapter-index">Introduction</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>The ToolDef language features the following concepts:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Simple and intuitive syntax makes it easy to writing scripts.</p> |
| </li> |
| <li> |
| <p>A large number of built-in data types, including booleans, integers, longs, |
| doubles, strings, lists, sets, maps, tuples, and objects.</p> |
| </li> |
| <li> |
| <p>Static typing allows to catch simple mistakes.</p> |
| </li> |
| <li> |
| <p>The type system is compatible with <a href="http://oracle.com/java">Java</a>, |
| allowing easy integration with existing Java code.</p> |
| </li> |
| <li> |
| <p>A large library of useful built-in operators and tools, including tools to |
| write to the console, to start applications or execute other ToolDef scripts, |
| to manipulate paths, to interact with files and directories, and to |
| manipulate data of the various supported data types.</p> |
| </li> |
| <li> |
| <p>Easy to extend with new tools, written in ToolDef itself, or in |
| <a href="http://oracle.com/java">Java</a>.</p> |
| </li> |
| <li> |
| <p>Tools can be parameterized with types.</p> |
| </li> |
| <li> |
| <p>Tools can be overloaded.</p> |
| </li> |
| <li> |
| <p>Tools can have optional parameters.</p> |
| </li> |
| <li> |
| <p>Tools can have a variable number of arguments.</p> |
| </li> |
| <li> |
| <p>Tool invocations can use both positional and named arguments.</p> |
| </li> |
| <li> |
| <p>Tools can return a single value, multiple values, or no values at all.</p> |
| </li> |
| <li> |
| <p>Automatic type widening.</p> |
| </li> |
| <li> |
| <p>Type declarations allow for reuse.</p> |
| </li> |
| <li> |
| <p>Value semantics for ease of use.</p> |
| </li> |
| <li> |
| <p>The usual imperative statements, including assignments, tool invocation, |
| <code>if</code> statement, <code>for</code> statement, <code>while</code> statement, <code>return</code> |
| statement, <code>exit</code> statement, <code>break</code> statement, and <code>continue</code> |
| statement.</p> |
| </li> |
| <li> |
| <p>Powerful assignment statement, including partial variable assignment, and |
| multi-assignments.</p> |
| </li> |
| <li> |
| <p>Variable declarations as statements, allowing variables to be declared in |
| the middle of scripts, or in scopes, such as in bodies of <code>for</code> statements.</p> |
| </li> |
| <li> |
| <p>Powerful <code>for</code> statement, allowing tuple unpacking, and iteration over |
| values of various data types.</p> |
| </li> |
| <li> |
| <p>A powerful import mechanism, allowing reuse of scripts, tools, and code.</p> |
| </li> |
| <li> |
| <p>A registered library mechanism, allowing easy importing of libraries of |
| tools.</p> |
| </li> |
| <li> |
| <p>Platform independent path handling, allowing a single script with relative |
| paths to be executed on Window, Linux, and Mac OS X.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For more information, see also the <a href="#lang-ref-chapter-index">language reference</a> documentation.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>The ToolDef tooling features:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Platform and machine independent execution of ToolDef scripts, on Microsoft |
| Windows, Linux, and Mac OS X.</p> |
| </li> |
| <li> |
| <p>Command line execution.</p> |
| </li> |
| <li> |
| <p>Tight integration with the <a href="https://eclipse.org">Eclipse</a> IDE.</p> |
| </li> |
| <li> |
| <p>User-friendly error messages.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For more information, see also the <a href="#tools-chapter-index">tool</a> documentation.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="lang-ref-chapter-index">Language reference</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The documentation in this language reference manual serves as reference. |
| It is not intended to be read from beginning to end, but more to look up |
| specific information when needed. The reference documentation generally |
| provides detailed and complete information, but this information may not |
| always be presented in the most accessible way.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The information is divided into categories. The following categories and |
| information is part of the language reference documentation:</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Syntax</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-syntax-lexical">Lexical syntax</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-syntax-grammar">Grammar</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in tools and operators</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-operators">Built-in operators</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data">Built-in data tools</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-io">Built-in I/O tools</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-generic">Built-in generic tools</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path">Built-in path tools</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file">Built-in file tools</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="lang-ref-syntax">Syntax</h3> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-syntax-lexical">Lexical syntax</h4> |
| <div class="paragraph"> |
| <p>This page describes the ToolDef lexical syntax.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-keywords">Keywords</h5> |
| <div class="paragraph"> |
| <p><em>General</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">as else if map tool |
| bool end import null true |
| break exit in object tuple |
| continue false int return type |
| double for list set while |
| elif from long string</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Operators</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">and div mod not or</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in data tools</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">abs enumerate log reverse str |
| ceil floor lower round strdup |
| contains fmt ltrim rtrim subset |
| del indexof max size trim |
| delidx join min sorted upper |
| empty keys pow split values |
| endswith lastindexof range sqrt |
| entries ln replace startswith</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in I/O tools</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">err errln out outln</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in generic tools</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">app exec tooldef</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in path tools</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">abspath dirname |
| basename fileext |
| chdir hasfileext |
| chfileext pathjoin |
| curdir scriptpath</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><em>Built-in file tools</em></p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">cpdir filenewer isfile readlines |
| cpfile filesize mkdir rmdir |
| diff find mvdir rmfile |
| exists isdir mvfile writefile</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-terminals">Terminals</h5> |
| <div class="paragraph"> |
| <p>Besides the keyword terminals listed above, ToolDef features several other |
| terminals:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>IDENTIFIERTK</code></dt> |
| <dd> |
| <p>An identifier. Defined by the regular expression: |
| <code>[$]?[a-zA-Z_][a-zA-Z0-9_]*</code>. They thus consist of letters, numbers |
| and underscore characters (<code>_</code>). Identifiers may not start with a |
| numeric digit. Keywords take priority over identifiers. To use a |
| keyword as an identifier, prefix it with a <code>$</code> character. |
| The <code>$</code> is not part of the identifier name.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">apple // identifier |
| bear // identifier |
| int // keyword |
| $int // identifier 'int' (override keyword priority with $)</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>RELATIVENAMETK</code></dt> |
| <dd> |
| <p>A name. Defined by the regular expression: |
| <code>[$]?[a-zA-Z_][a-zA-Z0-9_]*(\.[$]?[a-zA-Z_][a-zA-Z0-9_]*)+</code>. |
| It thus consists of two or more <code>IDENTIFIERTK</code> joined together |
| with periods (<code>.</code>).</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">some_library.some_tool</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>NUMBERTK</code></dt> |
| <dd> |
| <p>An integer literal. Defined by the regular expression: <code>0|[1-9][0-9]*</code>. |
| Integers thus consist of numeric digits. Only for the number <code>0</code> may an |
| integer literal start with <code>0</code>. E.g. <code>02</code> is invalid.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">0 |
| 1 |
| 123</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>DOUBLETK</code></dt> |
| <dd> |
| <p>A double literal. Defined by the regular expression: |
| <code>(0|[1-9][0-9]*)(\.[0-9]+|(\.[0-9]+)?[eE][\-\+]?[0-9]+)</code>. |
| Simple double literals consist of an integer literal followed by |
| a period (<code>.</code>) and some numeric digits. Double literals using scientific |
| notation start with either an integer literal or a simple double literal. |
| They then contain either an <code>e</code> or <code>E</code>, followed by the exponent. |
| The exponent consists of numeric digits, optionally preceded by <code>+</code> or <code>-</code>.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">0.0 |
| 1e5 |
| 1E+03 |
| 1.05e-78</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>STRINGTK</code></dt> |
| <dd> |
| <p>A string literal. Defined by the regular expression: |
| <code>\"([^\\\"\n]|\\[nt\\\"])*\"</code>. String literals are enclosed in double |
| quotes (<code>"</code>). String literals must be on a single line and must thus not |
| include new line characters (<code>\n</code>, Unicode U+0A). To include a double quote |
| (<code>"</code>) in a string literal, it must be escaped as <code>\"</code>. Since a |
| backslash (<code>\</code>) serves as escape character, to include a backslash in a string |
| literal it must be escaped as <code>\\</code>. To include a tab character in a string |
| literal, use <code>\t</code>. To include a newline in a string literal, use <code>\n</code>.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">"hello world" |
| "first line\nsecond line"</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-whitespace">Whitespace</h5> |
| <div class="paragraph"> |
| <p>ToolDef supports spaces, tabs, and new line characters as whitespace. |
| Whitespace is ignored (except in string literals), but can be used to separate |
| tokens as well as for layout purposes. The use of tab characters is allowed, |
| but should be avoided if possible, as layout will be different for text |
| editors with different tab settings. You may generally format a ToolDef |
| script as you see fit, and start on a new line when desired.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">// Normal layout. |
| int x = 5; |
| |
| // Alternative layout. |
| int |
| x = |
| 5 |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-comments">Comments</h5> |
| <div class="paragraph"> |
| <p>ToolDef features two types of comments. Single line comments start with |
| <code>//</code> and end at end of the line. Multi line comments start with <code>/*</code> and |
| end at <code>*/</code>. Comments are ignored.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">int x = 5; // Single line comment. |
| |
| int /* some comment */ x = /* some |
| more comments |
| and some more |
| end of the multi line comment */ 5;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-syntax-grammar">Grammar</h4> |
| <div class="paragraph"> |
| <p>Below, the <a href="http://en.wikipedia.org/wiki/Formal_grammar">grammar</a> of the |
| ToolDef language is shown, in a form closely resembling |
| <a href="http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form">Backus-Naur Form</a> |
| (BNF). The <code>Script</code> |
| <a href="http://en.wikipedia.org/wiki/Nonterminal_symbol">non-terminal</a> is the |
| <a href="http://en.wikipedia.org/wiki/Start_symbol_(formal_languages)">start symbol</a> |
| of the grammar. Text between quotes are terminals. Names using only upper case |
| letters are defined in the <a href="#lang-ref-syntax-lexical">lexical syntax</a>. The |
| remaining names are the non-terminals of the grammar.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="bnf">Script : /* empty */ |
| | Decls |
| ; |
| |
| Decls : Decl |
| | Decls Decl |
| ; |
| |
| Decl : Import |
| | "type" TypeDecls ";" |
| | "tool" IDENTIFIERTK OptTypeParams ToolParameters ":" OptStatements "end" |
| | "tool" Types IDENTIFIERTK OptTypeParams ToolParameters ":" OptStatements "end" |
| | Statement |
| ; |
| |
| Import : "import" STRINGTK ";" |
| | "import" STRINGTK "as" IDENTIFIERTK ";" |
| | "import" Name ";" |
| | "import" Name "as" IDENTIFIERTK ";" |
| | "import" Name ":" Name ";" |
| | "import" Name ":" Name "as" IDENTIFIERTK ";" |
| | "from" STRINGTK "import" ImportParts ";" |
| ; |
| |
| ImportParts : "*" |
| | IDENTIFIERTK |
| | IDENTIFIERTK "as" IDENTIFIERTK |
| | ImportParts "," "*" |
| | ImportParts "," IDENTIFIERTK |
| | ImportParts "," IDENTIFIERTK "as" IDENTIFIERTK |
| ; |
| |
| TypeDecls : TypeDecl |
| | TypeDecls "," TypeDecl |
| ; |
| |
| TypeDecl : IDENTIFIERTK "=" Type |
| ; |
| |
| OptTypeParams : /* empty */ |
| | "<" Names ">" |
| ; |
| |
| ToolParameters : "(" ")" |
| | "(" ToolParams ")" |
| ; |
| |
| ToolParams : Type ToolParam |
| | Type "..." ToolParam |
| | ToolParams "," Type ToolParam |
| | ToolParams "," Type "..." ToolParam |
| ; |
| |
| ToolParam : IDENTIFIERTK |
| | IDENTIFIERTK "=" Expression |
| ; |
| |
| OptStatements : /* empty */ |
| | OptStatements Statement |
| ; |
| |
| Statement : Type VarDecls ";" |
| | "while" Expression ":" OptStatements "end" |
| | "while" Expression "::" Statement |
| | "for" AddressableDecls "in" Expression ":" OptStatements "end" |
| | "for" AddressableDecls "in" Expression "::" Statement |
| | "if" Expression ":" OptStatements OptElifStatements OptElseStatement "end" |
| | "if" Expression "::" Statement |
| | "break" ";" |
| | "continue" ";" |
| | Addressables "=" Expressions ";" |
| | "return" ";" |
| | "return" Expressions ";" |
| | ToolInvokeExpression ";" |
| | "exit" ";" |
| | "exit" Expression ";" |
| ; |
| |
| VarDecls : VarDecl |
| | VarDecls "," VarDecl |
| ; |
| |
| VarDecl : IDENTIFIERTK |
| | IDENTIFIERTK "=" Expression |
| ; |
| |
| OptElifStatements : /* empty */ |
| | OptElifStatements "elif" Expression ":" OptStatements |
| ; |
| |
| OptElseStatement : /* empty */ |
| | "else" OptStatements |
| ; |
| |
| AddressableDecls : AddressableDecl |
| | AddressableDecls "," AddressableDecl |
| ; |
| |
| AddressableDecl : IDENTIFIERTK |
| | "(" AddressableDecl "," AddressableDecls ")" |
| ; |
| |
| Addressables : Addressable |
| | Addressables "," Addressable |
| ; |
| |
| Addressable : IDENTIFIERTK |
| | IDENTIFIERTK Projections |
| | "(" Addressable "," Addressables ")" |
| ; |
| |
| Projections : Projection |
| | Projections Projection |
| ; |
| |
| Projection : "[" Expression "]" |
| ; |
| |
| Types : Type |
| | Types "," Type |
| ; |
| |
| Type : "bool" |
| | "bool" "?" |
| | "int" |
| | "int" "?" |
| | "long" |
| | "long" "?" |
| | "double" |
| | "double" "?" |
| | "string" |
| | "string" "?" |
| | "list" Type |
| | "list" "?" Type |
| | "set" Type |
| | "set" "?" Type |
| | "map" "(" Type ":" Type ")" |
| | "map" "?" "(" Type ":" Type ")" |
| | "tuple" "(" Type "," Types ")" |
| | "tuple" "?" "(" Type "," Types ")" |
| | "object" |
| | "object" "?" |
| | Name |
| ; |
| |
| Expressions : Expression |
| | Expressions "," Expression |
| ; |
| |
| OptExpression : /* empty */ |
| | Expression |
| ; |
| |
| Expression : AndExpression |
| | Expression "or" AndExpression |
| ; |
| |
| AndExpression : CompareExpression |
| | AndExpression "and" CompareExpression |
| ; |
| |
| CompareExpression : AddExpression |
| | CompareExpression "<" AddExpression |
| | CompareExpression "<=" AddExpression |
| | CompareExpression "==" AddExpression |
| | CompareExpression "!=" AddExpression |
| | CompareExpression ">=" AddExpression |
| | CompareExpression ">" AddExpression |
| ; |
| |
| AddExpression : MulExpression |
| | AddExpression "-" MulExpression |
| | AddExpression "+" MulExpression |
| ; |
| |
| MulExpression : UnaryExpression |
| | MulExpression "*" UnaryExpression |
| | MulExpression "/" UnaryExpression |
| | MulExpression "div" UnaryExpression |
| | MulExpression "mod" UnaryExpression |
| ; |
| |
| UnaryExpression : ProjExpression |
| | "-" UnaryExpression |
| | "+" UnaryExpression |
| | "not" UnaryExpression |
| ; |
| |
| ProjExpression : ExpressionFactor |
| | ProjExpression "[" Expression "]" |
| | ProjExpression "[" OptExpression ":" OptExpression "]" |
| ; |
| |
| ExpressionFactor : "true" |
| | "false" |
| | NUMBERTK |
| | DOUBLETK |
| | "null" |
| | STRINGTK |
| | "<" Type ">" ExpressionFactor |
| | "[" "]" |
| | "[" Expressions OptComma "]" |
| | "{" "}" |
| | "{" Expressions OptComma "}" |
| | "{" MapEntries OptComma "}" |
| | "(" Expression "," Expressions OptComma ")" |
| | "(" Expression ")" |
| | ToolInvokeExpression |
| | Name |
| ; |
| |
| MapEntries : Expression ":" Expression |
| | MapEntries "," Expression ":" Expression |
| ; |
| |
| ToolInvokeExpression : ToolRef "(" ToolArgs OptComma ")" |
| | ToolRef "(" ")" |
| ; |
| |
| ToolRef : BuiltInTool |
| | Name |
| ; |
| |
| BuiltInTool : BuiltInIoTool |
| | BuiltInGenericTool |
| | BuiltInPathTool |
| | BuiltInFileTool |
| | BuiltInDataTool |
| ; |
| |
| ToolArgs : Expression |
| | IDENTIFIERTK "=" Expression |
| | ToolArgs "," Expression |
| | ToolArgs "," IDENTIFIERTK "=" Expression |
| ; |
| |
| Names : Name |
| | Names "," Name |
| ; |
| |
| Name : IDENTIFIERTK |
| | RELATIVENAMETK |
| ; |
| |
| OptComma : /* empty */ |
| | "," |
| ; |
| |
| BuiltInIoTool : "err" |
| | "errln" |
| | "out" |
| | "outln" |
| ; |
| |
| BuiltInGenericTool : "app" |
| | "exec" |
| | "tooldef" |
| ; |
| |
| BuiltInPathTool : "abspath" |
| | "basename" |
| | "chdir" |
| | "chfileext" |
| | "curdir" |
| | "dirname" |
| | "fileext" |
| | "hasfileext" |
| | "pathjoin" |
| | "scriptpath" |
| ; |
| |
| BuiltInFileTool : "cpdir" |
| | "cpfile" |
| | "diff" |
| | "exists" |
| | "filenewer" |
| | "filesize" |
| | "find" |
| | "isdir" |
| | "isfile" |
| | "mkdir" |
| | "mvdir" |
| | "mvfile" |
| | "readlines" |
| | "rmdir" |
| | "rmfile" |
| | "writefile" |
| ; |
| |
| BuiltInDataTool : "abs" |
| | "ceil" |
| | "contains" |
| | "del" |
| | "delidx" |
| | "empty" |
| | "endswith" |
| | "entries" |
| | "enumerate" |
| | "floor" |
| | "fmt" |
| | "indexof" |
| | "join" |
| | "keys" |
| | "lastindexof" |
| | "ln" |
| | "log" |
| | "lower" |
| | "ltrim" |
| | "max" |
| | "min" |
| | "pow" |
| | "range" |
| | "replace" |
| | "reverse" |
| | "round" |
| | "rtrim" |
| | "size" |
| | "sorted" |
| | "split" |
| | "sqrt" |
| | "startswith" |
| | "str" |
| | "strdup" |
| | "subset" |
| | "trim" |
| | "upper" |
| | "values" |
| ;</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="lang-ref-built-in-tools-and-operators">Built-in tools and operators</h3> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-operators">Built-in operators</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in operators:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-not">not</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-and">and</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-or">or</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-plus-unary">+ (unary)</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-dash-unary">- (unary)</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-plus-binary">+ (binary)</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-dash-binary">- (binary)</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-star">*</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-slash">/</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-div">div</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-mod">mod</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-lt"><</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-le"><=</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-gt">></a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-ge">>=</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-eq">==</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-operators-ne">!=</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The signatures of the operators are given using tool headers, to show the name |
| of the operator, the types of the arguments, and the type of the resulting |
| value. Operators however, can not be used by means of tool invocations. |
| Operators with one argument are put directly before the argument (e.g. |
| <code>not true</code>, <code>-5</code>), while operators with two arguments are put between the |
| arguments (e.g. <code>true and false</code>, <code>1 + 3</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-not">not operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool not(bool arg)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the logical inverse of a boolean value.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>arg</code></dt> |
| <dd> |
| <p>The boolean value.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The logical inverse result.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-and">and operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool and(bool left, bool right) |
| tool set T and<T>(set T left, set T right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the conjunction of two boolean values, or the intersection of two sets. |
| For boolean values, the operator uses short circuit evaluation. That is, the |
| <code>right</code> argument is only evaluated if necessary, i.e. only if the <code>left</code> |
| argument evaluates to <code>true</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first boolean value or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second boolean value or set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The conjunction or intersection result.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-or">or operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool or(bool left, bool right) |
| tool set T or<T>(set T left, set T right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the disjunction of two boolean values, or the union of two sets. |
| For boolean values, the operator uses short circuit evaluation. That is, the |
| <code>right</code> argument is only evaluated if necessary, i.e. only if the <code>left</code> |
| argument evaluates to <code>false</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first boolean value or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second boolean value or set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The disjunction or union result.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-plus-unary">+ operator (unary)</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int +(int arg) |
| tool long +(long arg) |
| tool double +(double arg)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the unary plus of an integer, long, or double value. This is |
| essentially the |
| <a href="http://en.wikipedia.org/wiki/Identity_function">identity function</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>arg</code></dt> |
| <dd> |
| <p>The integer, long, or double value.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The integer, long, or double value.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-plus-binary">+ operator (binary)</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int +(int left, int right) |
| tool long +(long left, long right) |
| tool double +(double left, double right) |
| tool string +(string left, string right) |
| tool list T +<T>(list T left, list T right) |
| tool map(K:V) +<K, V>(map(K:V) left, map(K:V) right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the addition of two integer, long, or double numbers, the concatenation |
| of two strings or lists, or the update of a first map with the entries of a |
| second map. For two maps, essentially, the entries of the first map are |
| overwritten by the entries of the second map, while entries for new keys are |
| added.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number, string, list, or map.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number, string, list, or map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The addition, concatenation, or map update result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow (for integer, long, and double numbers |
| only).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-dash-unary">- operator (unary)</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int -(int arg) |
| tool long -(long arg) |
| tool double -(double arg)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the negation of an integer, long, or double value.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>arg</code></dt> |
| <dd> |
| <p>The integer, long, or double value.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The negation result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-dash-binary">- operator (binary)</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int -(int left, int right) |
| tool long -(long left, long right) |
| tool double -(double left, double right) |
| tool set T -<T>(set T left, set T right) |
| tool map(K:V) -<K, V>(map(K:V) left, list K right) |
| tool map(K:V) -<K, V>(map(K:V) left, set K right) |
| tool map(K:V) -<K, V, V2>(map(K:V) left, map(K:V2) right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the subtraction of two integer, long, or double numbers, the set |
| difference of two sets, the map with the keys from the list removed from it, |
| the map with the keys from the set removed from it, or the first map with the |
| keys from the second map removed from it.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number, the first set, or the (first) map.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number, the (second) set, the list, or |
| the second map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The subtraction, set difference, or map removal result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow (for integer, long, and double numbers |
| only).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-star">* operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int *(int left, int right) |
| tool long *(long left, long right) |
| tool double *(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the multiplication of two integer, long, or double numbers.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The multiplication result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-slash">/ operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool double /(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the division of two double numbers.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The division result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow or division by zero.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-div">div operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int div(int left, int right) |
| tool long div(long left, long right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the integer division of two integer or long numbers.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer or long number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer or long number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The integer division result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow or division by zero.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-mod">mod operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int mod(int left, int right) |
| tool long mod(long left, long right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the modulus of two integer or long numbers.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer or long number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer or long number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The modulus result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in division by zero.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-lt">< operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool <(int left, int right) |
| tool bool <(long left, long right) |
| tool bool <(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first integer, long, or double number is less than the |
| second integer, long, or double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first number is less than the second number, <code>false</code> |
| otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-le"><= operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool <=(int left, int right) |
| tool bool <=(long left, long right) |
| tool bool <=(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first integer, long, or double number is less than or equal |
| to the second integer, long, or double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first number is less than or equal to the second number, |
| <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-gt">> operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool >(int left, int right) |
| tool bool >(long left, long right) |
| tool bool >(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first integer, long, or double number is greater than the |
| second integer, long, or double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first number is greater than the second number, <code>false</code> |
| otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-ge">>= operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool >=(int left, int right) |
| tool bool >=(long left, long right) |
| tool bool >=(double left, double right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first integer, long, or double number is greater than or |
| equal to the second integer, long, or double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first integer, long, or double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first number is greater than or equal to the second number, |
| <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-eq">== operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool ==<T>(T left, T right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first value is equal to the second value.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the values.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first value. May be <code>null</code>.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second value. May be <code>null</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first value is equal to the second value, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-operators-ne">!= operator</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool !=<T>(T left, T right)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first value is unequal to the second value.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the values.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Arguments</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>left</code></dt> |
| <dd> |
| <p>The first value. May be <code>null</code>.</p> |
| </dd> |
| <dt class="hdlist1"><code>right</code></dt> |
| <dd> |
| <p>The second value. May be <code>null</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first value is unequal to the second value, <code>false</code> |
| otherwise.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-data">Built-in data tools</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in data tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-data-abs">abs</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-ceil">ceil</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-contains">contains</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-del">del</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-delidx">delidx</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-empty">empty</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-endswith">endswith</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-entries">entries</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-enumerate">enumerate</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-floor">floor</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-fmt">fmt</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-indexof">indexof</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-join">join</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-keys">keys</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-lastindexof">lastindexof</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-ln">ln</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-log">log</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-lower">lower</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-ltrim">ltrim</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-max">max</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-min">min</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-pow">pow</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-range">range</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-replace">replace</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-reverse">reverse</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-round">round</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-rtrim">rtrim</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-size">size</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-sorted">sorted</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-split">split</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-sqrt">sqrt</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-startswith">startswith</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-str">str</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-strdup">strdup</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-subset">subset</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-trim">trim</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-upper">upper</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-data-values">values</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-abs">abs tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int abs(int x) |
| tool long abs(long x) |
| tool double abs(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the absolute value of an integer, long, or double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The integer, long, or double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The absolute value.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow (for integer and long numbers only).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-ceil">ceil tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool long ceil(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given double number rounded to a whole long number, towards |
| positive infinity.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The double number rounded to a whole long number, towards positive infinity.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-contains">contains tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool contains(string whole, string part) |
| tool bool contains<T>(list T $list, T elem) |
| tool bool contains<T>(set T $set, T elem) |
| tool bool contains<K,V>(map(K:V) $map, K key)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether a given string is contained in another given string, a given |
| value is contained in a given list, a given value is contained in a given set, |
| or a given value is a key of a given map.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>whole</code>, <code>list</code>, <code>set</code>, <code>map</code></dt> |
| <dd> |
| <p>The whole string, the list, the set, or the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>part</code>, <code>elem</code>, <code>key</code></dt> |
| <dd> |
| <p>The part string (potentially contained in the whole string), or the value |
| (potential element of the list or set, or potential key of the map).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the part string is contained in the whole string, if the value is |
| contained in the list, if the value is contained in the set, or if the value is |
| a key of the map, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-del">del tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list T del<T>(list T $list, T elem) |
| tool set T del<T>(set T $set, T elem) |
| tool map(K:V) del<K,V>(map(K:V) $map, K key)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given list with all occurrences of the given element removed from |
| it, the given set with the given element removed from it, or the given map |
| with the given entry with the given key removed from it. If the element or key |
| does not exist, the list, set or map is returned unmodified.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>list</code>, <code>set</code>, <code>map</code></dt> |
| <dd> |
| <p>The list, set, or map.</p> |
| </dd> |
| <dt class="hdlist1"><code>elem</code>, <code>key</code></dt> |
| <dd> |
| <p>The element or key to remove. May be <code>null</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The list with all occurrences of the element removed from it, the set with the |
| element removed from it, or the map with the entry with the given key removed |
| from it.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-delidx">delidx tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list T delidx<T>(list T $list, int index)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Removes an element from a list, and returns the list without that element.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>list</code></dt> |
| <dd> |
| <p>The list.</p> |
| </dd> |
| <dt class="hdlist1"><code>index</code></dt> |
| <dd> |
| <p>The 0-based index into the list of the element to remove. Negative indices |
| are allowed, and count from the right.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The list with the element removed from it.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the index is out of bounds for the list.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-empty">empty tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool empty(string x) |
| tool bool empty<T>(list T x) |
| tool bool empty<T>(set T x) |
| tool bool empty<K,V>(map(K:V) x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether a given string, list, set, or map is empty (no characters, |
| elements, or entries).</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The string, list, set, or map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the given string, list, set, or map is empty, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-endswith">endswith tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool endswith(string whole, string suffix)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first given string ends with the second given string. For |
| an empty suffix, always returns <code>true</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>whole</code></dt> |
| <dd> |
| <p>The first given string.</p> |
| </dd> |
| <dt class="hdlist1"><code>suffix</code></dt> |
| <dd> |
| <p>The second given string.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first given string ends with the second given string, <code>false</code> |
| otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-entries">entries tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list tuple(K, V) entries<K,V>(map(K:V) $map)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns a list with 2-tuples of keys and values for all entries of the given |
| map.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>map</code></dt> |
| <dd> |
| <p>The map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The list with 2-tuples of keys and values for all entries of the given map.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-enumerate">enumerate tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list tuple(int, T) enumerate<T>(list T $list)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns a list with 2-tuples of 0-based indices and elements for all elements |
| of the given list.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>list</code></dt> |
| <dd> |
| <p>The list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The list with 2-tuples of 0-based indices and elements for all elements of the |
| given list.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-floor">floor tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool long floor(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given double number rounded to a whole long number, towards |
| negative infinity.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The double number rounded to a whole long number, towards negative infinity.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-fmt">fmt tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string fmt(string pattern, object?... args)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Formats a text based on a pattern and arguments.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#lang-ref-builtins-data-str">str</a> tool, as <code>str(value)</code> is |
| equal to <code>fmt("%s", value)</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The format pattern.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The arguments.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The formatted text.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the format pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If the format pattern and arguments don’t match.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-indexof">indexof tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int indexof(string whole, string part) |
| tool int indexof(string whole, string part, int offset) |
| tool int indexof<T>(list T $list, T elem) |
| tool int indexof<T>(list T $list, T elem, int offset)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the 0-based index of the first occurrence of the second given string |
| or value, in the first given string or list. The tool looks for an occurrence |
| from left to right of the first given string or elements of the first given |
| list. If an offset is given, the tool only looks for an occurrence at or after |
| that 0-based offset. If no offset is not given, the tool starts looking at the |
| first (left most) character or list element.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Returns <code>-1</code> if the second given string or value doesn’t occur in the first |
| given string or list, at or after the 0-based offset if given, or at all if |
| no offset is given. For an empty second string, always returns <code>0</code> if no |
| offset is given. For an empty second string, if an offset is given, always |
| returns the offset, unless there is no character at the given offset, in which |
| <code>-1</code> is always returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>whole</code>, <code>list</code></dt> |
| <dd> |
| <p>The first given string, or the list.</p> |
| </dd> |
| <dt class="hdlist1"><code>part</code>, <code>elem</code></dt> |
| <dd> |
| <p>The second given string, or the value.</p> |
| </dd> |
| <dt class="hdlist1"><code>offset</code></dt> |
| <dd> |
| <p>The optional 0-based offset.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The 0-based index of the first occurrence, at or after the given offset if |
| given, or <code>-1</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-join">join tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string join(string... texts) |
| tool string join(list string texts) |
| tool string join(list string texts, string separator)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given texts joined together. They can be joined without any |
| separator, or using a given separator.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>texts</code></dt> |
| <dd> |
| <p>The texts to join.</p> |
| </dd> |
| <dt class="hdlist1"><code>separator</code></dt> |
| <dd> |
| <p>The optional separator text to use.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The joined texts.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-keys">keys tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool set K keys<K,V>(map(K:V) $map)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns a set with the keys of the given map.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>map</code></dt> |
| <dd> |
| <p>The map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The set with the keys of the map.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-lastindexof">lastindexof tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int lastindexof(string whole, string part) |
| tool int lastindexof(string whole, string part, int offset) |
| tool int lastindexof<T>(list T $list, T elem) |
| tool int lastindexof<T>(list T $list, T elem, int offset)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the 0-based index of the last occurrence of the second given string |
| or value, in the first given string or list. The tool looks for an occurrence |
| from left to right of the first given string or elements of the first given |
| list. If an offset is given, the tool only looks for an occurrence at or before |
| that 0-based offset. If no offset is not given, the tool starts looking at the |
| first (left most) character or list element.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Returns <code>-1</code> if the second given string or value doesn’t occur in the first |
| given string or list, at or before the 0-based offset if given, or at all if |
| no offset is given. For an empty second string, always returns the size of the |
| first given string, if no offset is given. For an empty second string, if an |
| offset is given, always returns the offset, unless there is no character at the |
| given offset, in which <code>-1</code> is always returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>whole</code>, <code>list</code></dt> |
| <dd> |
| <p>The first given string, or the list.</p> |
| </dd> |
| <dt class="hdlist1"><code>part</code>, <code>elem</code></dt> |
| <dd> |
| <p>The second given string, or the value.</p> |
| </dd> |
| <dt class="hdlist1"><code>offset</code></dt> |
| <dd> |
| <p>The optional 0-based offset.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The 0-based index of the last occurrence, at or before the given offset if |
| given, or <code>-1</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-ln">ln tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool double ln(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the natural logarithm of a double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The natural logarithm of the double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the double number is not positive.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-log">log tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool double log(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the logarithm (base 10) of a double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The logarithm (base 10) of the double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the double number is not positive.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-lower">lower tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string lower(string text)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given text, converted to lower case. Uses a US English locale.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text, in lower case.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-ltrim">ltrim tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string ltrim(string text)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given text with whitespace at the left/start of the text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text with whitespace at the left/start of the text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-max">max tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int max(int... x) |
| tool long max(long... x) |
| tool double max(double... x) |
| tool int max(list int x) |
| tool long max(list long x) |
| tool double max(list double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the maximum of some integer, long, or double numbers. If no numbers are |
| given, the minimum representable finite integer, long, or double value is |
| returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The integer, long, or double numbers.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The maximum number.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-min">min tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int min(int... x) |
| tool long min(long... x) |
| tool double min(double... x) |
| tool int min(list int x) |
| tool long min(list long x) |
| tool double min(list double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the minimum of some integer, long, or double numbers. If no numbers are |
| given, the maximum representable finite integer, long, or double value is |
| returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The integer, long, or double numbers.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The minimum number.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-pow">pow tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool double pow(double base, double exponent)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the exponentiation (power) of two double numbers.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>base</code></dt> |
| <dd> |
| <p>The base double number.</p> |
| </dd> |
| <dt class="hdlist1"><code>exponent</code></dt> |
| <dd> |
| <p>The exponent double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The exponentiation result.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in double overflow, or <code>NaN</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-range">range tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list int range(int count) |
| tool list int range(int begin, int $end) |
| tool list int range<T>(list T $list)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns a list of numbers representing the range <code>[0..count-1]</code>, |
| <code>[begin..end]</code>, or <code>[0..size(list)-1]</code>. That is, for <code>count</code> = <code>5</code> the |
| list <code>[0, 1, 2, 3, 4]</code> is returned, for <code>begin</code> = <code>-3</code> and <code>end</code> = |
| <code>2</code> the list <code>[-3, -2, -1, 0, 1, 2]</code> is returned, and for a <code>list</code> with |
| <code>5</code> elements the list <code>[0, 1, 2, 3, 4]</code> is returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>count</code></dt> |
| <dd> |
| <p>The number of elements in the resulting list. Negative counts are treated as |
| zero.</p> |
| </dd> |
| <dt class="hdlist1"><code>begin</code></dt> |
| <dd> |
| <p>The lower bound of the range.</p> |
| </dd> |
| <dt class="hdlist1"><code>end</code></dt> |
| <dd> |
| <p>The upper bound of the range.</p> |
| </dd> |
| <dt class="hdlist1"><code>list</code></dt> |
| <dd> |
| <p>The list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The range <code>[0..count-1]</code>, <code>[begin..end]</code>, or <code>[0..size(list)-1]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-replace">replace tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string replace(string text, string oldtext, string newtext) |
| tool list T replace<T>(list T $list, T oldelem, T newelem)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the string or list with old sub strings or elements replaced by new |
| text or elements. For strings, the replacement proceeds from the beginning of |
| the string to the end. That is, replacing <code>"aa"</code> with <code>"b"</code> in the string |
| <code>"aaa"</code> will result in <code>"ba"</code> rather than <code>"ab"</code>. For lists, the |
| replacement is performed for all matching old elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code>, <code>list</code></dt> |
| <dd> |
| <p>The text (string) or list in which to replace text or elements.</p> |
| </dd> |
| <dt class="hdlist1"><code>oldtext</code>, <code>oldelem</code></dt> |
| <dd> |
| <p>The text (sub string) or element to replace. For list elements, it may be |
| <code>null</code>.</p> |
| </dd> |
| <dt class="hdlist1"><code>newtext</code>, <code>newelem</code></dt> |
| <dd> |
| <p>The replacement text or element. For list elements, it may be <code>null</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text or list with all replacements applied.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-reverse">reverse tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string reverse(string text) |
| tool list T reverse<T>(list T $list)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the reverse of the given string or list.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code>, <code>list</code></dt> |
| <dd> |
| <p>The string or list.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The reverse string or list.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-round">round tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool long round(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given double number rounded to the closest whole long number, with |
| ties being rounded toward positive infinity.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The rounded number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the operation results in overflow.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-rtrim">rtrim tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string rtrim(string text)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given text with whitespace at the right/end of the text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text with whitespace at the right/end of the text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-size">size tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int size(string x) |
| tool int size<T>(list T x) |
| tool int size<T>(set T x) |
| tool int size<K,V>(map(K:V) x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the size (number of characters, elements, or entries) of the given |
| string, list, set, or map.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list or set.</p> |
| </dd> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The string, list, set, or map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The size.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-sorted">sorted tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list T sorted<T>(list T $list) |
| tool list T sorted<T>(set T $set)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given list, or the given set as a list, with the elements sorted in |
| ascending order.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the list or set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>list</code></dt> |
| <dd> |
| <p>The list.</p> |
| </dd> |
| <dt class="hdlist1"><code>set</code></dt> |
| <dd> |
| <p>The set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The sorted list.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-split">split tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list string split(string text, string? separator = null, bool removeEmpty = true)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Splits the given text at all non-overlapping occurrences of the given |
| separator.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text to split.</p> |
| </dd> |
| <dt class="hdlist1"><code>separator</code></dt> |
| <dd> |
| <p>The separator text. May be empty or <code>null</code> to split on whitespace.</p> |
| </dd> |
| <dt class="hdlist1"><code>removeEmpty</code></dt> |
| <dd> |
| <p>Whether to remove empty parts (in case the text starts or ends with the |
| separator, or in case the text contains consecutive separators), or not.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The parts of the original text resulting from splitting the original text at |
| the separators.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-sqrt">sqrt tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool double sqrt(double x)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the square root of a double number.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>x</code></dt> |
| <dd> |
| <p>The double number.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The square root.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the double number is negative.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-startswith">startswith tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool startswith(string whole, string prefix)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first given string starts with the second given string. For |
| an empty prefix, always returns <code>true</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>whole</code></dt> |
| <dd> |
| <p>The first given string.</p> |
| </dd> |
| <dt class="hdlist1"><code>prefix</code></dt> |
| <dd> |
| <p>The second given string.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first given string starts with the second given string, |
| <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-str">str tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string str(object? value)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Converts the given value into a textual representation, closely resembling the |
| ToolDef syntax.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Values of type <code>string</code> as returned as provided. Values of type <code>string</code> |
| included in containers such as lists are escaped and surrounded by double |
| quotes, as in the ToolDef syntax.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#lang-ref-builtins-data-fmt">fmt</a> tool, as <code>str(value)</code> is |
| equal to <code>fmt("%s", value)</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>value</code></dt> |
| <dd> |
| <p>The value to convert to a textual representation.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The textual representation.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-strdup">strdup tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string strdup(string text, int count)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Duplicates a string a given number of times.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The string to duplicate.</p> |
| </dd> |
| <dt class="hdlist1"><code>count</code></dt> |
| <dd> |
| <p>The number of times that the input string should occur in the output.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The concatenation of <code>count</code> times the <code>text</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the count is negative.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-subset">subset tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool subset<T>(set T part, set T whole)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns whether the first given set is a subset (proper subset or equal) of the |
| second given set.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code></dt> |
| <dd> |
| <p>The type of the elements of the sets.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>part</code></dt> |
| <dd> |
| <p>The first set.</p> |
| </dd> |
| <dt class="hdlist1"><code>whole</code></dt> |
| <dd> |
| <p>The second set.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the first given set is a subset of the second given set, <code>false</code> |
| otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-trim">trim tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string trim(string text)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given text with whitespace at the left/start and right/end of the |
| text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text with whitespace at the left/start and right/end of the text removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-upper">upper tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string upper(string text)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the given text, converted to upper case. Uses a US English locale.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>text</code></dt> |
| <dd> |
| <p>The text.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The text, in upper case.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-data-values">values tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool set V values<K,V>(map(K:V) $map)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns a set with the values of the given map.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Type parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>K</code></dt> |
| <dd> |
| <p>The type of the keys of the map.</p> |
| </dd> |
| <dt class="hdlist1"><code>V</code></dt> |
| <dd> |
| <p>The type of the values of the map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>map</code></dt> |
| <dd> |
| <p>The map.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The set with the values of the map.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-io">Built-in I/O tools</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in I/O tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-io-out">out</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-io-err">err</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-io-outln">outln</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-io-errln">errln</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-io-out">out tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool out(string pattern, object?... args)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Prints <a href="#lang-ref-builtins-data-fmt">formatted text</a> (based on a |
| pattern and arguments) to the standard output stream (stdout).</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The format pattern.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The arguments.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the format pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If the format pattern and arguments don’t match.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-io-err">err tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool err(string pattern, object?... args)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Prints <a href="#lang-ref-builtins-data-fmt">formatted text</a> (based on a |
| pattern and arguments) to the standard error stream (stderr).</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The format pattern.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The arguments.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the format pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If the format pattern and arguments don’t match.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-io-outln">outln tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool outln(string pattern = "", object?... args)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Prints <a href="#lang-ref-builtins-data-fmt">formatted text</a> (based on a |
| pattern and arguments) to the standard output stream (stdout), printing an |
| additional new line at the end.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The format pattern.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The arguments.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the format pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If the format pattern and arguments don’t match.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-io-errln">errln tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool errln(string pattern = "", object?... args)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Prints <a href="#lang-ref-builtins-data-fmt">formatted text</a> (based on a |
| pattern and arguments) to the standard error stream (stderr), printing an |
| additional new line at the end.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The format pattern.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The arguments.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the format pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If the format pattern and arguments don’t match.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-generic">Built-in generic tools</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in generic tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-generic-app">app</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-generic-exec">exec</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-generic-tooldef">tooldef</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-generic-app">app tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int app(string? plugin, string classname, string... args, string stdin = "-", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false) |
| tool int app(string? plugin, string classname, list string args = [], string stdin = "-", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Executes an application framework application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The application is specified as a Java class that extends the |
| <code>org.eclipse.escet.common.app.framework.Application</code> class. It should have a constructor |
| that accepts one parameter, of type <code>org.eclipse.escet.common.app.framework.io.AppStreams</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The application is started within the current Java interpreter, in a new |
| thread. If executed from Eclipse, the class is loaded using the class loader |
| of the given bundle (if provided), otherwise, it is loaded using the default |
| class loader. In the latter case, the class should be in the class path.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that this tool is only machine independent and platform independent, as |
| long as the applications that are executed, are machine independent and |
| platform independent as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>plugin</code></dt> |
| <dd> |
| <p>The name of the plug-in (OSGi bundle) in which to resolve the application |
| class. If the Java application is executed from Eclipse, then the class is |
| loaded by the class loader of this bundle, otherwise it is resolved using the |
| default class loader. May be <code>null</code> to always use the default class loader.</p> |
| </dd> |
| <dt class="hdlist1"><code>classname</code></dt> |
| <dd> |
| <p>The absolute name of the Java class to execute as application.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The command line arguments of the application to execute. Each argument |
| string is parsed to zero or more actual arguments. It is possible to use a |
| single string with all arguments (where the arguments themselves are |
| separated by spaces), comma separated strings for each of the arguments (each |
| string has one argument), or a mix of those.</p> |
| <div class="paragraph"> |
| <p>In argument strings, individual arguments are separated by whitespace |
| (spaces, tabs, new lines, etc). The whitespace itself is ignored, and only |
| serves as separation. To include whitespace in an argument, the argument (or |
| a part of it), may be quoted, by putting it between double quotes (<code>"</code>) or |
| single quotes (<code>'</code>). Characters may be escaped by prefixing them with a |
| backslash (<code>\</code>). This is particularly useful for single/double quotes, and |
| escape characters, and can also be used to escape spaces. Escapes work the |
| same inside of quoted parts as they do outside of quoted parts.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>stdin</code></dt> |
| <dd> |
| <p>Specify whether to have a standard input (stdin) stream and where the input |
| comes from. Use <code>""</code> to not have a stdin stream, <code>"-"</code> to use the stdin |
| stream of the ToolDef interpreter, or otherwise an absolute or relative local |
| file system path of the file from which to read the standard input. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stdout</code></dt> |
| <dd> |
| <p>Specify whether to have a standard output (stdout) stream and where to write |
| the standard output. Use <code>""</code> to not have a stdout stream, <code>"-"</code> to use |
| the stdout stream of the ToolDef interpreter, or otherwise an absolute or |
| relative local file system path of the file to which to write the standard |
| output. May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stderr</code></dt> |
| <dd> |
| <p>Specify whether to have a standard error (stderr) stream and where to write |
| the standard error output. Use <code>""</code> to not have a stderr stream, <code>"-"</code> |
| to use the stderr stream of the ToolDef interpreter, or otherwise an absolute |
| or relative local file system path of the file to which to write the standard |
| error output. May contain both <code>\</code> and <code>/</code> as path separators. Is ignored |
| when the standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendOut</code></dt> |
| <dd> |
| <p>Whether to append to the stdout file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored when standard output is not written to a file.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendErr</code></dt> |
| <dd> |
| <p>Whether to append to the stderr file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored if standard error output is not written to a file. Is also ignored |
| when standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>errToOut</code></dt> |
| <dd> |
| <p>Whether to redirect the standard error stream to the standard output stream |
| (<code>true</code>) or use separate streams (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>ignoreNonZeroExitCode</code></dt> |
| <dd> |
| <p>Whether to ignore non-zero exit codes (<code>true</code>) or consider them as errors |
| (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The application exit code. See the application framework documentation for a |
| description of the exit codes.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the class loader can not be obtained.</p> |
| </li> |
| <li> |
| <p>If the class can not be found or loaded.</p> |
| </li> |
| <li> |
| <p>If the class is not an application framework application.</p> |
| </li> |
| <li> |
| <p>If an appropriate constructor is not available.</p> |
| </li> |
| <li> |
| <p>If an instance of the application class can not be constructed.</p> |
| </li> |
| <li> |
| <p>If parsing of the command line arguments fails.</p> |
| </li> |
| <li> |
| <p>If the application fails to execute due to its thread being interrupted.</p> |
| </li> |
| <li> |
| <p>If the application exits with a non-zero exit code and non-zero exit codes |
| are not ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-generic-exec">exec tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int exec(string cmd, string... args, string stdin = "", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false) |
| tool int exec(string cmd, list string args = [], string stdin = "", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Executes a system command or external application as a sub process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This tool should be avoided if possible, as it is in general not guaranteed to |
| be cross platform and machine independent. Commands and external applications |
| may not be available on all systems, or may have different behavior on |
| different systems.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>cmd</code></dt> |
| <dd> |
| <p>The name of the command or the absolute or relative local file system path of |
| the external application to execute, using platform specific new line |
| characters.</p> |
| </dd> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The command line arguments of the command or external application to execute. |
| Each argument string is parsed to zero or more actual arguments. It is |
| possible to use a single string with all arguments (where the arguments |
| themselves are separated by spaces), comma separated strings for each of the |
| arguments (each string has one argument), or a mix of those.</p> |
| <div class="paragraph"> |
| <p>In argument strings, individual arguments are separated by whitespace |
| (spaces, tabs, new lines, etc). The whitespace itself is ignored, and only |
| serves as separation. To include whitespace in an argument, the argument (or |
| a part of it), may be quoted, by putting it between double quotes (<code>"</code>) or |
| single quotes (<code>'</code>). Characters may be escaped by prefixing them with a |
| backslash (<code>\</code>). This is particularly useful for single/double quotes, and |
| escape characters, and can also be used to escape spaces. Escapes work the |
| same inside of quoted parts as they do outside of quoted parts.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>stdin</code></dt> |
| <dd> |
| <p>Specify whether to have a standard input (stdin) stream and where the input |
| comes from. Use <code>""</code> to not have a stdin stream, <code>"-"</code> to use the stdin |
| stream of the ToolDef interpreter, or otherwise an absolute or relative local |
| file system path of the file from which to read the standard input. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stdout</code></dt> |
| <dd> |
| <p>Specify whether to have a standard output (stdout) stream and where to write |
| the standard output. Use <code>""</code> to not have a stdout stream, <code>"-"</code> to use |
| the stdout stream of the ToolDef interpreter, or otherwise an absolute or |
| relative local file system path of the file to which to write the standard |
| output. May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stderr</code></dt> |
| <dd> |
| <p>Specify whether to have a standard error (stderr) stream and where to write |
| the standard error output. Use <code>""</code> to not have a stderr stream, <code>"-"</code> |
| to use the stderr stream of the ToolDef interpreter, or otherwise an absolute |
| or relative local file system path of the file to which to write the standard |
| error output. May contain both <code>\</code> and <code>/</code> as path separators. Is ignored |
| when the standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendOut</code></dt> |
| <dd> |
| <p>Whether to append to the stdout file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored when standard output is not written to a file.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendErr</code></dt> |
| <dd> |
| <p>Whether to append to the stderr file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored if standard error output is not written to a file. Is also ignored |
| when standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>errToOut</code></dt> |
| <dd> |
| <p>Whether to redirect the standard error stream to the standard output stream |
| (<code>true</code>) or use separate streams (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>ignoreNonZeroExitCode</code></dt> |
| <dd> |
| <p>Whether to ignore non-zero exit codes (<code>true</code>) or consider them as errors |
| (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The exit code resulting from the execution of the command or external |
| application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If parsing of the command line arguments fails.</p> |
| </li> |
| <li> |
| <p>If ToolDef fails to execution the command or external application.</p> |
| </li> |
| <li> |
| <p>If execution results in a non-zero exit code and non-zero exit codes are not |
| ignored.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-generic-tooldef">tooldef tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool int tooldef(string... args, string stdin = "-", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false) |
| tool int tooldef(list string args = [], string stdin = "-", string stdout = "-", string stderr = "-", bool appendOut = false, bool appendErr = false, bool errToOut = false, bool ignoreNonZeroExitCode = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Executes a ToolDef script. Waits for that script to finish its execution before |
| continuing with the current script.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The script is executed within the current Java interpreter, in a new thread, |
| using a new ToolDef interpreter.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>args</code></dt> |
| <dd> |
| <p>The command line arguments for the ToolDef interpreter, including the path to |
| the script to execute. Each argument string is parsed to zero or more actual |
| arguments. It is possible to use a single string with all arguments (where |
| the arguments themselves are separated by spaces), comma separated strings |
| for each of the arguments (each string has one argument), or a mix of those.</p> |
| <div class="paragraph"> |
| <p>In argument strings, individual arguments are separated by whitespace |
| (spaces, tabs, new lines, etc). The whitespace itself is ignored, and only |
| serves as separation. To include whitespace in an argument, the argument (or |
| a part of it), may be quoted, by putting it between double quotes (<code>"</code>) or |
| single quotes (<code>'</code>). Characters may be escaped by prefixing them with a |
| backslash (<code>\</code>). This is particularly useful for single/double quotes, and |
| escape characters, and can also be used to escape spaces. Escapes work the |
| same inside of quoted parts as they do outside of quoted parts.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>stdin</code></dt> |
| <dd> |
| <p>Specify whether to have a standard input (stdin) stream and where the input |
| comes from. Use <code>""</code> to not have a stdin stream, <code>"-"</code> to use the stdin |
| stream of the ToolDef interpreter, or otherwise an absolute or relative local |
| file system path of the file from which to read the standard input. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stdout</code></dt> |
| <dd> |
| <p>Specify whether to have a standard output (stdout) stream and where to write |
| the standard output. Use <code>""</code> to not have a stdout stream, <code>"-"</code> to use |
| the stdout stream of the ToolDef interpreter, or otherwise an absolute or |
| relative local file system path of the file to which to write the standard |
| output. May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>stderr</code></dt> |
| <dd> |
| <p>Specify whether to have a standard error (stderr) stream and where to write |
| the standard error output. Use <code>""</code> to not have a stderr stream, <code>"-"</code> |
| to use the stderr stream of the ToolDef interpreter, or otherwise an absolute |
| or relative local file system path of the file to which to write the standard |
| error output. May contain both <code>\</code> and <code>/</code> as path separators. Is ignored |
| when the standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendOut</code></dt> |
| <dd> |
| <p>Whether to append to the stdout file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored when standard output is not written to a file.</p> |
| </dd> |
| <dt class="hdlist1"><code>appendErr</code></dt> |
| <dd> |
| <p>Whether to append to the stderr file (<code>true</code>) or overwrite it (<code>false</code>). |
| Is ignored if standard error output is not written to a file. Is also ignored |
| when standard error stream is redirected to the standard output stream.</p> |
| </dd> |
| <dt class="hdlist1"><code>errToOut</code></dt> |
| <dd> |
| <p>Whether to redirect the standard error stream to the standard output stream |
| (<code>true</code>) or use separate streams (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>ignoreNonZeroExitCode</code></dt> |
| <dd> |
| <p>Whether to ignore non-zero exit codes (<code>true</code>) or consider them as errors |
| (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The ToolDef interpreter exit code, i.e. the exit code of the script.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If parsing of the command line arguments fails.</p> |
| </li> |
| <li> |
| <p>If the application fails to execute due to its thread being interrupted.</p> |
| </li> |
| <li> |
| <p>If execution results in a non-zero exit code and non-zero exit codes are not |
| ignored.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-path">Built-in path tools</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in I/O tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-path-abspath">abspath</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-basename">basename</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-chdir">chdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-chfileext">chfileext</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-curdir">curdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-dirname">dirname</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-fileext">fileext</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-hasfileext">hasfileext</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-pathjoin">pathjoin</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-path-scriptpath">scriptpath</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-abspath">abspath tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string abspath(string path) |
| tool string abspath(string path, string workdir)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns an absolute local file system path, given an absolute or relative local |
| file system path.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path. May contain both <code>\</code> and |
| <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>workdir</code></dt> |
| <dd> |
| <p>The optional absolute local file system path of the working directory against |
| which to resolve relative paths. May contain both <code>\</code> and <code>/</code> as path |
| separators. If not specified, relative paths are resolved against the |
| <a href="#lang-ref-builtins-path-curdir">current working directory</a>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The absolute local file system path. The path contains separators for the |
| current platform.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-basename">basename tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string basename(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the base name of the given absolute or relative local file system path. |
| The base name of a file or directory is the name of that file or directory. In |
| other words, returns the last part of the given path.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path to the file or directory for |
| which to return the base name. May contain both <code>\</code> and <code>/</code> as path |
| separators. Must not end with <code>\</code> or <code>/</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The base name.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the path ends with <code>\</code> or <code>/</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-chdir">chdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool chdir(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Changes the <a href="#lang-ref-builtins-path-curdir">current working directory</a> to |
| the directory referred to by the given path.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path to the new current working |
| directory. Relative paths are resolved against the |
| <a href="#lang-ref-builtins-path-curdir">current working directory</a>. May contain |
| both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the given path does not exist.</p> |
| </li> |
| <li> |
| <p>If the given path refers to a file rather than a directory.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the given path refers to a file or a |
| directory.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-chfileext">chfileext tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string chfileext(string path, string? oldext = null, string? newext = null)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Modifies a path such that it ends with a new extension, removing an old |
| extension if it exists.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path to modify. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>oldext</code></dt> |
| <dd> |
| <p>The old extension that can be removed (case insensitive, no . at the |
| start). Use <code>null</code> to not remove an old extension.</p> |
| </dd> |
| <dt class="hdlist1"><code>newext</code></dt> |
| <dd> |
| <p>The new extension to use (case sensitive, no . at the start). Use |
| <code>null</code> to not add a new extension.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The changed path, ending with the new extension (if any).</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-curdir">curdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string curdir()</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the script execution’s current working directory, as an absolute local |
| file system path. The path contains separators for the current platform.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The script execution’s current working directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-dirname">dirname tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string dirname(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the absolute directory path of the directory that contains the given |
| file or directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute local file system path that refers to a file or directory. May |
| contain both <code>\</code> and <code>/</code> as path separators. Must not end with <code>\</code> or <code>/</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The absolute directory path of the directory that contains the given file or |
| directory. May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the given path is not an absolute local file system path.</p> |
| </li> |
| <li> |
| <p>If the given path ends with <code>\</code> or <code>/</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-fileext">fileext tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string fileext(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the file extension of the given file, or <code>""</code> if the file has no file |
| extension.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path to the file. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The file extension, or <code>""</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-hasfileext">hasfileext tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool hasfileext(string path, string ext)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Does the given file have the given file extension?</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path to the file. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>ext</code></dt> |
| <dd> |
| <p>The file extension to check for (case sensitive, no <code>.</code> at the start).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the file has the given file extension, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-pathjoin">pathjoin tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string pathjoin(string... paths) |
| tool string pathjoin(list string paths)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Joins paths together. If no paths are given, an empty string is returned. If |
| one path is given, the path is returned.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>paths</code></dt> |
| <dd> |
| <p>The paths to join together. The first path may be an absolute or relative |
| local file system path. The remaining paths must be relative local file |
| system paths. All paths may contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The joined path. The path contains separators for the current platform.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-path-scriptpath">scriptpath tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool string scriptpath()</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the absolute local file system path to the script being executed. The |
| path contains separators for the current platform.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The absolute local file system path to the script being executed.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="lang-ref-builtins-file">Built-in file tools</h4> |
| <div class="paragraph"> |
| <p>This page describes the built-in I/O tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#lang-ref-builtins-file-cpfile">cpfile</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-cpdir">cpdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-diff">diff</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-exists">exists</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-filenewer">filenewer</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-filesize">filesize</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-find">find</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-isdir">isdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-isfile">isfile</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-mkdir">mkdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-mvfile">mvfile</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-mvdir">mvdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-readlines">readlines</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-rmfile">rmfile</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-rmdir">rmdir</a></p> |
| </li> |
| <li> |
| <p><a href="#lang-ref-builtins-file-writefile">writefile</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-cpfile">cpfile tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool cpfile(string source, string target, bool overwrite = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Copies a file from a source location to a target location.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>source</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the source file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>target</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the target file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>overwrite</code></dt> |
| <dd> |
| <p>Whether to overwrite the target file if it already exists.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the source file does not exist.</p> |
| </li> |
| <li> |
| <p>If the source is a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the source path refers to a file or a |
| directory.</p> |
| </li> |
| <li> |
| <p>If the target file exists and overwriting is not allowed.</p> |
| </li> |
| <li> |
| <p>If the target file exists and overwriting is allowed, but the target refers |
| to a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If the target file exists and overwriting is allowed, but it can not be |
| determined whether the target path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If copying the file failed due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-cpdir">cpdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool cpdir(string source, string target)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Copies a directory from a source location to a target location. All files and |
| directories in the source directory are copied recursively.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the operation fails, part of the operation may have already been performed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>source</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the source directory. All |
| files and directories in the source directory are copied recursively. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>target</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the target directory. This |
| is the directory in which the contents of the source directory are copied. |
| The source directory itself is not copied, only the files and directories |
| contained in the source directory. May contain both <code>\</code> and <code>/</code> as path |
| separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the source directory does not exist.</p> |
| </li> |
| <li> |
| <p>If the source is a file rather than a directory.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the source path refers to a file or a |
| directory.</p> |
| </li> |
| <li> |
| <p>If the target directory already exists.</p> |
| </li> |
| <li> |
| <p>If the target directory doesn’t exist, but one of the ancestors is not a |
| directory.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) fails.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) encounters a file system cycle (due to |
| symbolic links).</p> |
| </li> |
| <li> |
| <p>If a file or (sub-)directory could not be copied due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-diff">diff tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool diff(string file1, string file2, string output = "-", bool missingAsEmpty = false, bool warnOnDiff = false, bool failOnDiff = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Computes the differences between two files.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>file1</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the first file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>file2</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the second file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>output</code></dt> |
| <dd> |
| <p>Specify whether/where to write a unified diff if the files differ. Use <code>""</code> |
| to not write a unified diff, <code>"-"</code> to write the unified diff to the |
| standard output stream (stdout), or otherwise an absolute or relative local |
| file system path of the file to which to write the unified diff. May contain |
| both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>missingAsEmpty</code></dt> |
| <dd> |
| <p>Treat a missing first/second file as empty (<code>true</code>) or as an error |
| (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>warnOnDiff</code></dt> |
| <dd> |
| <p>Emit a warning for differing files (<code>true</code>) or not (<code>false</code>). If a |
| warning is emitted to the standard error stream (stderr), the unified diff |
| (if enabled) is printed first.</p> |
| </dd> |
| <dt class="hdlist1"><code>failOnDiff</code></dt> |
| <dd> |
| <p>Treat differing files as an error (<code>true</code>) or not (<code>false</code>). If an error |
| is emitted, the unified diff (if enabled) and warning (if enabled) are |
| printed first.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the files differ, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If either the first or second file doesn’t exist and <code>missingAsEmpty</code> is |
| disabled.</p> |
| </li> |
| <li> |
| <p>If the first or second file is not a file but a directory.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the first or second path refers to a file |
| or a directory.</p> |
| </li> |
| <li> |
| <p>If an I/O error occurs.</p> |
| </li> |
| <li> |
| <p>If the <code>out</code> file exists but is a directory rather than a regular file.</p> |
| </li> |
| <li> |
| <p>If the <code>out</code> file does not exist but cannot be created.</p> |
| </li> |
| <li> |
| <p>If the <code>out</code> file cannot be opened for writing for any other reason.</p> |
| </li> |
| <li> |
| <p>If an I/O error occurs while writing to the <code>out</code> file.</p> |
| </li> |
| <li> |
| <p>If the <code>out</code> file can not be closed.</p> |
| </li> |
| <li> |
| <p>If the files differ and <code>failOnDiff</code> is enabled.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-exists">exists tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool exists(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Does a file or directory with the given path exist?</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file or directory. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the file or directory exists, <code>false</code> otherwise.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-filenewer">filenewer tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool filenewer(string path, string refpath, bool allowNonExisting = false, bool sameAsNewer = true) |
| tool bool filenewer(string path, string... refpaths, bool allowNonExisting = false, bool sameAsNewer = true) |
| tool bool filenewer(string path, list string refpaths, bool allowNonExisting = false, bool sameAsNewer = true)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Checks whether a file is newer (was modified at a later date/time) than some |
| reference file(s).</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file for which to |
| check whether it is newer than the reference file(s). May contain both <code>\</code> |
| and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>refpath</code>, <code>refpaths</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the reference file(s). May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>allowNonExisting</code></dt> |
| <dd> |
| <p>Whether to allow the first file to not exist (<code>true</code>) or consider it an |
| error if the first file does not exist (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>sameAsNewer</code></dt> |
| <dd> |
| <p>Whether to treat files with the same last change date as being the same |
| (<code>false</code>) or as newer (<code>true</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>false</code> if the first file does not exist (if allowed by enabling |
| <code>allowNonExisting</code>), if the first file is older than any the reference files, |
| or if the first file has the same last change date as any of the reference |
| files and <code>sameAsNewer</code> is disabled. <code>true</code> if the first file is newer than |
| all of the reference files, if the first file has the same last change date as |
| some the reference files and <code>sameAsNewer</code> is enabled and is newer than all |
| of the other reference files, or if the first file has the same last change |
| date as all the reference files and <code>sameAsNewer</code> is enabled.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the first file does not exist and <code>allowNonExisting</code> is disabled.</p> |
| </li> |
| <li> |
| <p>If any of the reference files does not exist.</p> |
| </li> |
| <li> |
| <p>If any of the files is a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If for any of the paths it can not be determined whether the path refers to a |
| file or a directory.</p> |
| </li> |
| <li> |
| <p>If the last change date/time of any of the files can not be determined.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-filesize">filesize tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool long filesize(string path, bool missingAsZero = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Returns the size of the file, in bytes.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>missingAsZero</code></dt> |
| <dd> |
| <p>Whether to return 0 if the file does not exist (<code>true</code>) or consider it |
| an error if the file does not exist (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The size of the file in bytes, or <code>0</code> if the file is missing and |
| <code>missingAsZero</code> is enabled.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the file does not exist and <code>missingAsZero</code> is disabled.</p> |
| </li> |
| <li> |
| <p>If the file is a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If the size of the file can not be determined due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-find">find tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list string find(string path, string pattern = "*", bool recursive = true, bool files = true, bool dirs = true)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Searches a directory for files and/or directories matching a pattern.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the directory in which to |
| search. The directory itself is never returned. May contain both <code>\</code> and |
| <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>pattern</code></dt> |
| <dd> |
| <p>The pattern to use to match files/directories. Is a |
| <a href="https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob">Java NIO glob</a> |
| pattern, that is matched against single file names or single directory names, |
| and never against paths. Pattern <code>"*"</code> matches all files and directories.</p> |
| </dd> |
| <dt class="hdlist1"><code>recursive</code></dt> |
| <dd> |
| <p>Whether to recursively look in sub-directories.</p> |
| </dd> |
| <dt class="hdlist1"><code>files</code></dt> |
| <dd> |
| <p>Whether to match files.</p> |
| </dd> |
| <dt class="hdlist1"><code>dirs</code></dt> |
| <dd> |
| <p>Whether to match directories.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The local file system paths of the matched files and directories, relative |
| against the given root directory from which searching started.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the given directory is not found.</p> |
| </li> |
| <li> |
| <p>If the given directory is a file rather than a directory.</p> |
| </li> |
| <li> |
| <p>If the can not be determined whether the given path refers to a file or a |
| directory.</p> |
| </li> |
| <li> |
| <p>If the pattern is invalid.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) fails.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) encounters a file system cycle (due to |
| symbolic links).</p> |
| </li> |
| <li> |
| <p>If the operation fails due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-isdir">isdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool isdir(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Does a directory with the given path exist?</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the directory. May contain |
| both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the directory exists, <code>false</code> if it doesn’t exist or is not a |
| directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-isfile">isfile tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool isfile(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Does a file with the given path exist?</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file. May contain |
| both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the file exists, <code>false</code> if it doesn’t exist or is not a file.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-mkdir">mkdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool mkdir(string path, bool force = false, bool parents = true)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Creates the given directory, and optionally its parents as needed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the directory to create. |
| May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>force</code></dt> |
| <dd> |
| <p>Whether to skip creating the directory if it already exists (<code>true</code>) or |
| fail if it already exists (<code>false</code>).</p> |
| </dd> |
| <dt class="hdlist1"><code>parents</code></dt> |
| <dd> |
| <p>Whether to allow creating parents as needed (<code>true</code>) or fail if the parent |
| directory does not exist (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the directory already exists and <code>force</code> is disabled.</p> |
| </li> |
| <li> |
| <p>If creating the directory or any of its parents fails, due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-mvfile">mvfile tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool mvfile(string source, string target, bool overwrite = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Moves a file from a source location to a target location. This can be used to |
| rename a file and/or move it to another directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>source</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the source file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>target</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the target file. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>overwrite</code></dt> |
| <dd> |
| <p>Whether to overwrite the target file if it already exists.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the source file does not exist.</p> |
| </li> |
| <li> |
| <p>If the source is a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the source path refers to a file or a |
| directory.</p> |
| </li> |
| <li> |
| <p>If the target file exist and overwriting is not allowed.</p> |
| </li> |
| <li> |
| <p>If the target file exists and overwriting is allowed, but the target refers |
| to a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If the target file exists and overwriting is allowed, but it can not be |
| determined whether the target path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If moving the file fails due to an I/O error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-mvdir">mvdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool mvdir(string source, string target)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Moves a directory from a source location to a target location. The directory |
| and all files and directories in it are moved recursively.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The operation is implemented as a copy from source to target, followed by a |
| remove of the source. If the operation fails, part of the operation may have |
| already been performed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>source</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the source directory. The |
| directory itself and all files and directories in it are moved recursively. |
| May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>target</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the target directory. This |
| is the directory into which the contents of the source directory are moved. |
| May contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the source directory does not exist.</p> |
| </li> |
| <li> |
| <p>If the source is a file rather than a directory.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the source path refers to a file or a |
| directory.</p> |
| </li> |
| <li> |
| <p>If the target directory already exists.</p> |
| </li> |
| <li> |
| <p>If the target directory doesn’t exist but one of the ancestors is not a |
| directory.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) fails.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) encounters a file system cycle (due to |
| symbolic links).</p> |
| </li> |
| <li> |
| <p>If a file or (sub-)directory can not be copied or removed, due to an I/O |
| error.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-readlines">readlines tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool list string readlines(string path)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Read lines of text from a file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file to read. May |
| contain both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>The lines of text from the file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the file does not exist.</p> |
| </li> |
| <li> |
| <p>If the path refers to a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If for some other reason can not be opened for reading.</p> |
| </li> |
| <li> |
| <p>If an I/O error occurs.</p> |
| </li> |
| <li> |
| <p>If the file can not be closed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-rmfile">rmfile tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool rmfile(string path, bool force = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Removes a file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>force</code></dt> |
| <dd> |
| <p>Whether to ignore non-existing files (<code>true</code>) or consider it an error |
| (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the file was removed, <code>false</code> if it could not be removed because |
| it did not exist and force is enabled.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the file does not exist and <code>force</code> is disabled.</p> |
| </li> |
| <li> |
| <p>If the file is a directory rather than a file.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If an I/O error occurs.</p> |
| </li> |
| <li> |
| <p>If the file can not be removed for some other reason.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-rmdir">rmdir tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool bool rmdir(string path, bool force = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Removes a directory, recursively.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the directory. May contain |
| both <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>force</code></dt> |
| <dd> |
| <p>Whether to ignore non-existing directories (<code>true</code>) or consider it an error |
| (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Returns</em></p> |
| </div> |
| <div class="paragraph"> |
| <p><code>true</code> if the directory was removed, <code>false</code> if it could not be removed |
| because it did not exist and <code>force</code> is enabled.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the directory does not exist and <code>force</code> is disabled.</p> |
| </li> |
| <li> |
| <p>If the directory is a file rather than a directory.</p> |
| </li> |
| <li> |
| <p>If it can not be determined whether the path refers to a file or a directory.</p> |
| </li> |
| <li> |
| <p>If an I/O error occurs.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) fails.</p> |
| </li> |
| <li> |
| <p>If walking the directory (recursively) encounters a file system cycle (due to |
| symbolic links).</p> |
| </li> |
| <li> |
| <p>If the directory or one of its sub-files or sub-directories can not be |
| removed for some other reason.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="lang-ref-builtins-file-writefile">writefile tool</h5> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="tooldef">tool writefile(string path, string text, bool append = false) |
| tool writefile(string path, list string lines, bool append = false)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Writes text to a file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Parameters</em></p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>path</code></dt> |
| <dd> |
| <p>The absolute or relative local file system path of the file. May contain both |
| <code>\</code> and <code>/</code> as path separators.</p> |
| </dd> |
| <dt class="hdlist1"><code>text</code>, <code>lines</code></dt> |
| <dd> |
| <p>The text or lines of text to write to the file.</p> |
| </dd> |
| <dt class="hdlist1"><code>append</code></dt> |
| <dd> |
| <p>Whether to append the lines text to the file if it already exists (<code>true</code>), |
| or overwrite the file if it already exists (<code>false</code>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p><em>Runtime errors</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the path exists but is a directory rather than a regular file.</p> |
| </li> |
| <li> |
| <p>If the file does not exist, but cannot be created.</p> |
| </li> |
| <li> |
| <p>If the file can not be opened for writing for any other reason.</p> |
| </li> |
| <li> |
| <p>If writing to the file fails due to an I/O error.</p> |
| </li> |
| <li> |
| <p>If closing the file fails.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="tools-chapter-index">Tooling</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Below you can find general information on how to use the ToolDef tooling, |
| both on the command line, and in the <a href="https://eclipse.org">Eclipse</a> IDE.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To start using the ToolDef tooling, create a <code>.tooldef</code> file. See the |
| <a href="#lang-ref-chapter-index">language reference</a> documentation for more |
| information on the syntax.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect2"> |
| <h3 id="tools-command-line">Command line</h3> |
| <div class="paragraph"> |
| <p>To execute a ToolDef script on the command line, use the <code>tooldef</code> |
| executable. To start executing a ToolDef script, enter |
| something like this on the command line:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="shell">tooldef some_script.tooldef</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| Additional options are available, to influence how the script is executed. For |
| details, execute the ToolDef interpreter with the <code>--help</code> or <code>-h</code> command |
| line option:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="shell">tooldef --help</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tools-eclipse-ide">Eclipse IDE</h3> |
| <div class="paragraph"> |
| <p> |
| |
| To execute a ToolDef script in the Eclipse IDE, right click the file or an |
| open text editor for the script, and choose <b class="menuref">Execute ToolDef</b>. |
| Alternatively, choose <b class="menuref">Execute ToolDef…​</b> to first shown an option |
| dialog, where several options that influence how the script is executed, before |
| actually executing the script.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is also possible to start executing a script by pressing <kbd>F10</kbd>, while |
| a <code>.tooldef</code> file is selected or an open text for such a file has the focus. |
| Finally, clicking the corresponding toolbar icon |
| (<span class="image"><img src="./tools/tooldef_icon.png" alt="tooldef icon"></span>) has the same effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Execution of ToolDef script can be manually terminated by means of the |
| termination features of the <em>Applications</em> view.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="release-notes-chapter-index">ToolDef release notes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The release notes for the releases of ToolDef and the associated tools, as |
| part of the Eclipse ESCET project, are listed below in reverse chronological |
| order.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="version-0-1-unreleased">Version 0.1 (unreleased)</h3> |
| <div class="paragraph"> |
| <p>The first release of ToolDef as part of the Eclipse ESCET project.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="legal-chapter-index">Legal</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The material in this documentation is |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse ESCET and ESCET are trademarks of the Eclipse Foundation. |
| Eclipse, and the Eclipse Logo are registered trademarks of the |
| Eclipse Foundation. Other names may be trademarks of their |
| respective owners.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>License</strong></p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation makes available all content in this document |
| ("Content"). Unless otherwise indicated below, the Content is provided to you |
| under the terms and conditions of the MIT License. A copy of the MIT License |
| is available at <a href="https://opensource.org/licenses/MIT" class="bare">https://opensource.org/licenses/MIT</a>. For purposes of the |
| MIT License, "Software" will mean the Content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you did not receive this Content directly from the Eclipse Foundation, |
| the Content is being redistributed by another party ("Redistributor") and |
| different terms and conditions may apply to your use of any object code in |
| the Content. Check the Redistributor’s license that was provided with the |
| Content. If no such license exists, contact the Redistributor. Unless |
| otherwise indicated below, the terms and conditions of the MIT License |
| still apply to any source code in the Content and such source code may be |
| obtained at <a href="http://www.eclipse.org" class="bare">http://www.eclipse.org</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <style> |
| /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ |
| pre.CodeRay{background:#f7f7f8} |
| .CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0} |
| .CodeRay span.line-numbers{display:inline-block;margin-right:.75em} |
| .CodeRay .line-numbers strong{color:#000} |
| table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.CodeRay td{vertical-align:top;line-height:inherit} |
| table.CodeRay td.line-numbers{text-align:right} |
| table.CodeRay td.code{padding:0 0 0 .75em} |
| .CodeRay .debug{color:#fff !important;background:#000080 !important} |
| .CodeRay .annotation{color:#007} |
| .CodeRay .attribute-name{color:#000080} |
| .CodeRay .attribute-value{color:#700} |
| .CodeRay .binary{color:#509} |
| .CodeRay .comment{color:#998;font-style:italic} |
| .CodeRay .char{color:#04d} |
| .CodeRay .char .content{color:#04d} |
| .CodeRay .char .delimiter{color:#039} |
| .CodeRay .class{color:#458;font-weight:bold} |
| .CodeRay .complex{color:#a08} |
| .CodeRay .constant,.CodeRay .predefined-constant{color:#008080} |
| .CodeRay .color{color:#099} |
| .CodeRay .class-variable{color:#369} |
| .CodeRay .decorator{color:#b0b} |
| .CodeRay .definition{color:#099} |
| .CodeRay .delimiter{color:#000} |
| .CodeRay .doc{color:#970} |
| .CodeRay .doctype{color:#34b} |
| .CodeRay .doc-string{color:#d42} |
| .CodeRay .escape{color:#666} |
| .CodeRay .entity{color:#800} |
| .CodeRay .error{color:#808} |
| .CodeRay .exception{color:inherit} |
| .CodeRay .filename{color:#099} |
| .CodeRay .function{color:#900;font-weight:bold} |
| .CodeRay .global-variable{color:#008080} |
| .CodeRay .hex{color:#058} |
| .CodeRay .integer,.CodeRay .float{color:#099} |
| .CodeRay .include{color:#555} |
| .CodeRay .inline{color:#000} |
| .CodeRay .inline .inline{background:#ccc} |
| .CodeRay .inline .inline .inline{background:#bbb} |
| .CodeRay .inline .inline-delimiter{color:#d14} |
| .CodeRay .inline-delimiter{color:#d14} |
| .CodeRay .important{color:#555;font-weight:bold} |
| .CodeRay .interpreted{color:#b2b} |
| .CodeRay .instance-variable{color:#008080} |
| .CodeRay .label{color:#970} |
| .CodeRay .local-variable{color:#963} |
| .CodeRay .octal{color:#40e} |
| .CodeRay .predefined{color:#369} |
| .CodeRay .preprocessor{color:#579} |
| .CodeRay .pseudo-class{color:#555} |
| .CodeRay .directive{font-weight:bold} |
| .CodeRay .type{font-weight:bold} |
| .CodeRay .predefined-type{color:inherit} |
| .CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} |
| .CodeRay .key{color:#808} |
| .CodeRay .key .delimiter{color:#606} |
| .CodeRay .key .char{color:#80f} |
| .CodeRay .value{color:#088} |
| .CodeRay .regexp .delimiter{color:#808} |
| .CodeRay .regexp .content{color:#808} |
| .CodeRay .regexp .modifier{color:#808} |
| .CodeRay .regexp .char{color:#d14} |
| .CodeRay .regexp .function{color:#404;font-weight:bold} |
| .CodeRay .string{color:#d20} |
| .CodeRay .string .string .string{background:#ffd0d0} |
| .CodeRay .string .content{color:#d14} |
| .CodeRay .string .char{color:#d14} |
| .CodeRay .string .delimiter{color:#d14} |
| .CodeRay .shell{color:#d14} |
| .CodeRay .shell .delimiter{color:#d14} |
| .CodeRay .symbol{color:#990073} |
| .CodeRay .symbol .content{color:#a60} |
| .CodeRay .symbol .delimiter{color:#630} |
| .CodeRay .tag{color:#008080} |
| .CodeRay .tag-special{color:#d70} |
| .CodeRay .variable{color:#036} |
| .CodeRay .insert{background:#afa} |
| .CodeRay .delete{background:#faa} |
| .CodeRay .change{color:#aaf;background:#007} |
| .CodeRay .head{color:#f8f;background:#505} |
| .CodeRay .insert .insert{color:#080} |
| .CodeRay .delete .delete{color:#800} |
| .CodeRay .change .change{color:#66f} |
| .CodeRay .head .head{color:#f4f} |
| </style> |
| <script type="text/x-mathjax-config"> |
| MathJax.Hub.Config({ |
| messageStyle: "none", |
| tex2jax: { |
| inlineMath: [["\\(", "\\)"]], |
| displayMath: [["\\[", "\\]"]], |
| ignoreClass: "nostem|nolatexmath" |
| }, |
| asciimath2jax: { |
| delimiters: [["\\$", "\\$"]], |
| ignoreClass: "nostem|noasciimath" |
| }, |
| TeX: { equationNumbers: { autoNumber: "none" } } |
| }) |
| MathJax.Hub.Register.StartupHook("AsciiMath Jax Ready", function () { |
| MathJax.InputJax.AsciiMath.postfilterHooks.Add(function (data, node) { |
| if ((node = data.script.parentNode) && (node = node.parentNode) && node.classList.contains('stemblock')) { |
| data.math.root.display = "block" |
| } |
| return data |
| }) |
| }) |
| </script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script> |
| <!-- |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| |
| <div id="footer"> |
| <div id="footer-text"> |
| <a href="https://www.eclipse.org">Eclipse Home</a> |
| | |
| <a href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a> |
| | |
| <a href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a> |
| | |
| <a href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a> |
| | |
| <a href="https://www.eclipse.org/legal">Eclipse Legal</a> |
| </div> |
| </div> |
| </body> |
| </html> |
