484 ❘ CHAPTER 18 DEBUGGING To delete an expression, select it in the Expressions window and press the Delete key. Expressions are very useful for examining the contents of array values. An expression like stack[1] examines the second element in the stack array. The expression buffer[index] examines whichever element the variable index refers to. DATA FORMATTERS The summary column in the variables pane is designed to present a compact, informative explanation of the value or object. For some objects, like strings, the summary value is obvious. For objects like a collection it might display the size of the collection — not a lot of detail, but still informative. For an opaque FSRef structure, it might convert that structure into a readable fi lename — very informative, indeed. This descriptive transformation is done using data formatters. Xcode includes many data formatters, but they won ’ t help with any object that you defi ne. You can create your own data formatters to summarize complex data structures and objects in the debugger. Creating a Custom Data Formatter Creating your own data formatters is very easy. It is really nothing more than a format string with placeholders for values or expressions derived from the variable being summarized. Any regular text in the data formatter is displayed verbatim. There are two kinds of placeholders: references and expressions. References are delimited by two percent characters ( %reference% ). A reference can refer to a single member variable by name. If the variable is contained in a substructure, use the appropriate period (.) separated variable name. You cannot use operators such as pointer dereferences or array indexes. For that, you need to use an expression. Taking the class that ’ s defi ned in Listing 18 - 3, the reference to the integer record_no of DataBlock class would be %header.record_no% . LISTING 18 - 3: Sample class typedef struct { int record_no; unsigned long checksum; } BlockHeader; @interface DataBlock : NSObject { @public BlockHeader header; NSMutableData* data; } An expression is any debugger expression; the same kind of expression that you can add to the Expressions window. In fact, it ’ s good to think of an expression in a data formatter as an expression in the Expressions window, as you ’ ll see in moment. Expressions are contained between matching braces ( { expression } ). Unlike references, expressions do not assume the context of the value being examined. To refer to the object being examined, use c18.indd 484c18.indd 484 1/22/10 12:55:49 PM1/22/10 12:55:49 PM Download at getcoolebook.com the $VAR macro in the expression. $VAR will be replaced with the name of the variable when the data formatter is evaluated. Using the previous class as an example again, the expression to access the record_no value would be {$VAR.header.record_no} . If you ’ re now guessing that you can refer to other variables in the context of the current stack frame, you ’ re correct. However, this isn ’ t a good idea, which is explained later. Limit your evaluation to the structure or object being examined. The advantage of expressions over references is that they are more expressive. You can perform math, include conditionals, and even call member functions. Again using the class defi ned in Listing 18 - 3, here are some valid expressions: {$VAR.header.record_no} {$VAR.header.checksum & 0x0000ffff} {$VAR.data?(int)[$VAR.data length]:0} Combining these two techniques, you can now create a data formatter for the DataBlock object type. Start by running the program and stopping the debugger with an instance of the DataBlock class in scope. Make sure that Run ➪ Variables View ➪ Enable Data Formatters is checked. Select the DataBlock variable in the variables pane and choose the Run ➪ Variables View ➪ Edit Summary Format. The debugger lets you edit the data formatter for the variable. Now you can enter the data formatter string shown in Figure 18 - 31. ➤ ➤ ➤ FIGURE 18-32 FIGURE 18-31 After it has been entered, this text becomes the data formatter used for every instance of the DataBlock class. The debugger resolves the references and expressions for each instance, creating the more informative summary shown in Figure 18 - 32. The syntax used for references and expressions can be extended to obtain other information about the value or expression. The fi nal display value can be something different from the value to which the expression evaluates. The other types of information that can be extracted from an expression are chosen using one of the column selectors listed in the following table. The “ column ” Data Formatters ❘ 485 c18.indd 485c18.indd 485 1/22/10 12:55:50 PM1/22/10 12:55:50 PM Download at getcoolebook.com 486 ❘ CHAPTER 18 DEBUGGING you are selecting is one of the columns in the variables pane or the Expressions window. In essence, the result of a reference or expression is treated as if it had been entered into the Expressions window. The column selector lets you choose which column in the window will be used as the result of the expression. You can think of an expression result as an object with four properties (value, name, type, and summary) — the column selector lets you choose which property to display. COLUMN SELECTOR DESCRIPTION { expression }:v , % reference %:v The value of the expression — that is, the primitive numerical value that would appear in the Value column of the Expressions window. This is the default column. Omitting the column selector is equivalent to using :v . { expression }:t , % reference %:t The type of the fi nal data object to which the expression evaluates. A numerical expression would result in a primitive data type, such as int or double. The type of an expression that refers to a member variable, or calls a function, will be the type of the expression ’ s result. For example, the expression {[$VAR owner]}:t would display the type of the object returned by the method owner. { expression }:s , % reference %:s This selector results in the text that would appear in the Summary column of the expression. Because the Summary column can be formed using data formatters, this is a way of using other data formatters in portions of your data formatter. You can only use this on expressions that have a summary display. Expressions that result in primitive values do not have any content in their Summary column. { expression }:n , % reference %:n The name of the variable or expression that would appear in the Expression column of the Expressions window. The column is self - referential and not particularly useful. The type column ( :t ) can be useful for displaying the type or class of a member value. For example, if you have a class that manages a collection of homogenous objects, a data formatter of collection of {[$VAR lastObject]}:t would tell you what kind of objects your collection contains. The summary column selector is the most useful. You can use it to construct data formatters from other data formatters. To get a feel for creating your own data formatters, look at the following example. Let ’ s assume you have a project with the DataBlock class shown in Listing 18 - 3, and a subclass named StampedDatablock, shown in Listing 18 - 4. LISTING 18 - 4: DataBlock subclass @interface StampedDataBlock : DataBlock { @private NSCalendarDate* createdDate; NSCalendarDate* modifiedDate; } c18.indd 486c18.indd 486 1/22/10 12:55:51 PM1/22/10 12:55:51 PM Download at getcoolebook.com To create a custom data formatter for these two classes, follow these steps: 1. Build the application, start it under the control of the debugger, and stop at a breakpoint where a DataBlock and StampedDataBlock object are in scope, as shown in Figure 18 - 33. 2. Set the data formatter for the block variable to record %header.record_no%, {(int)[$VAR.data length]} bytes . 3. Set the data formatter for the trackedBlock variable to {(DataBlock*)$VAR}:s, created %createdDate%:s . 4. Continue stepping through the program. FIGURE 18-33 The fi rst data formatter created for the DataBlock class summarizes its contents by accessing its record_no and data instance variables. The debugger now presents a much friendlier summary of the object ’ s state. The StampedDataBlock formatter is a little trickier. The StampedDataBlock class does not inherit the data formatter for DataBlock. Data formatters for each type are independent of one another. Two problems are inherent in creating a data formatter for the new subclass. First, you don ’ t want to repeat everything you wrote for the DataBlock formatter. Secondly, you don ’ t want to write a formatter for the NSCalendarDate member object. The summary column selector lets you avoid both of these problems by setting the data formatter for the StampedDataBlock class to {(DataBlock*)$VAR}:s, created %createdDate%:s . The fi rst expression casts the object to an instance of its superclass and obtains text that would appear in its Summary column, effectively calling the data formatter you created for the DataBlock class. The second reference obtains the value of createdDate and inserts what would appear in its Summary column, essentially using Xcode ’ s built - in data formatter. The fi nal result, shown in Figure 18 - 34, is a data formatter that extends the data formatter of its superclass using a built - in data formatter supplied by Xcode. Data Formatters ❘ 487 c18.indd 487c18.indd 487 1/22/10 12:55:52 PM1/22/10 12:55:52 PM Download at getcoolebook.com 488 ❘ CHAPTER 18 DEBUGGING Troubleshooting Data Formatters Data formatters can be very useful during debugging. You can create data formatters that quickly summarize the state of complex objects. This allows you to concentrate on the high - level logic of your application, rather than spending all of your time digging through the member variables of objects trying to decode their content. Writing data formatters, however, can be a frustrating experience. If there is anything the debugger doesn ’ t like about your data formatter, it won ’ t use it. The following table lists some of the more common problems you can encounter while creating data formatters: TYPE OF PROBLEM SOLUTION Syntax Be extra careful about the syntax of your expressions and references. Quotes Double quotes in the body of an expression must be escaped with a backslash. Example: name “ {[$VAR getProperty:\ “ name\ “ ]}:s ” . Notice that the quotes inside the expression are escaped, but not in the text outside the expression. Unknown types The debugger often does not know the data type of values returned by functions. If you have any doubts, cast the result: author {(NSString*)[$VAR authorName]}:s Execution problems Expressions that call functions have to function perfectly. The formatter name {[$VAR name]}:s will fail if the method name throws an exception, tries to access a NULL variable, can ’ t allocate memory, or any of a limitless number of similar run time problems. The functions that you call using data formatters should be extremely defensive. Null summary You cannot use the :s column selector if the expression results in a data type that has no summary column content. Invalid references Expressions that use other variables in the current stack frame context will fail when interpreted in a di erent stack frame or execution context where those variables don ’ t exist. Data formatters should concern themselves only with examining the contents of the structure or object. FIGURE 18-34 c18.indd 488c18.indd 488 1/22/10 12:55:53 PM1/22/10 12:55:53 PM Download at getcoolebook.com TYPE OF PROBLEM SOLUTION ZeroLink, dynamically loaded libraries This is yet one more situation where dynamically loaded libraries can trip you up. Expressions executed in the debugger will not cause unreferenced symbols to load. If your application hasn ’ t caused a symbol or function to load yet, a data formatter that uses that function or type will fail. Temporary Objects (For Objective - C programmers) Be warned that creating auto - released objects in your data formatters may result in memory leaks. An example would be {(NSString*)[NSString stringWithCharacters: $VAR.uStr.unicode length:$VAR.uStr.length] }:s . The problem here is that the NSString object is created in the context of the debugger and has no auto - release pool. You will see a “ leak ” message in the debugger log. Side E ects Data formatters can call functions in your application. Side e ects, such as altering instance variables or releasing objects, can have unexpected consequences in your application and your debugging e orts. If you are having problems getting a formatter to work, break it down into its individual components and subexpressions and try each one at a time. Slowly build up the expression until you get it working or fi nd the element that thwarts your efforts. Try expressions without the column selector. Cast return values liberally. Replace macros and function calls with constants. Turn off ZeroLink. Add the same function call to your code and try debugging it. Data formatters you defi ne are stored in the ~/Library/Application Support/Apple/Developer Tools/CustomDataViews/CustomDataViews.plist fi le. Data formatters are global to all projects and are not stored in the project document. Sharing data formatters with other developers will require some copying and pasting, or you may just want to exchange CustomDataViews.plist fi les. Beyond Data Formatter Strings Although data formatters can do a lot, they are limited to what can be expressed in a format string. If you need a data formatter that exceeds these capabilities, you can develop your own data formatter plug - in. The descriptions for doing so are in the DataFormatterPlugin.h fi le, buried inside the Xcode application itself at /Developer/Applications/Xcode.app/Contents/PlugIns/ GDBMIDebugging.xcplugin/Contents/Headers/DataFormatterPlugin.h . This fi le contains detailed information about formatter strings, the format of CustomDataViews.plist , and how to create a data formatter plug - in, among other topics. In brief, you create a data formatter plug - in by creating a bundle. The bundle contains its own CustomDataViews.plist fi le. Unlike data formatter strings that you type into the debugger window, the data formatter strings in the bundle ’ s CustomDataViews.plist fi le can call any of the functions defi ned in the plug - in bundle. The sample ManagedObjectDataFormatter project produces a data formatter plug - in for managed objects. You can fi nd it by searching the Xcode documentation for ManagedObjectDataFormatter. Use this project as a template for creating your own data formatter plug - ins. Data Formatters ❘ 489 c18.indd 489c18.indd 489 1/22/10 12:55:54 PM1/22/10 12:55:54 PM Download at getcoolebook.com 490 ❘ CHAPTER 18 DEBUGGING Object Descriptions Like data formatters, many object - oriented languages have adopted conventions for converting any object into a textual representation. In Java, this is the toString() function. Objective - C uses the - [NSObject description] method. If you are using an object that supports one of these standards, you can use the Run ➪ Variables View ➪ Print Description to Console command. The debugger invokes the standard “ to string ” function on the object and sends the result to the debugger console. WATCHPOINTS Watchpoints are breakpoints for data. You can make any variable a watchpoint. Whenever the debugger detects that the value of that variable has changed, it stops your application. Watchpoints sound great, but they are fairly limited. The biggest problem is that your application can ’ t execute any code where the watchpoint variable is out of context, so they are mostly useful for global variables that are always in scope and for catching state changes in a loop. You set a watchpoint by fi rst selecting a variable in the variables pane. Choose the Run ➪ Variables View ➪ Watch Variable command. This places a magnifying glass icon next to the variable as shown in Figure 18 - 35. Start the program executing again, and it breaks at the point just before the variable is altered with a dialog box explaining what is about to happen, also shown in Figure 18 - 35. FIGURE 18-35 You can choose to acknowledge the event and leave the watchpoint set, or disable the watchpoint by clicking the Disable button. Watchpoints are automatically deleted whenever your application exits the context where the watchpoint variable exists. Watchpoints are not retained between debug sessions. You can create an effect similar to a watchpoint using a breakpoint conditional like i!=0 . It ’ s not as convenient as a watchpoint, but it ’ s more durable. To remove a watchpoint, select the variable being watched and choose Run ➪ Variables View ➪ Watch Variable again to remove the check mark. c18.indd 490c18.indd 490 1/22/10 12:55:54 PM1/22/10 12:55:54 PM Download at getcoolebook.com . and choose the Run ➪ Variables View ➪ Edit Summary Format. The debugger lets you edit the data formatter for the variable. Now you can enter the data formatter string shown in Figure 18 - 31 are in scope, as shown in Figure 18 - 33 . 2. Set the data formatter for the block variable to record %header.record_no%, {(int)[$VAR.data length]} bytes . 3. Set the data formatter for the trackedBlock. those variables don ’ t exist. Data formatters should concern themselves only with examining the contents of the structure or object. FIGURE 18 -34 c18.indd 488c18.indd 488 1/22/10 12:55: 53 PM1/22/10