projects / binutils-gdb.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 56ddd99)
* gdbint.texinfo (User Interface): Update ui-out documentation to
authorAndrew Cagney <cagney@redhat.com>
Sat, 7 Jul 2001 16:20:57 +0000 (16:20 +0000)
committerAndrew Cagney <cagney@redhat.com>
Sat, 7 Jul 2001 16:20:57 +0000 (16:20 +0000)
refelect recent UI/MI updates.

gdb/doc/ChangeLog patch | blob | history
gdb/doc/gdbint.texinfo patch | blob | history

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index ef38bc5c299570462c19e1d367e6b11b610ec6fd..1b103b8aded33f5095f0a3f0d492398932a1988a 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2001-07-04  Andrew Cagney  <ac131313@redhat.com>
+
+       * gdbint.texinfo (User Interface): Update ui-out documentation to
+       refelect recent UI/MI updates.
+
 2001-07-04  Andrew Cagney  <ac131313@redhat.com>
 
        * gdb.texinfo (Mode Options): Mention the mi0 and mi1
 2001-07-04  Andrew Cagney  <ac131313@redhat.com>
 
        * gdb.texinfo (Mode Options): Mention the mi0 and mi1
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index f772be5cb4c7f77480df6516e8550520fd4770fa..5e5cbb22a0fca6f136c9f1d3dc03b32b57961ee6 100644 (file)
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -743,7 +743,7 @@ aliases to set the deprecated flag.  @code{deprecate_cmd} takes a
 return value from @code{add_com} or @code{add_cmd} to deprecate the
 command immediately after it is created.
 
 return value from @code{add_com} or @code{add_cmd} to deprecate the
 command immediately after it is created.
 
-The first time a comamnd is used the user will be warned and offered a
+The first time a command is used the user will be warned and offered a
 replacement (if one exists). Note that the replacement string passed to
 @code{deprecate_cmd} should be the full name of the command, i.e. the
 entire string the user should type at the command line.
 replacement (if one exists). Note that the replacement string passed to
 @code{deprecate_cmd} should be the full name of the command, i.e. the
 entire string the user should type at the command line.
@@ -808,157 +808,183 @@ machine oriented formatting--a more terse formatting to allow for easy
 parsing by programs which read @value{GDBN}'s output
 
 @item
 parsing by programs which read @value{GDBN}'s output
 
 @item
-annotation, whose purpose is to help a GUI (such as GDBTK or Emacs) to
-identify interesting parts in the output
+annotation, whose purpose is to help legacy GUIs to identify interesting
+parts in the output
 @end itemize
 
 The @code{ui_out} routines take care of the first three aspects.
 @end itemize
 
 The @code{ui_out} routines take care of the first three aspects.
-Annotations are provided by separate annotation routines.  Note that
-use of annotations for an interface between a GUI and @value{GDBN} is
+Annotations are provided by separate annotation routines.  Note that use
+of annotations for an interface between a GUI and @value{GDBN} is
 deprecated.
 
 deprecated.
 
-Output can be in the form of a single item, which we call a
-@dfn{field}; a @dfn{list} of fields; or a @dfn{table}, which is a list
-of fields with a header.  In a BNF-like form:
+Output can be in the form of a single item, which we call a @dfn{field};
+a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
+non-identical fields; or a @dfn{table}, which is a tuple consisting of a
+header and a body.  In a BNF-like form:
 
 
-@example
-<field> ::= any single item of data kept by gdb ;;
-
-<list> ::= @{ <field> @} ;;
-
-<table> ::= <header> @{ <list> @} ;;
-
-<header> ::= @{ <column> @} ;;
-
-<column> ::= <width> <alignment> <title> ;;
-@end example
+@table @code
+@item <table> @expansion{}
+@code{<header> <body>}
+@item <header> @expansion{}
+@code{@{ <column> @}}
+@item <column> @expansion{}
+@code{<width> <alignment> <title>}
+@item <body> @expansion{}
+@code{@{<row>@}}
+@end table
 
 
 @subsection General Conventions
 
 
 
 @subsection General Conventions
 
