1io(3) Erlang Module Definition io(3)
2
6 io - Standard I/O server interface functions.
7
9 This module provides an interface to standard Erlang I/O servers. The
10 output functions all return ok if they are successful, or exit if they
11 are not.
12 All functions in this module have an optional parameter IoDevice. If
14 included, it must be the pid of a process that handles the I/O proto‐
15 cols. Normally, it is the IoDevice returned by file:open/2.
16 For a description of the I/O protocols, see section The Erlang I/O Pro‐
18 tocol in the User's Guide.
19 Warning:
21 As from Erlang/OTP R13A, data supplied to function put_chars/2 is to be
22 in the unicode:chardata() format. This means that programs supplying
23 binaries to this function must convert them to UTF-8 before trying to
24 output the data on an I/O device.
25 If an I/O device is set in binary mode, functions get_chars/2,3 and
27 get_line/1,2 can return binaries instead of lists. The binaries are, as
28 from Erlang/OTP R13A, encoded in UTF-8.
29 To work with binaries in ISO Latin-1 encoding, use the file module in‐
31 stead.
32 For conversion functions between character encodings, see the unicode
34 module.
35
38 device() = atom() | pid()
39 An I/O device, either standard_io, standard_error, a registered
41 name, or a pid handling I/O protocols (returned from
42 file:open/2).
43 opt_pair() =
45 {binary, boolean()} |
46 {echo, boolean()} |
47 {expand_fun, expand_fun()} |
48 {encoding, encoding()}
49 expand_fun() =
51 fun((term()) -> {yes | no, string(), [string(), ...]})
52 encoding() =
54 latin1 | unicode | utf8 | utf16 | utf32 |
55 {utf16, big | little} |
56 {utf32, big | little}
57 setopt() = binary | list | opt_pair()
59 format() = atom() | string() | binary()
61 location() = erl_anno:location()
63 prompt() = atom() | unicode:chardata()
65 server_no_data() = {error, ErrorDescription :: term()} | eof
67 What the I/O server sends when there is no data.
69
71 columns() -> {ok, integer() >= 1} | {error, enotsup}
72 columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
74 Types:
76 IoDevice = device()
78 Retrieves the number of columns of the IoDevice (that is, the
80 width of a terminal). The function succeeds for terminal devices
81 and returns {error, enotsup} for all other I/O devices.
82 format(Format) -> ok
84 format(Format, Data) -> ok
86 format(IoDevice, Format, Data) -> ok
88 fwrite(Format) -> ok
90 fwrite(Format, Data) -> ok
92 fwrite(IoDevice, Format, Data) -> ok
94 Types:
96 IoDevice = device()
98 Format = format()
99 Data = [term()]
100 Writes the items in Data ([]) on the standard output (IoDevice)
102 in accordance with Format. Format contains plain characters that
103 are copied to the output device, and control sequences for for‐
104 matting, see below. If Format is an atom or a binary, it is
105 first converted to a list with the aid of atom_to_list/1 or bi‐
106 nary_to_list/1. Example:
107 1> io:fwrite("Hello world!~n", []).
109 Hello world!
110 ok
111 The general format of a control sequence is ~F.P.PadModC.
113 The character C determines the type of control sequence to be
115 used. It is the only required field. All of F, P, Pad, and Mod
116 are optional. For example, to use a # for Pad but use the de‐
117 fault values for F and P, you can write ~..#C.
118 * F is the field width of the printed argument. A negative
120 value means that the argument is left-justified within the
121 field, otherwise right-justified. If no field width is spec‐
122 ified, the required print width is used. If the field width
123 specified is too small, the whole field is filled with *
124 characters.
125 * P is the precision of the printed argument. A default value
127 is used if no precision is specified. The interpretation of
128 precision depends on the control sequences. Unless otherwise
129 specified, argument within is used to determine print width.
130 * Pad is the padding character. This is the character used to
132 pad the printed representation of the argument so that it
133 conforms to the specified field width and precision. Only
134 one padding character can be specified and, whenever appli‐
135 cable, it is used for both the field width and precision.
136 The default padding character is ' ' (space).
137 * Mod is the control sequence modifier. This is one or more
139 characters that change the interpretation of Data. The cur‐
140 rent modifiers are t, for Unicode translation, and l, for
141 stopping p and P from detecting printable characters.
142 If F, P, or Pad is a * character, the next argument in Data is
144 used as the value. For example:
145 1> io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).
147 003.14159
148 ok
149 To use a literal * character as Pad, it must be passed as an ar‐
151 gument:
152 2> io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).
154 **3.14159
155 ok
156 Available control sequences:
158 ~:
160 Character ~ is written.
161 c:
163 The argument is a number that is interpreted as an ASCII
164 code. The precision is the number of times the character is
165 printed and defaults to the field width, which in turn de‐
166 faults to 1. Example:
167 1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
169 | aaaaa|bbbbb |ccccc|
170 ok
171 If the Unicode translation modifier (t) is in effect, the
173 integer argument can be any number representing a valid Uni‐
174 code codepoint, otherwise it is to be an integer less than
175 or equal to 255, otherwise it is masked with 16#FF:
176 2> io:fwrite("~tc~n",[1024]).
178 \x{400}
179 ok
180 3> io:fwrite("~c~n",[1024]).
181 ^@
182 ok
183 f:
185 The argument is a float that is written as [-]ddd.ddd, where
186 the precision is the number of digits after the decimal
187 point. The default precision is 6 and it cannot be < 1.
188 e:
190 The argument is a float that is written as [-]d.ddde+-ddd,
191 where the precision is the number of digits written. The de‐
192 fault precision is 6 and it cannot be < 2.
193 g:
195 The argument is a float that is written as f, if it is >=
196 0.1 and < 10000.0. Otherwise, it is written in the e format.
197 The precision is the number of significant digits. It de‐
198 faults to 6 and is not to be < 2. If the absolute value of
199 the float does not allow it to be written in the f format
200 with the desired number of significant digits, it is also
201 written in the e format.
202 s:
204 Prints the argument with the string syntax. The argument is,
205 if no Unicode translation modifier is present, an iolist(),
206 a binary(), or an atom(). If the Unicode translation modi‐
207 fier (t) is in effect, the argument is unicode:chardata(),
208 meaning that binaries are in UTF-8. The characters are
209 printed without quotes. The string is first truncated by the
210 specified precision and then padded and justified to the
211 specified field width. The default precision is the field
212 width.
213 This format can be used for printing any object and truncat‐
215 ing the output so it fits a specified field:
216 1> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
218 |**********|
219 ok
220 2> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
221 |{hey,hey,h|
222 3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).
223 |{hey,hey |
224 ok
225 A list with integers > 255 is considered an error if the
227 Unicode translation modifier is not specified:
228 4> io:fwrite("~ts~n",[[1024]]).
230 \x{400}
231 ok
232 5> io:fwrite("~s~n",[[1024]]).
233 ** exception error: bad argument
234 in function io:format/3
235 called as io:format(<0.53.0>,"~s~n",[[1024]])
236 w:
238 Writes data with the standard syntax. This is used to output
239 Erlang terms. Atoms are printed within quotes if they con‐
240 tain embedded non-printable characters. Atom characters >
241 255 are escaped unless the Unicode translation modifier (t)
242 is used. Floats are printed accurately as the shortest, cor‐
243 rectly rounded string.
244 p:
246 Writes the data with standard syntax in the same way as ~w,
247 but breaks terms whose printed representation is longer than
248 one line into many lines and indents each line sensibly.
249 Left-justification is not supported. It also tries to detect
250 flat lists of printable characters and output these as
251 strings. For example:
252 1> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
254 {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
255 {typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
256 2> io:fwrite("~w~n", [T]).
257 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,
258 [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
259 me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
260 ,implicit}]
261 ok
262 3> io:fwrite("~62p~n", [T]).
263 [{attributes,[[{id,age,1.5},
264 {mode,explicit},
265 {typename,"INTEGER"}],
266 [{id,cho},{mode,explicit},{typename,'Cho'}]]},
267 {typename,'Person'},
268 {tag,{'PRIVATE',3}},
269 {mode,implicit}]
270 ok
271 The field width specifies the maximum line length. It de‐
273 faults to 80. The precision specifies the initial indenta‐
274 tion of the term. It defaults to the number of characters
275 printed on this line in the same call to write/1 or for‐
276 mat/1,2,3. For example, using T above:
277 4> io:fwrite("Here T = ~62p~n", [T]).
279 Here T = [{attributes,[[{id,age,1.5},
280 {mode,explicit},
281 {typename,"INTEGER"}],
282 [{id,cho},
283 {mode,explicit},
284 {typename,'Cho'}]]},
285 {typename,'Person'},
286 {tag,{'PRIVATE',3}},
287 {mode,implicit}]
288 ok
289 As from Erlang/OTP 21.0, a field width of value 0 can be
291 used for specifying that a line is infinitely long, which
292 means that no line breaks are inserted. For example:
293 5> io:fwrite("~0p~n", [lists:seq(1, 30)]).
295 [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
296 ok
297 When the modifier l is specified, no detection of printable
299 character lists takes place, for example:
300 6> S = [{a,"a"}, {b, "b"}], io:fwrite("~15p~n", [S]).
302 [{a,"a"},
303 {b,"b"}]
304 ok
305 7> io:fwrite("~15lp~n", [S]).
306 [{a,[97]},
307 {b,[98]}]
308 ok
309 The Unicode translation modifier t specifies how to treat
311 characters outside the Latin-1 range of codepoints, in
312 atoms, strings, and binaries. For example, printing an atom
313 containing a character > 255:
314 8> io:fwrite("~p~n",[list_to_atom([1024])]).
316 ok
317 9> io:fwrite("~tp~n",[list_to_atom([1024])]).
318 ok
319 By default, Erlang only detects lists of characters in the
321 Latin-1 range as strings, but the +pc unicode flag can be
322 used to change this (see printable_range/0 for details). For
323 example:
324 10> io:fwrite("~p~n",[[214]]).
326 "Ö"
327 ok
328 11> io:fwrite("~p~n",[[1024]]).
329 [1024]
330 ok
331 12> io:fwrite("~tp~n",[[1024]]).
332 [1024]
333 ok
334 but if Erlang was started with +pc unicode:
337 13> io:fwrite("~p~n",[[1024]]).
339 [1024]
340 ok
341 14> io:fwrite("~tp~n",[[1024]]).
342 "Ѐ"
343 ok
344 Similarly, binaries that look like UTF-8 encoded strings are
346 output with the binary string syntax if the t modifier is
347 specified:
348 15> io:fwrite("~p~n", [<<208,128>>]).
350 <<208,128>>
351 ok
352 16> io:fwrite("~tp~n", [<<208,128>>]).
353 <<"Ѐ"/utf8>>
354 ok
355 17> io:fwrite("~tp~n", [<<128,128>>]).
356 <<128,128>>
357 ok
358 W:
360 Writes data in the same way as ~w, but takes an extra argu‐
361 ment that is the maximum depth to which terms are printed.
362 Anything below this depth is replaced with .... For example,
363 using T above:
364 8> io:fwrite("~W~n", [T,9]).
366 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
367 [{id,cho},{mode,...},{...}]]},{typename,'Person'},
368 {tag,{'PRIVATE',3}},{mode,implicit}]
369 ok
370 If the maximum depth is reached, it cannot be read in the
372 resultant output. Also, the ,... form in a tuple denotes
373 that there are more elements in the tuple but these are be‐
374 low the print depth.
375 P:
377 Writes data in the same way as ~p, but takes an extra argu‐
378 ment that is the maximum depth to which terms are printed.
379 Anything below this depth is replaced with ..., for example:
380 9> io:fwrite("~62P~n", [T,9]).
382 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
383 [{id,cho},{mode,...},{...}]]},
384 {typename,'Person'},
385 {tag,{'PRIVATE',3}},
386 {mode,implicit}]
387 ok
388 B:
390 Writes an integer in base 2-36, the default base is 10. A
391 leading dash is printed for negative integers.
392 The precision field selects base, for example:
394 1> io:fwrite("~.16B~n", [31]).
396 1F
397 ok
398 2> io:fwrite("~.2B~n", [-19]).
399 -10011
400 ok
401 3> io:fwrite("~.36B~n", [5*36+35]).
402 5Z
403 ok
404 X:
406 Like B, but takes an extra argument that is a prefix to in‐
407 sert before the number, but after the leading dash, if any.
408 The prefix can be a possibly deep list of characters or an
410 atom. Example:
411 1> io:fwrite("~X~n", [31,"10#"]).
413 10#31
414 ok
415 2> io:fwrite("~.16X~n", [-31,"0x"]).
416 -0x1F
417 ok
418 #:
420 Like B, but prints the number with an Erlang style #-sepa‐
421 rated base prefix. Example:
422 1> io:fwrite("~.10#~n", [31]).
424 10#31
425 ok
426 2> io:fwrite("~.16#~n", [-31]).
427 -16#1F
428 ok
429 b:
431 Like B, but prints lowercase letters.
432 x:
434 Like X, but prints lowercase letters.
435 +:
437 Like #, but prints lowercase letters.
438 n:
440 Writes a new line.
441 i:
443 Ignores the next term.
444 The function returns:
446 ok:
448 The formatting succeeded.
449 If an error occurs, there is no output. Example:
451 1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
453 abc def 'abc def' {foo,1} A
454 ok
455 2> io:fwrite("~s", [65]).
456 ** exception error: bad argument
457 in function io:format/3
458 called as io:format(<0.53.0>,"~s","A")
459 In this example, an attempt was made to output the single char‐
461 acter 65 with the aid of the string formatting directive "~s".
462 fread(Prompt, Format) -> Result
464 fread(IoDevice, Prompt, Format) -> Result
466 Types:
468 IoDevice = device()
470 Prompt = prompt()
471 Format = format()
472 Result =
473 {ok, Terms :: [term()]} |
474 {error, {fread, FreadError :: io_lib:fread_error()}} |
475 server_no_data()
476 server_no_data() = {error, ErrorDescription :: term()} | eof
477 Reads characters from the standard input (IoDevice), prompting
479 it with Prompt. Interprets the characters in accordance with
480 Format. Format contains control sequences that directs the in‐
481 terpretation of the input.
482 Format can contain the following:
484 * Whitespace characters (Space, Tab, and Newline) that cause
486 input to be read to the next non-whitespace character.
487 * Ordinary characters that must match the next input charac‐
489 ter.
490 * Control sequences, which have the general format ~*FMC,
492 where:
493 * Character * is an optional return suppression character.
495 It provides a method to specify a field that is to be
496 omitted.
497 * F is the field width of the input field.
499 * M is an optional translation modifier (of which t is the
501 only supported, meaning Unicode translation).
502 * C determines the type of control sequence.
504 Unless otherwise specified, leading whitespace is ignored
506 for all control sequences. An input field cannot be more
507 than one line wide.
508 Available control sequences:
510 ~:
512 A single ~ is expected in the input.
513 d:
515 A decimal integer is expected.
516 u:
518 An unsigned integer in base 2-36 is expected. The field
519 width parameter is used to specify base. Leading white‐
520 space characters are not skipped.
521 -:
523 An optional sign character is expected. A sign character -
524 gives return value -1. Sign character + or none gives 1.
525 The field width parameter is ignored. Leading whitespace
526 characters are not skipped.
527 #:
529 An integer in base 2-36 with Erlang-style base prefix (for
530 example, "16#ffff") is expected.
531 f:
533 A floating point number is expected. It must follow the
534 Erlang floating point number syntax.
535 s:
537 A string of non-whitespace characters is read. If a field
538 width has been specified, this number of characters are
539 read and all trailing whitespace characters are stripped.
540 An Erlang string (list of characters) is returned.
541 If Unicode translation is in effect (~ts), characters >
543 255 are accepted, otherwise not. With the translation mod‐
544 ifier, the returned list can as a consequence also contain
545 integers > 255:
546 1> io:fread("Prompt> ","~s").
548 Prompt> <Characters beyond latin1 range not printable in this medium>
549 {error,{fread,string}}
550 2> io:fread("Prompt> ","~ts").
551 Prompt> <Characters beyond latin1 range not printable in this medium>
552 {ok,[[1091,1085,1080,1094,1086,1076,1077]]}
553 a:
555 Similar to s, but the resulting string is converted into
556 an atom.
557 c:
559 The number of characters equal to the field width are read
560 (default is 1) and returned as an Erlang string. However,
561 leading and trailing whitespace characters are not omitted
562 as they are with s. All characters are returned.
563 The Unicode translation modifier works as with s:
565 1> io:fread("Prompt> ","~c").
567 Prompt> <Character beyond latin1 range not printable in this medium>
568 {error,{fread,string}}
569 2> io:fread("Prompt> ","~tc").
570 Prompt> <Character beyond latin1 range not printable in this medium>
571 {ok,[[1091]]}
572 l:
574 Returns the number of characters that have been scanned up
575 to that point, including whitespace characters.
576 The function returns:
578 {ok, Terms}:
580 The read was successful and Terms is the list of success‐
581 fully matched and read items.
582 eof:
584 End of file was encountered.
585 {error, FreadError}:
587 The reading failed and FreadError gives a hint about the
588 error.
589 {error, ErrorDescription}:
591 The read operation failed and parameter ErrorDescription
592 gives a hint about the error.
593 Examples:
595 20> io:fread('enter>', "~f~f~f").
597 enter>1.9 35.5e3 15.0
598 {ok,[1.9,3.55e4,15.0]}
599 21> io:fread('enter>', "~10f~d").
600 enter> 5.67899
601 {ok,[5.678,99]}
602 22> io:fread('enter>', ":~10s:~10c:").
603 enter>: alan : joe :
604 {ok, ["alan", " joe "]}
605 get_chars(Prompt, Count) -> Data | server_no_data()
607 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
609 Types:
611 IoDevice = device()
613 Prompt = prompt()
614 Count = integer() >= 0
615 Data = string() | unicode:unicode_binary()
616 server_no_data() = {error, ErrorDescription :: term()} | eof
617 Reads Count characters from standard input (IoDevice), prompting
619 it with Prompt.
620 The function returns:
622 Data:
624 The input characters. If the I/O device supports Unicode,
625 the data can represent codepoints > 255 (the latin1 range).
626 If the I/O server is set to deliver binaries, they are en‐
627 coded in UTF-8 (regardless of whether the I/O device sup‐
628 ports Unicode).
629 eof:
631 End of file was encountered.
632 {error, ErrorDescription}:
634 Other (rare) error condition, such as {error, estale} if
635 reading from an NFS file system.
636 get_line(Prompt) -> Data | server_no_data()
638 get_line(IoDevice, Prompt) -> Data | server_no_data()
640 Types:
642 IoDevice = device()
644 Prompt = prompt()
645 Data = string() | unicode:unicode_binary()
646 server_no_data() = {error, ErrorDescription :: term()} | eof
647 Reads a line from the standard input (IoDevice), prompting it
649 with Prompt.
650 The function returns:
652 Data:
654 The characters in the line terminated by a line feed (or end
655 of file). If the I/O device supports Unicode, the data can
656 represent codepoints > 255 (the latin1 range). If the I/O
657 server is set to deliver binaries, they are encoded in UTF-8
658 (regardless of if the I/O device supports Unicode).
659 eof:
661 End of file was encountered.
662 {error, ErrorDescription}:
664 Other (rare) error condition, such as {error, estale} if
665 reading from an NFS file system.
666 getopts() -> [opt_pair()] | {error, Reason}
668 getopts(IoDevice) -> [opt_pair()] | {error, Reason}
670 Types:
672 IoDevice = device()
674 Reason = term()
675 Requests all available options and their current values for a
677 specific I/O device, for example:
678 1> {ok,F} = file:open("/dev/null",[read]).
680 {ok,<0.42.0>}
681 2> io:getopts(F).
682 [{binary,false},{encoding,latin1}]
683 Here the file I/O server returns all available options for a
685 file, which are the expected ones, encoding and binary. However,
686 the standard shell has some more options:
687 3> io:getopts().
689 [{expand_fun,#Fun<group.0.120017273>},
690 {echo,true},
691 {binary,false},
692 {encoding,unicode}]
693 This example is, as can be seen, run in an environment where the
695 terminal supports Unicode input and output.
696 nl() -> ok
698 nl(IoDevice) -> ok
700 Types:
702 IoDevice = device()
704 Writes new line to the standard output (IoDevice).
706 parse_erl_exprs(Prompt) -> Result
708 parse_erl_exprs(IoDevice, Prompt) -> Result
710 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
712 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
714 Result
715 Types:
717 IoDevice = device()
719 Prompt = prompt()
720 StartLocation = location()
721 Options = erl_scan:options()
722 Result = parse_ret()
723 parse_ret() =
724 {ok,
725 ExprList :: [erl_parse:abstract_expr()],
726 EndLocation :: location()} |
727 {eof, EndLocation :: location()} |
728 {error,
729 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
730 ErrorLocation :: location()} |
731 server_no_data()
732 server_no_data() = {error, ErrorDescription :: term()} | eof
733 Reads data from the standard input (IoDevice), prompting it with
735 Prompt. Starts reading at location StartLocation (1). Argument
736 Options is passed on as argument Options of function
737 erl_scan:tokens/4. The data is tokenized and parsed as if it was
738 a sequence of Erlang expressions until a final dot (.) is
739 reached.
740 The function returns:
742 {ok, ExprList, EndLocation}:
744 The parsing was successful.
745 {eof, EndLocation}:
747 End of file was encountered by the tokenizer.
748 eof:
750 End of file was encountered by the I/O server.
751 {error, ErrorInfo, ErrorLocation}:
753 An error occurred while tokenizing or parsing.
754 {error, ErrorDescription}:
756 Other (rare) error condition, such as {error, estale} if
757 reading from an NFS file system.
758 Example:
760 25> io:parse_erl_exprs('enter>').
762 enter>abc(), "hey".
763 {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
764 26> io:parse_erl_exprs ('enter>').
765 enter>abc("hey".
766 {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
767 parse_erl_form(Prompt) -> Result
769 parse_erl_form(IoDevice, Prompt) -> Result
771 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
773 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
775 Types:
777 IoDevice = device()
779 Prompt = prompt()
780 StartLocation = location()
781 Options = erl_scan:options()
782 Result = parse_form_ret()
783 parse_form_ret() =
784 {ok,
785 AbsForm :: erl_parse:abstract_form(),
786 EndLocation :: location()} |
787 {eof, EndLocation :: location()} |
788 {error,
789 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
790 ErrorLocation :: location()} |
791 server_no_data()
792 server_no_data() = {error, ErrorDescription :: term()} | eof
793 Reads data from the standard input (IoDevice), prompting it with
795 Prompt. Starts reading at location StartLocation (1). Argument
796 Options is passed on as argument Options of function
797 erl_scan:tokens/4. The data is tokenized and parsed as if it was
798 an Erlang form (one of the valid Erlang expressions in an Erlang
799 source file) until a final dot (.) is reached.
800 The function returns:
802 {ok, AbsForm, EndLocation}:
804 The parsing was successful.
805 {eof, EndLocation}:
807 End of file was encountered by the tokenizer.
808 eof:
810 End of file was encountered by the I/O server.
811 {error, ErrorInfo, ErrorLocation}:
813 An error occurred while tokenizing or parsing.
814 {error, ErrorDescription}:
816 Other (rare) error condition, such as {error, estale} if
817 reading from an NFS file system.
818 printable_range() -> unicode | latin1
820 Returns the user-requested range of printable Unicode charac‐
822 ters.
823 The user can request a range of characters that are to be con‐
825 sidered printable in heuristic detection of strings by the shell
826 and by the formatting functions. This is done by supplying +pc
827 <range> when starting Erlang.
828 The only valid values for <range> are latin1 and unicode. latin1
830 means that only code points < 256 (except control characters,
831 and so on) are considered printable. unicode means that all
832 printable characters in all Unicode character ranges are consid‐
833 ered printable by the I/O functions.
834 By default, Erlang is started so that only the latin1 range of
836 characters indicate that a list of integers is a string.
837 The simplest way to use the setting is to call io_lib:print‐
839 able_list/1, which uses the return value of this function to de‐
840 cide if a list is a string of printable characters.
841 Note:
843 In a future release, this function may return more values and
844 ranges. To avoid compatibility problems, it is recommended to
845 use function io_lib:printable_list/1.
846 put_chars(CharData) -> ok
849 put_chars(IoDevice, CharData) -> ok
851 Types:
853 IoDevice = device()
855 CharData = unicode:chardata()
856 Writes the characters of CharData to the I/O server (IoDevice).
858 read(Prompt) -> Result
860 read(IoDevice, Prompt) -> Result
862 Types:
864 IoDevice = device()
866 Prompt = prompt()
867 Result =
868 {ok, Term :: term()} | server_no_data() | {error, Error‐
869 Info}
870 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
871 server_no_data() = {error, ErrorDescription :: term()} | eof
872 Reads a term Term from the standard input (IoDevice), prompting
874 it with Prompt.
875 The function returns:
877 {ok, Term}:
879 The parsing was successful.
880 eof:
882 End of file was encountered.
883 {error, ErrorInfo}:
885 The parsing failed.
886 {error, ErrorDescription}:
888 Other (rare) error condition, such as {error, estale} if
889 reading from an NFS file system.
890 read(IoDevice, Prompt, StartLocation) -> Result
892 read(IoDevice, Prompt, StartLocation, Options) -> Result
894 Types:
896 IoDevice = device()
898 Prompt = prompt()
899 StartLocation = location()
900 Options = erl_scan:options()
901 Result =
902 {ok, Term :: term(), EndLocation :: location()} |
903 {eof, EndLocation :: location()} |
904 server_no_data() |
905 {error, ErrorInfo, ErrorLocation :: location()}
906 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
907 server_no_data() = {error, ErrorDescription :: term()} | eof
908 Reads a term Term from IoDevice, prompting it with Prompt. Read‐
910 ing starts at location StartLocation. Argument Options is passed
911 on as argument Options of function erl_scan:tokens/4.
912 The function returns:
914 {ok, Term, EndLocation}:
916 The parsing was successful.
917 {eof, EndLocation}:
919 End of file was encountered.
920 {error, ErrorInfo, ErrorLocation}:
922 The parsing failed.
923 {error, ErrorDescription}:
925 Other (rare) error condition, such as {error, estale} if
926 reading from an NFS file system.
927 rows() -> {ok, integer() >= 1} | {error, enotsup}
929 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
931 Types:
933 IoDevice = device()
935 Retrieves the number of rows of IoDevice (that is, the height of
937 a terminal). The function only succeeds for terminal devices,
938 for all other I/O devices the function returns {error, enotsup}.
939 scan_erl_exprs(Prompt) -> Result
941 scan_erl_exprs(Device, Prompt) -> Result
943 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
945 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
947 Types:
949 Device = device()
951 Prompt = prompt()
952 StartLocation = location()
953 Options = erl_scan:options()
954 Result = erl_scan:tokens_result() | server_no_data()
955 server_no_data() = {error, ErrorDescription :: term()} | eof
956 Reads data from the standard input (IoDevice), prompting it with
958 Prompt. Reading starts at location StartLocation (1). Argument
959 Options is passed on as argument Options of function
960 erl_scan:tokens/4. The data is tokenized as if it were a se‐
961 quence of Erlang expressions until a final dot (.) is reached.
962 This token is also returned.
963 The function returns:
965 {ok, Tokens, EndLocation}:
967 The tokenization succeeded.
968 {eof, EndLocation}:
970 End of file was encountered by the tokenizer.
971 eof:
973 End of file was encountered by the I/O server.
974 {error, ErrorInfo, ErrorLocation}:
976 An error occurred while tokenizing.
977 {error, ErrorDescription}:
979 Other (rare) error condition, such as {error, estale} if
980 reading from an NFS file system.
981 Example:
983 23> io:scan_erl_exprs('enter>').
985 enter>abc(), "hey".
986 {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
987 24> io:scan_erl_exprs('enter>').
988 enter>1.0er.
989 {error,{1,erl_scan,{illegal,float}},2}
990 scan_erl_form(Prompt) -> Result
992 scan_erl_form(IoDevice, Prompt) -> Result
994 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
996 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
998 Types:
1000 IoDevice = device()
1002 Prompt = prompt()
1003 StartLocation = location()
1004 Options = erl_scan:options()
1005 Result = erl_scan:tokens_result() | server_no_data()
1006 server_no_data() = {error, ErrorDescription :: term()} | eof
1007 Reads data from the standard input (IoDevice), prompting it with
1009 Prompt. Starts reading at location StartLocation (1). Argument
1010 Options is passed on as argument Options of function
1011 erl_scan:tokens/4. The data is tokenized as if it was an Erlang
1012 form (one of the valid Erlang expressions in an Erlang source
1013 file) until a final dot (.) is reached. This last token is also
1014 returned.
1015 The return values are the same as for scan_erl_exprs/1,2,3,4.
1017 setopts(Opts) -> ok | {error, Reason}
1019 setopts(IoDevice, Opts) -> ok | {error, Reason}
1021 Types:
1023 IoDevice = device()
1025 Opts = [setopt()]
1026 Reason = term()
1027 Set options for the standard I/O device (IoDevice).
1029 Possible options and values vary depending on the I/O device.
1031 For a list of supported options and their current values on a
1032 specific I/O device, use function getopts/1.
1033 The options and values supported by the OTP I/O devices are as
1035 follows:
1036 binary, list, or {binary, boolean()}:
1038 If set in binary mode (binary or {binary, true}), the I/O
1039 server sends binary data (encoded in UTF-8) as answers to
1040 the get_line, get_chars, and, if possible, get_until re‐
1041 quests (for details, see section The Erlang I/O Protocol) in
1042 the User's Guide). The immediate effect is that
1043 get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead
1044 of lists of characters for the affected I/O device.
1045 By default, all I/O devices in OTP are set in list mode.
1047 However, the I/O functions can handle any of these modes and
1048 so should other, user-written, modules behaving as clients
1049 to I/O servers.
1050 This option is supported by the standard shell (group.erl),
1052 the 'oldshell' (user.erl), and the file I/O servers.
1053 {echo, boolean()}:
1055 Denotes if the terminal is to echo input. Only supported for
1056 the standard shell I/O server (group.erl)
1057 {expand_fun, expand_fun()}:
1059 Provides a function for tab-completion (expansion) like the
1060 Erlang shell. This function is called when the user presses
1061 the Tab key. The expansion is active when calling line-read‐
1062 ing functions, such as get_line/1,2.
1063 The function is called with the current line, up to the cur‐
1065 sor, as a reversed string. It is to return a three-tuple:
1066 {yes|no, string(), [string(), ...]}. The first element gives
1067 a beep if no, otherwise the expansion is silent; the second
1068 is a string that will be entered at the cursor position; the
1069 third is a list of possible expansions. If this list is not
1070 empty, it is printed and the current input line is written
1071 once again.
1072 Trivial example (beep on anything except empty line, which
1074 is expanded to "quit"):
1075 fun("") -> {yes, "quit", []};
1077 (_) -> {no, "", ["quit"]} end
1078 This option is only supported by the standard shell
1080 (group.erl).
1081 {encoding, latin1 | unicode}:
1083 Specifies how characters are input or output from or to the
1084 I/O device, implying that, for example, a terminal is set to
1085 handle Unicode input and output or a file is set to handle
1086 UTF-8 data encoding.
1087 The option does not affect how data is returned from the I/O
1089 functions or how it is sent in the I/O protocol, it only af‐
1090 fects how the I/O device is to handle Unicode characters to
1091 the "physical" device.
1092 The standard shell is set for unicode or latin1 encoding
1094 when the system is started. The encoding is set with the
1095 help of the LANG or LC_CTYPE environment variables on Unix-
1096 like system or by other means on other systems. So, the user
1097 can input Unicode characters and the I/O device is in {en‐
1098 coding, unicode} mode if the I/O device supports it. The
1099 mode can be changed, if the assumption of the runtime system
1100 is wrong, by setting this option.
1101 The I/O device used when Erlang is started with the "-old‐
1103 shell" or "-noshell" flags is by default set to latin1 en‐
1104 coding, meaning that any characters > codepoint 255 are es‐
1105 caped and that input is expected to be plain 8-bit ISO
1106 Latin-1. If the encoding is changed to Unicode, input and
1107 output from the standard file descriptors are in UTF-8 (re‐
1108 gardless of operating system).
1109 Files can also be set in {encoding, unicode}, meaning that
1111 data is written and read as UTF-8. More encodings are possi‐
1112 ble for files, see below.
1113 {encoding, unicode | latin1} is supported by both the stan‐
1115 dard shell (group.erl including werl on Windows), the 'old‐
1116 shell' (user.erl), and the file I/O servers.
1117 {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
1119 | {utf32,big} | {utf32,little}}:
1120 For disk files, the encoding can be set to various UTF vari‐
1121 ants. This has the effect that data is expected to be read
1122 as the specified encoding from the file, and the data is
1123 written in the specified encoding to the disk file.
1124 {encoding, utf8} has the same effect as {encoding, unicode}
1126 on files.
1127 The extended encodings are only supported on disk files
1129 (opened by function file:open/2).
1130 write(Term) -> ok
1132 write(IoDevice, Term) -> ok
1134 Types:
1136 IoDevice = device()
1138 Term = term()
1139 Writes term Term to the standard output (IoDevice).
1141
1143 All Erlang processes have a default standard I/O device. This device is
1144 used when no IoDevice argument is specified in the function calls in
1145 this module. However, it is sometimes desirable to use an explicit
1146 IoDevice argument that refers to the default I/O device. This is the
1147 case with functions that can access either a file or the default I/O
1148 device. The atom standard_io has this special meaning. The following
1149 example illustrates this:
1150 27> io:read('enter>').
1152 enter>foo.
1153 {ok,foo}
1154 28> io:read(standard_io, 'enter>').
1155 enter>bar.
1156 {ok,bar}
1157 There is always a process registered under the name of user. This can
1159 be used for sending output to the user.
1160
1162 In certain situations, especially when the standard output is redi‐
1163 rected, access to an I/O server specific for error messages can be con‐
1164 venient. The I/O device standard_error can be used to direct output to
1165 whatever the current operating system considers a suitable I/O device
1166 for error output. Example on a Unix-like operating system:
1167 $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1169 'init:stop().' > /dev/null
1170 Error: error 11
1171
1173 The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1174 ture that is returned from all I/O modules. It has the following for‐
1175 mat:
1176 {ErrorLocation, Module, ErrorDescriptor}
1178 A string that describes the error is obtained with the following call:
1180 Module:format_error(ErrorDescriptor)
1182Ericsson AB stdlib 3.14.2.1 io(3)