[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Console Input/Output (Text_IO)

The Text_IO package handles reading and writing to the console (or UNIX tty device) and text files. The package name "text_io" should be omitted when invoking these subroutines.

GCC Ada Equivalent: Ada.Text_IO

Files are opened using file_type variables.

The predefined enumerated type file_mode determines if a file will be read (in_file), written to (out_file) or appended to (append_file). If a file is appended to, it should already exist.

There are several predefined file_type constants: standard_input, standard_output and standard_error can be used to redirect I/O to your operating system's standard input, output or error respectively.

There are also three file_type aliases. These can be used anywhere a file_type variable is expected.

  • current_input -- an alias for the current input file
  • current_output-- an alias for the current output file
  • current_error -- an alias for the current error file

The current aliases can be redirected using set_output or related procedures.

=> set_output( f )

From now on, all output going to standard output is written to the file_type variable f. The current_output function refers to the file being written to (in this case, f). Output redirected to f is not counted by the line function.

The put, put_line, get, get_line and new_line commands are used to read and write files.

=> f : file_type
=> create( f, out_file, "data.out" )
=> put_line( f, "Added to file" )
=> ? name( f )
data.out
=> ? mode( f )
out_file
=> ? line( f )
1
=> close( f )
 
Example: Writing to a text file

 

? e (question mark command)

 

Display expression e to current output. If appropriate, removes the decimal part of the expression (i.e. 41.0 will be displayed as 41) so as more human-friendly. If f is specified, writes to the file f instead of current_output. The expression type can be a string type, a numeric type or an enumerated type. Limited types are not allowed.

Example

? 3*2; -- displays 6

Parameters

Param Mode Type Default Description
e in not limited required the expression to write

Exceptions

-

Restrictions

Not allowed with pragma ada_95

See Also

put
put_line

Compare With

BASIC: ?
PHP: = (in a short open tag)

Rationale

Provided as a command prompt convenience.

close( f )

 

Close and save the open file f

Example

close( data );

Parameters

Param Mode Type Default Description
f in out file_type required file variable representing the file to close

Exceptions

If the file is not opened an exception will be raised

See Also

delete
is_open

Compare With

Ada: Ada.Text_IO.Close
PHP: fclose

create( f [, m] [, n] )

 

Create a new file or open an existing file for writing. If no path is specified, create a new temporary file. The mode cannot be in_file.

Example

create( temp_file );

Parameters

Param Mode Type Default Description
f out file_type required file variable representing the open file
m in file_mode out_file open the file writing or appending
n in string random temp file the pathname of the file to create

Exceptions

If the file cannot be opened an exception will be raised

Restrictions

out_mode not allowed in a restricted shell

See Also

close
is_open
open
reset

Compare With

Ada: Ada.Text_IO.Create
PHP: tmpfile

delete( f )

 

Close and delete the open file f

Example

delete( temp_file );

Parameters

Param Mode Type Default Description
f in out file_type required file variable representing the file to delete

Exceptions

If the file is not opened an exception will be raised

See Also

close
is_open

Compare With

Ada: Ada.Text_IO.Delete
PHP: unlink

end_of_file( f )

 

Return true if all data has been read from in_file mode file f

Example

if end_of_file( data ) then ...

Parameters

Param Mode Type Default Description
f in file_type required file variable representing the file to test

Exceptions

An exception will be raised if the file is not open or has the wrong mode

See Also

-

Compare With

Ada: Ada.Text_IO.End_Of_File
PHP: feof

end_of_line( f )

 

Return true if at the end of line for file f

Example

if end_of_line( data ) then ...

Parameters

Param Mode Type Default Description
f in file_type required file variable representing the file to test

Exceptions

-

See Also

-

Compare With

Ada: Ada.Text_IO.End_Of_Line

get( [f,] c )

 

Read the first character from a line on standard input and return it as c. End-of-line charcters are not returned.

Example

get( ch );

Parameters

Param Mode Type Default Description
f in file_type standard_input the file to read input from
c out character required the character read

Exceptions

Reading past end of file will raise an exception

See Also

end_of_file
end_of_line
get_line
inkey
skip_line

Compare With

Ada: Ada.Text_IO.Get_Line, Ada.Strings.Unbounded.Text_IO.Get
PHP: fgetc

get_immediate( c, [b] )

 

Read the first character from a line on standard input and return it as c. Don't display the character. Return immediately if there's no data when b is true.

Example

get_immediate( ch );

Parameters

Param Mode Type Default Description
c out character required the character read
b in boolean false true to return immediately

Exceptions

Reading past end of file will raise an exception

See Also

end_of_file
end_of_line
get_line
inkey
skip_line

Compare With

Ada: Ada.Text_IO.Get_Immediate

Implementation Note

This function is incomplete. It was introduced in SparForte 1.5
Displaying the character is turned off when get_immediate is executed so if a user types a character before get_immediate is executed, it will still appear.

s := get_line [( f )]

 

Read a string until the end of line is encountered. If f is specified, read from file f instead of current_input. End-of-line characters are not returned. To read a numeric value, convert the string value to a numeric value with numerics.value and typecast it if necessary.

Example

s := get_line;

Parameters

Param Mode Type Default Description
f in file_type standard_input the file to read input from
s return value string required the string that was read

Exceptions

Reading past end of file will raise an exception

See Also


end_of_file
end_of_line
get
inkey
skip_line

Compare With

Ada: Ada.Text_IO.Get_Line / Ada.Strings.Unbounded.Text_IO.Get_Line
PHP: fgets

c := inkey

 

Read a character from current_input. It does not write the character back to current_output.

Example

ch := inkey;

Parameters

Param Mode Type Default Description
c return value character required the key that was pressed

Exceptions

-

See Also

-

Compare With

BASIC: inkey$

Rationale

get is provided for compatibility for Ada 95 but get is not very convenient. inkey is a more useful function for reading a keypress.

is_open( f )

 

Return true if file f is open

Example

if is_open( data ) then ...

Parameters

Param Mode Type Default Description
f in file_type required file variable representing the file to test

Exceptions

-

See Also

-

Compare With

Ada: Ada.Text_IO.Is_Open

i := line( f )

 

Return the number of lines read or written to file f (with put_line, the number of lines explicitly put to that file). This function will work with standard_input, standard_output and standard_error. However, it does not take into account lines read or written by operating system commands.

Example

if line( f ) > 33 then ...

Parameters

Param Mode Type Default Description
i return value integer required the number of lines read or written
f in file_type required file variable representing the file to test

Exceptions

An exception will be raised if the file is not open

See Also

mode
name

Compare With

Ada: Ada.Text_IO.Line

m := mode( f )

 

Return the mode of the open file. This function will work with standard_input, standard_output and standard_error.

Example

if mode( f ) = in_file then ...

Parameters

Param Mode Type Default Description
m return value file_mode required the current mode of the file
f in file_type required file variable representing the file

Exceptions

An exception will be thrown if the file is not open

See Also

line
name

Compare With

Ada: Ada.Text_IO.Mode

s := name( f )

 

Return the pathname of the open file. This function will work with standard_input, standard_output and standard_error. However, it does not return a pathname since these files have no known pathnames.

Example

put_line( "error in file " & name( f ) );

Parameters

Param Mode Type Default Description
s return value string required the pathname of the file
f in file_type required file variable representing the file

Exceptions

An exception will be raised if the file is not open

See Also

line
mode

Compare With

Ada: Ada.Text_IO.Name

new_line [(f)]

 

Write a line feed (new line). If f is specified, writes to the file f instead of current_output.

Example

new_line;

Parameters

Param Mode Type Default Description
f in file_type standard_output file to redirect output to

Exceptions

If the new line cannot be written an exception will be raised

See Also

? (question mark command)
skip_line

Compare With

Ada: Ada.Text_IO.New_Line
PHP: echo

open( f, m, p )

 

Open existing file f as pathname p in file mode m.

Example

open( data, in_file, "/home/ken/data.txt" );

Parameters

Param Mode Type Default Description
f out file_type required file variable representing the open file
m in file_mode required open the file for reading, writing or appending
p in string required the pathname of the file to open

Exceptions

If the file cannot be opened an exception will be raised

See Also

close
create
is_open
reset

Compare With

Ada: Ada.Text_IO.Open
PHP: fopen

put( [f,] e [, p] )

 

Write expression e with optional numeric formatting. The expression type can be a string type, a numeric type or an enumerated type. Limited types are not allowed. If f is specified, writes to the file f instead of current_output. If picture string p is used, formats a numeric value according to the picture as described in Numeric Formatting with Put in the reference section.

Example

put( 3*2 ); -- displays 6.0E+00
put( 3*2, "9999" ); -- displays 0006

Parameters

Param Mode Type Default Description
f in file_type standard_output the file to direct output to
e in not limited required the expression to write
p in string none format picture to write with

Exceptions

If the value cannot be written an exception will be raised
If the value does not fit the picture an exception will be raised

See Also

? (question mark command)
put_line

Compare With

Ada: Ada.Text_IO.Put / Ada.Strings.Unbounded.Text_IO.Put / Ada.Text_IO.Editing / etc.
PHP: printf / fprintf

put_line( [f,] e )

 

Write expression e with an appended line feed (new line) character. The expression type can be a string type, a numeric type or an enumerated type. Limited types are not allowed. If f is specified, writes to the file f instead of current_output.

Example

put_line( 3*2 );
put_line( true or false );
put_line( standard_error, "an error message" );

Parameters

Param Mode Type Default Description
f in file_type standard_output file to direct output to
e in not limited required the expressions to write

Exceptions

If the value cannot be written an exception will be raised

See Also

? (question mark command)
put
new_line

Compare With

Ada: Ada.Text_IO.Put_Line / Ada.Strings.Unbounded.Text_IO.Put_Line / etc.
PHP: echo

reset( f [, m] )

 

Reopen open file f in optional new file mode m

Example

reset( temp_file, in_file );

Parameters

Param Mode Type Default Description
f in out file_type required file variable representing the file to reopen
m in file_mode current mode the new mode for the file

Exceptions

An exception will be raised if the file cannot be opened in the new mode

Restrictions

out_mode not allowed in a restricted shell

See Also

create
open

Compare With

Ada: Ada.Text_IO.Reset
PHP: rewind

set_error( f )

 

Redirect the current error file (usually standard_error) to another open file f. All future writes to current_error (put_line( current_error, ...), etc.) will use the new file. The new file must be an out_mode file. Use set_error( standard_error ) to return to standard error, or save the value of current_error and restore it later.

Example

set_error( log_file );

Parameters

Param Mode Type Default Description
f in file_type required the file to write error output to

Exceptions

If the file is not open or if it is the wrong mode, an exception will be raised

See Also

set_input
set_output

Compare With

Ada: Ada.Text_IO.Set_Error

set_input( f )

 

Redirect the current input (usually standard_input) to another open file f. All future reads (get, get_line, etc.) will use the new file. The new file must be an in_file mode file. Use set_input( standard_input ) to return to standard input, or save the value of current_input and restore it later.

Example

set_input( data_file );

Parameters

Param Mode Type Default Description
f in file_type required the file to read input from

Exceptions

If the file is not open or if it is the wrong mode, an exception will be raised

See Also

set_error
set_output

Compare With

Ada: Ada.Text_IO.Set_Input

set_output( f )

 

Redirect the current output (usually standard_output) to another open file f. All future writes (put, put_line, etc.) will use the new file. The new file must be an out_mode file. Use set_output( standard_output ) to return to standard output, or save the value of current_output and restore it later.

Example

set_output( data_file );

Parameters

Param Mode Type Default Description
f in file_type required the file to write output to

Exceptions

If the file is not open or if it is the wrong mode, an exception will be raised

See Also

set_input
set_error

Compare With

Ada: Ada.Text_IO.Set_Output

skip_line( [f] )

 

Read a line from standard input and discard it

Example

skip_line;

Parameters

Param Mode Type Default Description
f in file_type standard_input the file to read input from

Exceptions

If the new line cannot be read or it is the end of file, an exception will be raised

See Also

get
get_line

Compare With

Ada: Ada.Text_IO.Skip_Line

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]