SE-NNNN-language_mode_compiler_condition.md

• Proposal: SE-NNNN
• Author: James Dempsey
• Review Manager: TBD
• Status: Awaiting implementation
• Implementation: swiftlang/swift#NNNNN
• Previous Proposal: SE-0441

Introduction

SE-0441 formalized the term "language mode" in Swift compiler options and Swift Package Manager APIs. This proposal introduces a languageMode() compilation condition, further standardizing the term. It also provides a more easily understandable way to conditionally compile based on language mode than the existing swift() compilation condition.

Motivation

With SE-0441, the Swift toolchain has formalized the term ‘language mode’. This proposal continues to standardize that term by introducing a new compilation condition that is also more clear and direct.

The existing swift() compilation condition checks specific versions of Swift but does so taking the current language mode into account.

This hybrid behavior can be difficult to explain and reason about ¹. In addition, with this compilation condition, the compiler does not provide any checking for valid language mode values.

Although it is currently possible to write conditional code predicated on language mode, doing so is error-prone and potentially confusing to use and read.

Proposed solution

The proposed solution is to add a new languageMode(…) compiler condition that validates the specified language mode.

Detailed design

The new languageMode(…) compiler condition uses the same syntax as the existing compiler(…) and swift(…) conditions, allowing for >= and <.

#if languageMode(>=6)
...
#endif

#if languageMode(<5)
...
#endif

The new compiler condition will only accept the defined set of language mode values. The compiler will generate an error if provided a value that is not a valid language mode. This mirrors the behavior of the existing compiler command-line option.

The diagnostic message will be similar to the existing command-line error message:

#if languageMode(>=5.2) // Error: Invalid value '5.2', valid arguments are '4', '4.2', '5', '6'
...
#endif

No longer supported language modes

An exception to this behavior is for language modes that were supported by previous compiler versions but are no longer supported. To maintain source compatibility, these will generate a warning, not an error. Once-supported language modes are assumed to be older than any currently supported language mode. When used with >= the code block will always compile. When used with < the code block will never compile.

#if languageMode(>=3) // Warning: Unsupported language mode '3', valid arguments are '4', '4.2', '5', '6'
... // This code will always compile
#endif

#if languageMode(<3) // Warning: Unsupported language mode '3', valid arguments are '4', '4.2', '5', '6'
... // This code will never compile
#endif

Note that this is meant only for source compatibility going forward. The initial implementation is only required to support the set of language modes supported by the compiler when this proposal is implemented. In practice, Swift 3 language mode will likely be included in order to test this functionality.

The swift() compilation condition

No changes are proposed for the existing swift() compilation condition. It will remain as-is.

Source compatibility

This proposal is additive and does not affect source compatibility.

ABI compatibility

This proposal has no effect on ABI stability.

Alternatives considered

SE-0441 contains a discussion of alternate names considered.

Footnotes

1. For example, multiple attempts to precisely and succinctly describe its exact behavior for this proposal have been in vain. ↩