From e5875001247e6a6ac4f474157a51a8c54f94ae49 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 14 Mar 2013 16:01:25 +0100 Subject: Convert XML files to UTF-8 --- lib/stdlib/doc/src/io_lib.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 3dac259477..9cbc54d8bd 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -1,4 +1,4 @@ - + -- cgit v1.2.3 From a474bdfda30a3b6a520bf2be4b4550b251095703 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 21 Aug 2013 13:50:20 +0200 Subject: Correct the specifications of io_lib:fread/2,3 Thanks to Chris King and Kostis Sagonas for pinpointing the bug. --- lib/stdlib/doc/src/io_lib.xml | 3 +++ 1 file changed, 3 insertions(+) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 3dac259477..68352ffeb1 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -53,6 +53,9 @@ + + + -- cgit v1.2.3 From 8e7441c27485bd416abdb0253c9c92620d671065 Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Tue, 6 May 2014 10:34:07 +0200 Subject: Make the scanned form of the io_lib format strings available for processing This adds three new functions to io_lib - scan_format/2, unscan_format/1, and build_text/1 - which expose the parsed form of the format control sequences to make it possible to easily modify or filter the input to io_lib:format/2. This can e.g. be used in order to replace unbounded-size control sequences like ~w or ~p with corresponding depth-limited ~W and ~P before doing the actual formatting. --- lib/stdlib/doc/src/io_lib.xml | 70 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 3312b08064..2117d66381 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -4,7 +4,7 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -59,6 +59,35 @@ + + +

Description:

+ +

control_char is the type of control + sequence: $P, $w, and so on;

+ +

args is a list of the arguments used by the + control sequence, or an empty list if the control sequence + does not take any arguments;

+ +

width is the field width;

+ +

adjust is the adjustment;

+ +

precision is the precision of the printed + argument;

+ +

pad_char is the padding character;

+ +

encoding is set to true if the translation + modifier t is present;

+ +

strings is set to false if the modifier + l is present.

+ + + + @@ -259,6 +288,45 @@ constant in the ISO-latin-1 character set.

 + + + Parse all control sequences in the format string + +

Returns a list corresponding to the given format string, + where control sequences have been replaced with + corresponding tuples. This list can be passed to io_lib:build_text/1 to have + the same effect as io_lib:format(Format, Args), or to + io_lib:unscan_format/1 + in order to get the corresponding pair of Format and + Args (with every * and corresponding argument + expanded to numeric values).

+

A typical use of this function is to replace unbounded-size + control sequences like ~w and ~p with the + depth-limited variants ~W and ~P before + formatting to text, e.g. in a logger.

+ + + + + Revert a pre-parsed format list to a plain character list + and a list of arguments + +

See io_lib:scan_format/2 for + details.

+ + + + + Build the output text for a pre-parsed format list + +

See io_lib:scan_format/2 for + details.

+ + Indentation after printing string -- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- lib/stdlib/doc/src/io_lib.xml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 2117d66381..cd58090dcd 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -8,16 +8,17 @@ Ericsson AB. All Rights Reserved. - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. -- cgit v1.2.3 From 6664eed554974336909d3ffe03f20349cc4c38fd Mon Sep 17 00:00:00 2001 From: Henrik Nord Date: Tue, 15 Mar 2016 15:19:56 +0100 Subject: update copyright-year --- lib/stdlib/doc/src/io_lib.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index cd58090dcd..b22ec15a0c 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -4,7 +4,7 @@
- 19962014 + 19962016 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/io_lib.xml | 400 +++++++++++++++++++++++------------------- 1 file changed, 221 insertions(+), 179 deletions(-) (limited to 'lib/stdlib/doc/src/io_lib.xml') diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index b22ec15a0c..931e50f6f2 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -29,14 +29,16 @@
io_lib - IO Library Functions + I/O library functions.

This module contains functions for converting to and from strings (lists of characters). They are used for implementing the - functions in the io module. There is no guarantee that the + functions in the io module. + There is no guarantee that the character lists returned from some of the functions are flat, - they can be deep lists. lists:flatten/1 can be used for - flattening deep lists.

+ they can be deep lists. Function + lists:flatten/1 + can be used for flattening deep lists.

 @@ -45,7 +47,8 @@ -

A continuation as returned by fread/3.

+

A continuation as returned by + fread/3.

 @@ -62,338 +65,377 @@ -

Description:

+

Where:

control_char is the type of control - sequence: $P, $w, and so on;

+ sequence: $P, $w, and so on.

args is a list of the arguments used by the control sequence, or an empty list if the control sequence - does not take any arguments;

+ does not take any arguments.

 -

width is the field width;

+

width is the field width.

 -

adjust is the adjustment;

+

adjust is the adjustment.

precision is the precision of the printed - argument;

+ argument.

 -

pad_char is the padding character;

+

pad_char is the padding character.

 -

encoding is set to true if the translation - modifier t is present;

+

encoding is set to true if translation + modifier t is present.

 -

strings is set to false if the modifier +

