Text macro format
Including other text macros
To include another text macro, add three underscore (_
) characters before and after the macro name:
1
___<MacroName>___
Modifying text macro expansion
You can modify the final expansion of the text macro by adding one or more modifiers. Add a modifier to a text macro by placing a colon (:
) at the end of the macro followed by the modifier. Add multiple modifiers by separating each one with a comma (,
).
1
<MACRO>:<modifier>[,<modifier>]…
For example, the following macro will remove the path extension from the FILENAME
macro:
1
FILENAME:deletingPathExtension
To turn the modified macro above into a valid C identifier, add the identifier
macro:
1
FILENAME:deletingPathExtension,identifier
Modifiers
bundleIdentifier
: Replaces any non-bundle identifier characters with a hyphen (-
).
deletingLastPathComponent
: Removes the last path component from the expansion string.
deletingPathExtension
: Removes any path extension from the expansion string.
deletingTrailingDot
: Removes any trailing dots (.
).
identifier
: Replaces any non-C identifier characters with an underscore (_
).
lastPathComponent
: Returns just the last path component of the expansion string.
pathExtension
: Returns the path extension of the expansion string.
rfc1034Identifier
: Replaces any non-rfc1034 identifier characters with a hyphen (-
).
xml
: Replaces special xml characters with the corresponding escape string. For example, less-than (<
) is replaced with <
Text macros reference
COPYRIGHT
A copyright string that uses the company name of the team for the project. If there is no company name, the string is blank.
The example shows a copyright string when the company is set to “Apple”.
1
Copyright © 2018 Apple. All rights reserved.
DATE
The current date.
DEFAULTTOOLCHAINSWIFTVERSION
The version of Swift used for the default toolchain.
FILEBASENAME
The name of the current file without any extension.
FILEBASENAMEASIDENTIFIER
The name of the current file encoded as a C identifier.
FILEHEADER
The text placed at the top of every new text file.
FILENAME
The full name of the current file.
FULLUSERNAME
The full name of the current macOS user.
NSHUMANREADABLECOPYRIGHTPLIST
The entry for the human readable copyright string in the Info.plist file of a macOS app target. The value of the macro must include the XML delimiters for the plist. For example, a valid value is:
1
2
<key>NSHumanReadableCopyright</key>
<string>Copyright © 2018 Apple, Inc. All rights reserved.</string>
ORGANIZATIONNAME
The name for your organization that appears in boilerplate text throughout your project folder. The organization name in your project isn’t the same as the organization name that you enter in App Store Connect.
PACKAGENAME
The name of the package built by the current scheme.
PACKAGENAMEASIDENTIFIER
A C-identifier encoded version of the package name built by the current scheme.
PRODUCTNAME
The app name of the product built by the current scheme.
PROJECTNAME
The name of the current project.
RUNNINGMACOSVERSION
The version of macOS that is running Xcode.
TARGETNAME
The name of the current target.
TIME
The current time.
USERNAME
The login name for the current macOS user.
UUID
Returns a unique ID. The first time this macro is used, it generates the ID before returning it. You can use this macro to create multiple unique IDs by using a modifier. Each modifier returns an ID that is unique for that modifier. For example, the first time the UUID:firstPurpose
modifier is used, the macro generates and returns a unique ID for that macro and modifier combination. Subsequent uses of the UUID:firstPurpose
modifier return the same ID. Adding the UUID:secondPurpose
modifier generates and returns a different ID that will be unique to UUID:secondPurpose
, and different from the ID for UUID:firstPurpose
.
WORKSPACENAME
The name of the current workspace. If there is only one project open, then the name of the current project.
YEAR
The localized year string for the current year.
Customize text macros
Text macros are symbols that are expanded in-place to the specified text. They are used in files and other places in Xcode, such as the header text for a new file or the project name. You can customize existing macros and add your own macros in a project, for all users of a project, or for all of Xcode. Customizing a macro requires two things:
- A plist named
IDETemplateMacros.plist
at an appropriate location. - An entry in
IDETemplateMacros.plist
for the text macro.
Xcode looks for the value of a text macro in the following locations and uses the first matching macro:
Project user data: <ProjectName>.xcodeproj/xcuserdata/[username].xcuserdatad/IDETemplateMacros.plist
.
Project shared data: <ProjectName>.xcodeproj/xcshareddata/IDETemplateMacros.plist
Workspace user data: <WorkspaceName>.xcworkspace/xcuserdata/[username].xcuserdatad/IDETemplateMacros.plist
.
Workspace shared data: <WorkspaceName>.xcworkspace/xcshareddata/IDETemplateMacros.plist
.
User Xcode data: ~/Library/Developer/Xcode/UserData/IDETemplateMacros.plist
.
Adding or customizing a text macro
- Open desired the
IDETemplateMacros.plist
file. - Add a new entry to the top level dictionary.
- Set the key for the new entry to the name of the text macro you want to customize or to add.
- Set the type of the new entry to String.
- Set the value of the new entry to the desired text.
- Save the file. Your macro is now available for use.
Adding the IDETemplateMacros.plist file
- Choose File > New File.
- Click on Property List and click Next.
- Set the top level type to Dictionary.
- Save the file as “IDETemplteMacros.plist” in the desired location.