| :orphan: |
| |
| Unified Function Syntax via Selector Splitting |
| ============================================== |
| |
| .. warning:: This document was used in planning Swift 1.0; it has not been kept |
| up to date and does not describe the current or planned behavior of Swift. In |
| particular, we experimented with preposition-based splitting and decided |
| against it. |
| |
| .. contents:: |
| |
| Cocoa Selectors |
| --------------- |
| A Cocoa selector is intended to convey what a method does or produces |
| as well as what its various arguments are. For example, |
| ``NSTableView`` has the following method:: |
| |
| - (void)moveRowAtIndex:(NSInteger)oldIndex toIndex:(NSInteger)newIndex; |
| |
| Note that there are three pieces of information in the selector |
| ``moveRowAtIndex:toIndex:``: |
| |
| 1. What the method is doing ("moving a row"). |
| 2. What the first argument is ("the index of the row we're moving"). |
| 3. What the second argument is ("the index we're moving to"). |
| |
| However, there are only two selector pieces: "moveRowAtIndex" and |
| "toIndex". The first selector piece is conveying both #1 and #2, and |
| it reads well in English because the preposition "at" separates the |
| action (``moveRow``) from the first argument (``AtIndex``), while the |
| second selector piece conveys #3. Cocoa conventions in this area are |
| fairly strong, where the first selector piece describes what the |
| operation is doing or produces, and well as what the first argument |
| is, and subsequent selector pieces describe the remaining arguments. |
| |
| Splitting Selectors at Prepositions |
| ----------------------------------- |
| When importing an Objective-C selector, split the first selector piece |
| into a base method name and a first argument name. The actual split |
| will occur just before the last preposition in the selector piece, |
| using camelCase word boundaries to identify words. The resulting |
| method name is:: |
| |
| moveRow(atIndex:toIndex:) |
| |
| where ``moveRow`` is the base name, ``atIndex`` is the name of the |
| first argument (note that the 'a' has been automatically lowercased), |
| and ``toIndex`` is the name of the second argument. |
| |
| In the (fairly rare) case where there are two prepositions in the |
| initial selector, splitting at the last preposition improves the |
| likelihood of a better split, because the last prepositional phrase is |
| more likely to pertain to the first argument. For example, |
| ``appendBezierPathWithArcFromPoint:toPoint:radius:`` becomes:: |
| |
| appendBezierPathWithArc(fromPoint:toPoint:radius:) |
| |
| If there are no prepositions within the first selector piece, the |
| entire first selector piece becomes the base name, and the first |
| argument is unnamed. For example ``UIView``'s |
| ``insertSubview:atIndex:`` becomes:: |
| |
| insertSubview(_:atIndex:) |
| |
| where '_' is a placeholder for an argument with no name. |
| |
| Calling Syntax |
| -------------- |
| By splitting selectors into a base name and argument names, Swift's |
| keyword-argument calling syntax works naturally:: |
| |
| tableView.moveRow(atIndex: i, toIndex: j) |
| view.insertSubview(someView, atIndex: i) |
| |
| The syntax generalizes naturally to global and local functions that |
| have no object argument, i.e.,:: |
| |
| NSMakeRange(location: loc, length: len) |
| |
| assuming that we had argument names for C functions or a Swift overlay |
| that provided them. It also nicely handles cases where argument names |
| aren't available, e.g.,:: |
| |
| NSMakeRange(loc, len) |
| |
| as well as variadic methods:: |
| |
| NSString(stringwithFormat: "%@ : %@", key, value) |
| |
| Declaration Syntax |
| ------------------ |
| The existing "selector-style" declaration syntax can be extended to |
| better support declaring functions with separate base names and first |
| argument names, i.e.:: |
| |
| func moveRow atIndex(Int) toIndex(Int) |
| |
| However, this declaration looks very little like the call site, which |
| uses a parenthesized argument list, commas, and colons. Let's |
| eliminate the "selector-style" declaration syntax entirely. We can use |
| the existing ("tuple-style") declaration syntax to mirror the call |
| syntax directly:: |
| |
| func moveRow(_ atIndex: Int, toIndex: Int) |
| |
| Now, sometimes the argument name that works well at the call site |
| doesn't work well for the body of the function. For example, splitting |
| the selector for ``UIView``'s ``contentHuggingPriorityForAxis:`` |
| results in:: |
| |
| func contentHuggingPriority(_ forAxis: UILayoutConstraintAxis) -> UILayoutPriority |
| |
| The name ``forAxis`` works well at the call site, but not within the |
| function body. So, we allow one to specify the name of the parameter |
| for the body of the function:: |
| |
| func contentHuggingPriority(forAxis axis: UILayoutConstraintAxis) -> UILayoutPriority { |
| // use 'axis' in the body |
| } |
| |
| One can use '_' in either the argument or parameter name position to |
| specify that there is no name. For example:: |
| |
| func f(_ a: Int) // no argument name; parameter name is 'a' |
| func g(b _: Int) // argument name is 'b'; no parameter name |
| |
| The first function doesn't support keyword arguments; it is what an |
| imported C or C++ function would use. The second function supports a |
| keyword argument (``b``), but the parameter is not named (and |
| therefore cannot be used) within the body. The second form is fairly |
| uncommon, and will presumably only to be used for backward |
| compatibility. |
| |
| Method Names |
| ------------ |
| The name of a method in this scheme is determined by the base name and |
| the names of each of the arguments, and is written as:: |
| |
| basename(param1:param2:param3:) |
| |
| to mirror the form of declarations and calls, with types, arguments, |
| and commas omitted. In code, one can refer to the name of a function |
| just by its basename, if the context provides enough information to |
| uniquely determine the method. For example, when uncurrying a method |
| reference to a variable of specified type:: |
| |
| let f: (UILayoutConstraintAxis) -> UILayoutPriority = view.contentHuggingPriority |
| |
| To refer to the complete method name, place the method name in |
| backticks, as in this reference to an optional method in a delegate:: |
| |
| if let method = delegate.`tableView(_:viewForTableColumn:row:)` { |
| // ... |
| } |
| |
| Initializers |
| ------------ |
| Objective-C ``init`` methods correspond to initializers in |
| Swift. Swift splits the selector name after the ``init``. For example, |
| ``NSView``'s ``initWithFrame:`` method becomes the initializer:: |
| |
| init(withFrame: NSRect) |
| |
| There is a degenerate case here where the ``init`` method has |
| additional words following ``init``, but there is no argument with |
| which to associate the information, such as with |
| ``initForIncrementalLoad``. This is currently handled by adding an |
| empty tuple parameter to store the name, i.e.:: |
| |
| init(forIncrementalLoad:()) |
| |
| which requires the somewhat unfortunate initialization syntax:: |
| |
| NSBitmapImageRep(forIncrementalLoad:()) |
| |
| Fortunately, this is a relatively isolated problem: Cocoa and Cocoa |
| Touch contain only four selectors of this form:: |
| |
| initForIncrementalLoad |
| initListDescriptor |
| initRecordDescriptor |
| initToMemory |
| |
| With a number that small, it's easy enough to provide overlays. |
| |
| Handling Poor Mappings |
| ---------------------- |
| The split-at-last-preposition heuristic works well for a significant |
| number of selectors, but it is not perfect. Therefore, we will |
| introduce an attribute into Objective-C that allows one to specify the |
| Swift method name for that Objective-C API. For example, by default, |
| the ``NSURL`` method ``+bookmarkDataWithContentsOfURL:error:`` will |
| come into Swift as:: |
| |
| class func bookmarkDataWithContents(ofURL bookmarkFileURL: NSURL, error: inout NSError) -> NSData |
| |
| However, one can provide a different mapping with the ``method_name`` |
| attribute:: |
| |
| + (NSData *)bookmarkDataWithContentsOfURL:(NSURL *)bookmarkFileURL error:(NSError **)error __attribute__((method_name(bookmarkData(withContentsOfURL:error:)))) |
| |
| This attribute specifies the Swift method name corresponding to that |
| selector. Presumably, the ``method_name`` attribute will be wrapped in |
| a macro supplied by Foundation, i.e.,:: |
| |
| #define NS_METHOD_NAME(Name) __attribute__((method_name(Name))) |
| |
| For 1.0, it is not feasible to mark up the Objective-C headers in the |
| various SDKs. Therefore, the compiler will contain a list of mapping |
| from Objective-C selectors to Swift method names. Post-1.0, we can |
| migrate these mappings to the headers. |
| |
| A mapping in the other direction is also important, allowing one to |
| associate a specific Objective-C selector with a method. For example, |
| a Boolean property:: |
| |
| var enabled: Bool { |
| @objc(isEnabled) get { |
| // ... |
| } |
| |
| set { |
| // ... |
| } |
| } |
| |
| Optionality and Ordering of Keyword Arguments |
| --------------------------------------------- |
| A number of programming languages have keyword arguments in one form |
| or another, including Ada, C#, Fortran 95, Lua, OCaml, |
| Perl 6, Python, and Ruby. Objective-C and Smalltalk's use of selectors |
| is roughly equivalent, in the sense that the arguments get names. |
| The languages with keyword arguments (but not Objective-C and |
| Smalltalk) all allow re-ordering of |
| arguments at the call site, and many allow one to |
| provide arguments positionally without their associated name at the |
| call site. However, Cocoa APIs were designed based on the |
| understanding that they would not be re-ordered, and the sentence |
| structure of some selectors depends on that. To that end, a new |
| attribute ``call_arguments(strict)`` can be placed on any function and |
| indicates that keyword arguments are required and cannot be reordered |
| in calls to that function, i.e.:: |
| |
| @call_arguments(strict) |
| func moveRow(_ atIndex:Int, toIndex:Int) |
| |
| Swift's Objective-C importer will automatically add this to all |
| imported Objective-C methods, so that Cocoa APIs will retain their |
| sentence structure. |
| |
| Removing ``with`` and ``for`` from Argument Names |
| ------------------------------------------------- |
| The prepositions ``with`` and ``for`` are commonly used in the first |
| selector piece to separate the action or result of a method from the |
| first argument, but don't themselves convey much information at either |
| the call or declaration site. For example, ``NSColor``'s |
| ``colorWithRed:green:blue:alpha:`` is called as:: |
| |
| NSColor.color(withRed: 0.5, green: 0.5, blue: 0.5, alpha: 1.0) |
| |
| The ``with`` in this case feels spurious and makes ``withRed`` feel |
| out of sync with ``green``, ``blue``, and ``alpha``. Therefore, we |
| will remove the ``with`` (or ``for``) from any argument name, so that |
| this call becomes:: |
| |
| NSColor.color(red: 0.5, green: 0.5, blue: 0.5, alpha: 1.0) |
| |
| In addition to improving the call site, this eliminates the need to |
| rename parameters as often at the declaration site, i.e., this:: |
| |
| class func color(withRed red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat) -> NSColor |
| |
| becomes:: |
| |
| class func color(_ red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat) -> NSColor |
| |
| Note that we only perform this removal for ``with`` and ``for``; other |
| prepositions tend to have important meaning associated with them, and |
| are therefore not removed. For example, consider calls to the |
| ``NSImage`` method ``-drawInRect:fromRect:operation:fraction:`` with |
| the leading prepositions retained and removed, respectively:: |
| |
| image.draw(inRect: x, fromRect: x, operation: op, fraction: 0.5) |
| image.draw(rect: x, rect: y, operation: op, fraction: 0.5) |
| |
| Here, dropping the leading prepositions is actively harmful, because |
| we've lost the directionality provided by ``in`` and ``from`` in the |
| first two arguments. ``with`` and ``for`` do not have this problem. |
| |
| The second concern with dropping ``with`` and ``for`` is that we need |
| to either specify or infer the prepositions when declaring a |
| method. For example, consider the following initializer:: |
| |
| init(frame: CGRect) |
| |
| How would the compiler know to insert the preposition "with" into the |
| name when computing the selector, so that this maps to |
| ``initWithFrame:``? In many cases, where we're overriding a method or |
| initializer from a superclass or we are implementing a method to conform |
| to a protocol, the selector can be deduced from method/initializer in |
| the superclass or protocol. In those cases where new API is being |
| defined in Swift where the selector requires a preposition, one would |
| use the ``objc`` attribute with a selector:: |
| |
| @objc(initWithFrame:) |
| init(frame: CGRect) |
| |
| Imported Objective-C methods would have the appropriate ``objc`` |
| attribute attached to them automatically. |
| |
| Which Prepositions? |
| ------------------- |
| |
| English has a large number of prepositions, and many of those words |
| also have other rules as adjectives, adverbs, and so on. The following |
| list, taken from `The English Club`_, with poetic, archaic, and non-US |
| forms removed, provided the starting point for the list of |
| prepositions used in splitting. The **bolded** prepositions are used |
| to split; notes indicate whether Cocoa uses this preposition as a |
| preposition in any of its selectors, as well as any special |
| circumstances that affect inclusion or exclusion from the list. |
| |
| +----------------+---------+---------+----------------------------+ |
| |Preposition |In Cocoa?|Dropped? | Notes | |
| +----------------+---------+---------+----------------------------+ |
| | Aboard | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | About | No* | | Used as an adjective | |
| +----------------+---------+---------+----------------------------+ |
| | **Above** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Across | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **After** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Against | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | **Along** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **Alongside** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Amid | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Among | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Anti | No* | | Used as an adjective | |
| +----------------+---------+---------+----------------------------+ |
| | Around | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **As** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Astride | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **At** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Bar | No* | | Used as a noun | |
| +----------------+---------+---------+----------------------------+ |
| | Barring | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Before** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Behind | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Below** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Beneath | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Beside | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Besides | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Between | Yes | | Not amenable to parameters | |
| +----------------+---------+---------+----------------------------+ |
| | Beyond | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | But | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **By** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Circa | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Concerning | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Considering | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Counting | No* | | Used as an adjective | |
| +----------------+---------+---------+----------------------------+ |
| | Cum | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Despite | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Down | No* | | Used as a noun | |
| +----------------+---------+---------+----------------------------+ |
| | During | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Except | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Excepting | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Excluding | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Following** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **For** | Yes | **Yes** | | |
| +----------------+---------+---------+----------------------------+ |
| | **From** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **Given** | Yes* | No | Never splits a selector | |
| +----------------+---------+---------+----------------------------+ |
| | **In** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **Including** | Yes* | No | Never splits a selector | |
| +----------------+---------+---------+----------------------------+ |
| | **Inside** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **Into** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Less | No* | | Always "less than" | |
| +----------------+---------+---------+----------------------------+ |
| | Like | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Minus | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Near | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Notwithstanding| No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Of** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Off | No* | | Used as a noun | |
| +----------------+---------+---------+----------------------------+ |
| | **On** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Onto | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Opposite | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Out | No* | | Used as an adverb | |
| +----------------+---------+---------+----------------------------+ |
| | Outside | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Over | No* | | Used as an adverb | |
| +----------------+---------+---------+----------------------------+ |
| | Past | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Pending | No* | | Used as an adjective | |
| +----------------+---------+---------+----------------------------+ |
| | Per | Yes* | | Misleading to split | |
| +----------------+---------+---------+----------------------------+ |
| | Plus | No | | Used as an adjective | |
| +----------------+---------+---------+----------------------------+ |
| | Pro | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Regarding | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Respecting | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Round | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Save | No* | | Used as adjective, verb | |
| +----------------+---------+---------+----------------------------+ |
| | Saving | No* | | Used as adjective | |
| +----------------+---------+---------+----------------------------+ |
| | **Since** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Than | No* | | Always "greater than" | |
| +----------------+---------+---------+----------------------------+ |
| | Through | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Throughout | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **To** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Toward | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Towards | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Under | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Underneath | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Unlike | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Until** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Unto | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | Up | No* | | Used as adjective | |
| +----------------+---------+---------+----------------------------+ |
| | Upon | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Versus | No | | | |
| +----------------+---------+---------+----------------------------+ |
| | **Via** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | **With** | Yes | **Yes** | | |
| +----------------+---------+---------+----------------------------+ |
| | **Within** | Yes | No | | |
| +----------------+---------+---------+----------------------------+ |
| | Without | Yes* | | Misleading when split | |
| +----------------+---------+---------+----------------------------+ |
| | Worth | No | | | |
| +----------------+---------+---------+----------------------------+ |
| |
| .. _the english club: https://www.englishclub.com/grammar/prepositions-list.htm |
