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