1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . W I D E _ W I D E _ T E X T _ I O --
9 -- Copyright (C) 1992-2017, 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 Wide_Wide_Text_IO (Integer_IO, Float_IO,
37 -- Fixed_IO, Modular_IO, Decimal_IO and Enumeration_IO) appear as private
38 -- children in GNAT. These children are with'ed automatically if they are
39 -- referenced, so this rearrangement is invisible to user programs, but has
40 -- the advantage that only the needed parts of Wide_Wide_Text_IO are processed
43 with Ada
.IO_Exceptions
;
46 with Interfaces
.C_Streams
;
49 with System
.File_Control_Block
;
52 package Ada
.Wide_Wide_Text_IO
is
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 that
68 -- the Line, Column and Page counts can never exceed this value is valid.
70 subtype Positive_Count
is Count
range 1 .. Count
'Last;
72 Unbounded
: constant Count
:= 0;
73 -- Line and page length
75 subtype Field
is Integer range 0 .. 255;
76 -- Note: if for any reason, there is a need to increase this value, then it
77 -- will be necessary to change the corresponding value in System.Img_Real
78 -- in file s-imgrea.adb.
80 subtype Number_Base
is Integer range 2 .. 16;
82 type Type_Set
is (Lower_Case
, Upper_Case
);
89 (File
: in out File_Type
;
90 Mode
: File_Mode
:= Out_File
;
95 (File
: in out File_Type
;
100 procedure Close
(File
: in out File_Type
);
101 procedure Delete
(File
: in out File_Type
);
102 procedure Reset
(File
: in out File_Type
; Mode
: File_Mode
);
103 procedure Reset
(File
: in out File_Type
);
105 function Mode
(File
: File_Type
) return File_Mode
;
106 function Name
(File
: File_Type
) return String;
107 function Form
(File
: File_Type
) return String;
109 function Is_Open
(File
: File_Type
) return Boolean;
111 ------------------------------------------------------
112 -- Control of default input, output and error files --
113 ------------------------------------------------------
115 procedure Set_Input
(File
: File_Type
);
116 procedure Set_Output
(File
: File_Type
);
117 procedure Set_Error
(File
: File_Type
);
119 function Standard_Input
return File_Type
;
120 function Standard_Output
return File_Type
;
121 function Standard_Error
return File_Type
;
123 function Current_Input
return File_Type
;
124 function Current_Output
return File_Type
;
125 function Current_Error
return File_Type
;
127 type File_Access
is access constant File_Type
;
129 function Standard_Input
return File_Access
;
130 function Standard_Output
return File_Access
;
131 function Standard_Error
return File_Access
;
133 function Current_Input
return File_Access
;
134 function Current_Output
return File_Access
;
135 function Current_Error
return File_Access
;
141 -- Note: The parameter file is in out in the RM, but as pointed out
142 -- in <<95-5166.a Tucker Taft 95-6-23>> this is clearly an oversight.
144 procedure Flush
(File
: File_Type
);
147 --------------------------------------------
148 -- Specification of line and page lengths --
149 --------------------------------------------
151 procedure Set_Line_Length
(File
: File_Type
; To
: Count
);
152 procedure Set_Line_Length
(To
: Count
);
154 procedure Set_Page_Length
(File
: File_Type
; To
: Count
);
155 procedure Set_Page_Length
(To
: Count
);
157 function Line_Length
(File
: File_Type
) return Count
;
158 function Line_Length
return Count
;
160 function Page_Length
(File
: File_Type
) return Count
;
161 function Page_Length
return Count
;
163 ------------------------------------
164 -- Column, Line, and Page Control --
165 ------------------------------------
167 procedure New_Line
(File
: File_Type
; Spacing
: Positive_Count
:= 1);
168 procedure New_Line
(Spacing
: Positive_Count
:= 1);
170 procedure Skip_Line
(File
: File_Type
; Spacing
: Positive_Count
:= 1);
171 procedure Skip_Line
(Spacing
: Positive_Count
:= 1);
173 function End_Of_Line
(File
: File_Type
) return Boolean;
174 function End_Of_Line
return Boolean;
176 procedure New_Page
(File
: File_Type
);
179 procedure Skip_Page
(File
: File_Type
);
182 function End_Of_Page
(File
: File_Type
) return Boolean;
183 function End_Of_Page
return Boolean;
185 function End_Of_File
(File
: File_Type
) return Boolean;
186 function End_Of_File
return Boolean;
188 procedure Set_Col
(File
: File_Type
; To
: Positive_Count
);
189 procedure Set_Col
(To
: Positive_Count
);
191 procedure Set_Line
(File
: File_Type
; To
: Positive_Count
);
192 procedure Set_Line
(To
: Positive_Count
);
194 function Col
(File
: File_Type
) return Positive_Count
;
195 function Col
return Positive_Count
;
197 function Line
(File
: File_Type
) return Positive_Count
;
198 function Line
return Positive_Count
;
200 function Page
(File
: File_Type
) return Positive_Count
;
201 function Page
return Positive_Count
;
203 ----------------------------
204 -- Character Input-Output --
205 ----------------------------
207 procedure Get
(File
: File_Type
; Item
: out Wide_Wide_Character
);
208 procedure Get
(Item
: out Wide_Wide_Character
);
209 procedure Put
(File
: File_Type
; Item
: Wide_Wide_Character
);
210 procedure Put
(Item
: Wide_Wide_Character
);
214 Item
: out Wide_Wide_Character
;
215 End_Of_Line
: out Boolean);
218 (Item
: out Wide_Wide_Character
;
219 End_Of_Line
: out Boolean);
221 procedure Get_Immediate
223 Item
: out Wide_Wide_Character
);
225 procedure Get_Immediate
226 (Item
: out Wide_Wide_Character
);
228 procedure Get_Immediate
230 Item
: out Wide_Wide_Character
;
231 Available
: out Boolean);
233 procedure Get_Immediate
234 (Item
: out Wide_Wide_Character
;
235 Available
: out Boolean);
237 -------------------------
238 -- String Input-Output --
239 -------------------------
241 procedure Get
(File
: File_Type
; Item
: out Wide_Wide_String
);
242 procedure Get
(Item
: out Wide_Wide_String
);
243 procedure Put
(File
: File_Type
; Item
: Wide_Wide_String
);
244 procedure Put
(Item
: Wide_Wide_String
);
248 Item
: out Wide_Wide_String
;
251 function Get_Line
(File
: File_Type
) return Wide_Wide_String
;
252 pragma Ada_05
(Get_Line
);
254 function Get_Line
return Wide_Wide_String
;
255 pragma Ada_05
(Get_Line
);
258 (Item
: out Wide_Wide_String
;
263 Item
: Wide_Wide_String
);
266 (Item
: Wide_Wide_String
);
268 ---------------------------------------
269 -- Generic packages for Input-Output --
270 ---------------------------------------
272 -- The generic packages:
274 -- Ada.Wide_Wide_Text_IO.Integer_IO
275 -- Ada.Wide_Wide_Text_IO.Modular_IO
276 -- Ada.Wide_Wide_Text_IO.Float_IO
277 -- Ada.Wide_Wide_Text_IO.Fixed_IO
278 -- Ada.Wide_Wide_Text_IO.Decimal_IO
279 -- Ada.Wide_Wide_Text_IO.Enumeration_IO
281 -- are implemented as separate child packages in GNAT, so the
282 -- spec and body of these packages are to be found in separate
283 -- child units. This implementation detail is hidden from the
284 -- Ada programmer by special circuitry in the compiler that
285 -- treats these child packages as though they were nested in
286 -- Text_IO. The advantage of this special processing is that
287 -- the subsidiary routines needed if these generics are used
288 -- are not loaded when they are not used.
294 Status_Error
: exception renames IO_Exceptions
.Status_Error
;
295 Mode_Error
: exception renames IO_Exceptions
.Mode_Error
;
296 Name_Error
: exception renames IO_Exceptions
.Name_Error
;
297 Use_Error
: exception renames IO_Exceptions
.Use_Error
;
298 Device_Error
: exception renames IO_Exceptions
.Device_Error
;
299 End_Error
: exception renames IO_Exceptions
.End_Error
;
300 Data_Error
: exception renames IO_Exceptions
.Data_Error
;
301 Layout_Error
: exception renames IO_Exceptions
.Layout_Error
;
305 -- The following procedures have a File_Type formal of mode IN OUT because
306 -- they may close the original file. The Close operation may raise an
307 -- exception, but in that case we want any assignment to the formal to
308 -- be effective anyway, so it must be passed by reference (or the caller
309 -- will be left with a dangling pointer).
311 pragma Export_Procedure
314 Mechanism
=> Reference
);
315 pragma Export_Procedure
318 Mechanism
=> Reference
);
319 pragma Export_Procedure
322 Parameter_Types
=> (File_Type
),
323 Mechanism
=> Reference
);
324 pragma Export_Procedure
327 Parameter_Types
=> (File_Type
, File_Mode
),
328 Mechanism
=> (File
=> Reference
));
330 package WCh_Con
renames System
.WCh_Con
;
332 -----------------------------------
333 -- Handling of Format Characters --
334 -----------------------------------
336 -- Line marks are represented by the single character ASCII.LF (16#0A#).
337 -- In DOS and similar systems, underlying file translation takes care
338 -- of translating this to and from the standard CR/LF sequences used in
339 -- these operating systems to mark the end of a line. On output there is
340 -- always a line mark at the end of the last line, but on input, this
341 -- line mark can be omitted, and is implied by the end of file.
343 -- Page marks are represented by the single character ASCII.FF (16#0C#),
344 -- The page mark at the end of the file may be omitted, and is normally
345 -- omitted on output unless an explicit New_Page call is made before
346 -- closing the file. No page mark is added when a file is appended to,
347 -- so, in accordance with the permission in (RM A.10.2(4)), there may
348 -- or may not be a page mark separating preexisting text in the file
349 -- from the new text to be written.
351 -- A file mark is marked by the physical end of file. In DOS translation
352 -- mode on input, an EOF character (SUB = 16#1A#) gets translated to the
353 -- physical end of file, so in effect this character is recognized as
354 -- marking the end of file in DOS and similar systems.
356 LM
: constant := Character'Pos (ASCII
.LF
);
359 PM
: constant := Character'Pos (ASCII
.FF
);
360 -- Used as page mark, except at end of file where it is implied
362 ------------------------------------------
363 -- Wide_Wide_Text_IO File Control Block --
364 ------------------------------------------
366 Default_WCEM
: WCh_Con
.WC_Encoding_Method
:= WCh_Con
.WCEM_UTF8
;
367 -- This gets modified during initialization (see body) using the default
368 -- value established in the call to Set_Globals.
370 package FCB
renames System
.File_Control_Block
;
372 type Wide_Wide_Text_AFCB
is new FCB
.AFCB
with record
376 Line_Length
: Count
:= 0;
377 Page_Length
: Count
:= 0;
379 Self
: aliased File_Type
;
380 -- Set to point to the containing Text_AFCB block. This is used to
381 -- implement the Current_{Error,Input,Output} functions which return
382 -- a File_Access, the file access value returned is a pointer to
383 -- the Self field of the corresponding file.
385 Before_LM
: Boolean := False;
386 -- This flag is used to deal with the anomalies introduced by the
387 -- peculiar definition of End_Of_File and End_Of_Page in Ada. These
388 -- functions require looking ahead more than one character. Since
389 -- there is no convenient way of backing up more than one character,
390 -- what we do is to leave ourselves positioned past the LM, but set
391 -- this flag, so that we know that from an Ada point of view we are
392 -- in front of the LM, not after it. A bit odd, but it works.
394 Before_LM_PM
: Boolean := False;
395 -- This flag similarly handles the case of being physically positioned
396 -- after a LM-PM sequence when logically we are before the LM-PM. This
397 -- flag can only be set if Before_LM is also set.
399 WC_Method
: WCh_Con
.WC_Encoding_Method
:= Default_WCEM
;
400 -- Encoding method to be used for this file
402 Before_Wide_Wide_Character
: Boolean := False;
403 -- This flag is set to indicate that a wide character in the input has
404 -- been read by Wide_Wide_Text_IO.Look_Ahead. If it is set to True,
405 -- then it means that the stream is logically positioned before the
406 -- character but is physically positioned after it. The character
407 -- involved must not be in the range 16#00#-16#7F#, i.e. if the flag is
408 -- set, then we know the next character has a code greater than 16#7F#,
409 -- and the value of this character is saved in
410 -- Saved_Wide_Wide_Character.
412 Saved_Wide_Wide_Character
: Wide_Wide_Character
;
413 -- This field is valid only if Before_Wide_Wide_Character is set. It
414 -- contains a wide character read by Look_Ahead. If Look_Ahead
415 -- reads a character in the range 16#0000# to 16#007F#, then it
416 -- can use ungetc to put it back, but ungetc cannot be called
417 -- more than once, so for characters above this range, we don't
418 -- try to back up the file. Instead we save the character in this
419 -- field and set the flag Before_Wide_Wide_Character to indicate that
420 -- we are logically positioned before this character even though
421 -- the stream is physically positioned after it.
425 type File_Type
is access all Wide_Wide_Text_AFCB
;
427 function AFCB_Allocate
428 (Control_Block
: Wide_Wide_Text_AFCB
) return FCB
.AFCB_Ptr
;
430 procedure AFCB_Close
(File
: not null access Wide_Wide_Text_AFCB
);
431 procedure AFCB_Free
(File
: not null access Wide_Wide_Text_AFCB
);
434 (File
: in out Wide_Wide_Text_AFCB
;
435 Item
: out Ada
.Streams
.Stream_Element_Array
;
436 Last
: out Ada
.Streams
.Stream_Element_Offset
);
437 -- Read operation used when Wide_Wide_Text_IO file is treated as a Stream
440 (File
: in out Wide_Wide_Text_AFCB
;
441 Item
: Ada
.Streams
.Stream_Element_Array
);
442 -- Write operation used when Wide_Wide_Text_IO file is treated as a Stream
444 ------------------------
445 -- The Standard Files --
446 ------------------------
448 Standard_Err_AFCB
: aliased Wide_Wide_Text_AFCB
;
449 Standard_In_AFCB
: aliased Wide_Wide_Text_AFCB
;
450 Standard_Out_AFCB
: aliased Wide_Wide_Text_AFCB
;
452 Standard_Err
: aliased File_Type
:= Standard_Err_AFCB
'Access;
453 Standard_In
: aliased File_Type
:= Standard_In_AFCB
'Access;
454 Standard_Out
: aliased File_Type
:= Standard_Out_AFCB
'Access;
457 Current_In
: aliased File_Type
:= Standard_In
;
458 Current_Out
: aliased File_Type
:= Standard_Out
;
459 Current_Err
: aliased File_Type
:= Standard_Err
;
462 procedure Initialize_Standard_Files
;
463 -- Initializes the file control blocks for the standard files. Called from
464 -- the elaboration routine for this package, and from Reset_Standard_Files
465 -- in package Ada.Wide_Wide_Text_IO.Reset_Standard_Files.
467 -----------------------
468 -- Local Subprograms --
469 -----------------------
471 -- These subprograms are in the private part of the spec so that they can
472 -- be shared by the children of Ada.Text_IO.Wide_Wide_Text_IO.
474 function Getc
(File
: File_Type
) return Interfaces
.C_Streams
.int
;
475 -- Gets next character from file, which has already been checked for being
476 -- in read status, and returns the character read if no error occurs. The
477 -- result is EOF if the end of file was read.
479 procedure Get_Character
(File
: File_Type
; Item
: out Character);
480 -- This is essentially copy of Wide_Wide_Text_IO.Get. It obtains a single
481 -- obtains a single character from the input file File, and places it in
482 -- Item. This result may be the leading character of a Wide_Wide_Character
483 -- sequence, but that is up to the caller to deal with.
485 function Get_Wide_Wide_Char
487 File
: File_Type
) return Wide_Wide_Character
;
488 -- This function is shared by Get and Get_Immediate to extract a wide
489 -- character value from the given File. The first byte has already been
490 -- read and is passed in C. The wide character value is returned as the
491 -- result, and the file pointer is bumped past the character.
493 function Nextc
(File
: File_Type
) return Interfaces
.C_Streams
.int
;
494 -- Returns next character from file without skipping past it (i.e. it is a
495 -- combination of Getc followed by an Ungetc).
497 end Ada
.Wide_Wide_Text_IO
;