Archive for the ‘Development’ Category

Swift Packages and the need for metadata

Right now, a Swift Package defines the sources and dependencies for successful compilation. The PackageDescription specifies items like the supported Swift version, linker settings, and so forth.

What it does not do is offer metadata. You won’t find email for the active project manager, a list of major authors, descriptive tags, an abstract or discussion of the package, a link to documentation, deprecation information or links to superceding packages upon deprecation.

For me, tags are especially important as they can drive discoverability on aggregators such as SwiftPackageIndex.com or SwiftPackageRegistry.com, among others, as they do in the various App Stores. However, all the other information I’ve mentioned can be equally valuable. The question is how this information should be stored and travel.

Extending SwiftPM’s PackageDescription is the most obvious way but the one with the greatest hurdles. Extending a specification means review, bikeshedding, and approval but is one that would produce the most rigorous and widely-applicable outcome:

let package = Package(
    name: "now",
    platforms: [
      .macOS(.v10_12)
    ],
    metadata: [
      .tags(["dates", "calendar", "scheduling", "time", "appointments"]),
      .maintainer("erica@ericasadun.com"),
    ],
...

Freeform tags are, as Mattt of three t’s pointed out to me, a folksonomy: a user-specified list that can be organized or freeform, sensible or not. Anyone familiar with the App Store will recall how its tags have both benefited developers and how its tags can be abused to drive traffic.

Of course, updating the PackageDefinition spec is not the only approach. The same information could be packaged into a second file cohosted with Package.swift. Perhaps it could be called Package.metadata (if stored as JSON, for example) or PackageMetadata.swift (if the information is SwiftPM-like with its own Metadata type and supporting package to better support automated validation and consumption).

Plain JSON has many advantages. It requires no secondary code development as PackageMetadata.swift would. It has an obvious place to live and can be just as easily omitted. The standard for contents could be community-sourced and Decodable developed specifically for it, plus the JSON could be validated according to that standard.

I am least enthused by PackageMetadata.swift with its high overhead and mimicking of Package.swift but it would certainly fit with the design and approach and lower the overhead for consumption.

What do you think? How would you design metadata delivery for Swift packages? The one file to rule them all expansion of SwiftPM itself, the simplicity of Metadata.json, or something else? Let me know.

The silly delight of the Xcode document opening `xed`

Julian Kahnert recently introduced me to xed, a command-line built-in that opens individual documents in Xcode. You give xed the name of a file (or files) and presto, it launches in my favorite IDE.

There’s some intriguing flexibility to xed. You can request that Xcode remains in the --background or specify a --line number to select once open. The line number request affects the last file in the invocation. In addition to passing it files to open, you can --create new files with the contents of stdin: promising for scripting and code-gen utilities.

If you pass --launch, xed promises to create a “new empty unsaved file”,  without involving stdin. Unfortunately, in my experiments with it over the past week, I’ve found that while it’s very good at opening a single file, complex commands can sometimes confuse the poor geriatric utility. xed was introduce way back in Xcode 3.0 and it kind of shows its age at times.

Even just limiting my xed use to opening a file for editing, it’s a neat little discovery for me, so thank you Julian!

Our discussion arose out of my own little utility xcopen, which I put up on Github. Mine looks in the working directory for an xcproj and then opens it. (I got tired of either working through the file completion, when there’s always a subdirectory with the same name as the xcproj or having to open Finder and then launch.)

I really like the idea behind xed and I’m half tempted to extend the feature set in xcopen using AppleScripting to get the promise of xed with a more reliable delivery platform.

Swift Process and osascript: so much easier than the command line

I use osascript a lot to automate things that need automating and until yesterday, I did so almost exclusively from shell scripts. Then,  while developing some sample code the other day, I discovered how much easier it is to call osascript from a command-line utility, even for the most trivial of scripts.

let script = """
  set appName to "\(appName)"
  tell application "System Events"
	if visible of application process appName is true then
		set visible of application process appName to false
	else
		set visible of application process appName to true
	end if
  end tell
  """

With Swift’s triple-quoted multiline string, you need little if any escaping and your script can basically be copy/pasted from the Script Editor app. Plus string interpolation enables you programmatically customize your AppleScript code.

For your Process, set your launchPath to "/usr/bin/osascript" and your arguments to ["-e", script]. Then launch and wait until exit.

if #available(macOS 10.13, *) {
    guard (try? process.run()) != nil
        else { throw RuntimeError.operationError }
} else {
    process.launch()
}
process.waitUntilExit()

