Xcode 文本宏（Text Macros）的介紹和應用

前言

文本宏（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開頭，如圖所示：

參考資料

• 《Xcode Help》