preface

Text Macros are a hidden feature of Xcode, and it wasn’t until Xcode 9.0 that Apple officially allowed developers to customize Text Macros. The following describes the knowledge and application scenarios of text macros in detail.

What are text macros

A Text Macro is a symbol that can be expanded in-place into specific Text. This is common in Xcode file templates, as shown below:

FILEHEADER, FILEBASENAME, and FILEBASENAMEASIDENTIFIER are text macros. For example, when NSObjectObjective -c file template is used to create a file named myObject. m, FILEHEADER is expanded to generate header comments. FILEBASENAME will expand to generate the string MyObject, FILEBASENAMEASIDENTIFIER will expand to generate the string MyObject, as shown below:

read

Xcode templates have file templates and project templates. The template files are stored according to the development platform. The template location for each platform is as follows:

  • MacOS Platform Template:/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates
  • IOS Platform template:/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates
  • TvOS Platform template:/Applications/Xcode.app/Contents/D eveloper/Platforms/AppleTVOS.platform/Developer/Library/Xcode/Templates
  • WatchOS Platform template:/Applications/Xcode.app/Contents/Developer/Platforms/WatchOS.platform/Developer/Library/Xcode/Templates

Expose available text macros

Xcode currently has the following types of text macros available to developers in its official documentation:

Class time:

  • DATE

    The current date, such as 2018/12/20.

  • YEAR

    The current number of years in a four-digit format, such as 2018

  • TIME

    The current time, such as 20:48

Development environment class:

  • RUNNINGMACOSVERSION

    The current macOS version.

  • DEFAULTTOOLCHAINSWIFTVERSION

    Swift version used by the current project.

  • FULLUSERNAME

    The full name of the current system user.

  • USERNAME

    The login name of the current macOS user.

Development project configuration:

  • ORGANIZATIONNAME

    Name of the company configured in the current project.

  • WORKSPACENAME

    The name of the current Workspace. If there is only one Project in the Workspace, the value of this macro is the name of the currently open Project.

  • PROJECTNAME

    Name of the current project.

  • TARGETNAME

    Name of the current Target.

  • PACKAGENAME

    Package name set by the current project Scheme.

  • PACKAGENAMEASIDENTIFIER

    Replace the characters that do not meet the C identifier specifications with the PACKAGENAME after the underscore (_).

  • PRODUCTNAME

    Application name set by Scheme in the current project.

  • COPYRIGHT

    Copyright information about the current project, for example, Copyright © 2018 YK-unit. All rights Reserved.

    Note that this value is an empty string if the current Xcode project does not have a company name configured.

Text file information:

  • FILENAME

    The full name of the current file, including the extension.

  • FILEBASENAME

    Delete FILENAME after the extension, for example, create a file named myObject. m, the value is MyObject.

  • FILEBASENAMEASIDENTIFIER

    Replace characters that do not conform to the C identifier specification with FILEBASENAME after underscore (_), for example, create a file named my-object. m, the value is My_Object.

    Note: The C identifier specification only allows letters (A-z, A-z) and numbers (0-9) and underscores (_). Using this macro will automatically replace other characters with underscores.

  • FILEHEADER

    The text of each text file header.

    Note: This text macro is actually composed of multiple text macros, which are first expanded to generate the following text:

    //  ___FILENAME___
//  ___PACKAGENAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//  ___COPYRIGHT___
//
Copy the code

    Xcode then expands the above macro text to generate the corresponding text, and finally generates the header comment information we see everyday.

Other:

  • NSHUMANREADABLECOPYRIGHTPLIST

    The value of the human-readable copyright information entry in the info.plist file in the Target of the macOS App project. The value includes the key and value of the entry and the XML delimiter, such as:

    <key>NSHumanReadableCopyright</key>
<string>Copyright © 2017 Apple, Inc. All rights reserved.</string>
Copy the code

  • UUID

    When you use this macro, a unique ID is returned. Specific application scenarios need to be explored.

How do I use text macros

To use a text macro, simply add three underscores (_) before and after the text macro, as in FILENAME text macro:

___FILENAME___
Copy the code

How do I format the value of a text macro

The value generated by text macro expansion may not meet development requirements. For example, when creating a file, the developer enters a file name with illegal characters. To do this, Xcode formats the values of text macros by providing modifiers. Use modifiers as follows:

< MACRO > : < modifier > [, < modifier >]...Copy the code

Text macros and modifiers are separated by a semicolon (:). Multiple modifiers can be separated by commas (,).

By combining a text macro with a specific modifier, you can change the final value of the text macro, such as the following macro that removes the FILENAME extension and replaces characters that do not conform to the C identifier with an underscore (_) :

FILENAME:deletingPathExtension,identifier
Copy the code

By this time the FILENAME: deletingPathExtension, identifier FILEBASENAMEASIDENTIFIER equivalent