-All @code{ui_out} routines currently are of type @code{void}, except
-for @code{ui_out_stream_new} which returns a pointer to the newly
-created object.
+Most @code{ui_out} routines are of type @code{void}, the exceptions are
+@code{ui_out_stream_new} (which returns a pointer to the newly created
+object) and the @code{make_cleanup} routines.
 
 
-The first parameter is always the @code{ui_out} vector object, a
-pointer to a @code{struct ui_out}.
+The first parameter is always the @code{ui_out} vector object, a pointer
+to a @code{struct ui_out}.
 
 
-The @var{format} parameter is like in @code{printf} family of
-functions.  When it is present, there is usually also a variable list
-of arguments used to satisfy the @code{%} specifiers in the supplied
+The @var{format} parameter is like in @code{printf} family of functions.
+When it is present, there must also be a variable list of arguments
+sufficient used to satisfy the @code{%} specifiers in the supplied
 format.
 
 format.
 
-When a character string argument is not used in a @code{ui_out}
-function call, a @code{NULL} pointer has to be supplied instead.
+When a character string argument is not used in a @code{ui_out} function
+call, a @code{NULL} pointer has to be supplied instead.
 
 
 
 
-@subsection Table and List Functions
+@subsection Table, Tuple and List Functions
 
 @cindex list output functions
 @cindex table output functions
 
 @cindex list output functions
 @cindex table output functions
-This section introduces @code{ui_out} routines for building lists and
-tables.  The routines to output the actual data items (fields) are
-presented in the next section.
-
-To recap: A @dfn{list} is a sequence of @dfn{fields} with information
-about an object; a @dfn{table} is a list of lists, each on a separate
-line, prefixed by a @dfn{header} line with the column @dfn{titles}.
+@cindex tuple output functions
+This section introduces @code{ui_out} routines for building lists,
+tuples and tables.  The routines to output the actual data items
+(fields) are presented in the next section.
 
 
-Use the table functions if your output is composed of a list of fields
-for several objects and the console output should have a header.  Use
-this even when you are listing just one object but you still want the
-header.
+To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
+containing information about an object; a @dfn{list} is a sequence of
+fields where each field describes an identical object.
 
 
-Use the list functions for the output of each object of a table or if
-your output consists of a single list of fields.
-
-You can nest a list into a table, but not the other way around.
+Use the @dfn{table} functions when your output consists of a list of
+rows (tuples) and the console output should include a heading.  Use this
+even when you are listing just one object but you still want the header.
 
 @cindex nesting level in @code{ui_out} functions
 
 @cindex nesting level in @code{ui_out} functions
-Lists can also be nested: some of your fields may be lists or
-@dfn{tuples}--@code{@{@var{name},@var{value}@}} pairs.  The maximum
-nesting level is currently 4.
+Tables can not be nested.  Tuples and lists can be nested up to a
+maximum of five levels.
 
 The overall structure of the table output code is something like this:
 
 @example
   ui_out_table_begin
     ui_out_table_header
 
 The overall structure of the table output code is something like this:
 
 @example
   ui_out_table_begin
     ui_out_table_header
-    ...
+    @dots{}
     ui_out_table_body
     ui_out_table_body
-      ui_out_list_begin
+      ui_out_tuple_begin
         ui_out_field_*
         ui_out_field_*
-        ...
-      ui_out_list_end
-      ...
+        @dots{}
+      ui_out_tuple_end
+      @dots{}
   ui_out_table_end
 @end example
 
   ui_out_table_end
 @end example
 
-Here's the description of table- and list-related @code{ui_out}
+Here is the description of table-, tuple- and list-related @code{ui_out}
 functions:
 
 functions:
 
