1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- O U T P U T -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1992-2020, Free Software Foundation, Inc. -- 10-- -- 11-- GNAT is free software; you can redistribute it and/or modify it under -- 12-- terms of the GNU General Public License as published by the Free Soft- -- 13-- ware Foundation; either version 3, or (at your option) any later ver- -- 14-- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- 15-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- 16-- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- 17-- for more details. You should have received a copy of the GNU General -- 18-- Public License distributed with GNAT; see file COPYING3. If not, go to -- 19-- http://www.gnu.org/licenses for a complete copy of the license. -- 20-- -- 21-- GNAT was originally developed by the GNAT team at New York University. -- 22-- Extensive contributions were provided by Ada Core Technologies Inc. -- 23-- -- 24------------------------------------------------------------------------------ 25 26-- This package contains low level output routines used by the compiler for 27-- writing error messages and informational output. It is also used by the 28-- debug source file output routines (see Sprint.Print_Debug_Line). 29 30with Hostparm; 31with Types; use Types; 32 33pragma Warnings (Off); 34-- This package is used also by gnatcoll 35with System.OS_Lib; use System.OS_Lib; 36pragma Warnings (On); 37 38package Output is 39 pragma Elaborate_Body; 40 41 type Output_Proc is access procedure (S : String); 42 -- This type is used for the Set_Special_Output procedure. If Output_Proc 43 -- is called, then instead of lines being written to standard error or 44 -- standard output, a call is made to the given procedure for each line, 45 -- passing the line with an end of line character (which is a single 46 -- ASCII.LF character, even in systems which normally use CR/LF or some 47 -- other sequence for line end). 48 49 ----------------- 50 -- Subprograms -- 51 ----------------- 52 53 procedure Set_Special_Output (P : Output_Proc); 54 -- Sets subsequent output to call procedure P. If P is null, then the call 55 -- cancels the effect of a previous call, reverting the output to standard 56 -- error or standard output depending on the mode at the time of previous 57 -- call. Any exception generated by calls to P is simply propagated to 58 -- the caller of the routine causing the write operation. 59 60 procedure Cancel_Special_Output; 61 -- Cancels the effect of a call to Set_Special_Output, if any. The output 62 -- is then directed to standard error or standard output depending on the 63 -- last call to Set_Standard_Error or Set_Standard_Output. It is never an 64 -- error to call Cancel_Special_Output. It has the same effect as calling 65 -- Set_Special_Output (null). 66 67 procedure Ignore_Output (S : String); 68 -- Does nothing. To disable output, pass Ignore_Output'Access to 69 -- Set_Special_Output. 70 71 procedure Set_Standard_Error; 72 -- Sets subsequent output to appear on the standard error file (whatever 73 -- that might mean for the host operating system, if anything) when 74 -- no special output is in effect. When a special output is in effect, 75 -- the output will appear on standard error only after special output 76 -- has been cancelled. 77 78 procedure Set_Standard_Output; 79 -- Sets subsequent output to appear on the standard output file (whatever 80 -- that might mean for the host operating system, if anything) when no 81 -- special output is in effect. When a special output is in effect, the 82 -- output will appear on standard output only after special output has been 83 -- cancelled. Output to standard output is the default mode before any call 84 -- to either of the Set procedures. 85 86 procedure Set_Output (FD : File_Descriptor); 87 -- Sets subsequent output to appear on the given file descriptor when no 88 -- special output is in effect. When a special output is in effect, the 89 -- output will appear on the given file descriptor only after special 90 -- output has been cancelled. 91 92 procedure Push_Output; 93 -- Saves the current output destination on a stack, but leaves it 94 -- unchanged. This subprogram only supports a small stack and is normally 95 -- used with a depth of one. 96 97 procedure Pop_Output; 98 -- Changes the current output destination to be the last output destination 99 -- popped using Push_Output. 100 101 procedure Indent; 102 -- Increases the current indentation level. Whenever a line is written 103 -- (triggered by Eol), an appropriate amount of whitespace is added to the 104 -- beginning of the line, wrapping around if it gets too long. 105 106 procedure Outdent; 107 -- Decreases the current indentation level 108 109 procedure Write_Char (C : Character); 110 -- Write one character to the standard output file. If the character is LF, 111 -- this is equivalent to Write_Eol. 112 113 procedure Write_Erase_Char (C : Character); 114 -- If last character in buffer matches C, erase it, otherwise no effect 115 116 procedure Write_Eol; 117 -- Write an end of line (whatever is required by the system in use, e.g. 118 -- CR/LF for DOS, or LF for Unix) to the standard output file. This routine 119 -- also empties the line buffer, actually writing it to the file. Note that 120 -- Write_Eol is the only routine that causes any actual output to be 121 -- written. Trailing spaces are removed. 122 123 procedure Write_Eol_Keep_Blanks; 124 -- Similar as Write_Eol, except that trailing spaces are not removed 125 126 procedure Write_Int (Val : Int); 127 -- Write an integer value with no leading blanks or zeroes. Negative values 128 -- are preceded by a minus sign). 129 130 procedure Write_Spaces (N : Nat); 131 -- Write N spaces 132 133 procedure Write_Str (S : String); 134 -- Write a string of characters to the standard output file. Note that 135 -- end of line is normally handled separately using WRITE_EOL, but it is 136 -- allowable for the string to contain LF (but not CR) characters, which 137 -- are properly interpreted as end of line characters. The string may also 138 -- contain horizontal tab characters. 139 140 procedure Write_Line (S : String); 141 -- Equivalent to Write_Str (S) followed by Write_Eol; 142 143 function Last_Char return Character; 144 -- Returns last character written on the current line, or null if the 145 -- current line is (so far) empty. 146 147 procedure Delete_Last_Char; 148 -- Deletes last character written on the current line, no effect if the 149 -- current line is (so far) empty. 150 151 function Column return Pos; 152 pragma Inline (Column); 153 -- Returns the number of the column about to be written (e.g. a value of 1 154 -- means the current line is empty). 155 156 ------------------------- 157 -- Buffer Save/Restore -- 158 ------------------------- 159 160 -- This facility allows the current line buffer to be saved and restored 161 162 type Saved_Output_Buffer is private; 163 -- Type used for Save/Restore_Buffer 164 165 Buffer_Max : constant := Hostparm.Max_Line_Length; 166 -- Maximal size of a buffered output line 167 168 function Save_Output_Buffer return Saved_Output_Buffer; 169 -- Save current line buffer and reset line buffer to empty 170 171 procedure Restore_Output_Buffer (S : Saved_Output_Buffer); 172 -- Restore previously saved output buffer. The value in S is not affected 173 -- so it is legitimate to restore a buffer more than once. 174 175 -------------------------- 176 -- Debugging Procedures -- 177 -------------------------- 178 179 -- The following procedures are intended only for debugging purposes, 180 -- for temporary insertion into the text in environments where a debugger 181 -- is not available. They all have non-standard very short lower case 182 -- names, precisely to make sure that they are only used for debugging. 183 184 procedure w (C : Character); 185 -- Dump quote, character, quote, followed by line return 186 187 procedure w (S : String); 188 -- Dump string followed by line return 189 190 procedure w (V : Int); 191 -- Dump integer followed by line return 192 193 procedure w (B : Boolean); 194 -- Dump Boolean followed by line return 195 196 procedure w (L : String; C : Character); 197 -- Dump contents of string followed by blank, quote, character, quote 198 199 procedure w (L : String; S : String); 200 -- Dump two strings separated by blanks, followed by line return 201 202 procedure w (L : String; V : Int); 203 -- Dump contents of string followed by blank, integer, line return 204 205 procedure w (L : String; B : Boolean); 206 -- Dump contents of string followed by blank, Boolean, line return 207 208private 209 210 type Saved_Output_Buffer is record 211 Buffer : String (1 .. Buffer_Max + 1); 212 Next_Col : Positive; 213 Cur_Indentation : Natural; 214 end record; 215 216end Output; 217