1 /* Output generating routines for GDB. 2 3 Copyright (C) 1999-2023 Free Software Foundation, Inc. 4 5 Contributed by Cygnus Solutions. 6 Written by Fernando Nasser for Cygnus. 7 8 This file is part of GDB. 9 10 This program is free software; you can redistribute it and/or modify 11 it under the terms of the GNU General Public License as published by 12 the Free Software Foundation; either version 3 of the License, or 13 (at your option) any later version. 14 15 This program is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU General Public License for more details. 19 20 You should have received a copy of the GNU General Public License 21 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 22 23 #ifndef UI_OUT_H 24 #define UI_OUT_H 1 25 26 #include <vector> 27 28 #include "gdbsupport/enum-flags.h" 29 #include "ui-style.h" 30 31 class ui_out_level; 32 class ui_out_table; 33 struct ui_file; 34 35 /* the current ui_out */ 36 37 /* FIXME: This should not be a global but something passed down from main.c 38 or top.c. */ 39 extern struct ui_out **current_ui_current_uiout_ptr (void); 40 #define current_uiout (*current_ui_current_uiout_ptr ()) 41 42 /* alignment enum */ 43 enum ui_align 44 { 45 ui_left = -1, 46 ui_center, 47 ui_right, 48 ui_noalign 49 }; 50 51 /* flags enum */ 52 enum ui_out_flag 53 { 54 ui_source_list = (1 << 0), 55 fix_multi_location_breakpoint_output = (1 << 1), 56 /* This indicates that %pF should be disallowed in a printf format 57 string. */ 58 disallow_ui_out_field = (1 << 2), 59 fix_breakpoint_script_output = (1 << 3), 60 }; 61 62 DEF_ENUM_FLAGS_TYPE (ui_out_flag, ui_out_flags); 63 64 /* Prototypes for ui-out API. */ 65 66 /* A result is a recursive data structure consisting of lists and 67 tuples. */ 68 69 enum ui_out_type 70 { 71 ui_out_type_tuple, 72 ui_out_type_list 73 }; 74 75 /* The possible kinds of fields. */ 76 enum class field_kind 77 { 78 /* "FIELD_STRING" needs a funny name to avoid clashes with tokens 79 named "STRING". See PR build/25250. FIELD_SIGNED is given a 80 similar name for consistency. */ 81 FIELD_SIGNED, 82 FIELD_STRING, 83 }; 84 85 /* The base type of all fields that can be emitted using %pF. */ 86 87 struct base_field_s 88 { 89 const char *name; 90 field_kind kind; 91 }; 92 93 /* A signed integer field, to be passed to %pF in format strings. */ 94 95 struct signed_field_s : base_field_s 96 { 97 LONGEST val; 98 }; 99 100 /* Construct a temporary signed_field_s on the caller's stack and 101 return a pointer to the constructed object. We use this because 102 it's not possible to pass a reference via va_args. */ 103 104 static inline signed_field_s * 105 signed_field (const char *name, LONGEST val, 106 signed_field_s &&tmp = {}) 107 { 108 tmp.name = name; 109 tmp.kind = field_kind::FIELD_SIGNED; 110 tmp.val = val; 111 return &tmp; 112 } 113 114 /* A string field, to be passed to %pF in format strings. */ 115 116 struct string_field_s : base_field_s 117 { 118 const char *str; 119 }; 120 121 /* Construct a temporary string_field_s on the caller's stack and 122 return a pointer to the constructed object. We use this because 123 it's not possible to pass a reference via va_args. */ 124 125 static inline string_field_s * 126 string_field (const char *name, const char *str, 127 string_field_s &&tmp = {}) 128 { 129 tmp.name = name; 130 tmp.kind = field_kind::FIELD_STRING; 131 tmp.str = str; 132 return &tmp; 133 } 134 135 /* A styled string. */ 136 137 struct styled_string_s 138 { 139 /* The style. */ 140 ui_file_style style; 141 142 /* The string. */ 143 const char *str; 144 }; 145 146 /* Construct a temporary styled_string_s on the caller's stack and 147 return a pointer to the constructed object. We use this because 148 it's not possible to pass a reference via va_args. */ 149 150 static inline styled_string_s * 151 styled_string (const ui_file_style &style, const char *str, 152 styled_string_s &&tmp = {}) 153 { 154 tmp.style = style; 155 tmp.str = str; 156 return &tmp; 157 } 158 159 class ui_out 160 { 161 public: 162 163 explicit ui_out (ui_out_flags flags = 0); 164 virtual ~ui_out (); 165 166 void push_level (ui_out_type type); 167 void pop_level (ui_out_type type); 168 169 /* A table can be considered a special tuple/list combination with the 170 implied structure: ``table = { hdr = { header, ... } , body = [ { 171 field, ... }, ... ] }''. If NR_ROWS is negative then there is at 172 least one row. */ 173 174 void table_begin (int nr_cols, int nr_rows, const std::string &tblid); 175 void table_header (int width, ui_align align, const std::string &col_name, 176 const std::string &col_hdr); 177 void table_body (); 178 void table_end (); 179 180 void begin (ui_out_type type, const char *id); 181 void end (ui_out_type type); 182 183 void field_signed (const char *fldname, LONGEST value); 184 void field_fmt_signed (int width, ui_align align, const char *fldname, 185 LONGEST value); 186 /* Like field_signed, but print an unsigned value. */ 187 void field_unsigned (const char *fldname, ULONGEST value); 188 void field_core_addr (const char *fldname, struct gdbarch *gdbarch, 189 CORE_ADDR address); 190 void field_string (const char *fldname, const char *string, 191 const ui_file_style &style = ui_file_style ()); 192 void field_string (const char *fldname, const std::string &string, 193 const ui_file_style &style = ui_file_style ()) 194 { 195 field_string (fldname, string.c_str (), style); 196 } 197 void field_stream (const char *fldname, string_file &stream, 198 const ui_file_style &style = ui_file_style ()); 199 void field_skip (const char *fldname); 200 void field_fmt (const char *fldname, const char *format, ...) 201 ATTRIBUTE_PRINTF (3, 4); 202 void field_fmt (const char *fldname, const ui_file_style &style, 203 const char *format, ...) 204 ATTRIBUTE_PRINTF (4, 5); 205 206 void spaces (int numspaces); 207 void text (const char *string); 208 void text (const std::string &string) { text (string.c_str ()); } 209 210 /* Output a printf-style formatted string. In addition to the usual 211 printf format specs, this supports a few GDB-specific 212 formatters: 213 214 - '%pF' - output a field. 215 216 The argument is a field, wrapped in any of the base_field_s 217 subclasses. signed_field for integer fields, string_field for 218 string fields. This is preferred over separate 219 uiout->field_signed(), uiout_>field_string() etc. calls when 220 the formatted message is translatable. E.g.: 221 222 uiout->message (_("\nWatchpoint %pF deleted because the program has " 223 "left the block in\n" 224 "which its expression is valid.\n"), 225 signed_field ("wpnum", b->number)); 226 227 - '%p[' - output the following text in a specified style. 228 '%p]' - output the following text in the default style. 229 230 The argument to '%p[' is a ui_file_style pointer. The argument 231 to '%p]' must be nullptr. 232 233 This is useful when you want to output some portion of a string 234 literal in some style. E.g.: 235 236 uiout->message (_(" %p[<repeats %u times>%p]"), 237 metadata_style.style ().ptr (), 238 reps, repeats, nullptr); 239 240 - '%ps' - output a styled string. 241 242 The argument is the result of a call to styled_string. This is 243 useful when you want to output some runtime-generated string in 244 some style. E.g.: 245 246 uiout->message (_("this is a target address %ps.\n"), 247 styled_string (address_style.style (), 248 paddress (gdbarch, pc))); 249 250 Note that these all "abuse" the %p printf format spec, in order 251 to be compatible with GCC's printf format checking. This is OK 252 because code in GDB that wants to print a host address should use 253 host_address_to_string instead of %p. */ 254 void message (const char *format, ...) ATTRIBUTE_PRINTF (2, 3); 255 void vmessage (const ui_file_style &in_style, 256 const char *format, va_list args) ATTRIBUTE_PRINTF (3, 0); 257 258 void wrap_hint (int indent); 259 260 void flush (); 261 262 /* Redirect the output of a ui_out object temporarily. */ 263 void redirect (ui_file *outstream); 264 265 ui_out_flags test_flags (ui_out_flags mask); 266 267 /* HACK: Code in GDB is currently checking to see the type of ui_out 268 builder when determining which output to produce. This function is 269 a hack to encapsulate that test. Once GDB manages to separate the 270 CLI/MI from the core of GDB the problem should just go away .... */ 271 272 bool is_mi_like_p () const; 273 274 bool query_table_field (int colno, int *width, int *alignment, 275 const char **col_name); 276 277 /* Return true if this stream is prepared to handle style 278 escapes. */ 279 virtual bool can_emit_style_escape () const = 0; 280 281 /* An object that starts and finishes displaying progress updates. */ 282 class progress_update 283 { 284 public: 285 /* Represents the printing state of a progress update. */ 286 enum state 287 { 288 /* Printing will start with the next update. */ 289 START, 290 /* Printing has already started. */ 291 WORKING, 292 /* Progress bar printing has already started. */ 293 BAR 294 }; 295 296 /* SHOULD_PRINT indicates whether something should be printed for a tty. */ 297 progress_update () 298 { 299 m_uiout = current_uiout; 300 m_uiout->do_progress_start (); 301 } 302 303 ~progress_update () 304 { 305 306 } 307 308 progress_update (const progress_update &) = delete; 309 progress_update &operator= (const progress_update &) = delete; 310 311 /* Emit some progress for this progress meter. Includes current 312 amount of progress made and total amount in the display. */ 313 void update_progress (const std::string& msg, const char *unit, 314 double cur, double total) 315 { 316 m_uiout->do_progress_notify (msg, unit, cur, total); 317 } 318 319 /* Emit some progress for this progress meter. */ 320 void update_progress (const std::string& msg) 321 { 322 m_uiout->do_progress_notify (msg, "", -1, -1); 323 } 324 private: 325 326 struct ui_out *m_uiout; 327 }; 328 329 virtual void do_progress_end () = 0; 330 331 protected: 332 333 virtual void do_table_begin (int nbrofcols, int nr_rows, const char *tblid) 334 = 0; 335 virtual void do_table_body () = 0; 336 virtual void do_table_end () = 0; 337 virtual void do_table_header (int width, ui_align align, 338 const std::string &col_name, 339 const std::string &col_hdr) = 0; 340 341 virtual void do_begin (ui_out_type type, const char *id) = 0; 342 virtual void do_end (ui_out_type type) = 0; 343 virtual void do_field_signed (int fldno, int width, ui_align align, 344 const char *fldname, LONGEST value) = 0; 345 virtual void do_field_unsigned (int fldno, int width, ui_align align, 346 const char *fldname, ULONGEST value) = 0; 347 virtual void do_field_skip (int fldno, int width, ui_align align, 348 const char *fldname) = 0; 349 virtual void do_field_string (int fldno, int width, ui_align align, 350 const char *fldname, const char *string, 351 const ui_file_style &style) = 0; 352 virtual void do_field_fmt (int fldno, int width, ui_align align, 353 const char *fldname, const ui_file_style &style, 354 const char *format, va_list args) 355 ATTRIBUTE_PRINTF (7, 0) = 0; 356 virtual void do_spaces (int numspaces) = 0; 357 virtual void do_text (const char *string) = 0; 358 virtual void do_message (const ui_file_style &style, 359 const char *format, va_list args) 360 ATTRIBUTE_PRINTF (3,0) = 0; 361 virtual void do_wrap_hint (int indent) = 0; 362 virtual void do_flush () = 0; 363 virtual void do_redirect (struct ui_file *outstream) = 0; 364 365 virtual void do_progress_start () = 0; 366 virtual void do_progress_notify (const std::string &, const char *, 367 double, double) = 0; 368 369 /* Set as not MI-like by default. It is overridden in subclasses if 370 necessary. */ 371 372 virtual bool do_is_mi_like_p () const 373 { return false; } 374 375 private: 376 void call_do_message (const ui_file_style &style, const char *format, 377 ...); 378 379 ui_out_flags m_flags; 380 381 /* Vector to store and track the ui-out levels. */ 382 std::vector<std::unique_ptr<ui_out_level>> m_levels; 383 384 /* A table, if any. At present only a single table is supported. */ 385 std::unique_ptr<ui_out_table> m_table_up; 386 387 void verify_field (int *fldno, int *width, ui_align *align); 388 389 int level () const; 390 ui_out_level *current_level () const; 391 }; 392 393 /* Start a new tuple or list on construction, and end it on 394 destruction. Normally this is used via the typedefs 395 ui_out_emit_tuple and ui_out_emit_list. */ 396 template<ui_out_type Type> 397 class ui_out_emit_type 398 { 399 public: 400 401 ui_out_emit_type (struct ui_out *uiout, const char *id) 402 : m_uiout (uiout) 403 { 404 uiout->begin (Type, id); 405 } 406 407 ~ui_out_emit_type () 408 { 409 m_uiout->end (Type); 410 } 411 412 DISABLE_COPY_AND_ASSIGN (ui_out_emit_type<Type>); 413 414 private: 415 416 struct ui_out *m_uiout; 417 }; 418 419 typedef ui_out_emit_type<ui_out_type_tuple> ui_out_emit_tuple; 420 typedef ui_out_emit_type<ui_out_type_list> ui_out_emit_list; 421 422 /* Start a new table on construction, and end the table on 423 destruction. */ 424 class ui_out_emit_table 425 { 426 public: 427 428 ui_out_emit_table (struct ui_out *uiout, int nr_cols, int nr_rows, 429 const char *tblid) 430 : m_uiout (uiout) 431 { 432 m_uiout->table_begin (nr_cols, nr_rows, tblid); 433 } 434 435 ~ui_out_emit_table () 436 { 437 m_uiout->table_end (); 438 } 439 440 ui_out_emit_table (const ui_out_emit_table &) = delete; 441 ui_out_emit_table &operator= (const ui_out_emit_table &) = delete; 442 443 private: 444 445 struct ui_out *m_uiout; 446 }; 447 448 /* On construction, redirect a uiout to a given stream. On 449 destruction, pop the last redirection by calling the uiout's 450 redirect method with a NULL parameter. */ 451 class ui_out_redirect_pop 452 { 453 public: 454 455 ui_out_redirect_pop (ui_out *uiout, ui_file *stream) 456 : m_uiout (uiout) 457 { 458 m_uiout->redirect (stream); 459 } 460 461 ~ui_out_redirect_pop () 462 { 463 m_uiout->redirect (NULL); 464 } 465 466 ui_out_redirect_pop (const ui_out_redirect_pop &) = delete; 467 ui_out_redirect_pop &operator= (const ui_out_redirect_pop &) = delete; 468 469 private: 470 struct ui_out *m_uiout; 471 }; 472 473 #endif /* UI_OUT_H */ 474