strings is set to false if modifier l is present.

 + - - Write a newline + + Build the output text for a preparsed format list. -

Returns a character list which represents a new line - character.

+

For details, see + scan_format/2.

 + - - - Write a term + + Test for a list of characters. -

Returns a character list which represents Term. The - Depth (-1) argument controls the depth of the - structures written. When the specified depth is reached, - everything below this level is replaced by "...". For - example:

- 
-1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
-"{1,[2],[3],[4,5],6,7,8,9}"
-2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
-"{1,[2],[3],[...],...}"
+

Returns true if Term is a flat list of + characters in the Unicode range, otherwise false.

 + - - - Pretty print a term + + Test for a deep list of characters. -

Also returns a list of characters which represents - Term, but breaks representations which are longer than - one line into many lines and indents each line sensibly. It - also tries to detect and output lists of printable characters - as strings. Column is the starting column (1), - LineLength the maximum line length (80), and - Depth (-1) the maximum print depth.

+

Returns true if Term is a, possibly deep, + list of characters in the Unicode range, otherwise false.

 + - - - Write formatted output + + Test for a deep list of characters. -

Returns a character list which represents Data - formatted in accordance with Format. See - io:fwrite/1,2,3 for a detailed - description of the available formatting options. A fault is - generated if there is an error in the format string or - argument list.

+

Returns true if Term is a, possibly deep, + list of characters in the ISO Latin-1 range, otherwise + false.

+ + -

If (and only if) the Unicode translation modifier is used - in the format string (i.e. ~ts or ~tc), the resulting list - may contain characters beyond the ISO-latin-1 character - range (in other words, numbers larger than 255). If so, the - result is not an ordinary Erlang string(), but can well be - used in any context where Unicode data is allowed.

- + + + + Write formatted output. + +

Returns a character list that represents Data + formatted in accordance with Format. + For a detailed description of the available formatting options, see + io:fwrite/1,2,3. + If the format string or argument list contains an error, a fault is + generated.

+

If and only if the Unicode translation modifier is used in the + format string (that is, ~ts or ~tc), the resulting list + can contain characters beyond the ISO Latin-1 character range + (that is, numbers > 255). If so, the + result is not an ordinary Erlang string(), but can well be + used in any context where Unicode data is allowed.

 + - Read formatted input + Read formatted input. -

Tries to read String in accordance with the control - sequences in Format. See - io:fread/3 for a detailed - description of the available formatting options. It is - assumed that String contains whole lines. It returns:

+

Tries to read String in accordance with the + control sequences in Format. + For a detailed description of the available formatting options, see + io:fread/3. It is + assumed that String contains whole lines.

+

The function returns:

- {ok, InputList, LeftOverChars} + {ok, InputList, + LeftOverChars} -

The string was read. InputList is the list of - successfully matched and read items, and - LeftOverChars are the input characters not used.

+

The string was read. InputList is the list + of successfully matched and read items, and + LeftOverChars are the input characters not + used.

 - {more, RestFormat, Nchars, InputStack} + {more, RestFormat, Nchars, + InputStack} -

The string was read, but more input is needed in order - to complete the original format string. RestFormat - is the remaining format string, Nchars the number +

The string was read, but more input is needed to complete the + original format string. RestFormat is the + remaining format string, Nchars is the number of characters scanned, and InputStack is the reversed list of inputs matched up to that point.

 {error, What} -

The read operation failed and the parameter What +

The read operation failed and parameter What gives a hint about the error.

 -

Example:

+

Example:

 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
 {ok,[15.6,1.73e-5,24.5],[]}
 + Re-entrant formatted reader

This is the re-entrant formatted reader. The continuation of - the first call to the functions must be []. Refer to - Armstrong, Virding, Williams, 'Concurrent Programming in - Erlang', Chapter 13 for a complete description of how the - re-entrant input scheme works.

+ the first call to the functions must be []. For a complete + description of how the re-entrant input scheme works, see + Armstrong, Virding, Williams: 'Concurrent Programming in + Erlang', Chapter 13.

The function returns:

- {done, Result, LeftOverChars} + {done, Result, + LeftOverChars} -

The input is complete. The result is one of the - following:

+

The input is complete. The result is one of the following:

{ok, InputList} -

The string was read. InputList is the list of - successfully matched and read items, and - LeftOverChars are the remaining characters.

+

The string was read. InputList is the + list of successfully matched and read items, and + LeftOverChars are the remaining + characters.

 eof -

End of file has been encountered. +

End of file was encountered. LeftOverChars are the input characters not used.

 {error, What} -

An error occurred and the parameter What gives - a hint about the error.

+

An error occurred and parameter What + gives a hint about the error.

 {more, Continuation}

More data is required to build a term. - Continuation must be passed to fread/3, + Continuation must be passed to fread/3 when more data becomes available.

 + - - Write an atom + + Indentation after printing string. -

Returns the list of characters needed to print the atom - Atom.

+

Returns the indentation if String has been + printed, starting at StartIndent.

 + - - Write a string + + Test for a list of ISO Latin-1 characters. -

