Sources/OrgApp/CaptureModel.swift
195 lines · 10426 bytes
1import Foundation
2import Observation
3import OrgCore
4import OrgDocument
5
6/// Capture templates from `capture.toml`, and capturing into their targets:
7///
8/// ```toml
9/// [[template]]
10/// key = "t"
11/// name = "Personal todo"
12/// type = "entry" # entry, item, checkitem, plain or table-line
13/// file = "todo.org" # relative to the first folder, or ~/… or /…
14/// headline = "Inbox" # or olp = "Projects/Work"; neither for the end of the file
15/// template = "* TODO %?\n%i\n%a"
16/// prepend = false
17/// ```
18///
19/// Other targets: `datetree = true` (under `olp` if given; `tree-type` "day", "week" or
20/// "month"), `id = "…"` without `file`, `clock = true` without `file`. Other properties, as
21/// in `org-capture-templates`: `immediate-finish`, `empty-lines`, `empty-lines-before`,
22/// `empty-lines-after`, `jump-to-captured`, `clock-in`, `clock-keep`, `clock-resume`,
23/// `table-line-pos`.
24@MainActor
25public enum CaptureTemplates {
26 public static var userFile: URL { UserConfig.file("capture.toml") }
27
28 /// The templates in your Doom configuration.
29 public static let defaults = [
30 CaptureTemplate(key: "t", name: "Personal todo", target: .headline(file: "todo.org", headline: "Inbox"), template: "* TODO %?\n%i\n%a"),
31 CaptureTemplate(key: "n", name: "Personal notes", target: .headline(file: "notes.org", headline: "Inbox"), template: "* %u %?\n%i\n%a"),
32 ]
33
34 public static func load(userFile: URL = userFile) -> (templates: [CaptureTemplate], problems: [String]) {
35 guard let text = try? String(contentsOf: userFile, encoding: .utf8) else { return (defaults, []) }
36 let tables: [TOML.Table]
37 do {
38 tables = try TOML.parse(text)
39 } catch {
40 return (defaults, ["capture.toml: \(error)"])
41 }
42 var templates: [CaptureTemplate] = []
43 var problems: [String] = []
44 for table in tables where !(table.name.isEmpty && table.values.isEmpty) {
45 guard table.name == "template", table.isArrayElement else {
46 problems.append("capture.toml line \(table.line): expected [[template]]")
47 continue
48 }
49 let values = table.values
50 let fileless = values["id"]?.string != nil || values["clock"]?.bool == true
51 guard let key = values["key"]?.string, let body = values["template"]?.string, let file = values["file"]?.string ?? (fileless ? "" : nil) else {
52 problems.append("capture.toml line \(table.line): a template needs key, file and template")
53 continue
54 }
55 guard let kind = CaptureTemplate.Kind(rawValue: table.values["type"]?.string ?? "entry") else {
56 problems.append("capture.toml line \(table.line): unknown type")
57 continue
58 }
59 let olp = values["olp"]?.string.map { $0.split(separator: "/").map(String.init) }
60 let target: CaptureTemplate.Target
61 if let id = values["id"]?.string {
62 target = .id(id)
63 } else if values["clock"]?.bool == true {
64 target = .clock
65 } else if values["datetree"]?.bool == true {
66 guard let tree = CaptureTemplate.TreeType(rawValue: values["tree-type"]?.string ?? "day") else {
67 problems.append("capture.toml line \(table.line): tree-type is day, week or month")
68 continue
69 }
70 target = .datetree(file: file, path: olp ?? [], tree: tree)
71 } else if let headline = values["headline"]?.string {
72 target = .headline(file: file, headline: headline)
73 } else if let olp {
74 target = .outline(file: file, path: olp)
75 } else {
76 target = .file(file)
77 }
78 func flag(_ name: String) -> Bool { values[name]?.bool ?? false }
79 func lines(_ name: String) -> Int? { values[name]?.integer }
80 let options = CaptureTemplate.Options(
81 prepend: flag("prepend"), immediateFinish: flag("immediate-finish"), emptyLines: lines("empty-lines"),
82 emptyLinesBefore: lines("empty-lines-before"), emptyLinesAfter: lines("empty-lines-after"),
83 jumpToCaptured: flag("jump-to-captured"), clockIn: flag("clock-in"), clockKeep: flag("clock-keep"), clockResume: flag("clock-resume"),
84 tableLinePos: values["table-line-pos"]?.string
85 )
86 templates.append(CaptureTemplate(key: key, name: values["name"]?.string ?? key, kind: kind, target: target, template: body, options: options))
87 }
88 return (templates.isEmpty ? defaults : templates, problems)
89 }
90}
91
92extension DocumentSession {
93 /// Places captured `text` with `template`: through the buffer when the target is open,
94 /// otherwise in the file, created if missing, through the save path. `id` and `clock`
95 /// targets must be resolved first (`file` names the ID's file). Returns the file and where
96 /// the entry starts.
97 public func capture(_ text: String, template: CaptureTemplate, root: String?, file: String? = nil, now: Date = Date()) -> Result<(path: String, offset: Int), CaptureError> {
98 let path = file ?? Self.resolve(template.target.file, root: root)
99 if !isOpen(path), !FileManager.default.fileExists(atPath: path) {
100 do {
101 try FileManager.default.createDirectory(at: URL(fileURLWithPath: path).deletingLastPathComponent(), withIntermediateDirectories: true)
102 try Data().write(to: URL(fileURLWithPath: path))
103 } catch {
104 return .failure(CaptureError(message: "Can't create \(path): \(error.localizedDescription)"))
105 }
106 }
107 switch perform(CapturePlacement(text: text, template: template), path: path, at: 0, expect: nil, now: now) {
108 case .commit(let result): return .success((path, result.selection?.first?.lowerBound ?? 0))
109 case .failed(let message): return .failure(CaptureError(message: message))
110 default: return .failure(CaptureError(message: "Can't capture there."))
111 }
112 }
113
114 /// A template's file: absolute, `~/…`, or relative to `root`.
115 public static func resolve(_ file: String, root: String?) -> String {
116 if file.hasPrefix("/") { return file }
117 if file.hasPrefix("~") { return (file as NSString).expandingTildeInPath }
118 return ((root ?? NSHomeDirectory()) as NSString).appendingPathComponent(file)
119 }
120
121 /// `%a`: a link to the heading at the caret, as `org-store-link` makes one.
122 public func captureAnnotation() -> String {
123 guard let path, self.document != nil else { return "" }
124 let abbreviated = path.hasPrefix(NSHomeDirectory()) ? "~" + path.dropFirst(NSHomeDirectory().count) : Substring(path)
125 guard let entry = outline.last(where: { $0.start <= caret }) else { return "[[file:\(abbreviated)]]" }
126 return "[[file:\(abbreviated)::*\(entry.title)][\(entry.title)]]"
127 }
128}
129
130public struct CaptureError: Error, Equatable {
131 public let message: String
132 public init(message: String) { self.message = message }
133}
134
135/// The edit `Capture.place` makes, as a command so the save path applies it. The selection
136/// it leaves is the captured entry's start.
137struct CapturePlacement: OrgCommand {
138 let text: String
139 let template: CaptureTemplate
140 var id: String { "internal.capture" }
141 var title: String { "Capture" }
142 func applies(in context: EditContext) -> Bool { true }
143 func run(in context: EditContext) -> CommandStep {
144 switch Capture.placement(text, template: template, in: context.text, settings: context.tree.settings, now: context.now, calendar: context.calendar) {
145 case .failure(.message(let message)):
146 return .failed(message)
147 case .success(let placed):
148 return .commit(EditResult(baseRevision: context.revision, edits: TextEdit.between(context.text, placed.text), selection: [placed.start..<placed.start]))
149 }
150 }
151}
152
153extension DocumentSession {
154 /// Shortcuts' "Capture to Orgstar": `text` as `%i` in the template keyed `key` (the first
155 /// when nil or empty), its prompts taking their defaults, filed without the capture window.
156 /// The template used.
157 public func capture(
158 _ text: String, templateKey key: String?, templates: [CaptureTemplate], workspace: WorkspaceModel, clock: ClockModel,
159 clipboard: String, userName: String
160 ) -> Result<CaptureTemplate, CaptureError> {
161 let key = key.flatMap { $0.isEmpty ? nil : $0 }
162 guard let chosen = key.map({ key in templates.first { $0.key == key } }) ?? templates.first else {
163 return .failure(CaptureError(message: "No capture template \"\(key ?? "")\""))
164 }
165 let context = CaptureContext(initial: text, clipboard: clipboard, userName: userName, allTags: (try? workspace.index.tags()) ?? [])
166 let answers = Capture.questions(chosen.template, context: context).map { _ in "" }
167 guard case .success(let filled) = Capture.fill(chosen.template, context: context, answers: answers) else {
168 return .failure(CaptureError(message: "Can't fill template \"\(chosen.key)\""))
169 }
170 return chosen.resolved(workspace: workspace, session: self, clock: clock).flatMap { resolved in
171 capture(filled.text, template: resolved.template, root: workspace.rootPaths.first, file: resolved.file)
172 }.map { _ in chosen }
173 }
174}
175
176extension CaptureTemplate {
177 /// `id` and `clock` targets as a file and a heading.
178 @MainActor
179 public func resolved(
180 workspace: WorkspaceModel, session: DocumentSession, clock: ClockModel
181 ) -> Result<(template: CaptureTemplate, file: String?), CaptureError> {
182 switch target {
183 case .id(let id):
184 guard let location = try? workspace.index.headings(withID: id).first else {
185 return .failure(CaptureError(message: "Cannot find target ID \"\(id)\""))
186 }
187 return .success((self, location.path))
188 case .clock:
189 guard let entry = clock.entry(session) else { return .failure(CaptureError(message: "No running clock")) }
190 return .success((retargeted(.heading(file: entry.path, offset: entry.offset)), entry.path))
191 default:
192 return .success((self, nil))
193 }
194 }
195}