Xcode 文本宏（Text Macros）

2019 - 07 - 11

Posted by York_魚

前言

文本宏（Text Macros）是Xcode隐藏的特性，直到Xcode 9.0后，苹果官方才开始允许开发者进行自定义文本宏。下面将会详细介绍文本宏的相关知识和应用场景。

什么是文本宏

文本宏（Text Macro）是一种可以就地展开（expanded in-place）为特定文本的符号。其常见于Xcode文件模板中，如图所示：

图中的FILEHEADER、FILEBASENAME、FILEBASENAMEASIDENTIFIER就是所说的文本宏。Xcode在使用文件模板创建文件时，会把文件模板中的文本宏，展开生成特定的文本，如使用NSObjectObjective-C文件模板创建一个文件名为MyObject.m的文件时，FILEHEADER会展开生成头部注释信息，FILEBASENAME会展开生成字符串MyObject，FILEBASENAMEASIDENTIFIER会展开生成字符串MyObject，如下图所示：

延伸阅读

Xcode模板有文件模板和工程模板。模板文件按照开发平台存放，其中每个平台的模板位置如下：

  • macOS平台模板：/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates
  • iOS平台模板：/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates
  • tvOS平台模板：/Applications/Xcode.app/Contents/D eveloper/Platforms/AppleTVOS.platform/Developer/Library/Xcode/Templates
  • watchOS平台模板：/Applications/Xcode.app/Contents/Developer/Platforms/WatchOS.platform/Developer/Library/Xcode/Templates

公开可用的文本宏

当前Xcode在其官方文档公开给开发者可用的文本宏有以下几类：

时间类：

  • DATE

    当前的日期，如2018/12/20。

  • YEAR

    四位数字格式的当前年数，如2018

  • TIME

    当前的时间，如20:48

开发环境类：

  • RUNNINGMACOSVERSION

    当前macOS系统的版本。

  • DEFAULTTOOLCHAINSWIFTVERSION

    当前工程使用的Swift版本。

  • FULLUSERNAME

    当前系统用户的全名。

  • USERNAME

    当前macOS用户的登录名。

开发工程配置类：

  • ORGANIZATIONNAME

    当前工程配置的公司名称。

  • WORKSPACENAME

    当前Workspace的名称。如果Workspace中只有一个 Project，那么这个宏的值便是当前打开的Project的名称。

  • PROJECTNAME

    当前工程的名称。

  • TARGETNAME

    当前Target的名称。

  • PACKAGENAME

    当前工程Scheme所设置的包名。

  • PACKAGENAMEASIDENTIFIER

    把不符合C语言标识符规范的字符替换为下划线（_）后的PACKAGENAME。

  • PRODUCTNAME

    当前工程Scheme设置的应用名称。

  • COPYRIGHT

    当前工程的版权信息，如Copyright © 2018 YK-Unit. All rights reserved.。

    需要注意的是，若当前Xcode工程没有配置公司名，该值会是一个空字符串。

文本文件信息类：

  • FILENAME

    当前文件的完整名称，包括扩展名。

  • FILEBASENAME

    删除掉扩展名后的FILENAME，如创建一个名为MyObject.m的文件，该值为MyObject。

  • FILEBASENAMEASIDENTIFIER

    把不符合C语言标识符规范的字符替换为下划线（_）后的FILEBASENAME，如创建一个名为My-Object.m的文件，该值为My_Object。

    注：C语言标识符规范只允许使用字母（A-Z, a-z）和数字（0-9）以及下划线（_），使用这个宏会把其他的字符自动替换成下划线。

  • FILEHEADER

    每个文本文件头部的文本。

    注：该文本宏其实是由多个文本宏组成，其首先是展开生成以下文本：

    //  ___FILENAME___
//  ___PACKAGENAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//  ___COPYRIGHT___
//

    之后Xcode再把上述的宏文本展开生成对应的文本，最后生成的就是我们日常看到的文件头部注释信息了。

其他：

  • NSHUMANREADABLECOPYRIGHTPLIST

    macOS app工程的target中的Info.plist 文件中人类可读的版权信息条目的值，该值包括这个条目的key和value以及XML的分隔符，如：

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

  • UUID

    使用这个宏的时候，会返回一个唯一ID。具体应用场景待探索。

如何使用文本宏

使用文本宏的方式很简单，只需要在文本宏之前和之后添加三条下划线（_）即可，如使用FILENAME文本宏：

___FILENAME___

如何格式化文本宏的值

