Compiler Diagnostic Directives using a hashtag in Swift

Published in

Swift Programming

2 min readAug 14, 2018

The Swift standard library brings quite some compiler diagnostic directives by default. Although this might not ring a bell at all, a lot of them are quite known and listed here in the Swift repository.

Warning

Warning can be used to manually trigger a warning on the given line. This can be useful during development to give feedback about the current state of your code.

#warning("fill in your API key below")

Error

Although you would probably use an assertion type you can also use the error keyword. This will trigger an error earlier during compilation instead of during runtime.

#if !canImport(UIKit)
  #error("This framework requires UIKit!")
#endif

TODO

When Swift was introduced, the #warning and #error keywords were no longer available while they were in Objective-C. A lot of users used a run-script to show a warning for TODO: lines. These can now be replaced with the #warning keyword.

#warning("TODO: Update this code for the new iOS 12 APIs")

Debugging identifiers

Modernized in SE-0028 are the debugging identifiers. These keywords provide high utility for logging, both tracing execution and enabling developers to capture error context using logs or compiler warnings and errors.

File and line

From all these keywords, the line and file keywords are probably the most unknown. Funny enough, they’re probably used by you quite a lot. Methods like XCTAssert, XCTAssertNotNil and XCTFail use these keywords as default parameters to trigger an assertion on the line where it has been implemented.

public func XCTAssert(_ expression: @autoclosure () throws -> Bool, _ message: @autoclosure () -> String = default, file: StaticString = #file, line: UInt = #line)

If you’re using custom test methods, you might want to look into the XCTest header file for inspiration. A great blog post on this topic is written by Thomas Visser: Customizing the source location of failures reported by XCTest.

Function

Logs are used quite a lot but they’re sometimes hard to follow. Including the #function keyword can help you point to the right direction for debugging purposes.

/// Tracker.swift:L11: Configuration failed inside setup()
print("\(#file):L\(#line): Configuration failed inside \(#function)")

Other compiler diagnostic keywords

A lot of more compiler diagnostic keywords exist for which most of them are not that useful in most cases. The current list of available keywords can be found here and includes the following list.

Do you know them all?

// Keywords prefixed with a '#'.  "if" becomes "tok::pound_if".
POUND_KEYWORD(if)
POUND_KEYWORD(else)
POUND_KEYWORD(elseif)
POUND_KEYWORD(endif)
POUND_KEYWORD(keyPath)
POUND_KEYWORD(line)
POUND_KEYWORD(sourceLocation)
POUND_KEYWORD(selector)
POUND_KEYWORD(warning)
POUND_KEYWORD(error)// Keywords prefixed with a '#' that are build configurations.
POUND_CONFIG(available)
// Object literals and their corresponding protocols.
POUND_OBJECT_LITERAL(fileLiteral, "file reference", ExpressibleByFileReferenceLiteral)
POUND_OBJECT_LITERAL(imageLiteral, "image", ExpressibleByImageLiteral)
POUND_OBJECT_LITERAL(colorLiteral, "color", ExpressibleByColorLiteral)POUND_OLD_OBJECT_LITERAL(FileReference, fileLiteral, fileReferenceLiteral, resourceName)
POUND_OLD_OBJECT_LITERAL(Image, imageLiteral, imageLiteral, resourceName)
POUND_OLD_OBJECT_LITERAL(Color, colorLiteral, colorLiteralRed, red)POUND_KEYWORD(file)
POUND_KEYWORD(column)
POUND_KEYWORD(function)
POUND_KEYWORD(dsohandle)

This story is originally posted at:
https://www.avanderlee.com/swift/compiler-diagnostic-directives/