On Thu, May 26, 2016 at 7:37 PM, Stuart Breckenridge via swift-evolution < [email protected]> 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 > > > <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. > 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. > > <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 <[email protected]> > 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 > [email protected] > https://lists.swift.org/mailman/listinfo/swift-evolution > >
_______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