文本宏展开生成的值，不一定符合开发要求，如创建文件时，开发者输入的文件名带有非法的字符。为此，Xcode通过提供修饰符（modifier）来对文本宏的值进行格式化。使用修饰符的方法如下：

<MACRO>:<modifier>[,<modifier>]…

文本宏和修饰符之间用分号（:）分隔。多个修饰符之间可以用逗号（,）分隔。

把文本宏和特定的修饰符结合起来后，就可以修改文本宏的最终值，如下面这段宏可以删除掉的FILENAME的扩展名以及使用下划线（_）替换掉不符合C标识符的字符：

FILENAME:deletingPathExtension,identifier

这时候的FILENAME:deletingPathExtension,identifier等同于FILEBASENAMEASIDENTIFIER

当前Xcode提供的修饰符有：

  • identifier

    用下划线（_）替换所有不符合C语言标识符规范的字符。

    注：C语言标识符规范只允许使用字母（A-Z, a-z）和数字（0-9）以及下划线（_）

  • bundleIdentifier

    用连字符（-）替换所有不符合bundle标识符规范的字符。

    注：bundle标识符规范只允许使用字母（A-Z, a-z）和数字（0-9）以及连字符（-）。

  • rfc1034Identifier

    用连字符（-）替换所有不符合rfc1034标识符规范的字符

  • xml

    将一些特殊的XML字符用其转义字符替换。如，<会被 &lt 替换。

  • deletingLastPathComponent

    从展开的字符串中删除最后一个路径组件 (path component)。

  • deletingPathExtension

    从展开的字符串中删除扩展名。

  • deletingTrailingDot

    删除所有句子末尾的句点（.）

  • lastPathComponent

    仅返回字符最后一个路径组件。

  • pathExtension

    返回字符的扩展名。

文本宏的应用

从Xcode 9.0开始，开发者可以自定义文本宏（覆盖已有的文本宏或者添加新的文本宏）。但是，实际开发中，文本宏的应用场景很少，目前暂时只发现了2个应用场景（若有其他场景，欢迎补充）：

  • 自定义文件头部注释
  • 给创建的类都添加统一前缀

下面将会演示如何如何实现上述场景。

但是，在这之前，开发者需要创建一个名为IDETemplateMacros.plist的文件，并把文件放置在下面文件目录列表中的一个：

注意：

  • 不同位置具有不同的影响范围。
  • IDETemplateMacros.plist文件可以放置到以下几个位置中的任何一个。但是建议只放置在一个地方。
  • 当存在多个IDETemplateMacros.plist文件时，Xcode只会使用最先找到的IDETemplateMacros.plist。

  • Project user data位置:

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

    影响范围：对当前 Project 指定的用户（username）创建的文件有影响

  • Project shared data位置:

    <ProjectName>.xcodeproj/xcshareddata/IDETemplateMacros.plist

    影响范围：对当前 Project 的所有成员创建的文件有影响

  • Workspace user data位置:

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

    影响范围：对当前的 Workspace 下的指定的用户（username）创建的文件有影响

  • Workspace shared data位置:

    <WorkspaceName>.xcworkspace/xcshareddata/IDETemplateMacros.plist

    影响范围：对当前 Workspace 下的所有成员创建的文件有影响

  • User Xcode data位置:

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

    影响范围：对当前 Xcode 创建的文件都有影响

自定义文件头部注释

Xcode文件模板中，使用FILEHEADER文本宏来展开生成头部注释，所以只需要在IDETemplateMacros.plist中重定义FILEHEADER即可。编辑后的IDETemplateMacros.plist如下:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<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>

注意：示例中不止是重定义FILEHEADER，还新增了新的文本宏AUTHOR和DATETIME。

这时候使用Xcode创建的文本文件的头部注释如下：

注释中的dog图形是使用命令行字符形状工具boxes生成。

boxes支持创建各种字符形状，有兴趣的童鞋不妨去探索下。

给创建的类都添加统一前缀

Xcode文件模板中，使用FILEBASENAMEASIDENTIFIER文本宏来展开生成类名，所以只需要在IDETemplateMacros.plist中重定义FILEBASENAMEASIDENTIFIER即可。编辑后的IDETemplateMacros.plist如下:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>FILEBASENAMEASIDENTIFIER</key>
    <string>YK___FILENAME:deletingPathExtension,identifier___</string>
</dict>
</plist>

这时候使用Xcode创建的一个类时，类的前缀都是以YK开头，如图所示：

参考资料

Table of Contents