AdaCL.EAstrings.IO

More...

Entities

Constants and variables

Known_Line_Breaks
Native_Line_Breaks

Simple types

File_Mode
Line_Break_Array
Read_Stop_Cause

Access types

EAstream_Pointer
Line_Break_Pointer

Record types

Line_Break_Record

Tagged types

EAfile
EAstream
Stream_EAstream

Subprograms

Append_File
Get
Get_Line
In_File
New_Line
Out_File
Put
Put_Line
Skip_Line
Standard_Error
Standard_Input
Standard_Output

Dispatching subprograms

Close
Connect
Create
Delete
Encoding
End_Of_File
Finalize
Flush
Form
Get
Get
Get_Line
Get_Line
Initialize
Is_Open
Is_Open
Is_Open
Line_Break
Mode
Name
New_Line
Open
Put
Put_Line
Recognized_Line_Breaks
Reset
Reset
Reset
Set_Encoding
Set_Encoding
Set_Line_Break
Set_Recognized_Line_Breaks
Skip_Line
Stream
Stream
Stream

Description

This package provides encoding-aware output to and input from text files and text streams. Text streams are byte streams that can be read or written sequentially, and where the bytes constitute text encoded in some character encoding. They have no defined line length; line breaks are represented as characters in the stream. There is no concept of pages in this package. Each open stream has an associated character encoding. By default, streams are assumed to be encoded in the encoding that OS.OS_Encoding reports. Another encoding can be specified when the stream is opened or later. How line breaks are represented when writing and the set of line breaks that shall be recognized when reading can also be configured. In this package it is assumed that Ada.Streams.Stream_Element equals one byte, that is, eight bits.

Known_Line_Breaks [source]

441Known_Line_Breaks : constant Line_Break_Array :=
442 [(+[1 => LF], True),
443 (+[1 => CR], True),
444 (+[CR, LF], True),
445 (+[1 => NEL], True)];

Native_Line_Breaks [source]

423Native_Line_Breaks : constant array (Known_OS) of EAstring := [
424 Windows => +[CR, LF],
425 MacOS => +[CR, LF],
426 Linux => +[1 => LF]];

File_Mode [source]

250 subtype File_Mode is Stream_IO.File_Mode;

Line_Break_Array [source]

437 type Line_Break_Array is array (Integer range <>) of Line_Break_Record;

Read_Stop_Cause [source]

56 type Read_Stop_Cause is (All_Done, End_Of_File, Incomplete, Invalid);

Reason why Get or Get_Line returns. All_Done : The requested amount of data was read. End_Of_File : The end of the file was reached before the requested

1amount of data was read.

Incomplete : The file ended in an incomplete code sequence. Invalid : The file's content wasn't a valid encoded text for the

1file's encoding.
All_Done
End_Of_File
Incomplete
Invalid

EAstream_Pointer [source]

54 type EAstream_Pointer is access all EAstream'Class;

Line_Break_Pointer [source]

439 type Line_Break_Pointer is access all Line_Break_Array;

Line_Break_Record [source]

428 type Line_Break_Record is record
429 String : EAstring;
430 Possible : Boolean;
431 end record;

Used for line breaks to recognize when reading. Possible tells whether this line break can be expressed in the encoding that characters from the file are in when they are compared to the recognized line breaks (because if it can't, then this line break can't occur in the file).

String of type AdaCL.EAstrings.EAstring
Possible of type Boolean

EAfile [source]

247 type EAfile is new EAstream with private;

An EAfile reads from or writes to a named external file.

Inherits EAstream

EAstream [source]

53 type EAstream is abstract tagged limited private;

Inherits Limited_Controlled

Inherited by EAfile, Stream_EAstream

Stream_EAstream [source]

378 type Stream_EAstream is new EAstream with private;

A Stream_EAstream reads and writes through an object in Root_Stream_Type'Class, so that you can wrap an EAstream around anything that you can get a Stream_Access value for.

Inherits EAstream

Append_File [source]

253 function Append_File return File_Mode renames Stream_IO.Append_File;

Get [source]

187 procedure Get (Item : out EAstring; Length : in Natural);

Like above, but reads from Standard_Input.

Item of type AdaCL.EAstrings.EAstring
Length of type Natural

Get_Line [source]

217 procedure Get_Line (Item : out EAstring);

Like above, but reads from Standard_Input.

Item of type AdaCL.EAstrings.EAstring

In_File [source]

251 function In_File return File_Mode renames Stream_IO.In_File;

New_Line [source]

138 procedure New_Line (Spacing : in Positive := 1);

Like above, but writes to Standard_Output.

Spacing of type Positive

Out_File [source]

252 function Out_File return File_Mode renames Stream_IO.Out_File;

