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 a IoDevice returned by file:open/2. If no IoDe‐
16 vice is given, standard_io is used.
17 For a description of the I/O protocols, see section The Erlang I/O Pro‐
19 tocol in the User's Guide.
20 Warning:
22 As from Erlang/OTP R13A, data supplied to function put_chars/2 is to be
23 in the unicode:chardata() format. This means that programs supplying
24 binaries to this function must convert them to UTF-8 before trying to
25 output the data on an I/O device.
26 If an I/O device is set in binary mode, functions get_chars/2,3 and
28 get_line/1,2 can return binaries instead of lists. The binaries are, as
29 from Erlang/OTP R13A, encoded in UTF-8.
30 To work with binaries in ISO Latin-1 encoding, use the file module in‐
32 stead.
33 For conversion functions between character encodings, see the unicode
35 module.
36
39 device() =
40 atom() | pid() | standard_io() | standard_error() | user()
41 An I/O device, either standard_io, standard_error, user, a reg‐
43 istered name, or a pid handling I/O protocols (returned from
44 file:open/2).
45 standard_io() = standard_io
47 All Erlang processes have a default standard I/O device. This
49 device is used when no IoDevice argument is specified in the
50 function calls in this module. However, it is sometimes desir‐
51 able to use an explicit IoDevice argument that refers to the de‐
52 fault I/O device. This is the case with functions that can ac‐
53 cess either a file or the default I/O device. The atom stan‐
54 dard_io has this special meaning. The following example illus‐
55 trates this:
56 27> io:read('enter>').
58 enter>foo.
59 {ok,foo}
60 28> io:read(standard_io, 'enter>').
61 enter>bar.
62 {ok,bar}
63 By default all I/O sent to standard_io will en up in the user
65 I/O device of the node that spawned the calling process.
66 standard_io is an alias for group_leader/0, so in order to
68 change where the default input/output requests are sent you can
69 change the group leader for the current process using
70 group_leader(NewGroupLeader, self()).
71 standard_error() = standard_error
73 The I/O device standard_error can be used to direct output to
75 whatever the current operating system considers a suitable I/O
76 device for error output. This can be useful when standard output
77 is redirected. Example on a Unix-like operating system:
78 $ erl -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
80 'init:stop().' > /dev/null
81 Error: error 11
82 user() = user
84 An I/O device that can be used to interact with the node local
86 stdout and stdin. This can be either a terminal, a pipe, a file,
87 or a combination. You can use getopts/0 to get more information
88 about the I/O device.
89 See The Interactive Shell and Escripts and non-interactive I/O
91 in the Using Unicode In Erlang User's Guide for details on how
92 Unicode is handled by user.
93 opt_pair() =
95 {binary, boolean()} |
96 {echo, boolean()} |
97 {expand_fun, expand_fun()} |
98 {encoding, encoding()} |
99 {atom(), term()}
100 get_opt_pair() = opt_pair() | {terminal, boolean()}
102 expand_fun() = fun((string()) -> {yes | no, string(), list()})
104 encoding() =
106 latin1 | unicode | utf8 | utf16 | utf32 |
107 {utf16, big | little} |
108 {utf32, big | little}
109 setopt() = binary | list | opt_pair()
111 format() = atom() | string() | binary()
113 location() = erl_anno:location()
115 prompt() = atom() | unicode:chardata()
117 server_no_data() = {error, ErrorDescription :: term()} | eof
119 What the I/O server sends when there is no data.
121
123 columns() -> {ok, integer() >= 1} | {error, enotsup}
124 columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
126 Types:
128 IoDevice = device()
130 Retrieves the number of columns of the IoDevice (that is, the
132 width of a terminal). The function succeeds for terminal devices
133 and returns {error, enotsup} for all other I/O devices.
134 format(Format) -> ok
136 format(Format, Data) -> ok
138 format(IoDevice, Format, Data) -> ok
140 fwrite(Format) -> ok
142 fwrite(Format, Data) -> ok
144 fwrite(IoDevice, Format, Data) -> ok
146 Types:
148 IoDevice = device()
150 Format = format()
151 Data = [term()]
152 Writes the items in Data ([]) on the standard output (IoDevice)
154 in accordance with Format. Format contains plain characters that
155 are copied to the output device, and control sequences for for‐
156 matting, see below. If Format is an atom or a binary, it is
157 first converted to a list with the aid of atom_to_list/1 or bi‐
158 nary_to_list/1. Example:
159 1> io:fwrite("Hello world!~n", []).
161 Hello world!
162 ok
163 The general format of a control sequence is ~F.P.PadModC.
165 The character C determines the type of control sequence to be
167 used. It is the only required field. All of F, P, Pad, and Mod
168 are optional. For example, to use a # for Pad but use the de‐
169 fault values for F and P, you can write ~..#C.
170 * F is the field width of the printed argument. A negative
172 value means that the argument is left-justified within the
173 field, otherwise right-justified. If no field width is spec‐
174 ified, the required print width is used. If the field width
175 specified is too small, the whole field is filled with *
176 characters.
177 * P is the precision of the printed argument. A default value
179 is used if no precision is specified. The interpretation of
180 precision depends on the control sequences. Unless otherwise
181 specified, argument within is used to determine print width.
182 * Pad is the padding character. This is the character used to
184 pad the printed representation of the argument so that it
185 conforms to the specified field width and precision. Only
186 one padding character can be specified and, whenever appli‐
187 cable, it is used for both the field width and precision.
188 The default padding character is ' ' (space).
189 * Mod is the control sequence modifier. This is one or more
191 characters that change the interpretation of Data.
192 The current modifiers are:
194 t:
196 For Unicode translation.
197 l:
199 For stopping p and P from detecting printable characters.
200 k:
202 For use with p, P, w, and W to format maps in map-key or‐
203 dered order (see maps:iterator_order()).
204 K:
206 Similar to k, for formatting maps in map-key order, but
207 takes an extra argument that specifies the maps:itera‐
208 tor_order().
209 For example:
211 > M = #{ a => 1, b => 2 }.
213 #{a => 1,b => 2}
214 > io:format("~Kp~n", [reversed, M]).
215 #{b => 2,a => 1}
216 ok
217 If F, P, or Pad is a * character, the next argument in Data is
219 used as the value. For example:
220 1> io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).
222 003.14159
223 ok
224 To use a literal * character as Pad, it must be passed as an ar‐
226 gument:
227 2> io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).
229 **3.14159
230 ok
231 Available control sequences:
233 ~:
235 Character ~ is written.
236 c:
238 The argument is a number that is interpreted as an ASCII
239 code. The precision is the number of times the character is
240 printed and defaults to the field width, which in turn de‐
241 faults to 1. Example:
242 1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
244 | aaaaa|bbbbb |ccccc|
245 ok
246 If the Unicode translation modifier (t) is in effect, the
248 integer argument can be any number representing a valid Uni‐
249 code codepoint, otherwise it is to be an integer less than
250 or equal to 255, otherwise it is masked with 16#FF:
251 2> io:fwrite("~tc~n",[1024]).
253 \x{400}
254 ok
255 3> io:fwrite("~c~n",[1024]).
256 ^@
257 ok
258 f:
260 The argument is a float that is written as [-]ddd.ddd, where
261 the precision is the number of digits after the decimal
262 point. The default precision is 6 and it cannot be < 1.
263 e:
265 The argument is a float that is written as [-]d.ddde+-ddd,
266 where the precision is the number of digits written. The de‐
267 fault precision is 6 and it cannot be < 2.
268 g:
270 The argument is a float that is written as f, if it is >=
271 0.1 and < 10000.0. Otherwise, it is written in the e format.
272 The precision is the number of significant digits. It de‐
273 faults to 6 and is not to be < 2. If the absolute value of
274 the float does not allow it to be written in the f format
275 with the desired number of significant digits, it is also
276 written in the e format.
277 s:
279 Prints the argument with the string syntax. The argument is,
280 if no Unicode translation modifier is present, an iolist(),
281 a binary(), or an atom(). If the Unicode translation modi‐
282 fier (t) is in effect, the argument is unicode:chardata(),
283 meaning that binaries are in UTF-8. The characters are
284 printed without quotes. The string is first truncated by the
285 specified precision and then padded and justified to the
286 specified field width. The default precision is the field
287 width.
288 This format can be used for printing any object and truncat‐
290 ing the output so it fits a specified field:
291 1> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
293 |**********|
294 ok
295 2> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
296 |{hey,hey,h|
297 3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).
298 |{hey,hey |
299 ok
300 A list with integers > 255 is considered an error if the
302 Unicode translation modifier is not specified:
303 4> io:fwrite("~ts~n",[[1024]]).
305 \x{400}
306 ok
307 5> io:fwrite("~s~n",[[1024]]).
308 ** exception error: bad argument
309 in function io:format/3
310 called as io:format(<0.53.0>,"~s~n",[[1024]])
311 w:
313 Writes data with the standard syntax. This is used to output
314 Erlang terms. Atoms are printed within quotes if they con‐
315 tain embedded non-printable characters. Atom characters >
316 255 are escaped unless the Unicode translation modifier (t)
317 is used. Floats are printed accurately as the shortest, cor‐
318 rectly rounded string.
319 p:
321 Writes the data with standard syntax in the same way as ~w,
322 but breaks terms whose printed representation is longer than
323 one line into many lines and indents each line sensibly.
324 Left-justification is not supported. It also tries to detect
325 flat lists of printable characters and output these as
326 strings. For example:
327 1> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
329 {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
330 {typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
331 2> io:fwrite("~w~n", [T]).
332 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,
333 [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
334 me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
335 ,implicit}]
336 ok
337 3> io:fwrite("~62p~n", [T]).
338 [{attributes,[[{id,age,1.5},
339 {mode,explicit},
340 {typename,"INTEGER"}],
341 [{id,cho},{mode,explicit},{typename,'Cho'}]]},
342 {typename,'Person'},
343 {tag,{'PRIVATE',3}},
344 {mode,implicit}]
345 ok
346 The field width specifies the maximum line length. It de‐
348 faults to 80. The precision specifies the initial indenta‐
349 tion of the term. It defaults to the number of characters
350 printed on this line in the same call to write/1 or for‐
351 mat/1,2,3. For example, using T above:
352 4> io:fwrite("Here T = ~62p~n", [T]).
354 Here T = [{attributes,[[{id,age,1.5},
355 {mode,explicit},
356 {typename,"INTEGER"}],
357 [{id,cho},
358 {mode,explicit},
359 {typename,'Cho'}]]},
360 {typename,'Person'},
361 {tag,{'PRIVATE',3}},
362 {mode,implicit}]
363 ok
364 As from Erlang/OTP 21.0, a field width of value 0 can be
366 used for specifying that a line is infinitely long, which
367 means that no line breaks are inserted. For example:
368 5> io:fwrite("~0p~n", [lists:seq(1, 30)]).
370 [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]
371 ok
372 When the modifier l is specified, no detection of printable
374 character lists takes place, for example:
375 6> S = [{a,"a"}, {b, "b"}], io:fwrite("~15p~n", [S]).
377 [{a,"a"},
378 {b,"b"}]
379 ok
380 7> io:fwrite("~15lp~n", [S]).
381 [{a,[97]},
382 {b,[98]}]
383 ok
384 The Unicode translation modifier t specifies how to treat
386 characters outside the Latin-1 range of codepoints, in
387 atoms, strings, and binaries. For example, printing an atom
388 containing a character > 255:
389 8> io:fwrite("~p~n",[list_to_atom([1024])]).
391 ok
392 9> io:fwrite("~tp~n",[list_to_atom([1024])]).
393 ok
394 By default, Erlang only detects lists of characters in the
396 Latin-1 range as strings, but the +pc unicode flag can be
397 used to change this (see printable_range/0 for details). For
398 example:
399 10> io:fwrite("~p~n",[[214]]).
401 "Ö"
402 ok
403 11> io:fwrite("~p~n",[[1024]]).
404 [1024]
405 ok
406 12> io:fwrite("~tp~n",[[1024]]).
407 [1024]
408 ok
409 but if Erlang was started with +pc unicode:
412 13> io:fwrite("~p~n",[[1024]]).
414 [1024]
415 ok
416 14> io:fwrite("~tp~n",[[1024]]).
417 "Ѐ"
418 ok
419 Similarly, binaries that look like UTF-8 encoded strings are
421 output with the binary string syntax if the t modifier is
422 specified:
423 15> io:fwrite("~p~n", [<<208,128>>]).
425 <<208,128>>
426 ok
427 16> io:fwrite("~tp~n", [<<208,128>>]).
428 <<"Ѐ"/utf8>>
429 ok
430 17> io:fwrite("~tp~n", [<<128,128>>]).
431 <<128,128>>
432 ok
433 W:
435 Writes data in the same way as ~w, but takes an extra argu‐
436 ment that is the maximum depth to which terms are printed.
437 Anything below this depth is replaced with .... For example,
438 using T above:
439 8> io:fwrite("~W~n", [T,9]).
441 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
442 [{id,cho},{mode,...},{...}]]},{typename,'Person'},
443 {tag,{'PRIVATE',3}},{mode,implicit}]
444 ok
445 If the maximum depth is reached, it cannot be read in the
447 resultant output. Also, the ,... form in a tuple denotes
448 that there are more elements in the tuple but these are be‐
449 low the print depth.
450 P:
452 Writes data in the same way as ~p, but takes an extra argu‐
453 ment that is the maximum depth to which terms are printed.
454 Anything below this depth is replaced with ..., for example:
455 9> io:fwrite("~62P~n", [T,9]).
457 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
458 [{id,cho},{mode,...},{...}]]},
459 {typename,'Person'},
460 {tag,{'PRIVATE',3}},
461 {mode,implicit}]
462 ok
463 B:
465 Writes an integer in base 2-36, the default base is 10. A
466 leading dash is printed for negative integers.
467 The precision field selects base, for example:
469 1> io:fwrite("~.16B~n", [31]).
471 1F
472 ok
473 2> io:fwrite("~.2B~n", [-19]).
474 -10011
475 ok
476 3> io:fwrite("~.36B~n", [5*36+35]).
477 5Z
478 ok
479 X:
481 Like B, but takes an extra argument that is a prefix to in‐
482 sert before the number, but after the leading dash, if any.
483 The prefix can be a possibly deep list of characters or an
485 atom. Example:
486 1> io:fwrite("~X~n", [31,"10#"]).
488 10#31
489 ok
490 2> io:fwrite("~.16X~n", [-31,"0x"]).
491 -0x1F
492 ok
493 #:
495 Like B, but prints the number with an Erlang style #-sepa‐
496 rated base prefix. Example:
497 1> io:fwrite("~.10#~n", [31]).
499 10#31
500 ok
501 2> io:fwrite("~.16#~n", [-31]).
502 -16#1F
503 ok
504 b:
506 Like B, but prints lowercase letters.
507 x:
509 Like X, but prints lowercase letters.
510 +:
512 Like #, but prints lowercase letters.
513 n:
515 Writes a new line.
516 i:
518 Ignores the next term.
519 The function returns:
521 ok:
523 The formatting succeeded.
524 If an error occurs, there is no output. Example:
526 1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
528 abc def 'abc def' {foo,1} A
529 ok
530 2> io:fwrite("~s", [65]).
531 ** exception error: bad argument
532 in function io:format/3
533 called as io:format(<0.53.0>,"~s","A")
534 In this example, an attempt was made to output the single char‐
536 acter 65 with the aid of the string formatting directive "~s".
537 fread(Prompt, Format) -> Result
539 fread(IoDevice, Prompt, Format) -> Result
541 Types:
543 IoDevice = device()
545 Prompt = prompt()
546 Format = format()
547 Result =
548 {ok, Terms :: [term()]} |
549 {error, {fread, FreadError :: io_lib:fread_error()}} |
550 server_no_data()
551 server_no_data() = {error, ErrorDescription :: term()} | eof
552 Reads characters from the standard input (IoDevice), prompting
554 it with Prompt. Interprets the characters in accordance with
555 Format. Format contains control sequences that directs the in‐
556 terpretation of the input.
557 Format can contain the following:
559 * Whitespace characters (Space, Tab, and Newline) that cause
561 input to be read to the next non-whitespace character.
562 * Ordinary characters that must match the next input charac‐
564 ter.
565 * Control sequences, which have the general format ~*FMC,
567 where:
568 * Character * is an optional return suppression character.
570 It provides a method to specify a field that is to be
571 omitted.
572 * F is the field width of the input field.
574 * M is an optional translation modifier (of which t is the
576 only supported, meaning Unicode translation).
577 * C determines the type of control sequence.
579 Unless otherwise specified, leading whitespace is ignored
581 for all control sequences. An input field cannot be more
582 than one line wide.
583 Available control sequences:
585 ~:
587 A single ~ is expected in the input.
588 d:
590 A decimal integer is expected.
591 u:
593 An unsigned integer in base 2-36 is expected. The field
594 width parameter is used to specify base. Leading white‐
595 space characters are not skipped.
596 -:
598 An optional sign character is expected. A sign character -
599 gives return value -1. Sign character + or none gives 1.
600 The field width parameter is ignored. Leading whitespace
601 characters are not skipped.
602 #:
604 An integer in base 2-36 with Erlang-style base prefix (for
605 example, "16#ffff") is expected.
606 f:
608 A floating point number is expected. It must follow the
609 Erlang floating point number syntax.
610 s:
612 A string of non-whitespace characters is read. If a field
613 width has been specified, this number of characters are
614 read and all trailing whitespace characters are stripped.
615 An Erlang string (list of characters) is returned.
616 If Unicode translation is in effect (~ts), characters >
618 255 are accepted, otherwise not. With the translation mod‐
619 ifier, the returned list can as a consequence also contain
620 integers > 255:
621 1> io:fread("Prompt> ","~s").
623 Prompt> <Characters beyond latin1 range not printable in this medium>
624 {error,{fread,string}}
625 2> io:fread("Prompt> ","~ts").
626 Prompt> <Characters beyond latin1 range not printable in this medium>
627 {ok,[[1091,1085,1080,1094,1086,1076,1077]]}
628 a:
630 Similar to s, but the resulting string is converted into
631 an atom.
632 c:
634 The number of characters equal to the field width are read
635 (default is 1) and returned as an Erlang string. However,
636 leading and trailing whitespace characters are not omitted
637 as they are with s. All characters are returned.
638 The Unicode translation modifier works as with s:
640 1> io:fread("Prompt> ","~c").
642 Prompt> <Character beyond latin1 range not printable in this medium>
643 {error,{fread,string}}
644 2> io:fread("Prompt> ","~tc").
645 Prompt> <Character beyond latin1 range not printable in this medium>
646 {ok,[[1091]]}
647 l:
649 Returns the number of characters that have been scanned up
650 to that point, including whitespace characters.
651 The function returns:
653 {ok, Terms}:
655 The read was successful and Terms is the list of success‐
656 fully matched and read items.
657 eof:
659 End of file was encountered.
660 {error, FreadError}:
662 The reading failed and FreadError gives a hint about the
663 error.
664 {error, ErrorDescription}:
666 The read operation failed and parameter ErrorDescription
667 gives a hint about the error.
668 Examples:
670 20> io:fread('enter>', "~f~f~f").
672 enter>1.9 35.5e3 15.0
673 {ok,[1.9,3.55e4,15.0]}
674 21> io:fread('enter>', "~10f~d").
675 enter> 5.67899
676 {ok,[5.678,99]}
677 22> io:fread('enter>', ":~10s:~10c:").
678 enter>: alan : joe :
679 {ok, ["alan", " joe "]}
680 get_chars(Prompt, Count) -> Data | server_no_data()
682 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
684 Types:
686 IoDevice = device()
688 Prompt = prompt()
689 Count = integer() >= 0
690 Data = string() | unicode:unicode_binary()
691 server_no_data() = {error, ErrorDescription :: term()} | eof
692 Reads Count characters from standard input (IoDevice), prompting
694 it with Prompt.
695 The function returns:
697 Data:
699 The input characters. If the I/O device supports Unicode,
700 the data can represent codepoints > 255 (the latin1 range).
701 If the I/O server is set to deliver binaries, they are en‐
702 coded in UTF-8 (regardless of whether the I/O device sup‐
703 ports Unicode). If you want the data to be returned as a
704 latin1 encoded binary you should use file:read/2 instead.
705 eof:
707 End of file was encountered.
708 {error, ErrorDescription}:
710 Other (rare) error condition, such as {error, estale} if
711 reading from an NFS file system.
712 get_line(Prompt) -> Data | server_no_data()
714 get_line(IoDevice, Prompt) -> Data | server_no_data()
716 Types:
718 IoDevice = device()
720 Prompt = prompt()
721 Data = string() | unicode:unicode_binary()
722 server_no_data() = {error, ErrorDescription :: term()} | eof
723 Reads a line from the standard input (IoDevice), prompting it
725 with Prompt.
726 The function returns:
728 Data:
730 The characters in the line terminated by a line feed (or end
731 of file). If the I/O device supports Unicode, the data can
732 represent codepoints > 255 (the latin1 range). If the I/O
733 server is set to deliver binaries, they are encoded in UTF-8
734 (regardless of if the I/O device supports Unicode). If you
735 want the data to be returned as a latin1 encoded binary you
736 should use file:read_line/1 instead.
737 eof:
739 End of file was encountered.
740 {error, ErrorDescription}:
742 Other (rare) error condition, such as {error, estale} if
743 reading from an NFS file system.
744 getopts() -> [get_opt_pair()] | {error, Reason}
746 getopts(IoDevice) -> [get_opt_pair()] | {error, Reason}
748 Types:
750 IoDevice = device()
752 Reason = term()
753 Requests all available options and their current values for a
755 specific I/O device, for example:
756 1> {ok,F} = file:open("/dev/null",[read]).
758 {ok,<0.42.0>}
759 2> io:getopts(F).
760 [{binary,false},{encoding,latin1}]
761 Here the file I/O server returns all available options for a
763 file, which are the expected ones, encoding and binary. However,
764 the standard shell has some more options:
765 3> io:getopts().
767 [{expand_fun,#Fun<group.0.120017273>},
768 {echo,true},
769 {binary,false},
770 {encoding,unicode},
771 {terminal,true}]
772 This example is, as can be seen, run in an environment where the
774 terminal supports Unicode input and output.
775 The terminal option is read only and indicates whether the out‐
777 put stream is a terminal or not. When it is a terminal, most
778 systems that Erlang runs on allows the use of ANSI escape codes
779 to control what the terminal outputs.
780 See setopts/1 for a description of the other options.
782 nl() -> ok
784 nl(IoDevice) -> ok
786 Types:
788 IoDevice = device()
790 Writes new line to the standard output (IoDevice).
792 parse_erl_exprs(Prompt) -> Result
794 parse_erl_exprs(IoDevice, Prompt) -> Result
796 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
798 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
800 Result
801 Types:
803 IoDevice = device()
805 Prompt = prompt()
806 StartLocation = location()
807 Options = erl_scan:options()
808 Result = parse_ret()
809 parse_ret() =
810 {ok,
811 ExprList :: [erl_parse:abstract_expr()],
812 EndLocation :: location()} |
813 {eof, EndLocation :: location()} |
814 {error,
815 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
816 ErrorLocation :: location()} |
817 server_no_data()
818 server_no_data() = {error, ErrorDescription :: term()} | eof
819 Reads data from the standard input (IoDevice), prompting it with
821 Prompt. Starts reading at location StartLocation (1). Argument
822 Options is passed on as argument Options of function
823 erl_scan:tokens/4. The data is tokenized and parsed as if it was
824 a sequence of Erlang expressions until a final dot (.) is
825 reached.
826 The function returns:
828 {ok, ExprList, EndLocation}:
830 The parsing was successful.
831 {eof, EndLocation}:
833 End of file was encountered by the tokenizer.
834 eof:
836 End of file was encountered by the I/O server.
837 {error, ErrorInfo, ErrorLocation}:
839 An error occurred while tokenizing or parsing.
840 {error, ErrorDescription}:
842 Other (rare) error condition, such as {error, estale} if
843 reading from an NFS file system.
844 Example:
846 25> io:parse_erl_exprs('enter>').
848 enter>abc(), "hey".
849 {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
850 26> io:parse_erl_exprs ('enter>').
851 enter>abc("hey".
852 {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
853 parse_erl_form(Prompt) -> Result
855 parse_erl_form(IoDevice, Prompt) -> Result
857 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
859 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
861 Types:
863 IoDevice = device()
865 Prompt = prompt()
866 StartLocation = location()
867 Options = erl_scan:options()
868 Result = parse_form_ret()
869 parse_form_ret() =
870 {ok,
871 AbsForm :: erl_parse:abstract_form(),
872 EndLocation :: location()} |
873 {eof, EndLocation :: location()} |
874 {error,
875 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
876 ErrorLocation :: location()} |
877 server_no_data()
878 server_no_data() = {error, ErrorDescription :: term()} | eof
879 Reads data from the standard input (IoDevice), prompting it with
881 Prompt. Starts reading at location StartLocation (1). Argument
882 Options is passed on as argument Options of function
883 erl_scan:tokens/4. The data is tokenized and parsed as if it was
884 an Erlang form (one of the valid Erlang expressions in an Erlang
885 source file) until a final dot (.) is reached.
886 The function returns:
888 {ok, AbsForm, EndLocation}:
890 The parsing was successful.
891 {eof, EndLocation}:
893 End of file was encountered by the tokenizer.
894 eof:
896 End of file was encountered by the I/O server.
897 {error, ErrorInfo, ErrorLocation}:
899 An error occurred while tokenizing or parsing.
900 {error, ErrorDescription}:
902 Other (rare) error condition, such as {error, estale} if
903 reading from an NFS file system.
904 printable_range() -> unicode | latin1
906 Returns the user-requested range of printable Unicode charac‐
908 ters.
909 The user can request a range of characters that are to be con‐
911 sidered printable in heuristic detection of strings by the shell
912 and by the formatting functions. This is done by supplying +pc
913 <range> when starting Erlang.
914 The only valid values for <range> are latin1 and unicode. latin1
916 means that only code points < 256 (except control characters,
917 and so on) are considered printable. unicode means that all
918 printable characters in all Unicode character ranges are consid‐
919 ered printable by the I/O functions.
920 By default, Erlang is started so that only the latin1 range of
922 characters indicate that a list of integers is a string.
923 The simplest way to use the setting is to call io_lib:print‐
925 able_list/1, which uses the return value of this function to de‐
926 cide if a list is a string of printable characters.
927 Note:
929 In a future release, this function may return more values and
930 ranges. To avoid compatibility problems, it is recommended to
931 use function io_lib:printable_list/1.
932 put_chars(CharData) -> ok
935 put_chars(IoDevice, CharData) -> ok
937 Types:
939 IoDevice = device()
941 CharData = unicode:chardata()
942 Writes the characters of CharData to the I/O server (IoDevice).
944 If you want to write latin1 encoded bytes to the I/O server you
945 should use file:write/2 instead.
946 read(Prompt) -> Result
948 read(IoDevice, Prompt) -> Result
950 Types:
952 IoDevice = device()
954 Prompt = prompt()
955 Result =
956 {ok, Term :: term()} | server_no_data() | {error, Error‐
957 Info}
958 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
959 server_no_data() = {error, ErrorDescription :: term()} | eof
960 Reads a term Term from the standard input (IoDevice), prompting
962 it with Prompt.
963 The function returns:
965 {ok, Term}:
967 The parsing was successful.
968 eof:
970 End of file was encountered.
971 {error, ErrorInfo}:
973 The parsing failed.
974 {error, ErrorDescription}:
976 Other (rare) error condition, such as {error, estale} if
977 reading from an NFS file system.
978 read(IoDevice, Prompt, StartLocation) -> Result
980 read(IoDevice, Prompt, StartLocation, Options) -> Result
982 Types:
984 IoDevice = device()
986 Prompt = prompt()
987 StartLocation = location()
988 Options = erl_scan:options()
989 Result =
990 {ok, Term :: term(), EndLocation :: location()} |
991 {eof, EndLocation :: location()} |
992 server_no_data() |
993 {error, ErrorInfo, ErrorLocation :: location()}
994 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
995 server_no_data() = {error, ErrorDescription :: term()} | eof
996 Reads a term Term from IoDevice, prompting it with Prompt. Read‐
998 ing starts at location StartLocation. Argument Options is passed
999 on as argument Options of function erl_scan:tokens/4.
1000 The function returns:
1002 {ok, Term, EndLocation}:
1004 The parsing was successful.
1005 {eof, EndLocation}:
1007 End of file was encountered.
1008 {error, ErrorInfo, ErrorLocation}:
1010 The parsing failed.
1011 {error, ErrorDescription}:
1013 Other (rare) error condition, such as {error, estale} if
1014 reading from an NFS file system.
1015 rows() -> {ok, integer() >= 1} | {error, enotsup}
1017 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
1019 Types:
1021 IoDevice = device()
1023 Retrieves the number of rows of IoDevice (that is, the height of
1025 a terminal). The function only succeeds for terminal devices,
1026 for all other I/O devices the function returns {error, enotsup}.
1027 scan_erl_exprs(Prompt) -> Result
1029 scan_erl_exprs(Device, Prompt) -> Result
1031 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
1033 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
1035 Types:
1037 Device = device()
1039 Prompt = prompt()
1040 StartLocation = location()
1041 Options = erl_scan:options()
1042 Result = erl_scan:tokens_result() | server_no_data()
1043 server_no_data() = {error, ErrorDescription :: term()} | eof
1044 Reads data from the standard input (IoDevice), prompting it with
1046 Prompt. Reading starts at location StartLocation (1). Argument
1047 Options is passed on as argument Options of function
1048 erl_scan:tokens/4. The data is tokenized as if it were a se‐
1049 quence of Erlang expressions until a final dot (.) is reached.
1050 This token is also returned.
1051 The function returns:
1053 {ok, Tokens, EndLocation}:
1055 The tokenization succeeded.
1056 {eof, EndLocation}:
1058 End of file was encountered by the tokenizer.
1059 eof:
1061 End of file was encountered by the I/O server.
1062 {error, ErrorInfo, ErrorLocation}:
1064 An error occurred while tokenizing.
1065 {error, ErrorDescription}:
1067 Other (rare) error condition, such as {error, estale} if
1068 reading from an NFS file system.
1069 Example:
1071 23> io:scan_erl_exprs('enter>').
1073 enter>abc(), "hey".
1074 {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
1075 24> io:scan_erl_exprs('enter>').
1076 enter>1.0er.
1077 {error,{1,erl_scan,{illegal,float}},2}
1078 scan_erl_form(Prompt) -> Result
1080 scan_erl_form(IoDevice, Prompt) -> Result
1082 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
1084 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
1086 Types:
1088 IoDevice = device()
1090 Prompt = prompt()
1091 StartLocation = location()
1092 Options = erl_scan:options()
1093 Result = erl_scan:tokens_result() | server_no_data()
1094 server_no_data() = {error, ErrorDescription :: term()} | eof
1095 Reads data from the standard input (IoDevice), prompting it with
1097 Prompt. Starts reading at location StartLocation (1). Argument
1098 Options is passed on as argument Options of function
1099 erl_scan:tokens/4. The data is tokenized as if it was an Erlang
1100 form (one of the valid Erlang expressions in an Erlang source
1101 file) until a final dot (.) is reached. This last token is also
1102 returned.
1103 The return values are the same as for scan_erl_exprs/1,2,3,4.
1105 setopts(Opts) -> ok | {error, Reason}
1107 setopts(IoDevice, Opts) -> ok | {error, Reason}
1109 Types:
1111 IoDevice = device()
1113 Opts = [setopt()]
1114 Reason = term()
1115 Set options for the standard I/O device (IoDevice).
1117 Possible options and values vary depending on the I/O device.
1119 For a list of supported options and their current values on a
1120 specific I/O device, use function getopts/1.
1121 The options and values supported by the OTP I/O devices are as
1123 follows:
1124 binary, list, or {binary, boolean()}:
1126 If set in binary mode (binary or {binary, true}), the I/O
1127 server sends binary data (encoded in UTF-8) as answers to
1128 the get_line, get_chars, and, if possible, get_until re‐
1129 quests (for details, see section The Erlang I/O Protocol) in
1130 the User's Guide). The immediate effect is that
1131 get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead
1132 of lists of characters for the affected I/O device.
1133 By default, all I/O devices in OTP are set in list mode.
1135 However, the I/O functions can handle any of these modes and
1136 so should other, user-written, modules behaving as clients
1137 to I/O servers.
1138 This option is supported by the standard shell (group.erl),
1140 the 'oldshell' (user.erl), and the file I/O servers.
1141 {echo, boolean()}:
1143 Denotes if the terminal is to echo input. Only supported for
1144 the standard shell I/O server (group.erl)
1145 {expand_fun, expand_fun()}:
1147 Provides a function for tab-completion (expansion) like the
1148 Erlang shell. This function is called when the user presses
1149 the Tab key. The expansion is active when calling line-read‐
1150 ing functions, such as get_line/1,2.
1151 The function is called with the current line, up to the cur‐
1153 sor, as a reversed string. It is to return a three-tuple:
1154 {yes|no, string(), list()}. The first element gives a beep
1155 if no, otherwise the expansion is silent; the second is a
1156 string that will be entered at the cursor position; the
1157 third is a list of possible expansions. If this list is not
1158 empty, it is printed below the current input line. The list
1159 of possible expansions can be formatted in different ways to
1160 make more advanced expansion suggestions more readable to
1161 the user, see edlin_expand:expand/2 for documentation of
1162 that.
1163 Trivial example (beep on anything except empty line, which
1165 is expanded to "quit"):
1166 fun("") -> {yes, "quit", []};
1168 (_) -> {no, "", ["quit"]} end
1169 This option is only supported by the standard shell
1171 (group.erl).
1172 {encoding, latin1 | unicode}:
1174 Specifies how characters are input or output from or to the
1175 I/O device, implying that, for example, a terminal is set to
1176 handle Unicode input and output or a file is set to handle
1177 UTF-8 data encoding.
1178 The option does not affect how data is returned from the I/O
1180 functions or how it is sent in the I/O protocol, it only af‐
1181 fects how the I/O device is to handle Unicode characters to
1182 the "physical" device.
1183 The standard shell is set for unicode or latin1 encoding
1185 when the system is started. The encoding is set with the
1186 help of the LANG or LC_CTYPE environment variables on Unix-
1187 like system or by other means on other systems. So, the user
1188 can input Unicode characters and the I/O device is in {en‐
1189 coding, unicode} mode if the I/O device supports it. The
1190 mode can be changed, if the assumption of the runtime system
1191 is wrong, by setting this option.
1192 Note:
1194 Prior to OTP 26.0, when Erlang was started with the -oldshell
1195 or -noshell flags (for example, in an escript), the default
1196 encoding for standard_io was set to latin1, meaning that any
1197 characters > codepoint 255 were escaped and that input was ex‐
1198 pected to be plain 8-bit ISO Latin-1. As of OTP 26.0, stan‐
1199 dard_io always defaults to unicode if its supported, otherwise
1200 latin1.
1201 If you want to send raw bytes on standard_io, you now always
1203 need to explicitly set the encoding to latin1; otherwise, code
1204 points 128-255 will be converted to UTF-8. This is best done
1205 by setting the kernel configuration parameter standard_io_en‐
1206 coding to latin1.
1207 Files can also be set in {encoding, unicode}, meaning that
1210 data is written and read as UTF-8. More encodings are possi‐
1211 ble for files, see below.
1212 {encoding, unicode | latin1} is supported by both the stan‐
1214 dard shell (group.erl including werl on Windows), the 'old‐
1215 shell' (user.erl), and the file I/O servers.
1216 {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
1218 | {utf32,big} | {utf32,little}}:
1219 For disk files, the encoding can be set to various UTF vari‐
1220 ants. This has the effect that data is expected to be read
1221 as the specified encoding from the file, and the data is
1222 written in the specified encoding to the disk file.
1223 {encoding, utf8} has the same effect as {encoding, unicode}
1225 on files.
1226 The extended encodings are only supported on disk files
1228 (opened by function file:open/2).
1229 write(Term) -> ok
1231 write(IoDevice, Term) -> ok
1233 Types:
1235 IoDevice = device()
1237 Term = term()
1238 Writes term Term to the standard output (IoDevice).
1240
1242 The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1243 ture that is returned from all I/O modules. It has the following for‐
1244 mat:
1245 {ErrorLocation, Module, ErrorDescriptor}
1247 A string that describes the error is obtained with the following call:
1249 Module:format_error(ErrorDescriptor)
1251Ericsson AB stdlib 5.1.1 io(3)