// 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 = 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 {}