Put [source]

224 procedure Put (Item : in EAstring);

Like above, but writes to Standard_Output.

Item of type AdaCL.EAstrings.EAstring

Put_Line [source]

232 procedure Put_Line (Item : in EAstring);

Like above, but writes to Standard_Output.

Item of type AdaCL.EAstrings.EAstring

Skip_Line [source]

155 procedure Skip_Line (Spacing : in Positive := 1);

Like above, but reads from Standard_Input.

Spacing of type Positive

Standard_Error [source]

241 function Standard_Error return EAstream_Pointer;
Return value

Standard_Input [source]

239 function Standard_Input return EAstream_Pointer;
Return value

Standard_Output [source]

240 function Standard_Output return EAstream_Pointer;
Return value

Close [source]

302 procedure Close (File : in out EAfile);

Severs the association between the given EAfile and its associated external file. The EAfile is left closed. If the file being closed has mode Out_File or Append_File, then the last character written since the most recent open or reset is the last character that can be read from the file. If nothing has been written and the mode is Out_File, then the closed file is empty. If nothing has been written and the mode is Append_File, then the closed file is unchanged. Status_Error is propagated if the EAfile is not open.

File of type AdaCL.EAstrings.IO.EAfile

Connect [source]

387 procedure Connect
388 (File : in out Stream_EAstream;
389 Stream : in Stream_IO.Stream_Access;
390 Encoding : in Character_Encoding := OS.OS_Encoding);

Connects an EAstream object to an open byte stream and sets the character encoding to be used when reading from or writing to the stream.

File of type AdaCL.EAstrings.IO.Stream_EAstream
Stream of type Stream_Access
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Create [source]

259 procedure Create
260 (File : in out EAfile;
261 Name : in EAstring := Null_EAstring;
262 Encoding : in Character_Encoding := OS.OS_Encoding;
263 Form : in String := "");

Creates a new external file, with the given name and form, and associates this external file with the given EAfile. The EAfile is left open. The character encoding of the EAfile is set to the given encoding and its current mode is set to Out_File. A null string for Name specifies an external file that is not accessible after the completion of the main program (a temporary file). The valid values of Form are the same as for Ada.Streams.Stream_IO.Create; a null string specifies the default options for the external file. Status_Error is propagated if the EAfile is already open. Name_Error is propagated if the string given as Name does not allow the identification of an external file. Use_Error is propagated if the external environment does not support creation of an external file with the given name (in the absence of Name_Error) and form.

File of type AdaCL.EAstrings.IO.EAfile
Name of type AdaCL.EAstrings.EAstring
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Form of type String

Delete [source]

313 procedure Delete (File : in out EAfile);

Deletes the external file associated with the given EAfile. The EAfile is closed, and the external file ceases to exist. Status_Error is propagated if the EAfile is not open. Use_Error is propagated if deletion of the external file is not supported by the external environment.

File of type AdaCL.EAstrings.IO.EAfile

Encoding [source]

102 function Encoding (File : in EAstream) return Character_Encoding;

Returns the character encoding that the byte stream is currently interpreted as when reading from File, or that the text is currently encoded in when writing to File.

File of type AdaCL.EAstrings.IO.EAstream
Return value

End_Of_File [source]

73 function End_Of_File (File : in EAstream) return Boolean;

Returns True if the end of the file has been found, otherwise returns False. End_Of_File can't look ahead. It only returns True if Get or Get_Line has already encountered the end of the file. It is quite possible that the last character has already been read but End_Of_File returns False, because only the next read attempt will fail and report the end of the file.

File of type AdaCL.EAstrings.IO.EAstream
Return value

Finalize [source]

478 overriding procedure Finalize (Object : in out EAstream);
Object of type AdaCL.EAstrings.IO.EAstream

Flush [source]

369 procedure Flush (File : in EAfile);

Synchronizes the external file with the internal file (by flushing any internal buffers) without closing the file or changing the position. Mode_Error is propagated if the mode of the EAfile is In_File.

File of type AdaCL.EAstrings.IO.EAfile

Form [source]

361 function Form (File : in EAfile) return String;

Returns the form string for the external file currently associated with the given EAfile. Status_Error is propagated if the EAfile is not open.

File of type AdaCL.EAstrings.IO.EAfile
Return value

Get [source]

162 procedure Get
163 (File : in out EAstream;
164 Item : out EAstring;
165 Length : in Natural;
166 Exit_Cause : out Read_Stop_Cause);

Reads the number of characters specified by Length from File and stores them in Item. If line breaks are encountered they will be included in Item just like other characters. Mode_Error is propagated if File is an EAfile whose mode is not In_File. Otherwise, success or failure is reported in Exit_Cause. In case of failure, as much as could be read is returned in Item.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring
Length of type Natural
Exit_Cause of type AdaCL.EAstrings.IO.Read_Stop_Cause

