I’m looking to hire on help for my Mac app projects. You can apply now and I’ll be looking forward to pick someone in March.

The Available Topics

Ordered by importance:

1. Wiring NSTextView and friends and use the Cocoa Text System to write a better, no, the best Markdown syntax highlighter. I wrote a ton about the topic myself, and I have a couple of interesting approaches prepared, but my time is too limited to make the ideas reality as quickly as I would like, so help (aka paid labor) is appreciated! This includes variants based on C libraries, server/client like service architecture, and pure Swift. We can also talk about Open Sourcing the result if that is a thing you burn for.
2. Writing a data model and UI for better file content tracking (got the file/directory tracking part already) to integrate project progress better into the WordCounter.
3. Designing a UI to manage user-created scripts in an app and execute these manually or on a regular basis. A poor man’s cron, so to speak, but more accessible to non-programmers. Scripts will usually work with plain text content and produce more plain text stuff.
4. Writing a replacement for, or customizing the vanilla NSTableView of TableFlip to make multi-line cell contents a thing while keeping the UI responsive. A replacement component would be more greenfield-ish than improving the existing UI code, of course.
5. Actually not for Mac: Adding iCloud sync to a Core Data-backed iOS app. It’s part Objective-C, and I’m fine adding on more Objective-C.

Have another look at my apps to see what kind of stuff I work on.

The Setting

This list of stuff is mostly about self-contained modules. You can think of these to be greenfield projects, so you don’t need to deal with existing code most of the time. We will design components from UI to API together and you’ll get to be as creative as you want and the project allows.

Depending on what you eventually want to do with the rest of your life and how well we resonate with each other, consider the topics above to be entryways into a long-term cooperation.

Timing is flexible. Part-time is totally fine. For longer-term nuts to crack, it even makes sense to spread out the workload a bit, especially in the beginning. After all, you’ll need to get accustomed to everything, and I believe it’s nicer for both of us if you have more headspace. The pressure of trying to churn out 40 hours right from the get go might actually get in the way. The opposite sounds a lot more sensible, so if you only have 2 days per week to spend, no problemo.

Please note there will be no SwiftUI or Combine for the foreseeable future, but I’m game for RxSwift.

The Requirements

I’m looking for experienced developers with a knack for the problem of their choosing, because I’m happy if you’re happy at work, and we’re both more happy if you pick a topic that motivates you to excel.

If you really, absolutely want to tackle more boring and menial tasks, I can see what I can do after we finished some of the interesting stuff.

Get in touch if

• you are interested in a topic mentioned above,
• you have experience with the problem domain and macOS app development,
• you are available “soon”,
• you can work as a freelancer/contractor.

Don’t know if “experienced” applies to you? Introduce yourself and we’ll find out!

I ran into a situation with a window that is movable by its background and a text field inside it. The text field draws neither border nor background, so to the user, it looks like an input field directly on the window’s background. Much like the Spotlight search box.

Even when a window’s isMovableByWindowBackground is enabled, a NSTextField captures click and drag events, and it changes the pointer to a text insertion variant (NSCursor.iBeam). All that is weird when you don’t know there’s a text field at that point. And you cannot know how large the text field is if nothing is drawn there. When the background is gone, this feels pretty weird.

One could subclass NSTextView and change mouseDownCanMoveWindow to return true. That would let some drag operations through, but even for controls that are supposed to be clickable but not draggable, like table view lists, this produced a lot of micro movements during my tests. That’s partly because I use an external mouse: the touch bar on MacBooks usually doesn’t register move/drag commands that quickly. I discarded this cheap way out for that reason, though.

My solution was to shrink the text field to fit the content.

1. Give it a >= trailing Auto Layout constraint so it can get smaller than the window,
2. Set the window’s contentView‘s width to a constant value,
3. Update NSTextField.intrinsicContentSize while the user is typing to fit the typed text.

Spotlight, by the way, doesn’t use NSTextField.placeholderString. I think Apple conditionally show/hide a label behind the text field, with isVisible wired to !String.isEmpty. For a regular placeholder to show, the text field has to be wide enough. But when the text field is as wide as the placeholder, the I-beam cursor should show when you hover over the placeholder text. With the Spotlight search box, it doesn’t.

Here’s my code for both variants: one using a placeholder, which makes the size caching a bit more complicated, and one that ignores the placeholder completely, so you have to wire a label like Spotlight does it.

Drop-in NSTextField subclass that uses the placeholder

