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
.
6 '\" See the file
"license.terms" for information on usage
and redistribution
7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
9 '\" RCS: @(#) $Id: scan.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
11 '\" The definitions below are for supplemental macros used in Tcl/Tk
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
)
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.
27 '\" Start box enclosure
. From here until next
.BE
, everything will be
28 '\" enclosed in one large box.
31 '\" End of box enclosure
.
34 '\" Begin code excerpt.
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.
47 '\" End of vertical sidebar
.
50 '\" Begin an indented unfilled display.
53 '\" End of indented unfilled display
.
56 '\" Start of list of standard options for a Tk widget. The
57 '\" options follow on successive lines
, in four columns separated
61 '\" End of
list of standard options
for a Tk widget
.
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.
70 '\" Print arg1 underlined
, then print arg2 normally
.
72 '\" RCS
: @
(#) $Id: scan.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
74 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
78 '\" # Start an argument description
82 . ie !"\\$2"" .TP \\n()Cu
87 \&\\$1 \\fI\\$2\\fP (\\$3)
100 '\" # define tabbing values for .AP
103 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
106 .if !"\\$2
"" .nr
)B
\\w
'\\$2'u
+\\n()Au
+3n
107 .nr
)C
\\n()Bu
+\\w
'(in/out)'u
+2n
109 .AS Tcl_Interp Tcl_CreateInterp
in/out
110 '\" # BS - start boxed text
111 '\" # ^y = starting y location
119 .if n \l'\\n(.lu\
(ul
'
122 '\" # BE - end boxed text (draw box now)
127 .ie n \l
'\\n(^lu\(ul'
129 .\" Draw four
-sided box normally
, but don
't draw top of
130 .\" box if the box started on an earlier page.
132 \h'-1.5n
'\L'|\\n(^yu
-1v
'\l'\\n(^lu
+3n\
(ul
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
135 \h'-1.5n
'\L'|\\n(^yu
-1v
'\h'\\n(^lu
+3n
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
142 '\" # VS - start vertical sidebar
143 '\" # ^Y = starting y location
144 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
148 .ie n 'mc \s12\(br\s0
151 '\" # VE - end of vertical sidebar
159 \h
'|\\n(^lu+3n'\L
'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h
'-|\\n(^lu+3n'
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.
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
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
195 '\" # DS - begin display
201 '\" # DE - end display
207 '\" # SO - start of list of standard options
209 .SH
"STANDARD OPTIONS"
215 '\" # SE - end of list of standard options
220 See the \\fBoptions\\fR manual entry for details on the standard options.
222 '\" # OP - start of full description for a single option
227 Command
-Line Name
: \\fB
\\$1
\\fR
228 Database Name
: \\fB
\\$2
\\fR
229 Database Class
: \\fB
\\$3
\\fR
233 '\" # CS - begin code excerpt
239 '\" # CE - end code excerpt
247 .TH scan n
8.3 Tcl
"Tcl Built-In Commands"
249 '\" Note: do not modify the .SH NAME line immediately below!
251 scan \- Parse string using conversion specifiers in the style of sscanf
253 \fBscan \fIstring format \fR?\fIvarName varName ...\fR?
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.
267 If no \fIvarName\fR variables are specified, then \fBscan\fR works in an
268 inline manner, returning the data that would otherwise be stored in the
269 variables as a list. In the inline case, an empty string is returned when
270 the end of the input string is reached before any conversions have been
274 .SH "DETAILS ON SCANNING"
276 \fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together.
277 If the next character in \fIformat\fR is a blank or tab then it
278 matches any number of white space characters in \fIstring\fR (including
280 Otherwise, if it isn't a
\fB
%\fR character then it
281 must
match the next character of
\fIstring
\fR
.
282 When a
\fB
%\fR is encountered
in \fIformat
\fR
, it indicates
283 the start of a conversion specifier
.
284 A conversion specifier contains up to four fields after the
\fB
%\fR
:
285 a
\fB
*\fR
, which indicates that the converted value is to be discarded
286 instead of assigned to a variable
; a XPG3 position specifier
; a number
287 indicating a maximum field width
; and a conversion character
.
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
.
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
.
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
.
308 The following conversion characters are supported
:
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.
315 The input field must be an octal integer
. It is read
in and the
316 value is stored
in the variable
as a
decimal string.
318 If the value exceeds
MAX_INT (017777777777 on platforms
using 32-bit
319 integers
), it will be truncated to a signed integer
. Hence
, 037777777777
320 will appear
as -1 on a
32-bit machine
.
324 The input field must be a hexadecimal integer
. It is read
in
325 and the value is stored
in the variable
as a
decimal string.
327 If the value exceeds
MAX_INT (0x7FFFFFFF on platforms
using 32-bit
328 integers
), it will be truncated to a signed integer
. Hence
, 0xFFFFFFFF
329 will appear
as -1 on a
32-bit machine
.
333 The input field must be a
decimal integer
. The value is stored
in the
334 variable
as an unsigned
decimal integer
string.
337 The input field must be an integer
. The
base (i
.e
. decimal, octal
, or
338 hexadecimal
) is determined
in the same fashion
as described
in
339 \fBexpr
\fR
. The value is stored
in the variable
as a
decimal string.
342 A single character is read
in and its binary value is stored
in
343 the variable
as a
decimal string.
344 Initial white space is not skipped
in this case
, so the input
345 field may be a white
-space character
.
346 This conversion is different from the ANSI standard
in that the
347 input field always consists of a single character
and no field
348 width may be specified
.
351 The input field consists of all the characters up to the next
352 white
-space character
; the characters are copied to the variable
.
354 \fBe
\fR or
\fBf
\fR or
\fBg
\fR
355 The input field must be a floating
-point number consisting
356 of an optional sign
, a
string of
decimal digits possibly
357 containing a
decimal point
, and an optional exponent consisting
358 of an
\fBe
\fR or
\fBE
\fR followed by an optional sign
and a
string of
360 It is read
in and stored
in the variable
as a floating
-point
string.
363 The input field consists of any number of characters
in
365 The matching
string is stored
in the variable
.
366 If the first character between the brackets is a
\fB
]\fR then
367 it is treated
as part of
\fIchars
\fR rather than the closing
370 contains a sequence of the form
\fIa
\fB\
-\fIb
\fR then any
371 character between
\fIa
\fR
and \fIb
\fR
(inclusive
) will
match.
372 If the first or last character between the brackets is a
\fB\
-\fR
, then
373 it is treated
as part of
\fIchars
\fR rather than indicating a range
.
376 The input field consists of any number of characters not
in
378 The matching
string is stored
in the variable
.
379 If the character immediately following the
\fB^
\fR is a
\fB
]\fR then it is
380 treated
as part of the set rather than the closing bracket
for
383 contains a sequence of the form
\fIa
\fB\
-\fIb
\fR then any
384 character between
\fIa
\fR
and \fIb
\fR
(inclusive
) will be excluded
386 If the first or last character between the brackets is a
\fB\
-\fR
, then
387 it is treated
as part of
\fIchars
\fR rather than indicating a range
.
390 No input is consumed from the input
string. Instead
, the total number
391 of chacters scanned from the input
string so far is stored
in the variable
.
393 The number of characters read from the input
for a conversion is the
394 largest number that makes sense
for that particular
conversion (e
.g
.
395 as many
decimal digits
as possible
for \fB%d
\fR
, as
396 many octal digits
as possible
for \fB%o
\fR
, and so on
).
397 The input field
for a given conversion terminates either
when a
398 white
-space character is encountered or
when the maximum field
399 width has been reached
, whichever comes first
.
400 If a
\fB
*\fR is present
in the conversion specifier
401 then no variable is assigned
and the next scan argument is not consumed
.
403 .SH
"DIFFERENCES FROM ANSI SSCANF"
405 The behavior of the
\fBscan
\fR command is the same
as the behavior of
406 the ANSI C
\fBsscanf
\fR procedure except
for the following differences
:
408 \fB%p
\fR conversion specifier is not currently supported
.
410 For
\fB%c
\fR conversions a single character value is
411 converted to a
decimal string, which is then assigned to the
412 corresponding
\fIvarName
\fR
;
413 no field width may be specified
for this conversion
.
415 The
\fBl
\fR
, \fBh
\fR
, and \fBL
\fR modifiers are ignored
; integer
416 values are always converted
as if there were no modifier present
417 and real values are always converted
as if the
\fBl
\fR modifier
418 were
present (i
.e
. type \fBdouble
\fR is used
for the
internal
422 If the end of the input
string is reached before any conversions have been
423 performed
and no variables are given
, and empty
string is returned
.
430 conversion specifier
, parse
, scan