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

[Stuart Breckenridge]

I thought about including @deprecated as an alternative, but it needs some addition tweaking outside of @unavailable and @restricted.

For example, would arguments like introduced and obsoleted still be available for use, or would they need to be separated out? 

@introduced(iOS 9.0)
@deprecated(iOS 9.1, message="Use a.n.other protocol")
@obsoleted(iOS 9.2, message="Use a.n.other protocol")
protocol MyProtocol { }

I think @unavailable and @restricted lend themselves to the existing syntax.

Stuart 

> On 26 May 2016, at 21:48, Charlie Monroe <charlie at charliemonroe.net> wrote:
> 
> With the alternatives, I'd mention @deprecated as well.
> 
> Charlie
> 
>> On May 26, 2016, at 3:25 PM, Stuart Breckenridge via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>> 
>> ADD AN @RESTRICTED DECLARATION ATTRIBUTE
>> 
>> Proposal: SE-NNNN
>> Author: Stuart Breckenridge
>> Status: DRAFT
>> Review Manager: TBD
>> 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 approach.
>> 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 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.
>> Proposal
>> 
>> Implement an @restricted attribute which is the inverse of @available. The effect would be that the compiler would use @restricted to limit the declaration to be available on the platform(s) specified in the attribute. Similar to @available, multiple @restricted attributes can be added to a declaration. 
>> Therefore, where @restricted attribute(s) are present and target platform is not specified, the declaration is not available on the unspecified target platform. In addition, where a @restricted attribute has been applied to a declaration, it should not be commingled with @available on the same declaration (it would lead to intense confusion).
>> Design
>> 
>> From a syntax perspective, it would follow @available:
>> @restricted(platform name version number, *)
>> or
>> @restricted(platform name, introduced=version number)
>> Similarly, all @available arguments would be available to @restricted. 
>> Examples
>> 
>> Using the previous example, instead of using @available to specify unavailability, we use @restricted to scope the declarations availability:
>> Single Platform Restriction
>> @restricted(OSX 10.8, *)
>> case LinkedIn = "com.apple.social.linkedin"
>> Effect: only available on OS X 10.8 or newer.
>> Multiple Platform Restriction
>> @restricted(OSX 10.8, iOS 9.4, *)
>> case LinkedIn = "com.apple.social.linkedin"
>> Effect: Available on OSX 10.8 or newer, and iOS 9.4 or newer.
>> Restricted within Version Bounds
>> @restricted(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
>> @restricted(OSX 10.10, *)
>> case TencentWeibo = "com.apple.social.tencentweibo"
>> 
>> // Second Release
>> @restricted(OSX, introduced=10.10, deprecated=10.11, renamed="Weibo")
>> case TencentWeibo = "com.apple.social.tencentweibo"
>> 
>> @restricted(OSX 10.11) 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. 
>> Benefits & Impact on existing code
>> 
>> @restricted has the benefit of reducing the amount code while maintaining clarity of purpose: it is obvious based on the attribute name what the intent is. 
>> @restricted is purely additive, and therefore has no impact on existing code that makes use of @available. 
>> Alternatives
>> 
>> An alternative, though not a strict replacement of @restricted, could be to extract the unavailableargument and use it as an attribute (@unavailable). In use:
>> @available(OSX 10.8, *)
>> @unavailable(iOS, *)
>> case LinkedIn = "com.apple.social.linkedin"
>> Effect: Available on OS X but not iOS.
>> @unavailable is worthy of further discussion as using an unavailable argument inside an @availableattribute seems counterintuitive. 
>> However, this proposal is limited to the consideration of @restricted.
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160526/52cb5baa/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/20160526/52cb5baa/attachment.p7s>