gdb/unittests/command-def-selftests.c

   1 /* Self tests for GDB command definitions for GDB, the GNU debugger.
   2
   3    Copyright (C) 2019-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #include "defs.h"
  21 #include "cli/cli-cmds.h"
  22 #include "cli/cli-decode.h"
  23 #include "gdbsupport/selftest.h"
  24
  25 #include <map>
  26
  27 namespace selftests {
  28
  29 /* Verify some invariants of GDB commands documentation.  */
  30
  31 namespace help_doc_tests {
  32
  33 static unsigned int nr_failed_invariants;
  34
  35 /* Report a broken invariant and increments nr_failed_invariants.  */
  36
  37 static void
  38 broken_doc_invariant (const char *prefix, const char *name, const char *msg)
  39 {
  40   gdb_printf ("help doc broken invariant: command '%s%s' help doc %s\n",
  41               prefix, name, msg);
  42   nr_failed_invariants++;
  43 }
  44
  45 /* Recursively walk the commandlist structures, and check doc invariants:
  46    - The first line of the doc must end with a '.'.
  47    - the doc must not end with a new line.
  48   If an invariant is not respected, produce a message and increment
  49   nr_failed_invariants.
  50   Note that we do not call SELF_CHECK in this function, as we want
  51   all commands to be checked before making the test fail.  */
  52
  53 static void
  54 check_doc (struct cmd_list_element *commandlist, const char *prefix)
  55 {
  56   struct cmd_list_element *c;
  57
  58   /* Walk through the commands.  */
  59   for (c = commandlist; c; c = c->next)
  60     {
  61       /* Checks the doc has a first line terminated with a '.'.  */
  62       const char *p = c->doc;
  63
  64       /* Position p on the first LF, or on terminating null byte.  */
  65       while (*p && *p != '\n')
  66         p++;
  67       if (p == c->doc)
  68         broken_doc_invariant
  69           (prefix, c->name,
  70            "is missing the first line terminated with a '.' character");
  71       else if (*(p-1) != '.')
  72         broken_doc_invariant
  73           (prefix, c->name,
  74            "first line is not terminated with a '.' character");
  75
  76       /* Checks the doc is not terminated with a new line.  */
  77       if (c->doc[strlen (c->doc) - 1] == '\n')
  78         broken_doc_invariant
  79           (prefix, c->name,
  80            "has a superfluous trailing end of line");
  81
  82       /* Check if this command has subcommands and is not an
  83          abbreviation.  We skip checking subcommands of abbreviations
  84          in order to avoid duplicates in the output.  */
  85       if (c->is_prefix () && !c->abbrev_flag)
  86         {
  87           /* Recursively call ourselves on the subcommand list,
  88              passing the right prefix in.  */
  89           check_doc (*c->subcommands, c->prefixname ().c_str ());
  90         }
  91     }
  92 }
  93
  94 static void
  95 help_doc_invariants_tests ()
  96 {
  97   nr_failed_invariants = 0;
  98   check_doc (cmdlist, "");
  99   SELF_CHECK (nr_failed_invariants == 0);
 100 }
 101
 102 } /* namespace help_doc_tests */
 103
 104 /* Verify some invariants of GDB command structure.  */
 105
 106 namespace command_structure_tests {
 107
 108 /* Nr of commands in which a duplicated list is found.  */
 109 static unsigned int nr_duplicates = 0;
 110 /* Nr of commands in a list having no valid prefix cmd.  */
 111 static unsigned int nr_invalid_prefixcmd = 0;
 112
 113 /* A map associating a list with the prefix leading to it.  */
 114
 115 static std::map<cmd_list_element **, const char *> lists;
 116
 117 /* Store each command list in lists, associated with the prefix to reach it.  A
 118    list must only be found once.
 119
 120    Verifies that all elements of the list have the same non-null prefix
 121    command.  */
 122
 123 static void
 124 traverse_command_structure (struct cmd_list_element **list,
 125                             const char *prefix)
 126 {
 127   struct cmd_list_element *c, *prefixcmd;
 128
 129   auto dupl = lists.find (list);
 130   if (dupl != lists.end ())
 131     {
 132       gdb_printf ("list %p duplicated,"
 133                   " reachable via prefix '%s' and '%s'."
 134                   "  Duplicated list first command is '%s'\n",
 135                   list,
 136                   prefix, dupl->second,
 137                   (*list)->name);
 138       nr_duplicates++;
 139       return;
 140     }
 141
 142   lists.insert ({list, prefix});
 143
 144   /* All commands of *list must have a prefix command equal to PREFIXCMD,
 145      the prefix command of the first command.  */
 146   if (*list == nullptr)
 147     prefixcmd = nullptr; /* A prefix command with an empty subcommand list.  */
 148   else
 149     prefixcmd = (*list)->prefix;
 150
 151   /* Walk through the commands.  */
 152   for (c = *list; c; c = c->next)
 153     {
 154       /* If this command has subcommands and is not an alias,
 155          traverse the subcommands.  */
 156       if (c->is_prefix () && !c->is_alias ())
 157         {
 158           /* Recursively call ourselves on the subcommand list,
 159              passing the right prefix in.  */
 160           traverse_command_structure (c->subcommands, c->prefixname ().c_str ());
 161         }
 162       if (prefixcmd != c->prefix
 163           || (prefixcmd == nullptr && *list != cmdlist))
 164         {
 165           if (c->prefix == nullptr)
 166             gdb_printf ("list %p reachable via prefix '%s'."
 167                         "  command '%s' has null prefixcmd\n",
 168                         list,
 169                         prefix, c->name);
 170           else
 171             gdb_printf ("list %p reachable via prefix '%s'."
 172                         "  command '%s' has a different prefixcmd\n",
 173                         list,
 174                         prefix, c->name);
 175           nr_invalid_prefixcmd++;
 176         }
 177     }
 178 }
 179
 180 /* Verify that a list of commands is present in the tree only once.  */
 181
 182 static void
 183 command_structure_invariants_tests ()
 184 {
 185   nr_duplicates = 0;
 186   nr_invalid_prefixcmd = 0;
 187
 188   traverse_command_structure (&cmdlist, "");
 189
 190   /* Release memory, be ready to be re-run.  */
 191   lists.clear ();
 192
 193   SELF_CHECK (nr_duplicates == 0);
 194   SELF_CHECK (nr_invalid_prefixcmd == 0);
 195 }
 196
 197 }
 198
 199 } /* namespace selftests */
 200
 201 void _initialize_command_def_selftests ();
 202 void
 203 _initialize_command_def_selftests ()
 204 {
 205   selftests::register_test
 206     ("help_doc_invariants",
 207      selftests::help_doc_tests::help_doc_invariants_tests);
 208
 209   selftests::register_test
 210     ("command_structure_invariants",
 211      selftests::command_structure_tests::command_structure_invariants_tests);
 212 }