From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/io.xml | 354 ++++++++++++++++++---------------------------- 1 file changed, 137 insertions(+), 217 deletions(-) (limited to 'lib/stdlib/doc/src/io.xml') diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index 41e3e92c59..af9c75d546 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -43,7 +43,7 @@

As of R13A, data supplied to the put_chars function should be in the - chardata() format described below. This means that programs + unicode:chardata() format. This means that programs supplying binaries to this function need to convert them to UTF-8 before trying to output the data on an io_device().

@@ -64,76 +64,84 @@ -
- DATA TYPES - -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() + + + + +

Either standard_io, standard_error, a + registered name, or a pid handling IO protocols (returned from + file:open/2).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Whatever the I/O-server sends.

 + + -charlist() = [unicode_char() | unicode_binary() | charlist()] - a unicode_binary is allowed as the tail of the list -
- columns() -> {ok,int()} | {error, enotsup} - columns(IoDevice) -> {ok,int()} | {error, enotsup} + + Get the number of columns of a device - - IoDevice = io_device() -

Retrieves the number of columns of the - IoDevice (i.e. the width of a terminal). The function + IoDevice (i.e. the width of a terminal). The function only succeeds for terminal devices, for all other devices the function returns {error, enotsup}

 - put_chars(IoData) -> ok - put_chars(IoDevice, IoData) -> ok + + Write a list of characters - - IoDevice = io_device() - IoData = chardata() - -

Writes the characters of IoData to the io_server() - (IoDevice).

+

Writes the characters of CharData to the io_server() + (IoDevice).

 - nl() -> ok - nl(IoDevice) -> ok + + Write a newline - - IoDevice = io_device() - -

Writes new line to the standard output (IoDevice).

+

Writes new line to the standard output (IoDevice).

 - get_chars(Prompt, Count) -> Data | eof - get_chars(IoDevice, Prompt, Count) -> Data | eof + + Read a specified number of characters - - IoDevice = io_device() - Prompt = atom() | string() - Count = int() - Data = [ unicode_char() ] | unicode_binary() - -

Reads Count characters from standard input - (IoDevice), prompting it with Prompt. It +

Reads Count characters from standard input + (IoDevice), prompting it with Prompt. It returns:

- Data + Data

The input characters. If the device supports Unicode, the data may represent codepoints larger than 255 (the @@ -145,7 +153,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

End of file was encountered.

 - {error,Reason} + {error,Reason}

Other (rare) error condition, for instance {error,estale} if reading from an NFS file system.

@@ -154,19 +162,14 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] - get_line(Prompt) -> Data | eof | {error,Reason} - get_line(IoDevice, Prompt) -> Data | eof | {error,Reason} + + Read a line - - IoDevice = io_device() - Prompt = atom() | string() - Data = [ unicode_char() ] | unicode_binary() - -

Reads a line from the standard input (IoDevice), - prompting it with Prompt. It returns:

+

Reads a line from the standard input (IoDevice), + prompting it with Prompt. It returns:

- Data + Data

The characters in the line terminated by a LF (or end of file). If the device supports Unicode, @@ -179,7 +182,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

End of file was encountered.

 - {error,Reason} + {error,Reason}

Other (rare) error condition, for instance {error,estale} if reading from an NFS file system.

@@ -188,15 +191,9 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] - getopts() -> Opts - getopts(IoDevice) -> Opts + + Get the supported options and values from an I/O-server - - IoDevice = io_device() - Opts = [Opt] -   Opt = {atom(),Value} -   Value = term() -

This function requests all available options and their current values for a specific io_device(). Example:

@@ -216,18 +213,11 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
       
     
     
-      setopts(Opts) -> ok | {error, Reason}
-      setopts(IoDevice, Opts) -> ok | {error, Reason}
+      
+      
       Set options
-      
-        IoDevice = io_device()
-        Opts = [Opt]
-          Opt = atom() | {atom(),Value}
-	  Value = term()
-        Reason = term()
-      
       
-        
Set options for the io_device() (IoDevice).

+        
Set options for the io_device() (IoDevice).

 
         
Possible options and values vary depending on the actual
         io_device(). For a list of supported options and their current values
@@ -236,17 +226,17 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
 
 	
The options and values supported by the current OTP io_devices are:

         
-          binary, list or {binary, bool()}
+          binary, list or {binary, boolean()}
           
             
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 get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead of lists of chars for the affected device.

 	    
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.

           
-          {echo, bool()}
+          {echo, boolean()}
 	  
 	  
Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (group.erl)

 	  
-          {expand_fun, fun()}
+          {expand_fun, expand_fun()}
           
             
Provide a function for tab-completion (expansion)
               like the erlang shell. This function is called
@@ -288,35 +278,24 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
       
     
     
-      write(Term) -> ok
-      write(IoDevice, Term) -> ok
+      
+      
       Write a term