Get [source]

175 procedure Get
176 (File : in out EAstream;
177 Item : out EAstring;
178 Length : in Natural);

Like above, but raises exceptions when reading fails: End_Error is raised if an attempt is made to read a file terminator. Incomplete_Byte_Sequence is raised if File ends in an incomplete code sequence. Invalid_Byte_Sequence is raised if File's content isn't a valid encoded text for File's encoding.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring
Length of type Natural

Get_Line [source]

190 procedure Get_Line
191 (File : in out EAstream;
192 Item : out EAstring;
193 Exit_Cause : out Read_Stop_Cause);

Reads characters from File and stores them in Item until one of the recognized line breaks is encountered. In the next call to Get or Get_Line, the first character read will be the first one after the line break. Mode_Error is propagated if File is an EAfile whose mode is not In_File. Otherwise, success or failure is reported in Exit_Cause. In case of failure, as much as could be read is returned in Item. If the file ends before anything has been read, Exit_Cause is set to End_Of_File. If characters have been read, Exit_Cause is set to All_Done and End_Of_File is not reported until the next read attempt. That is, it is not required that a file ends with a line break.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring
Exit_Cause of type AdaCL.EAstrings.IO.Read_Stop_Cause

Get_Line [source]

208 procedure Get_Line (File : in out EAstream; Item : out EAstring);

Like above, but raises exceptions when reading fails: End_Error is raised if the file ends before anything has been read. Incomplete_Byte_Sequence is raised if File ends in an incomplete code sequence. Invalid_Byte_Sequence is raised if File's content isn't a valid encoded text for File's encoding.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring

Initialize [source]

477 overriding procedure Initialize (Object : in out EAstream);
Object of type AdaCL.EAstrings.IO.EAstream

Is_Open [source]

69 function Is_Open (File : in EAstream) return Boolean is abstract;

Returns True if the EAstream is open (that is, if it is associated with a byte stream), otherwise returns False.

File of type AdaCL.EAstrings.IO.EAstream
Return value

Is_Open [source]

488 overriding function Is_Open (File : in EAfile) return Boolean;
File of type AdaCL.EAstrings.IO.EAfile
Return value

Is_Open [source]

490 overriding function Is_Open (File : in Stream_EAstream) return Boolean;
File of type AdaCL.EAstrings.IO.Stream_EAstream
Return value

Line_Break [source]

113 function Line_Break (File : in EAstream) return EAstring;

Returns the string that is currently used for line breaks when Put_Line or New_Line is called on File.

File of type AdaCL.EAstrings.IO.EAstream
Return value

Mode [source]

348 function Mode (File : in EAfile) return File_Mode;

Returns the current mode of the given EAfile. Status_Error is propagated if the EAfile is not open.

File of type AdaCL.EAstrings.IO.EAfile
Return value

Name [source]

352 function Name (File : in EAfile) return EAstring;

Returns a string which uniquely identifies the external file currently associated with the given EAfile (and may thus be used in an Open operation). Status_Error is propagated if the EAfile is not open. Use_Error is propagated if the associated external file is a temporary file that cannot be opened by any name.

File of type AdaCL.EAstrings.IO.EAfile
Return value

New_Line [source]

133 procedure New_Line (File : in EAstream; Spacing : in Positive := 1);

Writes the number of line breaks specified by Spacing to File. Mode_Error is propagated if File is an EAfile whose mode is not Out_File or Append_File.

File of type AdaCL.EAstrings.IO.EAstream
Spacing of type Positive

Open [source]

281 procedure Open
282 (File : in out EAfile;
283 Mode : in File_Mode;
284 Name : in EAstring;
285 Encoding : in Character_Encoding := OS.OS_Encoding;
286 Form : in String := "");

Associates the given EAfile with an existing external file having the given name and form, and sets the current mode and character encoding of the EAfile to the given mode and encoding. The EAfile is left open. The valid values of Form are the same as for Ada.Streams.Stream_IO.Open. Status_Error is propagated if the EAfile is already open. Name_Error is propagated if the string given as Name does not allow the identification of an external file; in particular, this exception is propagated if no external file with the given name exists. Use_Error is propagated if, for the specified mode, the external environment does not support opening for an external file with the given name (in the absence of Name_Error) and form.

File of type AdaCL.EAstrings.IO.EAfile
Mode of type AdaCL.EAstrings.IO.File_Mode
Name of type AdaCL.EAstrings.EAstring
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Form of type String

Put [source]

220 procedure Put (File : in EAstream; Item : in EAstring);

