Skip to content

Commit 0194ec7

Browse files
authored
Update guide.md
1 parent 71237aa commit 0194ec7

File tree

1 file changed

+17
-6
lines changed

1 file changed

+17
-6
lines changed

docs/guide.md

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -136,12 +136,21 @@ r"\|\^>[A-Z]{6}<\^\|" #end-flag-line
136136

137137
**Unexpected** output in `stdout` is also easy to parse, because these things are not wrapped by any preset flags. They are usually caused by exceptions which can not be handled and cause current process to exit abnormally.
138138

139-
* `|v>ARGINF<v|` & `|^>ARGINF<^|`
140-
* `|v>EXCEPT<v|` & `|^>EXCEPT<^|`
141-
* `|v>STRING<v|` & `|^>STRING<^|`
142-
* `|v>FORMAT<v|` & `|^>FORMAT<^|`
143-
* `|v>ATTACH<v|` & `|^>ATTACH<^|`
144-
* `|v>ILOGIN<v|` & `|^>ILOGIN<^|`
139+
### 2.2.2. Meaning of each flag-line
140+
141+
The so called *flag-line* always appear in pair, with one indicating the start of messages and the other indicating the end. Different words wrapped by `>` and `<` indicate different message types.
142+
143+
* `|v>ARGINF<v|`&`|^>ARGINF<^|`&emsp;Messages come from the patched `argparse.ArgumentParser`. This patched stuff would never call `sys.exit` when it fails in parsing. Usually the messages are used to inform you the parser is waiting for input or whether the parameters it read from `stdin` are legal.
144+
145+
* `|v>EXCEPT<v|`&`|^>EXCEPT<^|`&emsp;It indicates that an exception has been caught and properly handled. Exceptions within the expected range could be various. Such as a socket error occurs (e.g. TCP connection timeout), or the Bugzilla server throws an error. These exceptions are not fatal, and indicate that this round is not successful, and it is best to directly jump into a new round.
146+
147+
* `|v>FORMAT<v|`&`|^>FORMAT<^|`&emsp;Output stuff when using `--outputformat` option.
148+
149+
* `|v>ATTACH<v|`&`|^>ATTACH<^|`&emsp;Output stuff from performing `attach` command.
150+
151+
* `|v>ILOGIN<v|`&`|^>ILOGIN<^|`&emsp;Stuff about login or API key. In some situations, terminals will block in the next line of its *end-flag-line*, waiting for the user name, password, or API key to be written into `stdin`. For the interactive behavior about login, it is recommanded to check the methods with names beginning with `interactive_` in `base.py`.
152+
153+
* `|v>STRING<v|`&`|^>STRING<^|`&emsp;Other general output stuff.
145154

146155
## 2.3. Environment variables
147156

@@ -153,6 +162,8 @@ r"\|\^>[A-Z]{6}<\^\|" #end-flag-line
153162

154163
### 2.3.4. `__BUGZILLA_UNITTEST_DEBUG`
155164

165+
## 2.4 Exit *MI*
166+
156167
# 3. Tips
157168

158169
## 3.1. Explicitly specify *XMLRPC* or *REST*

0 commit comments

Comments
 (0)