• It respects the placeholderString, either changed during runtime or set in Interface Builder, to affect the minimum width.
• It adapts the intrinsicContentSize to match the visible contents of the field editor (or the placeholder, if the field editor is empty).
• It reacts to programmatic changes of the stringValue property.

class AutoGrowingTextField: NSTextField {
    private var placeholderWidth: CGFloat? = 0

    /// Field editor inset; experimental value
    private let rightMargin: CGFloat = 5

    private var lastSize: NSSize?
    private var isEditing = false

    override func awakeFromNib() {
        super.awakeFromNib()

        if let placeholderString = self.placeholderString {
            self.placeholderWidth = sizeForProgrammaticText(placeholderString).width
        }
    }

    override var placeholderString: String? {
        didSet {
            guard let placeholderString = self.placeholderString else { return }
            self.placeholderWidth = sizeForProgrammaticText(placeholderString).width
        }
    }

    override var stringValue: String {
        didSet {
            guard !isEditing else { return }
            self.lastSize = sizeForProgrammaticText(stringValue)
        }
    }

    private func sizeForProgrammaticText(_ string: String) -> NSSize {
        let font = self.font ?? NSFont.systemFont(ofSize: NSFont.systemFontSize, weight: .regular)
        let stringWidth = NSAttributedString(
            string: string,
            attributes: [ .font : font ])
            .size().width

        // Don't use `self` to avoid cycles
        var size = super.intrinsicContentSize
        size.width = stringWidth
        return size
    }

    override func textDidBeginEditing(_ notification: Notification) {
        super.textDidBeginEditing(notification)
        isEditing = true
    }

    override func textDidEndEditing(_ notification: Notification) {
        super.textDidEndEditing(notification)
        isEditing = false
    }

    override func textDidChange(_ notification: Notification) {
        super.textDidChange(notification)
        self.invalidateIntrinsicContentSize()
    }

    override var intrinsicContentSize: NSSize {
        var minSize: NSSize {
            var size = super.intrinsicContentSize
            size.width = self.placeholderWidth ?? 0
            return size
        }

        // Use cached value when not editing
        guard isEditing,
            let fieldEditor = self.window?.fieldEditor(false, for: self) as? NSTextView
            else { return self.lastSize ?? minSize }

        // Make room for the placeholder when the text field is empty
        guard !fieldEditor.string.isEmpty else {
            self.lastSize = minSize
            return minSize
        }

        // Use the field editor's computed width when possible
        guard let container = fieldEditor.textContainer,
            let newWidth = container.layoutManager?.usedRect(for: container).width
            else { return self.lastSize ?? minSize }

        var newSize = super.intrinsicContentSize
        newSize.width = newWidth + rightMargin

        self.lastSize = newSize

        return newSize
    }
}

Variant that ignores the placeholder (so you have to add a label yourself)

• It adapts the intrinsicContentSize to match the visible contents of the field editor.
• It reacts to programmatic changes of the stringValue property.

You have to create a label below this text field with the placeholder value and then set up view controller wiring to conditionally hide and show the placeholder. Here’s some boilerplate to get you started, not taking into account programmatic changes to NSTextField.stringValue:

class MyViewController: NSViewController, NSTextFieldDelegate {
    @IBOutlet weak var placeholderLabel: NSTextField!
    @IBOutlet weak var textField: NSTextField!

    func controlTextDidChange(_ obj: Notification) {
        placeholderLabel.isHidden = !textField.stringValue.isEmpty
    }
}

And here’s the way simpler text field subclass:

class AutoGrowingTextField: NSTextField {
    /// Field editor inset; experimental value
    private let rightMargin: CGFloat = 5

    private var lastSize: NSSize?
    private var isEditing = false

    override var stringValue: String {
        didSet {
            guard !isEditing else { return }
            self.lastSize = sizeForProgrammaticText(stringValue)
        }
    }

    private func sizeForProgrammaticText(_ string: String) -> NSSize {
        let font = self.font ?? NSFont.systemFont(ofSize: NSFont.systemFontSize, weight: .regular)
        let stringWidth = NSAttributedString(
            string: string,
            attributes: [ .font : font ])
            .size().width

        // Don't use `self` to avoid cycles
        var size = super.intrinsicContentSize
        size.width = stringWidth
        return size
    }

    override func textDidBeginEditing(_ notification: Notification) {
        super.textDidBeginEditing(notification)
        isEditing = true
    }

    override func textDidEndEditing(_ notification: Notification) {
        super.textDidEndEditing(notification)
        isEditing = false
    }

    override func textDidChange(_ notification: Notification) {
        super.textDidChange(notification)
        self.invalidateIntrinsicContentSize()
    }

