tsh Commands

The basics of how to operate tsh.

Updated Sun Apr 10 09:54:53 EDT 2005 for tsh 2.900.

Starting tsh

Once you have installed and configured tsh, you’re ready to run tsh. Now tsh is a Perl script that runs under many different operating systems, and each operating system has a different way of starting programs.

In Mac OS/X, you may either open a Finder window to your tsh folder and double-click on the ‘osx-tsh.command’ icon, or follow the generic Unix instructions.

I have not supported Classic MacOS since 2003. If you would like a double-clickable icon that works with MacOS 9, please contact me.

With Unix, open a shell (terminal) window, cd to your tsh directory and enter “./tsh.pl” (or just “tsh.pl” if your path permits).

Under Windows, open a window to your tsh folder, then double-click on the dos-run.bat icon. You can also type “perl tsh.pl” in a DOS command window (Choose “Run Command” from the Windows Start menu, then enter “command”), if you prefer.

If you use an operating system not listed here, please contact me and I’ll add more instructions to this section.

If you get a message complaining that the configuration file can’t be Make sure that all ‘.pl’, ‘.t’ and ‘.config’ files are together in one directory, along with any OS-specific files you’re using to launch tsh.

When you successfully start tsh, you should see a sequence of messages something like the following.

Welcome to tsh version 2.800.
Loading configuration file.
Configuration file loaded.
Loading division A.
Loading division B.
Loading division C.
Loading division D.
Loading division E.
All divisions loaded.
tsh>

The “tsh>” is your main prompt. When you see it, you can type a command, about which much more will follow. The most important commands to remember are “help” and “quit”. After typing a command, don’t forget to press the return key.

Using tsh

tsh is a command shell. If you’re familiar with using shells such as any Unix shell, OS/X Terminal or even DOS, you can probably skip this paragraph. A command shell is a no-frills way of interacting with a computer. In a large window, the computer displays a prompt, inviting you to type in a command that the computer understands. When you do so and then press the return key (analogous to hitting your clock in Scrabble), the computer takes some action based on what you’ve entered, then prompts you for your next command. Sometimes your command is modal, causing the computer to prompt for and expect a different set of commands until the mode is complete.

Pay attention to the changing prompts, which indicate what information tsh needs. Don’t forget to press the return key to confirm each command.

All currently available tsh commands are listed below in tables for reference, grouped by function. Most users will not use most of these commands. Each command has a name which verbosely describes its purpose, but which can be abbreviated to the portion shown in capital letters as shown in its example. Most commands must be followed (on the same line, before pressing return) by one or more arguments. These arguments are represented in examples by names, which must be replaced by actual values. If you don’t enter correct arguments, tsh will tell you what the correct ones should be, and where it stopped understanding what you were typing. Within modal commands, the syntax of what you are supposed to type varies, but is usually shown in the prompt.

To take one case, the example for the “RoundStandings” command, which displays standings in a division as of a specified round, reads rs r d. This means that “RoundStandings” can be abbreviated to its capitalised letters “rs”, and that it must be followed by a round number and a division name. You would enter “rs 5 b” and press the return key to ask for Division B standings as of Round 5. If you have only one division in your tournament, you may omit division names as arguments to commands. In the preceding example, you would just enter “rs 5”.

tsh Command Reference

The following commands are used for entering tournament results, as well as checking and correcting them:

Command	Example	Description
Addscore	a r d	Begin entering new game scores for round `r`, division `d`. This command is modal, and keeps prompting for scores until you press return on a line without scores.
DELETEscore	delete p1 s1 p2 s2 r d	Delete the previously entered scores `s1` for player `p1` and `s2` for player `p2` in round `r` division `d`. This syntax is intentionally verbose to discourage the use of this command.
EditScores	d p r	Begin editing previously entered game scores, starting with player `p` in round `r`, division `d`. This command is modal.
MISSING	missing r	List all players whose round `r` scores have not yet been entered.
showScoreCard	sc d p	Show the correct scorecard for player `p` in division `d`, for checking.

The following commands generate reports based on tournament results:

Command	Example	Description
RATings	rat d	Show current division standings (with ratings estimates) for division `d`.
ResultsByRound	rbr r1-r2 d	Rank players in division `d` based only on rounds `r1` through `r2`, typically to compute “best results, day n” prizes.
RoundStandings	rs r d	Show standings for division `d` as of round `r`.
ShowPair	sp r d	Show pairings for round `r`, division `d`.
STandings	st d	Show current standings for division `d`.
showWallChart	wc d	Show correct wall chart for division `d`, to check against the physical chart.

The following commands are used for manually pairing rounds. You will need to know about them if you are configuring tsh before a tournament, or if you encounter an unexpected pairing situation and want to override automatic pairings.

Command	Example	Description
CAMbridgePair	camp d	Set up seven-round pairings as used in Cambridge ON for division `d`.
InitFontes	if nr d	Set up fixed pairings for `nr` rounds (typically 3) in division `d` to give later Fontes pairings a place to start. Players are randomly chosen from quartiles and paired in round-robin quads.
KOTH	koth rpt sr d	Add king-of-the-hill pairings allowing `rpt` repeats (0 for none, 1 for simple repeats, 2 for threepeats), based on round `sr` standings in division `d`.
NewSwiss	ns rpt sr d	Add a round of Swiss pairings. See KOTH above for descriptions of arguments.
PAIR	pair p1 p2 r d	Manually pair players `p1` and `p2` in round `r`, division `d`.
Pair1324	p1324 rpt sr d	Pair 1-3, 2-4, 5-7, 6-8, and so on, i.e., factored pairings with factor two. See KOTH above for descriptions of arguments.
PairMany	pm r d	Begin manually pairing a large number of players in round `r`, division `d`. This command is modal.
RoundRobin	rr d	Add a full round robin to a division.
UnPairRound	upr r d	Delete pairings.

The following pairing commands are deprecated, but are listed in case there is anyone who is still using them. All of these commands have been replaced by NewSwiss, which produces much better quality Swiss pairings.

Command	Example	Description
BYE	bye p s r d	Deprecated: use `PAIR` and `Addscore` instead.
PartialSWiss	psw rpt p1 p2 d	Deprecated: use `NewSwiss` instead.
PrePreSwiss	ppsw rpt p1 p2 d	Deprecated: use `NewSwiss` instead.
PRESWiss	ppsw rpt p1 p2 d	Deprecated: use `NewSwiss` instead.
SWiss	sw rpt sr d	Deprecated: use `NewSwiss` instead.

And here all the commands which don’t fit into one of the above categories:

Command	Example	Description
EVAL	eval code	Evaluate arbitary perl code. Use only if you know what you’re doing.
HELP	help	List a brief description of each command.
Look	l word	Look up `word` in dictionary. Optional, not yet part of the main distribution.
Quit	q	Quit tsh.
RANDomscores	rand d...	Give each player in division `d` a random score, to help simulate a tournament’s pairing system. Entering more than one division acts on each division, entering a division name more than once adds more than one round’s worth of random data.

There may also be external (plug-in) commands installed in your particular copy of tsh. These will be in a directory called ‘bin’, and listed in a configuration file there called ‘tshxcfg.txt’.