-      
-        IoDevice = io_device()
-        Term = term()
-      
       
-        
Writes the term Term to the standard output
-          (IoDevice).

+        
Writes the term Term to the standard output
+          (IoDevice).

       
     
     
-      read(Prompt) -> Result
-      read(IoDevice, Prompt) -> Result
+      
+      
       Read a term
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        Result = {ok, Term} | eof | {error, ErrorInfo}
-         Term = term()
-         ErrorInfo -- see section Error Information below
-      
       
-        
Reads a term Term from the standard input
-          (IoDevice), prompting it with Prompt. It
+        
Reads a term Term from the standard input
+          (IoDevice), prompting it with Prompt. It
           returns:

         
-          {ok, Term}
+          {ok, Term}
           
             
The parsing was successful.

           
@@ -324,7 +303,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
           
             
End of file was encountered.

           
-          {error, ErrorInfo}
+          {error, ErrorInfo}
           
             
The parsing failed.

           
@@ -332,31 +311,22 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
       
     
     
-      read(IoDevice, Prompt, StartLine) -> Result
+      
       Read a term
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        StartLine = int()
-        Result = {ok, Term, EndLine} | {eof, EndLine} |  {error, ErrorInfo, EndLine}
-         Term = term()
-         EndLine = int()
-         ErrorInfo -- see section Error Information below
-      
       
-        
Reads a term Term from IoDevice, prompting it
-          with Prompt. Reading starts at line number
-          StartLine. It returns:

+        
Reads a term Term from IoDevice, prompting it
+          with Prompt. Reading starts at line number
+          StartLine. It returns:

         
-          {ok, Term, EndLine}
+          {ok, Term, EndLine}
           
             
The parsing was successful.

           
-          {eof, EndLine}
+          {eof, EndLine}
           
             
End of file was encountered.

           
-          {error, ErrorInfo, EndLine}
+          {error, ErrorInfo, ErrorLine}
           
             
The parsing failed.

           
@@ -364,24 +334,19 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
       
     
     
-      fwrite(Format) ->
-      fwrite(Format, Data) -> ok
-      fwrite(IoDevice, Format, Data) -> ok
-      format(Format) ->
-      format(Format, Data) -> ok
-      format(IoDevice, Format, Data) -> ok
+      
+      
+      
+      
+      
+      
       Write formatted output
-      
-        IoDevice = io_device()
-        Format = atom() | string() | binary()
-        Data = [term()]
-      
       
-        
Writes the items in Data ([]) on the standard
-          output (IoDevice) in accordance with Format.
-          Format contains plain characters which are copied to
+        
Writes the items in Data ([]) on the standard
+          output (IoDevice) in accordance with Format.
+          Format contains plain characters which are copied to
           the output device, and control sequences for formatting, see
-          below. If Format is an atom or a binary, it is first 
+          below. If Format is an atom or a binary, it is first
           converted to a list with the aid of atom_to_list/1
           or binary_to_list/1.

         
@@ -474,7 +439,7 @@ ok

           
             
Prints the argument with the string syntax. The
               argument is, if no Unicode translation modifier is present, an 
-	      I/O list, a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is chardata(), meaning that binaries are in UTF-8. The characters
+	      I/O list, a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is unicode:chardata(), meaning that binaries are in UTF-8. The characters
               are printed without quotes. The string is first truncated
 	      by the given precision and then padded and justified
 	      to the given field width. The default precision is the field width.

@@ -673,23 +638,15 @@ ok
       
     
     
-      fread(Prompt, Format) -> Result
-      fread(IoDevice, Prompt, Format) -> Result
+      
+      
       Read formatted input
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        Format = string()
-        Result = {ok, Terms} | eof | {error, What}
-         Terms = [term()]
-         What = term()
-      
       
-        
Reads characters from the standard input (IoDevice),
-          prompting it with Prompt. Interprets the characters in
-          accordance with Format. Format contains control
+        
Reads characters from the standard input (IoDevice),
+          prompting it with Prompt. Interprets the characters in
+          accordance with Format. Format contains control
           sequences which directs the interpretation of the input.

-        
Format may contain:

+        
Format may contain:

         
           
             
White space characters (SPACE, TAB and NEWLINE) which
@@ -803,19 +760,19 @@ Prompt> <Character beyond latin1 range not printable in this medium>
             
             
It returns:

             
-              {ok, Terms}
+              {ok, Terms}
               
-                
The read was successful and Terms is the list
+                
The read was successful and Terms is the list
                   of successfully matched and read items.

               
               eof
               
                 
End of file was encountered.

               
-              {error, What}
+              {error, What}
               
                 
The read operation failed and the parameter
-                  What gives a hint about the error.

+                  What gives a hint about the error.

               
             
           
@@ -834,33 +791,21 @@ enter>:   alan   :   joe
     
     
-      rows() -> {ok,int()} | {error, enotsup}
-      rows(IoDevice) -> {ok,int()} | {error, enotsup}
+      
+      
       Get the number of rows of a device