-@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, char *@var{tblid})
-The function @code{ui_out_table_begin} marks the beginning of the
-output of a table.  It should always be called before any other
-@code{ui_out} function for a given table.  @var{nbrofcols} is the
-number of columns in the table, and @var{tblid} is an optional string
-identifying the table.  The string pointed to by @var{tblid} is copied
-by the implementation of @code{ui_out_table_begin}, so the application
-can free the string if it was @code{malloc}ed.
+@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
+The function @code{ui_out_table_begin} marks the beginning of the output
+of a table.  It should always be called before any other @code{ui_out}
+function for a given table.  @var{nbrofcols} is the number of columns in
+the table. @var{nr_rows} is the number of rows in the table.
+@var{tblid} is an optional string identifying the table.  The string
+pointed to by @var{tblid} is copied by the implementation of
+@code{ui_out_table_begin}, so the application can free the string if it
+was @code{malloc}ed.
 
 The companion function @code{ui_out_table_end}, described below, marks
 the end of the table's output.
 @end deftypefun
 
 
 The companion function @code{ui_out_table_end}, described below, marks
 the end of the table's output.
 @end deftypefun
 
-@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, char *@var{colhdr})
-@code{ui_out_table_header} provides the header information for a
-single table column.  You call this function several times, one each
-for every column of the table, after @code{ui_out_table_begin}, but
-before @code{ui_out_table_body}.
+@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
+@code{ui_out_table_header} provides the header information for a single
+table column.  You call this function several times, one each for every
+column of the table, after @code{ui_out_table_begin}, but before
+@code{ui_out_table_body}.
 
 The value of @var{width} gives the column width in characters.  The
 value of @var{alignment} is one of @code{left}, @code{center}, and
 @code{right}, and it specifies how to align the header: left-justify,
 center, or right-justify it.  @var{colhdr} points to a string that
 specifies the column header; the implementation copies that string, so
 
 The value of @var{width} gives the column width in characters.  The
 value of @var{alignment} is one of @code{left}, @code{center}, and
 @code{right}, and it specifies how to align the header: left-justify,
 center, or right-justify it.  @var{colhdr} points to a string that
 specifies the column header; the implementation copies that string, so
-column header strings in @code{malloc}ed storage can be freed after
-the call.
+column header strings in @code{malloc}ed storage can be freed after the
+call.
 @end deftypefun
 
 @deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
 @end deftypefun
 
 @deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
-This function marks the end of header information and the beginning of
-table body output.  It doesn't by itself produce any data output; that
-is done by the list and field output functions described below.
+This function delimits the table header from the table body.
 @end deftypefun
 
 @deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
 @end deftypefun
 
 @deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
-This function signals the end of a table's output.  It should be
-called after the table body has been produced by the list and field
-output functions.
+This function signals the end of a table's output.  It should be called
+after the table body has been produced by the list and field output
+functions.
 
 There should be exactly one call to @code{ui_out_table_end} for each
 
 There should be exactly one call to @code{ui_out_table_end} for each
-call to @code{ui_out_table_begin}, otherwise the @code{ui_out}
-functions will signal an internal error.
+call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
+will signal an internal error.
 @end deftypefun
 
 @end deftypefun
 
-The output of the lists that represent the table rows must follow the
+The output of the tuples that represent the table rows must follow the
 call to @code{ui_out_table_body} and precede the call to
 call to @code{ui_out_table_body} and precede the call to
-@code{ui_out_table_end}.  You produce the lists by calling
-@code{ui_out_list_begin} and @code{ui_out_list_end}, with suitable
+@code{ui_out_table_end}.  You build a tuple by calling
+@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
 calls to functions which actually output fields between them.
 
 calls to functions which actually output fields between them.
 
