gdb/testsuite/gdb.python/py-doc-reformat.exp

   1 # Copyright 2022-2024 Free Software Foundation, Inc.
   2
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 3 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 # Test how GDB reformats the documentation string of commands
  17 # implemented in Python for use as the help text of those same
  18 # commands.
  19
  20 load_lib gdb-python.exp
  21
  22 require allow_python_tests
  23
  24 clean_restart
  25
  26 # A global counter used to number the tests.
  27 set idx 0
  28
  29 # Run a test, create both a command and a parameter with INPUT_DOCS as
  30 # the Python documentation string, load the command and parameter into
  31 # GDB, and then ask for the help text of the command, and the show and
  32 # set help for the parameter.  The output from GDB should match
  33 # EXPECTED_OUTPUT in each case.
  34 #
  35 # The INPUT_DOCS must start with 2 space characters, followed by the
  36 # 3-quote characters to start the doc string, and must end with the
  37 # final 3-quote characters.  If this is not true then an error is
  38 # thrown, and this function immediately returns.
  39 proc test { input_docs expected_output } {
  40     global idx
  41
  42     set local_idx $idx
  43     incr idx
  44
  45     with_test_prefix "test ${local_idx}" {
  46
  47         # The tests in this script don't have descriptive names,
  48         # rather they use the global IDX to generate a unique name for
  49         # each test.  To make it easier to track down a failing test,
  50         # we print out the test name and the input string.
  51         verbose -log "Start of: test_cmd ${local_idx}"
  52         verbose -log "Input:\n${input_docs}"
  53
  54         if { [string range $input_docs 0 4] != "  \"\"\"" } {
  55             perror "Input string does not start with the required pattern"
  56             return
  57         }
  58
  59         if { [string range $input_docs end-2 end] != "\"\"\"" } {
  60             perror "Input string does not end with the required pattern"
  61             return
  62         }
  63
  64         set python_filename [standard_output_file "${::gdb_test_file_name}-${local_idx}.py"]
  65
  66         set fd [open $python_filename w]
  67
  68         puts $fd "class test_cmd (gdb.Command):"
  69         puts $fd $input_docs
  70         puts $fd ""
  71         puts $fd "  def __init__ (self):"
  72         puts $fd "    super ().__init__ (\"test-cmd\", gdb.COMMAND_OBSCURE)"
  73         puts $fd ""
  74         puts $fd "  def invoke (self, arg, from_tty):"
  75         puts $fd "    print (\"In test-cmd\")"
  76         puts $fd ""
  77
  78         puts $fd "class test_param (gdb.Parameter):"
  79         puts $fd $input_docs
  80         puts $fd ""
  81         puts $fd "  show_doc = \"This is the show doc line\""
  82         puts $fd "  set_doc = \"This is the set doc line\""
  83         puts $fd ""
  84         puts $fd "  def __init__ (self):"
  85         puts $fd "    super ().__init__ (\"test-param\", gdb.COMMAND_OBSCURE, gdb.PARAM_BOOLEAN)"
  86         puts $fd ""
  87         puts $fd "  def get_show_string (self, value):"
  88         puts $fd "    return \"The state is '\" + value + \"'\""
  89
  90         puts $fd ""
  91         puts $fd "test_param ()"
  92         puts $fd "test_cmd ()"
  93
  94         puts $fd ""
  95         puts $fd "print(\"Loaded OK.\")"
  96
  97         close $fd
  98
  99         set remote_python_file \
 100             [gdb_remote_download host $python_filename]
 101
 102         clean_restart
 103
 104         gdb_test "source ${remote_python_file}" \
 105             "Loaded OK\\." \
 106             "source python command file"
 107
 108         # Use gdb_test_multiple here as plain gdb_test will allow
 109         # excess blank lines between the expected_output pattern and
 110         # the gdb_prompt - a core part of this test is that we are
 111         # checking that such blank lines are removed - so we can't use
 112         # gdb_test here.
 113         gdb_test_multiple "help test-cmd" "" {
 114             -re "^help test-cmd\r\n" {
 115                 exp_continue
 116             }
 117             -re "^$expected_output\r\n$::gdb_prompt $" {
 118                 pass $gdb_test_name
 119             }
 120         }
 121
 122         gdb_test_multiple "help set test-param" "" {
 123             -re "^help set test-param\r\n" {
 124                 exp_continue
 125             }
 126             -re "^This is the set doc line\r\n" {
 127                 exp_continue
 128             }
 129             -re "^$expected_output\r\n$::gdb_prompt $" {
 130                 pass $gdb_test_name
 131             }
 132         }
 133
 134         gdb_test_multiple "help show test-param" "" {
 135             -re "^help show test-param\r\n" {
 136                 exp_continue
 137             }
 138             -re "^This is the show doc line\r\n" {
 139                 exp_continue
 140             }
 141             -re "^$expected_output\r\n$::gdb_prompt $" {
 142                 pass $gdb_test_name
 143             }
 144         }
 145     }
 146 }
 147
 148 # The first test is pretty vanilla. First line starts immediately
 149 # after the opening quotes, and closing quotes are immediately after
 150 # the last line.
 151 test \
 152     [multi_line_input \
 153          "  \"\"\"This is the first line." \
 154          "" \
 155          "  This is the third line.\"\"\""] \
 156     [multi_line \
 157          "This is the first line\\." \
 158          "" \
 159          "This is the third line\\."]
 160
 161 # In this test the first line starts on the line after the opening
 162 # quotes.  The blank line in the middle is still completely empty.
 163 test \
 164     [multi_line_input \
 165          "  \"\"\"" \
 166          "  This is the first line." \
 167          "" \
 168          "  This is the third line.\"\"\""] \
 169     [multi_line \
 170          "This is the first line\\." \
 171          "" \
 172          "This is the third line\\."]
 173
 174 # This test adds an indented line in the middle, we expect the
 175 # relative indentation to be retained.
 176 test\
 177     [multi_line_input \
 178          "  \"\"\"" \
 179          "  This is the first line." \
 180          "    Indented second line." \
 181          "  This is the third line.\"\"\""] \
 182     [multi_line \
 183          "This is the first line\\." \
 184          "  Indented second line\\." \
 185          "This is the third line\\."]
 186
 187 # The indentation moves to the first line.
 188 test\
 189     [multi_line_input \
 190          "  \"\"\"" \
 191          "    Indented first line." \
 192          "  This is the second line." \
 193          "  This is the third line.\"\"\""] \
 194     [multi_line \
 195          "  Indented first line\\." \
 196          "This is the second line\\." \
 197          "This is the third line\\."]
 198
 199 # The indentation moves to the last line.
 200 test\
 201     [multi_line_input \
 202          "  \"\"\"" \
 203          "  This is the first line." \
 204          "  This is the second line." \
 205          "    Indented third line.\"\"\""] \
 206     [multi_line \
 207          "This is the first line\\." \
 208          "This is the second line\\." \
 209          "  Indented third line\\."]
 210
 211 # Tests using different amounts of white-space on a line of its own.
 212 # We test with the white-space at the beginning, end, and in the
 213 # middle of the doc string.
 214 foreach line [list "" " " "  " "   " "    "] {
 215     # Blank lines at the beginning should be removed.
 216     test \
 217         [multi_line_input \
 218              "  \"\"\"" \
 219              $line \
 220              "  This is the first line." \
 221              "    Indented second line." \
 222              "  This is the third line.\"\"\""] \
 223         [multi_line \
 224              "This is the first line\\." \
 225              "  Indented second line\\." \
 226              "This is the third line\\."]
 227
 228     # As should blank lines at the end.
 229     test \
 230         [multi_line_input \
 231              "  \"\"\"" \
 232              "  This is the first line." \
 233              "    Indented second line." \
 234              "  This is the third line." \
 235              $line \
 236              "  \"\"\""] \
 237         [multi_line \
 238              "This is the first line\\." \
 239              "  Indented second line\\." \
 240              "This is the third line\\."]
 241
 242     # While blank lines in the middle should have all white-space
 243     # removed.
 244     test \
 245         [multi_line_input \
 246              "  \"\"\"" \
 247              "  This is the first line." \
 248              $line \
 249              "  This is the third line." \
 250              $line \
 251              "  \"\"\""] \
 252         [multi_line \
 253              "This is the first line\\." \
 254              "" \
 255              "This is the third line\\."]
 256 }
 257
 258 # Check for correct handling of closing quotes being on a line of
 259 # their own.
 260 test\
 261     [multi_line_input \
 262          "  \"\"\"  " \
 263          "  This is the first line." \
 264          "    Indented second line." \
 265          "  This is the third line." \
 266          "  \"\"\""] \
 267     [multi_line \
 268          "This is the first line\\." \
 269          "  Indented second line\\." \
 270          "This is the third line\\." ]
 271
 272
 273 # Check with a single 'x' character before the closing quotes.  Make
 274 # sure we don't drop this character.
 275 test\
 276     [multi_line_input \
 277          "  \"\"\"  " \
 278          "  This is the first line." \
 279          "    Indented second line." \
 280          "  This is the third line." \
 281          "  x\"\"\""] \
 282     [multi_line \
 283          "This is the first line\\." \
 284          "  Indented second line\\." \
 285          "This is the third line\\." \
 286          "x"]