new version number for developer release
[xboard.git] / ics-parsing.txt
1 Parsing of ICS Output
2 Updated to match xboard/WinBoard 4.0.2
3 ==============================================================================
4
5 This document describes how xboard and WinBoard parse ICS output.  The
6 general parsing method is to compare a list of patterns against the
7 current line (whether partial or complete) each time new input is
8 received from ICS.  The patterns are considered in a fixed order.  The
9 pattern matching is not "anchored", so unmatched text at the beginning
10 of a line (including the prompt, usually) is skipped.  Whenever a
11 pattern is matched, the characters are "consumed" and matching begins
12 again with the next unmatched character, starting at the top of the
13 list.  The last pattern is "\n", causing characters up to a newline to
14 be discarded if they have not matched any patterns.  The pattern
15 language is very simple.  Every character but "*" must match
16 literally.  "*" matches zero or more characters that don't include a
17 newline and don't match the character immediately following the *, if
18 any.  A "*" at the end of a pattern will not match until a complete
19 line is received
20
21 This method of pattern matching is rather fragile.  The patterns have
22 to be chosen quite carefully to avoid unexpected results.  For
23 example, at one time "* shouts: *" was used to match shouts, while
24 "<12>" was used to match the start of a board.  If someone shouted
25 "<12>", xboard would succeed in ignoring the <12> only if all the
26 characters from the ">" to the next newline were received at one time,
27 so that the shout pattern could match before the start-of-board
28 pattern was considered.  (This usually happens on TCP connections, but
29 is not guaranteed.)
30         
31 The patterns intentionally allow text in finger notes to be parsed and
32 colorized as tells, shouts, etc.  I did this because Zek once said
33 that ZIICS users like this feature, even though he originally
34 considered it a bug in ZIICS, and so he doesn't dare change it.  I may
35 eventually change it anyway so that people stop reporting it as a bug.
36
37 Here is the complete list of patterns that xboard looks for, in order.
38 The list was obtained by grepping the source code for "looking_at", my
39 procedure for pattern-matching.  Some of these are specific to FICS,
40 some to ICC, and some may be outdated---that is, they may reflect
41 messages that no ICS produces anymore.  Occasionally the same pattern
42 appears more than once because earlier occurrences were inside
43 if/then/else statements.  There may also be a couple of places where I
44 do a test without calling looking_at.
45
46 zippy.c (runs first if Zippy is active, otherwise skipped):
47 "* kibitzes: Hello from Crafty"
48 "* is in the computer list."
49 "* * is a computer *"
50 "* offers to be your bughouse partner"
51 "* tells you: [automatic message] I chose you"
52 "* agrees to be your partner"
53 "are no longer *'s partner"
54 "no longer have a bughouse partner"
55 "partner has disconnected"
56 "partner has just chosen a new partner"
57 "* tells you: [automatic message] I'm no longer your"
58 "* (your partner) tells you: *"
59 "* tells you: *"
60 "* says: *"
61 "--> * *"
62 "* shouts: *"
63 "* kibitzes: *"
64 "* whispers: *"
65 "You have * message*."
66 "* has left a message for you."
67 "* just sent you a message."
68 "--* (*:*): *"
69 "*. * (*:*): *"
70 "*. * at *:*: *"
71 "*(*): *"
72 "*(*)(*): *"
73 "Notification: * has arrived"
74 "Not sent -- * is censoring you"
75 "command is currently turned off"
76 "* * match * * requested with * (*)"
77 "* * match * requested with * (*)"
78 * has made an alternate proposal of * * match * *."
79 "Challenge: * (*) *(*) * * * * Loaded from *"
80 "Challenge: * (*) *(*) * * * * : * * Loaded from *"
81 "Challenge: * (*) *(*) * * * * : * *"
82 "Challenge: * (*) *(*) * * * * * *"
83 "Challenge: * (*) *(*) * * * *"
84 "offers you a draw"
85 "requests that the game be aborted"
86 "would like to abort"
87 "requests adjournment"
88 "would like to adjourn"
89
90 backend.c:
91 "ics%"                  /* right after login only; nonessential */
92 "chessclub.com"         /* before login; turns on ICC mode */
93 "\"*\" is *a registered name"
94 "Logging you in as \"*\""
95 "Your name will be \"*\""
96 "* s-shouts: "
97 "* c-shouts: "
98 "--->"                  /* seen in FICS login, not a shout */
99 "* shouts: "
100 "--> "
101 "* tells you: "
102 "* (your partner) tells you: "
103 "* says: "
104 "* has left a message "
105 "* just sent you a message:\n"
106 "*. * (*:*): "
107 "*. * at *:*: "
108 "* whispers: "
109 "* kibitzes: "
110 "*)(*): *"               /* channel tell or allobs or admin comment */
111 "*(*): *"                /* channel tell or allobs or admin comment */
112 "*)(*)(*): *"            /* channel tell */
113 "Challenge:"
114 "* offers you"
115 "* offers to be"
116 "* would like to"
117 "* requests to"
118 "Your opponent offers"
119 "Your opponent requests"
120 "\\   "                  /* continuation line */
121 "Black Strength :"       /* need to issue "style 12; refresh" */
122 "<<< style 10 board >>>" /* need to issue "style 12; refresh" */
123 "<10>"                   /* need to issue "style 12; refresh" */
124 "#@#"                    /* need to issue "style 12; refresh" */
125 "login:"
126 "\n<12> "
127 "<12> "
128 "\n<b1> "
129 "<b1> "
130 "* *vs. * *--- *"        /* move list coming */
131 "* * match, initial time: * minute*, increment: * second"
132 "Move  "                 /* move list is here */
133 "% "                     /* end of prompt; nonessential */
134 "}*"                     /* ends a move list */
135 "Adding game * to observation list"
136 "Game notification: * (*) vs. * (*)"
137 "Entering examine mode for game *"
138 "has made you an examiner of game *"
139 "Illegal move"
140 "Not a legal move"
141 "Your king is in check"
142 "It isn't your turn"
143 "It is not your move"
144 "still have time"
145 "not out of time"
146 "either player is out of time"
147 "has timeseal; checking"
148 "added * seconds to"
149 "seconds were added to"
150 "clock paused"
151 "clock resumed"
152 "Creating: * (*)* * (*)"
153 "Creating: * (*) [*] * (*)"
154 "{Game * (* vs. *) *}*"
155 "Removing game * from observation"
156 "no longer observing game *"
157 "Game * (*) has no examiners"
158 "no longer examining game *"
159 "\n"
160 "*% "                    /* end of prompt; nonessential */