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

Thu May 26 20:09:51 CDT 2016

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
>
>
> <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 <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/20160526/a863db1d/attachment.html>