    override var intrinsicContentSize: NSSize {
        var minSize: NSSize {
            var size = super.intrinsicContentSize
            size.width = 0
            return size
        }

        guard isEditing,
            let fieldEditor = self.window?.fieldEditor(false, for: self) as? NSTextView,
            let container = fieldEditor.textContainer,
            let newWidth = container.layoutManager?.usedRect(for: container).width
            else { return self.lastSize ?? minSize }

        var newSize = super.intrinsicContentSize
        newSize.width = newWidth + rightMargin

        self.lastSize = newSize

        return newSize
    }
}

There’s not a lot to do, but the documentation is (1) old, (2) not maintained anymore, (3) very wordy. The steps involved are actually very simple. I’ll go through them and provide detail and links for further reading.

Open the Script Editor app. You’ll want to use that for test-driving your app.

Enable AppleScript in Your App

The steps from the now archived docs are:

1. You need an .sdef file with the script command definitions,
2. reference this file in your Info.plist, and
3. enable AppleScript in your Info.plist as well.

First, create a script definition file ending in .sdef. It usually has the same name as your app, but you can pick whatever you want. For TableFlip, this file would be TableFlip.sdef, for The Archive I picked TheArchive.sdef.

Xcode won’t help you with a template here, so you might as well use touch from the Terminal or your favorie text editor and drag the file into your project later.

This is the bare minimum container boilerplate:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "file://localhost/System/Library/DTDs/sdef.dtd">
<dictionary xmlns:xi="http://www.w3.org/2003/XInclude" title="YOUR APP NAME HERE Terminonoly">
</dictionary>

Replace the title with the name of your app plus the word “Terminology”. That appears to be a convention.

Add this file to your Xcode project and make sure it’s part of the app target. You may want to double-check that the target’s Build Phases > Copy Bundle Resources now contains your .sdef file.

Second, open your app target’s Info.plist in Xcode and add two new rows:

1. In the first row, enable AppleScript support. Set the key to NSAppleScriptEnabled (will become “Scriptable”) and the value to YES (it’s a boolean Xcode will recognize).
2. In the next row, define which .sdef file exposes available commands. Set the key to OSAScriptingDefinition (will become “Scripting definition file name”) and the value to the file name of your .sdef, e.g. “TableFlip.sdef”. No need to specify a path.

Now build your project in Xcode.

Reveal the build product in Finder and drag the app bundle onto the Script Editor. When you drag app bundles onto the Script Editor, it’ll show a browsable scripting definition, aka the terminology your app exposes.

Since the boilerplate is empty, this should also be empty. For now.

Add default Cocoa commands to e.g. quit your app

How do you get started with defining script commands? – Thanksfully, there’s a default set of commands that is provided as a quick start.

You can open it in Xcode straight from the Terminal:

open /System/Library/ScriptingDefinitions/CocoaStandard.sdef

It looks like this at the moment of writing on my machine:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "file://localhost/System/Library/DTDs/sdef.dtd">

<dictionary title="Standard Terminology">

    <suite name="Standard Suite" code="????" description="Common classes and commands for all applications.">

        <command name="open" code="aevtodoc" description="Open a document.">
            <direct-parameter description="The file(s) to be opened.">
                <type type="file"/>
                <type type="file" list="yes"/>
            </direct-parameter>
                <result description="The opened document(s).">
                <type type="document"/>
                <type type="document" list="yes"/>
            </result>
        </command>

    ... lines 19--263 follow ...

    </suite>

</dictionary>

That’s the same structure as the boilerplate from above. You see that inside of a terminology <dictionary> element, there is a <suite> element that contains many <command> elements.

Your .sdef can only have 1 root level <dictionary> element, only one!, but that can contain multiple suited to group different purposes.

If you want, copy the whole code from the opening <suite> until the closing </suite> into your .sdef file. Note that you will want to have a look at each command and change it so it fits your app. Not everything from the CocoaStandard.sdef makes sense.

Let’s look at an example to see how you can customize this.

Customize the standard Quit command

If you look at the definition of the “quit” command in the CocoaStandard.sdef file, you’ll see this (broken onto multiple lines to preserve space):

<command name="quit" code="aevtquit" description="Quit the application.">
    <cocoa class="NSQuitCommand"/>
    <parameter name="saving" code="savo" 
            type="save options" optional="yes" 
            description="Should changes be saved before quitting?">
        <cocoa key="SaveOptions"/>
    </parameter>
</command>

