[swift-evolution] Rewrite imported C function signatures

[Douglas Gregor]

> On Apr 24, 2016, at 3:45 PM, Carlos Rodríguez Domínguez <carlos at everywaretech.es> wrote:
> 
> Thanks for the explanation, which makes me think that it should be suitable, as you comment, to promote API notes to a “first class” transition technology.
> 
> As a first approach towards that goal, would it be ok to expand the notion of “bridging headers” to also include API notes? In that case, it could be appropriate to develop a new C syntax to refer to YAML API notes inside bridging headers. For instance, something like this could be nice:
> 
> #apinotes “notes.yaml”

I think of API notes like module maps: it’s an external format that lays additional semantic information on top of existing headers without requiring you to modify those headers (because you often don’t control them).

	- Doug

> 
> 
>> El 29 mar 2016, a las 18:45, Douglas Gregor <dgregor at apple.com> escribió:
>> 
>> 
>>> On Mar 29, 2016, at 3:02 AM, Carlos Rodríguez Domínguez <carlos at everywaretech.es> wrote:
>>> 
>>> Well, those proposal are more oriented towards annotating on C/Objective-C files to allow a more sophisticate import into swift.
>> 
>> Yes, that is true. The philosophy behind these is that it’s better to automatically transform (via annotation) than manually wrap. Naturally, such transformations cannot handle everything.
>> 
>>> However, my proposal is to be able to directly annotate in swift, in order to fix “old-style” imports, autogenerated code, etc. Please, allow me to repeat myself, but consider the example of Core Data, in which model classes are autogenerated from a graphical model that, for instance, lacks from enums’ support. Therefore, if we use Core Data, then we can not use enums (Please, take a look at the proposal named "[swift-evolution] Promote "primitive" types to enums in extensions” in order to understand the intention of my proposal as a whole).
>> 
>> There is a Clang attribute “swift_private” that prefixes the name of the declaration with “__” when it is imported into Swift. That way, you can wrap it with a different, more Swift-friendly, API that calls the “__” version.
>> 
>> Note that we do have a mechanism for annotating C/Objective-C APIs without modifying the headers, called “API notes”. It’s a simple YAML format that lets us describe various Clang attributes for entities, e.g., provide the Swift name for a given C function, mark a type as unavailable in Swift, and so on. It’s semi-documented in the swift-clang sources:
>> 
>> 	https://github.com/apple/swift-clang/blob/upstream-with-swift/lib/APINotes/APINotesYAMLCompiler.cpp
>> 
>> Essentially, one writes a YAML file for each module that needs annotation. API notes was designed as a transitional technology, so it’s a bit under-designed for a general-purpose tool. However, as we add more Clang-side annotations to improve the mapping of C/Objective-C APIs into Swift, it’s becoming more likely that API notes could/should grow into a more general mechanism for adapting existing C/Objective-C APIs to Swift without manually wrapping everything.
>> 
>> 	- Doug
>> 
>>>> El 28 mar 2016, a las 7:29, Douglas Gregor <dgregor at apple.com> escribió:
>>>> 
>>>> 
>>>>> On Mar 25, 2016, at 3:25 AM, Carlos Rodríguez Domínguez via swift-evolution <swift-evolution at swift.org> wrote:
>>>>> 
>>>>> (Please, take a look at the proposal named "[swift-evolution] Promote "primitive" types to enums in extensions” in order to understand the intention of my proposal as a whole)
>>>>> 
>>>>> This proposal intends to allow developers to rewrite func signatures to better adapt certain imported C functions to swift. For instance, the function to create a POSIX socket has a C signature like this:
>>>>> 
>>>>> int socket(int domain, int type, int protocol);
>>>>> 
>>>>> In swift, it is currently imported like this:
>>>>> 
>>>>> func socket(_: Int32, _: Int32, _: Int32) -> Int32
>>>>> 
>>>>> However, by documentation, the first parameter should be one of a set of constants beginning with PF_. The second one should be either SOCK_STREAM, SOCK_DGRAM or SOCK_RAW. The third one should be a constant specifying the protocol to use. Finally, the result could be either -1 (to indicate an error) or another integer to indicate that a socket descriptor has been returned.
>>>>> 
>>>>> As you can observe, that old-style signature is highly error prone, does not comply with swift guidelines, it is difficult to understand, etc. My opinion is that there should be some syntax to rewrite the signature to avoid those issues. For instance, a possible syntax could be:
>>>>> 
>>>>> #mapsignature(socket(_:,_:,_:)->Int32)
>>>>> func socket(domain:SocketDomain, type:SocketType, protocol:SocketProtocol) -> socket_t? {
>>>>> 	let result = socket(domain.rawValue, type.rawValue, protocol.rawValue)
>>>>> 	if result == -1 {
>>>>> 		return nil
>>>>> 	}
>>>>> 	else{
>>>>> 		return result
>>>>> 	}
>>>>> }
>>>>> 
>>>>> Note that the compiler should enforce a function call to the original function that we are rewriting.
>>>>> 
>>>>> After a rewriting has happened, three options may be considered: either to allow the original function to be called, to avoid the original function to be called (through a compiler error with a fix-it) or to emit a warning, advising the developer to adopt the rewritten signature.
>>>>> 
>>>>> Anyhow, this proposal should allow a greatly increased interoperability between old style code and swift, which, in my opinion, is quite “forced” right now.
>>>> 
>>>> FWIW, there have been a number of proposals in roughly this space, using annotations in the C headers to improve the mapping into Swift, including
>>>> 
>>>> 	Import as member: https://github.com/apple/swift-evolution/blob/master/proposals/0044-import-as-member.md
>>>> 	Import Objective-C constants as Swift types: https://github.com/apple/swift-evolution/blob/master/proposals/0033-import-objc-constants.md
>>>> 	Better translation of Objective-C APIs into Swift (the swift_name attribute part, at least): https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md
>>>> 
>>>> 	- Doug
>>>> 
>>>> 
>>> 
>> 
>