TextFormation

TextFormation is simple rule system that can be used to implement typing completions and whitespace control. Think matching "}" with "{" and indenting.

Integration

dependencies: [
    .package(url: "https://github.com/ChimeHQ/TextFormation", from: "0.8.0")
]

Concept

TextFormation's core model is a Filter. Filters are typically set up once for a given language. From there, changes in the form of a TextMutation are fed in. The filter examines a TextMutation before it has been applied. A filter can have three possible result actions.

none indicates that the mutation should be passed to the next filter in the list
stop means no further filtering should be applied
discard is just like stop, but also means the TextMutation shouldn't be applied

Filters do not necessarily change the text. You must respect the filter action, ensuring that the mutation is actually applied in the cases of none and stop. The design of the filters tries hard to allow mutations to occur to help maintain the expected selection and undo behaviors of a standard text view.

Usage

Careful use of filter nesting, possibly CompositeFilter, and these actions can produce some pretty powerful behaviors. Here's an example of a chain that produces typing completions that roughly matches what Xcode does for open/close curly braces:

// skip over closings
let skip = SkipFilter(matching: "}")

// apply whitespace to our close
let closeWhitespace = LineLeadingWhitespaceFilter(string: "}")

// handle newlines inserted in between opening and closing
let newlinePair = NewlineWithinPairFilter(open: "{", close: "}")

// auto-insert closings after an opening, with special-handling for newlines
let closePair = ClosePairFilter(open: "{", close: "}")

// surround selection-replacements with the pair
let openPairReplacement = OpenPairReplacementFilter(open: "{", close: "}")

// delete a matching close when adjacent and the opening is deleted
let deleteClose = DeleteCloseFilter(open: "{", close: "}")

let filters: [Filter] = [skip, closeWhitespace, openPairReplacement, newlinePair, closePair, deleteClose]

// treat a "stop" as only applying to our local chain
let filter = CompositeFilter(filters: filters, handler: { (_, action) in
    switch action {
    case .stop, .none:
        return .none
    case .discard:
        return .discard
    }
})

This kind of usage is probably going to be common, so all this behavior is wrapped up in a pre-made filter: StandardOpenPairFilter.

let filter = StandardOpenPairFilter(open: "{", close: "}")

Using filters:

// simple indentation algorithm that uses minimal text context
let indenter = TextualIndenter()

// delete any trailing whitespace, and use our indenter to compute
// any needed leading whitespace using a four-space unit
let providers = WhitespaceProviders(leadingWhitespace: indenter.substitionProvider(indentationUnit: "    ", width: 4),
                                    trailingWhitespace: { _, _ in return "" })

let action = filter.shouldProcessMutation(mutation, in: textView, with: providers)

There's also a nice little type called TextViewFilterApplier that can make it easier to connect filters up to an NSTextView or UITextView. All you need to do use one of the stand-in delegate methods:

public func textView(_ textView: NSTextView, shouldChangeTextInRanges affectedRanges: [NSValue], replacementStrings: [String]?) -> Bool
public func textView(_ textView: NSTextView, shouldChangeTextInRange affectedRange: NSRange, replacementString: String?) -> Bool

public func textView(_ textView: UITextView, shouldChangeTextIn range: NSRange, replacementText text: String) -> Bool

Indenting

Correctly indenting in the general case may require parsing. It also typically needs some understanding of the user's preferences. The included TextualIndenter type has a pattern-based system that can perform sufficiently in many situations.

It also includes pre-defined patterns for some languages:

TextualIndenter.rubyPatterns
TextualIndenter.pythonPatterns

Suggestions or Feedback

We'd love to hear from you! Get in touch via an issue or pull request.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.