In my note-taking app The Archive, there’s no notion of manual saving. Files are saved as you type. Yet the command definition above offers an optional parameter to the “quit” command. I don’t need that, so it has to go. I delete the whole <parameter>...</parameter> node.

My .sdef looks like this afterwards:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "file://localhost/System/Library/DTDs/sdef.dtd">
<dictionary xmlns:xi="http://www.w3.org/2003/XInclude" title="YOUR APP NAME HERE Terminonoly">
    <suite name="Standard Suite" code="????" description="Common classes and commands for all applications.">
        <command name="quit" code="aevtquit" description="Quit the application.">
            <cocoa class="NSQuitCommand"/>
        </command>
    </suite>
</dictionary>

You can paste this into your .sdef, too. Save the file, build the project, then drag the app bundle onto Script Editor again. It does not auto-update just because the underlying bundle did change during compilation.

Lo and behold – your first command appears!

Test your commands

With Script Editor still open, create a new document. That’ll be the scratchpad for AppleScript interaction.

Use the power of the new “quit” command to see how things work.

tell application "THE APP NAME" to quit

You have to replace THE APP NAME with your app’s name. It appears to work well with the product name. In my case, that’ll be The Archive with a space, or TableFlip without one.

First, run the app from Xcode so it is open.

Then execute the script.

Did your app close? If so, congratulations!

If not, it could be because you typed

# Warning: will not work!
tell "THE APP NAME" to quit

That’ll send the “quit” message to the string. You want to send it to the application with that name.

Where to go from here

I think it’s a good first step to redact the CocoaStandard.sdef to fit your app.

Heads up: Removing commands like the “quit” command from your app’s .sdef will actually not disable them. The app still responds to the standard messages; apparently, these are inherited and the suite with the same name and identifier can be overridden. So the commands just don’t show up in the Script Editor terminology view.

When you have cleaned up the “Standard Suite”, you can start adding your own.

To prototype your app’s scriptability, the archived docs recommend you start with the .sdef file first and don’t actually implement any functionality. Instead, you write test scripts in Script Editor and hit the “Compile” button. That’ll verify the syntax and show errors if you mistyped the invokation in the script, or botched the definition in you .sdef file.

I really like the idea of outside-in development of the syntax to see what kind of interactions you will want, and then you figure out how to create the appropriate command implementations.

You will be putting your commands into your own <suite>…</suite> node, with a unique name and a unique 8-character identifier. Whatever that is for, and why-ever that is limited to 8 characters. Legacy, I guess. We’ll have a look at custom command creation in another post.

Please note that you need to run your app from Xcode before you execute a Script Editor script. If you don’t, macOS’s launch services may figure that the best fit for an application of that name is in you /Application folder. Run your app from Xcode to make this debug version occupy the name and receive the AppleScript events.

Further reading:

• Excellent example of a custom script command suite on StackOverflow.
• How to turn on script debugging to show command handling in the Xcode console output.
• Implementing a Scriptable Application from the archived docs.

Here’s NSProgress subclass that allows block-based callbacks for finishing the progress in a new callback called finishHandler that should work the same as the existing handlers.

By default NSProgress (or with Swift just Progress) comes with handlers for resumeing, pausing, and cancellation events, but not for finishing. I don’t know why.

This subclass uses Key–Value-Observations on the isFinished property (that’s actually "finished" by its Objective-C property name).

Note that you need to add a convenience initializer init(totalUnitCount:) yourself in both subclass variants because the Progress.init(totalUnitCount:) is not inheritable. Sad.

RxSwift Variant

This one is pretty short because you can model the KVO and its “dispatch only once please” condition very succinct:

class FinishObservableProgress: Progress {
    private var disposeBag = DisposeBag()

    var finishHandler: (() -> Void)? {
        didSet {
            disposeBag = DisposeBag()

            guard let finishHandler = finishHandler else { return }

            self.rx.observeWeakly(Bool.self, "finished", options: [.new])
                .filter { $0 == true }
                .distinctUntilChanged()
                .map { _ in () }
                .subscribe(onNext: finishHandler)
                .disposed(by: disposeBag)
        }
    }

    convenience init(totalUnitCount: Int64) {
        self.init(parent: nil, userInfo: nil)
        self.totalUnitCount = totalUnitCount
    }
}

Regular KVO Variant

If you don’t have RxSwift handy, regular KVO will do the trick just as well. I’ll introduce a private helper class to actually handle the observation so the progress doesn’t have to self-observe, which I always find a bit odd.

