[swift-evolution] [PITCH] ADD AN @RESTRICTED DECLARATION ATTRIBUTE

[Stuart Breckenridge]

On reflection, I think the introduction of a new argument to limit platform scope is superior — one less attribute to know about.

I've revised the proposal draft: https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md> and would welcome further comments.

Add An only Declaration Argument

Proposal: SE-NNNN
Author: Stuart Breckenridge
Status: DRAFT
Review Manager: TBD
 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#introduction>Introduction

Adapted from the Swift 2.2 Programming Guide:

The @available attribute indicates a declaration's life cycle relative to certain platforms and operating systems. Today's functionality allows you to add multiple @available attributes on a declaration to specify its availability on different platforms.
In a related Swift Evolution discussion examining the @available attribute, it was confirmed that there is currently no way to limit availability to specific platform without using the long form @available approach. 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#motivation>Motivation

When a declaration is only available on a certain platform, it requires multiple @available attributes to restrict its availability to that platform. Consider the following example using SLServiceType like constants:

@available(iOS, unavailable)
@available(tvOS, unavailable)
@available(watchOS, unavailable)
@available(OSX, introduced=10.8)
case LinkedIn = "com.apple.social.linkedin"
The compiler will only use an @available attribute when the attribute specifies a platform that matches the current target platform. The implication being that if the target platform isn't specified, then the attribute defaults to available.

Thus, while it is clear that the above is restricting availability to OS X 10.8 and later, it is verbose and can be simplified.

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#proposal>Proposal

Implement an only attribute argument. The effect would be that the compiler would use only to limit the declaration to be available on the target platform(s) specified in the attribute. Similar to existing @available attributes, multiple platforms can be specified in an single declaration and multiple @available attributes can applied to a single declaration. 

Therefore, where only arguments(s) are present and the target platform is not specified, the declaration is not available on the unspecified target platform(s). 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#design>Design

From a design perspective, only would be a new argument for use with @available. It would replace the trailing * that denotes all other platforms: only and * cannot be used on the same declaration. 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#syntnax>Syntnax

@available(platform name version number, only) or @available(platform name, introduced=version number, only)

No changes would be required to other @available arguments. 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#examples>Examples

Using the previous example, we use only to scope the declarations availability:

Single Platform Restriction

@available(OSX 10.8, only)
case LinkedIn = "com.apple.social.linkedin"
Effect: only available on OS X 10.8 or newer.

Multiple Platform Restriction

@available(OSX 10.8, only)
@available(iOS 9.3, only)
case LinkedIn = "com.apple.social.linkedin"
Effect: Available on OSX 10.8 or newer, and iOS 9.3 or newer.

Restricted within Version Bounds

@available(OSX, introduced=10.8, deprecated=10.10, obsoleted=10.11, message="No longer available.")
case LinkedIn = "com.apple.social.linkedin"
Effect: Available on OS X from 10.8 through 10.11 only.

Restricted with Renamed Case

// Initial Release
@available(OSX 10.10, only)
case TencentWeibo = "com.apple.social.tencentweibo"

// Second Release
@available(OSX, introduced=10.10, deprecated=10.11, renamed="Weibo", only)
case TencentWeibo = "com.apple.social.tencentweibo"

@available(OSX 10.11, only) case Weibo = "com.apple.social.weibo"
Effect: Initial release case is restricted to 10.10 and newer; second release has the original case deprecated from 10.11, with a new case introduced which is available on OS X 10.11 and newer only. 

Illegal Usage

@available(OSX 10.8, only)
@available(iOS 9.3, *)
case LinkedIn = "com.apple.social.linkedin"
Reason: * and only are mutually exclusive. 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#benefits--impact-on-existing-code>Benefits & Impact on existing code

only has the benefit of reducing the amount of attribute code, while maintaining clarity of purpose: it is obvious based on the argument name what the intent is. 

only is purely additive, and therefore has no impact on existing declarations that make use of @available. 

 <https://github.com/stuartbreckenridge/swift-evolution/blob/master/proposals/NNNN-add-only-declaration-argument.md#alternatives>Alternatives

An alternative considered was the introduction of an @restricted attribute that would be used in place of @available. In use:

@restricted(OSX 10.8, *)
case LinkedIn = "com.apple.social.linkedin"
Effect: Available on OS X 10.8 and newer.

@restricted and only achieve the same goal of providing a simple way of scoping a declaration's availability to specific platform(s) while reducing the amount of code required to do so. The general feedback from the initial proprosal was that an introduction of a new argument (only) was preferred over the introduction of a new attribute @restricted.






> On 27 May 2016, at 05:14, Brent Royal-Gordon <brent at architechies.com> wrote:
> 
>> @available(OS X 10.9, restricted)
> 
> Personally, I would prefer something like this, perhaps spelled:
> 
> 	@available(OS X 10.9, only)
> 
> When using shorthand form, you would have to write either `*` or `only` as the last element. `*` means "and any other platforms", while `only` means "only the listed platforms".
> 
> -- 
> Brent Royal-Gordon
> Architechies
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160527/b5e59615/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3138 bytes
Desc: not available
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160527/b5e59615/attachment.p7s>