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

Thu May 26 20:37:40 CDT 2016

I disagree. If you look the S
wift 2.2 guide:

"You can also use an asterisk (*) to indicate availability of the declaration on all of the platform names listed above."

What this proposal would add is:

"Alternatively, you can use the word 'only' to indicate that the declaration is only available on the platform name(s) listed in the attribute."

Sent from my iPhone

> On 27 May 2016, at 09:09, Xiaodi Wu <xiaodi.wu at gmail.com> wrote:
> 
>> On Thu, May 26, 2016 at 7:37 PM, Stuart Breckenridge via swift-evolution <swift-evolution at swift.org> wrote:
>> 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 and would welcome further comments.
>> 
>> Add An only Declaration Argument
>> 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 @available 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, 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.
>> 
>> 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). 
>> 
>> 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. 
>> 
>> Syntnax
>> 
>> @available(platform name version number, only) or @available(platform name, introduced=version number, only)
>> 
>> No changes would be required to other @available arguments. 
>> 
>> 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. 
>> 
>> 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. 
>> 
> I see what you're going for, but it is not at all obvious what the word "only" means. In fact, the intuitive interpretation of `@available(OSX 10.8, only)` is that "only" applies to the version number and not the platform--i.e. the feature is available only in OS X 10.8 and not in earlier or later versions; that interpretation is only reinforced by your proposed syntax allowing "only" to be written multiple times, once for each platform. The only intuitive interpretation of `@available(OSX 10.8, only)` followed by `@available(iOS 9.3, only)` is that the feature is available only in version 10.8 of OS X and only in version 9.3 of iOS, not that you are restricting availability on other platforms. By contrast, the current syntax is verbose but unambiguous.
>  
>> only is purely additive, and therefore has no impact on existing declarations that make use of @available. 
>> 
>> 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
>> 
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> 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/20160527/16b8129f/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4005 bytes
Desc: not available
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160527/16b8129f/attachment.p7s>