class FinishObservableProgress: Progress {
    private class Observer: NSObject {
        let callback: (() -> Void)

        init(callback: @escaping (() -> Void)) {
            self.callback = callback
        }

        /// Prevents multiple completions.
        private var didFinish = false

        override func observeValue(
                forKeyPath keyPath: String?,
                of object: Any?,
                change: [NSKeyValueChangeKey : Any]?,
                context: UnsafeMutableRawPointer?) {
            guard didFinish == false else { return }
            guard keyPath == "finished",
                let value = change?[.newKey] as? Bool,
                value == true
                else { return }
            didFinish = true
            callback()
        }
    }

    private var observer: Observer?

    deinit {
        if let observer = observer {
            self.removeObserver(observer, forKeyPath: "isFinished")
        }
    }

    var finishHandler: (() -> Void)? {
        get {
            return observer?.callback
        }
        set {
            self.observer = {
                guard let newValue = newValue else { return nil }

                let newObserver = Observer(callback: newValue)
                self.addObserver(newObserver,
                                 forKeyPath: "finished",
                                 options: [.new],
                                 context: nil)
                return newObserver
            }()
        }
    }

    convenience init(totalUnitCount: Int64) {
        self.init(parent: nil, userInfo: nil)
        self.totalUnitCount = totalUnitCount
    }
}

I was getting back to fix a couple of small issues in The Archive and release an update when I noticed that one new feature I added, a statistics status bar, made most sense when hidden by default to avoid UI clutter. But how do people notice the new feature, then?

Well, that’s what the “What’s New” window is for. To make it support a history of amazing changes, I adapted my very own WhatsNewKit to support this. And there you go, WhatsNewKit version 1.2.0 is out now and supports multiple update notices!

You pass it an Array<Update> with each Update.version specifying the app version a feature was introduced. By default, WhatsNewKit then determines the subset of all Updates since the last known update that was displayed. It then displays all that remain. That means you will get 1 update notice for the upcoming update of The Archive if you have last launched it yesterday. If you haven’t opened the app for more than half a year, you will get 2 update notices.

You can also forcibly show all known update notices, e.g. from The Archive‘s main menu when you pick Help > Show What’s New…

Get WhatsNewKit on GitHub

I fixed the newsletter signup form. If you found the button to previously not do anything, now it will work.

Here is a transaction type to copy & paste into projects to encapsulates thread-safe read/write access:

struct Transaction {
    let queue: DispatchQueue

    func read<T>(_ value: @autoclosure () -> T) -> T {
        return read(block: value)
    }

    func read<T>(block: () -> T) -> T {
        return queue.sync {
            block()
        }
    }

    func write(block: @escaping () -> Void) {
        queue.async(flags: .barrier) {
            block()
        }
    }
}

Just make sure to not use the main queue, because .sync call from main to main will deadlock your app!

It ensures you read values synchronously, which isn’t dangerous, and enqueue and execute write operations in order. This is useful if you need to access any resource from multiple threads and want to avoid the overhead of mutex locks.

I called it Transaction because the result is access to resources in a way similar to ACID transactions: complex operations are executed in a batch (Atomicity), write operations don’t get in each other’s way (Consistency & Isolation); the Durability part is debatable, though.

Usage example

Here’s how you’d wrap read and write operations for a totally contrived example:

class Counter {
    private static let queue = DispatchQueue(label: "counter", qos: .background)
    private var count = 0

    var tx: Transaction {
        return Transaction(queue: Counter.queue)
    }

    func increment() {
        tx.write {
            self.count += 1
        }
    }

    var currentValue: Int {
        return tx.read(count)
    }
}

Checking if this really does help

Here’s an example program to demonstrate the effects:

let counter = Counter()
for _ in (0 ..< 20) {
    DispatchQueue.global(qos: .background).async {
        // This is actually bad sample code because it's two calls where time passes in between
        counter.increment()
        print(counter.currentValue, terminator: ", ")
    }
}

It’s output:

10, 10, 10, 10, 10, 10, 10, 10, 10, 17, 10, 18, 18, 18, 19, 20, 20, 20, 20, 20

You see there are 20 print statements, but they don’t happen right after the increment. They are still in order, but apparently some “read” calls have been intercepted by other “write” operations and had to wait, e.g. the last 5.

Here’s one without the Transaction‘s queue being used, demonstating how random the values can appear if you read and write willy-nilly:

14, 14, 15, 14, 16, 15, 15, 19, 20, 20, 15, 20, 15, 20, 20, 20, 20, 20, 20, 20
            ^^      ^^  ^^              ^^      ^^

