Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1993 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
4 | '\" Copyright (c) 2000 Scriptics Corporation. | |
5 | '\" | |
6 | '\" See the file "license.terms" for information on usage and redistribution | |
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
8 | '\" | |
9 | '\" RCS: @(#) $Id: scan.n,v 1.9.2.1 2004/10/27 14:23:58 dkf Exp $ | |
10 | '\" | |
11 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
12 | '\" manual entries. | |
13 | '\" | |
14 | '\" .AP type name in/out ?indent? | |
15 | '\" Start paragraph describing an argument to a library procedure. | |
16 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
17 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
18 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
19 | '\" needed; use .AS below instead) | |
20 | '\" | |
21 | '\" .AS ?type? ?name? | |
22 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
23 | '\" name are examples of largest possible arguments that will be passed | |
24 | '\" to .AP later. If args are omitted, default tab stops are used. | |
25 | '\" | |
26 | '\" .BS | |
27 | '\" Start box enclosure. From here until next .BE, everything will be | |
28 | '\" enclosed in one large box. | |
29 | '\" | |
30 | '\" .BE | |
31 | '\" End of box enclosure. | |
32 | '\" | |
33 | '\" .CS | |
34 | '\" Begin code excerpt. | |
35 | '\" | |
36 | '\" .CE | |
37 | '\" End code excerpt. | |
38 | '\" | |
39 | '\" .VS ?version? ?br? | |
40 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
41 | '\" of man pages. The first argument is ignored and used for recording | |
42 | '\" the version when the .VS was added, so that the sidebars can be | |
43 | '\" found and removed when they reach a certain age. If another argument | |
44 | '\" is present, then a line break is forced before starting the sidebar. | |
45 | '\" | |
46 | '\" .VE | |
47 | '\" End of vertical sidebar. | |
48 | '\" | |
49 | '\" .DS | |
50 | '\" Begin an indented unfilled display. | |
51 | '\" | |
52 | '\" .DE | |
53 | '\" End of indented unfilled display. | |
54 | '\" | |
55 | '\" .SO | |
56 | '\" Start of list of standard options for a Tk widget. The | |
57 | '\" options follow on successive lines, in four columns separated | |
58 | '\" by tabs. | |
59 | '\" | |
60 | '\" .SE | |
61 | '\" End of list of standard options for a Tk widget. | |
62 | '\" | |
63 | '\" .OP cmdName dbName dbClass | |
64 | '\" Start of description of a specific option. cmdName gives the | |
65 | '\" option's name as specified in the class command, dbName gives | |
66 | '\" the option's name in the option database, and dbClass gives | |
67 | '\" the option's class in the option database. | |
68 | '\" | |
69 | '\" .UL arg1 arg2 | |
70 | '\" Print arg1 underlined, then print arg2 normally. | |
71 | '\" | |
72 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
73 | '\" | |
74 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
75 | .if t .wh -1.3i ^B | |
76 | .nr ^l \n(.l | |
77 | .ad b | |
78 | '\" # Start an argument description | |
79 | .de AP | |
80 | .ie !"\\$4"" .TP \\$4 | |
81 | .el \{\ | |
82 | . ie !"\\$2"" .TP \\n()Cu | |
83 | . el .TP 15 | |
84 | .\} | |
85 | .ta \\n()Au \\n()Bu | |
86 | .ie !"\\$3"" \{\ | |
87 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
88 | .\".b | |
89 | .\} | |
90 | .el \{\ | |
91 | .br | |
92 | .ie !"\\$2"" \{\ | |
93 | \&\\$1 \\fI\\$2\\fP | |
94 | .\} | |
95 | .el \{\ | |
96 | \&\\fI\\$1\\fP | |
97 | .\} | |
98 | .\} | |
99 | .. | |
100 | '\" # define tabbing values for .AP | |
101 | .de AS | |
102 | .nr )A 10n | |
103 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
104 | .nr )B \\n()Au+15n | |
105 | .\" | |
106 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
107 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
108 | .. | |
109 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
110 | '\" # BS - start boxed text | |
111 | '\" # ^y = starting y location | |
112 | '\" # ^b = 1 | |
113 | .de BS | |
114 | .br | |
115 | .mk ^y | |
116 | .nr ^b 1u | |
117 | .if n .nf | |
118 | .if n .ti 0 | |
119 | .if n \l'\\n(.lu\(ul' | |
120 | .if n .fi | |
121 | .. | |
122 | '\" # BE - end boxed text (draw box now) | |
123 | .de BE | |
124 | .nf | |
125 | .ti 0 | |
126 | .mk ^t | |
127 | .ie n \l'\\n(^lu\(ul' | |
128 | .el \{\ | |
129 | .\" Draw four-sided box normally, but don't draw top of | |
130 | .\" box if the box started on an earlier page. | |
131 | .ie !\\n(^b-1 \{\ | |
132 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
133 | .\} | |
134 | .el \}\ | |
135 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
136 | .\} | |
137 | .\} | |
138 | .fi | |
139 | .br | |
140 | .nr ^b 0 | |
141 | .. | |
142 | '\" # VS - start vertical sidebar | |
143 | '\" # ^Y = starting y location | |
144 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
145 | .de VS | |
146 | .if !"\\$2"" .br | |
147 | .mk ^Y | |
148 | .ie n 'mc \s12\(br\s0 | |
149 | .el .nr ^v 1u | |
150 | .. | |
151 | '\" # VE - end of vertical sidebar | |
152 | .de VE | |
153 | .ie n 'mc | |
154 | .el \{\ | |
155 | .ev 2 | |
156 | .nf | |
157 | .ti 0 | |
158 | .mk ^t | |
159 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
160 | .sp -1 | |
161 | .fi | |
162 | .ev | |
163 | .\} | |
164 | .nr ^v 0 | |
165 | .. | |
166 | '\" # Special macro to handle page bottom: finish off current | |
167 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
168 | '\" # page bottom macro. | |
169 | .de ^B | |
170 | .ev 2 | |
171 | 'ti 0 | |
172 | 'nf | |
173 | .mk ^t | |
174 | .if \\n(^b \{\ | |
175 | .\" Draw three-sided box if this is the box's first page, | |
176 | .\" draw two sides but no top otherwise. | |
177 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
179 | .\} | |
180 | .if \\n(^v \{\ | |
181 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
182 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
183 | .\} | |
184 | .bp | |
185 | 'fi | |
186 | .ev | |
187 | .if \\n(^b \{\ | |
188 | .mk ^y | |
189 | .nr ^b 2 | |
190 | .\} | |
191 | .if \\n(^v \{\ | |
192 | .mk ^Y | |
193 | .\} | |
194 | .. | |
195 | '\" # DS - begin display | |
196 | .de DS | |
197 | .RS | |
198 | .nf | |
199 | .sp | |
200 | .. | |
201 | '\" # DE - end display | |
202 | .de DE | |
203 | .fi | |
204 | .RE | |
205 | .sp | |
206 | .. | |
207 | '\" # SO - start of list of standard options | |
208 | .de SO | |
209 | .SH "STANDARD OPTIONS" | |
210 | .LP | |
211 | .nf | |
212 | .ta 5.5c 11c | |
213 | .ft B | |
214 | .. | |
215 | '\" # SE - end of list of standard options | |
216 | .de SE | |
217 | .fi | |
218 | .ft R | |
219 | .LP | |
220 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
221 | .. | |
222 | '\" # OP - start of full description for a single option | |
223 | .de OP | |
224 | .LP | |
225 | .nf | |
226 | .ta 4c | |
227 | Command-Line Name: \\fB\\$1\\fR | |
228 | Database Name: \\fB\\$2\\fR | |
229 | Database Class: \\fB\\$3\\fR | |
230 | .fi | |
231 | .IP | |
232 | .. | |
233 | '\" # CS - begin code excerpt | |
234 | .de CS | |
235 | .RS | |
236 | .nf | |
237 | .ta .25i .5i .75i 1i | |
238 | .. | |
239 | '\" # CE - end code excerpt | |
240 | .de CE | |
241 | .fi | |
242 | .RE | |
243 | .. | |
244 | .de UL | |
245 | \\$1\l'|0\(ul'\\$2 | |
246 | .. | |
247 | .TH scan n 8.4 Tcl "Tcl Built-In Commands" | |
248 | .BS | |
249 | '\" Note: do not modify the .SH NAME line immediately below! | |
250 | .SH NAME | |
251 | scan \- Parse string using conversion specifiers in the style of sscanf | |
252 | .SH SYNOPSIS | |
253 | \fBscan \fIstring format \fR?\fIvarName varName ...\fR? | |
254 | .BE | |
255 | ||
256 | .SH INTRODUCTION | |
257 | .PP | |
258 | This command parses fields from an input string in the same fashion as the | |
259 | ANSI C \fBsscanf\fR procedure and returns a count of the number of | |
260 | conversions performed, or -1 if the end of the input string is reached | |
261 | before any conversions have been performed. \fIString\fR gives the input | |
262 | to be parsed and \fIformat\fR indicates how to parse it, using \fB%\fR | |
263 | conversion specifiers as in \fBsscanf\fR. Each \fIvarName\fR gives the | |
264 | name of a variable; when a field is scanned from \fIstring\fR the result is | |
265 | converted back into a string and assigned to the corresponding variable. | |
266 | If no \fIvarName\fR variables are specified, then \fBscan\fR works in an | |
267 | inline manner, returning the data that would otherwise be stored in the | |
268 | variables as a list. In the inline case, an empty string is returned when | |
269 | the end of the input string is reached before any conversions have been | |
270 | performed. | |
271 | .SH "DETAILS ON SCANNING" | |
272 | .PP | |
273 | \fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together. | |
274 | If the next character in \fIformat\fR is a blank or tab then it | |
275 | matches any number of white space characters in \fIstring\fR (including | |
276 | zero). | |
277 | Otherwise, if it isn't a \fB%\fR character then it | |
278 | must match the next character of \fIstring\fR. | |
279 | When a \fB%\fR is encountered in \fIformat\fR, it indicates | |
280 | the start of a conversion specifier. | |
281 | .VS 8.4 | |
282 | A conversion specifier contains up to four fields after the \fB%\fR: | |
283 | a \fB*\fR, which indicates that the converted value is to be discarded | |
284 | instead of assigned to a variable; a XPG3 position specifier; a number | |
285 | indicating a maximum field width; a field size modifier; and a | |
286 | conversion character. | |
287 | .VE 8.4 | |
288 | All of these fields are optional except for the conversion character. | |
289 | The fields that are present must appear in the order given above. | |
290 | .PP | |
291 | When \fBscan\fR finds a conversion specifier in \fIformat\fR, it | |
292 | first skips any white-space characters in \fIstring\fR (unless the | |
293 | specifier is \fB[\fR or \fBc\fR). | |
294 | Then it converts the next input characters according to the | |
295 | conversion specifier and stores the result in the variable given | |
296 | by the next argument to \fBscan\fR. | |
297 | .PP | |
298 | If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in | |
299 | ``\fB%2$d\fR'', then the variable to use is not taken from the next | |
300 | sequential argument. Instead, it is taken from the argument indicated | |
301 | by the number, where 1 corresponds to the first \fIvarName\fR. If | |
302 | there are any positional specifiers in \fIformat\fR then all of the | |
303 | specifiers must be positional. Every \fIvarName\fR on the argument | |
304 | list must correspond to exactly one conversion specifier or an error | |
305 | is generated, or in the inline case, any position can be specified | |
306 | at most once and the empty positions will be filled in with empty strings. | |
307 | .PP | |
308 | The following conversion characters are supported: | |
309 | .TP 10 | |
310 | \fBd\fR | |
311 | The input field must be a decimal integer. | |
312 | It is read in and the value is stored in the variable as a decimal string. | |
313 | .VS 8.4 | |
314 | If the \fBl\fR or \fBL\fR field size modifier is given, the scanned | |
315 | value will have an internal representation that is at least 64-bits in | |
316 | size. | |
317 | .VE 8.4 | |
318 | .TP 10 | |
319 | \fBo\fR | |
320 | The input field must be an octal integer. It is read in and the | |
321 | value is stored in the variable as a decimal string. | |
322 | .VS 8.4 | |
323 | If the \fBl\fR or \fBL\fR field size modifier is given, the scanned | |
324 | value will have an internal representation that is at least 64-bits in | |
325 | size. | |
326 | If the value exceeds MAX_INT (017777777777 on platforms using 32-bit | |
327 | integers when the \fBl\fR and \fBL\fR modifiers are not given), it | |
328 | will be truncated to a signed integer. Hence, 037777777777 will | |
329 | appear as -1 on a 32-bit machine by default. | |
330 | .VE 8.4 | |
331 | .TP 10 | |
332 | \fBx\fR | |
333 | The input field must be a hexadecimal integer. It is read in | |
334 | and the value is stored in the variable as a decimal string. | |
335 | .VS 8.4 | |
336 | If the \fBl\fR or \fBL\fR field size modifier is given, the scanned | |
337 | value will have an internal representation that is at least 64-bits in | |
338 | size. | |
339 | If the value exceeds MAX_INT (0x7FFFFFFF on platforms using 32-bit | |
340 | integers when the \fBl\fR and \fBL\fR modifiers are not given), it | |
341 | will be truncated to a signed integer. Hence, 0xFFFFFFFF will appear | |
342 | as -1 on a 32-bit machine. | |
343 | .VE 8.4 | |
344 | .TP 10 | |
345 | \fBu\fR | |
346 | The input field must be a decimal integer. The value is stored in the | |
347 | variable as an unsigned decimal integer string. | |
348 | .VS 8.4 | |
349 | If the \fBl\fR or \fBL\fR field size modifier is given, the scanned | |
350 | value will have an internal representation that is at least 64-bits in | |
351 | size. | |
352 | .VE 8.4 | |
353 | .TP 10 | |
354 | \fBi\fR | |
355 | The input field must be an integer. The base (i.e. decimal, octal, or | |
356 | hexadecimal) is determined in the same fashion as described in | |
357 | \fBexpr\fR. The value is stored in the variable as a decimal string. | |
358 | .VS 8.4 | |
359 | If the \fBl\fR or \fBL\fR field size modifier is given, the scanned | |
360 | value will have an internal representation that is at least 64-bits in | |
361 | size. | |
362 | .VE 8.4 | |
363 | .TP 10 | |
364 | \fBc\fR | |
365 | A single character is read in and its binary value is stored in | |
366 | the variable as a decimal string. | |
367 | Initial white space is not skipped in this case, so the input | |
368 | field may be a white-space character. | |
369 | This conversion is different from the ANSI standard in that the | |
370 | input field always consists of a single character and no field | |
371 | width may be specified. | |
372 | .TP 10 | |
373 | \fBs\fR | |
374 | The input field consists of all the characters up to the next | |
375 | white-space character; the characters are copied to the variable. | |
376 | .TP 10 | |
377 | \fBe\fR or \fBf\fR or \fBg\fR | |
378 | The input field must be a floating-point number consisting | |
379 | of an optional sign, a string of decimal digits possibly | |
380 | containing a decimal point, and an optional exponent consisting | |
381 | of an \fBe\fR or \fBE\fR followed by an optional sign and a string of | |
382 | decimal digits. | |
383 | It is read in and stored in the variable as a floating-point string. | |
384 | .TP 10 | |
385 | \fB[\fIchars\fB]\fR | |
386 | The input field consists of any number of characters in | |
387 | \fIchars\fR. | |
388 | The matching string is stored in the variable. | |
389 | If the first character between the brackets is a \fB]\fR then | |
390 | it is treated as part of \fIchars\fR rather than the closing | |
391 | bracket for the set. | |
392 | If \fIchars\fR | |
393 | contains a sequence of the form \fIa\fB\-\fIb\fR then any | |
394 | character between \fIa\fR and \fIb\fR (inclusive) will match. | |
395 | If the first or last character between the brackets is a \fB\-\fR, then | |
396 | it is treated as part of \fIchars\fR rather than indicating a range. | |
397 | .TP 10 | |
398 | \fB[^\fIchars\fB]\fR | |
399 | The input field consists of any number of characters not in | |
400 | \fIchars\fR. | |
401 | The matching string is stored in the variable. | |
402 | If the character immediately following the \fB^\fR is a \fB]\fR then it is | |
403 | treated as part of the set rather than the closing bracket for | |
404 | the set. | |
405 | If \fIchars\fR | |
406 | contains a sequence of the form \fIa\fB\-\fIb\fR then any | |
407 | character between \fIa\fR and \fIb\fR (inclusive) will be excluded | |
408 | from the set. | |
409 | If the first or last character between the brackets is a \fB\-\fR, then | |
410 | it is treated as part of \fIchars\fR rather than indicating a range. | |
411 | .TP 10 | |
412 | \fBn\fR | |
413 | No input is consumed from the input string. Instead, the total number | |
414 | of characters scanned from the input string so far is stored in the variable. | |
415 | .LP | |
416 | The number of characters read from the input for a conversion is the | |
417 | largest number that makes sense for that particular conversion (e.g. | |
418 | as many decimal digits as possible for \fB%d\fR, as | |
419 | many octal digits as possible for \fB%o\fR, and so on). | |
420 | The input field for a given conversion terminates either when a | |
421 | white-space character is encountered or when the maximum field | |
422 | width has been reached, whichever comes first. | |
423 | If a \fB*\fR is present in the conversion specifier | |
424 | then no variable is assigned and the next scan argument is not consumed. | |
425 | .SH "DIFFERENCES FROM ANSI SSCANF" | |
426 | .PP | |
427 | The behavior of the \fBscan\fR command is the same as the behavior of | |
428 | the ANSI C \fBsscanf\fR procedure except for the following differences: | |
429 | .IP [1] | |
430 | \fB%p\fR conversion specifier is not currently supported. | |
431 | .IP [2] | |
432 | For \fB%c\fR conversions a single character value is | |
433 | converted to a decimal string, which is then assigned to the | |
434 | corresponding \fIvarName\fR; | |
435 | no field width may be specified for this conversion. | |
436 | .IP [3] | |
437 | .VS 8.4 | |
438 | The \fBh\fR modifier is always ignored and the \fBl\fR and \fBL\fR | |
439 | modifiers are ignored when converting real values (i.e. type | |
440 | \fBdouble\fR is used for the internal representation). | |
441 | .VE 8.4 | |
442 | .IP [4] | |
443 | If the end of the input string is reached before any conversions have been | |
444 | performed and no variables are given, an empty string is returned. | |
445 | .SH EXAMPLES | |
446 | Parse a simple color specification of the form \fI#RRGGBB\fR using | |
447 | hexadecimal conversions with field sizes: | |
448 | .CS | |
449 | set string "#08D03F" | |
450 | \fBscan\fR $string "#%2x%2x%2x" r g b | |
451 | .CE | |
452 | .PP | |
453 | Parse a \fIHH:MM\fR time string, noting that this avoids problems with | |
454 | octal numbers by forcing interpretation as decimals (if we did not | |
455 | care, we would use the \fB%i\fR conversion instead): | |
456 | .CS | |
457 | set string "08:08" ;# *Not* octal! | |
458 | if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} { | |
459 | error "not a valid time string" | |
460 | } | |
461 | # We have to understand numeric ranges ourselves... | |
462 | if {$minutes < 0 || $minutes > 59} { | |
463 | error "invalid number of minutes" | |
464 | } | |
465 | .CE | |
466 | .PP | |
467 | Break a string up into sequences of non-whitespace characters (note | |
468 | the use of the \fB%n\fR conversion so that we get skipping over | |
469 | leading whitespace correct): | |
470 | .CS | |
471 | set string " a string {with braced words} + leading space " | |
472 | set words {} | |
473 | while {[\fBscan\fR $string %s%n word length] == 2} { | |
474 | lappend words $word | |
475 | set string [string range $string $length end] | |
476 | } | |
477 | .CE | |
478 | .PP | |
479 | Parse a simple coordinate string, checking that it is complete by | |
480 | looking for the terminating character explicitly: | |
481 | .CS | |
482 | set string "(5.2,-4e-2)" | |
483 | # Note that the spaces before the literal parts of | |
484 | # the scan pattern are significant, and that ")" is | |
485 | # the Unicode character \\u0029 | |
486 | if { | |
487 | [\fBscan\fR $string " (%f ,%f %c" x y last] != 3 | |
488 | || $last != 0x0029 | |
489 | } then { | |
490 | error "invalid coordinate string" | |
491 | } | |
492 | puts "X=$x, Y=$y" | |
493 | .CE | |
494 | ||
495 | .SH "SEE ALSO" | |
496 | format(n), sscanf(3) | |
497 | ||
498 | .SH KEYWORDS | |
499 | conversion specifier, parse, scan |