So I'm attempting to consolidate what I know of the TeraTerm language into a single mega-post. If you have any knowledge that you think would be a valuable addition to this post, feel free to let me know.
Note that this is pretty much just an abridged form of the language reference tied into a somewhat cohesive format. Just because something isn't mentioned here doesn't mean it doesn't exist; check out the official [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/index.html]language reference[/url] and search the forums to get a handle on some of TeraTerm's more advanced features. This is really not a full-fledged tutorial to take you from the very basics of computer literacy; if you have no prior programming experience this may be challenging to follow.
As a little precursor, if you happen to use [url=http://www.pnotepad.org/]Programmer's Notepad[/url] as your editor of choice, the NSIS Installer highlighting scheme matches fairly well with this scripting language. Vim users might be able to make use of [url=http://www.vim.org/scripts/script.php?script_id=3129]this highlighting scheme[/url] (somewhat outdated, won't have latest keywords).
So to start things off, let's deal with variables.
There are two types of variables: Strings (limited to 255 characters) , and Integers (Limited to ~ +/-2 billion) ([url=http://logmett.com/forum/viewtopic.php?f=8&t=2080]want to go bigger?[/url]). The type is determined implicitly when the variable is created and cannot be altered afterwards.
Also, since TeraTerm 4.72, there are now arrays of both of these types (limited to 65536 indices per array)
But variables by themselves are boring. The real basis of any programming language is the [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/ifthenelseif.html]if[/url] statement. However an if statement by itself is somewhat boring, so let's go a little further and also show you a [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/wait.html]wait[/url] statement:
The wait statement is one of the more or less unique features of TeraTerm. Essentially, it reads through all of the serial output that hasn't been parsed yet, and when one of the strings in its sensitivity list is found, it sets result to the index of that string and moves on. The [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/setsync.html]documentation for the setsync[/url] command has a partial general overview for how TeraTerm internally works.
Note that you can also set a timeout for wait, and it will then only hold up the execution of the script for at most timeout.mtimeout seconds:
A nice counterpoint to the 'wait' command is the '[url=http://ttssh2.sourceforge.jp/manual/en/macro/command/sendln.html]sendln[/url]' and '[url=http://ttssh2.sourceforge.jp/manual/en/macro/command/send.html]send[/url]' commands. These guys do pretty much what their names suggest: they write stuff back out to the terminal (with sendln adding a newline at the end of its string).
A common use that I have for the wait/sendln pair is to send a series of commands to a machine.
For example, when sending a series of commands to a Linux box, it might look something like the following:
This ensures that the prior command has finished before you send the next command. The sendkcode command is also occasionally useful in some cases.
Note that the above code is somewhat ugly. If the prompt were to change (say from root@localhost to root@servername), I'd have to manually replace a bunch of lines. Since I'm lazy, the following format is much nicer:
That looks much nicer.
Branching is all well and good, but eventually you will want to do something that has some repetition in it. Teraterm has several more or less standard looping constructs
I won't go into too much detail about all of these; TeraTerm probably has more looping constructs than is really healthy, but definitely keep in mind the 'for' loop, and the fact that the 'do while' loop can be done as a pre-test loop or a post-test loop. The 'break' command can also be used to escape from a loop before its condition triggers
Lastly for the basics is TeraTerm's goto command. Some people (especially those experienced with C and who have experienced the nightmares of [url=http://en.wikipedia.org/wiki/Spaghetti_code]spaghetti code[/url]) view gotos as positively [url=http://www.u.arizona.edu/~rubinson/copyright_violations/Go_To_Considered_Harmful.html]evil[/url] and wish they could be nuked from every language in existence. Gotos can do just about anything, but typically not as nicely as one of the above looping structures. About the only place that gotos should really go is in error handling:
TeraTerm and regular expressions
Regular expressions are an interesting creature in and of themselves. An old and relatively well-known quote about regular expressions (regexes) goes something like this:
ome people, when confronted with a problem, think “I know, I'll use regular expressions.” Now they have two problems.
Regexes are a double-edged sword that allow you to do stuff with strings that would normally not be possible. Since I don't really want to go into all the nitty gritty, here's a link to [url=http://en.wikipedia.org/wiki/Regular_expression]wikipedia[/url], as well as a[url=http://www.regular-expressions.info/]fairly-well-laid-out regex tutorial site[/url]. Note that TeraTerm has also [url=http://ttssh2.sourceforge.jp/manual/en/reference/RE.txt]posted a reference[/url] for the regex engine that they use, but that isn't really laid out for learning...
TeraTerm has several commands which use the power of regular expressions (let me know which one's I'm forgetting...):
strmatch and strreplace are both relatively normal. You put your regular expression in, and TeraTerm works its magic.[url=http://ttssh2.sourceforge.jp/manual/en/macro/command/waitregex.html]waitregex[/url]
is a beast that I've seen misused in these forums time and again. In many ways, it is identical to the wait command, just with regular expression support. The large difference is with regular expression matching. Regular expression matching is what happens when a regular expression with parenthesis triggers on a string. The result inside the string is then returned (in normal regular expressions, it is returned as \1, \2, \3, etc, while with TeraTerm, they are stored in the groupmatchstr1, groupmatchstr2,...,groupmatchstr9 variables).
An example is as follows:
Let's pick the above code fragment apart bit by bit.
First we have '[0-9]+' This regex essentially grabs the largest amount of consecutive characters that fall between 0 and 9. The parenthesis '(...)' are what initiate the grouping. With the parenthesis, the string that was caught by '[0-9]+' gets stored into groupmatchstr1. If the regular expression as a whole was triggered, the result will be one and the if statement will let the str2int command work its magic. The str2int command (and its counterpart, the int2str command) do exactly what their names suggest: convert between string and integer variables.
Thus, if the 'value = 5643' was received on the terminal, this code would set returnValue to 5643
Note that waitregex only works on the first 255 characters of a line, so anything further than that and you're going to have to find another way.File input and outputMy file I/O skills are minimal at best. Anything that you'd care to offer is gladly acceptedAlso, don't forget about the ability to use logging commands in some cases (check out [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/loginfo.html]loginfo[/url], [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/logopen.html]logopen[/url], [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/logclose.html]logclose[/url], [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/logstart.html]logstart[/url], [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/logpause.html]logpause[/url], and [url=http://ttssh2.sourceforge.jp/manual/en/macro/command/logWrite.html]logwrite[/url])User input and output
Most of the commands used here are described in the Miscellaneous Commands section of the TTL Command Reference.
This is one of the most commonly-used UI-type commands of the macro language. It pops up a window with the title equal to <title>, and the content equal to <message>, with an Ok button at the bottom. Note that code beneath this command won't execute until Ok is clicked.
This is almost identical to the messagebox, however rather than an Ok button, there's a Yes and a No button. If Yes is clicked, result=1, otherwise result=0
The third of the *box commands that I use on a normal basis, this is like the messagebox command, but with an area that the user can type stuff in. That area is populated with <default> when the window first appears, and after the user clicks Ok, the variable 'inputstr' contains the value of that area.Strings!!!Fill this section with stuff for commands like sprintf2Connecting to things other than serial ports and whatnotI'm really not at all good with TeraTerm in this department. If someone else here has some wisdom to offer, feel free to drop it off here...
Any feedback is appreciated, both for my sake, and for all of the newbies out there. The main goal of this post is to be a one-stop learning reference for people who are just learning the language, as well as to facilitate the general usability of it through simple examples.
Good luck, bon apetit, hasta la vista, whatever. Just go out and make/break something...
10/24/2012 - Added a brief (unverified) description of arrays (I use a slightly older version of TT at work, and primarily use Linux at home currently, so I haven't had a chance to play around with these)
10/31/2012 - Added more formatting/hyperlinks and clarified a few points
Let's keep the suggestions coming!