1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . W I D E _ T E X T _ I O --
10 -- Copyright (C) 1992-2000 Free Software Foundation, Inc. --
12 -- This specification is derived from the Ada Reference Manual for use with --
13 -- GNAT. The copyright notice above, and the license provisions that follow --
14 -- apply solely to the contents of the part following the private keyword. --
16 -- GNAT is free software; you can redistribute it and/or modify it under --
17 -- terms of the GNU General Public License as published by the Free Soft- --
18 -- ware Foundation; either version 2, or (at your option) any later ver- --
19 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
20 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
21 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
22 -- for more details. You should have received a copy of the GNU General --
23 -- Public License distributed with GNAT; see file COPYING. If not, write --
24 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
25 -- MA 02111-1307, USA. --
27 -- As a special exception, if other files instantiate generics from this --
28 -- unit, or you link this unit with other files to produce an executable, --
29 -- this unit does not by itself cause the resulting executable to be --
30 -- covered by the GNU General Public License. This exception does not --
31 -- however invalidate any other reasons why the executable file might be --
32 -- covered by the GNU Public License. --
34 -- GNAT was originally developed by the GNAT team at New York University. --
35 -- Extensive contributions were provided by Ada Core Technologies Inc. --
37 ------------------------------------------------------------------------------
39 -- Note: the generic subpackages of Wide_Text_IO (Integer_IO, Float_IO,
40 -- Fixed_IO, Modular_IO, Decimal_IO and Enumeration_IO) appear as private
41 -- children in GNAT. These children are with'ed automatically if they are
42 -- referenced, so this rearrangement is invisible to user programs, but has
43 -- the advantage that only the needed parts of Wide_Text_IO are processed
46 with Ada
.IO_Exceptions
;
49 with System
.File_Control_Block
;
52 package Ada
.Wide_Text_IO
is
54 package WCh_Con
renames System
.WCh_Con
;
56 type File_Type
is limited private;
57 type File_Mode
is (In_File
, Out_File
, Append_File
);
59 -- The following representation clause allows the use of unchecked
60 -- conversion for rapid translation between the File_Mode type
61 -- used in this package and System.File_IO.
64 (In_File
=> 0, -- System.FIle_IO.File_Mode'Pos (In_File)
65 Out_File
=> 2, -- System.File_IO.File_Mode'Pos (Out_File)
66 Append_File
=> 3); -- System.File_IO.File_Mode'Pos (Append_File)
68 type Count
is range 0 .. Natural'Last;
69 -- The value of Count'Last must be large enough so that the assumption
70 -- enough so that the assumption that the Line, Column and Page
71 -- counts can never exceed this value is a valid assumption.
73 subtype Positive_Count
is Count
range 1 .. Count
'Last;
75 Unbounded
: constant Count
:= 0;
76 -- Line and page length
78 subtype Field
is Integer range 0 .. 255;
79 -- Note: if for any reason, there is a need to increase this value,
80 -- then it will be necessary to change the corresponding value in
81 -- System.Img_Real in file s-imgrea.adb.
83 subtype Number_Base
is Integer range 2 .. 16;
85 type Type_Set
is (Lower_Case
, Upper_Case
);
92 (File
: in out File_Type
;
93 Mode
: in File_Mode
:= Out_File
;
94 Name
: in String := "";
95 Form
: in String := "");
98 (File
: in out File_Type
;
101 Form
: in String := "");
103 procedure Close
(File
: in out File_Type
);
104 procedure Delete
(File
: in out File_Type
);
105 procedure Reset
(File
: in out File_Type
; Mode
: in File_Mode
);
106 procedure Reset
(File
: in out File_Type
);
108 function Mode
(File
: in File_Type
) return File_Mode
;
109 function Name
(File
: in File_Type
) return String;
110 function Form
(File
: in File_Type
) return String;
112 function Is_Open
(File
: in File_Type
) return Boolean;
114 ------------------------------------------------------
115 -- Control of default input, output and error files --
116 ------------------------------------------------------
118 procedure Set_Input
(File
: in File_Type
);
119 procedure Set_Output
(File
: in File_Type
);
120 procedure Set_Error
(File
: in File_Type
);
122 function Standard_Input
return File_Type
;
123 function Standard_Output
return File_Type
;
124 function Standard_Error
return File_Type
;
126 function Current_Input
return File_Type
;
127 function Current_Output
return File_Type
;
128 function Current_Error
return File_Type
;
130 type File_Access
is access constant File_Type
;
132 function Standard_Input
return File_Access
;
133 function Standard_Output
return File_Access
;
134 function Standard_Error
return File_Access
;
136 function Current_Input
return File_Access
;
137 function Current_Output
return File_Access
;
138 function Current_Error
return File_Access
;
144 -- Note: The parameter file is in out in the RM, but as pointed out
145 -- in <<95-5166.a Tucker Taft 95-6-23>> this is clearly an oversight.
147 procedure Flush
(File
: in File_Type
);
150 --------------------------------------------
151 -- Specification of line and page lengths --
152 --------------------------------------------
154 procedure Set_Line_Length
(File
: in File_Type
; To
: in Count
);
155 procedure Set_Line_Length
(To
: in Count
);
157 procedure Set_Page_Length
(File
: in File_Type
; To
: in Count
);
158 procedure Set_Page_Length
(To
: in Count
);
160 function Line_Length
(File
: in File_Type
) return Count
;
161 function Line_Length
return Count
;
163 function Page_Length
(File
: in File_Type
) return Count
;
164 function Page_Length
return Count
;
166 ------------------------------------
167 -- Column, Line, and Page Control --
168 ------------------------------------
170 procedure New_Line
(File
: in File_Type
; Spacing
: in Positive_Count
:= 1);
171 procedure New_Line
(Spacing
: in Positive_Count
:= 1);
173 procedure Skip_Line
(File
: in File_Type
; Spacing
: in Positive_Count
:= 1);
174 procedure Skip_Line
(Spacing
: in Positive_Count
:= 1);
176 function End_Of_Line
(File
: in File_Type
) return Boolean;
177 function End_Of_Line
return Boolean;
179 procedure New_Page
(File
: in File_Type
);
182 procedure Skip_Page
(File
: in File_Type
);
185 function End_Of_Page
(File
: in File_Type
) return Boolean;
186 function End_Of_Page
return Boolean;
188 function End_Of_File
(File
: in File_Type
) return Boolean;
189 function End_Of_File
return Boolean;
191 procedure Set_Col
(File
: in File_Type
; To
: in Positive_Count
);
192 procedure Set_Col
(To
: in Positive_Count
);
194 procedure Set_Line
(File
: in File_Type
; To
: in Positive_Count
);
195 procedure Set_Line
(To
: in Positive_Count
);
197 function Col
(File
: in File_Type
) return Positive_Count
;
198 function Col
return Positive_Count
;
200 function Line
(File
: in File_Type
) return Positive_Count
;
201 function Line
return Positive_Count
;
203 function Page
(File
: in File_Type
) return Positive_Count
;
204 function Page
return Positive_Count
;
206 ----------------------------
207 -- Character Input-Output --
208 ----------------------------
210 procedure Get
(File
: in File_Type
; Item
: out Wide_Character);
211 procedure Get
(Item
: out Wide_Character);
212 procedure Put
(File
: in File_Type
; Item
: in Wide_Character);
213 procedure Put
(Item
: in Wide_Character);
216 (File
: in File_Type
;
217 Item
: out Wide_Character;
218 End_Of_Line
: out Boolean);
221 (Item
: out Wide_Character;
222 End_Of_Line
: out Boolean);
224 procedure Get_Immediate
225 (File
: in File_Type
;
226 Item
: out Wide_Character);
228 procedure Get_Immediate
229 (Item
: out Wide_Character);
231 procedure Get_Immediate
232 (File
: in File_Type
;
233 Item
: out Wide_Character;
234 Available
: out Boolean);
236 procedure Get_Immediate
237 (Item
: out Wide_Character;
238 Available
: out Boolean);
240 -------------------------
241 -- String Input-Output --
242 -------------------------
244 procedure Get
(File
: in File_Type
; Item
: out Wide_String);
245 procedure Get
(Item
: out Wide_String);
246 procedure Put
(File
: in File_Type
; Item
: in Wide_String);
247 procedure Put
(Item
: in Wide_String);
250 (File
: in File_Type
;
251 Item
: out Wide_String;
255 (Item
: out Wide_String;
259 (File
: in File_Type
;
260 Item
: in Wide_String);
263 (Item
: in Wide_String);
265 ---------------------------------------
266 -- Generic packages for Input-Output --
267 ---------------------------------------
269 -- The generic packages:
271 -- Ada.Wide_Text_IO.Integer_IO
272 -- Ada.Wide_Text_IO.Modular_IO
273 -- Ada.Wide_Text_IO.Float_IO
274 -- Ada.Wide_Text_IO.Fixed_IO
275 -- Ada.Wide_Text_IO.Decimal_IO
276 -- Ada.Wide_Text_IO.Enumeration_IO
278 -- are implemented as separate child packages in GNAT, so the
279 -- spec and body of these packages are to be found in separate
280 -- child units. This implementation detail is hidden from the
281 -- Ada programmer by special circuitry in the compiler that
282 -- treats these child packages as though they were nested in
283 -- Text_IO. The advantage of this special processing is that
284 -- the subsidiary routines needed if these generics are used
285 -- are not loaded when they are not used.
291 Status_Error
: exception renames IO_Exceptions
.Status_Error
;
292 Mode_Error
: exception renames IO_Exceptions
.Mode_Error
;
293 Name_Error
: exception renames IO_Exceptions
.Name_Error
;
294 Use_Error
: exception renames IO_Exceptions
.Use_Error
;
295 Device_Error
: exception renames IO_Exceptions
.Device_Error
;
296 End_Error
: exception renames IO_Exceptions
.End_Error
;
297 Data_Error
: exception renames IO_Exceptions
.Data_Error
;
298 Layout_Error
: exception renames IO_Exceptions
.Layout_Error
;
301 -----------------------------------
302 -- Handling of Format Characters --
303 -----------------------------------
305 -- Line marks are represented by the single character ASCII.LF (16#0A#).
306 -- In DOS and similar systems, underlying file translation takes care
307 -- of translating this to and from the standard CR/LF sequences used in
308 -- these operating systems to mark the end of a line. On output there is
309 -- always a line mark at the end of the last line, but on input, this
310 -- line mark can be omitted, and is implied by the end of file.
312 -- Page marks are represented by the single character ASCII.FF (16#0C#),
313 -- The page mark at the end of the file may be omitted, and is normally
314 -- omitted on output unless an explicit New_Page call is made before
315 -- closing the file. No page mark is added when a file is appended to,
316 -- so, in accordance with the permission in (RM A.10.2(4)), there may
317 -- or may not be a page mark separating preexising text in the file
318 -- from the new text to be written.
320 -- A file mark is marked by the physical end of file. In DOS translation
321 -- mode on input, an EOF character (SUB = 16#1A#) gets translated to the
322 -- physical end of file, so in effect this character is recognized as
323 -- marking the end of file in DOS and similar systems.
325 LM
: constant := Character'Pos (ASCII
.LF
);
328 PM
: constant := Character'Pos (ASCII
.FF
);
329 -- Used as page mark, except at end of file where it is implied
331 -------------------------------------
332 -- Wide_Text_IO File Control Block --
333 -------------------------------------
335 Default_WCEM
: WCh_Con
.WC_Encoding_Method
:= WCh_Con
.WCEM_UTF8
;
336 -- This gets modified during initialization (see body) using
337 -- the default value established in the call to Set_Globals.
339 package FCB
renames System
.File_Control_Block
;
341 type Wide_Text_AFCB
is new FCB
.AFCB
with record
345 Line_Length
: Count
:= 0;
346 Page_Length
: Count
:= 0;
348 Before_LM
: Boolean := False;
349 -- This flag is used to deal with the anomolies introduced by the
350 -- peculiar definition of End_Of_File and End_Of_Page in Ada. These
351 -- functions require looking ahead more than one character. Since
352 -- there is no convenient way of backing up more than one character,
353 -- what we do is to leave ourselves positioned past the LM, but set
354 -- this flag, so that we know that from an Ada point of view we are
355 -- in front of the LM, not after it. A bit of a kludge, but it works!
357 Before_LM_PM
: Boolean := False;
358 -- This flag similarly handles the case of being physically positioned
359 -- after a LM-PM sequence when logically we are before the LM-PM. This
360 -- flag can only be set if Before_LM is also set.
362 WC_Method
: WCh_Con
.WC_Encoding_Method
:= Default_WCEM
;
363 -- Encoding method to be used for this file
365 Before_Wide_Character
: Boolean := False;
366 -- This flag is set to indicate that a wide character in the input has
367 -- been read by Wide_Text_IO.Look_Ahead. If it is set to True, then it
368 -- means that the stream is logically positioned before the character
369 -- but is physically positioned after it. The character involved must
370 -- not be in the range 16#00#-16#7F#, i.e. if the flag is set, then
371 -- we know the next character has a code greater than 16#7F#, and the
372 -- value of this character is saved in Saved_Wide_Character.
374 Saved_Wide_Character
: Wide_Character;
375 -- This field is valid only if Before_Wide_Character is set. It
376 -- contains a wide character read by Look_Ahead. If Look_Ahead
377 -- reads a character in the range 16#0000# to 16#007F#, then it
378 -- can use ungetc to put it back, but ungetc cannot be called
379 -- more than once, so for characters above this range, we don't
380 -- try to back up the file. Instead we save the character in this
381 -- field and set the flag Before_Wide_Character to indicate that
382 -- we are logically positioned before this character even though
383 -- the stream is physically positioned after it.
387 type File_Type
is access all Wide_Text_AFCB
;
389 function AFCB_Allocate
(Control_Block
: Wide_Text_AFCB
) return FCB
.AFCB_Ptr
;
391 procedure AFCB_Close
(File
: access Wide_Text_AFCB
);
392 procedure AFCB_Free
(File
: access Wide_Text_AFCB
);
395 (File
: in out Wide_Text_AFCB
;
396 Item
: out Ada
.Streams
.Stream_Element_Array
;
397 Last
: out Ada
.Streams
.Stream_Element_Offset
);
398 -- Read operation used when Wide_Text_IO file is treated as a Stream
401 (File
: in out Wide_Text_AFCB
;
402 Item
: in Ada
.Streams
.Stream_Element_Array
);
403 -- Write operation used when Wide_Text_IO file is treated as a Stream
405 ------------------------
406 -- The Standard Files --
407 ------------------------
409 Null_Str
: aliased constant String := "";
410 -- Used as name and form of standard files
412 Standard_Err_AFCB
: aliased Wide_Text_AFCB
;
413 Standard_In_AFCB
: aliased Wide_Text_AFCB
;
414 Standard_Out_AFCB
: aliased Wide_Text_AFCB
;
416 Standard_Err
: aliased File_Type
:= Standard_Err_AFCB
'Access;
417 Standard_In
: aliased File_Type
:= Standard_In_AFCB
'Access;
418 Standard_Out
: aliased File_Type
:= Standard_Out_AFCB
'Access;
421 Current_In
: aliased File_Type
:= Standard_In
;
422 Current_Out
: aliased File_Type
:= Standard_Out
;
423 Current_Err
: aliased File_Type
:= Standard_Err
;
426 -----------------------
427 -- Local Subprograms --
428 -----------------------
430 -- These subprograms are in the private part of the spec so that they can
431 -- be shared by the routines in the body of Ada.Text_IO.Wide_Text_IO.
433 -- Note: we use Integer in these declarations instead of the more accurate
434 -- Interfaces.C_Streams.int, because we do not want to drag in the spec of
435 -- this interfaces package with the spec of Ada.Text_IO, and we know that
436 -- in fact these types are identical
438 function Getc
(File
: File_Type
) return Integer;
439 -- Gets next character from file, which has already been checked for
440 -- being in read status, and returns the character read if no error
441 -- occurs. The result is EOF if the end of file was read.
443 procedure Get_Character
444 (File
: in File_Type
;
445 Item
: out Character);
446 -- This is essentially a copy of the normal Get routine from Text_IO. It
447 -- obtains a single character from the input file File, and places it in
448 -- Item. This character may be the leading character of a Wide_Character
449 -- sequence, but that is up to the caller to deal with.
451 function Get_Wide_Char
454 return Wide_Character;
455 -- This function is shared by Get and Get_Immediate to extract a wide
456 -- character value from the given File. The first byte has already been
457 -- read and is passed in C. The wide character value is returned as the
458 -- result, and the file pointer is bumped past the character.
460 function Nextc
(File
: File_Type
) return Integer;
461 -- Returns next character from file without skipping past it (i.e. it
462 -- is a combination of Getc followed by an Ungetc).
464 procedure Putc
(ch
: Integer; File
: File_Type
);
465 -- Outputs the given character to the file, which has already been
466 -- checked for being in output status. Device_Error is raised if the
467 -- character cannot be written.
469 procedure Terminate_Line
(File
: File_Type
);
470 -- If the file is in Write_File or Append_File mode, and the current
471 -- line is not terminated, then a line terminator is written using
472 -- New_Line. Note that there is no Terminate_Page routine, because
473 -- the page mark at the end of the file is implied if necessary.
475 procedure Ungetc
(ch
: Integer; File
: File_Type
);
476 -- Pushes back character into stream, using ungetc. The caller has
477 -- checked that the file is in read status. Device_Error is raised
478 -- if the character cannot be pushed back. An attempt to push back
479 -- and end of file character (EOF) is ignored.
481 end Ada
.Wide_Text_IO
;