Why is it worth creating an entire Xcode project to deal with a little osascript work? For me, it’s a big win when it is part of a larger utility. With the Swift Argument Parser, I’ve been porting a lot of my scripts — both shell scripts and swift scripts — to compiled utilities and I find that I tend to lean on osascript a lot more than I thought I did to automate my system.

SwiftPM and Tagging

A couple of days ago, I was having the oddest issues fetching a SwiftPM package. The package resolution/version solving failed. I still don’t know why this was happening as my package was tagged as “0.1.0” at the time, as confirmed over at Github.

In any case, I found that removing the tag locally and remotely and retagging and re-pushing my tags resolved the issue. The package resolved correctly afterwards.

While I was at this, I decided to update my .gitconfig to add tagging aliases. Here’s what I came up with. They work but they’re not pretty and I’m sure there are better ways to approach this:

####
# Tagging
retag = "!f(){ name=`git tag | tail -1`; \
	git tag -d \"$name\"; echo "Retagged $name"; \
	remote=`git remote -v`; \
	if [ \"$remote\" != \"\" ]; \
	then git push origin --delete \"$name\"; fi; \
	git tag \"$name\"; \
	if [ \"$remote\" != \"\" ]; \
	then git push --tags; \
	else echo "No remote"; fi; };f"
untag = "!f(){ name=`git tag | tail -1`; git tag -d \"$name\"; \
	remote=`git remote -v`; \
	if [ \"$remote\" != \"\" ]; \
	then git push origin --delete \"$name\"; \
	else echo "No remote"; fi; };f"
tagit = "!f(){ git tag \"$@\"; echo "Tagged $name";\
	remote=`git remote -v`; \
	if [ \"$remote\" != \"\" ]; \
	then git push --tags; \
	else echo "No remote"; fi; };f"

retag, which solved my issue, grabs the name of the current tag, removes it, and retags locally and remotely. untag removes the tag and tagit adds a new tag to the current commit.

Feel free to suggest improvements.

p.s. If you’re looking for it, I took down the time machine rant post at the suggestion of several commenters.

Building a silly WatchKit App

WatchKit apps are easy to build and draining to debug. I don’t know what it is about extensions but they’re never fun to work with. The other day, daughter asked for an app to play some favorite sounds. I promised I’d write up a post about this, so here it is.

The entirety of the code took maybe a couple of minutes. This is one of the many places where using SwiftUI is a sheer delight. I did have to play with renderingMode to override the default B&W scheme for three of my buttons:

I decided to go with bundle-stored audio rather than deal with the complexities of adding audio assets to an xcassets item. Quick and easy. I limited the daughter to just 4 out of her long list of requested sounds to simplify my life. She returned with her list grudgingly prioritized.

Trimming and converting the audio to wav took seconds, thanks to command-line ffmpeg. Creating the art, too, was simple. I just used Preview to create all the required App Icons. Call it another 5 minutes to get that done. It was a great time to use Preview’s magic selection wand and its support for layers and transparency.

Where all the trouble lay was getting the watch app to consistent deploy to hardware for testing. Although this was a watch-only app, the phone still plays a big role. And I finally discovered that keeping my phone tethered to the computer when deploying to the watch made for a much smoother and more consistent experience. But the frustrations of failed deploys led to over an hour invested.

Here’s a quick summary of where my development time was spent.  Area corresponds to the level of effort:

The actual coding was nothing. Asset prep is always tedious but it’s O(n). It’s pretty clear from the start how much effort is needed, which varies by the number of assets used. You don’t add more complexity when you’re working with the right formats and tools.

The vast majority of headache is getting the Xcode tooling and the hardware to sync, install, and test. This really should be the easiest part, but it was endlessly frustrating. I don’t know if my tether-breakthrough is a universal solution or if my next project will be just as frustrating.

In the end, what should have been a half hour project stretched to several hours. I hope the next one will be way shorter.

“mint” (a simple SwiftPM installer) has improved my command line life

SwiftPM’s lack of an easy install feature has long been an issue of mine and for other people too. As the linked forums thread suggests, to accomplish this for a general audience requires some careful thinking: adding to /usr/local/bin is not always the best solution for every user.

Still, it’s a feature whose absence is notable. To fill the gap, I’ve discovered Yonas Kolb’s mint. Thank you to Leo Dion, who introduced this to me. It is ridiculously simple to use. Could it get easier than mint install erica/now? Admittedly my github id is short and so is my project name, but I think my point stands…

Yesterday, I hastily added a SwiftPM project to remind so it too could be installed via mint. Suddenly, adding the project specification is no longer an afterthought but a driving feature. It’s made SwiftPM support far more valuable to me for executables.