It’s even more apparent with 100+ iterations, but I won’t print these here.

Property Wrapper variant

It cannot be a struct because async mutations need to capture a mutable reference to self in the async setter.

Also keep in mind that one-line increments like += 1 actually equal one get plus one set call. That will produce results you do not anticipate. The counter example above with a naive += 1 ends at the value 5 after 100 iterations on my machine, for example, because a ton of reading happens pretty quickly and asynchronously before a write operation sets up the barrier.

Do access the backing property directly with the underscore prefix and call e.g. _counter.mutate { $0 += 1 } to do it all at once.

That is, in effect, similar to tx.write { self.count += 1 }.

@propertyWrapper
final class Transaction<Value> {
    private let queue: DispatchQueue
    private var value: Value

    init(wrappedValue: Value, queue: DispatchQueue) {
        self.queue = queue
        self.value = wrappedValue
    }

    var wrappedValue: Value {
        get { queue.sync { value } }
        set { queue.async(flags: .barrier) { self.value = newValue } }
    }

    func mutate(_ mutation: (inout Value) -> Void) {
        return queue.sync {
            mutation(&value)
        }
    }
}

And then use it like so:

class Counter {
    private static let queue = DispatchQueue(label: "counter", qos: .background)

    @TransactionWrapper(wrappedValue: 0, queue: Counter.queue)
    private(set) var count

    func increment() {
        _count.mutate { $0 += 1 }
    }
}

Conclusion and usage

I use the Transaction type for access to a cache and for object repositories. Works like a charm and the call site doesn’t get too distracting. A very useful tool.

Heads up: There’s no need to go all-in with this. The overhead of async calls with the .barrier flag is not to be underestimated. Simply setting the value is many magnitudes faste. Only protect resources that you absolutely need to, and only introduce concurrency when you cannot get by without. Network API calls should not write to resources via transaction; they should finish in the background and then produce the result to your app on the main queue.

I didn’t invent any of this. There’s plenty of discussion on the web. For some more recent iterations on the topic, see also:

• Swift Atomic Properties with Property Wrappers by Vadim Bulavin
• Concurrent vs Serial DispatchQueue: Concurrency in Swift explained by Antoine van der Lee

When you look at the docs for String.index(_:offsetBy:limitedBy:), you get this description:

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

The “unless that distance is beyond a given limiting index” part got my attention. I remembered it to be a pain to use in practice. The overall API docs page looks way too innocent for that.

So what’s the example code?

let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
    print(s[i])
}
// Prints "t"

Paste it in a Playground. You’ll see that, yes, this prints t.

But what if I change the offset to 5 to actually see how the limit at the limit works?

Here’s the changed code for you to copy and paste, with the 5 instead of 4:

//  /!\  Warning! Do not use in production!   /!\
let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 5, limitedBy: s.endIndex) {
    print(s[i])
}

What does it print?

Nothing, you hope?

Because the String is too short?

(cue sad trombone)

“Ok, Christian, the API sample was just for demoing a valid use. You inferred something wrong from what you saw”, you might say.

Did I?

The String.index(_:offsetBy:limitedBy:) docs go on like this:

The next example attempts to retrieve an index six positions from s.startIndex but fails, because that distance is beyond the index passed as limit.

let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
print(j)
// Prints "nil"

… which is true, this code returns nil and does not crash. Oh, so it’s safe to try to get to indices beyond the bounds, nice, right?

Up next is this hand-wavy explanation:

The value passed as n must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Remember: This is an API documentation, not a marketing text. So is it safe to try to access an index beyond the bounds? It’s hard to say. All of this can be utterly misleading.

What does “prevent offsetting beyong those bounds” mean?

Is it allowing indexes up to or including the limit?

The docs don’t tell. You have to force yourself to consider this to be a vague statement and test its implications. Experiences programmers will undoubtedly do that thanks to years and years of trial by fire – but that doesn’t make the docs any better. If you start developing in Swift, you might not notice the vague statement here, and the omission of a specification of what happens when index + offset == endIndex.

If you copy the sample codes from the docs to play around, and only test the resulting algorithms in your program with an offset somewhere inside the bounds of the string and and somewhere way past the end of the string, you might be tricked into believing your algorithm is working as expected. – It doesn’t, though, because these tests made you overlook what happens when the result is equal to endIndex. That’s false confidence. The code does work for the cases you tested, yes, but it utterly crashes for one case.

So the crux is this: the offset may not be set so that the resulting index is at endIndex. Because that’s not a valid limit.¹