-@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, char *@var{lstid})
-This function marks the beginning or a list output.  @var{lstid}
-points to an optional string that identifies the list; it is copied by
-the implementation, and so strings in @code{malloc}ed storage can be
-freed after the call.
+@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
+This function marks the beginning of a tuple output.  @var{id} points
+to an optional string that identifies the tuple; it is copied by the
+implementation, and so strings in @code{malloc}ed storage can be freed
+after the call.
+@end deftypefun
+
+@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
+This function signals an end of a tuple output.  There should be exactly
+one call to @code{ui_out_tuple_end} for each call to
+@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
+be signaled.
+@end deftypefun
+
+@deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
+This function first opens the tuple and then establishes a cleanup
+(@pxref{Coding, Cleanups}) to close the tuple.  It provides a convenient
+and correct implementation of the non-portable@footnote{The function
+cast is not portable ISO-C.} code sequence:
+@smallexample
+struct cleanup *old_cleanup;
+ui_out_tuple_begin (uiout, "...");
+old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
+                            uiout);
+@end smallexample
+@end deftypefun
+
+@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
+This function marks the beginning of a list output.  @var{id} points to
+an optional string that identifies the list; it is copied by the
+implementation, and so strings in @code{malloc}ed storage can be freed
+after the call.
 @end deftypefun
 
 @deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
 @end deftypefun
 
 @deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
-This function signals an end of a list output.  There should be
-exactly one call to @code{ui_out_list_end} for each call to
-@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error
-will be signaled.
+This function signals an end of a list output.  There should be exactly
+one call to @code{ui_out_list_end} for each call to
+@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
+be signaled.
+@end deftypefun
+
+@deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
+Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
+opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
+that will close the list.list.
 @end deftypefun
 
 @subsection Item Output Functions
 @end deftypefun
 
 @subsection Item Output Functions
@@ -983,17 +1009,17 @@ This generic function should be used only when it is not possible to
 use one of the specialized versions (see below).
 @end deftypefun
 
 use one of the specialized versions (see below).
 @end deftypefun
 
-@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, char *@var{fldname}, int @var{value})
+@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
 This function outputs a value of an @code{int} variable.  It uses the
 @code{"%d"} output conversion specification.  @var{fldname} specifies
 the name of the field.
 @end deftypefun
 
 This function outputs a value of an @code{int} variable.  It uses the
 @code{"%d"} output conversion specification.  @var{fldname} specifies
 the name of the field.
 @end deftypefun
 
-@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, char *@var{fldname}, CORE_ADDR @var{address})
+@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
 This function outputs an address.
 @end deftypefun
 
 This function outputs an address.
 @end deftypefun
 
-@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, char *@var{fldname}, const char *@var{string})
+@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
 This function outputs a string using the @code{"%s"} conversion
 specification.
 @end deftypefun
 This function outputs a string using the @code{"%s"} conversion
 specification.
 @end deftypefun
@@ -1025,7 +1051,7 @@ This functions destroys a @code{ui_stream} object specified by
 @var{streambuf}.
 @end deftypefun
 
 @var{streambuf}.
 @end deftypefun
 
-@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, char *@var{fieldname}, struct ui_stream *@var{streambuf})
+@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
 This function consumes all the data accumulated in
 @code{streambuf->stream} and outputs it like
 @code{ui_out_field_string} does.  After a call to
 This function consumes all the data accumulated in
 @code{streambuf->stream} and outputs it like
 @code{ui_out_field_string} does.  After a call to
@@ -1060,13 +1086,13 @@ same buffer twice.
 
 @subsection Utility Output Functions
 
 
 @subsection Utility Output Functions
 
-@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, char *@var{fldname})
+@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
 This function skips a field in a table.  Use it if you have to leave
 an empty field without disrupting the table alignment.  The argument
 @var{fldname} specifies a name for the (missing) filed.
 @end deftypefun
 
 This function skips a field in a table.  Use it if you have to leave
 an empty field without disrupting the table alignment.  The argument
 @var{fldname} specifies a name for the (missing) filed.
 @end deftypefun
 
-@deftypefun void ui_out_text (struct ui_out *@var{uiout}, char *@var{string})
+@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
 This function outputs the text in @var{string} in a way that makes it
 easy to be read by humans.  For example, the console implementation of
 this method filters the text through a built-in pager, to prevent it
 This function outputs the text in @var{string} in a way that makes it
 easy to be read by humans.  For example, the console implementation of
 this method filters the text through a built-in pager, to prevent it
@@ -1085,7 +1111,7 @@ text produced by @code{ui_out_text} with the rest of the table or
 list.
 @end deftypefun
 
 list.
 @end deftypefun
 