The modifiers currently provided by Xcode are:

  • identifier

    Replace all characters that do not conform to the C identifier specification with underscores (_).

    Note: The C identifier specification allows only letters (A-z, A-Z) and numbers (0-9) and underscores (_).

  • bundleIdentifier

    Replace all characters that do not conform to the bundle identifier specification with a hyphen (-).

    Note: The bundle identifier specification only allows letters (A-z, A-z) and numbers (0-9) and hyphens (-).

  • rfc1034Identifier

    Replace all characters that do not comply with the rfc1034 identifier specification with a hyphen (-)

  • xml

    Replace some special XML characters with their escape characters. For example, < is replaced by <.

  • deletingLastPathComponent

    Removes the last path component from the expanded string.

  • deletingPathExtension

    Removes the extension from the expanded string.

  • deletingTrailingDot

    Delete all periods at the end of sentences (.)

  • lastPathComponent

    Returns only the last path component of the character.

  • pathExtension

    Returns the extension of a character.

Application of text macros

Starting with Xcode 9.0, developers can customize text macros (overwriting existing text macros or adding new ones). However, there are few application scenarios of text macros in actual development. Currently, only two application scenarios have been found (if there are other scenarios, please add them) :

  • Custom file header comments
  • Add a uniform prefix to each class you create

The following shows how to implement the above scenario.

However, to do this, the developer needs to create a file named idetemplatemacros.plist and place the file in one of the following directories:

Note:

  • Different locations have different spheres of influence.
  • IDETemplateMacros.plistFiles can be placed in any of the following locations. But it is recommended to keep it in one place only.
  • When there are multipleIDETemplateMacros.plistXcode will only use the first one it findsIDETemplateMacros.plist.

  • Project user Data location:

    <ProjectName>.xcodeproj/xcuserdata/[username].xcuserdatad/IDETemplateMacros.plist

    Impact: Files created by the user specified in the current Project (username) are affected

  • Project shared data location:

    <ProjectName>.xcodeproj/xcshareddata/IDETemplateMacros.plist

    Scope: Affects files created by all members of the current Project

  • Workspace User data location:

    <WorkspaceName>.xcworkspace/xcuserdata/[username].xcuserdatad/IDETemplateMacros.plist

    Scope: Files created by the specified user (username) in the current Workspace will be affected

  • Workspace shared data location:

    <WorkspaceName>.xcworkspace/xcshareddata/IDETemplateMacros.plist

    Scope: The files created by all members in the Workspace are affected

  • User Xcode data location:

    ~/Library/Developer/Xcode/UserData/IDETemplateMacros.plist

    Impact scope: The files created by the current Xcode are affected

Custom file header comments

In the Xcode file template, the FILEHEADER text macro is used to expand and generate header comments, so just redefine FILEHEADER in ideTemPlatemacros.plist. The edited idetemplatemacros. plist is as follows:

<?xml version="1.0" encoding="UTF-8"? >

      
<plist version="1.0">
<dict>
	<key>FILEHEADER</key>
	<string>// __ _,--="=--,_ __ // / \." .-. "./ \ // / ,/ _ : : _ \/` \ // \ `| /o\ :_: /o\ |\__/ // `-'| :="~` _ `~"=: | / / \ ` (_) ` / / /. - -. \ | /. - "" -. / /. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- {} -- | /. - '-. \ | -- {} -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --. / /) _) (_) _) \_/`~-===-~`\_/ (_(_(_) ( // // File Name: ___FILENAME___ // Product Name: ___PRODUCTNAME___ // Author: ___AUTHOR___ // Swift Version: ___DEFAULTTOOLCHAINSWIFTVERSION___ // Created Date: ___DATETIME___ / / / / Copyright © ___YEAR___ ___ORGANIZATIONNAME___. / / All rights reserved. / /) ( / / '-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --'</string>
	<key>AUTHOR</key>
	<string>___USERNAME___@___ORGANIZATIONNAME___</string>
	<key>DATETIME</key>
	<string>___DATE___ ___TIME___</string>
</dict>
</plist>
Copy the code

Note: The example not only redefines FILEHEADER, but also adds new text macros AUTHOR and DATETIME.

The header of the text file created with Xcode is commented as follows:

The dog graph in the comment is generated using the command line character shape tool Boxes.

Boxes allows you to create a variety of character shapes, which should be explored by interested children.

Add a uniform prefix to each class you create

In the Xcode file template, the FILEBASENAMEASIDENTIFIER text macro is used to expand the generated class name, so just redefine FILEBASENAMEASIDENTIFIER in ideTemPlatemacros.plist. The edited idetemplatemacros. plist is as follows:

<?xml version="1.0" encoding="UTF-8"? >

      
<plist version="1.0">
<dict>
	<key>FILEBASENAMEASIDENTIFIER</key>
	<string>YK___FILENAME:deletingPathExtension,identifier___</string>
</dict>
</plist>
Copy the code

When you create a class with Xcode, the class prefix starts with YK, as shown in the figure below:

The resources

  • The Xcode”