From my understanding, the API docs is conveying the wrong information through these examples. (So my initial doubt in how simple it all looked was warranted, and now I’m becoming even more paranoid, great!) The function works real nice when you know what to do, but the String.endIndex doesn’t mean what you might take away from the sample.

The docs on endIndex says:

A string’s “past the end” position—that is, the position one greater than the last valid subscript argument.

You want the limitedBy: parameter to not be past the end, you want it be at at the end. Why is the sample code using an obviously incorrect approach to show how the function works?

That means you need to figure out the index before endIndex, provided the string is long enough to actually cover that. (An empty string has its startRange equal endRange.)

The following is an actually useful, safe way to limit String index access to the String’s real length:

let s = "Swift"

if let indexAtEnd = s.index(s.endIndex, offsetBy: -1, limitedBy: s.startIndex),
    let i = s.index(s.startIndex, offsetBy: 5, limitedBy: indexAtEnd) {
    print(s[i])
}
// nothing happens, as expected!

It’s also ugly as heck.

Remember: that’s why you need to be extra cautious and thorough in your unit tests, kids.

Always be testing

• right before,
• at, and
• right after the limits you want to verify.

Don’t just test somewhere before and somewhere after the limit. Imagine your tests are clamps, and your problem is being clamped so tight it cannot escape. No wiggle room, no margin for error.

—Now guess who was bitten by not testing that way in a particular place.

In other words, an update to The Archive is coming out soon.

I also filed a Feedback issue for this, finally.

I recently dropped blog posts rendered via MultiMarkdown. I used MMD to support citations, but this is not a book, this is a website!

So I retired my MultiMarkdown processor for nanoc, the static site generator that I use.

If you need something like it for your project, here it is:

require "systemu"

class MultiMarkdownFilter < Nanoc::Filter
  identifier :mmd
  type :text

  def run(content, args = {})
    output = ''
    stderr = ''
    status = systemu(
      [ 'multimarkdown' ],
      'stdin'  => content,
      'stdout' => output,
      'stderr' => stderr)

    unless status.success?
      $stderr.puts stderr
      raise RuntimeError, "MultiMarkdown filter failed with status #{status}"
    end

    output.force_encoding('UTF-8')
  end
end

It requires a local installation of the MultiMarkdown binaries. This is not part of any Ruby gem that I’m aware of, so you need to install it separately, e.g. via brew install multimarkdown.

Use it in your Rules file:

compile '/posts/**/*' do
  filter :erb
  filter :mmd  # <----
  layout '/default*'
end

I stumbled upon an interesting coding problem in a recent macOS project related to in-app purchases. IAP can be represented by a feature option set in code. How do you secure UserDefaults access in such a way that accessing values can be locked via the IAP available feature options? (This also applies to tiered licenses, like a “Basic” and a “Pro” feature set.)

Let’s say you represent the purchase-able features as such:

struct Feature: OptionSet {
    let rawValue: Int

    init(rawValue: Int) {
        self.rawValue = rawValue
    }

    static let export = Feature(rawValue: 1 << 1)
    static let analysis = Feature(rawValue: 1 << 2)
    static let advancedProcessCounter = Feature(rawValue: 1 << 3)
}

You can use these in code like this:

let purchasedFeatures: Feature = [.analysis, .export]

Let’s say you can get there through a service object that looks at the current license to figure out which in-app purchase is unlocked. For the sake of this post, it doesn’t matter if you use Apple’s API, the Paddle SDK, or a home-grown solution.

class LicenseReader {
    func purchasedFeatures() -> Feature { ... }
}

You store the value for advancedProcessCounter in a file or UserDefaults, because that’s simple.

private let advancedProcessCounterKey = "Advanced.processCount"

class AdvancedStuff {
    var processCounter: Int {
        get {
            return UserDefaults.standard.integer(forKey: advancedProcessCounterKey)
        }
        set {
            UserDefaults.standard.set(newValue, forKey: advancedProcessCounterKey)
        }
    }

    // Here be code that displays/uses the counter value ...
}

Now let’s hide this behind a paywall.

In your first approach, you ask the LicenseReader for available features directly and either read/write the value, or default to 0 if the user didn’t purchase that advanced thingie. It’s a valid approach to test if the paywall works at all:

private let advancedProcessCounterKey = "Advanced.processCount"

class AdvancedStuff {
    private let licenseReader: LicenseReader = ...
    private var isProcessCounterUnlocked: Bool {
        return licenseReader.purchasedFeatures().contains(.advancedProcessCounter)
    }

