1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . T E X T _ I O --
11 -- Copyright (C) 1992-2000 Free Software Foundation, Inc. --
13 -- This specification is derived from the Ada Reference Manual for use with --
14 -- GNAT. The copyright notice above, and the license provisions that follow --
15 -- apply solely to the contents of the part following the private keyword. --
17 -- GNAT is free software; you can redistribute it and/or modify it under --
18 -- terms of the GNU General Public License as published by the Free Soft- --
19 -- ware Foundation; either version 2, or (at your option) any later ver- --
20 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
21 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
22 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
23 -- for more details. You should have received a copy of the GNU General --
24 -- Public License distributed with GNAT; see file COPYING. If not, write --
25 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
26 -- MA 02111-1307, USA. --
28 -- As a special exception, if other files instantiate generics from this --
29 -- unit, or you link this unit with other files to produce an executable, --
30 -- this unit does not by itself cause the resulting executable to be --
31 -- covered by the GNU General Public License. This exception does not --
32 -- however invalidate any other reasons why the executable file might be --
33 -- covered by the GNU Public License. --
35 -- GNAT was originally developed by the GNAT team at New York University. --
36 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
38 ------------------------------------------------------------------------------
40 -- Note: the generic subpackages of Text_IO (Integer_IO, Float_IO, Fixed_IO,
41 -- Modular_IO, Decimal_IO and Enumeration_IO) appear as private children in
42 -- GNAT. These children are with'ed automatically if they are referenced, so
43 -- this rearrangement is invisible to user programs, but has the advantage
44 -- that only the needed parts of Text_IO are processed and loaded.
46 with Ada
.IO_Exceptions
;
49 with System
.File_Control_Block
;
51 package Ada
.Text_IO
is
52 pragma Elaborate_Body
(Text_IO
);
54 type File_Type
is limited private;
55 type File_Mode
is (In_File
, Out_File
, Append_File
);
57 -- The following representation clause allows the use of unchecked
58 -- conversion for rapid translation between the File_Mode type
59 -- used in this package and System.File_IO.
62 (In_File
=> 0, -- System.FIle_IO.File_Mode'Pos (In_File)
63 Out_File
=> 2, -- System.File_IO.File_Mode'Pos (Out_File)
64 Append_File
=> 3); -- System.File_IO.File_Mode'Pos (Append_File)
66 type Count
is range 0 .. Natural'Last;
67 -- The value of Count'Last must be large enough so that the assumption
68 -- enough so that the assumption that the Line, Column and Page
69 -- counts can never exceed this value is a valid assumption.
71 subtype Positive_Count
is Count
range 1 .. Count
'Last;
73 Unbounded
: constant Count
:= 0;
74 -- Line and page length
76 subtype Field
is Integer range 0 .. 255;
77 -- Note: if for any reason, there is a need to increase this value,
78 -- then it will be necessary to change the corresponding value in
79 -- System.Img_Real in file s-imgrea.adb.
81 subtype Number_Base
is Integer range 2 .. 16;
83 type Type_Set
is (Lower_Case
, Upper_Case
);
90 (File
: in out File_Type
;
91 Mode
: in File_Mode
:= Out_File
;
92 Name
: in String := "";
93 Form
: in String := "");
96 (File
: in out File_Type
;
99 Form
: in String := "");
101 procedure Close
(File
: in out File_Type
);
102 procedure Delete
(File
: in out File_Type
);
103 procedure Reset
(File
: in out File_Type
; Mode
: in File_Mode
);
104 procedure Reset
(File
: in out File_Type
);
106 function Mode
(File
: in File_Type
) return File_Mode
;
107 function Name
(File
: in File_Type
) return String;
108 function Form
(File
: in File_Type
) return String;
110 function Is_Open
(File
: in File_Type
) return Boolean;
112 ------------------------------------------------------
113 -- Control of default input, output and error files --
114 ------------------------------------------------------
116 procedure Set_Input
(File
: in File_Type
);
117 procedure Set_Output
(File
: in File_Type
);
118 procedure Set_Error
(File
: in File_Type
);
120 function Standard_Input
return File_Type
;
121 function Standard_Output
return File_Type
;
122 function Standard_Error
return File_Type
;
124 function Current_Input
return File_Type
;
125 function Current_Output
return File_Type
;
126 function Current_Error
return File_Type
;
128 type File_Access
is access constant File_Type
;
130 function Standard_Input
return File_Access
;
131 function Standard_Output
return File_Access
;
132 function Standard_Error
return File_Access
;
134 function Current_Input
return File_Access
;
135 function Current_Output
return File_Access
;
136 function Current_Error
return File_Access
;
142 -- Note: The parameter file is IN OUT in the RM, but this is clearly
143 -- an oversight, and was intended to be IN, see AI95-00057.
145 procedure Flush
(File
: in File_Type
);
148 --------------------------------------------
149 -- Specification of line and page lengths --
150 --------------------------------------------
152 procedure Set_Line_Length
(File
: in File_Type
; To
: in Count
);
153 procedure Set_Line_Length
(To
: in Count
);
155 procedure Set_Page_Length
(File
: in File_Type
; To
: in Count
);
156 procedure Set_Page_Length
(To
: in Count
);
158 function Line_Length
(File
: in File_Type
) return Count
;
159 function Line_Length
return Count
;
161 function Page_Length
(File
: in File_Type
) return Count
;
162 function Page_Length
return Count
;
164 ------------------------------------
165 -- Column, Line, and Page Control --
166 ------------------------------------
168 procedure New_Line
(File
: in File_Type
; Spacing
: in Positive_Count
:= 1);
169 procedure New_Line
(Spacing
: in Positive_Count
:= 1);
171 procedure Skip_Line
(File
: in File_Type
; Spacing
: in Positive_Count
:= 1);
172 procedure Skip_Line
(Spacing
: in Positive_Count
:= 1);
174 function End_Of_Line
(File
: in File_Type
) return Boolean;
175 function End_Of_Line
return Boolean;
177 procedure New_Page
(File
: in File_Type
);
180 procedure Skip_Page
(File
: in File_Type
);
183 function End_Of_Page
(File
: in File_Type
) return Boolean;
184 function End_Of_Page
return Boolean;
186 function End_Of_File
(File
: in File_Type
) return Boolean;
187 function End_Of_File
return Boolean;
189 procedure Set_Col
(File
: in File_Type
; To
: in Positive_Count
);
190 procedure Set_Col
(To
: in Positive_Count
);
192 procedure Set_Line
(File
: in File_Type
; To
: in Positive_Count
);
193 procedure Set_Line
(To
: in Positive_Count
);
195 function Col
(File
: in File_Type
) return Positive_Count
;
196 function Col
return Positive_Count
;
198 function Line
(File
: in File_Type
) return Positive_Count
;
199 function Line
return Positive_Count
;
201 function Page
(File
: in File_Type
) return Positive_Count
;
202 function Page
return Positive_Count
;
204 ----------------------------
205 -- Character Input-Output --
206 ----------------------------
208 procedure Get
(File
: in File_Type
; Item
: out Character);
209 procedure Get
(Item
: out Character);
210 procedure Put
(File
: in File_Type
; Item
: in Character);
211 procedure Put
(Item
: in Character);
214 (File
: in File_Type
;
215 Item
: out Character;
216 End_Of_Line
: out Boolean);
219 (Item
: out Character;
220 End_Of_Line
: out Boolean);
222 procedure Get_Immediate
223 (File
: in File_Type
;
224 Item
: out Character);
226 procedure Get_Immediate
227 (Item
: out Character);
229 procedure Get_Immediate
230 (File
: in File_Type
;
231 Item
: out Character;
232 Available
: out Boolean);
234 procedure Get_Immediate
235 (Item
: out Character;
236 Available
: out Boolean);
238 -------------------------
239 -- String Input-Output --
240 -------------------------
242 procedure Get
(File
: in File_Type
; Item
: out String);
243 procedure Get
(Item
: out String);
244 procedure Put
(File
: in File_Type
; Item
: in String);
245 procedure Put
(Item
: in String);
248 (File
: in File_Type
;
257 (File
: in File_Type
;
263 ---------------------------------------
264 -- Generic packages for Input-Output --
265 ---------------------------------------
267 -- The generic packages:
269 -- Ada.Text_IO.Integer_IO
270 -- Ada.Text_IO.Modular_IO
271 -- Ada.Text_IO.Float_IO
272 -- Ada.Text_IO.Fixed_IO
273 -- Ada.Text_IO.Decimal_IO
274 -- Ada.Text_IO.Enumeration_IO
276 -- are implemented as separate child packages in GNAT, so the
277 -- spec and body of these packages are to be found in separate
278 -- child units. This implementation detail is hidden from the
279 -- Ada programmer by special circuitry in the compiler that
280 -- treats these child packages as though they were nested in
281 -- Text_IO. The advantage of this special processing is that
282 -- the subsidiary routines needed if these generics are used
283 -- are not loaded when they are not used.
289 Status_Error
: exception renames IO_Exceptions
.Status_Error
;
290 Mode_Error
: exception renames IO_Exceptions
.Mode_Error
;
291 Name_Error
: exception renames IO_Exceptions
.Name_Error
;
292 Use_Error
: exception renames IO_Exceptions
.Use_Error
;
293 Device_Error
: exception renames IO_Exceptions
.Device_Error
;
294 End_Error
: exception renames IO_Exceptions
.End_Error
;
295 Data_Error
: exception renames IO_Exceptions
.Data_Error
;
296 Layout_Error
: exception renames IO_Exceptions
.Layout_Error
;
299 -----------------------------------
300 -- Handling of Format Characters --
301 -----------------------------------
303 -- Line marks are represented by the single character ASCII.LF (16#0A#).
304 -- In DOS and similar systems, underlying file translation takes care
305 -- of translating this to and from the standard CR/LF sequences used in
306 -- these operating systems to mark the end of a line. On output there is
307 -- always a line mark at the end of the last line, but on input, this
308 -- line mark can be omitted, and is implied by the end of file.
310 -- Page marks are represented by the single character ASCII.FF (16#0C#),
311 -- The page mark at the end of the file may be omitted, and is normally
312 -- omitted on output unless an explicit New_Page call is made before
313 -- closing the file. No page mark is added when a file is appended to,
314 -- so, in accordance with the permission in (RM A.10.2(4)), there may
315 -- or may not be a page mark separating preexising text in the file
316 -- from the new text to be written.
318 -- A file mark is marked by the physical end of file. In DOS translation
319 -- mode on input, an EOF character (SUB = 16#1A#) gets translated to the
320 -- physical end of file, so in effect this character is recognized as
321 -- marking the end of file in DOS and similar systems.
323 LM
: constant := Character'Pos (ASCII
.LF
);
326 PM
: constant := Character'Pos (ASCII
.FF
);
327 -- Used as page mark, except at end of file where it is implied
329 --------------------------------
330 -- Text_IO File Control Block --
331 --------------------------------
333 package FCB
renames System
.File_Control_Block
;
336 type File_Type
is access all Text_AFCB
;
338 type Text_AFCB
is new FCB
.AFCB
with record
342 Line_Length
: Count
:= 0;
343 Page_Length
: Count
:= 0;
345 Self
: aliased File_Type
;
346 -- Set to point to the containing Text_AFCB block. This is used to
347 -- implement the Current_{Error,Input,Ouput} functions which return
348 -- a File_Access, the file access value returned is a pointer to
349 -- the Self field of the corresponding file.
351 Before_LM
: Boolean := False;
352 -- This flag is used to deal with the anomolies introduced by the
353 -- peculiar definition of End_Of_File and End_Of_Page in Ada. These
354 -- functions require looking ahead more than one character. Since
355 -- there is no convenient way of backing up more than one character,
356 -- what we do is to leave ourselves positioned past the LM, but set
357 -- this flag, so that we know that from an Ada point of view we are
358 -- in front of the LM, not after it. A bit of a kludge, but it works!
360 Before_LM_PM
: Boolean := False;
361 -- This flag similarly handles the case of being physically positioned
362 -- after a LM-PM sequence when logically we are before the LM-PM. This
363 -- flag can only be set if Before_LM is also set.
367 function AFCB_Allocate
(Control_Block
: Text_AFCB
) return FCB
.AFCB_Ptr
;
369 procedure AFCB_Close
(File
: access Text_AFCB
);
370 procedure AFCB_Free
(File
: access Text_AFCB
);
373 (File
: in out Text_AFCB
;
374 Item
: out Ada
.Streams
.Stream_Element_Array
;
375 Last
: out Ada
.Streams
.Stream_Element_Offset
);
376 -- Read operation used when Text_IO file is treated directly as Stream
379 (File
: in out Text_AFCB
;
380 Item
: in Ada
.Streams
.Stream_Element_Array
);
381 -- Write operation used when Text_IO file is treated directly as Stream
383 ------------------------
384 -- The Standard Files --
385 ------------------------
387 Null_Str
: aliased constant String := "";
388 -- Used as name and form of standard files
390 Standard_Err_AFCB
: aliased Text_AFCB
;
391 Standard_In_AFCB
: aliased Text_AFCB
;
392 Standard_Out_AFCB
: aliased Text_AFCB
;
394 Standard_Err
: aliased File_Type
:= Standard_Err_AFCB
'Access;
395 Standard_In
: aliased File_Type
:= Standard_In_AFCB
'Access;
396 Standard_Out
: aliased File_Type
:= Standard_Out_AFCB
'Access;
399 Current_In
: aliased File_Type
:= Standard_In
;
400 Current_Out
: aliased File_Type
:= Standard_Out
;
401 Current_Err
: aliased File_Type
:= Standard_Err
;
404 -----------------------
405 -- Local Subprograms --
406 -----------------------
408 -- These subprograms are in the private part of the spec so that they can
409 -- be shared by the routines in the body of Ada.Text_IO.Wide_Text_IO.
411 -- Note: we use Integer in these declarations instead of the more accurate
412 -- Interfaces.C_Streams.int, because we do not want to drag in the spec of
413 -- this interfaces package with the spec of Ada.Text_IO, and we know that
414 -- in fact these types are identical
416 function Getc
(File
: File_Type
) return Integer;
417 -- Gets next character from file, which has already been checked for
418 -- being in read status, and returns the character read if no error
419 -- occurs. The result is EOF if the end of file was read.
421 function Nextc
(File
: File_Type
) return Integer;
422 -- Returns next character from file without skipping past it (i.e. it
423 -- is a combination of Getc followed by an Ungetc).
425 procedure Putc
(ch
: Integer; File
: File_Type
);
426 -- Outputs the given character to the file, which has already been
427 -- checked for being in output status. Device_Error is raised if the
428 -- character cannot be written.
430 procedure Terminate_Line
(File
: File_Type
);
431 -- If the file is in Write_File or Append_File mode, and the current
432 -- line is not terminated, then a line terminator is written using
433 -- New_Line. Note that there is no Terminate_Page routine, because
434 -- the page mark at the end of the file is implied if necessary.
436 procedure Ungetc
(ch
: Integer; File
: File_Type
);
437 -- Pushes back character into stream, using ungetc. The caller has
438 -- checked that the file is in read status. Device_Error is raised
439 -- if the character cannot be pushed back. An attempt to push back
440 -- and end of file character (EOF) is ignored.