Writing Data Formatters

You can provide your own data formatters to display data types defined by your program. To edit the formatter associated with a variable value or variable summary, select the variable in the Variable list in the debugger and double-click in the appropriate column of the Variable list in the debugger. You can also choose Run > Variables View > Edit Summary Format.

Data formatters can contain literal text and references to certain values and expressions.

• Literal text. You can add explanatory text or labels to identify the data presented by the format string.

• References to values within a structured data type. You can access any member of a structured variable from the format string for that variable. The syntax for doing so is %<pathToValue>%, where <pathToValue> is the period-delimited path to the value you want to access in the current data structure.

  In C++, to access a member defined in the superclass of an object, the path to the member must include the name of the superclass. For example, %Superclass.x%. You don’t need to include the public, protected, and private, keywords in the path.

• Expressions, including function or method calls. The syntax for an expression is {<expression>}. To reference the variable itself in <expression>, use $VAR. For example, to display the name of a notification—of type NSNotification—you can use {(NSString *)[$VAR name]}:s. See Data Formatter Macros to learn how to access dynamic structures in data formatters.

• References to columns in the Variable list. When Xcode resolves a data formatter, it replaces the member reference or expression with the value that was obtained by evaluating the reference or expression. This value is the same value found in the Value column of the Variable list. You can, however, specify that Xcode use the contents of any column in the Variable list—Variable name, Type, Value, or Summary. To do so, add :<referencedColumn> after the expression or member reference, where <referencedColumn> is a letter indicating which Variable-list column to access. So, the syntax for accessing a value in a structured data type becomes %<pathToValue>%:<referencedColumn>. Table 8-1 shows the possible values for referencing variable display columns.

  Table 8-1  Characters for referencing variable display columns

  Reference	Variable view column
  n	Variable (shows the variable name)
  v	Value
  t	Type
  s	Summary

Data Formatter Example

The following example uses the CGRect data type to illustrate how you can build format strings using member references and expressions. (Note that because Apple provides format strings for the CGRect data type, Xcode already knows how to display the contents of variables of that type). The CGRect data type is defined as follows:

struct CGRect { CGPoint origin; CGSize size; }; typedef struct CGRect CGRect;

Assuming that the goal is to create a format string that displays the origin and size of variables of type CGRect, there are many ways you can write such a format string. For example, you can reference members of the origin and size fields directly. Of course, each of these two fields also contains data structures, so simply referencing the values of those fields isn’t very interesting; the values you want are in the data structures themselves. One way you can access those values is to include the full path to the desired field from the CGRect type. For example, to access the height and width of the rectangle, in the height and width fields of the CGSize structure in the size field you could use the references %size.height% and %size.width%. A sample format string using these references might be similar to the following:

height = %size.height%, width = %size.width%

You could write a similar reference to access the x and y coordinates of the origin. Or, if you already have a data formatter for values of type CGPoint that displays the x and y coordinates of the point in the Summary column of the Variable list—such as (%x%, %y%)—you can leverage that format string to display the contents of the origin field in the data formatter for the CGRect type. You can do so by referencing the Summary column for CGPoint, as in the following format string:

origin: %origin%:s

When Xcode evaluates this format string, it accesses the origin field and retrieves the contents of the Summary column for the CGPoint data type, substituting it for the reference to the origin field. The end result is equivalent to writing the format string origin: (%origin.x%, %origin.y%).

You can combine this format string with the format string for the size field and create a data format string for the CGRect type similar to the following:

origin: %origin%:s, height = %size.height%, width = %size.width%

For example, a rectangle with the origin (1,2 ), a width of 3, and a height of 4 results in the following display:

origin: (1, 2), width=3, height=4.

You can also write a data formatter to display the same information using an expression such as the following:

origin: {$VAR.origin}:s, height = {$VAR.size.height}, width = {$VAR.size.width}

When Xcode evaluates this expression for a variable, it replaces $VAR with a reference to the variable itself. Of course, using an expression to perform a simple value reference is not necessary. Another example of an expression in a format string is {(NSString *)[$VAR name]}:s to display the name of a notification, of type NSNotification.

When you specify a custom data formatter for a variable of a given type, that format string is also used for all other variables of the same type. Note, however, that you cannot specify a custom format for string types, such as NSString, char*, and so on. Custom data formatters that you enter in the debugger are stored at:

~/

   Library/

      Application Support/

         Developer/

            Shared/

               Xcode/

                  CustomDataViews/

                     CustomDataViews.plist

Data-Formatter Bundle Requirements

A data-formatter bundle must contain these items:

• CustomDataViews.plist file. Defines the front-end (the text representation) of the data formatter.

• _pbxgdb_plugin_function_list *_pbxgdb_plugin_functions global symbol. Contains a list of pointers to the functions a plug-in exposes. The source file containing the data-formatter functions defines this symbol.

Data-formatter bundles and the data-formatter function they define must meet these requirements:

• Data-formatter functions must return char * for their output to be displayed in the Summary column of the debugger Variables list.

• Data-formatter bundles must be installed in the <Xcode> directory.

Data-Formatter Bundle Example

The following steps create a data-formatter bundle that formats a structure containing temperature data into its Celsius or Fahrenheit representation. Figure 8-1 shows the structure of the finished project and highlights the files that need to be added the project.

1. Create a Mac OS X Bundle project based on the Core Foundation framework.

   

2. Name the project TemperatureFormatter.

3. Delete the External Frameworks and Libraries group from the TemperatureFormatter group in the Groups & Files list.

Tips on using the Expressions window

For best results, follow these tips when using the Expressions window:

• The expression is evaluated in the current frame. As the frame changes, the expression may go in and out of scope. When an expression goes out of scope, Xcode notes this in the Summary column.

• Always cast a function to its proper return type. The debugger doesn’t know the return type for many functions. For example, use (int)getpid() instead of getpid().

• Expressions and functions can have side effects. For example, i++ increments i each time it’s evaluated. If you step though 10 lines of code, i is incremented 10 times.