Files
VCCPlusOSS/platforms/macos/App/BASICReference.swift
T

127 lines
5.1 KiB
Swift
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 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 {}