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

Thu May 26 21:01:23 CDT 2016

On Thu, May 26, 2016 at 8:37 PM, Stuart Breckenridge <
stuart.breckenridge at icloud.com> wrote:

> 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."
>

We'll leave aside that the asterisk isn't exactly intuitive in the first
place.

What I'm saying here is that even if you accept that the asterisk means all
platforms, it does not follow that another argument in the same place
should refer to the platform names *listed in the attribute*. That's not at
all precedented in the meaning of the asterisk.

Furthermore, the asterisk is put after a list of things *only in the
shorthand syntax*, whereas you are proposing that "only" should be usable
in the full syntax as well, in a position where the asterisk is not
allowed. It is something else entirely to say that a feature is available
in OSX version so-and-so only and then to say it's available in iOS version
so-and-so only, when in fact you mean that it's not available *on other
platforms*.

What makes more sense to me would be allowing (if it isn't already allowed)
`@available(*, unavailable)` to follow a previous @available declaration in
order to mean that the feature is unavailable on all platforms not
otherwise specified.

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