Syntax - Aware Editing WHAT'S IN THIS CHAPTER? Using and customizing syntax coloring Folding code blocks Accepting code completion suggestions Inserting text macros In Chapter 6, you learned a lot of editing features specifi cally designed to make writing source code easier, but most of these features are just textual aides that know little or nothing about your code and symbols. Xcode ’ s syntax - aware features pick up where the basic text editing aides leave off — with some overlap between them. Syntax - aware editing means that the editor analyzes your source code and uses that knowledge to highlight your code ’ s structure and symbols, offer suggestions, and make intelligent changes. You ’ ve already encountered a few syntax - aware features. The Balance command, which fi nds a matching brace or bracket, understands the block structure, string format, comment syntax, and other details of your programming language. This chapter describes the various syntax - aware editing features and tools available in Xcode. Xcode can know a lot about your code ’ s structure, and its vocabulary is quite broad; it understands languages from ADA to XML. The code analysis is performed continuously and in the background. It won ’ t get in the way of your development, and it ’ s almost always up - to - date. ➤ ➤ ➤ ➤ 7 c07.indd 127c07.indd 127 1/22/10 12:23:58 PM1/22/10 12:23:58 PM Download at getcoolebook.com 128 ❘ CHAPTER 7 SYNTAX-AWARE EDITING CODE SENSE Code Sense is the technology that analyzes your code continuously while you write it. It assembles and maintains a database, called the Code Sense index , of the classes, variables, methods, functions, structures, types, data models, and constants defi ned in your application. It also tracks class inheritance and fi le references. Many of the syntax - aware features described in this chapter rely on Code Sense. Code sense updates its index incrementally, analyzing only the function or method that you ’ re editing and the source fi les that have been saved recently. Updates are typically quite fast — on the order of a few seconds. This means that Code Sense recognizes local variables in the method you ’ re editing almost instantly, and changes to classes, methods, functions, and types as soon as you save the fi le. If a symbol doesn ’ t appear to be in the Code Sense index (that is, you can ’ t jump to its defi nition, or it doesn ’ t appear in the auto - completion list), save all of your source fi les to disk (File ➪ Save All, Option + Command + S). If the symbol still fails to appear within a reasonable amount of time, compile your code and check for syntax errors. Code Sense may not be able to index source fi les that won ’ t compile. Enabling Code Sense You enable Code Sense globally for all projects in the Code Sense panel of the Xcode preferences, as shown in Figure 7 - 1. FIGURE 7 - 1 c07.indd 128c07.indd 128 1/22/10 12:24:07 PM1/22/10 12:24:07 PM Download at getcoolebook.com The Enable for All Projects option turns all Code Sense – dependent features on or off. This includes some syntax coloring, code completion, jump to defi nition, the Included Files and Class Hierarchy navigation menus, the Symbols smart group, and the Class Browser. The only real motivation for disabling Code Sense is to avoid the CPU, memory, and disk space required to maintain it, but these seem like small prices to pay for the enormous benefi ts that Code Sense provides. I would recommend disabling it only if absolutely necessary. Code Sense works by interacting intimately with the compiler. This also requires that all the source items are members of a “ native ” target. Native targets are targets that Xcode knows how to build (see Chapter 16), and by extension it knows what compilers will be used to compile each source fi le. External (non - native) targets defer the actual build process to some external program, such as Make or Ant. Items in external targets cannot use Code Sense. TIP TO REMEMBER If you would like to use Code Sense in a project that requires the use of an external target, you still can. Simply create an additional native target that includes all of the source fi les and libraries you want Code Sense to see. Code Sense indexes all of the native source fi les referred to in a project. You never have to build that target; it just has to be defi ned. Because Code Sense works silently in the background, it ’ s sometimes hard to tell whether a symbol isn ’ t in the Code Sense index or whether Code Sense just hasn ’ t reindexed it yet. The Window ➪ Activity window tells when Code Sense is working and how far along it is. If Code Sense isn ’ t working, and a symbol isn ’ t in the index, either there ’ s a syntax error preventing Code Sense from indexing your source fi les or the index needs to be rebuilt. Reindexing a Project If you suspect that the Code Sense index has gotten out of synchronization with your project, open the Info widow for the project (Project ➪ Edit Project Settings). At the bottom of the project ’ s Info window, shown in Figure 7 - 2, is a Rebuild Code Sense Index button. Clicking it fl ushes the index for that project and queues Code Sense to index the entire project. For large projects, this could take some time. The Code Sense index is stored in your account ’ s ~/Library/Caches folder. If the Code Sense index is ever deleted or is not in synchronization, Xcode automatically rebuilds it. FIGURE 7-2 Code Sense ❘ 129 c07.indd 129c07.indd 129 1/22/10 12:24:20 PM1/22/10 12:24:20 PM Download at getcoolebook.com 130 ❘ CHAPTER 7 SYNTAX-AWARE EDITING SYNTAX COLORING The most visible and passive of the syntax - aware editing features is syntax coloring . It uses a basic knowledge of a language ’ s syntax to colorize the text of source code so that keywords, comments, literals, symbols, and other language elements are displayed in distinctive colors, fonts, or styles. The intent is to make it easier to read the code by highlighting the functionality of elements in the source. Customizing Syntax Coloring You control the colors that syntax coloring uses, or whether syntax coloring is done at all, in the Fonts & Colors tab of the Xcode Preferences, shown in Figure 7 - 3. FIGURE 7-3 Each entry in the table controls the color, and possibly the font, used to display a category of editor element. The entire collection is collectively referred to as a theme . Xcode provides several themes that you can choose from, and you can create your own. The major categories are described in the following table. You can control syntax - aware coloring globally with the Use Syntax - Based Formatting and Color Indexed Symbols options. Turning the fi rst option off disables all syntax coloring. With syntax coloring enabled, the second option determines whether only basic language elements are colorized, or whether project symbols in the Code Sense index are also colorized. c07.indd 130c07.indd 130 1/22/10 12:24:21 PM1/22/10 12:24:21 PM Download at getcoolebook.com In addition to the syntax coloring, this preference pane also establishes the font and color scheme used in all editing panes. This includes the background color of the pane and the color used to highlight selected text. The list is broadly organized into three groups of entries: The Background, Selection, Insertion Point, and Plain Text categories apply globally to all text editor panes. The categories Comments through Attributes affect recognized language elements when the Use Syntax - Based Formatting option is enabled. The remaining categories change the color of recognized symbols when the Color Indexed Symbols option is enabled. Text that isn ’ t colorized — either because it ’ s not one of the recognized categories or you ’ ve turned off the Use Syntax - Based Formatting or Color Index Symbols options — is displayed using the Plain Text color and font. CATEGORY DESCRIPTION Background The background color for all editor panes. Make sure that it contrasts well with the colors chosen for text selections, the insertion point, and text. Any element that ’ s the same color as the background will be invisible. Selection, Insertion Point The colors used to indicate the current text selection and insertion point. Plain Text The color, font, and size for all text that ’ s not colorized using one of the other categories. Comments Comments in the source code. For C, Java, and similar languages this means text enclosed by / * and * / character sequences, and the text following a // . For property lists and shell scripts, comments are lines that begin with # . AppleScript denotes comments between pairs of ( * and * ) and after - - . Documentation Comments Java ’ s JavaDoc and Darwin ’ s HeaderDoc tools scan source code fi les and generate documentation for a program or library. Both rely on specially formatted comments that begin with / * * or / * ! and contain annotations and keywords. Documentation Comments Keywords JavaDoc and HeaderDoc comments can also include any number of keywords that identify the di erent parts of the comment. For instance, the @param keyword is used to document a single parameter of a function call. Strings String literals contained between pairs of double quotes. Xcode interprets escape characters; it won ’ t be confused by strings such as “ North Carolina (the \ “ Tar Heel\ ” State) “ . ➤ ➤ ➤ continues Syntax Coloring ❘ 131 c07.indd 131c07.indd 131 1/22/10 12:24:22 PM1/22/10 12:24:22 PM Download at getcoolebook.com 132 ❘ CHAPTER 7 SYNTAX-AWARE EDITING CATEGORY DESCRIPTION Characters Character literals contained between single quotes. Numbers Numeric constants. Xcode recognizes decimal, octal, and hexadecimal numbers that begin with 0x . It does not recognize numeric Unicode constants. Keywords The standard keywords for the language. Obviously, this will vary wildly from one language to the next. For C - like languages, words such as for , if , else , and then are keywords. The word register is a keyword in a C ++ source fi le, but not in a Java fi le. For shell scripts, the keywords are the bash built - in commands. Preprocessor Statements Preprocessor directives used by C - based languages, such as #include or #define . Xcode understands multi - line preprocessor statements. URLs Any valid URL. Font & Color themes provided by Xcode are not editable. To create a customized theme, begin by clicking the Duplicate button to make a copy of any existing theme. To delete a custom theme, select it as the current theme and click the Delete button. If you attempt to edit a built - in theme, Xcode alerts you and gives you the opportunity to duplicate it. To customize an element, select the category (or categories) in the list and apply any of the text styling commands found in the Edit ➪ Format menu. As a shortcut, double - clicking a font name opens the Font palette, and double - clicking a color opens the Color - picker palette. Font styles (bold, italic, underline, strikethrough) are generally ignored, unless the font family has variants for specifi c styles like bold or italic. You can only set the color of the background, selection, insertion point, and index symbol types; these categories don ’ t use a font, or will use the font of the Plain Text category. Changing Syntax Coloring for a Single File Syntax coloring is naturally dependent on Xcode knowing in what language your source fi le is written. By default, Xcode uses the fi le ’ s type (see the “ Source Item Attributes ” section in Chapter 5) to determine this. The vast majority of time this is correct. If, for any reason, Xcode guesses wrong, you can manually specify that it use a different language when interpreting the fi le by selecting the correct language (or None) from the View ➪ Syntax Coloring menu, as shown in Figure 7 - 4. (continued) c07.indd 132c07.indd 132 1/22/10 12:24:22 PM1/22/10 12:24:22 PM Download at getcoolebook.com Syntax Coloring ❘ 133 FIGURE 7 - 4 When Default is selected, the language Xcode has chosen is displayed as a dash in the menu of available languages. For fi les that belong to a project, this setting is stored in the project document and is persistent. Otherwise, the selection is lost when the editor pane is closed. c07.indd 133c07.indd 133 1/22/10 12:24:23 PM1/22/10 12:24:23 PM Download at getcoolebook.com 134 ❘ CHAPTER 7 SYNTAX-AWARE EDITING CODE FOLDING Code folding highlights blocks of structured text and allows them to be collapsed — or “ folded ” — so that you can concentrate on the higher - level structure of your code. Code folding is supported in all C - like languages (C + + , Objective - C, Java) and XML, as shown in Figure 7 - 5. To see and use code folding, you must have the Show Code Folding Ribbon option turned on in the Text Editing pane of the Xcode Preferences. FIGURE 7-5 The code folding ribbon appears between the gutter and the text. The depth of the blocks in your text is graphed using gradations of grey; the darker the ribbon, the deeper the text in that line is nested. Hovering your cursor over the ribbon presents collapse controls for the block of text that begins on that line. Code Focus Code focus highlights a block of text in the editor, making it easier to see what the block encompasses, as shown in the bottom window in Figure 7 - 5. Code focus appears when you hover your cursor over the code folding ribbon. Uncheck the Code Focus option in the preferences to disable this behavior. If you fi nd code focus really useful, even temporarily, and are tired of moving your cursor over the code folding ribbon, you can have code focus follow your current text selection by choosing View ➪ Code Folding ➪ Focus Follows Selection (Control + Option + Command + F). Now, the code focus animation will continuously highlight the block containing the current selection or insertion point. Invoke the command a second time to toggle the feature off again. c07.indd 134c07.indd 134 1/22/10 12:24:23 PM1/22/10 12:24:23 PM Download at getcoolebook.com . persistent. Otherwise, the selection is lost when the editor pane is closed. c07.indd 133 c07.indd 133 1/22/10 12:24: 23 PM1/22/10 12:24: 23 PM Download at getcoolebook.com 134 ❘ CHAPTER 7 SYNTAX-AWARE. (continued) c07.indd 132 c07.indd 132 1/22/10 12:24:22 PM1/22/10 12:24:22 PM Download at getcoolebook.com Syntax Coloring ❘ 133 FIGURE 7 - 4 When Default is selected, the language Xcode has chosen is displayed. at all, in the Fonts & Colors tab of the Xcode Preferences, shown in Figure 7 - 3. FIGURE 7 -3 Each entry in the table controls the color, and possibly the font, used to display a category