title: Displaying dictionary word with GDB in Jonesforth
body: <p>In <a href="https://github.com/nornagon/jonesforth/blob/master/jonesforth.S" rel="nofollow noreferrer">Jonesforth</a>, a dictionary entry is laid out as follows:</p>
  
  <pre><code>&lt;--- DICTIONARY ENTRY (HEADER) -----------------------&gt;
  +------------------------+--------+---------- - - - - +----------- - - - -
  | LINK POINTER           | LENGTH/| NAME          | DEFINITION
  |                        | FLAGS  |               |
  +--- (4 bytes) ----------+- byte -+- n bytes  - - - - +----------- - - - -
  </code></pre>
  
  <p>We can take a peek at one of these entries using GDB. (See <a href="https://stackoverflow.com/questions/39628756/how-do-i-debug-jonesforth-with-gdb">this question</a> for details on using GDB with Jonesforth.)</p>
  
  <p>Let's display the first 16 bytes of the dictionary entry for <code>SWAP</code> as characters:</p>
  
  <pre><code>&gt;&gt;&gt; x/16cb &amp;name_SWAP
  0x105cc:    -68 '\274'    5 '\005'    1 '\001'    0 '\000'    4 '\004'    83 'S'    87 'W'    65 'A'
  0x105d4:    80 'P'    0 '\000'    0 '\000'    0 '\000'    43 '+'    0 '\000'    1 '\001'    0 '\000'
  </code></pre>
  
  <p>You can kind of see what's going on here.</p>
  
  <p>The first four bytes are the pointer to the previous word in the dictionary:</p>
  
  <pre><code>-68 '\274'    5 '\005'    1 '\001'    0 '\000'
  </code></pre>
  
  <p>Then comes the length of the name:</p>
  
  <pre><code>4 '\004'
  </code></pre>
  
  <p>Then we see the characters of the word name, "SWAP":</p>
  
  <pre><code>83 'S'    87 'W'    65 'A'   80 'P'
  </code></pre>
  
  <p>And finally some padding to align on a 32-bit boundary:</p>
  
  <pre><code>0 '\000'    0 '\000'    0 '\000'
  </code></pre>
  
  <p>It would be nice if there was a way to format the word entry in a nicer manner.</p>
  
  <p>If we do the following:</p>
  
  <pre><code>&gt;&gt;&gt; x/1xw &amp;name_SWAP
  0x105cc:    0x000105bc
  </code></pre>
  
  <p>we note that <code>name_SWAP</code> is at <code>0x105cc</code>.</p>
  
  <p>Let's use GDB's <code>printf</code> to display the word entry:</p>
  
  <pre><code>&gt;&gt;&gt; printf "link: %#010x   name length: %i   name: %s\n", *(0x105cc), (char)*(0x105cc+4), (0x105cc+5)
  link: 0x000105bc   name length: 4   name: SWAP
  </code></pre>
  
  <p>OK, that's not bad! We see the link, the name length, and name, all nicely displayed and labeled.</p>
  
  <p>The downside here is that I have to use the explicit address in the call to <code>printf</code>:</p>
  
  <pre><code>printf "link: %#010x   name length: %i   name: %s\n", *(0x105cc), (char)*(0x105cc+4), (0x105cc+5)
  </code></pre>
  
  <p>Ideally, I'd just be able to say something like:</p>
  
  <pre><code>show_forth_word name_SWAP
  </code></pre>
  
  <p>and it'd display the above.</p>
  
  <p>What's the best way to go about this? Is this doable with a <a href="https://sourceware.org/gdb/current/onlinedocs/gdb/Define.html#Define" rel="nofollow noreferrer">GDB user-defined command</a>? Or is it something more appropriate for the <a href="https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html#Python" rel="nofollow noreferrer">GDB Python</a> interface?</p>