Make sure you name your primary file main.swift, your product to .executable, and if you’re developing in Xcode, override your path to point to the Xcode-project-style folder for the source files, usually the same name as the project itself. I mention this because Xcode by default (File > New > Swift Package) builds library projects, not executable ones. At the command-line use swift package init --type executable.

// swift-tools-version:5.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "remind",
    platforms: [
        .macOS(.v10_12)
    ],
    products: [
        .executable(
            name: "remind",
            targets: ["remind"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "0.0.6"),
    ],
    targets: [
        .target(
            name: "remind",
            dependencies: [.product(name: "ArgumentParser", package: "swift-argument-parser")],
            path: "remind/"
        ),
    ],
    swiftLanguageVersions: [
        .v5
    ]
)

As for mint itself, you can build it or install it via HomeBrew: brew install mint.

If you have any suggestions on how I can improve my SwiftPM work, better integrate tagging, or any other tips, please let me know. Thanks!

Musings on `Result` and building a command line utility with completion handlers

Collaborating with Paul Hudson is a pleasure but the time difference can be, well, confusing. So when I started putting together an outline about the new command line argument parser for Pragmatic, one of the first things I wrote was a command line utility to tell me what time it was in Bath, UK:

% now bath uk
Bath 4:16:42 PM (GMT+1 United Kingdom Time)

I use CLGeocoder to use whatever terms I enter after the command as the hints to look up places of interests. I grab the first match and pull the time zone from that match (or throw an error if there’s no possible match).

Command-line utilities are not particularly well known for their asynchronous feature support. Because geocodeAddressString does run asynchronously, I use the quick and dirty trick of starting a runloop that executes until the completion handler finishes. I’m basically adapting an async method to sync.

This gave me an opportunity to finally get around to using the new Result type. Restrictions on other projects prevented me from kicking its wheels (or I was already using my own version from way back).

I struggled a little with how to incorporate Result. Here’s an earlier go at this. I use an optional resultto store the result, which is then set in completion scope:

var result: Result<[CLPlacemark], Error>?

CLGeocoder().geocodeAddressString(hint) { placemarks, error in
    switch (placemarks, error) {
    case (_, let error?):
        result = .failure(error)
    case (let placemarks?, _):
        result = .success(placemarks)
    default:
        fatalError("Geocoder error, no results.")
    }
    CFRunLoopStop(CFRunLoopGetCurrent())
}
CFRunLoopRun()

This code bothered me, and not just because I had to test and unwrap result when control returned to the main part of my method. It seems so obvious that Result should have a simple initializer based on the common elements found in legacy completion handlers. This would collapse those arguments to, for example, completion(Result(error, data)). Unless I’m missing something big here, I thought to build my own convenience initializer:

extension Result {
    init(_ success: Success?, _ failure: Failure?) {
        precondition(!(success == nil && failure == nil))
        switch (success, failure) {
        case (let success?, _):
            self = .success(success)
        case (_, .let failure?):
            self = .failure(failure)
        default:
            fatalError("Cannot initialize `Result` without success or failure")
        }
    }
}

That extension allowed me to collapse the code down to this. Notice how I can use the initializer here to eliminate the optional result, simplifying my extraction with get, towards the end. Admittedly, it’s not always easy to come up with an initial value that can be overwritten this way, but here it worked. The handler became two lines long, and processing the result to get my placemark (including all error handling), another two lines:

static func fetchPlaceMark(from hint: String) throws -> CLPlacemark {
    var result: Result<[CLPlacemark], Error> = Result([], nil)

    CLGeocoder().geocodeAddressString(hint) { placemarks, error in
        result = Result(placemarks, error)
        CFRunLoopStop(CFRunLoopGetCurrent())
    }
    CFRunLoopRun()

    let placemarks = try result.get()
    return placemarks[0]
}

I quite like my initializer and wonder why something like that doesn’t already exist unlike init(catching:() -> Success). I’m curious as surely I’ve missed something important. Even in normal completion handlers, I’d imagine using the legacy Error? and Data? optionals would be a common use-case for Result

Let me know.

How to contribute to the iOS Developer Survey

Dave Verwer, bless his heart, put together an amazing collection of developer statistics in this year’s iOS developer survey. From careers to conferences, dev tools to frameworks, he profiled the community to discover what is happening on our platforms and in our jobs. If you haven’t already been over to the survey site, go and click the link. Don’t worry, this post will still be here when you get back.

The raw data only goes so far. What the survey needs now is you. Dave is looking for community members to help analyze the results so we can better understand what all this data means. For example, we’ve come to love and cherish our dev tools in a way that was unthinkable just a few years ago. Are the high marks for Xcode universal or are  coders with, say, five or more years of development experience particularly grateful for this advancement?