-@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, char *@var{format}, ...)
+@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
 This function produces a formatted message, provided that the current
 verbosity level is at least as large as given by @var{verbosity}.  The
 current verbosity level is specified by the user with the @samp{set
 This function produces a formatted message, provided that the current
 verbosity level is at least as large as given by @var{verbosity}.  The
 current verbosity level is specified by the user with the @samp{set
@@ -1153,33 +1179,42 @@ The original code was:
 Here's the new version:
 
 @example
 Here's the new version:
 
 @example
- if (!found_a_breakpoint++)
-   @{
-     annotate_breakpoints_headers ();
-     if (addressprint)
-       ui_out_table_begin (ui, 6);
-     else
-       ui_out_table_begin (ui, 5);
-
-     annotate_field (0);
-     ui_out_table_header (ui, 4, left, "Num");
-     annotate_field (1);
-     ui_out_table_header (ui, 15, left, "Type");
-     annotate_field (2);
-     ui_out_table_header (ui, 5, left, "Disp");
-     annotate_field (3);
-     ui_out_table_header (ui, 4, left, "Enb");
-     if (addressprint)
-       @{
-         annotate_field (4);
-         ui_out_table_header (ui, 11, left, "Address");
-       @}
-     annotate_field (5);
-     ui_out_table_header (ui, 40, left, "What");
+  nr_printable_breakpoints = @dots{};
 
 
-     ui_out_table_body (ui);
-     annotate_breakpoints_table ();
-   @}
+  if (addressprint)
+    ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
+  else
+    ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
+
+  if (nr_printable_breakpoints > 0)
+    annotate_breakpoints_headers ();
+  if (nr_printable_breakpoints > 0)
+    annotate_field (0);
+  ui_out_table_header (uiout, 3, ui_left, "number", "Num");            /* 1 */
+  if (nr_printable_breakpoints > 0)
+    annotate_field (1);
+  ui_out_table_header (uiout, 14, ui_left, "type", "Type");            /* 2 */
+  if (nr_printable_breakpoints > 0)
+    annotate_field (2);
+  ui_out_table_header (uiout, 4, ui_left, "disp", "Disp");             /* 3 */
+  if (nr_printable_breakpoints > 0)
+    annotate_field (3);
+  ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb");   /* 4 */
+  if (addressprint)
+    @{
+     if (nr_printable_breakpoints > 0)
+       annotate_field (4);
+     if (TARGET_ADDR_BIT <= 32)
+       ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
+     else
+       ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
+    @}
+  if (nr_printable_breakpoints > 0)
+    annotate_field (5);
+  ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
+  ui_out_table_body (uiout);
+  if (nr_printable_breakpoints > 0)
+    annotate_breakpoints_table ();
 @end example
 
 This example, from the @code{print_one_breakpoint} function, shows how
 @end example
 
 This example, from the @code{print_one_breakpoint} function, shows how
@@ -1200,13 +1235,14 @@ in the above example.  The original code was:
    printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
    annotate_field (3);
    printf_filtered ("%-3c ", bpenables[(int)b->enable]);
    printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
    annotate_field (3);
    printf_filtered ("%-3c ", bpenables[(int)b->enable]);
+   @dots{}
 @end example
 
 This is the new version:
 
 @example
    annotate_record ();
 @end example
 
 This is the new version:
 
 @example
    annotate_record ();
-   ui_out_list_begin (uiout, "bkpt");
+   ui_out_tuple_begin (uiout, "bkpt");
    annotate_field (0);
    ui_out_field_int (uiout, "number", b->number);
    annotate_field (1);
    annotate_field (0);
    ui_out_field_int (uiout, "number", b->number);
    annotate_field (1);
@@ -1219,6 +1255,7 @@ This is the new version:
    ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
    annotate_field (3);
    ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
    ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
    annotate_field (3);
    ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
+   @dots{}
 @end example
 
 This example, also from @code{print_one_breakpoint}, shows how to
 @end example
 
 This example, also from @code{print_one_breakpoint}, shows how to