[Lldb-commits] [lldb] r134575 - /lldb/trunk/www/varformats.html

Enrico Granata granata.enrico at gmail.com
Wed Jul 6 17:39:56 PDT 2011

Author: enrico
Date: Wed Jul  6 19:39:55 2011
New Revision: 134575

URL: http://llvm.org/viewvc/llvm-project?rev=134575&view=rev
new webpage describing type command

    lldb/trunk/www/varformats.html   (with props)

Added: lldb/trunk/www/varformats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/varformats.html?rev=134575&view=auto
--- lldb/trunk/www/varformats.html (added)
+++ lldb/trunk/www/varformats.html Wed Jul  6 19:39:55 2011
@@ -0,0 +1,576 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link href="style.css" rel="stylesheet" type="text/css" />
+<title>LLDB Homepage</title>
+    <div class="www_title">
+      The <strong>LLDB</strong> Debugger
+    </div>
+<div id="container">
+	<div id="content">
+       <!--#include virtual="sidebar.incl"-->
+		<div id="middle">
+			<div class="post">
+				<h1 class ="postheader">Variable display</h1>
+				<div class="postcontent">
+				   <p>LLDB was recently modified to allow users to define the 
+				       format of the variables display on a per-type basis.</p>
+					<p>Usually, when you type <code>frame
+					variable</code> or run some <code>expression</code>
+					LLDB will automatically choose the <i>best</i> way
+					to display your results according to its own
+					logic:</p> <p> <code> (SimpleWithPointers [3])
+					sparray = {<br/> (SimpleWithPointers) [0] = {<br/>
+					(int *) x = 0x00000001001000f0<br/> (float *) y =
+					0x0000000100100100<br/> (char *) z =
+					0x0000000100100110 "3"<br/>
+					  }<br/>
+					  (SimpleWithPointers) [1] = {<br/> (int *) x =
+					  0x0000000100100120<br/> (float *) y =
+					  0x0000000100100130<br/> (char *) z =
+					  0x0000000100100140 "6"<br/>
+					  }<br/>
+					  (SimpleWithPointers) [2] = {<br/> (int *) x =
+					  0x0000000100100150<br/> (float *) y =
+					  0x0000000100100160<br/> (char *) z =
+					  0x0000000100100170 "9"<br/>
+					  }<br/>
+					}<br/>
+					</code> </p>
+				   <p>However, there are cases in which your idea of
+				   <i>best</i> is different from LLDB's. Now there are two
+				   new commands that enable you to give hints to the debugger
+				   as to how datatypes should be displayed.</p>
+				   <p>Using them you can obtain a format like this one for
+				   <code>sparray</code>, instead of the default shown above:
+				   </p>
+				   <p>
+				   <code>
+				   (SimpleWithPointers [3]) sparray = {<br/>
+  [0] = (x=0x00000001001000f0 -> -1, y=0x0000000100100100 -> -2, z="3")<br/>
+  [1] = (x=0x0000000100100120 -> -4, y=0x0000000100100130 -> -5, z="6")<br/>
+  [2] = (x=0x0000000100100150 -> -7, y=0x0000000100100160 -> -8, z="9")<br/>
+				   <p>Variable formatting can be set using the <b>type</b> commands:</p>
+				   <p><code>type format</code></p>
+				   <p><code>type summary</code></p>
+				   <p>Each of these commands has four subcommands:</p>
+				   <p><code>add</code>: adds a new entry</p>
+				   <p><code>delete</code>: deletes an existing entry</p>
+				   <p><code>list</code>: provides a listing of all entries</p>
+				   <p><code>clear</code>: deletes all entries</p>
+                   </div>
+       			<div class="postfooter"></div>
+   			</div>
+   			<div class="post">
+   				<h1 class ="postheader">type format</h1>
+   				<div class="postcontent">
+				   <p>Type formats enable you to quickly override the default format for displaying primitive types (the usual basic C/C++/ObjC types: int, float, char, ...).</p>
+				   <p>LLDB has a list of formatting options available out of which you can pick:</p>
+				   <table border="1">
+                   <tr valign=top><td width=23%><b>Format name</b></td><td><b>Abbreviation</b></td><td><b>Description</b></td></tr>
+                   <tr valign=top><td><b>default</b></td><td></td><td>the default LLDB algorithm is used to pick a format</td></tr>
+                   <tr valign=top><td><b>boolean</b></td><td>B</td><td>show this as a true/false boolean, using the customary rule that 0 is false and everything else is true</td></tr>
+                   <tr valign=top><td><b>binary</b></td><td>b</td><td>show this as a sequence of bits</td></tr>
+                   <tr valign=top><td><b>bytes</b></td><td>y</td><td>show the bytes one after the other<br/>e.g. <code>(int) s.x = 07 00 00 00</code></td></tr>
+                   <tr valign=top><td><b>bytes with ASCII</b></td><td>Y</td><td>show the bytes, but try to print them as ASCII characters<br/>e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00                         P.._....</code></td></tr>
+                   <tr valign=top><td><b>character</b></td><td>c</td><td>show the bytes printed as ASCII characters<br/>e.g. <code>(int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0</code></td></tr>
+                   <tr valign=top><td><b>printable character</b></td><td>C</td><td>show the bytes printed as printable ASCII characters<br/> e.g. <code>(int *) c.sp.x = P.._....</code></td></tr>
+                   <tr valign=top><td><b>complex float</b></td><td>F</td><td>interpret this value as the real and imaginary part of a complex floating-point number<br/>e.g. <code>(int *) c.sp.x = 2.76658e+19 + 4.59163e-41i</code></td></tr>
+                   <tr valign=top><td><b>c-string</b></td><td>s</td><td>show this as a 0-terminated C string</td></tr>
+                   <tr valign=top><td><b>signed decimal</b></td><td>i</td><td>show this as a signed integer number (this does not perform a cast, it simply shows the bytes as signed integer)</td></tr>
+                   <tr valign=top><td><b>enumeration</b></td><td>E</td><td>show this as an enumeration, printing the value's name if available or the integer value otherwise<br/>e.g. <code>(enum enumType) val_type = eValue2</code></td></tr>
+                   <tr valign=top><td><b>hex</b></td><td>x</td><td>show this as in hexadecimal notation (this does not perform a cast, it simply shows the bytes as hex)</td></tr>
+                   <tr valign=top><td><b>float</b></td><td>f</td><td>show this as a floating-point number (this does not perform a cast, it simply interprets the bytes as an IEEE754 floating-point value)</td></tr>
+                   <tr valign=top><td><b>octal</b></td><td>o</td><td>show this in octal notation</td></tr>
+                   <tr valign=top><td><b>OSType</b></td><td>O</td><td>show this as a MacOS OSType<br/>e.g. <code>(float) *c.sp.y = '\n\x1f\xd7\n'</code></td></tr>
+                   <tr valign=top><td><b>unicode16</b></td><td>U</td><td>show this as UTF-16 characters<br/> e.g. <code>(float) *c.sp.y = 0xd70a 0x411f</code></td></tr>
+                   <tr valign=top><td><b>unicode32</b></td><td></td><td>show this as UTF-32 characters<br/> e.g. <code>(float) *c.sp.y = 0x411fd70a</code></td></tr>
+                   <tr valign=top><td><b>unsigned decimal</b></td><td>u</td><td>show this as an unsigned integer number (this does not perform a cast, it simply shows the bytes as unsigned integer)</td></tr>
+                   <tr valign=top><td><b>pointer</b></td><td>p</td><td>show this as a native pointer (unless this is really a pointer, the resulting address will probably be invalid)</td></tr>
+                   <tr valign=top><td><b>char[]</b></td><td></td><td>show this as an array of characters<br/>e.g. <code>(char) *c.sp.z = {X}</code></td></tr>
+                   <tr valign=top><td><b>int8_t[], uint8_t[]<br/>int16_t[], uint16_t[]<br/>int32_t[], uint32_t[]<br/>int64_t[], uint64_t[]<br>uint128_t[]</b></td><td></td><td>show this as an array of the corresponding integer type<br/>e.g.<br/><code>(int) sarray[0].x = {1 0 0 0}</code><br/><code>(int) sarray[0].x = {0x00000001}</code></td></tr>
+                   <tr valign=top><td><b>float32[], float64[]</b></td><td></td><td>show this as an array of the corresponding floating-point type<br/>e.g. <code>(int *) pointer = {1.46991e-39 1.4013e-45}</code></td></tr>
+                   <tr valign=top><td><b>complex integer</b></td><td>I</td><td>interpret this value as the real and imaginary part of a complex integer number<br/> e.g. <code>(int *) pointer = 1048960 + 1i</code></td></tr>
+                   <tr valign=top><td><b>character array</b></td><td>a</td><td>show this as a character array<br/>e.g. <code>(int *) pointer = \x80\x01\x10\0\x01\0\0\0</code></td></tr>
+                   </table>
+				   <p>Some of the examples shown are willingfully
+				   unnatural ways to print some values, and meant to
+				   show that there is no casting or data-loss occurring
+				   when you change the format of a type. All that lldb
+				   does when you ask it to change format is reinterpret
+				   the bytes for display, leaving the original value
+				   unaltered.</p>
+				   <p>There are two ways to modify the format, one is
+				   temporary and per-variable, the other is permanent
+				   and per-type.</p> <p>In the first case you can simply
+				   use the <code>-f</code> option to <b><code>frame
+				   variable</code></b>, passing it one of the format
+				   names or abbreviations in the previous table:</p>
+				   <p><code>frame variable counter -f hex</code></p>
+				   <p>This has the effect of displaying the value of
+				   <code>counter</code> as an hexadecimal number, and
+				   will keep showing it this way until you either pick a
+				   different format or a subsequent stoppoint is
+				   hit.</p> <p>Obviously, if you have two
+				   <code>int</code> variables, and you format one as
+				   hex, the other will be left untouched. If for some
+				   reason, you want all <code>int</code> variables to
+				   print out as hex, you must add a format to the
+				   <code>int</code> type.</p> <p>This is done by typing
+				   <code>type format add -f hex int</code> at the LLDB
+				   command line.</p> <p>The <code>-f</code> option
+				   accepts one of the format names or abbreviations, and
+				   after that you can give out a list of names to which
+				   you want the new format applied.</p> <p>A frequent
+				   scenario is that your program has a
+				   <code>typedef</code> for a numeric type that you know
+				   represents something that must be printed in a
+				   certain way. Again, you can add a format just to that
+				   typedef by using <code>type format add</code> with
+				   the name alias.</p> <p>But things can quickly get
+				   hierarchical. Let's say you have a situation like the
+				   following:</p> <p><code>typedef int A;<br/>typedef A
+				   B;<br/>typedef B C;<br/>typedef C D;</code></p>
+				   <p>and you want to show all <code>A</code>s as hex,
+				   all <code>C</code>s as pointers and leave the
+				   defaults untouched for other types.</p> <p>If you
+				   simply type <br/><code>type format add -f hex
+				   A<br/>type format add -f pointer C</code><br/> values
+				   of type <code>B</code> will be shown as hex and
+				   values of type <code>D</code> as pointers.</p>
+				   <p>This is because by default LLDB <i>cascades</i>
+				   formats through typedef chains. In order to avoid
+				   that you can use the option <code>-C no</code> to
+				   prevent cascading, thus making the two commands
+				   required to achieve your goal:<br/> <code> type
+				   format add -f hex -C no A<br/> type format add -f
+				   pointer -C no C </code></p> <p>Two additional options
+				   that you will want to look at are <code>-p</code> and
+				   <code>-r</code>. These two options prevent LLDB from
+				   applying a format for type <code>T</code> to values
+				   of type <code>T*</code> and <code>T&</code>
+				   respectively.</p>
+				   <p>
+				   <code>
+				    <b>(lldb)</b> type format add -f float32[] int<br/>
+					<b>(lldb)</b> fr var pointer *pointer -T<br/>
+					(int *) pointer = {1.46991e-39 1.4013e-45}<br/>
+					(int) *pointer = {1.53302e-42}<br/>
+					<b>(lldb)</b> type format add -f float32[] int -p<br/>
+					<b>(lldb)</b> fr var pointer *pointer -T<br/>
+					(int *) pointer = 0x0000000100100180<br/>
+					(int) *pointer = {1.53302e-42}<br/>
+				   </code>
+				   </p>
+				   <p>As the previous example highlights, you will most
+				   probably want to use <code>-p</code> for your
+				   formats.</p> <p>If you need to delete a custom format
+				   simply type <code>type format delete</code> followed
+				   by the name of the type to which the format applies.
+				   To delete ALL formats, use <code>type format
+				   clear</code>. To see all the formats defined, type
+				   <code>type format list</code>.</p>
+				    </div> <div class="postfooter"></div> </div>
+   			<div class="post"> <h1 class ="postheader">type
+   			summary</h1> <div class="postcontent">
+				   <p>Type summaries enable you to add more information
+				   to the default viewing format for a type, or to
+				   completely replace it with your own display option.
+				   Unlike formats which only apply to basic types,
+				   summaries can be used on every type (basic types,
+				   classes (C++ and Objective-C), arrays, ...).</p>
+				   <p>The basic idea beneath type summaries is
+				   extracting information from variables and arranging
+				   it in a format that is suitable for display:</p> <p>
+				   <i>before adding a summary...</i><br/> <code> <b>(lldb)</b>
+				   fr var -T one<br/> (i_am_cool) one = {<br/> (int)
+				   integer = 3<br/> (float) floating = 3.14159<br/>
+				   (char) character = 'E'<br/>
+					}<br/>
+					</code> <br/> <i>after adding a summary...</i><br/>
+					<code> <b>(lldb)</b> fr var one<br/> (i_am_cool) one = int
+					= 3, float = 3.14159, char = 69<br/> </code> </p>
+				   <p>Evidently, somehow we managed to tell LLDB to grab
+				   the three member variables of the
+				   <code>i_am_cool</code> datatype, mix their values
+				   with some text, and even ask it to display the
+				   <code>character</code> member using a custom
+				   format.</p> <p>The way to do this is add a <i>summary
+				   string</i> to the datatype using the <code>type
+				   summary add</code> command.</p> <p>Its syntax is
+				   similar to <code>type format add</code>, but some
+				   more options are supported that will be described in
+				   the follow-up.</p> <p>The main option to <code>type
+				   summary add</code> is <code>-f</code> which accepts
+				   as parameter a summary string. After that, you can
+				   type as many type names as you want to associate the
+				   given summary string to them.</p>
+                   </div>
+       			<div class="postfooter"></div>
+   			</div>
+   			<div class="post">
+   				<h1 class ="postheader">Summary Strings</h1>
+   				<div class="postcontent">
+                   <p>So what is the format of the summary strings?
+                   Summary strings can contain plain text, control
+                   characters and special symbols that have access to
+                   information about the current object and the overall
+                   program state.</p>
+                   <p>Normal characters are any text that doesn't
+                   contain a <code><b>'{'</b></code>,
+                   <code><b>'}'</b></code>, <code><b>'$'</b></code>, or
+                   <code><b>'\'</b></code> character.</p>
+                   <p>Variable names are found in between a
+                   <code><b>"${"</b></code> prefix, and end with a
+                   <code><b>"}"</b></code> suffix. In other words, a
+                   variable looks like
+                   <code>"<b>${frame.pc}</b>"</code>.</p>
+                   <p>Basically, all the variables described in <a
+                   href="formats.html">Frame and Thread Formatting</a>
+                   are accepted. Also acceptable are the control
+                   characters and scoping features described in that
+                   page. Additionally, <code>${var</code> and
+                   <code>${*var</code> become acceptable symbols in this
+                   scenario.</p> <p>The simplest thing you can do is
+                   grab a member variable of a class or structure by
+                   typing its <i>expression path</i>. In the previous
+                   example, the expression path for the floating member
+                   is simply <code>.floating</code>, because all you
+                   have to do to get at it given an object of type
+                   <code>i_am_cool</code> is access it straight away.
+                   Thus, to ask the summary string to display
+                   <code>floating</code> you would type
+                   <code>${var.floating}</code> (<code>${var</code> is a
+                   placeholder token replaced with whatever variable is
+                   being displayed).</p> <p>If you have code like the
+                   following: <br/> <code> struct A {<br/> int x;<br/>
+                   int y;<br/>
+				   };<br/>
+				   struct B {<br/> A x;<br/> A y;<br/> int z;<br/>
+			 	   };<br/>
+			 	   </code> the expression path for the <code>y</code>
+			 	   member of the <code>x</code> member of an object of
+			 	   type <code>B</code> would be <code>.x.y</code> and
+			 	   you would type <code>${var.x.y}</code> to display it
+			 	   in a summary string for type <code>B</code>. </p>
+			 	   <p>As you could be using a summary string for both
+			 	   displaying objects of type <code>T</code> or
+			 	   <code>T*</code> (unless <code>-p</code> is used to
+			 	   prevent this), the expression paths do not
+			 	   differentiate between <code>.</code> and
+			 	   <code>-></code>, and the above expression path
+			 	   <code>.x.y</code> would be just as good if you were
+			 	   displaying a <code>B*</code>, or even if the actual
+			 	   definition of <code>B</code> were:
+				   	<code><br/>
+				   struct B {<br/>
+				    A *x;<br/>
+				    A y;<br/>
+				    int z;<br/>
+			 	   };<br/>
+			 	   </code>
+				   </p>
+				   <p>This is unlike the behaviour of <code>frame
+				   variable</code> which, on the contrary, will enforce
+				   the distinction. As hinted above, the rationale for
+				   this choice is that waiving this distinction enables
+				   one to write a summary string once for type
+				   <code>T</code> and use it for both <code>T</code> and
+				   <code>T*</code> instances. As a summary string is
+				   mostly about extracting nested members' information,
+				   a pointer to an object is just as good as the object
+				   itself for the purpose.</p>
+				   <p>Of course, you can have multiple entries in one
+				   summary string. For instance, the command used to
+				   produce the above summary string for i_am_cool was:
+				   <br/><code>type summary add -f "int = ${var.integer},
+				   float = ${var.floating}, char = ${var.character%u}"
+				   i_am_cool </code> </p> <p>As you can see, the last
+				   expression path also contains a <code>%u</code>
+				   symbol which is nowhere to be found in the actual
+				   member variable name. The symbol is reminding of a
+				   <code>printf()</code> format symbol, and in fact it
+				   has a similar effect. If you add a % sign followed by
+				   any one format name or abbreviation from the above
+				   table after an expression path, the resulting object
+				   will be displyed using exactly that format instead of
+				   the LLDB default one.
+				   </p>
+				   <p>There are two more special format symbols that you
+				   can use only as part of a summary string:
+				   <code>%V</code> and <code>%@</code>. The first one
+				   tells LLDB to ignore summary strings for the type of
+				   the object referred by the expression path and
+				   instead print the object's value. The second is only
+				   applicable to Objective-C classes, and tells LLDB to
+				   get the object's description from the Objective-C
+				   runtime. By default, if no format is provided, LLDB
+				   will try to get the object's summary, and if empty
+				   the object's value. If neither can be obtained,
+				   nothing will be displayed.</p>
+				   <p>As previously said, pointers and values are
+				   treated the same way when getting to their members in
+				   an expression path. However, if your expression path
+				   leads to a pointer, LLDB will not automatically
+				   dereference it. In order to obtain The deferenced
+				   value for a pointer, your expression path must start
+				   with <code>${*var</code> instead of
+				   <code>${var</code>. Because there is no need to
+				   dereference pointers along your way, the
+				   dereferencing symbol only applies to the result of
+				   the whole expression path traversing.
+				   <br/>
+				   e.g.
+				   <code>
+				   <br/>
+				   <b>(lldb)</b> fr var -T c<br/>
+(Couple) c = {<br/>
+  (SimpleWithPointers) sp = {<br/>
+    (int *) x = 0x00000001001000b0<br/>
+    (float *) y = 0x00000001001000c0<br/>
+    (char *) z = 0x00000001001000d0 "X"<br/>
+  }<br/>
+  (Simple *) s = 0x00000001001000e0<br/>
+<b>(lldb)</b> type summary add -f "int = ${*var.sp.x}, float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple = ${*var.s}" Couple<br/>
+<b>(lldb)</b> type summary add -c -p Simple<br/>
+<b>(lldb)</b> fr var c<br/>
+(Couple) c = int = 9, float = 9.99, char = 88, Simple = (x=9, y=9.99, z='X')<br/>
+				   </code>
+				   </p>
+				   <p>Option <code>-c</code> to <code>type summary
+				   add</code> tells LLDB not to look for a summary
+				   string, but instead to just print a listing of all
+				   the object's children on one line, lay out as in the
+				   previous example. The <code>-p</code> flag is used as
+				   a trick to show that aggregate types can be
+				   dereferenced as well as primitive ones. The above
+				   output would be shown even by typing <code>type
+				   summary add -f "int = ${*var.sp.x}, float =
+				   ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =
+				   ${var.s}" Couple</code> if one took away the
+				   <code>-p</code> flag from the summary for type
+				   <code>Simple</code>. </p>
+				    </div>
+       			<div class="postfooter"></div>
+   			</div>
+   			<div class="post">
+   				<h1 class ="postheader">More on summary strings</h1>
+   				<div class="postcontent">
+				   <p>What was described above are the main features
+				   that you can use in summary strings. However, there
+				   are three more features to them.</p> <p>Sometimes, a
+				   basic type's value actually represents several
+				   different values packed together in a bitfield. With
+				   the classical view, there is no way to look at them.
+				   Hexadecimal display can help, but if the bits
+				   actually span byte boundaries, the help is limited.
+				   Binary view would show it all without ambiguity, but
+				   is often too detailed and hard to read for real-life
+				   scenarios. To cope with the issue, LLDB supports
+				   native bitfield formatting in summary strings. If
+				   your expression paths leads to a so-called <i>scalar
+				   type</i> (the usual int, float, char, double, short,
+				   long, long long, double, long double and unsigned
+				   variants), you can ask LLDB to only grab some bits
+				   out of the value and display them in any format you
+				   like. The syntax is similar to that used for arrays,
+				   just you can also give a pair of indices separated by
+				   a <code>-</code>. <br/>
+				   e.g.
+				   <br/>
+				   <code>
+				   <b>(lldb)</b> fr var float_point<br/>
+(float) float_point = -3.14159<br/>
+<b>(lldb)</b> type summary add -f "Sign: ${var[31]%B} Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}" float<br/>
+<b>(lldb)</b> fr var float_point<br/>
+(float) float_point = -3.14159 Sign: true Exponent: 0x00000080 Mantissa: 4788184<br/>
+				   </code>
+				   In this example, LLDB shows the internal
+				   representation of a <code>float</code> variable by
+				   extracting bitfields out of a float object. If you
+				   give a single index, only that one bit will be
+				   extracted. If you give a pair of indices, all the
+				   bits in the range (extremes included) will be
+				   extracted. Ranges can be specified either by giving
+				   the lower index first, or higher index first (as is
+				   often customary in describing packed data-type
+				   formats). </p>
+				   <p>The second additional feature allows you to
+				   display array members inside a summary string. For
+				   instance, you may want to display all arrays of a
+				   given type using a more compact notation than the
+				   default, and then just delve into individual array
+				   members that prove interesting to your debugging
+				   task. You can use a similar syntax to the one used
+				   for bitfields to tell LLDB to format arrays in
+				   special ways.
+				    <br/>
+				   e.g.
+				   <br/>
+				   <code>
+				   <b>(lldb)</b> fr var sarray<br/>
+(Simple [3]) sarray = {<br/>
+  [0] = {<br/>
+    x = 1<br/>
+    y = 2<br/>
+    z = '\x03'<br/>
+  }<br/>
+  [1] = {<br/>
+    x = 4<br/>
+    y = 5<br/>
+    z = '\x06'<br/>
+  }<br/>
+  [2] = {<br/>
+    x = 7<br/>
+    y = 8<br/>
+    z = '\t'<br/>
+  }<br/>
+<b>(lldb)</b> type summary add -f "${var[].x}" "Simple [3]"<br/>
+<b>(lldb)</b> fr var sarray<br/>
+(Simple [3]) sarray = [1,4,7]<br/>
+				   </code>
+				   The <code>[]</code> symbol amounts to: <i>if
+				   <code>var</code> is an array and I knows its size,
+				   apply this summary string to every element of the
+				   array</i>. Here, we are asking LLDB to display
+				   <code>.x</code> for every element of the array, and
+				   in fact this is what happens. If you find some of
+				   those integers anomalous, you can then inspect that
+				   one item in greater detail, without the array format
+				   getting in the way:
+				   <br/>
+				   	<code>
+				   	<b>(lldb)</b> fr var sarray[1]<br/>
+(Simple) sarray[1] = {<br/>
+  x = 4<br/>
+  y = 5<br/>
+  z = '\x06'<br/>
+				   	</code>
+				   </p>
+				   <p>You can also ask LLDB to only print a subset of
+				   the array range by using the same syntax used to
+				   extract bit for bitfields.</p> <p>The same logic
+				   works if you are printing a pointer instead of an
+				   array, however in this latter case, <code>[]</code>
+				   cannot be used and you need to give exact range
+				   limits.</p> <p>The third, and last, additional
+				   feature does not directly apply to the summary
+				   strings themselves, but is an additional option to
+				   the <code>type summary add</code> command:
+				   <code>-x</code></p> <p>As you noticed, in order to
+				   associate the custom summary string to the array
+				   types, one must give the array size as part of the
+				   typename. This can long become tiresome when using
+				   arrays of different sizes, <code>Simple [3]</code>,
+				   <code>Simple [9]</code>, <code>Simple [12]</code>,
+				   ...</p> <p>If you use the <code>-x</code> option,
+				   type names are treated as regular expressions instead
+				   of type names. This would let you rephrase the above
+				   example as:
+				   	<br/>
+				   <code>
+<b>(lldb)</b> type summary add -f "${var[].x}" -x "Simple \[[0-9]+\]"<br/>
+<b>(lldb)</b> fr var sarray<br/>
+(Simple [3]) sarray = [1,4,7]<br/>
+					</code>
+					The above scenario works for <code>Simple [3]</code>
+					as well as for any other array of
+					<code>Simple</code> objects. </p> <p>While this
+					feature is mostly useful for arrays, you could also
+					use regular expressions to catch other type sets
+					grouped by name. However, as regular expression
+					matching is slower than normal name matching, LLDB
+					will first try to match by name in any way it can,
+					and only when this fails, will it resort to regular
+					expression matching. Thus, if your type has a base
+					class with a cascading summary, this will be
+					preferred over any regular expression match for your
+					type itself.</p>
+   				    </div> <div class="postfooter"></div> </div>
+   			 <div class="post"> <h1 class ="postheader">Finding
+   			 summaries 101</h1> <div class="postcontent">
+   				   <p>While the rules for finding an appropriate
+   				   format for a type are relatively simple (just go
+   				   through typedef hierarchies), summaries follow a
+   				   more complicated process in finding the right
+   				   summary string for a variable. Namely, what
+   				   happens is:</p> <ul> <li>If there is a summary for
+   				   the type of the variable, use it</li> <li>If this
+   				   object is a pointer, and there is a summary for
+   				   the pointee type that does not skip pointers, use
+   				   it</li> <li>If this object is a reference, and
+   				   there is a summary for the pointee type that does
+   				   not skip references, use it</li> <li>If this
+   				   object is an Objective-C class with a parent
+   				   class, look at the parent class (and parent of
+   				   parent, ...)</li> <li>If this object is a C++
+   				   class with base classes, look at base classes (and
+   				   bases of bases, ...)</li> <li>If this object is a
+   				   C++ class with virtual base classes, look at the
+   				   virtual base classes (and bases of bases,
+   				   ...)</li> <li>If this object's type is a typedef,
+   				   go through typedef hierarchy</li> <li>If
+   				   everything has failed, repeat the above search,
+   				   looking for regular expressions instead of exact
+   				   matches</li> </ul> </div> <div
+   				   class="postfooter"></div> </div>
+   			<div class="post"> <h1 class ="postheader">TODOs</h1>
+   			<div class="postcontent">
+				<ul> <li>There's no way to do multiple dereferencing,
+				and you need to be careful what the dereferencing
+				operation is binding to in complicated scenarios</li>
+				<li>There is no way to call functions inside summary
+				strings, not even <code>const</code> ones</li>
+				<li><code>type format add</code> does not support the
+				<code>-x</code> option</li> <li>Object location cannot
+				be printed in the summary string</li> </ul>
+                </div>
+          		<div class="postfooter"></div>
+      			</div>
+		</div>
+	</div>
\ No newline at end of file

Propchange: lldb/trunk/www/varformats.html
    svn:executable = *

More information about the lldb-commits mailing list