    var processCounter: Int {
        get {
            guard isProcessCounterUnlocked else { return 0 }
            return UserDefaults.standard.integer(forKey: advancedProcessCounterKey)
        }
        set {
            guard isProcessCounterUnlocked else { return }
            UserDefaults.standard.set(newValue, forKey: advancedProcessCounterKey)
        }
    }

    // Here be code that displays/uses the counter value ...
}

• LicenseReader.purchasedFeatures is used to test for availability of the .advancedProcessCounter feature
• isProcessCounterUnlocked wraps this check and prevents access to the stored value

You run the app, things work. Nice.

Now you modularize the growing app and want to extract the processCounter reading/writing into another object. This way, your app doesn’t need to know if the setting is stored in UserDefaults, a PList somewhere else, or in the cloud at this point and can defer the knowledge to a pluggable component.

Only now you notice that the I/O of the setting is closely coupled to the LicenseReader, which makes reorganizing the code harder. You don’t want to dependency inject the LicenseReader, either.

The whole license-reading business should not be relevant for reading the value from its source.

But you want the value to be “locked” behind a paywall as strictly as possible.

Encapsulate Value Access in a Paywall Object

Currently, the processCounter: Int property directly returns the stored value or a fallback if the paywall prevents access. How can you strictly require a feature availability check but still reduce the functionality of the defaults reader to simple reading the value?

You can split this into multiple steps:

1. Read the real value from disk/defaults/…
2. Wrap it in a paywall check before returning
3. Satisfy the paywall check when the value is used

If we were thinking about value transformations, it’d be of the form:

() -> (value: Value, required: Feature) -> (available: Feature) -> Value?

We’ll have a look at an object-based approach now.

Instead of directly running a query method on LicenseReader right now, you defer this call to a later point in time. And also abstract away the details.

class SettingsReader {
    var advancedProcessCounter: Paywall<Int> {
        // 1) Read the real value
        let value = UserDefaults.standard.int(forKey: advancedProcessCounterKey)

        // 2) Wrap it in a deferred paywall check
        return Paywall(value: value, 
                       requiredFeatures: .advancedProcessCounter)
    }
}

With this code, the real value is read, there’s no check at this very point, but we can still express a feature requirement.

Here’s a Paywall implementation:

struct Paywall<Value> {
    private let value: Value
    let requiredFeatures: Feature

    init(value: Value, requiredFeatures: Feature) {
        self.value = value
        self.requiredFeatures = requiredFeatures
    }

    func value(availableFeatures: Feature) -> Value? {
        var covered = requiredFeatures
        covered.formIntersection(availableFeatures)
        guard covered == requiredFeatures else { return nil }
        return value
    }
}

The magic happens in Paywall.value(availableFeatures:): it protects access to the value. You only get the value if at least all required features are passed in as the parameter. If one or more are missing, you get back nil.

Now your client code, like view controllers, can provide the glue:

class AdvancedComputationViewController: UIViewController {
    let settingsReader: SettingsReader = ...
    let licenseReader: LicenseReader = ...

    var processCount: Int {
        let paywall: Paywall<Int> = settingsReader.advancedProcessCount
        let value: Int? = paywall.value(availableFeatures: licenseReader.purchasedFeatures())
        return value ?? 0
    }

    // ...
}

You see how the LicenseReader is used to attempt to unlock the Paywall<Int>. If it fails, you return the default value 0 (same as in the very beginning).

The Paywall type forces you to pause for a second when you want access to protected details. You need to figure out a way to pass in the availableFeatures option set, or else you cannot get to the value. The type forces you to remember that this value is locked.

The knowledge about “being locked” is encapsulated in the Paywall type.

A more naive implementation could have read the real process count and then implemented the paywall-check in place:

var naiveProcessCountWithPaywall: Int {
    let value = UserDefaults.standard.int(forKey: advancedProcessCounterKey)

    // The paywall is here
    guard licenseReader.purchasedFeatures().contains(.advancesProcessCounter) else { return 0 }

    return value
}

Problem is: you can easily overlook that this is supposed to be a paywall-protected value. Forgetting the guard statement ruins the whole reason of making the feature purchase-able. Oops.

A type like my Paywall prototype above makes the type system do the work. That’s a beautifully, Swift-y way to help avoid problems instead having to remember them and write unit tests to catch errors.

It also helps splitting your app into multiple, decoupled modules. The SettingsReader does not need to know how available features and the license code is accessed. This is useful to e.g. inline your license-accessor code, making discovery of license-related code harder for crackers.