Returns the list of characters needed to print - String as a string.

+

Returns true if Term is a flat list of + characters in the ISO Latin-1 range, otherwise false.

 + - - Write a string + + Write a newline. -

Returns the list of characters needed to print - String as a string. Non-Latin-1 - characters are escaped.

+

Returns a character list that represents a new line character.

 + - - Write an ISO-latin-1 string + + + Pretty print a term. -

Returns the list of characters needed to print - Latin1String as a string.

+

Returns a list of characters that represents + Term, but breaks representations longer + than one line into many lines and indents each line sensibly. + Also tries to detect and output lists of printable characters + as strings.

+ + Column is the starting column; defaults + to 1. + LineLength is the maximum line length; + defaults to 80. + Depth is the maximum print depth; + defaults to -1, which means no limitation. + + - - Write a character + + Test for a list of printable ISO Latin-1 characters. -

Returns the list of characters needed to print a character - constant in the Unicode character set.

+

Returns true if Term is a flat list of + printable ISO Latin-1 characters, otherwise false.

 + - - Write a character + + Test for a list of printable characters. -

Returns the list of characters needed to print a character - constant in the Unicode character set. Non-Latin-1 characters - are escaped.

+

Returns true if Term is a flat list of + printable characters, otherwise false.

+

What is a printable character in this case is determined by + startup flag +pc to the Erlang VM; see + + io:printable_range/0 and + erl(1).

 + - - Write an ISO-latin-1 character + + Test for a list of printable Unicode characters. -

Returns the list of characters needed to print a character - constant in the ISO-latin-1 character set.

+

Returns true if Term is a flat list of + printable Unicode characters, otherwise false.

 + - Parse all control sequences in the format string + Parse all control sequences in the format string. -

Returns a list corresponding to the given format string, +

Returns a list corresponding to the specified format string, where control sequences have been replaced with - corresponding tuples. This list can be passed to io_lib:build_text/1 to have - the same effect as io_lib:format(Format, Args), or to - io_lib:unscan_format/1 - in order to get the corresponding pair of Format and - Args (with every * and corresponding argument - expanded to numeric values).

+ corresponding tuples. This list can be passed to:

+ + +

build_text/1 + to have the same effect as format(Format, Args)

+ + +

+ unscan_format/1 to get the corresponding pair + of Format and Args (with every * and + corresponding argument expanded to numeric values)

+ +

A typical use of this function is to replace unbounded-size control sequences like ~w and ~p with the depth-limited variants ~W and ~P before - formatting to text, e.g. in a logger.

+ formatting to text in, for example, a logger.

 + - Revert a pre-parsed format list to a plain character list - and a list of arguments - -

See io_lib:scan_format/2 for - details.

- - - - - Build the output text for a pre-parsed format list + Revert a preparsed format list to a plain character list + and a list of arguments. -

See io_lib:scan_format/2 for - details.

+

For details, see + scan_format/2.

 + - - Indentation after printing string + + + Write a term. -

Returns the indentation if String has been printed, - starting at StartIndent.

+

Returns a character list that represents Term. + Argument Depth controls the depth of the + structures written. When the specified depth is reached, + everything below this level is replaced by "...". + Depth defaults to -1, which means + no limitation.

+

Example:

+ 
+1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
+"{1,[2],[3],[4,5],6,7,8,9}"
+2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
+"{1,[2],[3],[...],...}"
 + - - Test for a list of characters + + Write an atom. -

Returns true if Term is a flat list of - characters in the Unicode range, otherwise it returns false.

+

Returns the list of characters needed to print atom + Atom.

 + - - Test for a list of ISO-latin-1 characters + + Write a character. -

Returns true if Term is a flat list of - characters in the ISO-latin-1 range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the Unicode character set.

 + - - Test for a deep list of characters + + Write a character. -

Returns true if Term is a, possibly deep, list - of characters in the Unicode range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the Unicode character set. Non-Latin-1 characters + are escaped.

 + - - Test for a deep list of characters + + Write an ISO Latin-1 character. -

Returns true if Term is a, possibly deep, list - of characters in the ISO-latin-1 range, otherwise it returns false.

+

Returns the list of characters needed to print a character + constant in the ISO Latin-1 character set.

 + - - Test for a list of printable characters + + Write an ISO Latin-1 string. -

Returns true if Term is a flat list of - printable characters, otherwise it returns false.

-

What is a printable character in this case is determined by the - +pc start up flag to the Erlang VM. See - io:printable_range/0 - and erl(1).

+

Returns the list of characters needed to print + Latin1String as a string.

 + - - Test for a list of printable ISO-latin-1 characters + + Write a string. -

Returns true if Term is a flat list of - printable ISO-latin-1 characters, otherwise it returns false.

+

Returns the list of characters needed to print + String as a string.

 + - - Test for a list of printable Unicode characters + + Write a string. -

Returns true if Term is a flat list of - printable Unicode characters, otherwise it returns false.

+

Returns the list of characters needed to print + String as a string. Non-Latin-1 + characters are escaped.

 -- cgit v1.2.3