Sources/OrgCore/Commands/HeadingCommands.swift
374 lines · 17299 bytes
1import Foundation
2
3// Heading-line commands, matched to Emacs 31.1 / Org 9.8.7 by the oracle tests.
4
5/// The heading whose line holds `offset`, for commands that act only on heading lines (org's
6/// M-left, M-right, S-up and S-down do something else elsewhere).
7func headingOnLine(at offset: Int, in tree: OrgTree) -> SyntaxNode? {
8 guard let heading = entryHeading(at: offset, in: tree) else { return nil }
9 let line = HeadingLine(heading)
10 return offset >= line.start && offset <= line.contentEnd ? heading : nil
11}
12
13/// The heading of the entry holding `offset`, as `org-back-to-heading`; nil before the first
14/// heading.
15func entryHeading(at offset: Int, in tree: OrgTree) -> SyntaxNode? {
16 let root = tree.root
17 let position = offset >= root.range.upperBound ? max(0, root.range.upperBound - 1) : offset
18 var node = root
19 var heading: SyntaxNode?
20 while let child = node.child(containing: position), child.kind == .section {
21 heading = child.firstChild(.heading)
22 node = child
23 }
24 return heading
25}
26
27/// The parts of a heading line, in offsets of the whole text.
28struct HeadingLine {
29 let start: Int
30 /// End of the line's content, before its line break.
31 let contentEnd: Int
32 let stars: Range<Int>
33 let todo: SyntaxToken?
34 let priority: SyntaxToken?
35 let tags: SyntaxToken?
36 /// Where the title begins: past the stars, keyword, cookie and the blanks after them.
37 let titleStart: Int
38
39 init(_ heading: SyntaxNode) {
40 let tokens = heading.tokens
41 start = heading.range.lowerBound
42 contentEnd = tokens.first { $0.kind == .newline }?.range.lowerBound ?? heading.range.upperBound
43 stars = tokens.first { $0.kind == .stars }?.range ?? start..<start
44 todo = tokens.first { $0.kind == .todoKeyword }
45 priority = tokens.first { $0.kind == .priority }
46 tags = tokens.first { $0.kind == .tags }
47 var at = start
48 for child in heading.green.children {
49 guard case .token(let token) = child, [.stars, .whitespace, .todoKeyword, .priority].contains(token.kind) else { break }
50 at += token.length
51 }
52 titleStart = min(at, contentEnd)
53 }
54
55 var level: Int { stars.count }
56}
57
58/// One line of text being edited, with a caret that moves the way Emacs moves point and
59/// markers for each kind of edit, so commands land the caret where Emacs does.
60struct LineBuffer {
61 var text: NSMutableString
62 /// Relative to the line start; nil when the caret is elsewhere in the document.
63 var caret: Int?
64
65 init(_ line: String, caret: Int?) {
66 text = NSMutableString(string: line)
67 self.caret = caret
68 }
69
70 var string: String { text as String }
71 var length: Int { text.length }
72
73 private mutating func edit(_ range: Range<Int>, _ replacement: String) -> Int {
74 text.replaceCharacters(in: NSRange(range), with: replacement)
75 return (replacement as NSString).length - range.count
76 }
77
78 /// `replace-match`: a caret strictly inside moves to the start; at or after the end it
79 /// shifts with the text.
80 mutating func replace(_ range: Range<Int>, with replacement: String) {
81 let delta = edit(range, replacement)
82 guard let position = caret else { return }
83 if position >= range.upperBound, position > range.lowerBound {
84 caret = position + delta
85 } else if position > range.lowerBound {
86 caret = range.lowerBound
87 }
88 }
89
90 /// Deleting `range`, then `insert-before-markers`: a caret anywhere from the start to the
91 /// end of the range ends up after the new text.
92 mutating func replaceBeforeMarkers(_ range: Range<Int>, with replacement: String) {
93 let delta = edit(range, replacement)
94 guard let position = caret else { return }
95 if position > range.upperBound {
96 caret = position + delta
97 } else if position >= range.lowerBound {
98 caret = range.lowerBound + (replacement as NSString).length
99 }
100 }
101
102 /// `insert` under `save-excursion`: a caret at the insertion point stays before the text.
103 mutating func insert(_ string: String, at position: Int) {
104 let delta = edit(position..<position, string)
105 if let caret, caret > position { self.caret = caret + delta }
106 }
107
108 /// `insert` at point: the caret moves past the text.
109 mutating func insertAtCaret(_ string: String) {
110 guard let position = caret else { return }
111 let delta = edit(position..<position, string)
112 caret = position + delta
113 }
114}
115
116extension HeadingLine {
117 /// Applies `edit` to the heading line in `context` and maps the caret: on the line it's
118 /// placed by `edit`; after the line it shifts by the change in length.
119 func commit(_ context: EditContext, _ edit: (inout LineBuffer) -> Void) -> CommandStep {
120 let old = (context.text as NSString).substring(with: NSRange(start..<contentEnd))
121 let caretOnLine = context.caret >= start && context.caret <= contentEnd
122 var buffer = LineBuffer(old, caret: caretOnLine ? context.caret - start : nil)
123 edit(&buffer)
124 let new = buffer.string
125 let delta = (new as NSString).length - (old as NSString).length
126 let caret = buffer.caret.map { $0 + start } ?? (context.caret > contentEnd ? context.caret + delta : context.caret)
127 guard new != old else { return .commit(EditResult(baseRevision: context.revision, edits: [], selection: [caret..<caret])) }
128 return .commit(EditResult(
129 baseRevision: context.revision,
130 edits: [TextEdit(range: start..<contentEnd, replacement: new)],
131 selection: [caret..<caret]
132 ))
133 }
134
135 /// Offsets relative to the line start.
136 func local(_ range: Range<Int>) -> Range<Int> { (range.lowerBound - start)..<(range.upperBound - start) }
137}
138
139// MARK: - Tags
140
141/// `org--align-tags-here` with `org-tags-column` -77: tags end at column 77, or sit one blank
142/// after the title when it is too long. Nothing changes when they are already there.
143///
144/// Commands align under `save-excursion`, where the caret is a marker: in the blanks before
145/// the tags it ends up where they start. Aligning tags directly (`preservingColumn`) keeps the
146/// caret's column instead, as org does for point.
147func alignTags(_ buffer: inout LineBuffer, options: EditingOptions = .org, preservingColumn: Bool = false) {
148 let line = buffer.string
149 guard let match = line.range(of: "[ \\t]+(:[[:alnum:]_@#%]+)+:[ \\t]*$", options: .regularExpression) else { return }
150 let matched = String(line[match])
151 let tags = matched.trimmingCharacters(in: .whitespaces)
152 let blankStart = (String(line[..<match.lowerBound]) as NSString).length
153 let tagsStart = blankStart + (matched as NSString).range(of: tags).location
154 // Columns as Emacs displays the line: link markup and, with the options, emphasis markers
155 // don't count.
156 let visible = VisibleLine(line, options: options)
157 let prefixColumn = visible.column(at: blankStart)
158 let currentColumn = visible.column(at: tagsStart)
159 let tagsColumn = options.tagsColumn
160 let target = tagsColumn >= 0 ? tagsColumn : abs(tagsColumn) - displayWidth(tags)
161 let newColumn = max(target, prefixColumn + 1)
162 guard newColumn != currentColumn else { return }
163 let inBlanks = buffer.caret.map { $0 > blankStart && $0 <= tagsStart } ?? false
164 let caretColumn: Int? = inBlanks && preservingColumn ? visible.column(at: buffer.caret!) : nil
165 let old = buffer.caret
166 buffer.text.replaceCharacters(in: NSRange(blankStart..<tagsStart), with: String(repeating: " ", count: newColumn - prefixColumn))
167 let delta = (newColumn - prefixColumn) - (tagsStart - blankStart)
168 if let caretColumn {
169 buffer.caret = VisibleLine(buffer.string, options: options).offset(ofColumn: caretColumn)
170 } else if inBlanks {
171 buffer.caret = blankStart
172 } else if let old, old > tagsStart {
173 buffer.caret = old + delta
174 }
175}
176
177
178// MARK: - TODO
179
180public struct TodoCycle: OrgCommand {
181 public init() {}
182 public var id: String { "org.todo.cycle" }
183 public var title: String { "Cycle TODO State" }
184
185 public func applies(in context: EditContext) -> Bool {
186 entryHeading(at: context.caret, in: context.tree) != nil
187 }
188
189 /// No keyword, then each keyword of its sequence in order, then no keyword again.
190 static func next(after current: String?, in settings: OrgSettings) -> String? {
191 guard let current else {
192 guard let first = settings.todoSequences.first else { return nil }
193 return (first.active + first.done).first?.name
194 }
195 for sequence in settings.todoSequences {
196 let names = (sequence.active + sequence.done).map(\.name)
197 if let index = names.firstIndex(of: current) {
198 return index + 1 < names.count ? names[index + 1] : nil
199 }
200 }
201 return nil
202 }
203
204 /// As `org-todo`: the blanks after the stars, the keyword and the blanks after it are
205 /// replaced by " NEXT " (or " " for no keyword) with `insert-before-markers`, then tags
206 /// are aligned.
207 /// `org-todo`, then the parent's TODO statistics, and the repeat of a repeating entry
208 /// that became done.
209 public func run(in context: EditContext) -> CommandStep {
210 let previous = EmacsBuffer(context.text, point: context.caret, settings: context.tree.settings).todoKeyword
211 return followUp(context, cycle(in: context)) { buffer in
212 try buffer.saveExcursion {
213 buffer.updateParentTodoStatistics()
214 let settings = context.tree.settings
215 guard let new = buffer.todoKeyword, settings.isDone(new), !(previous.map(settings.isDone) ?? false) else { return }
216 if let (marker, note) = try buffer.autoRepeat(doneWord: new, previous: previous) { buffer.storeNote(marker, note) }
217 }
218 }
219 }
220
221 private func cycle(in context: EditContext) -> CommandStep {
222 guard let heading = entryHeading(at: context.caret, in: context.tree) else {
223 return .failed("Before first headline")
224 }
225 let line = HeadingLine(heading)
226 let next = Self.next(after: line.todo?.text, in: context.tree.settings)
227 return line.commit(context) { buffer in
228 let text = buffer.string as NSString
229 let regionStart = line.stars.upperBound - line.start
230 var regionEnd = regionStart
231 while regionEnd < text.length, text.character(at: regionEnd) == 0x20 { regionEnd += 1 }
232 if let todo = line.todo {
233 regionEnd = line.local(todo.range).upperBound
234 var blanks = regionEnd
235 while blanks < text.length, text.character(at: blanks) == 0x20 { blanks += 1 }
236 if blanks > regionEnd {
237 regionEnd = blanks
238 } else if text.substring(from: regionEnd).allSatisfy({ $0 == " " || $0 == "\t" }) {
239 regionEnd = text.length
240 }
241 }
242 buffer.replaceBeforeMarkers(regionStart..<regionEnd, with: next.map { " \($0) " } ?? " ")
243 alignTags(&buffer, options: context.options)
244 }
245 }
246}
247
248// MARK: - Priority
249
250struct PriorityChange {
251 let up: Bool
252
253 func run(in context: EditContext) -> CommandStep {
254 guard let heading = headingOnLine(at: context.caret, in: context.tree) else {
255 return .failed("Not on a heading")
256 }
257 let line = HeadingLine(heading)
258 let priorities = context.tree.settings.priorities
259 guard let highest = Self.value(priorities.highest), let lowest = Self.value(priorities.lowest) else {
260 return .failed("Unsupported priority range")
261 }
262 let numeric = Int(priorities.highest) != nil
263 let current = line.priority.flatMap { Self.value(String($0.text.dropFirst(2).dropLast())) }
264 // From no cookie, the first press sets the default, as `org-priority-start-cycle-with-default`.
265 var new: Int?
266 if let current {
267 new = up ? current - 1 : current + 1
268 if let value = new, value < highest || value > lowest { new = nil }
269 } else {
270 new = Self.value(priorities.default)
271 }
272 let cookie = new.map { "[#\(Self.label($0, numeric: numeric))]" }
273 return line.commit(context) { buffer in
274 if let existing = line.priority {
275 let range = line.local(existing.range)
276 if let cookie {
277 buffer.replace((range.lowerBound + 2)..<(range.upperBound - 1), with: String(cookie.dropFirst(2).dropLast()))
278 } else {
279 // The cookie and one following space, as `org-priority-regexp` group 1.
280 let text = buffer.string as NSString
281 let space = range.upperBound < text.length && text.character(at: range.upperBound) == 0x20 ? 1 : 0
282 buffer.replace(range.lowerBound..<(range.upperBound + space), with: "")
283 }
284 } else if let cookie {
285 if let todo = line.todo {
286 buffer.insert(" " + cookie, at: line.local(todo.range).upperBound)
287 } else {
288 buffer.insert(cookie + " ", at: line.titleStart - line.start)
289 }
290 }
291 alignTags(&buffer, options: context.options)
292 }
293 }
294
295 /// A priority as a number: a letter's code point, or the number itself.
296 static func value(_ text: String) -> Int? {
297 if let number = Int(text) { return number }
298 guard text.unicodeScalars.count == 1, let scalar = text.unicodeScalars.first else { return nil }
299 return Int(scalar.value)
300 }
301
302 static func label(_ value: Int, numeric: Bool) -> String {
303 numeric ? String(value) : String(Character(Unicode.Scalar(UInt32(value))!))
304 }
305}
306
307public struct PriorityUp: OrgCommand {
308 public init() {}
309 public var id: String { "org.priority.up" }
310 public var title: String { "Raise Priority" }
311 public func applies(in context: EditContext) -> Bool { headingOnLine(at: context.caret, in: context.tree) != nil }
312 public func run(in context: EditContext) -> CommandStep { PriorityChange(up: true).run(in: context) }
313}
314
315public struct PriorityDown: OrgCommand {
316 public init() {}
317 public var id: String { "org.priority.down" }
318 public var title: String { "Lower Priority" }
319 public func applies(in context: EditContext) -> Bool { headingOnLine(at: context.caret, in: context.tree) != nil }
320 public func run(in context: EditContext) -> CommandStep { PriorityChange(up: false).run(in: context) }
321}
322
323// MARK: - Promote and demote
324
325public struct PromoteHeading: OrgCommand {
326 public init() {}
327 public var id: String { "org.heading.promote" }
328 public var title: String { "Promote Heading" }
329 public func applies(in context: EditContext) -> Bool { headingOnLine(at: context.caret, in: context.tree) != nil }
330
331 public func run(in context: EditContext) -> CommandStep {
332 guard let heading = headingOnLine(at: context.caret, in: context.tree) else { return .failed("Not on a heading") }
333 let line = HeadingLine(heading)
334 guard line.level > 1 else { return .failed("Cannot promote to level 0") }
335 return line.commit(context) { buffer in
336 buffer.replace(0..<(line.level + 1), with: String(repeating: "*", count: line.level - 1) + " ")
337 alignTags(&buffer, options: context.options)
338 fixPositionAfterPromote(&buffer, settings: context.tree.settings)
339 }
340 }
341}
342
343public struct DemoteHeading: OrgCommand {
344 public init() {}
345 public var id: String { "org.heading.demote" }
346 public var title: String { "Demote Heading" }
347 public func applies(in context: EditContext) -> Bool { headingOnLine(at: context.caret, in: context.tree) != nil }
348
349 public func run(in context: EditContext) -> CommandStep {
350 guard let heading = headingOnLine(at: context.caret, in: context.tree) else { return .failed("Not on a heading") }
351 let line = HeadingLine(heading)
352 return line.commit(context) { buffer in
353 buffer.replace(0..<(line.level + 1), with: String(repeating: "*", count: line.level + 1) + " ")
354 alignTags(&buffer, options: context.options)
355 fixPositionAfterPromote(&buffer, settings: context.tree.settings)
356 }
357 }
358}
359
360/// `org-fix-position-after-promote`: a caret right after the stars or the keyword steps over
361/// the following space, or adds one at the end of the line.
362func fixPositionAfterPromote(_ buffer: inout LineBuffer, settings: OrgSettings) {
363 guard let caret = buffer.caret else { return }
364 let tree = OrgParser.parse(buffer.string + "\n", defaults: settings)
365 guard let heading = tree.root.firstChild(.section)?.firstChild(.heading) else { return }
366 let line = HeadingLine(heading)
367 let anchors = [line.stars.upperBound, line.todo?.range.upperBound].compactMap { $0 }
368 guard anchors.contains(caret) else { return }
369 if caret == buffer.length {
370 buffer.insertAtCaret(" ")
371 } else if buffer.text.character(at: caret) == 0x20 {
372 buffer.caret = caret + 1
373 }
374}