127 lines
5.1 KiB
Swift
127 lines
5.1 KiB
Swift
// SPDX-License-Identifier: GPL-3.0-or-later
|
||
import Foundation
|
||
|
||
/// The ROM family which supplies a command. Common includes CoCo 3 Super Extended BASIC.
|
||
enum BASICReferenceDialect: String, Codable, CaseIterable, Sendable {
|
||
case common, disk, rgbdos, sdcdos
|
||
|
||
var displayName: String {
|
||
switch self {
|
||
case .common: return "Common BASIC"
|
||
case .disk: return "Disk BASIC"
|
||
case .rgbdos: return "RGB-DOS"
|
||
case .sdcdos: return "SDC-DOS"
|
||
}
|
||
}
|
||
}
|
||
|
||
enum BASICReferenceWork: String, Codable, CaseIterable, Sendable {
|
||
case basicGuide, diskGuide, rgbdos, sdcGuide
|
||
|
||
var citation: String {
|
||
switch self {
|
||
case .basicGuide: return "Tandy Corporation. Tandy Color Computer 3 BASIC Quick Reference Guide. 1986."
|
||
case .diskGuide: return "Color Computer Disk BASIC Quick Reference Guide. InterTAN Canada Ltd., 1987."
|
||
case .rgbdos: return "Krupski, Roger, Joe Scinta, Greg Miller, and Colin J. Stearman. RGB-DOS. Ken-Ton Electronics."
|
||
case .sdcGuide: return "Lindner, tim, producer. CoCo SDC User Guide. Fourth version, February 2023. Based on Brian Blake’s original manual."
|
||
}
|
||
}
|
||
}
|
||
|
||
struct BASICReferenceEntry: Codable, Identifiable, Sendable {
|
||
let id: String
|
||
let keyword: String
|
||
let title: String
|
||
let category: String
|
||
let dialect: BASICReferenceDialect
|
||
let summary: String
|
||
let syntax: [String]
|
||
let parameters: [String]
|
||
/// A short command fragment, which may need setup or input. Not an executable test.
|
||
let sample: String
|
||
let exampleID: String?
|
||
let related: [String]
|
||
let notes: [String]
|
||
let source: BASICReferenceWork
|
||
let sourcePage: String?
|
||
|
||
var citation: String {
|
||
guard let location = sourcePage, !location.isEmpty else { return source.citation }
|
||
guard location.first?.isNumber == true else { return source.citation + " " + location + "." }
|
||
let plural = location.contains("-") || location.contains(",")
|
||
return source.citation + (plural ? " pp. " : " p. ") + location.replacingOccurrences(of: "-", with: "–") + "."
|
||
}
|
||
}
|
||
|
||
struct BASICReferenceExample: Codable, Identifiable, Sendable {
|
||
let id: String
|
||
let title: String
|
||
let summary: String
|
||
/// Complete, numbered source that is opened in the editor, never implicitly run.
|
||
let source: String
|
||
let expectedOutput: String
|
||
let dialect: BASICReferenceDialect
|
||
}
|
||
|
||
struct BASICReferenceCatalog: Codable, Sendable {
|
||
let entries: [BASICReferenceEntry]
|
||
let examples: [BASICReferenceExample]
|
||
|
||
enum CatalogError: LocalizedError {
|
||
case missingResource
|
||
case invalidContent(String)
|
||
|
||
var errorDescription: String? {
|
||
switch self {
|
||
case .missingResource:
|
||
return "The BASIC Quick Reference is missing from this app. Reinstall a complete copy of VCC Plus."
|
||
case .invalidContent(let detail):
|
||
return "The BASIC Quick Reference could not be read: \(detail)"
|
||
}
|
||
}
|
||
}
|
||
|
||
static func load(from url: URL) throws -> BASICReferenceCatalog {
|
||
let catalog = try JSONDecoder().decode(Self.self, from: Data(contentsOf: url))
|
||
try catalog.validate()
|
||
return catalog
|
||
}
|
||
|
||
/// Preserve failures so the reference window can explain a damaged installation.
|
||
static let bundled: Result<BASICReferenceCatalog, Error> = Result {
|
||
let bundles = [Bundle.main, Bundle(for: BASICReferenceBundleMarker.self)]
|
||
guard let url = bundles.compactMap({ $0.url(forResource: "BASICReference", withExtension: "json") }).first else {
|
||
throw CatalogError.missingResource
|
||
}
|
||
return try load(from: url)
|
||
}
|
||
|
||
private func validate() throws {
|
||
guard !entries.isEmpty else { throw CatalogError.invalidContent("there are no reference entries.") }
|
||
let entryIDs = Set(entries.map(\.id))
|
||
let exampleIDs = Set(examples.map(\.id))
|
||
guard entryIDs.count == entries.count, exampleIDs.count == examples.count else {
|
||
throw CatalogError.invalidContent("an entry or example identifier is duplicated.")
|
||
}
|
||
for entry in entries {
|
||
guard !entry.id.isEmpty, !entry.keyword.isEmpty, !entry.title.isEmpty,
|
||
!entry.category.isEmpty, !entry.summary.isEmpty, !entry.syntax.isEmpty,
|
||
!entry.syntax.contains(where: \.isEmpty) else {
|
||
throw CatalogError.invalidContent("entry \(entry.id) is incomplete.")
|
||
}
|
||
guard entry.related.allSatisfy(entryIDs.contains),
|
||
entry.exampleID.map(exampleIDs.contains) ?? true else {
|
||
throw CatalogError.invalidContent("entry \(entry.id) has an unresolved reference.")
|
||
}
|
||
}
|
||
for example in examples {
|
||
guard !example.id.isEmpty, !example.title.isEmpty, !example.summary.isEmpty,
|
||
!example.source.isEmpty, !example.expectedOutput.isEmpty else {
|
||
throw CatalogError.invalidContent("example \(example.id) is incomplete.")
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
private final class BASICReferenceBundleMarker: NSObject {}
|