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” > El 29 mar 2016, a las 18:45, Douglas Gregor <[email protected]> escribió: > > >> On Mar 29, 2016, at 3:02 AM, Carlos Rodríguez Domínguez >> <[email protected]> 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 <[email protected]> escribió: >>> >>> >>>> On Mar 25, 2016, at 3:25 AM, Carlos Rodríguez Domínguez via >>>> swift-evolution <[email protected]> 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 >>> >>> >> > _______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