Writes the string in Item to File. Mode_Error is propagated if File is an EAfile whose mode is not Out_File or Append_File.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring

Put_Line [source]

227 procedure Put_Line (File : in EAstream; Item : in EAstring);

Writes the string in Item to File, followed by a line break. Mode_Error is propagated if File is an EAfile whose mode is not Out_File or Append_File.

File of type AdaCL.EAstrings.IO.EAstream
Item of type AdaCL.EAstrings.EAstring

Recognized_Line_Breaks [source]

123 function Recognized_Line_Breaks
124 (File : in EAstream)
125 return EAstring_Array;

Returns the set of strings that are currently recognized as line breaks by Get_Line and Skip_Line when reading from File.

File of type AdaCL.EAstrings.IO.EAstream
Return value

Reset [source]

321 procedure Reset
322 (File : in out EAfile;
323 Mode : in File_Mode;
324 Encoding : in Character_Encoding);

Resets the given EAfile so that reading can be restarted from the beginning of the file (for the mode In_File), and so that writing can be restarted at the beginning of the file (for the mode Out_File) or after the last character of the file (for the mode Append_File). The current mode and character encoding of the EAfile are set to the given mode and encoding. If the EAfile has mode Out_File or Append_File when Reset is called, the last character written since the most recent open or reset is the last character that can be read from the file. If nothing has been written and the mode is Out_File, then the reset file is empty. If nothing has been written and the mode is Append_File, then the reset file is unchanged. Status_Error is propagated if the EAfile is not open. Use_Error is propagated if the external environment does not support resetting for the external file and, also, if the external environment does not support resetting to the specified mode for the external file.

File of type AdaCL.EAstrings.IO.EAfile
Mode of type AdaCL.EAstrings.IO.File_Mode
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Reset [source]

342 procedure Reset (File : in out EAfile; Mode : in File_Mode);

Like above, but does not change the character encoding.

File of type AdaCL.EAstrings.IO.EAfile
Mode of type AdaCL.EAstrings.IO.File_Mode

Reset [source]

345 procedure Reset (File : in out EAfile);

Like above, but does not change the character encoding or the mode.

File of type AdaCL.EAstrings.IO.EAfile

Set_Encoding [source]

94 procedure Set_Encoding
95 (File : in out EAstream;
96 Encoding : in Character_Encoding);

Sets the character encoding that the byte stream should be interpreted as when reading from File, or that the text should be encoded in when writing to File. The character encoding can be changed in the middle of the file if so desired.

File of type AdaCL.EAstrings.IO.EAstream
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Set_Encoding [source]

496 overriding procedure Set_Encoding
497 (File : in out EAfile;
498 Encoding : in Character_Encoding);
File of type AdaCL.EAstrings.IO.EAfile
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Set_Line_Break [source]

107 procedure Set_Line_Break
108 (File : in out EAstream;
109 Line_Break : in EAstring);

Sets the string to be written for line breaks when Put_Line or New_Line is called on File.

File of type AdaCL.EAstrings.IO.EAstream
Line_Break of type AdaCL.EAstrings.EAstring

Set_Recognized_Line_Breaks [source]

117 procedure Set_Recognized_Line_Breaks
118 (File : in out EAstream;
119 Line_Breaks : in EAstring_Array);

Sets the set of strings to be recognized as line breaks by Get_Line and Skip_Line when reading from File.

File of type AdaCL.EAstrings.IO.EAstream
Line_Breaks of type AdaCL.EAstrings.EAstring_Array

Skip_Line [source]

141 procedure Skip_Line
142 (File : in out EAstream;
143 Spacing : in Positive := 1);

Reads from File and discards all characters until the number of line breaks specified by Spacing has been read. Mode_Error is propagated if File is an EAfile whose mode is not In_File. End_Error is propagated if an attempt is made to read a file terminator. Incomplete_Byte_Sequence is propagated if File ends in an incomplete code sequence. Invalid_Byte_Sequence is propagated if File's content isn't a valid encoded text for File's encoding.

File of type AdaCL.EAstrings.IO.EAstream
Spacing of type Positive

Stream [source]

83 function Stream
84 (File : in EAstream)
85 return Stream_IO.Stream_Access
86 is abstract;

Returns a pointer to the underlying raw byte stream that File is associated with. Status_Error is propagated if File is not open.

File of type AdaCL.EAstrings.IO.EAstream
Return value

Stream [source]

492 overriding function Stream (File : EAfile) return Stream_IO.Stream_Access;
File of type AdaCL.EAstrings.IO.EAfile
Return value

Stream [source]

494 overriding function Stream (File : Stream_EAstream) return Stream_IO.Stream_Access;
File of type AdaCL.EAstrings.IO.Stream_EAstream
Return value