This module provides an interface to standard Erlang IO servers.
The output functions all return
In the following description, all functions have an optional
parameter
For a description of the IO protocols refer to the STDLIB Users Guide.
As of R13A, data supplied to the
If an io_device() is set in binary mode, the functions
To work with binaries in ISO-latin-1 encoding, use the
For conversion functions between character encodings, see the
io_device()
as returned by file:open/2, a process handling IO protocols
unicode_binary() = binary() with characters encoded in UTF-8 coding standard
unicode_char() = integer() representing valid unicode codepoint
chardata() = charlist() | unicode_binary()
charlist() = [unicode_char() | unicode_binary() | charlist()]
a unicode_binary is allowed as the tail of the list
Retrieves the number of columns of the
Writes the characters of
Writes new line to the standard output (
Reads
The input characters. If the device supports Unicode, the data may represent codepoints larger than 255 (the latin1 range). If the io_server() is set to deliver binaries, they will be encoded in UTF-8 (regardless of if the device actually supports Unicode or not).
End of file was encountered.
Other (rare) error condition, for instance
Reads a line from the standard input (
The characters in the line terminated by a LF (or end of file). If the device supports Unicode, the data may represent codepoints larger than 255 (the latin1 range). If the io_server() is set to deliver binaries, they will be encoded in UTF-8 (regardless of if the device actually supports Unicode or not).
End of file was encountered.
Other (rare) error condition, for instance
This function requests all available options and their current values for a specific io_device(). Example:
1> {ok,F} = file:open("/dev/null",[read]).
{ok,<0.42.0>}
2> io:getopts(F).
[{binary,false},{encoding,latin1}]
Here the file I/O-server returns all available options for a file,
which are the expected ones,
3> io:getopts().
[{expand_fun,#Fun<group.0.120017273>},
{echo,true},
{binary,false},
{encoding,unicode}]
This example is, as can be seen, run in an environment where the terminal supports Unicode input and output.
Set options for the io_device() (
Possible options and values vary depending on the actual
io_device(). For a list of supported options and their current values
on a specific device, use the
The options and values supported by the current OTP io_devices are:
If set in binary mode (binary or {binary,true}), the io_server() sends binary data (encoded in UTF-8) as answers to the get_line, get_chars and, if possible, get_until requests (see the I/O protocol description in STDLIB User's Guide for details). The immediate effect is that
By default, all io_devices in OTP are set in list mode, but the io functions can handle any of these modes and so should other, user written, modules behaving as clients to I/O-servers.
This option is supported by the standard shell (group.erl), the 'oldshell' (user.erl) and the file I/O servers.
Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (group.erl)
Provide a function for tab-completion (expansion)
like the erlang shell. This function is called
when the user presses the Tab key. The expansion is
active when calling line-reading functions such as
The function is called with the current line, upto
the cursor, as a reversed string. It should return a
three-tuple:
Trivial example (beep on anything except empty line, which is expanded to "quit"):
fun("") -> {yes, "quit", []};
(_) -> {no, "", ["quit"]} end
This option is supported by the standard shell only (group.erl).
Specifies how characters are input or output from or to the actual device, implying that i.e. a terminal is set to handle Unicode input and output or a file is set to handle UTF-8 data encoding.
The option does not affect how data is returned from the io-functions or how it is sent in the I/O-protocol, it only affects how the io_device() is to handle Unicode characters towards the "physical" device.
The standard shell will be set for either unicode or latin1 encoding when the system is started. The actual encoding is set with the help of the "LANG" or "LC_CTYPE" environment variables on Unix-like system or by other means on other systems. The bottom line is that the user can input Unicode characters and the device will be in {encoding, unicode} mode if the device supports it. The mode can be changed, if the assumption of the runtime system is wrong, by setting this option.
The io_device() used when Erlang is started with the "-oldshell" or "-noshell" flags is by default set to latin1 encoding, meaning that any characters beyond codepoint 255 will be escaped and that input is expected to be plain 8-bit ISO-latin-1. If the encoding is changed to Unicode, input and output from the standard file descriptors will be in UTF-8 (regardless of operating system).
Files can also be set in {encoding, unicode}, meaning that data is written and read as UTF-8. More encodings are possible for files, see below.
{encoding, unicode | latin1} is supported by both the standard shell (group.erl including werl on windows), the 'oldshell' (user.erl) and the file I/O servers.
For disk files, the encoding can be set to various UTF variants. This will have the effect that data is expected to be read as the specified encoding from the file and the data will be written in the specified encoding to the disk file.
{encoding, utf8} will have the same effect as {encoding,unicode} on files.
The extended encodings are only supported on disk files (opened by the
Writes the term
Reads a term
The parsing was successful.
End of file was encountered.
The parsing failed.
Reads a term
The parsing was successful.
End of file was encountered.
The parsing failed.
Writes the items in
1> io:fwrite("Hello world!~n", []).
Hello world!
ok
The general format of a control sequence is
The following control sequences are available:
The character
The argument is a number that will be interpreted as an ASCII code. The precision is the number of times the character is printed and it defaults to the field width, which in turn defaults to 1. The following example illustrates:
2> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
| aaaaa|bbbbb |ccccc|
ok
If the Unicode translation modifier ('t') is in effect, the integer argument can be any number representing a valid unicode codepoint, otherwise it should be an integer less than or equal to 255, otherwise it is masked with 16#FF:
1> io:fwrite("~tc~n",[1024]).
\x{400}
ok
2> io:fwrite("~c~n",[1024]).
^@
ok
The argument is a float which is written as
The argument is a float which is written as
The argument is a float which is written as
Prints the argument with the
This format can be used for printing any object and truncating the output so it fits a specified field:
3> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
|**********|
ok
4> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
|{hey,hey,h|
ok
A list with integers larger than 255 is considered an error if the Unicode translation modifier is not given:
1> io:fwrite("~ts~n",[[1024]]).
\x{400}
ok
2> io:fwrite("~s~n",[[1024]]).
** exception exit: {badarg,[{io,format,[<0.26.0>,"~s~n",[[1024]]]},
...
Writes data with the standard syntax. This is used to output Erlang terms. Atoms are printed within quotes if they contain embedded non-printable characters, and floats are printed accurately as the shortest, correctly rounded string.
Writes the data with standard syntax in the same way as
5> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
{typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
{typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
...
6> io:fwrite("~w~n", [T]).
[{attributes,[[{id,age,1.5},{mode,explicit},{typename,
[73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
,implicit}]
ok
7> io:fwrite("~62p~n", [T]).
[{attributes,[[{id,age,1.5},
{mode,explicit},
{typename,"INTEGER"}],
[{id,cho},{mode,explicit},{typename,'Cho'}]]},
{typename,'Person'},
{tag,{'PRIVATE',3}},
{mode,implicit}]
ok
The field width specifies the maximum line length. It
defaults to 80. The precision specifies the initial
indentation of the term. It defaults to the number of
characters printed on this line in the
8> io:fwrite("Here T = ~62p~n", [T]).
Here T = [{attributes,[[{id,age,1.5},
{mode,explicit},
{typename,"INTEGER"}],
[{id,cho},
{mode,explicit},
{typename,'Cho'}]]},
{typename,'Person'},
{tag,{'PRIVATE',3}},
{mode,implicit}]
ok
Writes data in the same way as
9> io:fwrite("~W~n", [T,9]).
[{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
[{id,cho},{mode,...},{...}]]},{typename,'Person'},
{tag,{'PRIVATE',3}},{mode,implicit}]
ok
If the maximum depth has been reached, then it is
impossible to read in the resultant output. Also, the
Writes data in the same way as
10> io:fwrite("~62P~n", [T,9]).
[{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
[{id,cho},{mode,...},{...}]]},
{typename,'Person'},
{tag,{'PRIVATE',3}},
{mode,implicit}]
ok
Writes an integer in base 2..36, the default base is 10. A leading dash is printed for negative integers.
The precision field selects base. For example:
11> io:fwrite("~.16B~n", [31]).
1F
ok
12> io:fwrite("~.2B~n", [-19]).
-10011
ok
13> io:fwrite("~.36B~n", [5*36+35]).
5Z
ok
Like
The prefix can be a possibly deep list of characters or an atom.
14> io:fwrite("~X~n", [31,"10#"]).
10#31
ok
15> io:fwrite("~.16X~n", [-31,"0x"]).
-0x1F
ok
Like
16> io:fwrite("~.10#~n", [31]).
10#31
ok
17> io:fwrite("~.16#~n", [-31]).
-16#1F
ok
Like
Like
Like
Writes a new line.
Ignores the next term.
Returns:
The formatting succeeded.
If an error occurs, there is no output. For example:
18> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
abc def 'abc def' {foo,1} A
ok
19> io:fwrite("~s", [65]).
** exception exit: {badarg,[{io,format,[<0.22.0>,"~s","A"]},
{erl_eval,do_apply,5},
{shell,exprs,6},
{shell,eval_exprs,6},
{shell,eval_loop,3}]}
in function io:o_request/2
In this example, an attempt was made to output the single character '65' with the aid of the string formatting directive "~s".
Reads characters from the standard input (
White space characters (SPACE, TAB and NEWLINE) which cause input to be read to the next non-white space character.
Ordinary characters which must match the next input character.
Control sequences, which have the general format
Unless otherwise specified, leading white-space is ignored for all control sequences. An input field cannot be more than one line wide. The following control sequences are available:
A single
A decimal integer is expected.
An unsigned integer in base 2..36 is expected. The field width parameter is used to specify base. Leading white-space characters are not skipped.
An optional sign character is expected. A sign
character '-' gives the return value
An integer in base 2..36 with Erlang-style base
prefix (for example
A floating point number is expected. It must follow the Erlang floating point number syntax.
A string of non-white-space characters is read. If a field width has been specified, this number of characters are read and all trailing white-space characters are stripped. An Erlang string (list of characters) is returned.
If Unicode translation is in effect (~ts), characters larger than 255 are accepted, otherwise not. With the translation modifier, the list returned may as a consequence also contain integers larger than 255:
1> io:fread("Prompt> ","~s").
Prompt> <Characters beyond latin1 range not printable in this medium>
{error,{fread,string}}
2> io:fread("Prompt> ","~ts").
Prompt> <Characters beyond latin1 range not printable in this medium>
{ok,[[1091,1085,1080,1094,1086,1076,1077]]}
Similar to
The Unicode translation modifier is not allowed (atoms can not contain characters beyond the latin1 range).
The number of characters equal to the field width are
read (default is 1) and returned as an Erlang string.
However, leading and trailing white-space characters
are not omitted as they are with
The Unicode translation modifier works as with
1> io:fread("Prompt> ","~c").
Prompt> <Character beyond latin1 range not printable in this medium>
{error,{fread,string}}
2> io:fread("Prompt> ","~tc").
Prompt> <Character beyond latin1 range not printable in this medium>
{ok,[[1091]]}
Returns the number of characters which have been scanned up to that point, including white-space characters.
It returns:
The read was successful and
End of file was encountered.
The read operation failed and the parameter
Examples:
20> io:fread('enter>', "~f~f~f").
enter>1.9 35.5e3 15.0
{ok,[1.9,3.55e4,15.0]}
21> io:fread('enter>', "~10f~d").
enter> 5.67899
{ok,[5.678,99]}
22> io:fread('enter>', ":~10s:~10c:").
enter>: alan : joe :
{ok, ["alan", " joe "]}
Retrieves the number of rows of the
Reads data from the standard input (
The tokenization succeeded.
End of file was encountered.
An error occurred.
Example:
23> io:scan_erl_exprs('enter>').
enter>abc(), "hey".
{ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
24> io:scan_erl_exprs('enter>').
enter>1.0er.
{error,{1,erl_scan,{illegal,float}},2}
Reads data from the standard input (
Reads data from the standard input (
The parsing was successful.
End of file was encountered.
An error occurred.
Example:
25> io:parse_erl_exprs('enter>').
enter>abc(), "hey".
{ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
26> io:parse_erl_exprs ('enter>').
enter>abc("hey".
{error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
Reads data from the standard input (
The parsing was successful.
End of file was encountered.
An error occurred.
All Erlang processes have a default standard IO device. This
device is used when no
27> io:read('enter>').
enter>foo.
{ok,foo}
28> io:read(standard_io, 'enter>').
enter>bar.
{ok,bar}
There is always a process registered under the name of
In certain situations, especially when the standard output is redirected, access to an io_server() specific for error messages might be convenient. The io_device 'standard_error' can be used to direct output to whatever the current operating system considers a suitable device for error output. Example on a Unix-like operating system:
$ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\ 'init:stop().' > /dev/null Error: error 11
The
{ErrorLine, Module, ErrorDescriptor}
A string which describes the error is obtained with the following call:
Module:format_error(ErrorDescriptor)