-      
-        IoDevice = io_device()
-      
       
           
Retrieves the number of rows of the 
-          IoDevice (i.e. the height of a terminal). The function
+          IoDevice (i.e. the height of a terminal). The function
           only succeeds for terminal devices, for all other devices
           the function returns {error, enotsup}

       
     
     
-      scan_erl_exprs(Prompt) ->
-      scan_erl_exprs(Prompt, StartLine) -> Result
-      scan_erl_exprs(IoDevice, Prompt, StartLine) -> Result
+      
+      
+      
       Read and tokenize Erlang expressions
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        StartLine = int()
-        Result = {ok, Tokens, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine}
-         Tokens -- see erl_scan(3)
-         EndLine = int()
-         ErrorInfo -- see section Error Information below
-      
       
         
Reads data from the standard input (IoDevice),
           prompting it with Prompt. Reading starts at line number
@@ -876,7 +821,7 @@ enter>:   alan   :   joe
             
End of file was encountered.

           
-          {error, ErrorInfo, EndLine}
+          {error, ErrorInfo, ErrorLine}
           
             
An error occurred.

           
@@ -892,23 +837,14 @@ enter>1.0er.
       
     
     
-      scan_erl_form(Prompt) ->
-      scan_erl_form(Prompt, StartLine) -> Result
-      scan_erl_form(IoDevice, Prompt, StartLine) -> Result
+      
+      
+      
       Read and tokenize an Erlang form
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        StartLine = int()
-        Result = {ok, Tokens, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine}
-         Tokens -- see erl_scan(3)
-         EndLine = int()
-         ErrorInfo -- see section Error Information below
-      
       
-        
Reads data from the standard input (IoDevice),
-          prompting it with Prompt. Starts reading at line number
-          StartLine (1). The data is tokenized as if it were an
+        
Reads data from the standard input (IoDevice),
+          prompting it with Prompt. Starts reading at line number
+          StartLine (1). The data is tokenized as if it were an
           Erlang form - one of the valid Erlang expressions in an
           Erlang source file - until a final '.' is reached.
           This last token is also returned. The return values are the
@@ -916,27 +852,19 @@ enter>1.0er.
       
     
     
-      parse_erl_exprs(Prompt) ->
-      parse_erl_exprs(Prompt, StartLine) -> Result
-      parse_erl_exprs(IoDevice, Prompt, StartLine) -> Result
+      
+      
+      
+      
       Read, tokenize and parse Erlang expressions
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        StartLine = int()
-        Result = {ok, Expr_list, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine}
-         Expr_list -- see erl_parse(3)
-         EndLine = int()
-         ErrorInfo -- see section Error Information below
-      
       
-        
Reads data from the standard input (IoDevice),
-          prompting it with Prompt. Starts reading at line number
-          StartLine (1). The data is tokenized and parsed as if
+        
Reads data from the standard input (IoDevice),
+          prompting it with Prompt. Starts reading at line number
+          StartLine (1). The data is tokenized and parsed as if
           it were a sequence of Erlang expressions until a final '.' is
           reached. It returns:

         
-          {ok, Expr_list, EndLine}
+          {ok, ExprList, EndLine}
           
             
The parsing was successful.

           
@@ -944,7 +872,7 @@ enter>1.0er.
           
             
End of file was encountered.

           
-          {error, ErrorInfo, EndLine}
+          {error, ErrorInfo, ErrorLine}
           
             
An error occurred.

           
@@ -960,23 +888,15 @@ enter>abc("hey".
       
     
     
-      parse_erl_form(Prompt) ->
-      parse_erl_form(Prompt, StartLine) -> Result
-      parse_erl_form(IoDevice, Prompt, StartLine) -> Result
+      
+      
+      
+      
       Read, tokenize and parse an Erlang form
-      
-        IoDevice = io_device()
-        Prompt = atom() | string()
-        StartLine = int()
-        Result = {ok, AbsForm, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine}
-         AbsForm -- see erl_parse(3)
-         EndLine = int()
-         ErrorInfo -- see section Error Information below
-      
       
-        
Reads data from the standard input (IoDevice),
-          prompting it with Prompt. Starts reading at line number
-          StartLine (1). The data is tokenized and parsed as if
+        
Reads data from the standard input (IoDevice),
+          prompting it with Prompt. Starts reading at line number
+          StartLine (1). The data is tokenized and parsed as if
           it were an Erlang form - one of the valid Erlang expressions
           in an Erlang source file - until a final '.' is reached. It
           returns:

@@ -989,7 +909,7 @@ enter>abc("hey".
           
             
End of file was encountered.

           
-          {error, ErrorInfo, EndLine}
+          {error, ErrorInfo, ErrorLine}
           
             
An error occurred.

           
-- 
cgit v1.2.3