1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . T E X T _ I O --
9 -- Copyright (C) 1992-2009, Free Software Foundation, Inc. --
11 -- This specification is derived from the Ada Reference Manual for use with --
12 -- GNAT. The copyright notice above, and the license provisions that follow --
13 -- apply solely to the contents of the part following the private keyword. --
15 -- GNAT is free software; you can redistribute it and/or modify it under --
16 -- terms of the GNU General Public License as published by the Free Soft- --
17 -- ware Foundation; either version 3, or (at your option) any later ver- --
18 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
19 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
20 -- or FITNESS FOR A PARTICULAR PURPOSE. --
22 -- As a special exception under Section 7 of GPL version 3, you are granted --
23 -- additional permissions described in the GCC Runtime Library Exception, --
24 -- version 3.1, as published by the Free Software Foundation. --
26 -- You should have received a copy of the GNU General Public License and --
27 -- a copy of the GCC Runtime Library Exception along with this program; --
28 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
29 -- <http://www.gnu.org/licenses/>. --
31 -- GNAT was originally developed by the GNAT team at New York University. --
32 -- Extensive contributions were provided by Ada Core Technologies Inc. --
34 ------------------------------------------------------------------------------
36 -- Note: the generic subpackages of Text_IO (Integer_IO, Float_IO, Fixed_IO,
37 -- Modular_IO, Decimal_IO and Enumeration_IO) appear as private children in
38 -- GNAT. These children are with'ed automatically if they are referenced, so
39 -- this rearrangement is invisible to user programs, but has the advantage
40 -- that only the needed parts of Text_IO are processed and loaded.
42 with Ada
.IO_Exceptions
;
46 with System
.File_Control_Block
;
49 package Ada
.Text_IO
is
50 pragma Elaborate_Body
;
52 type File_Type
is limited private;
53 type File_Mode
is (In_File
, Out_File
, Append_File
);
55 -- The following representation clause allows the use of unchecked
56 -- conversion for rapid translation between the File_Mode type
57 -- used in this package and System.File_IO.
60 (In_File
=> 0, -- System.FIle_IO.File_Mode'Pos (In_File)
61 Out_File
=> 2, -- System.File_IO.File_Mode'Pos (Out_File)
62 Append_File
=> 3); -- System.File_IO.File_Mode'Pos (Append_File)
64 type Count
is range 0 .. Natural'Last;
65 -- The value of Count'Last must be large enough so that the assumption
66 -- enough so that the assumption that the Line, Column and Page
67 -- counts can never exceed this value is a valid assumption.
69 subtype Positive_Count
is Count
range 1 .. Count
'Last;
71 Unbounded
: constant Count
:= 0;
72 -- Line and page length
74 subtype Field
is Integer range 0 .. 255;
75 -- Note: if for any reason, there is a need to increase this value,
76 -- then it will be necessary to change the corresponding value in
77 -- System.Img_Real in file s-imgrea.adb.
79 subtype Number_Base
is Integer range 2 .. 16;
81 type Type_Set
is (Lower_Case
, Upper_Case
);
88 (File
: in out File_Type
;
89 Mode
: File_Mode
:= Out_File
;
94 (File
: in out File_Type
;
99 procedure Close
(File
: in out File_Type
);
100 procedure Delete
(File
: in out File_Type
);
101 procedure Reset
(File
: in out File_Type
; Mode
: File_Mode
);
102 procedure Reset
(File
: in out File_Type
);
104 function Mode
(File
: File_Type
) return File_Mode
;
105 function Name
(File
: File_Type
) return String;
106 function Form
(File
: File_Type
) return String;
108 function Is_Open
(File
: File_Type
) return Boolean;
110 ------------------------------------------------------
111 -- Control of default input, output and error files --
112 ------------------------------------------------------
114 procedure Set_Input
(File
: File_Type
);
115 procedure Set_Output
(File
: File_Type
);
116 procedure Set_Error
(File
: File_Type
);
118 function Standard_Input
return File_Type
;
119 function Standard_Output
return File_Type
;
120 function Standard_Error
return File_Type
;
122 function Current_Input
return File_Type
;
123 function Current_Output
return File_Type
;
124 function Current_Error
return File_Type
;
126 type File_Access
is access constant File_Type
;
128 function Standard_Input
return File_Access
;
129 function Standard_Output
return File_Access
;
130 function Standard_Error
return File_Access
;
132 function Current_Input
return File_Access
;
133 function Current_Output
return File_Access
;
134 function Current_Error
return File_Access
;
140 -- Note: The parameter file is IN OUT in the RM, but this is clearly
141 -- an oversight, and was intended to be IN, see AI95-00057.
143 procedure Flush
(File
: File_Type
);
146 --------------------------------------------
147 -- Specification of line and page lengths --
148 --------------------------------------------
150 procedure Set_Line_Length
(File
: File_Type
; To
: Count
);
151 procedure Set_Line_Length
(To
: Count
);
153 procedure Set_Page_Length
(File
: File_Type
; To
: Count
);
154 procedure Set_Page_Length
(To
: Count
);
156 function Line_Length
(File
: File_Type
) return Count
;
157 function Line_Length
return Count
;
159 function Page_Length
(File
: File_Type
) return Count
;
160 function Page_Length
return Count
;
162 ------------------------------------
163 -- Column, Line, and Page Control --
164 ------------------------------------
166 procedure New_Line
(File
: File_Type
; Spacing
: Positive_Count
:= 1);
167 procedure New_Line
(Spacing
: Positive_Count
:= 1);
169 procedure Skip_Line
(File
: File_Type
; Spacing
: Positive_Count
:= 1);
170 procedure Skip_Line
(Spacing
: Positive_Count
:= 1);
172 function End_Of_Line
(File
: File_Type
) return Boolean;
173 function End_Of_Line
return Boolean;
175 procedure New_Page
(File
: File_Type
);
178 procedure Skip_Page
(File
: File_Type
);
181 function End_Of_Page
(File
: File_Type
) return Boolean;
182 function End_Of_Page
return Boolean;
184 function End_Of_File
(File
: File_Type
) return Boolean;
185 function End_Of_File
return Boolean;
187 procedure Set_Col
(File
: File_Type
; To
: Positive_Count
);
188 procedure Set_Col
(To
: Positive_Count
);
190 procedure Set_Line
(File
: File_Type
; To
: Positive_Count
);
191 procedure Set_Line
(To
: Positive_Count
);
193 function Col
(File
: File_Type
) return Positive_Count
;
194 function Col
return Positive_Count
;
196 function Line
(File
: File_Type
) return Positive_Count
;
197 function Line
return Positive_Count
;
199 function Page
(File
: File_Type
) return Positive_Count
;
200 function Page
return Positive_Count
;
202 ----------------------------
203 -- Character Input-Output --
204 ----------------------------
206 procedure Get
(File
: File_Type
; Item
: out Character);
207 procedure Get
(Item
: out Character);
208 procedure Put
(File
: File_Type
; Item
: Character);
209 procedure Put
(Item
: Character);
213 Item
: out Character;
214 End_Of_Line
: out Boolean);
217 (Item
: out Character;
218 End_Of_Line
: out Boolean);
220 procedure Get_Immediate
222 Item
: out Character);
224 procedure Get_Immediate
225 (Item
: out Character);
227 procedure Get_Immediate
229 Item
: out Character;
230 Available
: out Boolean);
232 procedure Get_Immediate
233 (Item
: out Character;
234 Available
: out Boolean);
236 -------------------------
237 -- String Input-Output --
238 -------------------------
240 procedure Get
(File
: File_Type
; Item
: out String);
241 procedure Get
(Item
: out String);
242 procedure Put
(File
: File_Type
; Item
: String);
243 procedure Put
(Item
: String);
254 function Get_Line
(File
: File_Type
) return String;
255 pragma Ada_05
(Get_Line
);
257 function Get_Line
return String;
258 pragma Ada_05
(Get_Line
);
267 ---------------------------------------
268 -- Generic packages for Input-Output --
269 ---------------------------------------
271 -- The generic packages:
273 -- Ada.Text_IO.Integer_IO
274 -- Ada.Text_IO.Modular_IO
275 -- Ada.Text_IO.Float_IO
276 -- Ada.Text_IO.Fixed_IO
277 -- Ada.Text_IO.Decimal_IO
278 -- Ada.Text_IO.Enumeration_IO
280 -- are implemented as separate child packages in GNAT, so the
281 -- spec and body of these packages are to be found in separate
282 -- child units. This implementation detail is hidden from the
283 -- Ada programmer by special circuitry in the compiler that
284 -- treats these child packages as though they were nested in
285 -- Text_IO. The advantage of this special processing is that
286 -- the subsidiary routines needed if these generics are used
287 -- are not loaded when they are not used.
293 Status_Error
: exception renames IO_Exceptions
.Status_Error
;
294 Mode_Error
: exception renames IO_Exceptions
.Mode_Error
;
295 Name_Error
: exception renames IO_Exceptions
.Name_Error
;
296 Use_Error
: exception renames IO_Exceptions
.Use_Error
;
297 Device_Error
: exception renames IO_Exceptions
.Device_Error
;
298 End_Error
: exception renames IO_Exceptions
.End_Error
;
299 Data_Error
: exception renames IO_Exceptions
.Data_Error
;
300 Layout_Error
: exception renames IO_Exceptions
.Layout_Error
;
304 -- The following procedures have a File_Type formal of mode IN OUT because
305 -- they may close the original file. The Close operation may raise an
306 -- exception, but in that case we want any assignment to the formal to
307 -- be effective anyway, so it must be passed by reference (or the caller
308 -- will be left with a dangling pointer).
310 pragma Export_Procedure
313 Mechanism
=> Reference
);
314 pragma Export_Procedure
317 Mechanism
=> Reference
);
318 pragma Export_Procedure
321 Parameter_Types
=> (File_Type
),
322 Mechanism
=> Reference
);
323 pragma Export_Procedure
326 Parameter_Types
=> (File_Type
, File_Mode
),
327 Mechanism
=> (File
=> Reference
));
329 -----------------------------------
330 -- Handling of Format Characters --
331 -----------------------------------
333 -- Line marks are represented by the single character ASCII.LF (16#0A#).
334 -- In DOS and similar systems, underlying file translation takes care
335 -- of translating this to and from the standard CR/LF sequences used in
336 -- these operating systems to mark the end of a line. On output there is
337 -- always a line mark at the end of the last line, but on input, this
338 -- line mark can be omitted, and is implied by the end of file.
340 -- Page marks are represented by the single character ASCII.FF (16#0C#),
341 -- The page mark at the end of the file may be omitted, and is normally
342 -- omitted on output unless an explicit New_Page call is made before
343 -- closing the file. No page mark is added when a file is appended to,
344 -- so, in accordance with the permission in (RM A.10.2(4)), there may
345 -- or may not be a page mark separating preexisting text in the file
346 -- from the new text to be written.
348 -- A file mark is marked by the physical end of file. In DOS translation
349 -- mode on input, an EOF character (SUB = 16#1A#) gets translated to the
350 -- physical end of file, so in effect this character is recognized as
351 -- marking the end of file in DOS and similar systems.
353 LM
: constant := Character'Pos (ASCII
.LF
);
356 PM
: constant := Character'Pos (ASCII
.FF
);
357 -- Used as page mark, except at end of file where it is implied
359 --------------------------------
360 -- Text_IO File Control Block --
361 --------------------------------
363 Default_WCEM
: System
.WCh_Con
.WC_Encoding_Method
:=
364 System
.WCh_Con
.WCEM_UTF8
;
365 -- This gets modified during initialization (see body) using
366 -- the default value established in the call to Set_Globals.
368 package FCB
renames System
.File_Control_Block
;
371 type File_Type
is access all Text_AFCB
;
373 type Text_AFCB
is new FCB
.AFCB
with record
377 Line_Length
: Count
:= 0;
378 Page_Length
: Count
:= 0;
380 Self
: aliased File_Type
;
381 -- Set to point to the containing Text_AFCB block. This is used to
382 -- implement the Current_{Error,Input,Output} functions which return
383 -- a File_Access, the file access value returned is a pointer to
384 -- the Self field of the corresponding file.
386 Before_LM
: Boolean := False;
387 -- This flag is used to deal with the anomalies introduced by the
388 -- peculiar definition of End_Of_File and End_Of_Page in Ada. These
389 -- functions require looking ahead more than one character. Since
390 -- there is no convenient way of backing up more than one character,
391 -- what we do is to leave ourselves positioned past the LM, but set
392 -- this flag, so that we know that from an Ada point of view we are
393 -- in front of the LM, not after it. A bit of a kludge, but it works!
395 Before_LM_PM
: Boolean := False;
396 -- This flag similarly handles the case of being physically positioned
397 -- after a LM-PM sequence when logically we are before the LM-PM. This
398 -- flag can only be set if Before_LM is also set.
400 WC_Method
: System
.WCh_Con
.WC_Encoding_Method
:= Default_WCEM
;
401 -- Encoding method to be used for this file. Text_IO does not deal with
402 -- wide characters, but it does deal with upper half characters in the
403 -- range 16#80#-16#FF# which may need encoding, e.g. in UTF-8 mode.
405 Before_Upper_Half_Character
: Boolean := False;
406 -- This flag is set to indicate that an encoded upper half character has
407 -- been read by Text_IO.Look_Ahead. If it is set to True, then it means
408 -- that the stream is logically positioned before the character but is
409 -- physically positioned after it. The character involved must be in
410 -- the range 16#80#-16#FF#, i.e. if the flag is set, then we know the
411 -- next character has a code greater than 16#7F#, and the value of this
412 -- character is saved in Saved_Upper_Half_Character.
414 Saved_Upper_Half_Character
: Character;
415 -- This field is valid only if Before_Upper_Half_Character is set. It
416 -- contains an upper-half character read by Look_Ahead. If Look_Ahead
417 -- reads a character in the range 16#00# to 16#7F#, then it can use
418 -- ungetc to put it back, but ungetc cannot be called more than once,
419 -- so for characters above this range, we don't try to back up the
420 -- file. Instead we save the character in this field and set the flag
421 -- Before_Upper_Half_Character to True to indicate that we are logically
422 -- positioned before this character even though the stream is physically
423 -- positioned after it.
427 function AFCB_Allocate
(Control_Block
: Text_AFCB
) return FCB
.AFCB_Ptr
;
429 procedure AFCB_Close
(File
: not null access Text_AFCB
);
430 procedure AFCB_Free
(File
: not null access Text_AFCB
);
433 (File
: in out Text_AFCB
;
434 Item
: out Ada
.Streams
.Stream_Element_Array
;
435 Last
: out Ada
.Streams
.Stream_Element_Offset
);
436 -- Read operation used when Text_IO file is treated directly as Stream
439 (File
: in out Text_AFCB
;
440 Item
: Ada
.Streams
.Stream_Element_Array
);
441 -- Write operation used when Text_IO file is treated directly as Stream
443 ------------------------
444 -- The Standard Files --
445 ------------------------
447 Standard_In_AFCB
: aliased Text_AFCB
;
448 Standard_Out_AFCB
: aliased Text_AFCB
;
449 Standard_Err_AFCB
: aliased Text_AFCB
;
451 Standard_In
: aliased File_Type
:= Standard_In_AFCB
'Access;
452 Standard_Out
: aliased File_Type
:= Standard_Out_AFCB
'Access;
453 Standard_Err
: aliased File_Type
:= Standard_Err_AFCB
'Access;
456 Current_In
: aliased File_Type
:= Standard_In
;
457 Current_Out
: aliased File_Type
:= Standard_Out
;
458 Current_Err
: aliased File_Type
:= Standard_Err
;
461 function EOF_Char
return Integer;
462 -- Returns the system-specific character indicating the end of a text file.
463 -- This is exported for use by child packages such as Enumeration_Aux to
464 -- eliminate their needing to depend directly on Interfaces.C_Streams,
465 -- which is not available in certain target environments (such as AAMP).
467 procedure Initialize_Standard_Files
;
468 -- Initializes the file control blocks for the standard files. Called from
469 -- the elaboration routine for this package, and from Reset_Standard_Files
470 -- in package Ada.Text_IO.Reset_Standard_Files.