From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= This module provides an interface to standard Erlang I/O servers.
The output functions all return In the following description, all functions have an optional
+
+ All functions in this module have an optional
parameter For a description of the IO protocols refer to the 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
For a description of the I/O protocols, see section
+
As from Erlang/OTP R13A, data supplied to function
+
If an I/O device is set in binary mode, functions
+
To work with binaries in ISO Latin-1 encoding, use the
+
For conversion functions between character encodings, see the
+
An IO device. Either
An I/O device, either
What the I/O-server sends when there is no data.
What the I/O server sends when there is no data.
Retrieves the number of columns of the
-
Writes the characters of
Writes new line to the standard output (
Reads
The input characters. If the IO device supports Unicode, - the data may represent codepoints larger than 255 (the - latin1 range). If the I/O server is set to deliver - binaries, they will be encoded in UTF-8 (regardless of if - the IO 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 IO device supports Unicode, - the data may represent codepoints larger than 255 (the - latin1 range). If the I/O server is set to deliver - binaries, they will be encoded in UTF-8 (regardless of if - the IO 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.
+Retrieves the number of columns of the
+
Return the user requested range of printable Unicode characters.
-The user can request a range of characters that are to be considered printable in heuristic detection of strings by the shell and by the formatting functions. This is done by supplying
Currently the only valid values for
By default, Erlang is started so that only the
The simplest way to utilize the setting is to call
In the future, this function may return more values and ranges. It is recommended to use the io_lib:printable_list/1 function to avoid compatibility problems.
Set options for the standard 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 IO device, use the
The options and values supported by the current OTP IO devices are:
-If set in binary mode (
By default, all IO devices in OTP are set in list mode, but the I/O 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 (
Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (
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
- fun("") -> {yes, "quit", []};
- (_) -> {no, "", ["quit"]} end
- This option is supported by the standard shell only (
Specifies how characters are input or output from or to the actual IO 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 I/O 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
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
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.
-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.
-Other (rare) error condition, for instance
Reads a term
The parsing was successful.
-End of file was encountered.
-The parsing failed.
-Other (rare) error condition, for instance
Writes the items in
Writes the items in
1> io:fwrite("Hello world!~n", []). Hello world! ok-
The general format of a control sequence is
The general format of a control sequence is
Character
The following control sequences are available:
+Available control sequences:
The character
Character
The argument is a number that will be interpreted as an +
The argument is a number that is 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:
+ character is printed and defaults to the field width, + which in turn defaults to 1. Example:1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]). | aaaaa|bbbbb |ccccc| ok
If the Unicode translation modifier (
2> io:fwrite("~tc~n",[1024]). @@ -435,29 +201,28 @@ ok 3> io:fwrite("~c~n",[1024]). ^@ ok-
The argument is a float which is written as +
The argument is a float that is written as
The argument is a float which is written as +
The argument is a float that is written as
The argument is a float which is written as
The argument is a float that is written as
This format can be used for printing any object and truncating the output so it fits a specified field:
@@ -484,7 +250,8 @@ ok 3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]). |{hey,hey | ok-
A list with integers larger than 255 is considered an error if the Unicode translation modifier is not given:
+A list with integers > 255 is considered an error if the + Unicode translation modifier is not specified:
4> io:fwrite("~ts~n",[[1024]]). \x{400} @@ -497,8 +264,8 @@ ok-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 + they contain embedded non-printable characters. + Floats are printed accurately as the shortest, correctly rounded string.
@@ -506,11 +273,11 @@ ok p Writes the data with standard syntax in the same way as
+ what characters are printable, for example:~w , but breaks terms whose printed representation is longer than one line into many lines and indents each - line sensibly. Left justification is not supported. + line sensibly. Left-justification is not supported. It also tries to detect lists of printable characters and to output these as strings. The Unicode translation modifier is used for determining - what characters are printable. For example:1> T = [{attributes,[[{id,age,1.50000},{mode,explicit}, {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]}, @@ -531,12 +298,13 @@ ok {tag,{'PRIVATE',3}}, {mode,implicit}] ok-The field width specifies the maximum line length. It - defaults to 80. The precision specifies the initial +
The field width specifies the maximum line length. + 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
+ characters printed on this line in the same call to +same call to -io:fwrite orio:format . For example, using -T above:or + write/1 . + For example, using format/1,2,3 T above:4> io:fwrite("Here T = ~62p~n", [T]). Here T = [{attributes,[[{id,age,1.5}, @@ -549,8 +317,8 @@ Here T = [{attributes,[[{id,age,1.5}, {tag,{'PRIVATE',3}}, {mode,implicit}] ok-When the modifier
+l is given no detection of - printable character lists will take place. For example:When the modifier
l is specified, no detection of + printable character lists takes place, for example:5> S = [{a,"a"}, {b, "b"}]. 6> io:fwrite("~15p~n", [S]). @@ -561,9 +329,9 @@ ok [{a,[97]}, {b,[98]}] ok-Binaries that look like UTF-8 encoded strings will be +
Binaries that look like UTF-8 encoded strings are output with the string syntax if the Unicode translation - modifier is given:
+ modifier is specified:9> io:fwrite("~p~n",[[1024]]). [1024] @@ -578,7 +346,7 @@ okW Writes data in the same way as
~w , but takes an - extra argument which is the maximum depth to which terms + extra argument that is the maximum depth to which terms are printed. Anything below this depth is replaced with... . For example, usingT above:@@ -587,17 +355,17 @@ ok[{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 +
If the maximum depth is reached, it cannot
+ be read in the resultant output. Also, the
Writes data in the same way as
9> io:fwrite("~62P~n", [T,9]). [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}], @@ -609,9 +377,9 @@ ok
Writes an integer in base 2..36, the default base is +
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:
+The precision field selects base, for example:
1> io:fwrite("~.16B~n", [31]). 1F @@ -629,7 +397,7 @@ okprefix to insert before the number, but after the leading dash, if any.
The prefix can be a possibly deep list of characters or - an atom.
+ an atom. Example:1> io:fwrite("~X~n", [31,"10#"]). 10#31 @@ -641,7 +409,7 @@ ok
Like
1> io:fwrite("~.10#~n", [31]). 10#31 @@ -671,14 +439,14 @@ ok
Ignores the next term.
Returns:
+The function returns:
The formatting succeeded.
If an error occurs, there is no output. For example:
+If an error occurs, there is no output. Example:
1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]). abc def 'abc def' {foo,1} A @@ -692,45 +460,57 @@ ok 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 (
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.
+Whitespace characters (Space, Tab, and + Newline) that cause input to be read to the next + non-whitespace character.
Ordinary characters which must match the next input +
Ordinary characters that must match the next input character.
Control sequences, which have the general format
-
Unless otherwise specified, leading white-space is
+
Character
Unless otherwise specified, leading whitespace is ignored for all control sequences. An input field cannot - be more than one line wide. The following control - sequences are available:
+ be more than one line wide. +Available control sequences:
An unsigned integer in base 2..36 is expected. The +
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.
+ whitespace characters are not skipped.An optional sign character is expected. A sign
- character
An integer in base 2..36 with Erlang-style base
- prefix (for example
An integer in base 2-36 with Erlang-style base
+ prefix (for example,
A string of non-white-space characters is read. If a +
A string of non-whitespace characters is read. If a field width has been specified, this number of - characters are read and all trailing white-space + characters are read and all trailing whitespace characters are stripped. An Erlang string (list of characters) is returned.
- -If Unicode translation is in effect (
If Unicode translation is in effect (
1> io:fread("Prompt> ","~s"). Prompt> <Characters beyond latin1 range not printable in this medium> @@ -785,22 +562,23 @@ Prompt> <Characters beyond latin1 range not printable in this medium&g 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 Unicode translation modifier is not allowed (atoms
+ cannot contain characters beyond the
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
+ However, leading and trailing whitespace characters
are not omitted as they are with
The Unicode translation modifier works as with
The Unicode translation modifier works as with
1> io:fread("Prompt> ","~c"). Prompt> <Character beyond latin1 range not printable in this medium> @@ -808,21 +586,20 @@ Prompt> <Character beyond latin1 range not printable in this medium> 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 +
Returns the number of characters that have been + scanned up to that point, including whitespace characters.
It returns:
+The function returns:
The read was successful and
The read was successful and
The read operation failed and the parameter
-
The read operation failed and parameter
+
Examples:
+Examples:
20> io:fread('enter>', "~f~f~f"). enter>1.9 35.5e3 15.0 @@ -854,104 +632,127 @@ enter>: alan : joe
Retrieves the number of rows of the
-
Reads
The function returns:
+The input characters. If the I/O device supports Unicode,
+ the data can represent codepoints > 255 (the
+
End of file was encountered.
+Other (rare) error condition, such as
Reads data from the standard input (
Reads a line from the standard input (
The function returns:
The tokenization succeeded.
-End of file was encountered by the tokenizer.
+The characters in the line terminated by a line feed (or end of
+ file). If the I/O device supports Unicode,
+ the data can represent codepoints > 255 (the
+
End of file was encountered by the I/O-server.
+End of file was encountered.
An error occurred while tokenizing.
-Other (rare) error condition, for instance
Other (rare) error condition, such as
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 (
Requests all available options and their current + values for a specific I/O device, for 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.
Writes new line to the standard output
+ (
Reads data from the standard input
(
The function returns:
End of file was encountered by the I/O-server.
+End of file was encountered by the I/O server.
An error occurred while tokenizing or parsing.
Other (rare) error condition, for instance
Other (rare) error condition, such as
Example:
@@ -985,24 +786,25 @@ enter>abc("hey". {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
Reads data from the standard input (
The function returns:
End of file was encountered by the I/O-server.
+End of file was encountered by the I/O server.
An error occurred while tokenizing or parsing.
Other (rare) error condition, for instance
Other (rare) error condition, such as
Returns the user-requested range of printable Unicode characters.
+The user can request a range of characters that are to be considered
+ printable in heuristic detection of strings by the shell and by the
+ formatting functions. This is done by supplying
+
The only valid values for
By default, Erlang is started so that only the
The simplest way to use the setting is to call
+
In a future release, this function may return more values and
+ ranges. To avoid compatibility problems, it is recommended to use
+ function
Writes the characters of
Reads a term
The function returns:
+The parsing was successful.
+End of file was encountered.
+The parsing failed.
+Other (rare) error condition, such as
Reads a term
The function returns:
+The parsing was successful.
+End of file was encountered.
+The parsing failed.
+Other (rare) error condition, such as
Retrieves the number of rows of
Reads data from the standard input (
The function returns:
+The tokenization succeeded.
+End of file was encountered by the tokenizer.
+End of file was encountered by the I/O server.
+An error occurred while tokenizing.
+Other (rare) error condition, such as
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 (
The return values are the same as for
+
Set options for the standard I/O device
+ (
Possible options and values vary depending on the
+ I/O device. For a list of supported options and their current values
+ on a specific I/O device, use function
+
The options and values supported by the OTP I/O devices + are as follows:
+If set in binary mode (
By default, all I/O devices in OTP are set in
This option is supported by the standard shell
+ (
Denotes if the terminal is to echo input. Only supported for
+ the standard shell I/O server (
Provides 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, up to
+ the cursor, as a reversed string. It is to return a
+ three-tuple:
Trivial example (beep on anything except empty line, which
+ is expanded to
+fun("") -> {yes, "quit", []};
+ (_) -> {no, "", ["quit"]} end
+ This option is only supported by the standard shell
+ (
Specifies how characters are input or output from or to the I/O + device, implying that, for example, 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 + I/O functions or how it is sent in the I/O protocol, it only + affects how the I/O device is to handle Unicode characters to the + "physical" device.
+The standard shell is set for
The I/O device used when Erlang is started with the "-oldshell"
+ or "-noshell" flags is by default set to
Files can also be set in
For disk files, the encoding can be set to various UTF variants. + This has the effect that data is expected to be read as the + specified encoding from the file, and the data is written in the + specified encoding to the disk file.
+The extended encodings are only supported on disk files
+ (opened by function
+
Writes term
All Erlang processes have a default standard IO device. This +
All Erlang processes have a default standard I/O device. This
device is used when no
27> io:read('enter>'). enter>foo. @@ -1047,30 +1170,37 @@ enter>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 I/O-server specific for error messages might be convenient. The IO device
In certain situations, especially when the standard output is
+ redirected, access to an I/O server specific for error messages can be
+ convenient. The I/O device
$ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\ 'init:stop().' > /dev/null Error: error 11- - -
The
The
{ErrorLocation, Module, ErrorDescriptor}
- A string which describes the error is obtained with the following + +
A string that describes the error is obtained with the following call:
+
Module:format_error(ErrorDescriptor)