If you have an interest in deeper analysis, Dave has tools to help you slice, dice, and Julian fry the results. Right now there are just four articles available that evaluate the core information (“Is WWDC already a virtual conference?”, “How popular is Swift?”), and they’ve been written by Dave himself.

This data is crying out for deeper investigation, more voices, and diverse insights. If you have time and curiosity, I urge you to reach out to Dave on Twitter and get involved.

This is a fantastic opportunity to give a little back to the community that nurtures our professional lives.

How to fix: Ooops, I lost track of those beta upgrades

What happens when you put off beta upgrades and put them off and off and off and suddenly the release version has outpaced the beta? This happens:

And this happens:

So there you are, stuck in beta and complaining to your friends about what is, ultimate, my your fault. If you don’t update on a timely basis, you can waste a few hours (as I just did) getting your system back on track so you can mess with (for example, just to pull something out of thin air) Swift Playgrounds for iOS for Mac (which requires the 10.15.4 beta10.15.3).

Just so you don’t waste time, don’t try installing the 10.15.3 combo updater. (Image above) You need to:

  • Unenroll from the beta program,
  • Install the latest macos from the App Store,
  • Re-enroll into the beta program, and
  • Upgrade to the latest beta.

Prepare to waste your entire morning on this, hopefully less the time I spent figuring it out courtesy of friends. Once you get the App Store blessed macos install going, remember that once it reboots, there’s another hour of wait time just on the standard install:

Those 13 minutes are a lie.

Expect at least another hour once you get to the beta access installer:

Hopefully this post will help anyone doing a websearch to get out of exactly this issue at some point in the future.

A final note: Once you’re up to date, swear to yourself that your rule of “never be the first to install a new beta” doesn’t mean “never be the last to install the new beta“. Hopefully I’ve learned my lesson.

Circles within circles: custom types and extensions

So the other day Paul and I were shooting the breeze about spirographs. He was saying I needed to get back to blogging now that I have the time. Of course, the second you set out to try to write a post, so many ideas flow forth at once, it actually is hard to pick just one and focus on it. Since he had enjoyed my drawing work, I thought I’d start out with a little push at circles.

That quickly went out of control because I ended up with enough material for a few chapters rather than a single blog post. (And, no, my chapter for his book is about property wrappers, which I love, rather than drawing)

To give a little context, before I decided to try my hand at full time work, I had had a contract with Pragmatic to update my Drawing book. I had to cancel that because commuting full time to another city left me with zero free time for my self, my family, let alone writing. (Now that I am back at my own desk, I may see about returning to that project because geometry is a core passion.)

Anyway, let me start at the end of all this and show you some pictures and then I’ll (pardon me) circle back and start telling the story of the code and how all this came to pass.

I started my day by opening a playground, deciding to just flex my coding and see where it would take me. I wanted to work with circles, so I plugged a range into a map to get me there.

// Get some points around a circle
let points = (0 ..< nPoints).map({ idx -> CGPoint in
  let theta = CGFloat(idx) * (CGFloat.pi * 2 / CGFloat(nPoints))
  return CGPoint(x: r * cos(theta), y: r * sin(theta))
})

// Create a path
let path = UIBezierPath()

// Get the last point before the circle starts again
let lastIndex = points.index(before: points.endIndex)

// Draw something interesting
for (point, index) in zip(points, points.indices) {
  let p0 =  index == lastIndex
    ? points.startIndex
    : points.index(after: index)
  let p1 = index == points.startIndex
    ? lastIndex
    : points.index(before: index)
  path.move(to: .zero)
  path.addCurve(to: point, controlPoint1: points[p0], controlPoint2: points[p1])
  
}

It’s not the worst code in the world, but it’s not great. I was rewarded with a pretty path, so whee. Still, the code was screaming out that it wanted to be better.

I started by attacking the index work. Why not have an array that supported circular indexing by offering the next and previous items? So I built this:

public extension Array {
  /// Return the next element in a circular array
  subscript(progressing idx: Index) -> Element {
    idx == indices.index(before: indices.endIndex)
      ? self[indices.startIndex]
      : self[indices.index(after: idx)]
  }
  
  /// Return the previous element in a circular array
  subscript(regressing idx: Index) -> Element {
    idx == indices.startIndex
      ? self[indices.index(before: indices.endIndex)]
      : self[indices.index(before: idx)]
  }
}

Before you start yelling at me, I quickly realized that this was pretty pointless. Arrays use Int indexing and I had already written wrapping indices a billion times before. Just because I has the concept of a circle in my head didn’t mean that my array needed to. I pulled back and rewrote this to a variation of my wrap:

public extension Array {
  /// Return an offset element in a circular array
  subscript(offsetting idx: Index, by offset: Int) -> Element {
    return self[(((idx + offset) % count) + count) % count]
  }
}

Much shorter, a bit wordy, but you can offset in either direction for as far as you need to go. I did run into a few out of bounds errors before remembering that modulo can return negative values. I decided not to add in any assertions about whether idx was a valid index as arrays already trap on that, so a precondition or assertion was just overkill.

Next, I decided to design a PointCircle, a type made up of points in a circle. Although I initially assumed I’d want a struct, I soon realized that I preferred to be able to tweak a circle’s radius or center, so I moved it to a class instead:

/// A circle of points with a known center and radius
public class PointCircle {
  
  /// Points representing the circle
  public private(set) var points: [CGPoint] = []
  
  /// The number of points along the edge of the circle
  public var count: Int {
    didSet { setPoints() }
  }
  
  /// The circle radius
  public var radius: CGFloat {
    didSet { setPoints() }
  }
  
  /// The circle's center point
  public var center: CGPoint {
    didSet { setPoints() }
  }
  
  public init(count: Int, radius: CGFloat, center: CGPoint = .zero) {
    (self.count, self.radius, self.center) = (count, radius, center)
    setPoints()
  }

  /// Calculate the points based on the center, radius, and point count
  private func setPoints() {
    points = (0 ..< count).map({ idx -> CGPoint in
      let theta = CGFloat(idx) * (2 * CGFloat.pi / CGFloat(count))
      return CGPoint(x: center.x + radius * cos(theta), y: center.y + radius * sin(theta))
    })
  }
  
}

I added observers to each of the tweakable properties (the radius, point count, and center), so the circle points would update whenever these were changed. By the way, this is a great example of when not to use property wrappers. Wrappers establish behavioral declarations, which this is not. My circle uses the observers instead to maintain coherence of its internal state, not to modify, limit, or expand type side effects for any of these properties.

Now I could easily create a circle and play with its points:

let circle = PointCircle(count: 20, radius: 100)
let path = UIBezierPath()
for (point, index) in zip(circle.points, circle.points.indices) {
  path.move(to: circle.center)
  path.addCurve(to: point,
                controlPoint1: circle.points[offsetting: index, by: 1],
                controlPoint2: circle.points[offsetting: index, by: -1])
}

I decided not to add some kind of API for passing a 2-argument (point, index) closure to my circle instance. It doesn’t really add anything or make much sense to do that here. It wouldn’t produce much beyond a simple for-loop, and the point here is to build a Bezier path, not to “process” the circle points.

My goal was to build enough support to allow me to iterate through the points and reference adjacent (or further offset) points to build curves. This does the job quite nicely.

It didn’t feel quite finished though. I wanted to add a little extra because one of the things I often do with this kind of drawing is create stars and points and loops using offsets from the main radius, often interpolated between the main points on the circle’s edge. Because I had built such a simple class, adding an extension for this was a snap:

extension PointCircle {
  /// Returns an interpolated point after a given index.
  ///
  /// - Note: Cannot pass the existing radius as a default, which is why the greatest finite magnitude is used
  public func interpolatedPoint(after idx: Int, offsetBy offset: CGFloat = 0.5, radius r: CGFloat = .greatestFiniteMagnitude) -> CGPoint {
    let r = r == .greatestFiniteMagnitude ? self.radius : r
    let theta = (CGFloat(idx) + offset) * (2 * CGFloat.pi / CGFloat(count))
    return CGPoint(x: center.x + r * cos(theta), y: center.y + r * sin(theta))
  }
}

The most interesting thing about this is that you cannot use a type member to default a method argument, which is why I ended up defaulting it to `greatestFiniteMagnitude`. It seems to me that it would be a natural fit for the Swift language to allow that kind of defaulting. In this case, it would say: “If the caller doesn’t specify a radius, just use the one already defined by the instance.” What do you think? Is that too weird an ask?

To wrap up, here’s an example using the interpolation:

let path2 = UIBezierPath()
for (point, index) in zip(circle.points, circle.points.indices) {
  path2.move(to: point)
  path2.addCurve(to: circle.points[offsetting: index, by: 1],
                 controlPoint1: circle.interpolatedPoint(after: index, offsetBy: 0.33, radius: circle.radius * -2),
                 controlPoint2: circle.interpolatedPoint(after: index, offsetBy: 0.67, radius: circle.radius * -2))
}

All the shapes at the start of this post are created from this and the preceding loop by tweaking the curve parameters. What pretty results will you come up with? If you build something particularly lovely, please share. I’d love to see them!